@danielsimonjr/repo-tools 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -6,6 +6,103 @@ All notable changes to this project are recorded in this file. The format follow
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-10-02
+
+`repo-tools docs` is the new gate of the doc comments of a repository. It ports `code_docs.py` of
+the code-docs skill. `docs/parity-docs.md` lists the differences from the Python tool. The
+release also adds the audit of the fix ledger and the check for dangling references to the
+design document.
+
+### Added
+
+- `repo-tools docs`, the gate of the doc comments. The command is a port of `code_docs.py` of the
+  code-docs skill, and it needs no Python. `docs scan` measures the coverage of the exported
+  symbols and writes `COVERAGE.md` and `coverage.json`. `docs check` is the gate: it exits 1 on a
+  MUST issue (M1 to M5) and on a file that does not parse. `--paths` and `--paths-from=<file>`
+  gate the changed files of a pull request only. `docs stub` plans a skeleton comment with the
+  marker `TODO:` for each exported symbol that has no comment. The default is a dry run until
+  `--apply`. After a change, `stub` parses the file again, and it keeps the line ends of the
+  file. The command reads TypeScript, JavaScript and Python with tree-sitter. A
+  `.code-docs.json` file at the root excludes paths, and each entry needs a reason. Section 16
+  of `docs/design.md` describes the command. `docs/parity-docs.md` compares the command with the
+  Python tool on 9 public repositories: 4665 files, 22329 symbols, 690 MUST issues and 11208
+  SHOULD issues. The reports are equal, except for the order of the symbols in 40 files and the
+  doc names of 29 symbols of one repository. The command gives 3 MUST issues more than the Python
+  tool, for stale names in optional `[name]` tags. The record lists the differences. Some are
+  defects of the Python tool. The defects are a closing `*/` in the summary, comment delimiters in
+  the STE check, and the parameter names in a doc. The others are the parser of Python, the exit
+  codes, and the files that `stub` changes.
+- `repo-tools docs stub` never writes through a link. The command skips a file that is a link or
+  resolves outside the root, and names the file. The command does not write a TypeScript block
+  when another token precedes the declaration on its line, for example the end of a template. The
+  end of a Python signature ignores the brackets in strings and a comment after the colon. A root
+  with no source file gives exit code 1, as for `scan` and `check`. `--path=.` selects the whole
+  repository.
+- `docs check --paths-from` reads the quoted names that `git diff --name-only` writes for a
+  non-ASCII file name. The analysers read a JSDoc parameter name with `$`, and the optional forms
+  `[name]` and `[name=default]`. They read a reST field with a type, for example
+  `:param int x:`. A destructured parameter binds the names on the left of a default value. The
+  analysers read each name from the source as written, so a parameter named `abstract` keeps its
+  name. The Python tool has each of these defects, and design section 16.6 lists them.
+- The smoke test has a step for the doc gate. A run of `docs check` reads a TypeScript, a TSX and
+  a Python file, so one run loads the three grammars of the product. The test passes documented
+  source and fails a new undocumented export.
+- `bun run audit:ledger`, the audit of the fix ledger. For each fix (F1 to F44, M1 and R1), the
+  script restores the 1.x defect in a scratch copy of the repository. Then it runs the tests.
+  It runs the test file of the fix first, and then the whole suite. A test of the fix file must
+  fail. Each test has a 30 s limit (`--test-timeout-s`). A run in which only tests hit their
+  time limit is an error, because load can cause it.
+  The script exits 0 only when this holds for every mutation. Section 12 of
+  `docs/design.md` describes the audit. `scripts/fix-ledger-mutations.ts` holds the 77
+  mutations. `docs/fix-ledger-audit.md` holds the result: 77 of 77 mutations fail a test of
+  their own fix. The tests of the audit make their temporary repositories with a git identity
+  that the privacy check accepts.
+- Tests for the fixes that no test of their own locked. F12: the module map of
+  `dependency-layers.json`. F26: components sorted by smallest member. F30: the map resolver
+  picks a `.tsx` file and a directory index. F34: a workspace package folder that is a link.
+  F43: the `src/<sub>/index.ts` fallback of an `exports` subpath. The tests of F17, F41 and F43
+  assert more. They assert the `src/index.ts` fallback root, an excluded package that has an
+  entry, and the edges of a self-import.
+- `bun run check:design`, the check for dangling references to `docs/design.md`. A comment, a
+  test title or a workflow can name a part of the design, for example `design 11.4`. The script
+  finds each such reference and looks for a heading with that number. It prints each reference
+  that has no heading, and it exits 1. The unit tests run it on this repository. The check
+  proves that the number exists. It cannot prove that the heading has the meaning that the
+  reference gives.
+
+### Changed
+
+- The grammar loader reads a third grammar, TSX. The Node bundle and the npm package now hold four
+  `.wasm` files and not three, and the compiled executable holds the TSX grammar too. `docs` uses
+  it for `.tsx` and `.jsx` files. `map` still reads these files with the TypeScript grammar.
+- The directory readers of the map engine read through `readdirHook`. The readers are discovery,
+  the two `.csproj` walks and the folder list of a workspace pattern. The F2 test replaces
+  `readdirHook`. Before, the map never called the reader that the F2 test reversed. The test
+  passed with or without the sort in discovery.
+- `docs/fix-ledger-2.0.0.md` describes what each test locks. The rows for F9 to F12, F19 to F21,
+  F23, F24, F27 and F29 to F31 described other behavior. The rows for F13, F36, F41 and F44 sat
+  in the section "No 2.0.0 meaning", although tests lock them. The test for M1 said that
+  `--reachable-only` removes a file. It asserts that `map` rejects the flag.
+- `docs/design.md` now holds the parts that the code names. Section 11 has the subsections 11.1
+  to 11.4: the Node bundle, the compiled executables, the workflows and the release. Section 12
+  has 12.1, the steps of the smoke test. Section 14.2 describes the API-surface flags.
+- The check found 50 references in comments, test titles and workflows to a part that the
+  document never had. Each reference now names an existing section. Four more references named
+  section 4 for the chunk and compress modules. Section 4 holds the output rules, so they now
+  name section 8.
+
+### Maintenance
+
+- The root `bun` Dependabot entry is removed from `.github/dependabot.yml`. It cannot succeed.
+  The bun updater of Dependabot reads `bun.lock` lockfileVersion 1, and Bun 1.4 writes 2. The
+  `npm` alternative aborts during file fetching on a bun-managed project. Each error recommends
+  the other. Measured here: the `bun in /.` updater job failed on 2026-09-24 and again on
+  2026-10-01, while `github_actions in /.` succeeded on both days. `github-actions` updates are
+  unchanged. The file now records the two errors, the cost and a checkable revisit condition.
+  **Unlike the sibling repositories in this sweep, this one also has Dependabot alerts
+  disabled.** Thus nothing reports a vulnerable dependency either. A bump is entirely a human
+  action: `bun outdated`, `bun update <pkg>`, then commit the regenerated `bun.lock`.
+
 ## [2.1.0] - 2026-10-01
 
 `repo-tools check` is the new drift gate for the Markdown documents of a repository. It ports

