@danielsimonjr/repo-tools 2.2.3 → 2.2.4

package/CHANGELOG.md

@@ -6,6 +6,28 @@ All notable changes to this project are recorded in this file. The format follow
 
 ## [Unreleased]
 
+## [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.4.
 
 - `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.4):
 
 | Platform | File |
 |---|---|

package/dist/cli.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@danielsimonjr/repo-tools",
-  version: "2.2.3",
+  version: "2.2.4",
   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 = {
@@ -13114,8 +13115,8 @@ var IMPORTS_NAME_SYMBOLS = {
   rust: 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)
@@ -14194,14 +14195,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 +14366,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 ?? {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/repo-tools",
-  "version": "2.2.3",
+  "version": "2.2.4",
   "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",