@danielsimonjr/repo-tools 2.2.3 → 2.2.5

package/CHANGELOG.md

@@ -6,6 +6,55 @@ All notable changes to this project are recorded in this file. The format follow
 
 ## [Unreleased]
 
+## [2.2.5] - 2026-10-22
+
+### Changed
+
+- The C# test-coverage report states its basis. A C# `using` usually names a namespace, so a test covers every file
+  that declares the namespace, and a covered file is not proof that a test uses the file. A test in the same namespace,
+  or in a nested namespace, needs no `using` and does not count, so the percentage can be too high or too low.
+  `TEST_COVERAGE.md` now has a note under the summary table that says "counted by namespace import".
+  `test-coverage.json` now has `metadata.coverageBasis` (`namespace-import`) and `metadata.coverageCaveat`. The
+  percentage does not change. The reports of TypeScript, Python and Rust have no note and no new key, and the golden
+  files do not change.
+  `importsNameSymbols` in `src/map/artifacts.ts` is now the one rule for "does an import name a symbol"; the
+  unused-analysis caveat and its export classification use it as well.
+- `docs/design.md` passes `repo-tools ste` with 0 problems. The check reported 4 sentences of 31 to 43 words in
+  section 16.3. Each of the 4 sentences is now a group of shorter sentences. No fact changes.
+
+### Fixed
+
+- `repo-tools docs` fails on a repository that has more files of a language it cannot read than TypeScript,
+  JavaScript and Python together. It printed `PASS -- 0/0 exported symbols documented, 0 MUST issues` and exited 0
+  for IronClaw, a Rust repository. `docs check src` measured the 1 JavaScript file below `src` and none of the 247
+  Rust files. `scan`, `check` and `stub` now exit 1 and print
+  `this repo is rust: 247 rust file(s) against 1 TypeScript, JavaScript or Python file(s)`. `map` already refused
+  such a repository. `docs` uses the file walk of `map`, so both commands give a repository the same language. A tie
+  is measured. A TypeScript repository with a few Rust files is measured as before. A repository of Go files only
+  now names Go. It said before that it found no source file.
+
+## [2.2.4] - 2026-10-19
+
+### Fixed
+
+- `repo-tools map` and `repo-tools docs` read a `.js`, `.mjs` or `.cjs` file with the TSX grammar. These files used
+  the TypeScript grammar, which cannot read JSX. A JavaScript file that holds JSX then gave error nodes, and a
+  `docs` run counted the file as unparsed. A JavaScript file cannot hold an angle-bracket type assertion, which
+  TSX cannot read. The measurement used 2446 tracked JavaScript files in 87 repositories. It skipped build-output
+  and vendor folders, minified files and files over 1.5 MB. The TSX grammar added no error node to any file. It
+  removed the error nodes of the one file that held JSX. No export count changed. A `.ts` file keeps the
+  TypeScript grammar.
+
+- `repo-tools map` writes `duplicate-symbols.md` and `unused-analysis.md` with text that passes `repo-tools ste`. A
+  TypeScript repository got a 70-word introduction in `duplicate-symbols.md`. `unused-analysis.md` held caveat
+  sentences of 28 and 44 words and an ambiguous "This is". For C#, it held four more findings (three long sentences
+  and one ambiguous reference), and for Rust one long sentence. A hand edit of a generated report is lost at the
+  next run, so the generator text had to change. The introduction of `duplicate-symbols.md` is now three short
+  sentences and a list of the four tags. Each long caveat is split into short sentences. No fact changed, and no
+  opt-out marker is added. The new test `map-reports-ste.test.ts` maps a TypeScript, a C#, a Rust and a Python
+  repository and expects no STE finding in either report. A repository that commits these reports sees a one-time
+  diff at its next `repo-tools map`.
+
 ## [2.2.3] - 2026-10-16
 
 ### Fixed

package/README.md

@@ -13,7 +13,7 @@
 | `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.2.3.
+Status: version 2.2.5.
 
 - `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
