@phuc1403/musketeer 0.4.0 → 0.5.0

package/template/.claude/hooks/lib/characteristics/checker.cjs

@@ -0,0 +1,357 @@
+'use strict';
+
+// Structural checker for the two architecture-characteristic documents.
+//
+// Checks only what is mechanically decidable. The ranking ORDER is a judgement
+// call and is never questioned here; what is checked is that the table is
+// complete, that every comparative reason names the row it actually sits above,
+// and that the worksheet is a faithful derivation of the ranking's top 7.
+//
+// The catalog markdown is the single source of truth for which characteristics
+// exist, which of them are implicit, and how the composites decompose. Nothing
+// here restates it — edit the markdown and this checker follows.
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_CATALOG_PATH = path.join(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  'skills',
+  'architecture-characteristic-writer',
+  'references',
+  'characteristics-catalog.md'
+);
+
+const DRIVING_LIMIT = 7;
+
+// The ranking table is found by its header row rather than by the heading above
+// it. A heading is prose the author may reword or duplicate; this signature is
+// the table itself. Both the checker and scripts/ranking-table.cjs locate the
+// table this way, so neither can end up working on a different table.
+const RANKING_HEADER = /^\|\s*order\s*\|\s*characteristic\s*\|\s*reason\s*\|/i;
+
+// "feasibility (cost/time)" and "**feasibility**" both normalise to "feasibility"
+// so the checker never argues with formatting.
+function normalise(cell) {
+  return String(cell)
+    .replace(/`([^`]*)`/g, '$1')
+    .replace(/\*\*/g, '')
+    .replace(/\([^)]*\)/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+const isPlaceholder = (row) => row.some((c) => /\{[a-z0-9_]+\}/i.test(c)) || row.some((c) => c === '...');
+
+const splitCells = (line) =>
+  line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+
+const isSeparator = (cells) => cells.every((c) => /^:?-+:?$/.test(c) || c === '');
+
+// Returns the data rows of the first pipe table under a heading matching `re`,
+// or of the whole document when `re` is null. Header and separator are dropped.
+function parseTable(markdown, re) {
+  const lines = markdown.split(/\r?\n/);
+  let start = 0;
+
+  if (re) {
+    const i = lines.findIndex((l) => /^#{1,6}\s/.test(l) && re.test(l));
+    if (i === -1) return null;
+    start = i + 1;
+    const next = lines.slice(start).findIndex((l) => /^#{1,6}\s/.test(l));
+    if (next !== -1) lines.length = start + next;
+  }
+
+  const rows = [];
+  let seenHeader = false;
+
+  for (const line of lines.slice(start)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) {
+      if (seenHeader && rows.length) break;
+      continue;
+    }
+    const cells = splitCells(trimmed);
+    if (!seenHeader) {
+      seenHeader = true;
+      continue;
+    }
+    if (isSeparator(cells)) continue;
+    rows.push(cells);
+  }
+
+  return seenHeader ? rows : null;
+}
+
+// Line bounds of the table whose header matches `headerRe`, covering the header
+// through the last consecutive pipe line. Returns null when there is no match.
+function locateTable(lines, headerRe) {
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!lines[i].trim().startsWith('|') || !headerRe.test(lines[i].trim())) continue;
+    let end = i + 1;
+    while (end < lines.length && lines[end].trim().startsWith('|')) end += 1;
+    return { start: i, end };
+  }
+  return null;
+}
+
+// Data rows of the table located by `headerRe`, header and separator dropped.
+function tableRows(markdown, headerRe) {
+  const lines = markdown.split(/\r?\n/);
+  const at = locateTable(lines, headerRe);
+  if (!at) return null;
+  return lines
+    .slice(at.start + 1, at.end)
+    .map(splitCells)
+    .filter((c) => !isSeparator(c));
+}
+
+// Reads the catalog markdown and derives every set the checker needs from it.
+// Throws when the file is absent or a section is unreadable; the caller decides
+// whether that is fatal.
+function loadCatalog(catalogPath = DEFAULT_CATALOG_PATH) {
+  const markdown = fs.readFileSync(catalogPath, 'utf8');
+
+  const names = (re) => {
+    const rows = parseTable(markdown, re);
+    if (!rows) throw new Error(`no table found under a heading matching ${re}`);
+    return rows.filter((r) => r.length && !isPlaceholder(r)).map((r) => normalise(r[0]));
+  };
+
+  const common = names(/common/i);
+  const implicit = names(/implicit/i);
+
+  const compositeRows = parseTable(markdown, /composite/i);
+  if (!compositeRows) throw new Error('no Composite Architecture Characteristics table found');
+
+  const composites = {};
+  for (const row of compositeRows.filter((r) => r.length >= 2 && !isPlaceholder(r))) {
+    composites[normalise(row[0])] = row[1].split('+').map(normalise).filter(Boolean);
+  }
+
+  if (!common.length || !implicit.length) throw new Error('the Common or Implicit section is empty');
+
+  return { catalog: [...common, ...implicit], implicit, composites };
+}
+
+function checkRanking(markdown, { catalog }) {
+  const errors = [];
+  const found = tableRows(markdown, RANKING_HEADER);
+  if (!found) {
+    return {
+      errors: ['ranking: no table with a "| Order | Characteristic | Reason |" header row'],
+      order: [],
+    };
+  }
+  const raw = found.filter((r) => r.length >= 3);
+  const unfilled = raw.filter(isPlaceholder);
+  const rows = raw.filter((r) => !isPlaceholder(r));
+
+  // A scaffold is a blank form, not a broken document: every reason is still a
+  // placeholder, bar the last row whose reason is only the em dash.
+  const hasContent = (r) => !isPlaceholder(r) && !/^[—-]$/.test(String(r[2]).trim());
+  if (raw.length && !raw.some(hasContent)) return { errors: [], order: [] };
+  if (!rows.length) return { errors: ['ranking: no table rows found'], order: [] };
+
+  // Half-filled, so adjacency cannot be judged: a filled row's neighbour may be
+  // one of the rows still holding a placeholder. Ask for the rest first.
+  if (unfilled.length) {
+    return {
+      errors: [`ranking: ${unfilled.length} row(s) still hold the {why} placeholder, fill them in`],
+      order: [],
+    };
+  }
+
+  const order = rows.map((r) => normalise(r[1]));
+
+  // Rule 1 — the Order column counts 1..N with no gaps and no repeats.
+  rows.forEach((r, i) => {
+    const n = Number(String(r[0]).trim());
+    if (n !== i + 1) errors.push(`ranking row ${i + 1}: Order column reads "${r[0]}", expected ${i + 1}`);
+  });
+
+  // Rule 2 — the ranked set is exactly the catalog. Nothing missing, nothing
+  // invented, nothing ranked twice.
+  const seen = new Set();
+  order.forEach((name, i) => {
+    if (!catalog.includes(name)) errors.push(`ranking row ${i + 1}: "${name}" is not in the catalog`);
+    if (seen.has(name)) errors.push(`ranking row ${i + 1}: "${name}" is ranked more than once`);
+    seen.add(name);
+  });
+  for (const name of catalog) {
+    if (!seen.has(name)) errors.push(`ranking: "${name}" is missing`);
+  }
+
+  // Rules 3 and 4 — every reason names the row it actually sits above. This is
+  // what goes stale after a reorder, so it is checked by string, not by eye.
+  rows.forEach((r, i) => {
+    const reason = String(r[2]).trim();
+    const last = i === rows.length - 1;
+
+    if (last) {
+      if (!/^[—-]$/.test(reason)) {
+        errors.push(`ranking row ${i + 1}: last row has nothing below it, its Reason must be "—"`);
+      }
+      return;
+    }
+
+    const below = order[i + 1];
+    const m = reason.match(/^above\s+([^:]+):\s*(.*)$/i);
+
+    if (!m) {
+      errors.push(`ranking row ${i + 1} (${order[i]}): Reason must start with "Above ${below}:"`);
+      return;
+    }
+    if (normalise(m[1]) !== below) {
+      errors.push(
+        `ranking row ${i + 1} (${order[i]}): Reason compares against "${m[1].trim()}" but the row below is "${below}"`
+      );
+    }
+    if (m[2].trim().length < 15) {
+      errors.push(`ranking row ${i + 1} (${order[i]}): Reason has a prefix but no justification after it`);
+    }
+  });
+
+  return { errors, order };
+}
+
+function checkWorksheet(markdown, order, { implicit, composites }) {
+  const errors = [];
+  const driving = (parseTable(markdown, /driving/i) || []).filter((r) => r.length >= 2 && !isPlaceholder(r));
+  const implicitRows = (parseTable(markdown, /implicit/i) || []).filter(
+    (r) => r.length >= 1 && !isPlaceholder(r)
+  );
+
+  if (!driving.length) return ['worksheet: no Driving Characteristics rows found'];
+
+  const names = driving.map((r) => normalise(r[1] !== undefined && r.length >= 3 ? r[1] : r[0]));
+
+  // Rule 5 — no backfill. Composing shrinks the section; it never refills.
+  if (names.length > DRIVING_LIMIT) {
+    errors.push(`worksheet: ${names.length} driving characteristics, maximum is ${DRIVING_LIMIT}`);
+  }
+
+  // Listed twice, so the count is a lie and the top 7 cannot all be present.
+  // Said plainly here, or it surfaces later as a confusing pile of "missing".
+  const twice = new Set();
+  names.forEach((name, i) => {
+    if (names.indexOf(name) !== i) twice.add(name);
+  });
+  for (const name of twice) errors.push(`worksheet: "${name}" is listed more than once`);
+
+  // Without a readable ranking the remaining rules have nothing to derive from.
+  if (!order.length) return errors;
+
+  const top = order.slice(0, DRIVING_LIMIT);
+  const absorbed = new Set();
+
+  for (const name of names) {
+    const parts = composites[name];
+
+    if (parts) {
+      // Rule 7 — a composite stands only when the whole of it ranked top 7.
+      const missing = parts.filter((p) => !top.includes(p));
+      if (missing.length) {
+        errors.push(
+          `worksheet: "${name}" needs all of [${parts.join(', ')}] in the top 7, missing [${missing.join(', ')}]`
+        );
+      }
+      parts.forEach((p) => absorbed.add(p));
+
+      // Rule 8 — a composite and its own parts must never be listed side by side.
+      const both = parts.filter((p) => names.includes(p));
+      if (both.length) {
+        errors.push(`worksheet: "${name}" is listed alongside its own component [${both.join(', ')}]`);
+      }
+      continue;
+    }
+
+    // Rule 6 — everything driving traces back to the top 7.
+    if (!top.includes(name)) {
+      const rank = order.indexOf(name);
+      errors.push(
+        rank === -1
+          ? `worksheet: "${name}" is not in the ranking at all`
+          : `worksheet: "${name}" is ranked ${rank + 1}, outside the top 7`
+      );
+    }
+  }
+
+  const present = new Set([...names, ...absorbed]);
+
+  // Rule 6b — the top 7 is taken whole. Every one of them is either listed or
+  // swallowed by a composite; none may be quietly dropped.
+  for (const name of top) {
+    if (!present.has(name)) {
+      errors.push(`worksheet: "${name}" is ranked ${order.indexOf(name) + 1} but is missing from the worksheet`);
+    }
+  }
+
+  // Rule 9 — the implicit set is a pure derivation: the catalog's implicit
+  // characteristics, less any that reached the top 7, counting those a
+  // composite swallowed.
+  const expected = implicit.filter((c) => !present.has(c));
+  const actual = implicitRows.map((r) => normalise(r[0])).filter((c) => implicit.includes(c));
+
+  for (const c of expected) {
+    if (!actual.includes(c)) errors.push(`worksheet: implicit characteristic "${c}" is missing`);
+  }
+  for (const c of actual) {
+    if (!expected.includes(c)) {
+      errors.push(`worksheet: "${c}" is in the top 7, so it must not be listed as implicit`);
+    }
+  }
+
+  return errors;
+}
+
+// ranking and worksheet are file contents; either may be null when absent.
+// The catalog sets default to the shipped markdown; pass `catalog` to inject.
+function check({ ranking = null, worksheet = null, catalog = null, catalogPath } = {}) {
+  let sets = catalog;
+
+  if (!sets) {
+    try {
+      sets = loadCatalog(catalogPath);
+    } catch (err) {
+      return [`cannot read the characteristics catalog, so nothing can be checked: ${err.message}`];
+    }
+  }
+
+  let errors = [];
+  let order = [];
+
+  if (ranking !== null) {
+    const res = checkRanking(ranking, sets);
+    errors = errors.concat(res.errors);
+    order = res.order;
+  }
+
+  if (worksheet !== null) {
+    if (ranking === null) {
+      errors.push('worksheet: no ranking file to derive from, write the ranking first');
+    } else {
+      errors = errors.concat(checkWorksheet(worksheet, order, sets));
+    }
+  }
+
+  return errors;
+}
+
+module.exports = {
+  check,
+  checkRanking,
+  checkWorksheet,
+  parseTable,
+  locateTable,
+  splitCells,
+  isSeparator,
+  normalise,
+  loadCatalog,
+  RANKING_HEADER,
+  DEFAULT_CATALOG_PATH,
+};

package/template/.claude/hooks/validate-characteristics-hook.cjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// PostToolUse validation hook for the two architecture-characteristic documents.
+//
+// .claude/settings.json calls this after every Write/Edit/MultiEdit. If the
+// edited file is the ranking or the worksheet, both are checked together — the
+// worksheet is a derivation of the ranking, so neither can be judged alone.
+//
+// Hook exit-code contract:
+//   exit 0 -> ok (stdout shown in transcript)
+//   exit 2 -> blocking error (stderr fed back to Claude to fix)
+// An unrelated edit, a missing file, or an unparseable payload all exit 0.
+//
+// Only structure is checked. The ranking ORDER is the architect's call and is
+// never second-guessed here.
+
+const fs = require('fs');
+const path = require('path');
+
+const RANKING = 'docs/architecture-characteristics-ranking.md';
+const WORKSHEET = 'docs/architecture-characteristics.md';
+
+function read(root, rel) {
+  try {
+    return fs.readFileSync(path.join(root, rel), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+try {
+  const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
+  const edited = payload?.tool_input?.file_path;
+
+  if (!edited) process.exit(0);
+
+  // Windows resolves paths case-insensitively, so the same document can arrive
+  // spelled several ways. Comparing case-sensitively there would let an edit
+  // slip past the gate unchecked, which is worse than checking one file twice.
+  const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+  const rel = path.relative(root, path.resolve(root, edited)).split(path.sep).join('/');
+  if (fold(rel) !== fold(RANKING) && fold(rel) !== fold(WORKSHEET)) process.exit(0);
+
+  const { check } = require('./lib/characteristics/checker.cjs');
+  const ranking = read(root, RANKING);
+
+  // Editing the ranking alone, before any worksheet exists, is the normal path
+  // through Phase A: `read` returns null and the worksheet rules stay quiet.
+  const worksheet = read(root, WORKSHEET);
+
+  const errors = check({ ranking, worksheet });
+
+  if (errors.length) {
+    process.stderr.write(
+      `Architecture characteristics: ${errors.length} structural problem(s) in ${rel}\n\n` +
+        errors.map((e) => `  - ${e}`).join('\n') +
+        '\n\nFix the file. These are mechanical rules, not judgement calls: the ranking must ' +
+        'cover the catalog exactly once each, every Reason must name the row directly below it, ' +
+        'and the worksheet must derive from the top 7.\n'
+    );
+    process.exit(2);
+  }
+} catch {
+  /* fail open — a structure checker must never be the thing that breaks a session */
+}
+process.exit(0);