@danielsimonjr/repo-tools 1.1.0 → 2.0.0

package/CHANGELOG.md

@@ -6,6 +6,238 @@ All notable changes to this project are recorded in this file. The format follow
 
 ## [Unreleased]
 
+## [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
+
+- `map` makes no graph edge for a dynamic `import()`, as the Python tool does. depgraph 1.x
+  made one. So a cycle that closes only through `import()` is not a cycle in 2.0.0. On
+  memoryjs, one type-only cyclic component has 3 files, not 7. Test coverage still counts a
+  literal `import()` in a test file as a load.
+
+### 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,25 @@
 # 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). |
 | `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.0.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` 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 either
+  subcommand 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 +39,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.0.0):
 
 | Platform | File |
 |---|---|
@@ -112,7 +117,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 +126,38 @@ 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.
 
 | 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.
 
@@ -153,28 +168,34 @@ report starts with a "GENERATED FILE -- do not edit by hand" banner.
 
 ## 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 +205,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 +229,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