package/README.md

@@ -7,12 +7,13 @@
 | `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. |
+| `docs` | Measures the doc comments of TypeScript, JavaScript and Python files, plans the missing ones, and gates the result. |
 | `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.1.0.
+Status: version 2.2.0.
 
 - `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
@@ -40,7 +41,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.1.0):
+[GitHub release](https://github.com/danielsimonjr/repo-tools/releases/tag/v2.2.0):
 
 | Platform | File |
 |---|---|
@@ -210,6 +211,57 @@ metric that the graph build declared unreliable. `docs/design.md` (section 15) g
 differences from the Python tool. `docs/parity-check.md` records the comparison with that tool on
 11 repositories.
 
+## Gate the documentation comments
+
+`repo-tools docs` reads the TypeScript, JavaScript and Python files that git tracks. It finds each
+function, class, interface, type alias and method, and the doc comment of each one. It needs no
+Python on the computer.
+
+```sh
+repo-tools docs scan .                      # writes docs/code-docs/COVERAGE.md and coverage.json
+repo-tools docs check .                     # the gate: exit 1 on a MUST issue
+repo-tools docs stub . --path=src/api       # a dry run: lists the stubs and writes nothing
+repo-tools docs stub . --path=src/api --apply
+```
+
+The rules are:
+
+| Rule | Tier | The rule |
+|---|---|---|
+| M1 | MUST | An exported symbol has a doc comment. A test file is exempt. |
+| M2 | MUST | The doc comment has a summary line. |
+| M3 | MUST | The doc comment names no parameter that the signature lacks. |
+| M4 | MUST | The doc comment holds no `TODO:` marker. |
+| M5 | MUST | A file uses one doc dialect: `google`, `numpy` or `rest` for Python, `tsdoc` or `jsdoc` for TypeScript. |
+| S2 | SHOULD | The summary ends with a full stop. |
+| S5 | SHOULD | The doc comment does not repeat a type that the signature holds. |
+| S6 | SHOULD | The prose follows Simplified Technical English (the rules of `repo-tools ste`). |
+
+Only a MUST issue changes the exit code of `check`. A file that does not parse is also a failure,
+because an unknown file is not a clean file. A repository with no source file fails too.
+
+`stub` is a dry run until you pass `--apply`. Each stub holds the marker `TODO:`, so `check` fails
+until you replace the stub with real prose. The command parses a file again after the change.
+A file that would no longer parse stays unchanged. The command skips a file that is a link or
+resolves outside the root, and it names the skipped file.
+
+To gate a pull request and not the whole backlog, give `check` the changed files:
+
+```sh
+git diff --name-only origin/main... > changed.txt
+repo-tools docs check . --paths-from=changed.txt
+```
+
+A `.code-docs.json` file at the root excludes paths. Each entry needs a reason, and the output
+names each exclusion:
+
+```json
+{ "exclude": [ { "path": "assembly/", "reason": "AssemblyScript" } ] }
+```
+
+`docs/design.md` (section 16) gives the rules, the exit codes and the differences from the Python
+tool. `docs/parity-docs.md` records the comparison with that tool on 9 repositories.
+
 ## Query the graph
 
 `repo-tools query` answers questions from `dependency-graph.json` (and
@@ -269,6 +321,8 @@ the config key `query.out`, else from `map.out`, else from `docs/architecture`.
 | `bun run smoke -- <command...>` | Runs the smoke test against one way to run the tool. |
 | `bun run privacy` | Runs the privacy check on the tracked files and the commit messages. |
 | `bun run hooks` | Installs the `commit-msg` hook that runs the privacy check on each message. |
+| `bun run audit:ledger` | Reverts each fix of `docs/fix-ledger-2.0.0.md` in a scratch copy and checks that a test of that fix fails. |
+| `bun run check:design` | Finds each reference to a section of `docs/design.md` that has no heading with that number. |
 
 ## Design