harnery 0.6.0 → 0.7.0

package/src/lib/docs-frontmatter-migrate.ts

@@ -0,0 +1,427 @@
+import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { dump as dumpYaml, JSON_SCHEMA } from "js-yaml";
+import { type DocKind, normalizeStatus, parseFrontmatter } from "./docs-frontmatter.ts";
+
+let REPO_ROOT = "";
+let SUBMODULES: readonly string[] = [];
+
+export function initDocsMigrationContext(opts: {
+  repoRoot: string;
+  submodules: readonly string[];
+}): void {
+  REPO_ROOT = opts.repoRoot;
+  SUBMODULES = opts.submodules;
+}
+
+export interface FrontmatterMigrationOpts {
+  repo?: string;
+  apply?: boolean;
+}
+
+export type FrontmatterMigrationStatus = "would-update" | "updated" | "skipped" | "error";
+
+export interface FrontmatterMigrationRow {
+  repo: string;
+  path: string;
+  kind: DocKind;
+  status: FrontmatterMigrationStatus;
+  fields: string[];
+  message?: string;
+}
+
+export interface FrontmatterConversion {
+  status: "convert" | "skipped" | "error";
+  content?: string;
+  fields: string[];
+  message?: string;
+}
+
+interface ParsedBoldField {
+  index: number;
+  label: string;
+  value: string;
+}
+
+const FIELD_KEYS: Record<string, string> = {
+  status: "status",
+  date: "date",
+  "last updated": "last_updated",
+  "date identified": "date",
+  "date resolved": "resolved",
+  "date fixed": "resolved",
+  prerequisites: "prerequisites",
+  severity: "severity",
+  resolved: "resolved",
+  affected: "affected",
+  impact: "affected",
+  owner: "owner",
+  continues: "continues",
+  "what you're picking up": "synopsis",
+};
+
+const FIELD_ORDER = [
+  "status",
+  "date",
+  "last_updated",
+  "status_note",
+  "prerequisites",
+  "owner",
+  "severity",
+  "resolved",
+  "affected",
+  "continues",
+  "synopsis",
+];
+
+function normalizeLabel(label: string): string {
+  return label.trim().toLowerCase();
+}
+
+function openingFields(body: string): ParsedBoldField[] {
+  const lines = body.split("\n");
+  const fields: ParsedBoldField[] = [];
+  for (let index = 0; index < Math.min(lines.length, 40); index++) {
+    const line = lines[index]!;
+    if (/^##\s+/.test(line) || (index > 0 && /^---\s*$/.test(line))) break;
+    const match =
+      line.match(/^\*\*([^*]+):\*\*\s*(.*)$/) ?? line.match(/^\*\*([^*]+)\*\*:\s*(.*)$/);
+    if (!match) continue;
+    const label = normalizeLabel(match[1]!);
+    if (!(label in FIELD_KEYS)) continue;
+    fields.push({ index, label, value: match[2]!.trim() });
+  }
+  return fields;
+}
+
+function cleanNote(value: string): string {
+  let note = value.trim().replace(/^[-–—\s]+/, "");
+  if (note.startsWith("(") && note.endsWith(")")) note = note.slice(1, -1);
+  return note
+    .replace(/\*\*/g, "")
+    .replace(/^[*_`]+|[*_`]+$/g, "")
+    .trim();
+}
+
+function cleanStatusToken(value: string): string {
+  return value.trim().replace(/^[*_`]+|[*_`]+$/g, "");
+}
+
+function splitStatus(
+  raw: string,
+  kind: DocKind,
+): { status: string; note?: string } | { error: string } {
+  const clean = raw.replace(/^[^\p{L}\p{N}]+/u, "").trim();
+  if (!clean) return { error: "empty status value" };
+
+  const separator = clean.match(/\s+[-–—]\s+|\s*\(/);
+  if (separator?.index != null) {
+    const token = cleanStatusToken(clean.slice(0, separator.index));
+    const normalized = normalizeStatus(token, kind);
+    if (normalized) {
+      const note = cleanNote(clean.slice(separator.index));
+      return { status: normalized, ...(note ? { note } : {}) };
+    }
+  }
+
+  const whole = normalizeStatus(cleanStatusToken(clean), kind);
+  if (whole) return { status: whole };
+
+  const words = clean.split(/\s+/);
+  for (const count of [1, 2, 3]) {
+    if (words.length <= count) continue;
+    const token = cleanStatusToken(words.slice(0, count).join(" "));
+    const normalized = normalizeStatus(token, kind);
+    if (!normalized) continue;
+    const note = cleanNote(words.slice(count).join(" "));
+    return { status: normalized, ...(note ? { note } : {}) };
+  }
+
+  return { error: `unsupported ${kind} status '${raw}'` };
+}
+
+function leadingDate(raw: string): { value: string; note?: string } {
+  const match = raw.match(/^(\d{4}-\d{2}-\d{2})(.*)$/);
+  if (!match) return { value: raw };
+  const note = cleanNote(match[2]!);
+  return { value: match[1]!, ...(note ? { note } : {}) };
+}
+
+function splitSeverity(
+  raw: string,
+): { severity: "low" | "medium" | "high" | "critical"; note?: string } | { error: string } {
+  const plain = raw.replace(/\*\*/g, "").trim();
+  const leading = plain.match(/^(low|medium|high|critical)\b(.*)$/i);
+  if (leading) {
+    const note = cleanNote(leading[2]!);
+    return {
+      severity: leading[1]!.toLowerCase() as "low" | "medium" | "high" | "critical",
+      ...(note ? { note } : {}),
+    };
+  }
+
+  const severity = /\bcritical\b/i.test(plain)
+    ? "critical"
+    : /\bhigh\b/i.test(plain)
+      ? "high"
+      : /\b(?:medium|moderate)\b/i.test(plain)
+        ? "medium"
+        : /\blow\b/i.test(plain)
+          ? "low"
+          : null;
+  if (!severity) return { error: `unsupported severity '${raw}'` };
+  return { severity, note: plain };
+}
+
+function serializeFields(fields: Record<string, unknown>): string {
+  return FIELD_ORDER.filter((key) => Object.hasOwn(fields, key))
+    .map((key) =>
+      dumpYaml(
+        { [key]: fields[key] },
+        {
+          schema: JSON_SCHEMA,
+          noRefs: true,
+          lineWidth: -1,
+          sortKeys: false,
+        },
+      ).trimEnd(),
+    )
+    .join("\n");
+}
+
+function mergeStatusNote(existing: unknown, notes: string[]): string | undefined {
+  const parts = [
+    ...(typeof existing === "string" && existing.trim() ? [existing.trim()] : []),
+    ...notes.filter(Boolean),
+  ];
+  return parts.length > 0 ? parts.join("; ") : undefined;
+}
+
+function valuesEqual(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+/**
+ * Convert one lifecycle document without writing it.
+ *
+ * Only recognized bold fields in the opening block are removed. Narrative
+ * labels and bold examples deeper in the body are left byte-for-byte intact.
+ */
+export function convertLifecycleFrontmatter(content: string, kind: DocKind): FrontmatterConversion {
+  const parsed = parseFrontmatter(content);
+  const boldFields = openingFields(parsed.body);
+  const statusFields = boldFields.filter((field) => field.label === "status");
+  const hasYamlStatus = typeof parsed.data.status === "string" && parsed.data.status.trim();
+  if (statusFields.length === 0 && !hasYamlStatus) {
+    const variant = parsed.body
+      .split("\n")
+      .slice(0, 40)
+      .find((line) => /^\*\*Status/i.test(line));
+    return {
+      status: variant ? "error" : "skipped",
+      fields: [],
+      message: variant ? `unsupported bold status shape '${variant.trim()}'` : "no opening status",
+    };
+  }
+  if (statusFields.length === 0 && hasYamlStatus && boldFields.length === 0) {
+    return {
+      status: "skipped",
+      fields: [],
+      message: "already has YAML status",
+    };
+  }
+  if (statusFields.length > 1) {
+    return {
+      status: "error",
+      fields: [],
+      message: "multiple opening Status fields",
+    };
+  }
+
+  const migrated: Record<string, unknown> = {};
+  const notes: string[] = [];
+  const remove = new Set<number>();
+  const hasOpeningDate = boldFields.some((field) => field.label === "date");
+
+  for (const field of boldFields) {
+    const key = FIELD_KEYS[field.label]!;
+    let value: unknown = field.value;
+    if (key === "status") {
+      const split = splitStatus(field.value, kind);
+      if ("error" in split) return { status: "error", fields: [], message: split.error };
+      value = split.status;
+      if (
+        split.note &&
+        /^\d{4}-\d{2}-\d{2}$/.test(split.note) &&
+        kind === "plan" &&
+        split.status === "proposed" &&
+        !hasOpeningDate &&
+        !Object.hasOwn(parsed.data, "date")
+      ) {
+        migrated.date = split.note;
+      } else if (split.note) {
+        notes.push(split.note);
+      }
+    } else if (key === "date" || key === "last_updated" || key === "resolved") {
+      const date = leadingDate(field.value);
+      value = date.value;
+      if (date.note) notes.push(`${key}: ${date.note}`);
+    } else if (key === "prerequisites" && field.value.toLowerCase() === "none") {
+      value = [];
+    } else if (key === "severity") {
+      const severity = splitSeverity(field.value);
+      if ("error" in severity) {
+        return { status: "error", fields: [], message: severity.error };
+      }
+      value = severity.severity;
+      if (severity.note) notes.push(`severity: ${severity.note}`);
+    }
+
+    if (Object.hasOwn(migrated, key)) {
+      return {
+        status: "error",
+        fields: [],
+        message: `multiple opening '${field.label}' fields`,
+      };
+    }
+    if (Object.hasOwn(parsed.data, key)) {
+      if (!valuesEqual(parsed.data[key], value)) {
+        return {
+          status: "error",
+          fields: [],
+          message: `YAML '${key}' conflicts with bold '${field.label}'`,
+        };
+      }
+    } else {
+      migrated[key] = value;
+    }
+    remove.add(field.index);
+  }
+
+  const statusNote = mergeStatusNote(parsed.data.status_note, notes);
+  if (notes.length > 0 && Object.hasOwn(parsed.data, "status_note")) {
+    return {
+      status: "error",
+      fields: [],
+      message: "YAML 'status_note' conflicts with migrated metadata notes",
+    };
+  }
+  if (statusNote) {
+    migrated.status_note = statusNote;
+  }
+
+  const body = parsed.body
+    .split("\n")
+    .filter((_, index) => !remove.has(index))
+    .join("\n")
+    .replace(/^\n+/, "");
+
+  const newFields = serializeFields(migrated);
+  const yaml = parsed.raw ? `${parsed.raw.trimEnd()}\n${newFields}`.trim() : newFields;
+  const next = `---\n${yaml}\n---\n\n${body}`;
+
+  return {
+    status: "convert",
+    content: next,
+    fields: Object.keys(migrated),
+  };
+}
+
+function walkMarkdown(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  const files: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...walkMarkdown(path));
+    else if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "README.md") {
+      files.push(path);
+    }
+  }
+  return files;
+}
+
+function lifecycleFiles(repoPath: string): { path: string; kind: DocKind }[] {
+  const kinds: { dir: string; kind: DocKind }[] = [
+    { dir: "plans", kind: "plan" },
+    { dir: "issues", kind: "issue" },
+    { dir: "handoffs", kind: "handoff" },
+  ];
+  return kinds.flatMap(({ dir, kind }) =>
+    walkMarkdown(join(repoPath, "docs", dir)).map((path) => ({ path, kind })),
+  );
+}
+
+function isInitializedRepo(path: string): boolean {
+  return existsSync(join(path, ".git"));
+}
+
+function writeAtomic(path: string, content: string): void {
+  const temp = join(dirname(path), `.${Date.now()}-${process.pid}.frontmatter.tmp`);
+  writeFileSync(temp, content, "utf8");
+  renameSync(temp, path);
+}
+
+export function runFrontmatterMigration(opts: FrontmatterMigrationOpts): FrontmatterMigrationRow[] {
+  const targets = [
+    { name: "(root)", path: REPO_ROOT },
+    ...SUBMODULES.map((name) => ({ name, path: resolve(REPO_ROOT, name) })).filter((target) =>
+      isInitializedRepo(target.path),
+    ),
+  ];
+  const filter = opts.repo === "." ? "(root)" : opts.repo;
+  const selected = filter ? targets.filter((target) => target.name === filter) : targets;
+  if (filter && selected.length === 0) throw new Error(`Unknown repository: ${opts.repo}`);
+
+  const rows: FrontmatterMigrationRow[] = [];
+  const pending: { row: FrontmatterMigrationRow; path: string; content: string }[] = [];
+  for (const target of selected) {
+    for (const file of lifecycleFiles(target.path)) {
+      const displayPath = relative(REPO_ROOT, file.path);
+      let content: string;
+      try {
+        content = readFileSync(file.path, "utf8");
+      } catch {
+        rows.push({
+          repo: target.name,
+          path: displayPath,
+          kind: file.kind,
+          status: "error",
+          fields: [],
+          message: "unable to read file",
+        });
+        continue;
+      }
+
+      const conversion = convertLifecycleFrontmatter(content, file.kind);
+      if (conversion.status === "error" || conversion.status === "skipped") {
+        rows.push({
+          repo: target.name,
+          path: displayPath,
+          kind: file.kind,
+          status: conversion.status,
+          fields: conversion.fields,
+          message: conversion.message,
+        });
+        continue;
+      }
+
+      const row: FrontmatterMigrationRow = {
+        repo: target.name,
+        path: displayPath,
+        kind: file.kind,
+        status: "would-update",
+        fields: conversion.fields,
+      };
+      rows.push(row);
+      pending.push({ row, path: file.path, content: conversion.content! });
+    }
+  }
+
+  if (opts.apply && !rows.some((row) => row.status === "error")) {
+    for (const item of pending) {
+      writeAtomic(item.path, item.content);
+      item.row.status = "updated";
+    }
+  }
+  return rows.sort((a, b) => a.path.localeCompare(b.path));
+}

