@phuc1403/musketeer 0.12.0 → 0.14.0

package/template/.claude/skills/logical-components/references/component-level-detection.md

@@ -0,0 +1,95 @@
+# Component level detection
+
+How to turn a folder tree into modules and components. The main agent decides; the user confirms before any
+analysis runs. Works for any language: judge folder names and contents, not syntax.
+
+## Classify every folder
+
+| Kind | Recognise it by | What to do |
+|---|---|---|
+| **Layer** | A technical name: Controllers, Handlers, Services, Repositories, Models, Entities, Dtos, Api, Web, Application, Domain, Infrastructure, Persistence, Data, Core, Adapters, Ports, UseCases, `App.Application`-style project names | Look inside it. Its children are the candidates. |
+| **Module** | A folder whose children are components or layers, named after a business area: `Modules/*`, bounded contexts, `Auctions`, `Billing` | Becomes a module (a subgraph). Components inside get its id. |
+| **Component** | A feature folder whose files together serve one functional purpose: `BidCapture`, `order-placement`, `pricing` | One component = the whole subtree. Do not look deeper. |
+| **Container** | A folder that only groups others: source roots (`src`, `lib`, `app`, `packages`), `Modules`, `Features`, `Services` holding service folders | Look through it; never a component or module. Not listed at the gate. |
+| **Excluded** | Tests, build output, generated or tooling code, composition roots | Never a component. |
+
+Rules:
+
+- **Stop at the first component level.** Subfolders of a component (`BidCapture/Validation`) belong to it.
+- **Merge across layers by folder name.** Same feature folder under several layers → one component, several paths.
+  Compare names case- and separator-insensitively: `BidCapture`, `bid-capture`, `bid_capture` match.
+- **A layer with files but no feature subfolders** (a `Controllers` folder of mixed controllers, an `Api`
+  project) becomes one component for the whole layer, named after its role: `Http Api`, `Cli`, `Message Consumers`.
+  Its path is the outermost folder of that layer (`src/App.Api`, not `src/App.Api/Controllers`), so files added
+  beside `Controllers` later still belong to it.
+- **Composition roots** (`Program.cs`, `main.go`, `Host`, `Startup`, DI wiring only) are not components.
+- **Shared / Common** folders with real code are components like any other.
+- **Single-folder repos** (all code in `src/`) → group by file name prefix only if obvious; otherwise one
+  component per top-level folder and say so at the gate.
+- **Names:** the folder's words in Title Case when they already say what the code does (`BidderSignOn` →
+  `Bidder Sign-on`); id is kebab-case and unique (`bidder-sign-on`). Rename only technical or vague names
+  (`Core`, `Common`, entity-trap names like `OrderManager`) when the code clearly does something narrower, and
+  mention a vague name you kept at the gate.
+- **Low cohesion:** when a component's files do unrelated jobs, keep the folder as one component and say so in
+  its gate line; the analysis will list both jobs.
+- `module` is `null` when the repo has no module level, and `modules` is then `[]`.
+- **Excluded line at the gate:** list the excluded folders the scan reports on its `excluded:` line and any
+  composition roots you left out, each with its reason; write `Excluded: none` when there are none.
+
+Excluded folders (the scripts skip them too): `bin`, `obj`, `node_modules`, `dist`, `build`, `out`, `target`,
+`.git`, `test`, `tests`, `__tests__`, `spec`, `*.Tests`, `*.Test`, `coverage`, `vendor`, `generated`,
+`migrations`, and test files (`*.test.*`, `*.spec.*`, `*_test.go`, `test_*.py`).
+
+## structure.json
+
+```json
+{ "modules": [{ "id": "auctions", "name": "Auctions" }],
+  "components": [{ "id": "bid-capture", "name": "Bid Capture", "module": "auctions",
+                   "paths": ["src/Modules/Auctions/BidCapture"] }] }
+```
+
+Paths are repo-relative with forward slashes. Every path must exist.
+
+## Worked examples
+
+### Flat feature folders (TypeScript)
+
+```
+src/order-placement  src/inventory-management  src/item-pricing  src/supplier-ordering  src/email-notification
+tests/
+```
+
+No layers, no modules: five components, `module: null`, one path each. `tests/` excluded.
+
+### Modular monolith (C#)
+
+```
+src/Modules/Auctions/{BidCapture, BidTracker, LiveAuctionSession}
+src/Modules/Bidders/{BidderRegistration, BidderSignOn}
+src/Host/Program.cs
+```
+
+`Modules` is a container; `Auctions` and `Bidders` are modules; their children are components.
+`Host` is a composition root, excluded.
+
+### Clean Architecture (C#)
+
+```
+src/App.Application/{BidCapture, TripViewer}
+src/App.Infrastructure/{BidCapture, VideoStreamer}
+src/App.Api/Controllers/{BidsController.cs, TripsController.cs}
+tests/App.Tests/
+```
+
+`App.Application`, `App.Infrastructure`, `App.Api` are layers. `BidCapture` exists in two layers → one
+`bid-capture` component with both paths. `App.Api` has no feature folders → one `http-api` component
+(`Http Api`). Result: `bid-capture`, `http-api`, `trip-viewer`, `video-streamer`, no modules.
+
+## Counter-examples
+
+- `src/Services/OrderService.cs, PaymentService.cs` — `Services` is a layer of mixed files. If the other layers
+  are organised per feature, merge each file's feature into it; otherwise make `Services` one component and say
+  the code is organised by layer, not by feature.
+- `src/Domain/Order/`, `src/Domain/Customer/` — entity folders. Still components (folder = component), but
+  mention the entity trap at the gate if their code mixes unrelated jobs.
+- A module with a single folder inside → that folder is the component; keep the module.

