@danielsimonjr/repo-tools 1.1.0 → 2.1.0

package/CHANGELOG.md

@@ -6,6 +6,328 @@ All notable changes to this project are recorded in this file. The format follow
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-10-01
+
+`repo-tools check` is the new drift gate for the Markdown documents of a repository. It ports
+`check.py` of the architecture-docs skill. The release also makes a literal `import()` a graph
+edge, removes the 1.x depgraph pipeline, and adds an accept-list to the privacy check.
+`docs/parity-check.md` lists the differences from the Python tool.
+
+### Added
+
+- `repo-tools check --docs=<dir>`, the drift gate of the architecture documents. The command is
+  a port of `check.py` of the architecture-docs skill. The check reads the `## Verification`
+  tables of the Markdown files in the folder. The check builds a fresh graph, and the check
+  compares each claim with the graph. Exit 0 means that every claim matched. Exit 1 lists every
+  problem on standard error, one per line. A missing or empty docs folder is a problem. A
+  document without a Verification section is a problem. So are a section without a row, an
+  unknown claim, a count that the graph build declared unreliable, and a value that differs. A
+  document opts out when one of its lines is exactly `<!-- repo-map:no-verification -->`. A relative `--docs` path is
+  relative to the root, and an absolute path is used as given. The check reads
+  `map.duplicateAllowlist` and `map.verificationMarker` from the config file. Section 15 of
+  `docs/design.md` lists the differences from the Python tool. The smoke test has a `check` step.
+  `docs/parity-check.md` records the comparison with the Python tool on 11 repositories.
+- The privacy check has an accept-list, `scripts/privacy-accepted.txt`, for a reviewed finding in
+  the commit history. A commit message cannot change after a merge, so a new commit cannot clear
+  a finding in it. An entry holds a full commit sha, one finding kind, one line of the message and
+  a reason. The entry accepts that finding only: no prefix, no wildcard, no whole-commit waiver,
+  and never a finding in a tracked file. An entry that accepts no finding is a finding
+  (`accepted-stale`). The check prints each accepted finding with its reason.
+
+### Changed
+
+- A literal relative `import()` is an edge of the core graph. This reverses the known difference
+  in 2.0.0. A runtime call is a namespace use (`*`). A type-position `import('./c').Name` records
+  that name. `typeof import()` records no names. A template that contains `${`, and a specifier
+  that is not relative, are not edges. The parity record gives the merge rules. The verdict
+  against the Python tool is `repo_map-wrong`.
+- A namespace import (`import * as ns`, `export * as ns`) counts every export of its target as
+  used, as a runtime `import()` does. The Python tool lists those exports as unused. A name that
+  a file mentions only in a comment is not an in-module reference. The Python tool counts the
+  comment. The parity record gives the measured effect. A test locks the namespace rule.
+- The opt-out marker of `repo-tools check` must stand alone on a line. `check.py` opts a document
+  out when the marker is anywhere in its text. A document can quote the marker in a sentence, a
+  code span or a table cell. That document then skips its own table, and a stale claim passes in
+  silence.
+  `repo-tools check` opts out only when a line, trimmed, equals the marker. This changes the
+  result for a document that opted out from inside a sentence or a table cell: the check now
+  reads its claims. `repo-tools map` writes the marker alone on a line, so generated reports
+  still opt out. A blank `map.verificationMarker` matches no line. `docs/parity-check.md` records
+  the difference. The verdict is fail-closed.
+- A bodiless `export function f(): T;` is not an export, as in the Python tool
+  (`repo_map-kept`). An overload plus an implementation records the name once.
+- The 1.x depgraph pipeline is removed: the runner, the regex parser, the scanner, the inventory
+  reporter and the 1.x goldens. `repo-tools depgraph` stays an alias of `repo-tools map`.
+  `docs/fix-ledger-2.0.0.md` records which 1.x fixes the `map` tests lock, and which fixes have
+  no 2.0.0 meaning.
+
+### Fixed
+
+- `src/check/claims.ts` and one test held the byte-order mark as an invisible U+FEFF character.
+  Both files now spell it as an escape sequence. A new test fails when a file under `src/`,
+  `tests/` or `scripts/` holds a literal U+FEFF.
+- A named `export { name } from` writes one edge for that statement. The statement does not add a
+  second empty-imports edge to the same file.
+- `write` refuses a symbolic link inside the output folder that points outside it.
+- A skip-list folder under `src/` (`dist`, `build`, `coverage`, `node_modules`, `.git`) that
+  holds a source file produces a warning. The files stay out of the census. A root `build/` or
+  `dist/` folder stays silent.
+- `--check-census` names the configured regenerate command. The test-coverage note names the
+  configured coverage-policy path.
+- The config file accepts a top-level `$schema` key.
+- The walk skip list is not module state. Each walk builds its own skip set.
+- A type-position `import('./c').C` records the name `C`.
+- In single-package mode, `main` and `exports` targets are roots after `dist/` maps to `src/`,
+  including when the file is not `src/index.ts`. A subpath root is the source of the export
+  target.
+- Test coverage follows an import by package name, including the side-effect imports of the
+  resolved file.
+- A workspace subpath uses the `exports` target, then `<sub>.ts`, then `<sub>/index.ts`.
+- A package-name import is an edge in cycle detection, including the cyclic components in
+  `dependency-layers.json`.
+- The comment mask treats `a++ / b / c` as division, and `if (x) /re/` as a regular expression.
+- A bare `import './x'` together with `import('./x')` is one side-effect edge whose names are
+  `["*"]`.
+- A dangling symbolic link is listed in `skippedLinks`.
+- A `new URL` in a root config, and a `new URL('./x.js', import.meta.url)` launch, seed roots.
+- A `.test.tsx` or `.spec.tsx` file is in the `tests` area.
+- The repository scan of the privacy check passes again. A test fixture used an e-mail address
+  that the check rejects. Two trailers of the merge commit of the engine change hold a co-author
+  address and a name. The fixture now uses an allowed address. The accept-list records the two
+  trailers.
+
+## [2.0.0] - 2026-09-26
+
+The unified engine. `repo-tools map` replaces the Python `repo_map.py` and depgraph 1.x with one
+engine for TypeScript/JavaScript, Python, C# and Rust. On 11 public repositories, its four core
+files are identical to the Python tool, apart from the deliberate differences that the parity
+record lists. `repo-tools depgraph` stays as a deprecated alias through 2.x. The 1.x scan-scope
+flags have no effect: `map` exits 1 on them, and the alias gives a warning.
+
+### Known differences
+
+- The 2.0.0 release made no graph edge for a dynamic `import()`. That choice is reversed in
+  Unreleased: a literal relative `import()` is now an edge. On memoryjs, the release counted
+  one type-only cyclic component as 3 files, not 7. Test coverage counted a literal `import()`
+  in a test file as a load, and it still does.
+
+### Added
+
+- `repo-tools map` (design decision D8): the command of the 2.0.0 engine. It writes each report
+  of the engine into the output folder, for TypeScript/JavaScript, Python, C# and Rust.
+  `repo-tools depgraph` is now its deprecated alias through 2.x, and prints one deprecation line.
+  The 1.x scan-scope flags (`--src`, `--tests`, `--exclude`, `--also-exclude`, `--all`/`-a`,
+  `--reachable-only`, `--include-tests`/`-t`) have no effect in 2.0.0. `map` exits 1 on them,
+  and the alias gives a warning and continues. The config section `map` is the new name of
+  `depgraph`, and a file with both sections exits 1.
+- `map` (design decision D9): the duplicate allowlist and baseline and the coverage policy
+  default to `docs/architecture/`, never to the output folder. A root-relative `--out=../x`
+  writes outside the root.
+- `map` gates: `--strict-orphans`, `--strict-census`, `--check-census`, `--check-duplicates`,
+  `--no-regen` and `--write-duplicate-baseline`, and the `preflight` and `report` hooks of the
+  extensions. `--strict-census` compares the census with a walk of the root. It finds a source
+  file on disk that git does not track. The duplicate gate works for TypeScript only, and says
+  so for another language. The `report` hook receives the core `dependency-graph.json`.
+- `map --api-surface` (design decision D5): TypeScript keeps the 1.x report, and the
+  mini-repo report is byte-identical to the 1.x golden. Python and Rust list the surface names
+  of the entry file. C# exits 1 with the reason.
+- Goldens for `map` (`tests/golden/map`, written by `scripts/update-map-goldens.ts`). The smoke
+  test (design 13.3) runs `map`.
+- README and `docs/design.md` describe the 2.0.0 engine. The README gives `map`, the
+  `depgraph` alias, the report list of `map` and new query examples from the mono-repo fixture.
+  `docs/design.md` has a new section 14, "The 2.0.0 engine". Both documents in `docs/` start
+  with the `repo-map:no-verification` marker and give the reason: neither one makes a claim
+  about the graph of this repository.
+- `docs/parity-2.0.0.md`: the parity record of the 2.0.0 engine on public repositories. On side
+  1, the four core files are identical to the Python tool on 11 repositories, apart from the
+  two deliberate workspace differences on Mathts. A control shows that these two differences
+  cause all of the Mathts differences. Side 2 compares each extra with depgraph 1.x on
+  memoryjs, Mathts and universal-physics-tensor, and gives a verdict for each difference.
+- `repo-tools query` reads the core graph of `map` (design decision D8), and refuses a 1.x graph.
+  `dependents`, `symbol-users` and `cycles` have the meaning of the Python tool. They read each
+  area of the graph, and a path that is not a file of the graph exits 1. `symbol-users` lists
+  files. `cycles` lists the simple cycles, and `cycles --components` lists the runtime and
+  type-only components. `is-public` reads `package-export-surfaces.json` only when it runs. The
+  browser-safety commands serve TypeScript/JavaScript only, and exit 1 with the reason for
+  another language. They now follow the workspace imports too, so they find a `node:` file
+  that another package reaches through an import of its package name.
+
+- 2.0.0 engine, step 1: `src/map/discovery.ts` ports `repo_map/discovery.py` from the
+  architecture-docs skill. It holds the language detection, the file census and the area and
+  disposition rules. It refuses a repository in an unsupported language. The census comes from
+  `git ls-files`, or from a pruned walk. The 30 tests of its four test files are ported. Four
+  repositories give the same result in the port and in the Python tool: memoryjs, Mathts,
+  universal-physics-tensor and repo-tools. For all 3,717 files, the language, path, area,
+  disposition and line count agree. The file order is code-unit order on every operating system.
+- 2.0.0 engine, step 2: the TypeScript reader (`src/map/parsing.ts`) and the lazy grammar loader
+  (`src/map/grammars.ts`), on tree-sitter-typescript 0.23.2. The 18 tests of `test_parsing.py` are
+  ported; a synthetic barrel file replaces the source test's absolute path. On 3,719 files of four
+  repositories, the port gives the same imports, exports, kinds and default export as the Python
+  reader, file by file.
+- 2.0.0 engine, step 3: the C# and Rust readers (`parseCs`, `parseRs`), regex readers ported
+  with their exact behavior. Python's line-start anchor and `.` get exact translations. The 22
+  reader tests of `test_parsing_csharp.py` and `test_rust.py` are ported.
+- 2.0.0 engine, step 4: the Python reader (`parsePy`) on tree-sitter-python 0.25.0, in place of
+  CPython's `ast`. The import order is the order of `ast.walk` (ast depth, then source position).
+  A module that does not parse raises `SyntaxError`. The 9 tests of `test_parsing_python.py` are
+  ported; 8 new tests pin the import order and the export forms against CPython's output. The
+  Python, C# and Rust readers match the Python tool file by file on 726 files. The files come
+  from 7 public repositories: PITS-MRAS, auto-memory, fermat-mcp and memvid (Python), IronClaw
+  (Rust), ui-mcp and Windows-mcp (C#).
+- 2.0.0 engine, step 5: the resolvers (`src/map/resolvers.ts`) for TypeScript, Python, C# and
+  Rust, with Python's `posixpath` rules in `src/py.ts`. The Python standard-library list is the
+  `sys.stdlib_module_names` of CPython 3.13.15, as generated data. The 35 resolver tests of four
+  test files are ported.
+- Tests: `tests/unit/node-compat.test.ts` also fails when `src/` uses the `Bun` global or a
+  `bun:` module, because `npx` runs the Node bundle. It found `Bun.spawnSync` in the map
+  discovery; the git file list now comes from `node:child_process`.
+- 2.0.0 engine, step 6: the graph (`src/map/graph.ts`) and its schema (`src/map/schema.ts`).
+  It holds the classify-before-resolve buckets, barrel expansion, entry-point roots for four
+  languages, thin launchers, reachability and simple-cycle enumeration. The 29 tests of
+  `test_schema.py` and `test_graph.py` are ported. On 11 repositories and 4,456 files, the port
+  and the Python tool give the same dispositions, ordered edges, buckets, roots and warnings.
+  The empty-repo warning names the root, not its absolute path (output rule R4).
+  `pyproject.toml` is read with `smol-toml` 1.9.0, bundled and pinned.
+- 2.0.0 engine: the end-to-end graph tests of C#, Python and Rust are ported (18 tests, from
+  `test_graph_csharp.py`, `test_python_repo_end_to_end.py` and `test_rust.py`).
+- 2.0.0 engine, step 7: the four core artifacts (`src/map/artifacts.ts`). They are
+  `dependency-graph.json`, `file-inventory.json`, `duplicate-symbols.json` and
+  `unused-analysis.json`, with 27 ported tests. On 11 repositories, all 44 files are
+  byte-identical to the Python tool after the approved changes. The port writes LF line ends and
+  schema version 2.0.0, with no `generated` field. Warnings name no absolute root path. Paths
+  sort by code unit, and the Python tool sorts them in the Windows case-insensitive order.
+- 2.0.0 engine: the artifact tests of C# and Rust are ported (16 tests, from
+  `test_csharp_repo_end_to_end.py`, `test_unused_csharp.py` and `test_rust_unused_caveat.py`).
+  The source tests that read a local repository are not ported. The side-1 parity run covers
+  that repository.
+- 2.0.0 engine: the read-only queries (`src/map/query.ts`, from `repo_map/query.py`):
+  `loadGraph`, `dependents`, `symbolUsers` and `cycles`, with 23 ported tests. The query module
+  reads only the graph JSON. A test scans its imports and fails if a reader, resolver, grammar or
+  graph module is reachable. A 1.x graph is refused, because its major version is not 2.
+- 2.0.0 engine: the simple-cycle enumeration moves to `src/map/cycles.ts`. The graph and the
+  queries share it. The Python tool keeps two copies of this algorithm. On 10 repositories, the
+  artifacts are byte-identical before and after the move.
+- 2.0.0 engine (design decision D2): `dependency-graph.json` statistics also count the cyclic
+  components. The new keys are `runtimeCyclicComponents`, `typeOnlyCyclicComponents`,
+  `runtimeFilesInCycles` and `typeOnlyFilesInCycles`, after `circularDepsTruncated`. A cap never
+  truncates these counts. The Tarjan search moves from `src/depgraph/cycles.ts` to
+  `src/map/cycles.ts`, so depgraph and the core graph count components in the same way.
+- 2.0.0 engine (design decision D2): for a TypeScript repo, the statistics also give the
+  per-kind export counts of depgraph. The keys are `totalClasses`, `totalInterfaces`,
+  `totalFunctions`, `totalTypeGuards`, `totalEnums`, `totalConstants` and `totalReExports`. The
+  core reader gives the kinds, so the counts come from one parser. On memoryjs, each file has
+  the same names of each kind as in depgraph 1.x. The totals differ for two reasons. The core
+  counts every area, and depgraph counts the `src` files only. Also, depgraph counts an
+  overloaded or merged name one time for each declaration.
+- 2.0.0 engine (design decisions D3 and D5): `src/map/adapter.ts` changes the `src` files of the
+  graph into depgraph's parsed-file records. Then depgraph's analyzers run on the one graph for
+  each language. Each edge carries its resolved target. The new helper `targetOf` uses that
+  target, and a 1.x parse still resolves the specifier. The graph now also keeps each file's
+  export kinds, re-exports and re-export edges. The graph JSON does not write them. The records
+  have no workspace edges and no package name. The graph does not keep these facts.
+- 2.0.0 engine (design decision D3): `src/map/layers.ts` writes `dependency-layers.json`, which
+  is depgraph's subsystem view built on the graph. The file holds `metadata`, `entryPoints`,
+  `modules`, `cyclicComponents` and `layers`. `modules`, `entryPoints` and `layers` hold the
+  `src` files, as in depgraph 1.x. `cyclicComponents` holds every area, so its counts agree with
+  the core statistics. The adapter now also gives each edge its written specifier, and the
+  names of each package or built-in import. On memoryjs, the modules, files, entry points and
+  layers are identical to depgraph 1.x, and each field difference has a recorded cause.
+  `generateJSON` gets three helpers (`modulesJsonOf`, `layersOf`, `entryPointsOf`), and its
+  output does not change.
+- 2.0.0 engine (design decisions D3 and D5): `src/map/reports.ts` writes `DEPENDENCY_GRAPH.md`,
+  `dependency-graph.yaml` and `dependency-summary.compact.json` for each language. The
+  Markdown and the compact summary show the subsystem view with the core statistics. The YAML
+  is a copy of the core `dependency-graph.json` in YAML. The Markdown banner names
+  `repo-tools map`, and its table uses language-neutral labels. A language with no kind counts
+  gets no kind rows. In depgraph, `generateMarkdown` gets an optional `summaryRows` parameter.
+  Its cycle section counts the files of the listed components. The per-kind export counts of
+  `Statistics` are optional. After these changes, depgraph 1.x writes all 12 reports on
+  memoryjs byte-identical to a run before them.
+- 2.0.0 engine (design decision D4): `file-inventory.json` also gives depgraph's `byPackage`
+  and `skippedLinks`, the links that discovery does not follow. A walk does not follow a folder
+  link. In a git work tree, discovery does not follow a tracked link (mode 120000) to a folder
+  or to a missing file. The new `gitTrackedLinks` reads the modes with `git ls-files --stage`. The
+  git branch has a test that makes a folder link when the host permits it. The other core
+  files of 10 repositories stay byte-identical.
+- 2.0.0 engine (design decision D4): for a TypeScript repo, `duplicate-symbols.json` also
+  holds depgraph's classified lists: `runtime`, `types`, `classificationNote` and the four
+  summary counts. The allowlist is `<root>/docs/architecture/duplicate-allowlist.json`,
+  never a file in the output folder (D9). A declaration file (`.d.ts`) is no definer in the
+  classified lists, because it has no body. Another language gets an explicit
+  `classificationNote` and no classified lists. The adapter now gives each file its workspace
+  package, as depgraph 1.x does. On memoryjs, MathTS and universal-physics-tensor, each
+  classified entry is identical to depgraph 1.x. The one exception is a 1.x definer that is a
+  declaration file.
+- 2.0.0 engine (design decisions D4 and D5): `src/map/markdown.ts` writes `FILE_INVENTORY.md`,
+  `duplicate-symbols.md` and `unused-analysis.md` for each language. Each report reads the
+  JSON files in the output folder. A TypeScript duplicate report keeps the depgraph renderer.
+  Another language gets the name-only list and the explicit note. The inventory and unused
+  reports have new text, because the 1.x text described a census of TypeScript files only. The
+  unused report also lists the dormant files of the core reachability.
+- 2.0.0 engine (design decision D5): `src/map/coverage.ts` writes `TEST_COVERAGE.md` and
+  `test-coverage.json` for each language, with depgraph's analyzer. The name of a file decides
+  if it is a test. For TypeScript and JavaScript, the name is `*.test.*` or `*.spec.*`, as in
+  1.x. For Python, the name is `test_*.py` or `*_test.py`. For C# and Rust, each file in the
+  tests area is a test. A test also covers a file that it loads with a literal `import()`, or
+  through a relative `dist/` path. The core graph has no edge for these loads. The coverage
+  policy is `<root>/docs/architecture/coverage-policy.json` (D9). The reader records the bare
+  side-effect imports and the literal `import()` specifiers of TypeScript. The graph JSON does
+  not write them. On memoryjs, MathTS and universal-physics-tensor, the tested files are the
+  same as in depgraph 1.x.
+- 2.0.0 engine (design decision D5): `src/map/surfaces.ts` writes
+  `package-export-surfaces.json` for TypeScript with depgraph's public-surface rules. Fix: a
+  bare `export *` edge now keeps a `star` flag, and the adapter shows it as `*`, as 1.x does.
+  Before the fix, barrel expansion replaced the `*` with names. Then a name deep in an
+  `export *` chain was not public, which a test found. The layers module entries show star
+  edges as 1.x does. On memoryjs the surfaces are identical to 1.x. On MathTS and
+  universal-physics-tensor, each difference has a recorded cause.
+- 2.0.0 engine (design decision D5): `package-export-surfaces.json` for Python and Rust, with a
+  `note` that gives the rule. A Python package lists its `__all__`, else the public names that
+  its `__init__.py` defines. A Rust library crate root (`lib.rs`) lists its `pub` items and the
+  names of its plain `pub use` statements. The new `pubUseNames` reads an alias only as the
+  whole word `as`, so a name such as `HashMap` keeps its letters. For C#, no file is written,
+  because C# has no rule for a public surface of a package.
+- Dependencies (bundled, not installed by users): `web-tree-sitter` 0.27.0,
+  `tree-sitter-typescript` 0.23.2 and `tree-sitter-python` 0.25.0, pinned. The engine parses with
+  them in a later step. `src/ste/py.ts` moves to `src/py.ts`, because the engine also uses it.
+
+### Fixed
+
+- `map`: the Rust `use` reader kept the error of the Python tool. The Python tool removes the white
+  space of a `use` path, then cuts the path at the letters `as`. So `HashMap` gave `H`, `wasm`
+  gave `w` and `task` gave `t`, and a cut path could resolve to the wrong module. The reader now
+  removes only an alias that is the whole word `as` and a name. On IronClaw, 139 names are
+  complete again. The internal edges of 14 files go to the correct modules, and the simple
+  runtime cycle count goes from 1667 to 1009. The fix is a deliberate difference from the
+  Python tool.
+- Tests: the build test that runs `map` from the Node bundle writes `{"type": "module"}` next to
+  the bundle, as in the installed package. Without it, Node reads the nearest `package.json`
+  above the temporary folder. A stray one with no `type` makes Node write a warning to standard
+  error, and the test failed on such a machine.
+- The code-docs gate passes (399 of 399 exported symbols have a doc comment). Seven exported
+  types had no doc comment. The doc comment of `resolvePath` was apart from its function,
+  because `targetOf` was in the space between them. `src/map/graph.ts` and `src/ste/index.ts`
+  wrote the type `import("node:fs").Dirent` in the code, which the tree-sitter TypeScript
+  grammar cannot parse. They now import the type `Dirent`.
+- `map`: a workspace monorepo now has entry roots. The Python tool reads the root `package.json`
+  only, so each workspace source file showed as an orphan. The engine now also reads the
+  `package.json` of each workspace package, then the extra entries of depgraph, then a
+  `src/index.*` file. The workspace roots are a deliberate difference from the Python tool. On
+  MathTS, the roots go from 0 to 1167, and each disposition equals depgraph 1.x.
+- Build (design decision D7): `scripts/build.ts` now writes the three tree-sitter `.wasm` assets
+  next to `dist/cli.js`, under the names that the bundle refers to. Before this fix, the build
+  kept the JavaScript output only, so the Node bundle had no grammar files. `package.json`
+  `files` adds `dist/*.wasm`, and `npm pack --dry-run` lists the three files. The smoke test
+  passes 8 of 8 steps on the Windows executable, and on `dist/cli.js` with Bun, Node 20, Node
+  22 and Node 24. A bundle with no `.wasm` file fails the smoke test. The engine has three
+  `.wasm` files, not four, because it reads `.tsx` with the TypeScript grammar.
+- `map`: an import of a workspace package by name is now an edge to its entry file. In a single
+  package, an import of its own name is an edge too (1.x fix F43). The Python tool keeps each
+  such import as an external package, so a monorepo had no edges between its packages. The
+  import stays external when the census does not hold the entry file. The adapter lists these
+  edges as workspace edges, as depgraph 1.x does. On MathTS, 485 exports that other packages
+  use are no longer counted as unused.
+
 ## [1.1.0] - 2026-09-25
 
 The STE release. `repo-tools ste` checks Markdown, and docstring prose with `--prose`, against the

