@phuc1403/musketeer 0.12.0 → 0.14.0

package/template/.claude/skills/logical-components/scripts/lib/read-json-input.cjs

@@ -0,0 +1,109 @@
+'use strict';
+
+// Reads and validates the JSON files passed between the skill's steps.
+// Anything malformed raises InputError, which every CLI maps to exit code 2.
+
+const fs = require('fs');
+const path = require('path');
+
+class InputError extends Error {}
+
+const ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function readJson(file, label) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new InputError(`cannot read ${label} ${file}: ${error.message}`);
+  }
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+const byId = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+// Repo-relative folder path in posix form; rejects anything escaping the repo.
+function normalizeRepoPath(raw) {
+  const p = path.posix.normalize(String(raw).replace(/\\/g, '/')).replace(/\/+$/, '');
+  if (!p || p === '.' || p.startsWith('../') || p === '..' || p.startsWith('/') || /^[A-Za-z]:/.test(p)) return null;
+  return p;
+}
+
+function fail(label, message) {
+  throw new InputError(`invalid ${label}: ${message}`);
+}
+
+// Validates structure.json and returns it normalised: posix paths, sorted.
+function loadStructure(file) {
+  const raw = readJson(file, 'structure');
+  if (!raw || !Array.isArray(raw.modules) || !Array.isArray(raw.components)) fail('structure', 'needs modules and components arrays');
+  const modules = raw.modules.map((m) => {
+    if (!m || !ID.test(m.id) || typeof m.name !== 'string' || !m.name.trim()) fail('structure', `bad module ${JSON.stringify(m)}`);
+    return { id: m.id, name: m.name };
+  }).sort(byId);
+  const moduleIds = new Set(modules.map((m) => m.id));
+  const ids = new Set();
+  const owners = [];
+  const components = raw.components.map((c) => {
+    if (!c || !ID.test(c.id)) fail('structure', `component id must be kebab-case: ${JSON.stringify(c && c.id)}`);
+    if (ids.has(c.id)) fail('structure', `duplicate component id ${c.id}`);
+    ids.add(c.id);
+    if (typeof c.name !== 'string' || !c.name.trim()) fail('structure', `component ${c.id} needs a name`);
+    const module = c.module === undefined ? null : c.module;
+    if (module !== null && !moduleIds.has(module)) fail('structure', `component ${c.id} names unknown module ${module}`);
+    if (!Array.isArray(c.paths) || c.paths.length === 0) fail('structure', `component ${c.id} needs paths`);
+    const paths = [...new Set(c.paths.map((p) => {
+      const normalized = normalizeRepoPath(p);
+      if (!normalized) fail('structure', `component ${c.id} has a path outside the repo: ${p}`);
+      return normalized;
+    }))].sort();
+    for (const p of paths) owners.push({ id: c.id, path: p });
+    return { id: c.id, name: c.name, module, paths };
+  }).sort(byId);
+  // Compared case-insensitively: on Windows and macOS `src/Bids` and `src/bids` are one folder.
+  for (const a of owners) {
+    for (const b of owners) {
+      const pa = a.path.toLowerCase();
+      const pb = b.path.toLowerCase();
+      if (a !== b && (pa === pb || pa.startsWith(`${pb}/`))) {
+        fail('structure', `path ${a.path} (${a.id}) overlaps ${b.path} (${b.id})`);
+      }
+    }
+  }
+  return { modules, components };
+}
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+// symbols.json must come from the same structure: every component indexed.
+function loadSymbols(file, structure) {
+  const raw = readJson(file, 'symbols');
+  if (!isObject(raw) || !isObject(raw.symbols) || !isObject(raw.byComponent) || !isObject(raw.fingerprints)) {
+    fail('symbols', 'needs symbols, byComponent and fingerprints objects');
+  }
+  for (const c of structure.components) {
+    if (!Array.isArray(raw.byComponent[c.id]) || typeof raw.fingerprints[c.id] !== 'string') {
+      fail('symbols', `no entry for component ${c.id}; re-run index-declared-symbols.cjs with this structure`);
+    }
+  }
+  return raw;
+}
+
+// The previously written docs/logical-components.json, checked enough to reuse.
+function loadPreviousModel(file) {
+  const raw = readJson(file, 'previous model');
+  const valid = isObject(raw) && raw.version === 1 && Array.isArray(raw.components) && raw.components.every((c) =>
+    isObject(c) && typeof c.id === 'string' && Array.isArray(c.paths) && Array.isArray(c.declaredSymbols));
+  if (!valid) fail('previous model', `${file} is not a version 1 logical-components model`);
+  return raw;
+}
+
+// Bad input or a file system that changed under the run (a folder deleted or
+// unreadable mid-walk): reported on stderr with exit 2, never as a stack trace.
+const FS_CODES = new Set(['ENOENT', 'EACCES', 'EPERM', 'ENOTDIR', 'EISDIR', 'EBUSY']);
+const isInputFailure = (error) => error instanceof InputError || (error && FS_CODES.has(error.code));
+
+module.exports = { InputError, isInputFailure, readJson, writeJson, loadStructure, loadSymbols, loadPreviousModel, normalizeRepoPath, byId, isObject, ID };

