harnery 0.32.0 → 0.34.0

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;
+}

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

@@ -0,0 +1,262 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { dump as dumpYaml, JSON_SCHEMA } from "js-yaml";
+import { parseFrontmatter } from "./docs-frontmatter.ts";
+import { managedDocsMetadataType } from "./docs-metadata-managed.ts";
+import { isDocsMetadataV2, validateDocsMetadataV2 } from "./docs-metadata-v2.ts";
+import { sh } from "./exec.ts";
+
+let REPO_ROOT = "";
+let SUBMODULES: readonly string[] = [];
+
+export function initDocsMetadataSyncContext(opts: {
+  repoRoot: string;
+  submodules: readonly string[];
+}): void {
+  REPO_ROOT = opts.repoRoot;
+  SUBMODULES = opts.submodules;
+}
+
+export interface DocsMetadataSyncOpts {
+  repo?: string;
+  files?: string[];
+  check?: boolean;
+  reviewed?: boolean;
+  now?: string;
+}
+
+export interface DocsMetadataSyncRow {
+  repo: string;
+  path: string;
+  status: "unchanged" | "updated" | "drift" | "invalid";
+  fields: string[];
+  message?: string;
+}
+
+type Target = { name: string; path: string };
+
+function targets(repo?: string): Target[] {
+  const all: Target[] = [
+    { name: "(root)", path: REPO_ROOT },
+    ...SUBMODULES.filter((name) => existsSync(join(REPO_ROOT, name, ".git"))).map((name) => ({
+      name,
+      path: resolve(REPO_ROOT, name),
+    })),
+  ];
+  const filter = repo === "." ? "(root)" : repo;
+  const selected = filter ? all.filter((target) => target.name === filter) : all;
+  if (filter && selected.length === 0) throw new Error(`Unknown repository: ${repo}`);
+  return selected;
+}
+
+async function changedFiles(target: Target, explicit: string[]): Promise<string[]> {
+  if (explicit.length > 0) return explicit;
+  const result = await sh("git diff --cached --name-only --diff-filter=ACMR -- '*.md'", {
+    cwd: target.path,
+  });
+  if (result.exitCode !== 0) throw new Error(result.stderr || "git diff failed");
+  return result.stdout.split("\n").filter(Boolean);
+}
+
+async function headContent(target: Target, path: string): Promise<string | null> {
+  const result = await sh(`git show HEAD:${JSON.stringify(path)}`, { cwd: target.path });
+  return result.exitCode === 0 ? result.stdout : null;
+}
+
+function semanticMetadata(data: Record<string, unknown>): Record<string, unknown> {
+  const copy = { ...data };
+  delete copy.created_at;
+  delete copy.updated_at;
+  delete copy.status_changed_at;
+  delete copy.reviewed_at;
+  delete copy.review_due_at;
+  delete copy.source_updated_at;
+  delete copy.resolved_at;
+  return copy;
+}
+
+function semanticChanged(
+  before: ReturnType<typeof parseFrontmatter> | null,
+  after: ReturnType<typeof parseFrontmatter>,
+): boolean {
+  if (!before || !isDocsMetadataV2(before.data)) return false;
+  return (
+    JSON.stringify(semanticMetadata(before.data)) !==
+      JSON.stringify(semanticMetadata(after.data)) ||
+    before.body.replaceAll("\r\n", "\n").trimEnd() !== after.body.replaceAll("\r\n", "\n").trimEnd()
+  );
+}
+
+function serialize(data: Record<string, unknown>, body: string): string {
+  const yaml = dumpYaml(data, {
+    schema: JSON_SCHEMA,
+    noRefs: true,
+    lineWidth: -1,
+    sortKeys: false,
+    quotingType: '"',
+  }).trimEnd();
+  return `---\n${yaml}\n---\n${body.replace(/^\n+/, "\n")}`;
+}
+
+function addDays(value: string, days: number): string {
+  const date = new Date(value);
+  date.setUTCDate(date.getUTCDate() + days);
+  return date.toISOString().replace(".000Z", "Z");
+}
+
+export async function runDocsMetadataSync(
+  opts: DocsMetadataSyncOpts,
+): Promise<DocsMetadataSyncRow[]> {
+  const now = opts.now ?? new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+  const rows: DocsMetadataSyncRow[] = [];
+  for (const target of targets(opts.repo)) {
+    for (const path of await changedFiles(target, opts.files ?? [])) {
+      const full = join(target.path, path);
+      if (!existsSync(full)) continue;
+      const currentText = readFileSync(full, "utf8");
+      const current = parseFrontmatter(currentText);
+      if (!managedDocsMetadataType(path, current.data, current.raw !== null)) continue;
+      if (!isDocsMetadataV2(current.data)) {
+        rows.push({
+          repo: target.name,
+          path,
+          status: "invalid",
+          fields: [],
+          message: "managed document must use harnery-doc/v2",
+        });
+        continue;
+      }
+      const beforeText = await headContent(target, path);
+      const before = beforeText === null ? null : parseFrontmatter(beforeText);
+      const contentChanged = semanticChanged(before, current);
+      const beforeV2 = before !== null && isDocsMetadataV2(before.data) ? before.data : null;
+      const statusChanged = beforeV2 !== null && beforeV2.status !== current.data.status;
+      const fields: string[] = [];
+      const expected = { ...current.data };
+      if (contentChanged) {
+        expected.updated_at = now;
+        fields.push("updated_at");
+      }
+      if (statusChanged) {
+        expected.status_changed_at = now;
+        fields.push("status_changed_at");
+        if (current.data.status === "resolved" && current.data.type === "issue") {
+          expected.resolved_at = now;
+          fields.push("resolved_at");
+        }
+      }
+      if (
+        !statusChanged &&
+        beforeV2 &&
+        current.data.status_changed_at !== beforeV2.status_changed_at
+      ) {
+        expected.status_changed_at = beforeV2.status_changed_at;
+        fields.push("status_changed_at");
+      }
+      if (opts.reviewed) {
+        if (current.data.type !== "runbook") {
+          rows.push({
+            repo: target.name,
+            path,
+            status: "invalid",
+            fields: [],
+            message: "--reviewed applies only to runbooks",
+          });
+          continue;
+        }
+        expected.reviewed_at = now;
+        expected.review_due_at = addDays(now, 180);
+        expected.updated_at = now;
+        fields.push("reviewed_at", "review_due_at", "updated_at");
+      }
+      if (beforeV2 && expected.created_at !== beforeV2.created_at) {
+        rows.push({
+          repo: target.name,
+          path,
+          status: "invalid",
+          fields: ["created_at"],
+          message: "created_at is immutable",
+        });
+        continue;
+      }
+      if (opts.check) {
+        const validation = validateDocsMetadataV2(current.data);
+        if (!validation.valid) {
+          rows.push({
+            repo: target.name,
+            path,
+            status: "invalid",
+            fields,
+            message: validation.issues
+              .map((issue) => `${issue.field}: ${issue.message}`)
+              .join("; "),
+          });
+          continue;
+        }
+        const drift: string[] = [];
+        if (beforeV2 && contentChanged && current.data.updated_at === beforeV2.updated_at) {
+          drift.push("updated_at");
+        }
+        if (beforeV2 && statusChanged) {
+          if (current.data.status_changed_at === beforeV2.status_changed_at) {
+            drift.push("status_changed_at");
+          }
+          if (current.data.status_changed_at !== current.data.updated_at) {
+            drift.push("status_changed_at");
+          }
+          if (
+            current.data.type === "issue" &&
+            current.data.status === "resolved" &&
+            current.data.resolved_at !== current.data.status_changed_at
+          ) {
+            drift.push("resolved_at");
+          }
+        }
+        if (
+          beforeV2 &&
+          !statusChanged &&
+          current.data.status_changed_at !== beforeV2.status_changed_at
+        ) {
+          drift.push("status_changed_at");
+        }
+        if (
+          opts.reviewed &&
+          beforeV2 &&
+          (current.data.reviewed_at === beforeV2.reviewed_at ||
+            current.data.review_due_at !== addDays(String(current.data.reviewed_at), 180))
+        ) {
+          drift.push("reviewed_at", "review_due_at");
+        }
+        const uniqueDrift = [...new Set(drift)];
+        rows.push({
+          repo: target.name,
+          path,
+          status: uniqueDrift.length ? "drift" : "unchanged",
+          fields: uniqueDrift,
+          ...(uniqueDrift.length
+            ? { message: `run docs metadata sync for ${uniqueDrift.join(", ")}` }
+            : {}),
+        });
+        continue;
+      }
+      const validation = validateDocsMetadataV2(expected);
+      if (!validation.valid) {
+        rows.push({
+          repo: target.name,
+          path,
+          status: "invalid",
+          fields,
+          message: validation.issues.map((issue) => `${issue.field}: ${issue.message}`).join("; "),
+        });
+        continue;
+      }
+      if (fields.length === 0) {
+        rows.push({ repo: target.name, path, status: "unchanged", fields: [] });
+        continue;
+      }
+      writeFileSync(full, serialize(expected, current.body), "utf8");
+      rows.push({ repo: target.name, path, status: "updated", fields: [...new Set(fields)] });
+    }
+  }
+  return rows;
+}

