@danielsimonjr/repo-tools 2.2.1 → 2.2.3

package/CHANGELOG.md

@@ -6,6 +6,67 @@ All notable changes to this project are recorded in this file. The format follow
 
 ## [Unreleased]
 
+## [2.2.3] - 2026-10-16
+
+### Fixed
+
+- `repo-tools map` reads a `.tsx` or `.jsx` file with the TSX grammar. It read the file with the TypeScript grammar,
+  which cannot read JSX. That grammar gives error nodes, and the export statements that survive the error recovery
+  depend on the text of the file. The same component file gave 1 export without doc comments and 2 exports with doc
+  comments. In one application repository of 746 source files, the export count rises from 3259 to 3406, and the
+  count is the same with and without the doc comments. A drift gate (`repo-tools check`) that holds the earlier count
+  fails until `repo-tools map` writes the reports again.
+  A `.js`, `.mjs` or `.cjs` file that holds JSX still uses the TypeScript grammar.
+
+## [2.2.2] - 2026-10-15
+
+### Changed
+
+- The workflows pin three GitHub Actions to a newer release: `actions/upload-artifact` v7.0.1 to v7.0.2 (in `ci.yml` and
+  `build.yml`), `actions/download-artifact` v8.0.1 to v8.0.2 (in `build.yml`) and `actions/setup-node` v7.0.0 to v7.1.0 (in
+  `ci.yml`). Each pin is the commit of the upstream release tag. `build.yml` runs only on a `v*` tag, so the next release
+  build is the first run of the new `download-artifact` pin.
+
+### Fixed
+
+- `repo-tools docs` reads a `.tsx` or `.jsx` file that has a bare `&` in JSX text (`<h3>Review & Start</h3>`).
+  React and `tsc` accept the text, and the grammar gave an error node, so the file was an unparsed file and its
+  symbols were not measured. The analyser now writes a space over a `&` that is the first character of an error
+  node directly inside a JSX element, which keeps the length, and parses again. Any other error stays an error.
+  A real syntax error beside such a text is still reported. In one application repository four files moved from
+  unparsed to measured, and two files with `import()` type expressions stay unparsed.
+- `repo-tools docs check` reads the documentation of an overload set from its first overload. Before, the analyser read only
+  the comment that directly precedes a declaration, so an implementation signature that follows overload signatures counted
+  as undocumented (M1), although a caller sees only the overloads. A repository then needed a comment that no reader sees.
+  The implementation signature now takes the doc of the first overload of the same name, in a function set and in a class
+  member set. A doc that directly precedes the implementation still wins. A statement between the overloads and the
+  implementation ends the set. The `;` that ends a member signature in a class body does not end the set.
+  Rule M3 still compares the documented parameters with the implementation.
+- `repo-tools docs` reads a file that has an `import("m")` type expression (`let v: import("fs").Dirent[]` and
+  `f<typeof import("m")>()`). `tsc` accepts both. The grammar reads the call as a member expression of a value, so it
+  cannot take `[]` after it, and it reads the call in a type argument as a comparison. Both gave error nodes, so the
+  file was an unparsed file. When the first parse has an error, the analyser now writes an identifier of equal length
+  over each `import("m")` call that holds a string literal, keeps its line breaks, and parses again. A file that
+  parses is never rewritten, and any other error stays an error. In the application repository of the earlier entry
+  the last two unparsed files move to measured.
+- Two fan-out tests (`map-graph.test.ts` and `map-query.test.ts`) have an explicit 30 s timeout. Each builds a graph of about
+  9,000 nodes. The graph test took 0.85 s on a fast machine and 4.57 s on a slower one, against bun's 5 s default, so it
+  failed there under any load. The tests check a step bound, not time, so only the timeout changes. A comment on each test records the measurement and
+  names no machine, because the privacy check rejects machine names.
+- The privacy check accepts one finding in the history: the squash commit of #18 (`46a45d4c19af`) carries a
+  `Co-authored-by` trailer that GitHub added for the maintainer identity on the pull request branch, at line 53 of the
+  message. A commit message cannot change after a merge, so `scripts/privacy-accepted.txt` holds the entry, as it does
+  for `fc930a32f5d2`. Before, the `privacy` job and the test `this repository scans clean` failed on `main` after the
+  merge, although the pull request was green. A squash whose commits are all by the pull request opener adds no trailer.
+- `repo-tools docs` keeps the doc of a declaration when a tool directive stands between the doc comment and the
+  declaration (`// eslint-disable-next-line`, `// @ts-expect-error`, `// prettier-ignore`, `// biome-ignore` and the
+  other directives of a closed list). Before, the directive hid the doc and the symbol counted as undocumented (M1),
+  although a directive applies to the next line and so must stay directly above the declaration; a React repository
+  with the `react-refresh` lint rule had four such hooks and components. A plain line comment can move, so it still
+  separates a doc comment from its declaration. `docs stub` also writes
+  a new block above the directive and not between the directive and the declaration, where the directive would apply
+  to the block.
+
 ## [2.2.1] - 2026-10-08
 
 ### 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.1.