package/template/.claude/skills/logical-components/scripts/lib/repo-walk.cjs

@@ -0,0 +1,61 @@
+'use strict';
+
+// Walks source files under repo folders with the exclusions every
+// logical-components script shares, so the scan, the index, the fingerprints
+// and the claim checks all see exactly the same set of files.
+
+const fs = require('fs');
+const path = require('path');
+const { languageOf } = require('./declared-symbol-patterns.cjs');
+
+// Folder names that never hold component code: tests, build output, tooling.
+const EXCLUDED_DIRS = new Set([
+  'bin', 'obj', 'node_modules', 'dist', 'build', 'out', 'target', 'test', 'tests', '__tests__', 'spec',
+  'coverage', 'vendor', 'generated', 'migrations',
+]);
+const TEST_FILE = [/\.(test|spec)\.[^.]+$/i, /_test\.go$/, /^test_.*\.py$/];
+
+function isExcludedDir(name) {
+  return name.startsWith('.') || EXCLUDED_DIRS.has(name.toLowerCase()) || /\.tests?$/i.test(name);
+}
+
+function isSourceFile(name) {
+  return languageOf(name) !== null && !TEST_FILE.some((re) => re.test(name));
+}
+
+const toPosix = (p) => p.split(path.sep).join('/');
+
+function sortedEntries(absDir) {
+  return fs.readdirSync(absDir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+// Repo-relative posix paths of every source file under relDir, sorted.
+function walkSourceFiles(repo, relDir) {
+  const found = [];
+  const visit = (rel) => {
+    for (const entry of sortedEntries(path.join(repo, rel))) {
+      const child = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (!isExcludedDir(entry.name)) visit(child);
+      } else if (entry.isFile() && isSourceFile(entry.name)) {
+        found.push(child);
+      }
+    }
+  };
+  visit(relDir);
+  return found;
+}
+
+// Every source file of a component (all its paths), sorted and de-duplicated.
+function listComponentFiles(repo, paths) {
+  const files = new Set();
+  for (const p of paths) for (const f of walkSourceFiles(repo, p)) files.add(f);
+  return [...files].sort();
+}
+
+// File text with line endings normalised, so Windows checkouts read like LF ones.
+function readSource(repo, relFile) {
+  return fs.readFileSync(path.join(repo, relFile), 'utf8').replace(/\r\n?/g, '\n');
+}
+
+module.exports = { isExcludedDir, isSourceFile, toPosix, sortedEntries, walkSourceFiles, listComponentFiles, readSource };

package/template/.claude/skills/logical-components/scripts/lib/verify-claims.cjs

@@ -0,0 +1,159 @@
+'use strict';
+
+// Checks one component analyst's claims against the code. A responsibility
+// needs evidence inside the component's own files; a usage needs the target's
+// symbol to really appear near the cited line. Everything that fails is
+// returned with a precise reason, so the repair round can fix it.
+
+const fs = require('fs');
+const path = require('path');
+const { listComponentFiles, readSource } = require('./repo-walk.cjs');
+const { wholeWordPattern } = require('./declared-symbol-patterns.cjs');
+const { normalizeRepoPath } = require('./read-json-input.cjs');
+
+const MAX_TEXT = 160;
+const MAX_ACTION = 60;
+const MAX_SPAN = 60;
+const LINE_TOLERANCE = 3;
+// Markup starters, control characters, and invisible or bidi-reordering characters.
+const FORBIDDEN = /[<`[\u0000-\u0009\u000B-\u001F\u007F​-‏‪-‮⁠-⁤⁦-⁩]/;
+const UNPRINTABLE = /[\u0000-\u001F\u007F​-‏‪-‮⁠-⁤⁦-⁩]/g;
+const IMPORT_LINE = /^\s*(?:import|using|from|package|require|#include)\b|\brequire\s*\(|\bfrom\s+['"]/;
+// Inside a Go `import ( ... )` block an import is a bare quoted path, optionally aliased.
+const GO_IMPORT_ENTRY = /^\s*(?:[\w.]+\s+)?"[^"]*"\s*$/;
+
+// Single printable line for stdout and the rejected list.
+const oneLine = (value, max = 120) => String(value).replace(UNPRINTABLE, ' ').slice(0, max);
+const words = (s) => s.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+
+// True when a run of consecutive identifier segments of the import line spells
+// the folder name: `BidCapture` matches `App.Application.BidCapture` and
+// `../bid-capture/x`, but `Order` does not match `App.OrderPlacement`.
+function importNamesFolder(line, folder) {
+  const target = words(folder).join('');
+  const segments = words(line);
+  for (let start = 0; start < segments.length; start += 1) {
+    let joined = '';
+    for (let end = start; end < segments.length && joined.length < target.length; end += 1) {
+      joined += segments[end];
+      if (joined === target) return true;
+    }
+  }
+  return false;
+}
+
+function importLines(rel, lines) {
+  const isGo = rel.endsWith('.go');
+  return lines.filter((l) => IMPORT_LINE.test(l) || (isGo && GO_IMPORT_ENTRY.test(l)));
+}
+
+function plainTextProblem(value, label, max) {
+  if (typeof value !== 'string' || !value.trim()) return `${label} is empty`;
+  if (/[\r\n]/.test(value)) return `${label} contains a line break`;
+  if (value.length > max) return `${label} is longer than ${max} characters`;
+  if (FORBIDDEN.test(value)) return `${label} contains a forbidden character (<, backtick, [, control or invisible)`;
+  return null;
+}
+
+const isLine = (n) => Number.isInteger(n) && n >= 1;
+
+function createVerifier(repo, structure, symbols) {
+  const components = new Map(structure.components.map((c) => [c.id, c]));
+  const fileSets = new Map();
+  const fileLines = new Map();
+
+  const filesOf = (component) => {
+    if (!fileSets.has(component.id)) fileSets.set(component.id, new Set(listComponentFiles(repo, component.paths)));
+    return fileSets.get(component.id);
+  };
+  const linesOf = (rel) => {
+    if (!fileLines.has(rel)) {
+      const lines = readSource(repo, rel).split('\n');
+      if (lines.length > 1 && lines[lines.length - 1] === '') lines.pop();
+      fileLines.set(rel, lines);
+    }
+    return fileLines.get(rel);
+  };
+
+  // Returns { rel } for a scanned source file of the component, else { problem }.
+  function ownFile(component, file) {
+    const rel = typeof file === 'string' ? normalizeRepoPath(file) : null;
+    if (!rel || !component.paths.some((p) => rel === p || rel.startsWith(`${p}/`))) {
+      return { problem: `${oneLine(file)} is outside the component paths` };
+    }
+    if (!fs.existsSync(path.join(repo, rel))) return { problem: `${rel} does not exist` };
+    if (!filesOf(component).has(rel)) return { problem: `${rel} is not a scanned source file` };
+    return { rel };
+  }
+
+  function evidenceProblem(component, evidence) {
+    const lines = evidence && evidence.lines;
+    if (!evidence || !Array.isArray(lines) || lines.length !== 2 || !isLine(lines[0]) || !isLine(lines[1]) || lines[1] < lines[0]) {
+      return { problem: 'evidence must be { file, lines: [start, end] }' };
+    }
+    const { rel, problem } = ownFile(component, evidence.file);
+    if (problem) return { problem };
+    const [start, end] = lines;
+    if (end - start + 1 > MAX_SPAN) return { problem: `lines ${start}-${end} span more than ${MAX_SPAN} lines` };
+    const count = linesOf(rel).length;
+    if (end > count) return { problem: `lines ${start}-${end} are outside ${rel} (${count} lines)` };
+    return { value: { file: rel, lines: [start, end] } };
+  }
+
+  function verifyResponsibility(component, claim) {
+    const text = claim && claim.text;
+    const label = oneLine(text === undefined ? '(no text)' : text);
+    const textProblem = plainTextProblem(text, 'text', MAX_TEXT);
+    if (textProblem) return { claim: label, reason: textProblem };
+    const evidence = [];
+    const problems = [];
+    for (const item of Array.isArray(claim.evidence) ? claim.evidence : []) {
+      const checked = evidenceProblem(component, item);
+      if (checked.problem) problems.push(checked.problem);
+      else evidence.push(checked.value);
+    }
+    if (!evidence.length) return { claim: label, reason: `no valid evidence: ${problems.join('; ') || 'none given'}` };
+    return { value: { text: text.trim(), evidence } };
+  }
+
+  // Nearest line (earlier wins a tie) within the tolerance that names the symbol.
+  function findSymbolLine(rel, symbol, cited) {
+    const lines = linesOf(rel);
+    const pattern = wholeWordPattern([symbol]);
+    for (let distance = 0; distance <= LINE_TOLERANCE; distance += 1) {
+      for (const n of distance === 0 ? [cited] : [cited - distance, cited + distance]) {
+        if (n >= 1 && n <= lines.length && pattern.test(lines[n - 1])) return n;
+      }
+    }
+    return null;
+  }
+
+  function verifyUsage(component, usage) {
+    const { target, symbol, file, line, action } = usage || {};
+    const label = oneLine(`${symbol} -> ${target}`);
+    const reject = (reason) => ({ claim: label, reason });
+    if (target === component.id) return reject(`target ${target} is the component itself`);
+    if (typeof target !== 'string' || !components.has(target)) return reject(`unknown target ${oneLine(target)}`);
+    const owners = typeof symbol === 'string' && Object.hasOwn(symbols.symbols, symbol) ? symbols.symbols[symbol] : [];
+    if (!owners.includes(target)) return reject(`symbol ${oneLine(symbol)} is not declared by ${target}`);
+    const { rel, problem } = ownFile(component, file);
+    if (problem) return reject(problem);
+    if (!isLine(line)) return reject('line must be a positive integer');
+    const actionProblem = plainTextProblem(action, 'action', MAX_ACTION);
+    if (actionProblem) return reject(actionProblem);
+    const found = findSymbolLine(rel, symbol, line);
+    if (found === null) return reject(`symbol ${symbol} not found within ${LINE_TOLERANCE} lines of ${rel}:${line}`);
+    if (owners.length > 1) {
+      const folders = [...new Set(components.get(target).paths.map((p) => p.split('/').pop()))];
+      const imports = importLines(rel, linesOf(rel));
+      if (!folders.some((f) => imports.some((l) => importNamesFolder(l, f)))) {
+        return reject(`ambiguous symbol ${symbol} (declared by ${owners.join(', ')}) and ${rel} imports nothing named ${folders.join(' or ')}`);
+      }
+    }
+    return { value: { from: component.id, to: target, symbol, file: rel, line: found, action: action.trim() } };
+  }
+
+  return { verifyResponsibility, verifyUsage };
+}
+
+module.exports = { createVerifier, oneLine };

package/template/.claude/skills/logical-components/scripts/render-component-diagram-html.cjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+'use strict';
+
+// Renders docs/logical-components.json as one self-contained HTML page:
+// Mermaid component diagram, coupling and edge tables, component cards and
+// rejected claims. Same model in, byte-identical page out.
+// Usage: render-component-diagram-html.cjs --model <json> --out <html> [--repo <repo root, default cwd>]
+// Exit: 0 ok, 1 usage, 2 unreadable or invalid model (the existing page is left untouched).
+
+const fs = require('fs');
+const path = require('path');
+const { parseArgs } = require('util');
+const { InputError, isInputFailure, readJson, isObject, normalizeRepoPath, ID } = require('./lib/read-json-input.cjs');
+const { buildMermaid } = require('./lib/mermaid-graph.cjs');
+const { escapeHtml, renderCards, renderCouplingTable, renderEdgeTable, renderRejected } = require('./lib/html-sections.cjs');
+
+const TEMPLATE = path.join(__dirname, '..', 'assets', 'component-diagram-template.html');
+const USAGE = 'usage: render-component-diagram-html.cjs --model <logical-components.json> --out <page.html> [--repo <repo>]';
+
+function parse() {
+  try {
+    const { values } = parseArgs({ options: { model: { type: 'string' }, out: { type: 'string' }, repo: { type: 'string' } } });
+    if (values.model && values.out) return values;
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+  }
+  process.stderr.write(`${USAGE}\n`);
+  return process.exit(1);
+}
+
+const isCount = (n) => Number.isInteger(n) && n >= 0;
+const isLine = (n) => Number.isInteger(n) && n >= 1;
+const strings = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
+// Evidence links point into the repo only: a plain relative path, no scheme, no `..`.
+const isRepoFile = (f) => typeof f === 'string' && normalizeRepoPath(f) === f && !/^[a-z][a-z0-9+.-]*:/i.test(f);
+
+// Checks every field the renderer reads, so a hand-edited model fails loudly.
+function validateModel(model) {
+  const problem = (message) => { throw new InputError(`invalid model: ${message}`); };
+  if (!isObject(model) || model.version !== 1) problem('version must be 1');
+  if (!Array.isArray(model.modules) || !Array.isArray(model.components) || !Array.isArray(model.edges) || !Array.isArray(model.rejected)) {
+    problem('needs modules, components, edges and rejected arrays');
+  }
+  const modules = new Set();
+  for (const m of model.modules) {
+    if (!isObject(m) || !ID.test(m.id) || typeof m.name !== 'string') problem(`bad module ${JSON.stringify(m)}`);
+    modules.add(m.id);
+  }
+  const ids = new Set();
+  for (const c of model.components) {
+    if (!isObject(c) || !ID.test(c.id) || ids.has(c.id)) problem(`bad or duplicate component id ${JSON.stringify(c && c.id)}`);
+    ids.add(c.id);
+    if (typeof c.name !== 'string' || !strings(c.paths) || !(c.module === null || modules.has(c.module))) problem(`bad component ${c.id}`);
+    if (![c.ca, c.ce, c.ct].every(isCount) || !Array.isArray(c.responsibilities)) problem(`bad metrics or responsibilities in ${c.id}`);
+    for (const r of c.responsibilities) {
+      if (!isObject(r) || typeof r.text !== 'string' || !Array.isArray(r.evidence)
+        || !r.evidence.every((e) => isObject(e) && isRepoFile(e.file) && Array.isArray(e.lines) && e.lines.every(isLine))) {
+        problem(`bad responsibility in ${c.id}`);
+      }
+    }
+  }
+  for (const e of model.edges) {
+    if (!isObject(e) || !ids.has(e.from) || !ids.has(e.to) || !strings(e.labels) || !Array.isArray(e.evidence)
+      || !e.evidence.every((ev) => isObject(ev) && isRepoFile(ev.file) && isLine(ev.line))) {
+      problem(`bad edge ${JSON.stringify(e && [e.from, e.to])}`);
+    }
+  }
+  if (!isCount(model.totalCoupling)) problem('totalCoupling must be a count');
+  if (!model.rejected.every((r) => isObject(r) && ['component', 'kind', 'claim', 'reason'].every((k) => typeof r[k] === 'string'))) {
+    problem('bad rejected entry');
+  }
+}
+
+function renderPage(model, fileBase) {
+  const parts = {
+    SUMMARY: `<strong>${model.components.length} components · ${model.edges.length} edges</strong> · `
+      + `<strong>Total system coupling = ${model.totalCoupling}</strong>`,
+    MERMAID: escapeHtml(buildMermaid(model)),
+    COUPLING: renderCouplingTable(model),
+    EDGES: renderEdgeTable(model, fileBase),
+    CARDS: renderCards(model, fileBase),
+    REJECTED: renderRejected(model),
+  };
+  const template = fs.readFileSync(TEMPLATE, 'utf8').replace(/\r\n/g, '\n');
+  return template.replace(/\{\{([A-Z]+)\}\}/g, (match, key) => {
+    if (!Object.hasOwn(parts, key)) throw new Error(`template has unknown placeholder ${match}`);
+    return parts[key];
+  });
+}
+
+function main() {
+  const args = parse();
+  let html;
+  try {
+    const model = readJson(args.model, 'model');
+    validateModel(model);
+    const outDir = path.dirname(path.resolve(args.out));
+    const fileBase = path.relative(outDir, path.resolve(args.repo || process.cwd())).split(path.sep).join('/');
+    html = renderPage(model, fileBase);
+  } catch (error) {
+    if (!isInputFailure(error)) throw error;
+    process.stderr.write(`${error.message}\n`);
+    process.exit(2);
+  }
+  fs.mkdirSync(path.dirname(path.resolve(args.out)), { recursive: true });
+  const temp = `${args.out}.tmp-${process.pid}`;
+  fs.writeFileSync(temp, html);
+  fs.renameSync(temp, args.out);
+  process.stdout.write(`wrote ${args.out}\n`);
+}
+
+main();

package/template/.claude/skills/logical-components/scripts/scan-folder-tree.cjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+'use strict';
+
+// Prints the repo's folder tree with source-file counts and languages, so the
+// main agent can decide which folder level holds the logical components.
+// Usage: scan-folder-tree.cjs <repo> [--depth 4]
+// Exit: 0 ok, 1 usage.
+
+const fs = require('fs');
+const path = require('path');
+const { parseArgs } = require('util');
+const { isExcludedDir, isSourceFile, sortedEntries } = require('./lib/repo-walk.cjs');
+const { languageOf, LABELS } = require('./lib/declared-symbol-patterns.cjs');
+
+// Build output and dependencies are skipped silently; any other skipped folder
+// (tests, generated code, migrations) is named so the gate can list it.
+const SILENT = new Set(['bin', 'obj', 'node_modules', 'dist', 'build', 'out', 'target', 'coverage', 'vendor']);
+
+function hasSourceFile(absDir) {
+  return sortedEntries(absDir).some((e) => (e.isDirectory() ? hasSourceFile(path.join(absDir, e.name)) : languageOf(e.name) !== null));
+}
+
+function usage(message) {
+  process.stderr.write(`${message}\nusage: scan-folder-tree.cjs <repo> [--depth 4]\n`);
+  process.exit(1);
+}
+
+// Folder node with recursive source-file count and per-language counts.
+// `excluded` collects repo-relative paths of skipped folders worth naming.
+function scan(absDir, name, rel, excluded) {
+  const node = { name, files: 0, languages: {}, children: [] };
+  for (const entry of sortedEntries(absDir)) {
+    if (entry.isDirectory()) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (isExcludedDir(entry.name)) {
+        const silent = entry.name.startsWith('.') || SILENT.has(entry.name.toLowerCase());
+        if (!silent && hasSourceFile(path.join(absDir, entry.name))) excluded.push(`${childRel}/`);
+        continue;
+      }
+      const child = scan(path.join(absDir, entry.name), entry.name, childRel, excluded);
+      if (child.files === 0) continue;
+      node.children.push(child);
+      node.files += child.files;
+      for (const [lang, n] of Object.entries(child.languages)) node.languages[lang] = (node.languages[lang] || 0) + n;
+    } else if (entry.isFile() && isSourceFile(entry.name)) {
+      const lang = languageOf(entry.name);
+      node.files += 1;
+      node.languages[lang] = (node.languages[lang] || 0) + 1;
+    }
+  }
+  return node;
+}
+
+function describe(node) {
+  const langs = Object.keys(node.languages).sort().map((l) => `${LABELS[l]} ${node.languages[l]}`).join(', ');
+  return `${node.name}/  ${node.files} file${node.files === 1 ? '' : 's'} (${langs})`;
+}
+
+function render(node, depth, maxDepth, lines) {
+  lines.push(`${'  '.repeat(depth)}${describe(node)}`);
+  if (depth >= maxDepth) return;
+  for (const child of node.children) render(child, depth + 1, maxDepth, lines);
+}
+
+function main() {
+  let parsed;
+  try {
+    parsed = parseArgs({ allowPositionals: true, options: { depth: { type: 'string', default: '4' } } });
+  } catch (error) {
+    usage(error.message);
+  }
+  const [repo] = parsed.positionals;
+  if (!repo) usage('missing <repo>');
+  const depth = Number(parsed.values.depth);
+  if (!Number.isInteger(depth) || depth < 1) usage(`--depth must be a positive integer: ${parsed.values.depth}`);
+  const abs = path.resolve(repo);
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) usage(`not a directory: ${repo}`);
+
+  const excluded = [];
+  const root = scan(abs, path.basename(abs), '', excluded);
+  const lines = [];
+  if (root.files === 0) lines.push(`${root.name}/  no source files found`);
+  else render(root, 0, depth, lines);
+  lines.push(`excluded: ${excluded.length ? excluded.sort().join(', ') : 'none'}`);
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+main();

package/template/.claude/skills/logical-components/scripts/select-stale-components.cjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+'use strict';
+
+// Decides which components need a fresh analyst agent on this run and copies
+// the stored analysis of every other component out of the previous model.
+// Usage: select-stale-components.cjs --repo <repo> --structure <structure.json> --symbols <symbols.json>
+//          --previous <docs/logical-components.json> --analysis <dir> [--full]
+// Exit: 0 ok, 1 usage, 2 unreadable input or previous model.
+
+const fs = require('fs');
+const path = require('path');
+const { parseArgs } = require('util');
+const { listComponentFiles, readSource } = require('./lib/repo-walk.cjs');
+const { wholeWordPattern } = require('./lib/declared-symbol-patterns.cjs');
+const { InputError, isInputFailure, loadStructure, loadSymbols, loadPreviousModel, writeJson, isObject } = require('./lib/read-json-input.cjs');
+
+const USAGE = 'usage: select-stale-components.cjs --repo <repo> --structure <structure.json> --symbols <symbols.json> '
+  + '--previous <docs/logical-components.json> --analysis <dir> [--full]';
+
+function parse() {
+  const options = {
+    repo: { type: 'string' }, structure: { type: 'string' }, symbols: { type: 'string' },
+    previous: { type: 'string' }, analysis: { type: 'string' }, full: { type: 'boolean', default: false },
+  };
+  try {
+    const { values } = parseArgs({ options });
+    if (values.repo && values.structure && values.symbols && values.previous && values.analysis) return values;
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+  }
+  process.stderr.write(`${USAGE}\n`);
+  return process.exit(1);
+}
+
+const samePaths = (a, b) => JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
+
+// Symbols whose owners differ from the previous run: `new` when nobody declared
+// them before, `moved` when other components did. A stored usage of either may
+// now point at the wrong component or miss an edge, so components naming one re-run.
+function changedSymbols(previous, current) {
+  const ownersBefore = new Map();
+  for (const c of previous.components) {
+    for (const name of c.declaredSymbols) {
+      if (!ownersBefore.has(name)) ownersBefore.set(name, []);
+      ownersBefore.get(name).push(c.id);
+    }
+  }
+  const changed = new Map();
+  for (const name of Object.keys(current)) {
+    const before = ownersBefore.get(name);
+    if (!before) changed.set(name, 'new');
+    else if (before.sort().join(',') !== [...current[name]].sort().join(',')) changed.set(name, 'moved');
+  }
+  return changed;
+}
+
+// First changed symbol (alphabetically) that the component's code names, not counting its own.
+function changedSymbolMentioned(repo, component, changed, ownSymbols) {
+  const names = [...changed.keys()].filter((name) => !ownSymbols.includes(name));
+  if (!names.length) return null;
+  const pattern = wholeWordPattern(names, 'g');
+  const found = new Set();
+  for (const file of listComponentFiles(repo, component.paths)) {
+    for (const match of readSource(repo, file).matchAll(pattern)) found.add(match[0]);
+  }
+  if (!found.size) return null;
+  const name = [...found].sort()[0];
+  return `mentions ${changed.get(name)} symbol ${name}`;
+}
+
+function staleReason(repo, component, context) {
+  const { full, previous, symbols, changed, componentIds } = context;
+  if (full) return '--full';
+  if (!previous) return 'no previous model';
+  const before = previous.components.find((c) => c.id === component.id);
+  if (!before) return 'new component';
+  if (!samePaths(before.paths, component.paths)) return 'paths changed';
+  if (before.fingerprint !== symbols.fingerprints[component.id]) return 'content changed';
+  if (!isObject(before.analysis)) return 'no stored analysis';
+  const usages = Array.isArray(before.analysis.usages) ? before.analysis.usages : [];
+  const gone = usages.map((u) => u && u.target).find((t) => typeof t === 'string' && t !== component.id && !componentIds.has(t));
+  if (gone) return `uses removed component ${gone}`;
+  return changedSymbolMentioned(repo, component, changed, symbols.byComponent[component.id]);
+}
+
+function main() {
+  const args = parse();
+  const repo = path.resolve(args.repo);
+  try {
+    const structure = loadStructure(args.structure);
+    const symbols = loadSymbols(args.symbols, structure);
+    let previous = null;
+    if (!args.full && fs.existsSync(args.previous)) {
+      try {
+        previous = loadPreviousModel(args.previous);
+      } catch (error) {
+        throw new InputError(`${error.message}\nre-run with --full to analyse every component from scratch`);
+      }
+    }
+    const context = {
+      full: args.full,
+      previous,
+      symbols,
+      changed: previous ? changedSymbols(previous, symbols.symbols) : new Map(),
+      componentIds: new Set(structure.components.map((c) => c.id)),
+    };
+
+    fs.mkdirSync(args.analysis, { recursive: true });
+    const lines = [];
+    for (const component of structure.components) {
+      const out = path.join(args.analysis, `${component.id}.json`);
+      const reason = staleReason(repo, component, context);
+      if (reason) {
+        fs.rmSync(out, { force: true });
+        lines.push(`stale ${component.id} ${reason}`);
+      } else {
+        writeJson(out, previous.components.find((c) => c.id === component.id).analysis);
+      }
+    }
+    lines.push(`${lines.length} of ${structure.components.length} components stale`);
+    process.stdout.write(`${lines.join('\n')}\n`);
+  } catch (error) {
+    if (!isInputFailure(error)) throw error;
+    process.stderr.write(`${error.message}\n`);
+    process.exit(2);
+  }
+}
+
+main();