package/src/lib/docs-frontmatter.ts

@@ -0,0 +1,151 @@
+import { readFileSync } from "node:fs";
+import { JSON_SCHEMA, load as loadYaml } from "js-yaml";
+
+/**
+ * Shared YAML-frontmatter parsing + status reads for lifecycle docs
+ * (plans / issues / handoffs). Kept generic: no host-specific vocabulary, so
+ * it can live next to docs-sweep / docs-lint and ship in the published package.
+ */
+
+export interface ParsedFrontmatter {
+  /** Parsed YAML mapping (empty object when there is no frontmatter). */
+  data: Record<string, unknown>;
+  /** Document body after the closing `---` (or the whole text when none). */
+  body: string;
+  /** Raw YAML block text, or null when the doc has no frontmatter. */
+  raw: string | null;
+}
+
+/** Doc lifecycle kinds that carry a status. */
+export type DocKind = "plan" | "issue" | "handoff";
+
+// Leading `---\n … \n---` block. Tolerates a BOM and CRLF line endings.
+const FRONTMATTER_RE = /^?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+
+/**
+ * Split leading YAML frontmatter from a markdown document.
+ * Never throws: malformed YAML yields an empty `data` with the block still
+ * stripped from `body`, so status readers do not need try/catch.
+ */
+export function parseFrontmatter(text: string): ParsedFrontmatter {
+  const m = text.match(FRONTMATTER_RE);
+  if (!m) return { data: {}, body: text, raw: null };
+  let data: Record<string, unknown> = {};
+  try {
+    // JSON_SCHEMA keeps values predictable: `date: 2026-07-08` stays a string
+    // instead of becoming a Date (the default schema's timestamp type), and
+    // there are no YAML 1.1 bool surprises (`no`/`yes`/`on`).
+    const parsed = loadYaml(m[1]!, { schema: JSON_SCHEMA });
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      data = parsed as Record<string, unknown>;
+    }
+  } catch {
+    data = {};
+  }
+  return { data, body: text.slice(m[0].length), raw: m[1]! };
+}
+
+/**
+ * Kind-independent token normalization (spacing / casing / punctuation
+ * variants). Kind-specific collapses (done -> shipped vs resolved) are applied
+ * in `normalizeStatus`.
+ */
+const GENERIC_NORMALIZE: Record<string, string> = {
+  in_progress: "in-progress",
+  inprogress: "in-progress",
+  "in progress": "in-progress",
+  "in-progress": "in-progress",
+  wip: "in-progress",
+  "wont-fix": "wontfix",
+  wontfix: "wontfix",
+  proposed: "proposed",
+  abandoned: "abandoned",
+  open: "open",
+  resolved: "resolved",
+  shipped: "shipped",
+};
+
+// "done"-family tokens collapse to different canonical values per kind.
+const DONE_FAMILY = new Set(["done", "complete", "completed", "finished"]);
+const KIND_NORMALIZE: Record<DocKind, Record<string, string>> = {
+  plan: {
+    planning: "proposed",
+    draft: "proposed",
+    approved: "proposed",
+    plan: "proposed",
+    open: "proposed",
+    deferred: "proposed",
+    implemented: "shipped",
+    resolved: "shipped",
+    fixed: "shipped",
+    archived: "shipped",
+    shelved: "abandoned",
+  },
+  issue: {
+    "in progress": "open",
+    in_progress: "open",
+    "in-progress": "open",
+    blocked: "open",
+    mitigated: "open",
+    fixed: "resolved",
+    shipped: "resolved",
+  },
+  handoff: {
+    "in progress": "open",
+    in_progress: "open",
+    "in-progress": "open",
+    blocked: "open",
+    fixed: "resolved",
+    shipped: "resolved",
+  },
+};
+const ALLOWED_BY_KIND: Record<DocKind, ReadonlySet<string>> = {
+  plan: new Set(["proposed", "in-progress", "shipped", "abandoned"]),
+  issue: new Set(["open", "resolved", "wontfix"]),
+  handoff: new Set(["open", "resolved", "abandoned"]),
+};
+const ALL_CANONICAL = new Set(Object.values(ALLOWED_BY_KIND).flatMap((values) => [...values]));
+
+/**
+ * Normalize a raw status token to the canonical enum for its kind.
+ * Returns null when the token can't be mapped (caller may fail loud).
+ */
+export function normalizeStatus(raw: string, kind?: DocKind): string | null {
+  const t = raw.trim().toLowerCase();
+  if (!t) return null;
+  if (DONE_FAMILY.has(t)) {
+    // plans ship; issues/handoffs resolve. Default to "shipped" when unknown.
+    return kind === "issue" || kind === "handoff" ? "resolved" : "shipped";
+  }
+  const normalized = (kind ? KIND_NORMALIZE[kind][t] : undefined) ?? GENERIC_NORMALIZE[t];
+  if (!normalized) return null;
+  const allowed = kind ? ALLOWED_BY_KIND[kind] : ALL_CANONICAL;
+  return allowed.has(normalized) ? normalized : null;
+}
+
+/** Read and normalize a doc's YAML lifecycle status, or null when absent/invalid. */
+export function readDocStatus(filePath: string, kind?: DocKind): string | null {
+  let content: string;
+  try {
+    content = readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+  return readDocStatusFromText(content, kind);
+}
+
+/** Same as {@link readDocStatus} but from an in-memory string (testable). */
+export function readDocStatusFromText(content: string, kind?: DocKind): string | null {
+  const { data } = parseFrontmatter(content);
+  const yamlStatus = data.status;
+  if (typeof yamlStatus === "string" && yamlStatus.trim()) {
+    return normalizeStatus(yamlStatus, kind);
+  }
+  return null;
+}
+
+/** Whether a doc carries a non-empty status in leading YAML frontmatter. */
+export function hasYamlStatus(content: string): boolean {
+  const { data } = parseFrontmatter(content);
+  return typeof data.status === "string" && data.status.trim().length > 0;
+}

package/src/lib/docs-index.ts

@@ -23,6 +23,7 @@ function isSubmoduleInitialized(name: string): boolean {
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { resolveBinName } from "../core/config.ts";
+import { readDocStatusFromText } from "./docs-frontmatter.ts";
 
 /**
  * Regenerates index READMEs in docs/audits/ and docs/issues/ directories.
@@ -66,10 +67,8 @@ function extractTitle(content: string, fallbackSlug: string): string {
   return fallbackSlug.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
-function extractStatus(content: string): string | undefined {
-  const head = content.split("\n").slice(0, 20).join("\n");
-  const match = head.match(/\*\*Status:\*\*\s*([a-zA-Z][a-zA-Z-]*)/);
-  return match ? match[1]!.toLowerCase() : undefined;
+export function extractStatus(content: string): string | undefined {
+  return readDocStatusFromText(content, "issue") ?? undefined;
 }
 
 function readEntries(dir: string, includeStatus: boolean): DatedEntry[] {
@@ -138,7 +137,7 @@ function defaultPreamble(kind: "audits" | "issues"): string {
         "# Issues",
         "",
         "Date-stamped post-mortems and investigations. File names follow `YYYY-MM-DD_<slug>.md`.",
-        "Each file carries a `**Status:**` line (open | resolved | wontfix).",
+        "Each file carries lifecycle status in leading YAML frontmatter.",
         "",
         regen,
         "",

package/src/lib/docs-lint.ts

@@ -1,5 +1,6 @@
 import { existsSync as __existsSyncForDocs } from "node:fs";
 import { resolve as __resolveForDocs } from "node:path";
+import { hasYamlStatus } from "./docs-frontmatter.ts";
 import { sh } from "./exec.ts";
 
 // Module-level docs context, initialized by initDocsContext() before any
@@ -174,10 +175,13 @@ function isDeclaredMonolith(path: string): boolean {
   return /INTENTIONAL-MONOLITH/i.test(head);
 }
 
-/** Detect whether a file carries a Status line in its opening block */
-function hasStatusHeader(path: string): boolean {
-  const head = readHead(path, 15);
-  return /\*\*Status:\*\*/i.test(head);
+/** Detect whether a file carries lifecycle status in leading YAML frontmatter. */
+export function hasStatusHeader(path: string): boolean {
+  try {
+    return hasYamlStatus(readFileSync(path, "utf8"));
+  } catch {
+    return false;
+  }
 }
 
 // --- Individual checks ---
@@ -373,26 +377,28 @@ function checkChangelogNames(repoName: string, _repoPath: string, files: string[
   return violations;
 }
 
-/** Plans and issues must carry a Status header (content check, slow) */
+/** Plans, issues, and handoffs must carry YAML lifecycle status (content check, slow). */
 function checkStatusHeaders(repoName: string, repoPath: string, files: string[]): Violation[] {
   const violations: Violation[] = [];
-  const targetDirs = ["docs/plans/", "docs/issues/"];
+  const targetDirs = ["docs/plans/", "docs/issues/", "docs/handoffs/"];
   for (const rel of files) {
     const dirMatch = targetDirs.some((d) => rel.startsWith(d));
     if (!dirMatch) continue;
     const name = basename(rel);
     if (name === "README.md") continue;
-    // Skip archive subdir
-    if (rel.includes("/archive/")) continue;
     const full = join(repoPath, rel);
     if (!hasStatusHeader(full)) {
-      const kind = rel.startsWith("docs/plans/") ? "plan" : "issue";
+      const kind = rel.startsWith("docs/plans/")
+        ? "plan"
+        : rel.startsWith("docs/issues/")
+          ? "issue"
+          : "handoff";
       violations.push({
-        severity: "warning",
+        severity: "error",
         repo: repoName,
         path: join(repoName === "(root)" ? "" : repoName, rel),
         rule: "missing-status-header",
-        message: `${kind} missing **Status:** line in opening block`,
+        message: `${kind} missing status in leading YAML frontmatter`,
       });
     }
   }