+Status: version 2.2.3.
 
 - `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.1):
+[GitHub release](https://github.com/danielsimonjr/repo-tools/releases/tag/v2.2.3):
 
 | Platform | File |
 |---|---|

package/dist/cli.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@danielsimonjr/repo-tools",
-  version: "2.2.1",
+  version: "2.2.3",
   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,6 +10895,9 @@ function loadGrammar(name2) {
   }
   return pending;
 }
+function grammarFor(path) {
+  return path.endsWith(".tsx") || path.endsWith(".jsx") ? "tsx" : "typescript";
+}
 function parserFor(name2) {
   const parser = parsers.get(name2);
   if (!parser)
@@ -11122,8 +11125,8 @@ function addDynamicImportEdges(mod, calls) {
     });
   }
 }
-function parseTs(source) {
-  const tree = parserFor("typescript").parse(source);
+function parseTs(source, path = "") {
+  const tree = parserFor(grammarFor(path)).parse(source);
   if (!tree)
     throw new Error("tree-sitter returned no tree");
   const mod = emptyModule();
@@ -12568,6 +12571,8 @@ async function buildGraph(root) {
   }
   if (language === "typescript" || language === "python")
     await loadGrammar(language);
+  if (language === "typescript" && found.some((f) => grammarFor(f.path) === "tsx"))
+    await loadGrammar("tsx");
   const resolver = getResolver(language);
   const read = READERS[language];
   const parsed = new Map;
@@ -12576,7 +12581,7 @@ async function buildGraph(root) {
     const text = readSource(join11(root, f.path)).replace(/\r\n?/g, `
 `);
     sources.set(f.path, text);
-    parsed.set(f.path, read(text));
+    parsed.set(f.path, read(text, f.path));
   }
   resolver.indexNamespaces?.(parsed);
   const files = new Map;
@@ -18164,9 +18169,6 @@ var DECLARATIONS = {
   method_definition: "method"
 };
 var DECLARATION_TYPES = Object.keys(DECLARATIONS);
-function grammarFor(path) {
-  return path.endsWith(".tsx") || path.endsWith(".jsx") ? "tsx" : "typescript";
-}
 var SPACE_CLASS = "[ \\t\\n\\r\\f\\v]";
 var ABSTRACT_PROPERTY = new RegExp(`\\babstract(${SPACE_CLASS}*\\??${SPACE_CLASS}*:)`, "g");
 var EXPORT_TYPE_STAR = new RegExp(`(\\bexport${SPACE_CLASS}+)type(${SPACE_CLASS}*\\*)`, "g");
@@ -18208,13 +18210,60 @@ function anchorOf(node) {
     target = target.parent;
   return target;
 }
-function leadingDoc(anchor, text) {
-  const prev = anchor.previousSibling;
+var DIRECTIVE = new RegExp(`^//${SPACE_CLASS}*(?:eslint-(?:disable|enable)(?:-next-line|-line)?|@ts-(?:ignore|expect-error|nocheck|check)|` + "prettier-ignore|biome-ignore|oxlint-disable|deno-lint-ignore|tslint:(?:disable|enable)|" + `(?:istanbul|c8|v8)${SPACE_CLASS}+ignore)(?![\\w-])`);
+function isDirective(node, text) {
+  return node.type === "comment" && DIRECTIVE.test(text(node));
+}
+function docBefore(anchor, text) {
+  let prev = anchor.previousSibling;
+  while (prev && isDirective(prev, text))
+    prev = prev.previousSibling;
   if (prev?.type !== "comment")
     return "";
   const comment = text(prev);
   return comment.startsWith("/**") ? comment : "";
 }
