Metadata-Version: 2.4
Name: diff-dsl
Version: 0.1.0
Summary: DSL complementarity analysis library — compares wellmanifest.dsl/manifest/v1 manifests
Author-email: Tom Sapletta <tom@sapletta.com>
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# diff-dsl

DSL complementarity analysis library.

`diff-dsl` compares `wellmanifest.dsl/manifest/v1` manifests from multiple
repositories to detect overlaps, gaps, and pipeline composition opportunities.

## What it does

Given two or more `dsl-manifest.json` files, `diff-dsl` produces a structured
complementarity report across these dimensions:

| Dimension | Question answered |
|---|---|
| **Command overlap** | Do two DSLs declare the same command names? |
| **Domain overlap** | Do two DSLs serve the same domain? |
| **Effect model compatibility** | Can the output of one DSL feed into another? |
| **LLM boundary direction** | Who produces, who consumes LLM payloads? |
| **Schema cross-reference** | Does one DSL reference another's schemas? |
| **Declared mappings** | Do manifests declare `maps-to` / `compatible-with` edges? |
| **Adopt drift** | Do `x-adopts` local copies still cover the shared core? |
| **Pipeline position** | Where does each DSL sit in the source→extract→graph→validate→synthesize→execute chain? |
| **Projection overlap** | Do two DSLs share projection formats? |
| **Owned path conflicts** | Do two manifests claim the same paths? |

## Usage

```bash
# Compare all manifests in a directory
diff-dsl analyze --dir /home/tom/github/autogrammar/

# With explicit shared command schemas (adopt-drift checks)
diff-dsl analyze --dir /home/tom/github/autogrammar/ \
  --shared-schemas /home/tom/github/wellmanifest/dsl/schemas/commands

# Compare two specific manifests
diff-dsl compare a.json b.json

# Output as JSON
diff-dsl analyze --dir /home/tom/github/autogrammar/ --format json
```

When `--shared-schemas` is omitted, `diff-dsl` looks for
`WELLMANIFEST_DSL_COMMANDS` or a sibling `../wellmanifest/dsl/schemas/commands`.
Adopt drift exits with code `2` when incompatible divergence is found.

**Known non-adopted overlap:** shared `VALIDATE` is validate-path (`verb` +
`path`). `nlp2dsl` `VALIDATE` is validate-workflow and intentionally does not
`x-adopts` the shared schema — treat as separate contracts.

## Output

The report is a `diff-dsl.report/v1` JSON document:

```json
{
  "schemaVersion": "diff-dsl.report/v1",
  "manifests": ["autogrammar.todo2code.intent", "autogrammar.doql", ...],
  "pairs": [
    {
      "a": "autogrammar.todo2code.intent",
      "b": "autogrammar.doql",
      "commandOverlap": [],
      "domainOverlap": false,
      "effectModelCompatibility": "sequential",
      "llmDirection": "todo2code→doql",
      "schemaCrossRefs": [],
      "pipelinePosition": {"a": "extract+graph", "b": "generate"},
      "projectionOverlap": [],
      "pathConflicts": [],
      "complementarityScore": 0.75
    }
  ],
  "summary": {
    "totalPairs": 10,
    "complementary": 7,
    "overlapping": 1,
    "conflicting": 0,
    "orthogonal": 2
  }
}
```

## Pipeline position model

```
source → extract → graph/IR → validate → synthesize → generate → execute
```

Each DSL is mapped to one or more positions based on its `effectModel` and
declared commands:

| Position | Effect models | Typical commands |
|---|---|---|
| extract | descriptive, propose-only | ANALYZE, EXTRACT |
| graph | descriptive | LINK, DIFF |
| validate | declarative-policy | VALIDATE, ASSERT |
| synthesize | propose-only | GENERATE, QUERY |
| generate | declarative-policy | GENERATE, RENDER |
| execute | controlled-effects | PATCH, APPLY, RUN |