package/README.md

@@ -1,20 +1,26 @@
 # repo-tools
 
-`repo-tools` is one command-line tool with five subcommands for repositories:
+`repo-tools` is one command-line tool with these subcommands for repositories:
 
 | Subcommand | Job |
 |---|---|
-| `depgraph` | Writes the dependency graph and the architecture reports of a TypeScript tree. |
+| `map` | Writes the dependency graph and the architecture reports of a TypeScript/JavaScript, Python, C# or Rust repository. |
+| `depgraph` | The deprecated alias of `map` (through 2.x). |
+| `check` | Checks the `## Verification` tables of Markdown documents against a fresh graph, and fails on drift. |
 | `chunk` | Splits a large file into chunks, merges the chunks back, and shows which chunks changed. |
 | `compress` | Writes a compact copy of a file for a model context, and restores it. |
-| `query` | Answers structural questions from the depgraph reports, and writes two derived reports. |
+| `query` | Answers structural questions from the graph of `map`, and writes two derived reports. |
 | `ste` | Checks Markdown or docstring prose against Simplified Technical English. |
 
-Status: version 1.1.0.
+Status: version 2.1.0.
 
-- All five subcommands work.
-- `depgraph` and `query` read their settings from `repo-tools.config.json` in the root.
-  `--config=<file>` makes either subcommand read another file.
+- `map`, `check` and `query` read their settings from `repo-tools.config.json` in the root. The
+  section of `map` is `map` (its old name, `depgraph`, is also read). `--config=<file>` makes any
+  of the three read another file.
+- `repo-tools depgraph` prints one deprecation line and runs `map`. It accepts the 1.x
+  scan-scope flags (`--src`, `--tests`, `--exclude`, `--also-exclude`, `--all`,
+  `--reachable-only`, `--include-tests`) with a warning, because they have no effect in 2.0.0.
+  `map` exits 1 on them.
 - `compress -d` restores JSON files only.
 
 ## Install