@@ -41,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.2.3):
+[GitHub release](https://github.com/danielsimonjr/repo-tools/releases/tag/v2.2.5):
 
 | Platform | File |
 |---|---|
@@ -238,7 +238,9 @@ The rules are:
 | 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.
+because an unknown file is not a clean file. A repository with no source file fails too. So does a
+repository with more files of another language (Rust or Go, for example) than TypeScript, JavaScript
+and Python together. The command names the language and exits 1.
 
 `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.

package/dist/cli.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@danielsimonjr/repo-tools",
-  version: "2.2.3",
+  version: "2.2.5",
   description: "One CLI for repository analysis: dependency graphs creation and query with per-export API facts, file chunking, and context compression. TypeScript on Bun, compiled to a single executable.",
   type: "module",
   license: "MIT",
@@ -10895,8 +10895,9 @@ function loadGrammar(name2) {
   }
   return pending;
 }
+var TSX_SUFFIXES = [".tsx", ".jsx", ".js", ".mjs", ".cjs"];
 function grammarFor(path) {
-  return path.endsWith(".tsx") || path.endsWith(".jsx") ? "tsx" : "typescript";
+  return TSX_SUFFIXES.some((suffix) => path.endsWith(suffix)) ? "tsx" : "typescript";
 }
 function parserFor(name2) {
   const parser = parsers.get(name2);
@@ -13104,7 +13105,7 @@ var UNUSED_CAVEATS = [
   "A literal relative `import(...)` is a graph edge. A runtime call is a namespace use (`*`), so the exports of that file count as used. A type-position `import(...).Name` counts only `Name`, and `typeof import(...)` counts none. A dynamic import built from a variable or a template, and other runtime loads (e.g. `new Worker(path)`), are still invisible -- a file or export reached ONLY through one of those is reported as no-importer/unreferenced even though it may be live.",
   "`noImporterFiles` is NOT a deletion-candidate list. A file with zero in-repo importers is expected, not suspicious, for: a standalone script invoked directly (e.g. a smoketest run via `node script.mjs`, never `import`ed by anything), or a build/lint config file loaded by its own tool rather than by source code (e.g. `eslint.config.mjs`, read by eslint itself). Cross-check against package.json scripts / tool configs before treating any entry here as dead.",
   "Only NAMED exports are analysed (`FileNode.exports` carries named exports only) -- `export default` usage is not checked here.",
-  "The `referencedInModule` vs `unreferencedAnywhere` split for exports is a TEXT-LEVEL heuristic (whole-identifier occurrence count within the defining file's own source, minus the declaration site itself), not an AST reference count -- it can over-count a name that also appears in a string literal or comment. When the source text can't be read at all (no `RepoGraph.root_path`, or the file is missing) the export lands in `unclassifiedExports` instead of being guessed into either bucket.",
+  "The split of exports into `referencedInModule` and `unreferencedAnywhere` is a TEXT-LEVEL heuristic. The analysis counts whole-identifier occurrences in the source of the defining file, minus the declaration site itself. The count is not an AST reference count. The analysis can over-count a name that also appears in a string literal or comment. When the source text cannot be read (no `RepoGraph.root_path`, or the file is missing), the export lands in `unclassifiedExports`. The analysis does not guess a bucket for it.",
   "`unreferencedAnywhereNotes`'s dynamic-import check (`_dynamic_import_referrers`) only sees `import(...)` calls with a LITERAL string specifier. A dynamic import built from a variable or template literal (e.g. `import(`./cmds/${name}.js`)`, a command-dispatcher pattern) is invisible to it -- 'found none' in a note means no LITERAL match was found, NOT that nothing imports the file."
 ];
 var IMPORTS_NAME_SYMBOLS = {
@@ -13113,9 +13114,12 @@ var IMPORTS_NAME_SYMBOLS = {
   csharp: false,
   rust: true
 };
+function importsNameSymbols(language) {
+  return IMPORTS_NAME_SYMBOLS[language] ?? true;
+}
 var PUBLIC_API_LANGUAGES = new Set(["rust"]);
-var PUBLIC_API_CAVEAT = "A `pub` item with no user inside this crate is normally PUBLIC API, not dead code. `unused-analysis` can only see this repository, and a library crate's public surface exists for DOWNSTREAM consumers that are not in the graph -- so 'no importer here' is the expected state for most public items, not a finding. Measured on one real crate: 2,635 of 2,739 exports (96%) had no in-crate user, and essentially all of them were live API. Treat this list as 'candidates to check against the crate's intended surface', never as a deletion list.";
-var NAMESPACE_IMPORT_CAVEAT = "This language's imports name a namespace, not the symbols they bring in (C#'s `using App.Hosting;`), so per-symbol usage cannot be read off the import edges at all. Usage here is a whole-identifier text search across every scanned file instead -- the same class of TEXT-LEVEL heuristic as the `referencedInModule` split above, and subject to the same limit: a name appearing in another file's comment or string literal counts as a use. That makes this direction conservative -- it UNDER-reports dead code rather than inventing it -- which is the safe direction for a list whose entries read as deletion candidates. A type reached only by reflection (`Activator.CreateInstance`, DI-by-convention) or named solely in a .csproj/XAML file is invisible either way.";
+var PUBLIC_API_CAVEAT = "A `pub` item with no user inside this crate is normally PUBLIC API, not dead code. `unused-analysis` sees only the repository. A library crate's public surface exists for DOWNSTREAM consumers. These consumers are not in the graph. Therefore, 'no importer here' is the expected state for most public items. The state is not a finding. Measured on one real crate: 2,635 of 2,739 exports (96%) had no in-crate user, and essentially all of them were live API. Treat this list as 'candidates to check against the crate's intended surface', never as a deletion list.";
+var NAMESPACE_IMPORT_CAVEAT = "In this language, an import names a namespace, not the symbols that it brings in (C#'s `using App.Hosting;`). The import edges therefore cannot show the use of one symbol. Usage here is a whole-identifier text search across every scanned file instead. The search is the same class of TEXT-LEVEL heuristic as the `referencedInModule` split above. The limit is the same: a name in the comment or string literal of another file counts as a use. The search is conservative. It UNDER-reports dead code and never invents it. That direction is safe for a list whose entries read as deletion candidates. Neither the import edges nor the text search can see a type that only reflection reaches (`Activator.CreateInstance`, DI-by-convention) or that only a .csproj/XAML file names.";
 var IDENTIFIER = new RegExp(`${B}[A-Za-z_]${W}*`, "gu");
 function readSourceText(rootPath, rel) {
   if (rootPath === null)
@@ -13143,7 +13147,7 @@ function identifierUsers(graph) {
 }
 function caveatsFor(graph) {
   const caveats = [...UNUSED_CAVEATS];
-  if (!(IMPORTS_NAME_SYMBOLS[graph.language] ?? true))
+  if (!importsNameSymbols(graph.language))
     caveats.push(NAMESPACE_IMPORT_CAVEAT);
   if (PUBLIC_API_LANGUAGES.has(graph.language))
     caveats.push(PUBLIC_API_CAVEAT);
@@ -13184,7 +13188,7 @@ function classifyUnusedExports(graph) {
   const unreferenced = {};
   const referencedInModule = {};
   const unclassified = {};
-  const namesSymbols = IMPORTS_NAME_SYMBOLS[graph.language] ?? true;
+  const namesSymbols = importsNameSymbols(graph.language);
   const users = namesSymbols ? new Map : identifierUsers(graph);
   const push = (bucket, path, name2) => {
     const list = bucket[path] ?? [];
@@ -13529,6 +13533,8 @@ import { basename as basename5 } from "node:path";
 function percent(tested, total) {
   return total > 0 ? (tested / total * 100).toFixed(1) : "0";
 }
+var NAMESPACE_IMPORT_BASIS = "namespace-import";
+var NAMESPACE_IMPORT_COVERAGE_CAVEAT = "Coverage is counted by namespace import. A C# `using` directive usually names a namespace, not a type, so a test covers every file that declares the namespace. A namespace import does not show that a test uses the file. A test in the same namespace, or in a nested namespace, needs no `using` and does not count. The percentage can be too high or too low.";
 function generateTestCoverageMarkdown(coverage, options = {}) {
   const hint = options.expectedTestHint ?? true;
   const lines = [];
@@ -13547,9 +13553,11 @@ function generateTestCoverageMarkdown(coverage, options = {}) {
   lines.push(`| Source Files without Tests | ${totalUntested} |`);
   lines.push(`| Coverage (raw, direct-import) | **${percent(totalTested, totalSource)}%** |`);
   const b = coverage.policyBreakdown;
+  const basisNote = options.namespaceImportBasis ? [`> ${NAMESPACE_IMPORT_COVERAGE_CAVEAT}`, ""] : [];
   if (coverage.policy) {
     lines.push(`| Coverage (effective, active code only) | **${b.effectivePercent}%** (${b.testedActive} / ${b.activeFiles}) |`);
     lines.push("");
+    lines.push(...basisNote);
     const policyPath = options.policyPath ?? "docs/architecture/coverage-policy.json";
     lines.push("> The raw figure counts every source file the CDG tool finds, including code that is " + "intentionally not direct-imported by a vitest `*.test.ts` (synced mathjs categories, " + "AssemblyScript sources, type-only barrels, …). The **effective** figure excludes those " + `per \`${policyPath}\` so the number reflects the genuinely-active hand-written code only. ` + "See [`COVERAGE_POLICY.md`](./COVERAGE_POLICY.md) for the policy.");
     lines.push("");
