@danielsimonjr/repo-tools 2.2.4 → 2.2.5

package/CHANGELOG.md

@@ -6,6 +6,33 @@ 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

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.4.
+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.4):
+[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.4",
+  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",
@@ -13114,6 +13114,9 @@ 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` 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.";
@@ -13144,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);
@@ -13185,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] ?? [];
@@ -13530,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 = [];
@@ -13548,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("");
@@ -13566,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("");
@@ -13621,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;
@@ -13636,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,
@@ -14140,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];
 }
 
@@ -17517,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))
@@ -18711,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.
@@ -19085,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")
@@ -19094,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.4",
+  "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",