@@ -34,7 +40,7 @@ repo-tools --version
 
 The executable holds the tool and the Bun runtime. It needs no Bun, Node or `node_modules`.
 Download the file for your platform and `SHA256SUMS` from the
-[GitHub release](https://github.com/danielsimonjr/repo-tools/releases/tag/v1.1.0):
+[GitHub release](https://github.com/danielsimonjr/repo-tools/releases/tag/v2.1.0):
 
 | Platform | File |
 |---|---|
@@ -112,7 +118,7 @@ Prerequisites: Bun 1.4.2 or later, and a clone of this repository.
 
    ```sh
    bin/repo-tools-windows-x64.exe --version
-   bin/repo-tools-windows-x64.exe depgraph --root=path/to/repo
+   bin/repo-tools-windows-x64.exe map --root=path/to/repo
    ```
 
 4. Test the executable, not only the source. The executable is the artifact that ships:
@@ -121,28 +127,44 @@ Prerequisites: Bun 1.4.2 or later, and a clone of this repository.
    bun run smoke -- bin/repo-tools-windows-x64.exe
    ```
 
-`bun run build` writes a second channel, the Node bundle `dist/cli.js` (`node dist/cli.js --help`).
+`bun run build` writes a second channel, the Node bundle `dist/cli.js` (`node dist/cli.js --help`),
+with the tree-sitter grammar files (`dist/*.wasm`) next to it.
 
 ## Reports
 
-`repo-tools depgraph` writes its reports into `docs/architecture/` under the root. Every file is
-generated: do not edit it by hand. Run `repo-tools depgraph` again to update it. Each Markdown
-report starts with a "GENERATED FILE -- do not edit by hand" banner.
+`repo-tools map` writes its reports into `docs/architecture/` under the root (`--out=<dir>`
+names another folder; `--out=../reports` writes outside the root). Every file is generated: do
+not edit it by hand. Run `repo-tools map` again to update it. Each Markdown report starts with
+a "GENERATED FILE -- do not edit by hand" banner.
+
+The census is the set of source files that git tracks (outside a git work tree, a pruned walk).
+The language with the most files decides how `map` reads the repository. Input files never come
+from the output folder. The duplicate allowlist, the duplicate baseline and the coverage policy
+are in `docs/architecture/`, or at the path that the config gives. A repository that already has
+its own allowlist must set `map.duplicateAllowlist` (the old key `depgraph.duplicateAllowlist`
+is also read) to that file. Mathts has 283 allowlisted names. With the default path, the
+duplicate gate fails on those names.
+
+A literal relative `import()` is a graph edge. The Python `repo_map.py` records none. The parity
+record in `docs/parity-2.0.0.md` gives the rules and the verdict.
 
 | File | What it answers |
 |---|---|
+| `dependency-graph.json` | The core graph: each file by area, with its imports, exports and edges; the reachability; the cycle counts; and the statistics. |
+| `file-inventory.json` | Where is each source file, and what is it? Package, area and disposition (reachable, build entry, test-only, orphan, test, tool, config, example, bench), and the links that the census did not follow. |
+| `duplicate-symbols.json` | Which names do two or more files define? For TypeScript, also the classified lists. |
+| `unused-analysis.json` | Which exports and files does nothing import? |
+| `dependency-layers.json` | The subsystem view: the `src` files by module, the entry points, the layers and the cyclic components. |
 | `DEPENDENCY_GRAPH.md` | How do the files and modules depend on each other? Per-file imports and exports, the dependency matrix, cyclic components (runtime and type-only), a Mermaid diagram, and statistics. |
-| `dependency-graph.json` | The same graph as data, for tools: modules, files, imports, exports, entry points, cyclic components and statistics. |
-| `dependency-graph.yaml` | The same data as YAML. |
+| `dependency-graph.yaml` | `dependency-graph.json` as YAML. |
 | `dependency-summary.compact.json` | A small summary of the graph, with short keys, to give to a model. |
-| `unused-analysis.md` | Which files and exports does nothing import? Dormant files, split into orphans (reachable from nothing) and test-only files. |
-| `FILE_INVENTORY.md` | Where is every `.ts` file, and what is it? Area and disposition (reachable, build entry, test-only, orphan, test, tool, config, example, bench), and the result of the census self-check. |
-| `file-inventory.json` | The same inventory as data. |
-| `TEST_COVERAGE.md` | Which source files does a test import (directly, through a barrel, or through a side-effect import), and which files does no test reach? |
+| `FILE_INVENTORY.md`, `duplicate-symbols.md`, `unused-analysis.md` | The three JSON reports above, for a person to read. |
+| `TEST_COVERAGE.md` | Which source files does a test load (directly, through a barrel, through a side-effect import, or by `import()`), and which files does no test reach? |
 | `test-coverage.json` | The same coverage data, with the test-to-source map. |
-| `duplicate-symbols.md` | Which names do two or more files define? Each name is classified. |
-| `duplicate-symbols.json` | The same duplicate data as data. |
-| `package-export-surfaces.json` | Which names does each package export publicly? |
+| `package-export-surfaces.json` | Which names does each package export publicly? Not written for C#. |
+
+`docs/parity-2.0.0.md` records how these reports compare with the Python tool and with
+depgraph 1.x.
 
 `repo-tools query --emit` writes two more files into the same folder. They are also generated.
 
@@ -151,30 +173,73 @@ report starts with a "GENERATED FILE -- do not edit by hand" banner.
 | `dependency-reverse.json` | Which files import each file? The reverse edges of the graph. |
 | `node-safety.json` | Which packages are browser-safe, which files import a `node:` builtin, and which of those files does the `.` entry of each browser-safe package reach? |
 
+## Check the documents against the graph
+
+`repo-tools check --docs=<dir>` reads every `*.md` file of the folder. The check reads the
+`## Verification` table of each document. Each row `| claim | value | source |` names a metric of
+the graph (`totalFiles`, `orphanedFiles`, `runtimeCircularDeps` and so on). The value is the
+number that the document states. The check builds the graph again, so a stale report cannot hide
+drift. A relative `--docs` path is relative to the root.
+
+```md
+## Verification
+
+| Claim | Value | Source |
+|---|---|---|
+| totalFiles | 243 | file-inventory.json |
+```
+
+```sh
+repo-tools check --docs=docs/architecture
+# check passed: every claim matches the graph (1 claim in 1 document).
+```
+
+When a value drifts, the exit code is 1, and standard error lists every problem, one per line:
+
+```text
+OVERVIEW.md: totalFiles claims 243 but actual is 244
+```
+
+A document passes without a check when one of its lines is exactly
+`<!-- repo-map:no-verification -->`. The marker must stand alone on its line: a marker inside a
+sentence, a code span or a table cell does not count.
+`repo-tools map` writes that line at the top of each generated report. Every other gap is a
+failure. A missing docs folder, a folder with no `*.md` file, a document without a Verification
+section, and a section without a row are failures. An unknown claim name is a failure too. So is a
+metric that the graph build declared unreliable. `docs/design.md` (section 15) gives the rules and the
+differences from the Python tool. `docs/parity-check.md` records the comparison with that tool on
+11 repositories.
+
 ## Query the graph
 
-`repo-tools query` answers questions from `dependency-graph.json` and
-`package-export-surfaces.json`. It parses no source file, so run `repo-tools depgraph` first.
-The examples use a copy of `tests/fixtures/depgraph/mono-repo`:
+`repo-tools query` answers questions from `dependency-graph.json` (and
+`package-export-surfaces.json` for `is-public`). It parses no source file, so run
+`repo-tools map` first. It reads each area of the graph, and a path that is not a file of the
+graph exits 1. The examples use a copy of `tests/fixtures/depgraph/mono-repo`:
 
 ```sh
-repo-tools depgraph
+repo-tools map
 repo-tools query dependents packages/core/src/math.ts
 # packages/core/src/index.ts
 # packages/core/src/worker.ts
+# packages/core/tests/math.test.ts
 repo-tools query symbol-users add
-# packages/cli/src/main.ts  [@scope/core]
-# packages/core/src/index.ts  [internal]
+# packages/cli/src/main.ts
+# packages/core/src/index.ts
+# packages/core/tests/math.test.ts
 repo-tools query is-public packages/core add
 # PUBLIC: add is exported from packages/core
 repo-tools query is-public packages/core double
 # INTERNAL: double is not in the public export surface of packages/core
 repo-tools query cycles
+# 0 simple cycles
+repo-tools query cycles --components
 # runtime: 0 cyclic components
 # type-only: 0 cyclic components
 ```
 
-A package is the folder above a `src/index.ts` entry (`.` for the root entry). Each package is
+The browser-safety commands serve TypeScript/JavaScript only. A package is the folder above a
+`src/index.ts` file (`.` for the root file). Each package is
 browser-safe, unless `--node-runtime=<pkg,...>` or the config key `query.nodeRuntimes` lists it.
 The `.` entry of a browser-safe package must not reach a file that imports a `node:` builtin:
 
@@ -184,12 +249,12 @@ repo-tools query node-safety
 repo-tools query --check-browser-safety
 # browser-safety check passed: the . entries of 1 browser-safe package reach no node: code.
 repo-tools query --emit
-# Written: docs/architecture/dependency-reverse.json (3 files)
+# Written: docs/architecture/dependency-reverse.json (4 files)
 # Written: docs/architecture/node-safety.json (0 node files, 0 leaks)
 ```
 
 `--check-browser-safety` exits 1 on a leak. The query reads its reports from `--out`, else from
-the config key `query.out`, else from `depgraph.out`, else from `docs/architecture`. Run
+the config key `query.out`, else from `map.out`, else from `docs/architecture`. Run
 `repo-tools query --help` for every option.
 
 ## Develop
@@ -208,7 +273,7 @@ the config key `query.out`, else from `depgraph.out`, else from `docs/architectu
 ## Design
 
 `docs/design.md` describes the modules, the output rules, the config, the extension contract,
-the privacy check and the verification.
+the privacy check and the verification. Its section "The 2.0.0 engine" describes `map`.
 
 ## License