@danielsimonjr/repo-tools 2.2.0 → 2.2.2

package/CHANGELOG.md

@@ -6,6 +6,66 @@ All notable changes to this project are recorded in this file. The format follow
 
 ## [Unreleased]
 
+## [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
+
+- `repo-tools map` finds the entry roots of a package that has no `src/` tree. A `bin`, `main`,
+  `module` or `exports` entry that names a tracked source file (`bin/tool.mjs`, `./lib/index.js`)
+  is now a root. Before, only entries that map into `src/` counted. A package with `bin/` and `lib/`
+  and no `src/` showed `entryRoots` 0, and its `unused-analysis.md` listed every file as an orphan or
+  test-only. A package with a `src/` tree resolves as before, so a thin launcher that fails the scan
+  still warns. The warning text no longer says "under src/".
+
 ## [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

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.0.
+Status: version 2.2.2.
 
 - `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.0):
+[GitHub release](https://github.com/danielsimonjr/repo-tools/releases/tag/v2.2.2):
 
 | Platform | File |
 |---|---|

package/dist/cli.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@danielsimonjr/repo-tools",
-  version: "2.2.0",
+  version: "2.2.2",
   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",
@@ -12324,6 +12324,13 @@ function launcherEntry(root, spec, known) {
   }
   return null;
 }
+function declaredSource(spec, known) {
+  for (const path of known)
+    if (path.startsWith("src/"))
+      return null;
+  const posix = lstripDotSlash(spec.replaceAll("\\", "/"));
+  return known.has(posix) ? posix : null;
+}
 var isObject2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function packageJsonRoots(root, known) {
   let pkg;
@@ -12351,9 +12358,9 @@ function packageJsonRoots(root, known) {
   for (const spec of raw) {
     if (spec.endsWith(".json"))
       continue;
-    const mapped = mapDistToSrc(spec, known) ?? launcherEntry(root, spec, known);
+    const mapped = mapDistToSrc(spec, known) ?? launcherEntry(root, spec, known) ?? declaredSource(spec, known);
     if (mapped === null) {
-      warnings.push(`package.json entry ${pyRepr(spec)} did not resolve to a known source file under src/ -- ` + "ignored; if no other declared entry resolves either, the entry-point root falls back to " + "a conventional src/index.* file instead");
+      warnings.push(`package.json entry ${pyRepr(spec)} did not resolve to a known source file -- ` + "ignored; if no other declared entry resolves either, the entry-point root falls back to " + "a conventional src/index.* file instead");
       continue;
     }
     if (!roots.includes(mapped))
@@ -18201,13 +18208,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) {
@@ -18233,8 +18287,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 {
@@ -18247,7 +18346,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;
@@ -18261,7 +18360,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;
@@ -18269,8 +18369,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.0",
+  "version": "2.2.2",
   "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",