[jgrodziski]

Fourth step of the word cloud / glossary (#6), milestone M19a in PLAN.md §20. Stacked on #28 (itself on #27 and #26): review those first; this PR's diff is the seven commits after #28.

It adds the codegraph vocabulary command over the artifact #28 builds, and the drift report against a list of business terms.

The command

codegraph vocabulary MODEL… [--level corpus|module|type | --scope ID] [--top N]
                            [--class domain|technical|keyword|short|all]
                            [--weights KEY=N,…] [--technical FILE] [--drift FILE]
                            [--out FILE] [--json] [--internal-only] [--declared-only] [--no-cache]

• No flag: the corpus's 40 heaviest domain words, each with its weight, occurrences, carriers, and how many modules and types say it.
• --level module|type: one block per module or type, the scopes with the most distinct words first (a rough cognitive-load ranking), 10 words per block by default.
• --scope ID: one module or type. An operation's id is counted on demand (operationScope), since the artifact stores no operations. An unknown id, a stub or a kind that is none of these is refused with a message saying what the id is and, for a field, which scope counts its words.
• --class, --top, --weights, --technical FILE choose what is shown and how it is counted. --weights type=0 re-weighs; an unknown role, a repeated key or a malformed entry is a usage error.
• --out FILE writes vocabulary.json and still prints the report.
• Every report opens with the models, the level or scope, the view, the weights and the technical list (size, sha256, and its file when given), since a count means nothing without them.

On the Java fixture:

  TERM      CLASS   WEIGHT  OCC  CARRIERS  MODULES  TYPES
  order     domain      40   12        12        3      4
  price     domain      18    6         6        1      6
  basket    domain      16    2         2        1      2

Drift

--drift FILE reads one business term per line (Price list, Invoice) and reports, at the chosen level:

• never said: terms whose words no scope says, each with the missing words;
• said: terms some scope says in full, with the scopes;
• code only: the code's domain words that no business term contains, by weight.

Words match exactly, with no stemming: lines does not match line. A term repeating an earlier term's words is merged; # lines and blank lines are skipped; a line with no word (2024) is warned about with its line number.

Decisions worth a look

• --drift exits 3 when a business term is said nowhere, like analyze --report cycles on a cycle, so CI can gate on the glossary.
• --out keeps the report on stdout. city and navigator replace stdout with the file instead.
• A flag the report would not read is a usage error rather than ignored: --level or --drift with --scope, --class with --drift.

Commits

• feat(vocabulary): drift against business terms: parseBusinessTerms and vocabularyDrift.
• feat(vocabulary): an operation's words on demand: operationScope, with the counting rule shared with the aggregator. A lambda counts with its operation, a local class does not, and a C# delegate is a type.
• feat(vocabulary): read a technical list from text: parseTechnicalWords, one word per line.
• refactor(cli): share the view label: moved out of analyze.
• feat(cli): codegraph vocabulary: the command, its option spec and the JSON report codegraph.vocabularyReport/1.
• Docs: docs/cli.md; website pages for the command and for vocabulary.json; the CLI, artifact and exit-code index pages; PLAN §20.

Tests

• Drift: a hand-counted toy at three levels, and properties over the Java and Ruby fixtures.
• Operation scope: toy cases, a property that an operation's rows never exceed its parent scope's, and the C# delegate.
• CLI: 29 command tests, the option parser, and the vocabulary command added to the determinism, exit-code, stream-purity and JSON-parity suites. Reading through the cached model.db gives the same output as reading the file on the Java, Ruby and Elixir fixtures.
• 21 mutations across drift, the operation scope and the command, one at a time: each caught.

Verification

• pnpm -r build and pnpm -r typecheck green; eslint clean on every changed file; pnpm run gen:schemas and the website profiles page leave no diff; the Hugo site builds and the new pages' links resolve.
• vocabulary 284 tests, core 544, cli 973; every other package passes except the Node 26 node:sqlite warning test noted on feat(core): language lexicons on profiles (M19a) #26.
• The single-executable bundle runs vocabulary on the fixtures.

Part of #6.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	codegraph	294e5cc	Commit Preview URL Branch Preview URL	Oct 26 2026, 09:00 AM