+function stubAnchor(anchor, source, text) {
+  let first = anchor;
+  for (let prev = anchor.previousSibling;prev && isDirective(prev, text); ) {
+    if (prev.endPosition.row + 1 < first.startPosition.row)
+      break;
+    const lineStart = source.lastIndexOf(`
+`, prev.startIndex - 1) + 1;
+    if (source.slice(lineStart, prev.startIndex).trim() !== "")
+      break;
+    first = prev;
+    prev = prev.previousSibling;
+  }
+  return first;
+}
+var SIGNATURES = new Set(["function_signature", "method_signature"]);
+function signatureName(sibling, text) {
+  const inner = sibling.type === "export_statement" ? sibling.childForFieldName("declaration") : sibling;
+  if (!inner || !SIGNATURES.has(inner.type))
+    return null;
+  const name2 = inner.childForFieldName("name");
+  return name2 ? text(name2) : null;
+}
+function leadingDoc(anchor, node, text) {
+  const own = docBefore(anchor, text);
+  if (own || node.type !== "function_declaration" && node.type !== "method_definition") {
+    return own;
+  }
+  const name2 = node.childForFieldName("name");
+  if (!name2)
+    return "";
+  const implementation = text(name2);
+  let first = null;
+  for (let sibling = anchor.previousSibling;sibling; sibling = sibling.previousSibling) {
+    if (sibling.type === "comment" || sibling.type === ";")
+      continue;
+    if (signatureName(sibling, text) !== implementation)
+      break;
+    first = sibling;
+  }
+  return first ? docBefore(first, text) : "";
+}
 function isExported2(node) {
   let parent = node.parent;
   while (parent) {
@@ -18240,8 +18289,53 @@ function proseOfComment(doc) {
   return proseOf(lines.join(`
 `));
 }
+var JSX_PARENTS = new Set(["jsx_element", "jsx_fragment"]);
+var MAX_REPAIRS = 16;
+var IMPORT_CALL = new RegExp(`\\bimport${SPACE_CLASS}*\\(${SPACE_CLASS}*(?:"[^"\\n]*"|'[^'\\n]*')${SPACE_CLASS}*\\)`, "g");
+function blankImportCalls(text) {
+  return text.replace(IMPORT_CALL, (call) => {
+    let name2 = true;
+    let out2 = "";
+    for (const ch of call) {
+      if (/\s/u.test(ch)) {
+        name2 = false;
+        out2 += ch;
+      } else {
+        out2 += (name2 ? "_" : " ").repeat(ch.length);
+      }
+    }
+    return out2;
+  });
+}
+function parseSource(parser, text) {
+  let current = sanitise(text);
+  let tree = parser.parse(current);
+  let importsBlanked = false;
+  for (let pass = 0;tree?.rootNode.hasError && pass < MAX_REPAIRS; pass++) {
+    const marks = [];
+    for (const node of tree.rootNode.descendantsOfType("ERROR")) {
+      const start2 = node.startIndex;
+      if (current[start2] === "&" && node.parent && JSX_PARENTS.has(node.parent.type)) {
+        marks.push(start2);
+      }
+    }
+    let next = current;
+    for (const at of marks)
+      next = `${next.slice(0, at)} ${next.slice(at + 1)}`;
+    if (!importsBlanked) {
+      importsBlanked = true;
+      next = blankImportCalls(next);
+    }
+    if (next === current)
+      break;
+    tree.delete();
+    current = next;
+    tree = parser.parse(current);
+  }
+  return tree;
+}
 function parsesAsTypeScript(path, text) {
-  const tree = parserFor(grammarFor(path)).parse(sanitise(text.replace(/^\uFEFF/, "")));
+  const tree = parseSource(parserFor(grammarFor(path)), text.replace(/^\uFEFF/, ""));
   if (!tree)
     return false;
   try {
@@ -18254,7 +18348,7 @@ async function analyseTypeScript(path, source) {
   const report = newReport(path, "typescript");
   const grammar = grammarFor(path);
   await loadGrammar(grammar);
-  const tree = parserFor(grammar).parse(sanitise(source));
+  const tree = parseSource(parserFor(grammar), source);
   if (!tree) {
     report.error = "parse error (the parser returned no tree)";
     return report;
@@ -18268,7 +18362,8 @@ async function analyseTypeScript(path, source) {
     for (const node of tree.rootNode.descendantsOfType(DECLARATION_TYPES)) {
       const kind = DECLARATIONS[node.type];
       const anchor = anchorOf(node);
-      const doc = leadingDoc(anchor, text);
+      const lead = stubAnchor(anchor, source, text);
+      const doc = leadingDoc(anchor, node, text);
       const dialect = dialectOf(doc);
       const typeLike = kind === "class" || kind === "interface" || kind === "type";
       const line = node.startPosition.row + 1;
@@ -18276,8 +18371,8 @@ async function analyseTypeScript(path, source) {
       const sym = {
         file: path,
         line,
-        anchorLine: anchor.startPosition.row + 1,
-        anchorColumn: anchor.startPosition.column,
+        anchorLine: lead.startPosition.row + 1,
+        anchorColumn: lead.startPosition.column,
         name: nameNode ? text(nameNode) : "<anonymous>",
         kind,
         exported: isExported2(node),

package/package.json

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