package/src/lib/docs-metadata-v2-schema.ts

@@ -0,0 +1,138 @@
+import { DOCS_METADATA_TYPES } from "./docs-metadata-v2.ts";
+
+const timestamp = {
+  type: "string",
+  pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+};
+const stringList = { type: "array", items: { type: "string", minLength: 1 }, uniqueItems: true };
+
+/** Editor-facing JSON Schema. The TypeScript validator remains authoritative. */
+export const docsMetadataV2Schema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://harnery.com/schemas/docs-metadata-v2.schema.json",
+  title: "Harnery Markdown metadata v2",
+  type: "object",
+  required: ["schema", "type", "created_at", "updated_at", "summary"],
+  properties: {
+    schema: { const: "harnery-doc/v2" },
+    type: { enum: DOCS_METADATA_TYPES },
+    created_at: timestamp,
+    updated_at: timestamp,
+    owner: { type: "string", pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    summary: { type: "string", minLength: 1 },
+    tags: { ...stringList, items: { type: "string", pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$" } },
+    relations: {
+      type: "object",
+      properties: Object.fromEntries(
+        ["depends_on", "supersedes", "superseded_by", "continues", "related"].map((key) => [
+          key,
+          stringList,
+        ]),
+      ),
+      additionalProperties: false,
+    },
+    access: {
+      type: "object",
+      properties: { roles: stringList, viewers: stringList },
+      additionalProperties: false,
+    },
+    status: { type: "string" },
+    status_changed_at: timestamp,
+    status_note: { type: "string", minLength: 1 },
+    severity: { enum: ["low", "medium", "high", "critical"] },
+    resolved_at: timestamp,
+    affected: stringList,
+    resolution: {
+      type: "object",
+      required: ["outcome"],
+      properties: { outcome: { type: "string", minLength: 1 }, commits: stringList },
+      additionalProperties: false,
+    },
+    title: { type: "string", minLength: 1 },
+    audience: { type: "string", minLength: 1 },
+    source: { type: "string", minLength: 1 },
+    reviewed_at: timestamp,
+    review_due_at: timestamp,
+    category: { type: "string", minLength: 1 },
+    aliases: stringList,
+    source_count: { type: "integer", minimum: 0 },
+    provenance: {
+      type: "object",
+      required: ["sources"],
+      properties: { sources: stringList },
+      additionalProperties: false,
+    },
+    primary_entity: { type: "string" },
+    source_pages: {},
+    source_tokens: {},
+    top_entities: stringList,
+    handle: { type: "string", minLength: 1 },
+    published: { type: "boolean" },
+    source_updated_at: timestamp,
+    source_id: { type: "string", minLength: 1 },
+    source_template: { type: "string", minLength: 1 },
+    product: {},
+    variant: {},
+    sku: {},
+    manufacturer: {},
+    customer: {},
+    bid_id: {},
+    drive_file_id: {},
+    drive_title: {},
+    quote_date: {},
+    revision: {},
+    batch_size: {},
+    order_size: {},
+    price: {},
+    source_pdf: {},
+    claims: {},
+    week: {},
+    coverage: {},
+  },
+  patternProperties: { "^x_": {} },
+  additionalProperties: false,
+  allOf: [
+    {
+      if: { properties: { type: { const: "plan" } }, required: ["type"] },
+      // biome-ignore lint/suspicious/noThenProperty: JSON Schema requires the then keyword for conditional validation.
+      then: {
+        required: ["status", "status_changed_at", "owner"],
+        properties: { status: { enum: ["proposed", "in-progress", "shipped", "abandoned"] } },
+      },
+    },
+    {
+      if: { properties: { type: { const: "issue" } }, required: ["type"] },
+      // biome-ignore lint/suspicious/noThenProperty: JSON Schema requires the then keyword for conditional validation.
+      then: {
+        required: ["status", "status_changed_at", "owner", "severity"],
+        properties: { status: { enum: ["open", "resolved", "wontfix"] } },
+      },
+    },
+    {
+      if: { properties: { type: { const: "handoff" } }, required: ["type"] },
+      // biome-ignore lint/suspicious/noThenProperty: JSON Schema requires the then keyword for conditional validation.
+      then: {
+        required: ["status", "status_changed_at", "owner"],
+        properties: { status: { enum: ["open", "resolved", "abandoned"] } },
+      },
+    },
+    {
+      if: { properties: { type: { const: "runbook" } }, required: ["type"] },
+      // biome-ignore lint/suspicious/noThenProperty: JSON Schema requires the then keyword for conditional validation.
+      then: { required: ["owner", "reviewed_at", "review_due_at"] },
+    },
+    {
+      if: {
+        properties: { type: { enum: ["book", "entity", "concept", "query", "page"] } },
+        required: ["type"],
+      },
+      // biome-ignore lint/suspicious/noThenProperty: JSON Schema requires the then keyword for conditional validation.
+      then: { required: ["title", "category", "source_count", "provenance"] },
+    },
+    {
+      if: { properties: { type: { const: "synced-page" } }, required: ["type"] },
+      // biome-ignore lint/suspicious/noThenProperty: JSON Schema requires the then keyword for conditional validation.
+      then: { required: ["title", "handle", "published", "source", "source_updated_at"] },
+    },
+  ],
+};