@@ -13565,6 +13573,8 @@ function generateTestCoverageMarkdown(coverage, options = {}) {
     }
     lines.push(`| **Active (real gap — needs a test)** | ${b.byCategory.active_untested ?? 0} | These are the files that should grow a direct-import test. |`);
     lines.push("");
+  } else if (basisNote.length > 0) {
+    lines.push("", ...basisNote);
   }
   lines.push("---");
   lines.push("");
@@ -13620,7 +13630,7 @@ function generateTestCoverageMarkdown(coverage, options = {}) {
   return lines.join(`
 `);
 }
-function generateTestCoverageJson(coverage) {
+function generateTestCoverageJson(coverage, options = {}) {
   const coverageMapObj = {};
   for (const [source, tests] of coverage.coverageMap)
     coverageMapObj[source] = tests;
@@ -13635,6 +13645,10 @@ function generateTestCoverageJson(coverage) {
       testedCount: coverage.testedFiles.length,
       untestedCount: coverage.untestedFiles.length,
       coveragePercent: percent(coverage.testedFiles.length, coverage.sourceFiles.length),
+      ...options.namespaceImportBasis ? {
+        coverageBasis: NAMESPACE_IMPORT_BASIS,
+        coverageCaveat: NAMESPACE_IMPORT_COVERAGE_CAVEAT
+      } : {},
       effectiveCoverage: {
         policyLoaded: coverage.policy !== null,
         activeFiles: b.activeFiles,
@@ -14139,12 +14153,14 @@ function emitTestCoverage(graph, root, outDir, options = {}) {
   const coverage = analyzeTestCoverage(sources, tests, root, options.policyPath ?? join16(root, "docs", "architecture", "coverage-policy.json"));
   const mdPath = join16(outDir, "TEST_COVERAGE.md");
   const jsonPath = join16(outDir, "test-coverage.json");
+  const namespaceImportBasis = !importsNameSymbols(graph.language);
   const markdown = generateTestCoverageMarkdown(coverage, {
     expectedTestHint: graph.language === "typescript",
-    policyPath: options.policyNote ?? "docs/architecture/coverage-policy.json"
+    policyPath: options.policyNote ?? "docs/architecture/coverage-policy.json",
+    namespaceImportBasis
   });
   writeReport(mdPath, withBanner(markdown, { command: MAP_REGENERATE_COMMAND, ...options.banner }));
-  writeReport(jsonPath, JSON.stringify(generateTestCoverageJson(coverage), null, 2));
+  writeReport(jsonPath, JSON.stringify(generateTestCoverageJson(coverage, { namespaceImportBasis }), null, 2));
   return [mdPath, jsonPath];
 }
 
@@ -14194,14 +14210,22 @@ function generateDuplicateSymbolsMarkdown(report) {
   let md = `# Duplicate Symbols
 
 `;
-  md += "Names that are OWN-DEFINED (not merely re-exported) by >= 2 distinct files across ";
-  md += "the monorepo, then CLASSIFIED (see `DupEntryTag`) so the actionable subset is clear: ";
-  md += "`TRUE_DUPLICATE` (real merge targets) vs `DISPATCH_VARIANT` (>=2 `mathTyped(...)` ";
-  md += "registrations of the same public name — distinct dispatch surfaces, Bucket C delegation ";
-  md += "candidates, not copy-paste bodies), `ALIAS_DELEGATION` (a `const X = importedY` ";
-  md += "forward, excluded once <2 real bodies remain), and `ALLOWLISTED` (matches ";
-  md += "`duplicate-allowlist.json`: hot-path `is*` guards, AssemblyScript mirrors, ";
-  md += "per-package `VERSION` strings).\n\n";
+  md += "A name is listed here when two or more distinct files across the monorepo define it. ";
+  md += "A file that only re-exports the name does not count. ";
+  md += "Each name carries one tag (see `DupEntryTag`), so the actionable subset is clear:\n\n";
+  md += "- `TRUE_DUPLICATE`: a real merge target.\n";
+  md += "- `DISPATCH_VARIANT`: two or more `mathTyped(...)` registrations of the same public name. ";
+  md += "The registrations are distinct dispatch surfaces and Bucket C delegation candidates, ";
+  md += `not copy-paste bodies.
+`;
+  md += "- `ALIAS_DELEGATION`: a `const X = importedY` forward. ";
+  md += `The entry is excluded once fewer than two real bodies remain.
+`;
+  md += "- `ALLOWLISTED`: the name matches `duplicate-allowlist.json`. ";
+  md += "Examples are hot-path `is*` guards, AssemblyScript mirrors and per-package `VERSION` ";
+  md += `strings.
+
+`;
   md += `> **Note:** ${report.note}
 
 `;
@@ -14357,7 +14381,7 @@ function unusedMarkdown(unused, graph) {
   lines.push("Source files that only a test reaches. They ship nothing, but a test uses them.", "");
   bulletList(lines, testOnly);
   lines.push("## Files with no in-repo importer", "");
-  lines.push("No file of this repository imports these files. This is not a deletion list.", "");
+  lines.push("No file of this repository imports these files. Do not use the list as a deletion list.", "");
   bulletList(lines, unused.noImporterFiles ?? []);
   bucket(lines, "Exports unreferenced anywhere", "No other file imports these names, and their own module does not use them.", unused.unreferencedAnywhere ?? {});
   const notes = unused.unreferencedAnywhereNotes ?? {};
@@ -17508,6 +17532,22 @@ class ConfigError extends Error {
     this.name = "ConfigError";
   }
 }
+
+class UnreadableRepoLanguage extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnreadableRepoLanguage";
+  }
+}
+function assertReadableLanguage(root) {
+  const counts = countLanguages(root);
+  const readable = (counts.typescript ?? 0) + (counts.python ?? 0);
+  const unreadable = Object.entries(counts).filter(([language]) => language !== "typescript" && language !== "python").sort(([a, x], [b, y]) => y - x || (a < b ? -1 : a > b ? 1 : 0));
+  const [language, n] = unreadable[0] ?? ["", 0];
+  if (n > readable) {
+    throw new UnreadableRepoLanguage(`this repo is ${language}: ${n} ${language} file(s) against ${readable} TypeScript, ` + "JavaScript or Python file(s). repo-tools docs reads TypeScript, JavaScript and Python " + "only, so a PASS here would describe the wrong files. It fails rather than print a gate " + "that measured nothing.");
+  }
+}
 function languageOf(path) {
   const suffix = suffixOf(path.slice(path.lastIndexOf("/") + 1));
   if (PYTHON_SUFFIXES2.has(suffix))
@@ -18702,7 +18742,9 @@ var DOCS_HELP = `Usage: repo-tools docs scan  [root] [--out=<dir>]
 Measure, stub and gate the documentation comments of the TypeScript, JavaScript
 and Python files of a repository. The files are the files that git tracks. A
 file in a skipped folder (node_modules, dist, build, bundle, out, vendor) or
-with a generated name (.d.ts, .min.js, _pb2.py) is not read.
+with a generated name (.d.ts, .min.js, _pb2.py) is not read. A repository with
+more files of another language (for example Rust or Go) than TypeScript,
+JavaScript and Python together is refused: the run names the language and exits 1.
 
 Actions:
   scan   Measure the coverage. Write COVERAGE.md and coverage.json.
@@ -19076,6 +19118,7 @@ async function run5(argv, io) {
     root = resolve8(options.root);
     if (!isDirectory(root))
       throw new Error("the root <root> is not an existing directory");
+    assertReadableLanguage(root);
     if (options.action === "scan")
       return await runScan(root, options, io);
     if (options.action === "stub")
@@ -19085,7 +19128,7 @@ async function run5(argv, io) {
     const message = error instanceof Error ? error.message : String(error);
     stderr(`repo-tools docs: ${message}
 `);
-    return error instanceof NothingToMeasure ? 1 : 2;
+    return error instanceof NothingToMeasure || error instanceof UnreadableRepoLanguage ? 1 : 2;
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/repo-tools",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "description": "One CLI for repository analysis: dependency graphs creation and query with per-export API facts, file chunking, and context compression. TypeScript on Bun, compiled to a single executable.",
   "type": "module",
   "license": "MIT",