heyspex 0.1.0

package/vendor/heyspex-mcp/validate-linkage.mjs

@@ -0,0 +1,574 @@
+/**
+ * validate-linkage.mjs — the core of `heyspex_validate_linkage`.
+ *
+ * Detects four classes of linkage breakage across the spec vault so work an
+ * agent creates does not quietly go missing (HS-TASK-0U1F under
+ * [[HS-EPIC-0037-spec-linkage-validation-system]]):
+ *
+ *   1. orphan_specs          — milestone/epic/task not reachable from the roadmap.
+ *   2. broken_wikilinks      — `[[link]]` that resolves to no file under specs/.
+ *   3. missing_manifest_refs — roadmap manifest entry pointing to a missing file
+ *      (basename/unique-id match only — family idCore soft-match is intentionally
+ *      NOT enough, so stale Naming V3 era-1/2 listings cannot greenlight).
+ *   4. parent_child_mismatches — one side of a parent/child link not pointing back.
+ *
+ * Reachability is expressed in the manifest-v3 hierarchy
+ * ([[HS-TASK-JN9H-manifest-schema-v3-and-horizon-retirement]]):
+ *   roadmap → milestones (roadmap_manifest.milestones)
+ *           → epics       (epic `milestone:` ↔ milestone `epics:`)
+ *           → tasks       (task `parent:`   ↔ epic `children:`).
+ * The original 2026-05-18 task body assumed the retired `phases[].tasks[]`
+ * shape; this implementation tracks the live v3 manifest instead and the
+ * orphan `reason`/`suggestion` strings reflect that.
+ *
+ * The module is self-contained (no import from spex-console/) so the vendored
+ * MCP server stays portable. Frontmatter is read with the same regex-over-raw
+ * approach `scripts/validate-vault-ids.mjs` uses, not a full YAML parser.
+ *
+ * Faces ([[capability-three-faces-no-per-capability-slash]]): this core feeds
+ *   - the `heyspex_validate_linkage` MCP tool (cli.mjs), and
+ *   - the `validate` CLI verb (cli.mjs, used by the pre-commit linkage gate).
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { toCanonicalFamilyFirstId } from './spec-id-lib.mjs';
+
+// Entity kinds that must be reachable from the roadmap. Everything else
+// (research, protocol, memory-*, capture, diagnose, agent, review, adr, …) is
+// exempt — those are referenced by wikilink, not parented into the manifest.
+const SUBJECT_TYPES = new Set(['milestone', 'epic', 'task']);
+
+// ---------------------------------------------------------------------------
+// Frontmatter extraction (regex-over-raw — byte-tolerant, no YAML dependency)
+// ---------------------------------------------------------------------------
+
+function frontmatterBlock(raw) {
+  const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return m ? m[1] : '';
+}
+
+function scalarField(block, field) {
+  const m = block.match(new RegExp(`^${field}:[ \\t]*(.*)$`, 'm'));
+  if (!m) return null;
+  const v = m[1].trim();
+  if (!v) return null;
+  return v.replace(/^['"]|['"]$/g, '');
+}
+
+// Collect the raw list items under `field:` (a YAML block list). Each item may
+// be a bare token (manifest entries) or a wikilink (children/related/epics);
+// callers normalize with stripWikilink(). Returns [] when the field is absent
+// or explicitly empty (`field: []`).
+function listItems(block, field) {
+  if (new RegExp(`^[ \\t]*${field}:[ \\t]*\\[[ \\t]*\\][ \\t]*$`, 'm').test(block)) return [];
+  const m = block.match(
+    new RegExp(`^[ \\t]*${field}:[ \\t]*\\r?\\n((?:[ \\t]+-[^\\n]*(?:\\r?\\n|$))+)`, 'm'),
+  );
+  if (!m) return [];
+  const out = [];
+  for (const line of m[1].split(/\r?\n/)) {
+    const im = line.match(/^[ \t]+-[ \t]*(.+?)[ \t]*$/);
+    if (im) out.push(im[1].replace(/^['"]|['"]$/g, '').trim());
+  }
+  return out;
+}
+
+// `[[Foo|alias]]` / `[[Foo#anchor]]` / `Foo` → `Foo`. Returns null for empties.
+function stripWikilink(value) {
+  if (typeof value !== 'string') return null;
+  const inner = value.match(/\[\[([^\]]+)\]\]/);
+  let target = (inner ? inner[1] : value).trim();
+  target = target.split('|')[0].split('#')[0].trim();
+  return target || null;
+}
+
+// The stable identity core of an id/basename: `HS-TASK-0U1F-foo` → `HS-TASK-0U1F`.
+// Lets a `[[HS-TASK-0U1F]]` link (no slug) resolve to the full-slug file, and
+// guards the protocol/research hyphenated-id case
+// ([[hs-spec-id-regex-truncates-hyphenated-protocol-ids]]) by anchoring on the
+// 4+ char suffix rather than splitting on every hyphen.
+// Dual-read core: parseSpecId canonicalizes known types in EITHER ordering to one
+// form so refs match across the type-first → family-first migration; falls back to
+// the legacy anchored regex for unknown-type / hyphenated ids. [[HS-EPIC-DLE3]].
+function idCore(value) {
+  const canonical = toCanonicalFamilyFirstId(value);
+  if (canonical) return canonical.toUpperCase();
+  const m = String(value || '').match(/^(HS-[A-Z]+-[A-Za-z0-9]{2,})/i);
+  return m ? m[1].toUpperCase() : null;
+}
+
+// Every "real" `[[wikilink]]` in the file, with 1-based line numbers for
+// actionable reporting. Links inside fenced code blocks (``` / ~~~) and inline
+// code spans (`...`) are skipped — specs routinely show `[[example]]` syntax as
+// documentation, and those illustrative links must not be flagged as broken.
+// Handles `![[embeds]]` and multiple links per line.
+function extractLinks(raw) {
+  const links = [];
+  const lines = raw.split(/\r?\n/);
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^[ \t]*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    // Drop inline code spans so `[[link]]` shown as code is not treated as real.
+    const scrubbed = line.replace(/`[^`]*`/g, '');
+    const re = /!?\[\[([^\]]+)\]\]/g;
+    let m;
+    while ((m = re.exec(scrubbed)) !== null) {
+      const target = m[1].split('|')[0].split('#')[0].trim();
+      if (target) links.push({ target, line: i + 1 });
+    }
+  }
+  return links;
+}
+
+// ---------------------------------------------------------------------------
+// Vault walk → normalized spec records
+// ---------------------------------------------------------------------------
+
+function walkMarkdown(dir, acc = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === '.trash' || entry.name === 'node_modules') continue;
+      walkMarkdown(full, acc);
+    } else if (entry.name.endsWith('.md')) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+// Extract `## Related / lineage` markdown table rows and return wikilinks from
+// first column. Returns [] if section does not exist.
+function extractLineageTableLinks(raw) {
+  const lineageMatch = raw.match(/^##\s+Related\s*\/\s*lineage[\s\S]*?(?=^##\s|\Z)/m);
+  if (!lineageMatch) return [];
+  const section = lineageMatch[0];
+  // Find markdown table (| ... |)
+  const tableMatch = section.match(/^\|[^|]*\|[^|]*\|[\s\S]*?(?=\n\n|\Z)/m);
+  if (!tableMatch) return [];
+  const table = tableMatch[0];
+  const lines = table.split('\n');
+  const links = [];
+  // Skip header (first line) and separator (second line)
+  for (let i = 2; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) break;
+    // First column is between first and second | delimiters
+    const match = line.match(/^\|\s*([^|]*?)\s*\|/);
+    if (match) {
+      const cellContent = match[1].trim();
+      const linkMatch = cellContent.match(/\[\[([^\]]+)\]\]/);
+      if (linkMatch) {
+        const target = linkMatch[1].split('|')[0].split('#')[0].trim();
+        if (target) links.push(target);
+      }
+    }
+  }
+  return links;
+}
+
+/**
+ * Read every `.md` under `<vaultRoot>/specs/` into a normalized record the
+ * analyzer consumes. Exported so the analyzer can be unit-tested with synthetic
+ * records (no disk) while the real path walks the vault.
+ */
+export function collectVaultSpecs(vaultRoot) {
+  const specsDir = join(vaultRoot, 'specs');
+  if (!existsSync(specsDir)) return [];
+  const specs = [];
+  for (const abs of walkMarkdown(specsDir)) {
+    let raw;
+    try {
+      raw = readFileSync(abs, 'utf-8');
+    } catch {
+      continue;
+    }
+    const block = frontmatterBlock(raw);
+    const basename = abs.replace(/.*[\\/]/, '').replace(/\.md$/, '');
+    const id = scalarField(block, 'id') || basename;
+    const type = scalarField(block, 'type');
+    const manifestRoadmap = type === 'roadmap' || /^roadmap_manifest:/m.test(block);
+    specs.push({
+      id,
+      type,
+      basename,
+      idCore: idCore(id) || idCore(basename),
+      file: relative(vaultRoot, abs).split('\\').join('/'),
+      parent: stripWikilink(scalarField(block, 'parent')),
+      milestone: stripWikilink(scalarField(block, 'milestone')),
+      children: listItems(block, 'children').map(stripWikilink).filter(Boolean),
+      epics: listItems(block, 'epics').map(stripWikilink).filter(Boolean),
+      related: listItems(block, 'related').map(stripWikilink).filter(Boolean),
+      // `amends:` — the partial / non-terminal supersession tier ([[AMENDS-CONTRACT]] /
+      // HS-6DMR-EPIC). Lives ONLY on the amending (newer, canonical) doc; the reverse
+      // map "what amends spec X" is COMPUTED in analyzeLinkage — targets are never edited.
+      amends: listItems(block, 'amends').map(stripWikilink).filter(Boolean),
+      // `iterates_on:` — round-to-round iteration tier. Like amends, lives ONLY on the
+      // newer doc; the reverse map "what iterates_on spec X" is COMPUTED in analyzeLinkage.
+      iterates_on: listItems(block, 'iterates_on').map(stripWikilink).filter(Boolean),
+      links: extractLinks(raw),
+      lineage_table_links: extractLineageTableLinks(raw),
+      manifest: manifestRoadmap
+        ? {
+            milestones: listItems(block, 'milestones').map(stripWikilink).filter(Boolean),
+            initiatives: listItems(block, 'initiatives').map(stripWikilink).filter(Boolean),
+          }
+        : null,
+    });
+  }
+  return specs;
+}
+
+// ---------------------------------------------------------------------------
+// Analysis (pure — operates over normalized records)
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {object[]} specs    Normalized records (from collectVaultSpecs or a fixture).
+ * @param {object}   options
+ * @param {boolean}  [options.includeWarnings=true]
+ * @param {Set<string>|null} [options.scopeIds]  When set, only report issues whose
+ *        subject spec matches one of these ids/basenames/id-cores (pre-commit
+ *        `--staged-only`). null = whole vault.
+ */
+export function analyzeLinkage(specs, { includeWarnings = true, scopeIds = null } = {}) {
+  const byBasename = new Map();
+  const byId = new Map();
+  const byIdCore = new Map();
+  for (const s of specs) {
+    byBasename.set(s.basename, s);
+    if (s.id) byId.set(s.id, s);
+    if (s.idCore && !byIdCore.has(s.idCore)) byIdCore.set(s.idCore, s);
+  }
+
+  const resolveRef = (ref) => {
+    if (!ref) return null;
+    const t = stripWikilink(ref) ?? ref;
+    return byBasename.get(t) || byId.get(t) || byIdCore.get(idCore(t)) || null;
+  };
+  // Manifest entries must name an on-disk basename (or unique bare id). Family
+  // idCore alone is NOT enough — after Naming V3, an era-1/2 `HS-<family>-MIL-…`
+  // string shares idCore with the era-3 file but does not match the console's
+  // basename resolver, so roadmap rows go empty while linkage looked green.
+  const resolveManifestRef = (ref) => {
+    if (!ref) return null;
+    const t = stripWikilink(ref) ?? ref;
+    return byBasename.get(t) || byId.get(t) || null;
+  };
+  const refResolves = (ref) => resolveRef(ref) != null;
+  const refMatchesSpec = (ref, spec) => {
+    const t = stripWikilink(ref) ?? ref;
+    return t === spec.basename || t === spec.id || (!!spec.idCore && idCore(t) === spec.idCore);
+  };
+  const listContainsSpec = (list, spec) => list.some((ref) => refMatchesSpec(ref, spec));
+
+  // Manifest reachability index — union of every roadmap's milestone entries.
+  // Basename / bare-id only (no idCore) so a stale era-1/2 listing does not
+  // falsely cover the era-3 file on disk.
+  const manifestMilestoneRefs = new Set();
+  for (const s of specs) {
+    if (!s.manifest) continue;
+    for (const ref of s.manifest.milestones) {
+      manifestMilestoneRefs.add(ref);
+    }
+  }
+  const milestoneInManifest = (spec) =>
+    manifestMilestoneRefs.has(spec.basename) || manifestMilestoneRefs.has(spec.id);
+  const inScope = (spec) =>
+    !scopeIds ||
+    scopeIds.has(spec.id) ||
+    scopeIds.has(spec.basename) ||
+    (!!spec.idCore && scopeIds.has(spec.idCore));
+
+  // Amends reverse map ([[AMENDS-CONTRACT]] / HS-6DMR-EPIC) — the partial,
+  // non-terminal supersession tier. `amends:` lives only on the amending (newer)
+  // doc; "what amends spec X" is COMPUTED here by scanning every spec's amends
+  // list, so one edit on the source needs zero edits on N targets. Amended
+  // targets stay canonical + scheduled (this is resolution only, not filtering).
+  const amended_by = {}; // targetBasename → [sourceBasename, …]
+  const broken_amends = []; // amends entries that resolve to no spec under specs/
+  for (const spec of specs) {
+    for (const ref of spec.amends || []) {
+      const target = resolveRef(ref);
+      if (!target) {
+        if (inScope(spec)) {
+          broken_amends.push({
+            spec_id: spec.id,
+            file_path: spec.file,
+            ref: `[[${stripWikilink(ref) ?? ref}]]`,
+            error: 'amends: target does not resolve to a spec under specs/',
+          });
+        }
+        continue;
+      }
+      (amended_by[target.basename] ??= []).push(spec.basename);
+    }
+  }
+
+  // Iterates-on reverse map — round-to-round iteration tier. Like amends, `iterates_on:`
+  // lives only on the iterating (newer) doc; the reverse map "what iterates_on spec X"
+  // is COMPUTED here. Targets that don't resolve are reported in broken_iterates_on.
+  const iterated_by = {}; // targetBasename → [sourceBasename, …]
+  const broken_iterates_on = []; // iterates_on entries that resolve to no spec under specs/
+  for (const spec of specs) {
+    for (const ref of spec.iterates_on || []) {
+      const target = resolveRef(ref);
+      if (!target) {
+        if (inScope(spec)) {
+          broken_iterates_on.push({
+            spec_id: spec.id,
+            file_path: spec.file,
+            ref: `[[${stripWikilink(ref) ?? ref}]]`,
+            error: 'iterates_on: target does not resolve to a spec under specs/',
+          });
+        }
+        continue;
+      }
+      (iterated_by[target.basename] ??= []).push(spec.basename);
+    }
+  }
+
+  const orphan_specs = [];
+  const broken_wikilinks = [];
+  const missing_manifest_refs = [];
+  const parent_child_mismatches = [];
+  const warnings = [];
+  const seenMismatch = new Set();
+
+  const pushMismatch = (parent, child, issue, parentSpec, childSpec) => {
+    const key = `${parent}|${child}|${issue}`;
+    if (seenMismatch.has(key)) return;
+    seenMismatch.add(key);
+    if (!inScope(parentSpec) && !inScope(childSpec)) return;
+    parent_child_mismatches.push({ parent, child, issue });
+  };
+
+  let subjectsChecked = 0;
+  for (const spec of specs) {
+    // (2) broken wikilinks — every spec's outbound links, scoped to its owner.
+    if (inScope(spec)) {
+      for (const link of spec.links) {
+        if (!refResolves(link.target)) {
+          broken_wikilinks.push({ file: spec.file, line: link.line, link: `[[${link.target}]]` });
+        }
+      }
+    }
+
+    // (3) missing manifest refs — roadmap entries with no backing file.
+    // Strict: basename/id only. idCore soft-match would greenlight stale
+    // Naming V3-era family-first listings that the console cannot resolve.
+    if (spec.manifest && inScope(spec)) {
+      for (const ref of [...spec.manifest.milestones, ...spec.manifest.initiatives]) {
+        if (!resolveManifestRef(ref)) {
+          missing_manifest_refs.push({
+            manifest: spec.id,
+            ref,
+            error: 'File not found (manifest refs must match basename or unique id; family-core alone is not enough)',
+          });
+        }
+      }
+    }
+
+    if (!SUBJECT_TYPES.has(spec.type)) continue;
+    subjectsChecked++;
+
+    // (1) orphan detection, by entity kind.
+    if (spec.type === 'milestone') {
+      if (!milestoneInManifest(spec)) {
+        if (inScope(spec)) {
+          orphan_specs.push({
+            spec_id: spec.id,
+            file_path: spec.file,
+            type: spec.type,
+            suggestion: 'Add this milestone to a roadmap manifest (roadmap_manifest.milestones).',
+            reason: 'Milestone is not listed in any roadmap manifest, so it is unreachable from the roadmap.',
+          });
+        }
+      }
+    } else if (spec.type === 'epic') {
+      if (!spec.milestone || !refResolves(spec.milestone)) {
+        if (inScope(spec)) {
+          orphan_specs.push({
+            spec_id: spec.id,
+            file_path: spec.file,
+            type: spec.type,
+            suggestion: 'Set `milestone:` to an existing HS-MIL-* milestone.',
+            reason: spec.milestone
+              ? `Epic \`milestone:\` does not resolve to an existing milestone (${spec.milestone}).`
+              : 'Epic has no `milestone:` parent, so it is unreachable from the roadmap.',
+          });
+        }
+      } else {
+        const ms = resolveRef(spec.milestone);
+        if (ms && ms.type === 'milestone' && !listContainsSpec(ms.epics, spec)) {
+          pushMismatch(
+            ms.id,
+            spec.id,
+            'Epic lists milestone but milestone is missing the epic in epics[]',
+            ms,
+            spec,
+          );
+        }
+      }
+    } else if (spec.type === 'task') {
+      if (!spec.parent || !refResolves(spec.parent)) {
+        if (inScope(spec)) {
+          orphan_specs.push({
+            spec_id: spec.id,
+            file_path: spec.file,
+            type: spec.type,
+            suggestion: 'Set `parent:` to an existing HS-EPIC-* epic.',
+            reason: spec.parent
+              ? `Task \`parent:\` does not resolve to an existing epic (${spec.parent}).`
+              : 'Task has no `parent:` epic, so it is unreachable from the roadmap.',
+          });
+        }
+      } else {
+        const epic = resolveRef(spec.parent);
+        if (epic && epic.type === 'epic' && !listContainsSpec(epic.children, spec)) {
+          pushMismatch(
+            epic.id,
+            spec.id,
+            'Child lists parent but parent is missing the child in children[]',
+            epic,
+            spec,
+          );
+        }
+      }
+    }
+
+    // (4) reverse parent/child — declared children/epics must resolve under specs/.
+    // A stale wikilink to a file moved outside specs/ must NOT pass silently
+    // ([[HS-9A78-DIAG]] — previously `if (!child) continue` masked the gap).
+    if (spec.type === 'epic') {
+      for (const childRef of spec.children) {
+        const child = resolveRef(childRef);
+        const childLabel = stripWikilink(childRef) ?? childRef;
+        if (!child) {
+          if (inScope(spec)) {
+            pushMismatch(
+              spec.id,
+              childLabel,
+              'Parent lists child that does not resolve to a spec under specs/',
+              spec,
+              spec,
+            );
+          }
+          continue;
+        }
+        if (!child.parent || !refMatchesSpec(child.parent, spec)) {
+          pushMismatch(
+            spec.id,
+            child.id,
+            'Parent lists child but child `parent:` does not point back',
+            spec,
+            child,
+          );
+        }
+      }
+    }
+    if (spec.type === 'milestone') {
+      for (const epicRef of spec.epics) {
+        const epic = resolveRef(epicRef);
+        const epicLabel = stripWikilink(epicRef) ?? epicRef;
+        if (!epic) {
+          if (inScope(spec)) {
+            pushMismatch(
+              spec.id,
+              epicLabel,
+              'Milestone lists epic that does not resolve to a spec under specs/',
+              spec,
+              spec,
+            );
+          }
+          continue;
+        }
+        if (!epic.milestone || !refMatchesSpec(epic.milestone, spec)) {
+          pushMismatch(
+            spec.id,
+            epic.id,
+            'Milestone lists epic but epic `milestone:` does not point back',
+            spec,
+            epic,
+          );
+        }
+      }
+    }
+
+    // Soft warnings (gated) — the documented "no related[] links" nudge.
+    if (includeWarnings && inScope(spec) && spec.related.length === 0) {
+      warnings.push({ spec_id: spec.id, message: 'No related[] links defined' });
+    }
+
+    // Lineage table link resolution warnings — each wikilink in the first column
+    // of a "## Related / lineage" markdown table must resolve under specs/.
+    if (includeWarnings && inScope(spec)) {
+      for (const link of spec.lineage_table_links || []) {
+        if (!refResolves(link)) {
+          warnings.push({
+            spec_id: spec.id,
+            message: `Related/lineage table row wikilink does not resolve: [[${link}]]`,
+          });
+        }
+      }
+    }
+  }
+
+  const valid =
+    orphan_specs.length === 0 &&
+    broken_wikilinks.length === 0 &&
+    missing_manifest_refs.length === 0 &&
+    parent_child_mismatches.length === 0 &&
+    broken_amends.length === 0 &&
+    broken_iterates_on.length === 0;
+
+  return {
+    valid,
+    orphan_specs,
+    broken_wikilinks,
+    missing_manifest_refs,
+    parent_child_mismatches,
+    broken_amends,
+    amended_by,
+    broken_iterates_on,
+    iterated_by,
+    warnings: includeWarnings ? warnings : [],
+    summary: {
+      total_specs_checked: subjectsChecked,
+      orphans: orphan_specs.length,
+      broken_links: broken_wikilinks.length,
+      missing_refs: missing_manifest_refs.length,
+      mismatches: parent_child_mismatches.length,
+      broken_amends: broken_amends.length,
+      broken_iterates_on: broken_iterates_on.length,
+    },
+  };
+}
+
+/**
+ * End-to-end: walk a real vault and analyze it.
+ * @param {string} vaultRoot
+ * @param {object} [opts]
+ * @param {string}   [opts.spec_id]        Scope to a single spec.
+ * @param {string[]} [opts.spec_ids]       Scope to several specs (overrides spec_id).
+ * @param {boolean}  [opts.includeWarnings=true]
+ */
+export function validateLinkage(vaultRoot, { spec_id = null, spec_ids = null, includeWarnings = true } = {}) {
+  const specs = collectVaultSpecs(vaultRoot);
+  const scope = spec_ids ?? (spec_id ? [spec_id] : null);
+  return analyzeLinkage(specs, {
+    includeWarnings,
+    scopeIds: scope && scope.length ? new Set(scope) : null,
+  });
+}