harnery 0.33.0 → 0.34.0

package/src/lib/docs-frontmatter.ts

@@ -45,85 +45,12 @@ export function parseFrontmatter(text: string): ParsedFrontmatter {
   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. */
+/** Read a canonical v2 lifecycle status, or null when absent or invalid. */
 export function readDocStatus(filePath: string, kind?: DocKind): string | null {
   let content: string;
   try {
@@ -137,11 +64,13 @@ export function readDocStatus(filePath: string, kind?: DocKind): string | null {
 /** 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;
+  if (data.schema !== "harnery-doc/v2") return null;
+  if (kind && data.type !== kind) return null;
+  if (typeof data.status !== "string") return null;
+  if (kind) return ALLOWED_BY_KIND[kind].has(data.status) ? data.status : null;
+  return Object.values(ALLOWED_BY_KIND).some((allowed) => allowed.has(data.status as string))
+    ? data.status
+    : null;
 }
 
 /** Whether a doc carries a non-empty status in leading YAML frontmatter. */

package/src/lib/docs-index.ts

@@ -30,6 +30,10 @@ import { readDocStatusFromText } from "./docs-frontmatter.ts";
  * Idempotent: safe to run on every commit. Reads the first ~30 lines of
  * each dated file to extract title and (for issues) status.
  *
+ * Targets: the host root, every initialized git submodule, and first-level
+ * in-tree packages that keep `docs/audits` or `docs/issues` without being
+ * git submodules. Marker rules are unchanged.
+ *
  * Preserves hand-written preambles. The command updates only the section
  * between `<!-- BEGIN INDEX -->` and `<!-- END INDEX -->` markers. If a
  * README exists without markers, the command refuses to overwrite it and
@@ -165,12 +169,38 @@ function buildNewReadme(kind: "audits" | "issues", body: string): string {
   return `${defaultPreamble(kind)}\n${BEGIN_MARKER}\n${body}${END_MARKER}\n`;
 }
 
-export async function runIndex(opts: IndexOpts): Promise<IndexResult[]> {
-  const targets: { name: string; path: string }[] = [{ name: "(root)", path: REPO_ROOT }];
+const SKIP_NESTED_DIR_NAMES = new Set(["node_modules", "dist", "target"]);
+
+function hasIndexableDocs(path: string): boolean {
+  return existsSync(join(path, "docs", "audits")) || existsSync(join(path, "docs", "issues"));
+}
+
+/** Root + initialized submodules + first-level in-tree packages with docs indexes. */
+export function collectIndexTargets(): { name: string; path: string }[] {
+  const byPath = new Map<string, { name: string; path: string }>();
+  const add = (name: string, path: string) => {
+    byPath.set(path, { name, path });
+  };
+  add("(root)", REPO_ROOT);
   for (const name of SUBMODULES) {
     if (!isSubmoduleInitialized(name)) continue;
-    targets.push({ name, path: submodulePath(name) });
+    add(name, submodulePath(name));
   }
+  if (!existsSync(REPO_ROOT)) return [...byPath.values()];
+  for (const ent of readdirSync(REPO_ROOT, { withFileTypes: true })) {
+    if (!ent.isDirectory() && !ent.isSymbolicLink()) continue;
+    if (ent.name.startsWith(".")) continue;
+    if (SKIP_NESTED_DIR_NAMES.has(ent.name)) continue;
+    if (isSubmoduleInitialized(ent.name)) continue;
+    const child = join(REPO_ROOT, ent.name);
+    if (!hasIndexableDocs(child)) continue;
+    add(ent.name, child);
+  }
+  return [...byPath.values()];
+}
+
+export async function runIndex(opts: IndexOpts): Promise<IndexResult[]> {
+  const targets = collectIndexTargets();
 
   const filter = opts.repo === "." ? "(root)" : opts.repo;
   const filtered = filter ? targets.filter((t) => t.name === filter) : targets;

package/src/lib/docs-lint.ts

@@ -1,6 +1,7 @@
 import { existsSync as __existsSyncForDocs } from "node:fs";
 import { resolve as __resolveForDocs } from "node:path";
 import { hasYamlStatus } from "./docs-frontmatter.ts";
+import { initDocsMetadataAuditContext, runDocsMetadataAudit } from "./docs-metadata-audit.ts";
 import { sh } from "./exec.ts";
 
 // Module-level docs context, initialized by initDocsContext() before any
@@ -22,6 +23,7 @@ export function initDocsContext(opts: {
   SUBMODULES = opts.submodules;
   EXTRA_EXCLUDED_PREFIXES = opts.extraExcludedPrefixes ?? [];
   DOCS_ROOT_ALLOWLIST = opts.docsRootAllowlist ?? [];
+  initDocsMetadataAuditContext({ repoRoot: opts.repoRoot, submodules: opts.submodules });
 }
 
 function submodulePath(name: string): string {
@@ -380,34 +382,6 @@ function checkChangelogNames(repoName: string, _repoPath: string, files: string[
   return violations;
 }
 
-/** 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/", "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;
-    const full = join(repoPath, rel);
-    if (!hasStatusHeader(full)) {
-      const kind = rel.startsWith("docs/plans/")
-        ? "plan"
-        : rel.startsWith("docs/issues/")
-          ? "issue"
-          : "handoff";
-      violations.push({
-        severity: "error",
-        repo: repoName,
-        path: join(repoName === "(root)" ? "" : repoName, rel),
-        rule: "missing-status-header",
-        message: `${kind} missing status in leading YAML frontmatter`,
-      });
-    }
-  }
-  return violations;
-}
-
 /** Intentional monoliths >30KB need a declaration banner */
 function checkMonolithDeclaration(
   repoName: string,
@@ -462,10 +436,22 @@ export async function runLint(opts: LintOpts): Promise<Violation[]> {
     violations.push(...checkChangelogNames(name, path, files));
 
     if (!opts.fast) {
-      violations.push(...checkStatusHeaders(name, path, files));
       violations.push(...checkMonolithDeclaration(name, path, files));
     }
   }
 
+  const metadataRows = await runDocsMetadataAudit({ repo: opts.repo });
+  for (const row of metadataRows) {
+    for (const issue of row.issues.filter((entry) => entry.severity === "error")) {
+      violations.push({
+        severity: "error",
+        repo: row.repo,
+        path: row.path,
+        rule: `metadata-v2:${issue.code}`,
+        message: issue.field ? `${issue.field}: ${issue.message}` : issue.message,
+      });
+    }
+  }
+
   return violations;
 }

package/src/lib/docs-metadata-audit.ts

@@ -0,0 +1,166 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { parseFrontmatter } from "./docs-frontmatter.ts";
+import { isManagedDocsMetadataFile, managedDocsMetadataType } from "./docs-metadata-managed.ts";
+import {
+  type DocsMetadataProfile,
+  type DocsMetadataValidationIssue,
+  docsMetadataProfileForType,
+  isDocsMetadataV2,
+  validateDocsMetadataV2,
+} from "./docs-metadata-v2.ts";
+import { sh } from "./exec.ts";
+
+let REPO_ROOT = "";
+let SUBMODULES: readonly string[] = [];
+
+export function initDocsMetadataAuditContext(opts: {
+  repoRoot: string;
+  submodules: readonly string[];
+}): void {
+  REPO_ROOT = opts.repoRoot;
+  SUBMODULES = opts.submodules;
+}
+
+export interface DocsMetadataAuditOpts {
+  repo?: string;
+}
+
+export type DocsMetadataAuditState = "valid" | "invalid" | "legacy" | "missing";
+
+export interface DocsMetadataAuditRow {
+  repo: string;
+  path: string;
+  state: DocsMetadataAuditState;
+  profile: DocsMetadataProfile | null;
+  issues: DocsMetadataValidationIssue[];
+}
+
+function isInitializedRepo(path: string): boolean {
+  return existsSync(join(path, ".git"));
+}
+
+async function trackedMarkdownFiles(repoPath: string): Promise<string[]> {
+  const result = await sh('git ls-files --cached "**/*.md" "*.md"', { cwd: repoPath });
+  if (result.exitCode !== 0 || !result.stdout.trim()) return [];
+  return result.stdout
+    .trim()
+    .split("\n")
+    .filter((path) => path.endsWith(".md"));
+}
+
+function auditFile(repoName: string, repoPath: string, path: string): DocsMetadataAuditRow | null {
+  let content: string;
+  try {
+    content = readFileSync(join(repoPath, path), "utf8");
+  } catch {
+    return {
+      repo: repoName,
+      path: join(repoName === "(root)" ? "" : repoName, path),
+      state: "missing",
+      profile: null,
+      issues: [
+        {
+          severity: "error",
+          code: "file_unreadable",
+          field: "",
+          message: "metadata file could not be read",
+        },
+      ],
+    };
+  }
+
+  const { data, raw } = parseFrontmatter(content);
+  const displayPath = join(repoName === "(root)" ? "" : repoName, path);
+  if (!isManagedDocsMetadataFile(path, data, raw !== null)) return null;
+  const expectedType = managedDocsMetadataType(path, data, raw !== null);
+  if (isDocsMetadataV2(data)) {
+    const result = validateDocsMetadataV2(data);
+    return {
+      repo: repoName,
+      path: displayPath,
+      state: result.valid ? "valid" : "invalid",
+      profile: result.profile,
+      issues: result.issues,
+    };
+  }
+
+  const state: DocsMetadataAuditState = raw === null ? "missing" : "legacy";
+  return {
+    repo: repoName,
+    path: displayPath,
+    state,
+    profile: expectedType ? docsMetadataProfileForType(expectedType) : null,
+    issues: [
+      {
+        severity: "error",
+        code: state === "missing" ? "missing_metadata" : "legacy_schema",
+        field: "schema",
+        message:
+          state === "missing"
+            ? "required document has no leading YAML metadata"
+            : "document still uses pre-v2 metadata",
+      },
+    ],
+  };
+}
+
+export async function runDocsMetadataAudit(
+  opts: DocsMetadataAuditOpts,
+): Promise<DocsMetadataAuditRow[]> {
+  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: DocsMetadataAuditRow[] = [];
+  for (const target of selected) {
+    const files = await trackedMarkdownFiles(target.path);
+    for (const path of files) {
+      const row = auditFile(target.name, target.path, path);
+      if (row) rows.push(row);
+    }
+  }
+
+  return rows.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export function auditDocsMetadataText(content: string, path: string): DocsMetadataAuditRow | null {
+  const root = resolve("/");
+  const parsed = parseFrontmatter(content);
+  if (!isManagedDocsMetadataFile(path, parsed.data, parsed.raw !== null)) return null;
+  const expectedType = managedDocsMetadataType(path, parsed.data, parsed.raw !== null);
+  if (isDocsMetadataV2(parsed.data)) {
+    const result = validateDocsMetadataV2(parsed.data);
+    return {
+      repo: "(root)",
+      path: relative(root, resolve(root, path)),
+      state: result.valid ? "valid" : "invalid",
+      profile: result.profile,
+      issues: result.issues,
+    };
+  }
+  const state = parsed.raw === null ? "missing" : "legacy";
+  return {
+    repo: "(root)",
+    path,
+    state,
+    profile: expectedType ? docsMetadataProfileForType(expectedType) : null,
+    issues: [
+      {
+        severity: "error",
+        code: state === "missing" ? "missing_metadata" : "legacy_schema",
+        field: "schema",
+        message:
+          state === "missing"
+            ? "required document has no leading YAML metadata"
+            : "document still uses pre-v2 metadata",
+      },
+    ],
+  };
+}

package/src/lib/docs-metadata-managed.ts

@@ -0,0 +1,83 @@
+import { basename } from "node:path";
+import { type DocsMetadataType, isDocsMetadataType, isDocsMetadataV2 } from "./docs-metadata-v2.ts";
+
+function normalized(path: string): string {
+  return path.replaceAll("\\", "/");
+}
+
+/**
+ * Paths whose Markdown carries frontmatter belonging to another system:
+ * generated mirrors of documents that live elsewhere, vendored vendor
+ * specifications, and the placeholder headers inside document templates.
+ */
+export function isExcludedDocsMetadataPath(path: string): boolean {
+  const rel = normalized(path);
+  const segments = rel.split("/");
+  return (
+    segments.includes(".wiki-data") ||
+    // Dashboard surfaces render from copies of other repositories' documents.
+    /(?:^|\/)content\/dashboards\//.test(rel) ||
+    /(?:^|\/)docs\/shopify\/admin-api\//.test(rel) ||
+    /(?:^|\/)docs\/templates\//.test(rel)
+  );
+}
+
+function lifecycleType(path: string): DocsMetadataType | null {
+  const rel = normalized(path);
+  if (basename(rel).toLowerCase() === "readme.md") return null;
+  // A repository may sit at any depth inside the host checkout, so the
+  // directory rules anchor on `docs/<kind>/` rather than a single optional
+  // path segment. A one-segment-only prefix hid every document in a
+  // repository nested two or more levels down.
+  if (/(?:^|\/)docs\/plans\//.test(rel)) return "plan";
+  if (/(?:^|\/)docs\/issues\//.test(rel)) return "issue";
+  if (/(?:^|\/)docs\/coordination\/issues\//.test(rel)) return "issue";
+  if (/(?:^|\/)docs\/handoffs\//.test(rel)) return "handoff";
+  if (/(?:^|\/)docs\/audits\//.test(rel)) return "audit";
+  if (/^harnery-dev\/plans\//.test(rel)) return "plan";
+  if (/^harnery-dev\/issues\//.test(rel)) return "issue";
+  return null;
+}
+
+/**
+ * Return the v2 type expected for a Markdown file that participates in the
+ * managed metadata contract. Unmanaged Markdown and unrelated YAML-frontmatter
+ * systems return null.
+ */
+export function managedDocsMetadataType(
+  path: string,
+  data: Record<string, unknown>,
+  hasFrontmatter: boolean,
+): DocsMetadataType | null {
+  const rel = normalized(path);
+  if (isExcludedDocsMetadataPath(rel)) return null;
+  if (isDocsMetadataType(data.type)) return data.type;
+
+  const lifecycle = lifecycleType(rel);
+  if (lifecycle) return lifecycle;
+
+  const name = basename(rel).toLowerCase();
+  if (/(?:^|\/)docs\/runbook\.md$/.test(rel) || (hasFrontmatter && /^.+-runbook\.md$/.test(name))) {
+    return "runbook";
+  }
+
+  return null;
+}
+
+/**
+ * Whether a Markdown file has to satisfy the v2 contract.
+ *
+ * A file that claims the v2 schema marker is always checked, even when its
+ * `type` is missing or misspelled. Deciding membership from the type alone
+ * let a typo drop the document out of the audit entirely, so an invalid
+ * header reported as nothing rather than as an error.
+ */
+export function isManagedDocsMetadataFile(
+  path: string,
+  data: Record<string, unknown>,
+  hasFrontmatter: boolean,
+): boolean {
+  if (isExcludedDocsMetadataPath(path)) return false;
+  if (isDocsMetadataV2(data)) return true;
+  return managedDocsMetadataType(path, data, hasFrontmatter) !== null;
+}