@phuc1403/musketeer 0.12.1 → 0.15.0

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 };

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();