package/template/.claude/skills/logical-components/references/logical-component-concepts.md

@@ -0,0 +1,92 @@
+# Logical component concepts
+
+What the skill measures, and the words it uses. Read before deciding components or writing an analysis.
+
+## Logical vs physical architecture
+
+| | Logical architecture | Physical architecture |
+|---|---|---|
+| Focus | Functional building blocks and how they interact | Tangible implementation |
+| Answers | What the system does | How the system is built |
+| Includes | Logical components (`Bidder Registration`, `Auction Search`) | Services, databases, protocols, UI, API gateways |
+| Ignores | Services, databases, protocols, hardware | — (it groups and implements logical components) |
+
+This skill recovers the **logical** architecture of an existing codebase. It does not draw deployment units,
+databases or classes.
+
+## Component
+
+A **logical component** is a building block that does one functional job of the system. In code it is a
+**folder subtree**: every source file under the folder (recursively) belongs to it. When layers split one feature
+across several folders (`Application/BidCapture`, `Infrastructure/BidCapture`), those folders are **one component
+with several paths**. Classes are never nodes; a component's responsibilities are the combined responsibilities of
+its code.
+
+A good component name says exactly what it does: `Bid Capture`, `Item Pricing`, `Video Streamer`. A third-party
+wrapper (a video streaming client) is still a component.
+
+## Responsibility
+
+A **responsibility** is a short, verb-first statement of something the component does for the system, written for
+the folder as a whole, not per class:
+
+- Good: `Receive bids from online bidders`, `Raise an item price when its stock runs low`.
+- Bad: `BidReceiver class`, `Has a Receive method`, `Handles bids` (vague), one line per file.
+
+A component usually has 3–7 responsibilities. Each one cites evidence: the file and line range that implements it.
+
+## Cohesion and the entity trap
+
+**Cohesion** is how closely related a component's responsibilities are. High cohesion: they all serve one purpose.
+Low cohesion: a dumping ground of unrelated jobs, often a `Utility` component.
+
+The **entity trap** is grouping every action on one entity into one component (`Bid Manager` accepts bids, picks
+winners, audits, notifies, reports). The name is vague and the component bloats. Red-flag words in a name:
+Manager, Supervisor, Handler, Controller, Agent, Service, Engine, Mediator, Coordinator, Orchestrator, Processor,
+Utility, Worker. Not a hard rule: `Reference Data Manager` is specific enough. Name components after what they do.
+
+## Coupling
+
+**Coupling** is how much components know about and rely on each other. Arrow `A → B` means **A knows about B**:
+A's code references a symbol B declares. Any reference counts:
+
+- calling a function or method of B;
+- constructing B's type;
+- using B's type as a field, parameter, return or generic argument (DTOs included);
+- inheriting from or implementing B's class or interface.
+
+The arrow label is what A asks B to do, as a verb phrase: `Decrement inventory`, `Notify the customer`.
+A component referencing its own symbols is not coupling.
+
+- **Afferent coupling (CA)**: number of distinct components that point **to** this one (incoming).
+  `Bidder Profile`, used by `Auction Registration` and `Automatic Payment`, has CA = 2.
+- **Efferent coupling (CE)**: number of distinct components this one points **to** (outgoing).
+  `Bid Capture` sends to `Bid Streamer` and `Bid Tracker`: CE = 2.
+- **Total coupling (CT)** = CA + CE per component. **Total system coupling** = Σ CT = 2 × number of edges.
+
+Several references from A to B are one edge with several labels; CA and CE count components, not references.
+
+## Law of Demeter
+
+A component should know as little as possible about what other components do. The more it knows about what must
+happen elsewhere, the more coupled it is.
+
+Order Placement example, external "place an order" actor left out:
+
+- **Before:** Order Placement → Inventory Management, Item Pricing, Supplier Ordering, Email Notification.
+  Order Placement CE = 4; total system coupling 8.
+- **After:** Order Placement → Inventory Management (`Decrement inventory`), Email Notification
+  (`Notify the customer`); Inventory Management → Item Pricing (`Stock low? Raise the price`), Supplier Ordering
+  (`Stock low? Order more`). Order Placement CE = 2, Inventory Management CA = 1, CE = 2, CT = 3; total still 8.
+
+The knowledge was not removed, it moved to the component most responsible for it.
+
+## Trade-off
+
+| | Tightly coupled | Loosely coupled |
+|---|---|---|
+| Workflow | One hub knows every step | Each component knows only the next step |
+| Benefit | Easy to read the whole flow in one place | A change rarely breaks other components |
+| Drawback | A change anywhere can break the hub | The full flow is spread across components |
+
+The skill reports numbers; it does not judge a design good or bad.

