@phuc1403/musketeer 0.8.0 → 0.10.0

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

@@ -1,357 +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,
-};
+'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,
+};