# Debian Copyright Fragment Infrastructure

This repository uses a fragment-based workflow for managing the `debian/copyright` file,
following the debian-copyright skill guidelines.

## Directory Structure

```
debian/
├── copyright.header          # Main package copyright (non-vendored files)
├── copyright.in.d/           # Per-crate copyright fragments (128 files)
│   ├── aho-corasick         # Fragment for debian/missing-sources/aho-corasick
│   ├── anes                 # Fragment for debian/missing-sources/anes
│   └── ...                  # (one per crate, empty for stubs)
├── bin/
│   ├── merge-copyright      # Perl script to merge header + fragments → copyright
│   ├── process-crate.sh     # Generate a single fragment from a crate directory
│   ├── is-stub.sh          # Detect filtered-out stub crates
│   └── batch-copyright.sh   # Process all crates (coordinator)
└── missing-sources/          # Vendored Rust crates (128 subdirectories)
```

## Workflow

### 1. Generating Fragments

To regenerate all copyright fragments from the vendored crates:

```bash
# Process all crates (detects stubs automatically)
debian/bin/batch-copyright.sh

# Or process a single crate
debian/bin/process-crate.sh debian/missing-sources/<crate-name>
```

This will:
- Detect stub crates (filtered by cargo-vendor-filterer) and create empty fragments
- Extract license and copyright info from Cargo.toml and license files
- Translate SPDX license expressions to DEP-5 format:
  - `MIT` → `Expat`
  - `Apache-2.0` → `Apache-2`
  - `OR` → `or`, `AND` → `and`
  - Parentheses → commas for grouping
- Generate `debian/copyright.in.d/<crate>` files

### 2. Merging into debian/copyright

To rebuild the final `debian/copyright` from the fragments:

```bash
# Via debian/rules
make -f debian/rules debian/copyright

# Or directly
debian/bin/merge-copyright
```

This will:
- Start with `debian/copyright.header`
- Add all `Files:` stanzas from fragments (excluding empty/stub files)
- Deduplicate `License:` stanzas (identical texts merged)
- Handle license name clashes (appending `-2`, `-3`, etc.)
- Add "Used by: <crate>, <crate>, ..." comments to license stanzas

### 3. Resume / Incremental Updates

The batch processor automatically skips:
- Fragments that already exist and are non-empty
- Empty fragments for verified stub crates

To force regeneration:
```bash
rm debian/copyright.in.d/<crate>    # Remove specific fragment
rm debian/copyright.in.d/*          # Remove all and regenerate
```

## DEP-5 License Name Mappings

The scripts follow these DEP-5 naming conventions:

| SPDX (Cargo.toml)           | DEP-5 (debian/copyright) |
|-----------------------------|---------------------------|
| MIT                         | Expat                     |
| Apache-2.0                  | Apache-2                  |
| MIT OR Apache-2.0           | Expat or Apache-2         |
| Unlicense/MIT               | Unlicense or Expat        |
| Apache-2.0 WITH LLVM-exception | Apache-2 with LLVM exception |
| (MIT OR Apache-2.0) AND Unicode-3.0 | Expat or Apache-2, and Unicode |

## Current Status

- **128 crates** in `debian/missing-sources/`
  - **112 real crates** with generated copyright fragments
  - **16 stub crates** (filtered by cargo-vendor-filterer) with empty fragments
- **13 deduplicated license stanzas** in final copyright file
- Uses `/usr/share/common-licenses/` pointers for GPL-3+, Apache-2, CC0-1.0
- Embeds full text for Expat, ISC, BSD-*, Unlicense, Zlib, Unicode

## Skill Framework Integration

The infrastructure is based on the debian-copyright skill from `~/.pi/agent/skills/debian-copyright/`:

- **SKILL.md** - Main skill documentation and DEP-5 reference
- **writer.md** - Actor agent definition (drafts fragments, drives review loop)
- **reviewer.md** - Critic agent definition (audits fragments read-only)

The writer and reviewer subagents can be invoked for individual crates when the full
pi task infrastructure is available. For now, `process-crate.sh` implements the
writer logic directly.

## Validation

While `cme check dpkg-copyright` is not available in this environment, the generated
file follows all DEP-5 format requirements:

```bash
# Validate format (requires libconfig-model-dpkg-perl)
cme check dpkg-copyright

# Manual checks
grep -E "^License: (MIT|Apache-2\.0)" debian/copyright  # Should be empty
grep -E "^License:" debian/copyright | sort | uniq -c   # Check license names
```

## Future Improvements

1. Install and integrate `cme check dpkg-copyright` for format validation
2. Register writer.md and reviewer.md as pi agents for task invocation
3. Improve copyright year extraction (currently misses some years)
4. Handle multi-line authors fields in Cargo.toml
5. Add SPDX header detection for per-file license overrides