package/template/.claude/skills/logical-components/scripts/build-component-model.cjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+'use strict';
+
+// Merges the confirmed structure, the symbol index and every component
+// analysis into docs/logical-components.json. This is the trust boundary:
+// claims become facts only after verify-claims accepts them.
+// Usage: build-component-model.cjs --repo <repo> --structure <structure.json> --symbols <symbols.json>
+//          --analysis <dir> --out <docs/logical-components.json>
+// Exit: 0 ok, 1 usage, 2 unreadable input, 3 missing analysis.
+
+const fs = require('fs');
+const path = require('path');
+const { parseArgs } = require('util');
+const { InputError, isInputFailure, loadStructure, loadSymbols, writeJson, isObject } = require('./lib/read-json-input.cjs');
+const { createVerifier, oneLine } = require('./lib/verify-claims.cjs');
+const { aggregateEdges, computeMetrics } = require('./lib/coupling-metrics.cjs');
+
+const USAGE = 'usage: build-component-model.cjs --repo <repo> --structure <structure.json> --symbols <symbols.json> '
+  + '--analysis <dir> --out <docs/logical-components.json>';
+
+function parse() {
+  const names = ['repo', 'structure', 'symbols', 'analysis', 'out'];
+  try {
+    const { values } = parseArgs({ options: Object.fromEntries(names.map((n) => [n, { type: 'string' }])) });
+    if (names.every((n) => values[n])) return values;
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+  }
+  process.stderr.write(`${USAGE}\n`);
+  return process.exit(1);
+}
+
+// Parsed analysis, or null with a rejection when the agent wrote something unusable.
+function readAnalysis(file, id, rejected) {
+  let analysis;
+  try {
+    analysis = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    rejected.push({ component: id, kind: 'analysis', claim: `${id}.json`, reason: oneLine(`invalid JSON: ${error.message}`) });
+    return null;
+  }
+  if (!isObject(analysis)) {
+    rejected.push({ component: id, kind: 'analysis', claim: `${id}.json`, reason: 'analysis must be a JSON object' });
+    return null;
+  }
+  return analysis;
+}
+
+const listOf = (value) => (Array.isArray(value) ? value : []);
+
+function buildModel(repo, structure, symbols, analysisDir) {
+  const verifier = createVerifier(repo, structure, symbols);
+  const rejected = [];
+  const usages = [];
+  const components = structure.components.map((component) => {
+    const id = component.id;
+    const analysis = readAnalysis(path.join(analysisDir, `${id}.json`), id, rejected);
+    const responsibilities = [];
+    for (const claim of listOf(analysis && analysis.responsibilities)) {
+      const checked = verifier.verifyResponsibility(component, claim);
+      if (checked.value) responsibilities.push(checked.value);
+      else rejected.push({ component: id, kind: 'responsibility', claim: checked.claim, reason: checked.reason });
+    }
+    for (const usage of listOf(analysis && analysis.usages)) {
+      const checked = verifier.verifyUsage(component, usage);
+      if (checked.value) usages.push(checked.value);
+      else rejected.push({ component: id, kind: 'usage', claim: checked.claim, reason: checked.reason });
+    }
+    return { component, responsibilities, analysis };
+  });
+
+  const edges = aggregateEdges(usages);
+  const { metrics, totalCoupling } = computeMetrics(structure.components.map((c) => c.id), edges);
+  return {
+    version: 1,
+    modules: structure.modules,
+    components: components.map(({ component, responsibilities, analysis }) => ({
+      id: component.id,
+      name: component.name,
+      module: component.module,
+      paths: component.paths,
+      responsibilities,
+      ...metrics[component.id],
+      fingerprint: symbols.fingerprints[component.id],
+      declaredSymbols: symbols.byComponent[component.id],
+      analysis,
+    })),
+    edges,
+    totalCoupling,
+    rejected,
+  };
+}
+
+function main() {
+  const args = parse();
+  const repo = path.resolve(args.repo);
+  let model;
+  try {
+    const structure = loadStructure(args.structure);
+    const symbols = loadSymbols(args.symbols, structure);
+    const missing = structure.components.map((c) => c.id).filter((id) => !fs.existsSync(path.join(args.analysis, `${id}.json`)));
+    if (missing.length) {
+      process.stderr.write(`missing analysis for: ${missing.join(', ')}\n`);
+      process.exit(3);
+    }
+    model = buildModel(repo, structure, symbols, args.analysis);
+  } catch (error) {
+    if (!isInputFailure(error)) throw error;
+    process.stderr.write(`${error.message}\n`);
+    process.exit(2);
+  }
+  writeJson(args.out, model);
+
+  const lines = [`components ${model.components.length}, edges ${model.edges.length}, total coupling ${model.totalCoupling}, rejected ${model.rejected.length}`];
+  for (const r of model.rejected) lines.push(`rejected ${r.component} ${r.kind}: ${r.reason} [${r.claim}]`);
+  for (const c of model.components) if (!c.responsibilities.length) lines.push(`empty ${c.id}`);
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+main();

package/template/.claude/skills/logical-components/scripts/index-declared-symbols.cjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict';
+
+// Builds symbols.json from a confirmed structure.json: which component declares
+// each top-level symbol, and a content fingerprint per component for reruns.
+// Usage: index-declared-symbols.cjs --repo <repo> --structure <structure.json> --out <symbols.json>
+// Exit: 0 ok, 1 usage, 2 unreadable structure or missing component path.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { parseArgs } = require('util');
+const { listComponentFiles, readSource } = require('./lib/repo-walk.cjs');
+const { languageOf, extractDeclaredSymbols } = require('./lib/declared-symbol-patterns.cjs');
+const { InputError, isInputFailure, loadStructure, writeJson } = require('./lib/read-json-input.cjs');
+
+const USAGE = 'usage: index-declared-symbols.cjs --repo <repo> --structure <structure.json> --out <symbols.json>';
+
+function parse() {
+  try {
+    const { values } = parseArgs({ options: { repo: { type: 'string' }, structure: { type: 'string' }, out: { type: 'string' } } });
+    if (values.repo && values.structure && values.out) return values;
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+  }
+  process.stderr.write(`${USAGE}\n`);
+  return process.exit(1);
+}
+
+// sha256 over every file's path and LF-normalised content, in sorted order.
+function fingerprint(repo, files) {
+  const hash = crypto.createHash('sha256');
+  for (const file of files) hash.update(`${file}\0${readSource(repo, file)}\0`);
+  return `sha256:${hash.digest('hex')}`;
+}
+
+// A structure path must name an existing folder with the exact letter case on disk:
+// Windows and macOS would open `src/bids` for `src/Bids`, but every file path the
+// scripts compare afterwards would then disagree with it.
+function pathProblem(repo, relPath) {
+  let current = repo;
+  const actual = [];
+  for (const segment of relPath.split('/')) {
+    const match = fs.existsSync(current) && fs.statSync(current).isDirectory()
+      ? fs.readdirSync(current).find((name) => name.toLowerCase() === segment.toLowerCase())
+      : undefined;
+    if (match === undefined) return `missing path ${relPath}`;
+    actual.push(match);
+    current = path.join(current, match);
+  }
+  if (!fs.statSync(current).isDirectory()) return `path ${relPath} is a file, not a folder`;
+  const onDisk = actual.join('/');
+  return onDisk === relPath ? null : `path ${relPath} differs in letter case from the folder on disk: use ${onDisk}`;
+}
+
+function buildIndex(repo, structure) {
+  // A Map, so symbols named like Object.prototype members (`toString`, `constructor`) are plain keys.
+  const symbols = new Map();
+  const byComponent = {};
+  const fingerprints = {};
+  for (const component of structure.components) {
+    const files = listComponentFiles(repo, component.paths);
+    const declared = new Set();
+    for (const file of files) {
+      for (const name of extractDeclaredSymbols(readSource(repo, file), languageOf(file))) declared.add(name);
+    }
+    byComponent[component.id] = [...declared].sort();
+    fingerprints[component.id] = fingerprint(repo, files);
+    for (const name of declared) {
+      if (!symbols.has(name)) symbols.set(name, []);
+      symbols.get(name).push(component.id);
+    }
+  }
+  // Built with defineProperty so a `__proto__` symbol becomes an own key, not a prototype change.
+  const sortedSymbols = {};
+  for (const name of [...symbols.keys()].sort()) {
+    Object.defineProperty(sortedSymbols, name, { value: symbols.get(name).sort(), enumerable: true, writable: true, configurable: true });
+  }
+  return { symbols: sortedSymbols, byComponent, fingerprints };
+}
+
+function main() {
+  const args = parse();
+  const repo = path.resolve(args.repo);
+  try {
+    const structure = loadStructure(args.structure);
+    const missing = [];
+    for (const c of structure.components) {
+      for (const p of c.paths) {
+        const problem = pathProblem(repo, p);
+        if (problem) missing.push(`${problem} (component ${c.id})`);
+      }
+    }
+    if (missing.length) throw new InputError(missing.join('\n'));
+    const index = buildIndex(repo, structure);
+    writeJson(args.out, index);
+    const ambiguous = Object.values(index.symbols).filter((owners) => owners.length > 1).length;
+    process.stdout.write(`components ${structure.components.length}, symbols ${Object.keys(index.symbols).length}, ambiguous ${ambiguous}\n`);
+  } catch (error) {
+    if (!isInputFailure(error)) throw error;
+    process.stderr.write(`${error.message}\n`);
+    process.exit(2);
+  }
+}
+
+main();

package/template/.claude/skills/logical-components/scripts/lib/coupling-metrics.cjs

@@ -0,0 +1,48 @@
+'use strict';
+
+// Pure coupling maths. An edge A -> B means A knows about B. CE counts the
+// distinct components a component points to, CA the distinct components that
+// point to it, CT = CA + CE, and total system coupling is the sum of CT.
+
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+// Verified usages -> one edge per (from, to) with distinct sorted labels and evidence.
+function aggregateEdges(usages) {
+  const edges = new Map();
+  for (const u of usages) {
+    const key = `${u.from}\0${u.to}`;
+    if (!edges.has(key)) edges.set(key, { from: u.from, to: u.to, labels: new Set(), evidence: new Map() });
+    const edge = edges.get(key);
+    edge.labels.add(u.action);
+    edge.evidence.set(`${u.file}\0${u.line}\0${u.symbol}`, { file: u.file, line: u.line, symbol: u.symbol });
+  }
+  return [...edges.values()]
+    .sort((a, b) => compare(a.from, b.from) || compare(a.to, b.to))
+    .map((e) => ({
+      from: e.from,
+      to: e.to,
+      labels: [...e.labels].sort(compare),
+      evidence: [...e.evidence.values()].sort((a, b) => compare(a.file, b.file) || a.line - b.line || compare(a.symbol, b.symbol)),
+    }));
+}
+
+function computeMetrics(componentIds, edges) {
+  const metrics = {};
+  for (const id of componentIds) metrics[id] = { ca: 0, ce: 0, ct: 0 };
+  const seen = new Set();
+  for (const { from, to } of edges) {
+    const key = `${from}\0${to}`;
+    if (from === to || seen.has(key)) continue;
+    seen.add(key);
+    metrics[from].ce += 1;
+    metrics[to].ca += 1;
+  }
+  let totalCoupling = 0;
+  for (const id of componentIds) {
+    metrics[id].ct = metrics[id].ca + metrics[id].ce;
+    totalCoupling += metrics[id].ct;
+  }
+  return { metrics, totalCoupling };
+}
+
+module.exports = { aggregateEdges, computeMetrics, compare };

package/template/.claude/skills/logical-components/scripts/lib/declared-symbol-patterns.cjs

@@ -0,0 +1,57 @@
+'use strict';
+
+// Language detection and top-level declaration patterns. Regexes, not parsers:
+// they find the names other components can reference (types, exported
+// functions). A missed declaration only means a missing edge, never a wrong one.
+
+const LANGUAGES = {
+  '.cs': 'csharp',
+  '.java': 'java',
+  '.kt': 'kotlin', '.kts': 'kotlin',
+  '.ts': 'typescript', '.tsx': 'typescript', '.mts': 'typescript', '.cts': 'typescript',
+  '.js': 'javascript', '.jsx': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript',
+  '.py': 'python',
+  '.go': 'go',
+};
+
+const LABELS = { csharp: 'C#', java: 'Java', kotlin: 'Kotlin', typescript: 'TS', javascript: 'JS', python: 'Python', go: 'Go' };
+
+const CSHARP_MODIFIERS = 'public|internal|private|protected|static|sealed|abstract|partial|readonly|ref|unsafe|file|new';
+const JVM_MODIFIERS = 'public|private|protected|internal|static|final|abstract|sealed|open|data|inner|enum|annotation|value|inline';
+const ES_EXPORT = /^\s*export\s+(?:default\s+)?(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(?:function\s*\*?\s*|(?:const\s+enum|class|const|let|var|interface|type|enum)\s+)([A-Za-z_$][\w$]*)/gm;
+
+const PATTERNS = {
+  csharp: [new RegExp(`^\\s*(?:(?:${CSHARP_MODIFIERS})\\s+)*(?:class|record(?:\\s+(?:class|struct))?|struct|interface|enum)\\s+([A-Za-z_]\\w*)`, 'gm')],
+  java: [new RegExp(`^\\s*(?:(?:${JVM_MODIFIERS})\\s+)*(?:class|interface|enum|record)\\s+([A-Za-z_]\\w*)`, 'gm')],
+  kotlin: [new RegExp(`^\\s*(?:(?:${JVM_MODIFIERS})\\s+)*(?:class|interface|object|enum)\\s+([A-Za-z_]\\w*)`, 'gm')],
+  typescript: [ES_EXPORT],
+  javascript: [ES_EXPORT],
+  // Top level only (column 0); a leading underscore marks a private name.
+  python: [/^(?:async\s+)?(?:class|def)\s+([A-Za-z]\w*)/gm],
+  // Exported (capitalised) types and functions; methods start with a receiver `(`.
+  go: [/^type\s+([A-Z]\w*)/gm, /^func\s+([A-Z]\w*)\s*[[(]/gm],
+};
+
+function languageOf(fileName) {
+  const dot = fileName.lastIndexOf('.');
+  return dot < 0 ? null : LANGUAGES[fileName.slice(dot).toLowerCase()] || null;
+}
+
+// Sorted, de-duplicated names declared at the top level of `text`.
+function extractDeclaredSymbols(text, language) {
+  const names = new Set();
+  for (const pattern of PATTERNS[language] || []) {
+    pattern.lastIndex = 0;
+    for (const match of text.matchAll(pattern)) names.add(match[1]);
+  }
+  return [...names].sort();
+}
+
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// Matches any of `names` as a whole identifier (`$` counts as a word char for JS).
+function wholeWordPattern(names, flags = '') {
+  return new RegExp(`(?<![\\w$])(?:${names.map(escapeRegExp).join('|')})(?![\\w$])`, flags);
+}
+
+module.exports = { languageOf, extractDeclaredSymbols, wholeWordPattern, LABELS };

package/template/.claude/skills/logical-components/scripts/lib/html-sections.cjs

@@ -0,0 +1,91 @@
+'use strict';
+
+// HTML fragments of the logical-components page: component cards, the
+// coupling and edge tables, and the rejected-claims list. Every value from the
+// model is escaped; evidence links point at repo files relative to the page.
+
+const path = require('path');
+
+const escapeHtml = (value) => String(value)
+  .replace(/&/g, '&')
+  .replace(/</g, '&lt;')
+  .replace(/>/g, '&gt;')
+  .replace(/"/g, '&quot;')
+  .replace(/'/g, '&#39;');
+
+const anchor = (id) => `component-${id}`;
+
+// fileBase: posix path from the page's folder to the repo root ('..' for docs/).
+function evidenceLink(fileBase, file, start, end) {
+  const fragment = end === undefined || end === start ? `#L${start}` : `#L${start}-L${end}`;
+  const text = `${path.posix.basename(file)}:${end === undefined || end === start ? start : `${start}-${end}`}`;
+  const encoded = file.split('/').map(encodeURIComponent).join('/');
+  const href = `${fileBase ? `${fileBase}/` : ''}${encoded}${fragment}`;
+  return `<a href="${escapeHtml(href)}" title="${escapeHtml(file)}">${escapeHtml(text)}</a>`;
+}
+
+const componentLink = (byId, id) => `<a href="#${anchor(id)}">${escapeHtml(byId.get(id).name)}</a>`;
+
+function edgeItems(edges, byId, fileBase, other) {
+  if (!edges.length) return '<p class="none">None</p>';
+  const items = edges.map((e) => {
+    const evidence = e.evidence.map((ev) => evidenceLink(fileBase, ev.file, ev.line)).join(', ');
+    return `<li>${componentLink(byId, e[other])}: ${escapeHtml(e.labels.join('; '))} <span class="evidence">${evidence}</span></li>`;
+  });
+  return `<ul>${items.join('')}</ul>`;
+}
+
+function renderCards(model, fileBase) {
+  const byId = new Map(model.components.map((c) => [c.id, c]));
+  const moduleNames = new Map(model.modules.map((m) => [m.id, m.name]));
+  return model.components.map((c) => {
+    const responsibilities = c.responsibilities.length
+      ? `<ol>${c.responsibilities.map((r) => {
+        const links = r.evidence.map((ev) => evidenceLink(fileBase, ev.file, ev.lines[0], ev.lines[1])).join(', ');
+        return `<li>${escapeHtml(r.text)} <span class="evidence">${links}</span></li>`;
+      }).join('')}</ol>`
+      : '<p class="none">No verified responsibilities</p>';
+    const module = c.module === null ? '' : `${escapeHtml(moduleNames.get(c.module))} · `;
+    return [
+      `<section class="card" id="${anchor(c.id)}">`,
+      `<h3>${escapeHtml(c.name)}</h3>`,
+      `<p class="meta">${module}${c.paths.map((p) => `<code>${escapeHtml(p)}</code>`).join(' ')}</p>`,
+      `<p class="metrics">CA ${c.ca} · CE ${c.ce} · CT ${c.ct}</p>`,
+      `<h4>Responsibilities</h4>${responsibilities}`,
+      `<h4>Knows about (CE ${c.ce})</h4>${edgeItems(model.edges.filter((e) => e.from === c.id), byId, fileBase, 'to')}`,
+      `<h4>Known by (CA ${c.ca})</h4>${edgeItems(model.edges.filter((e) => e.to === c.id), byId, fileBase, 'from')}`,
+      '</section>',
+    ].join('\n');
+  }).join('\n');
+}
+
+function renderCouplingTable(model) {
+  const moduleNames = new Map(model.modules.map((m) => [m.id, m.name]));
+  const rows = [...model.components]
+    .sort((a, b) => b.ct - a.ct || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    .map((c) => `<tr><td><a href="#${anchor(c.id)}">${escapeHtml(c.name)}</a></td>`
+      + `<td>${c.module === null ? '' : escapeHtml(moduleNames.get(c.module))}</td>`
+      + `<td>${c.ca}</td><td>${c.ce}</td><td>${c.ct}</td></tr>`);
+  return `<table><thead><tr><th>Component</th><th>Module</th><th>CA</th><th>CE</th><th>CT</th></tr></thead>\n`
+    + `<tbody>\n${rows.join('\n')}\n</tbody></table>`;
+}
+
+// Plain edge list: readable even when the Mermaid CDN is unreachable.
+function renderEdgeTable(model, fileBase) {
+  if (!model.edges.length) return '<p class="none">No verified edges</p>';
+  const byId = new Map(model.components.map((c) => [c.id, c]));
+  const rows = model.edges.map((e) => `<tr><td>${componentLink(byId, e.from)}</td><td>${componentLink(byId, e.to)}</td>`
+    + `<td>${escapeHtml(e.labels.join('; '))}</td>`
+    + `<td>${e.evidence.map((ev) => evidenceLink(fileBase, ev.file, ev.line)).join(', ')}</td></tr>`);
+  return `<table><thead><tr><th>From</th><th>To</th><th>Asks to</th><th>Evidence</th></tr></thead>\n`
+    + `<tbody>\n${rows.join('\n')}\n</tbody></table>`;
+}
+
+function renderRejected(model) {
+  if (!model.rejected.length) return '<p class="none">No rejected claims</p>';
+  const items = model.rejected.map((r) => `<li><code>${escapeHtml(r.component)}</code> ${escapeHtml(r.kind)}: `
+    + `${escapeHtml(r.claim)} <span class="reason">${escapeHtml(r.reason)}</span></li>`);
+  return `<details class="rejected">\n<summary>Rejected claims (${model.rejected.length})</summary>\n<ul>${items.join('\n')}</ul>\n</details>`;
+}
+
+module.exports = { escapeHtml, renderCards, renderCouplingTable, renderEdgeTable, renderRejected };

package/template/.claude/skills/logical-components/scripts/lib/mermaid-graph.cjs

@@ -0,0 +1,55 @@
+'use strict';
+
+// Mermaid flowchart source for the component model. Node ids are index-based
+// (c0, c1, ...) so any component name, in any script, is safe; every piece of
+// text goes through mermaidText before it lands inside a quoted label.
+
+const MAX_LABELS = 2;
+
+// Mermaid entity codes for characters that could end a label or start markup.
+// `#` goes first so the codes added afterwards are not escaped twice.
+function mermaidText(value) {
+  return String(value)
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/#/g, '#35;')
+    .replace(/"/g, '#quot;')
+    .replace(/&/g, '#amp;')
+    .replace(/</g, '#lt;')
+    .replace(/>/g, '#gt;')
+    .replace(/`/g, '#96;')
+    // `%%{init}%%` directives and quoted keys must not survive as Mermaid syntax.
+    .replace(/%/g, '#37;')
+    .replace(/\{/g, '#123;')
+    .replace(/\}/g, '#125;')
+    .replace(/'/g, '#39;');
+}
+
+function edgeLabel(labels) {
+  const shown = labels.slice(0, MAX_LABELS).map(mermaidText).join('; ');
+  return labels.length > MAX_LABELS ? `${shown} +${labels.length - MAX_LABELS}` : shown;
+}
+
+function buildMermaid(model) {
+  const nodeIds = new Map(model.components.map((c, i) => [c.id, `c${i}`]));
+  const node = (c, indent) =>
+    `${indent}${nodeIds.get(c.id)}["${mermaidText(c.name)}<br/>CA ${c.ca} · CE ${c.ce} · CT ${c.ct}"]`;
+
+  const lines = ['flowchart LR'];
+  model.modules.forEach((module, i) => {
+    const members = model.components.filter((c) => c.module === module.id);
+    if (!members.length) return;
+    lines.push(`  subgraph m${i}["${mermaidText(module.name)}"]`);
+    for (const c of members) lines.push(node(c, '    '));
+    lines.push('  end');
+  });
+  for (const c of model.components.filter((x) => x.module === null)) lines.push(node(c, '  '));
+  for (const e of model.edges) {
+    lines.push(`  ${nodeIds.get(e.from)} -->|"${edgeLabel(e.labels)}"| ${nodeIds.get(e.to)}`);
+  }
+  // Ids are validated kebab-case, so they are safe inside the call string.
+  for (const c of model.components) lines.push(`  click ${nodeIds.get(c.id)} call focusCard("${c.id}")`);
+  return lines.join('\n');
+}
+
+module.exports = { buildMermaid, mermaidText };