harnery 0.33.0 → 0.34.1

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"] },
+    },
+  ],
+};