@danielsimonjr/repo-tools 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -6,6 +6,96 @@ 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
@@ -16,10 +106,10 @@ 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.
+- 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
 

package/README.md

@@ -6,16 +6,17 @@
 |---|---|
 | `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 graph of `map`, and writes two derived reports. |
 | `ste` | Checks Markdown or docstring prose against Simplified Technical English. |
 
-Status: version 2.0.0.
+Status: version 2.1.0.
 
-- `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.
+- `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.
@@ -39,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/v2.0.0):
+[GitHub release](https://github.com/danielsimonjr/repo-tools/releases/tag/v2.1.0):
 
 | Platform | File |
 |---|---|
@@ -139,7 +140,13 @@ 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.
+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 |
 |---|---|
@@ -166,6 +173,43 @@ depgraph 1.x.
 | `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