harnery 0.32.0 → 0.34.0

package/dist/lib/docs-metadata-v2.js

@@ -0,0 +1,424 @@
+export const DOCS_METADATA_SCHEMA_V2 = "harnery-doc/v2";
+export const DOCS_METADATA_TYPES = [
+    "plan",
+    "issue",
+    "handoff",
+    "runbook",
+    "topic",
+    "audit",
+    "book",
+    "entity",
+    "concept",
+    "query",
+    "page",
+    "inquiry",
+    "quote-sheet",
+    "weekly-post",
+    "synced-page",
+];
+const RFC3339_UTC_SECONDS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const PLAN_STATUSES = new Set(["proposed", "in-progress", "shipped", "abandoned"]);
+const ISSUE_STATUSES = new Set(["open", "resolved", "wontfix"]);
+const HANDOFF_STATUSES = new Set(["open", "resolved", "abandoned"]);
+const ISSUE_SEVERITIES = new Set(["low", "medium", "high", "critical"]);
+const LIFECYCLE_TYPES = new Set(["plan", "issue", "handoff"]);
+const WIKI_TYPES = new Set(["book", "entity", "concept", "query", "page"]);
+const SUPPORTED_TYPES = new Set(DOCS_METADATA_TYPES);
+const BASE_FIELDS = new Set([
+    "schema",
+    "type",
+    "created_at",
+    "updated_at",
+    "owner",
+    "summary",
+    "tags",
+    "relations",
+    "access",
+]);
+const PROFILE_FIELDS = {
+    lifecycle: new Set([
+        ...BASE_FIELDS,
+        "status",
+        "status_changed_at",
+        "status_note",
+        "severity",
+        "resolved_at",
+        "affected",
+        "resolution",
+    ]),
+    runbook: new Set([...BASE_FIELDS, "title", "audience", "source", "reviewed_at", "review_due_at"]),
+    wiki: new Set([
+        ...BASE_FIELDS,
+        "title",
+        "category",
+        "aliases",
+        "source_count",
+        "provenance",
+        "primary_entity",
+        "source_pages",
+        "source_tokens",
+        "top_entities",
+    ]),
+    synced: new Set([
+        ...BASE_FIELDS,
+        "title",
+        "handle",
+        "published",
+        "source",
+        "source_updated_at",
+        "source_id",
+        "source_template",
+    ]),
+    "quote-sheet": new Set([
+        ...BASE_FIELDS,
+        "title",
+        "status",
+        "product",
+        "variant",
+        "sku",
+        "manufacturer",
+        "customer",
+        "bid_id",
+        "drive_file_id",
+        "drive_title",
+        "quote_date",
+        "revision",
+        "batch_size",
+        "order_size",
+        "price",
+        "source_pdf",
+        "claims",
+    ]),
+    "weekly-post": new Set([...BASE_FIELDS, "title", "status", "week", "coverage"]),
+    inquiry: new Set([
+        ...BASE_FIELDS,
+        "title",
+        "status",
+        "status_changed_at",
+        "resolved_at",
+        "severity",
+        "affected",
+    ]),
+    general: BASE_FIELDS,
+};
+const LIFECYCLE_FIELDS = {
+    plan: new Set([...BASE_FIELDS, "status", "status_changed_at", "status_note"]),
+    issue: new Set([
+        ...BASE_FIELDS,
+        "status",
+        "status_changed_at",
+        "status_note",
+        "severity",
+        "resolved_at",
+        "affected",
+    ]),
+    handoff: new Set([...BASE_FIELDS, "status", "status_changed_at", "status_note", "resolution"]),
+};
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function add(issues, severity, code, field, message) {
+    issues.push({ severity, code, field, message });
+}
+export function docsMetadataProfileForType(type) {
+    if (LIFECYCLE_TYPES.has(type))
+        return "lifecycle";
+    if (type === "runbook")
+        return "runbook";
+    if (WIKI_TYPES.has(type))
+        return "wiki";
+    if (type === "synced-page")
+        return "synced";
+    if (type === "quote-sheet")
+        return "quote-sheet";
+    if (type === "weekly-post")
+        return "weekly-post";
+    if (type === "inquiry")
+        return "inquiry";
+    return "general";
+}
+export function isDocsMetadataType(value) {
+    return typeof value === "string" && SUPPORTED_TYPES.has(value);
+}
+function requireString(data, field, issues) {
+    const value = data[field];
+    if (typeof value !== "string" || value.trim() === "") {
+        add(issues, "error", "required_string", field, `${field} must be a non-empty string`);
+        return null;
+    }
+    return value;
+}
+function validateTimestamp(data, field, issues, required = true) {
+    const value = data[field];
+    if (value === undefined && !required)
+        return null;
+    if (typeof value !== "string" || !RFC3339_UTC_SECONDS.test(value)) {
+        add(issues, "error", "invalid_timestamp", field, `${field} must use RFC 3339 UTC seconds, for example 2026-08-19T19:47:53Z`);
+        return null;
+    }
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed) || new Date(parsed).toISOString().replace(".000Z", "Z") !== value) {
+        add(issues, "error", "invalid_timestamp", field, `${field} is not a real timestamp`);
+        return null;
+    }
+    return parsed;
+}
+function validateOwner(data, issues, required = false) {
+    if (data.owner === undefined && !required)
+        return;
+    const owner = requireString(data, "owner", issues);
+    if (owner && !SLUG.test(owner)) {
+        add(issues, "error", "invalid_owner", "owner", "owner must be a lowercase kebab-case id");
+    }
+}
+function validateSummary(data, issues, required = false) {
+    if (data.summary === undefined && !required)
+        return;
+    requireString(data, "summary", issues);
+}
+function validateOptionalString(data, field, issues) {
+    if (data[field] !== undefined)
+        requireString(data, field, issues);
+}
+function validateStringList(value, field, issues, itemPattern) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item.trim())) {
+        add(issues, "error", "invalid_list", field, `${field} must be a YAML list of strings`);
+        return null;
+    }
+    const items = value;
+    if (new Set(items).size !== items.length) {
+        add(issues, "error", "duplicate_list_item", field, `${field} contains duplicate values`);
+    }
+    if (itemPattern) {
+        for (const item of items) {
+            if (!itemPattern.test(item)) {
+                add(issues, "error", "invalid_list_item", field, `${field} contains invalid value '${item}'`);
+            }
+        }
+    }
+    return items;
+}
+function validateRelations(data, issues) {
+    if (data.relations === undefined)
+        return;
+    if (!isRecord(data.relations)) {
+        add(issues, "error", "invalid_relations", "relations", "relations must be a YAML mapping");
+        return;
+    }
+    const allowed = new Set(["depends_on", "supersedes", "superseded_by", "continues", "related"]);
+    for (const [key, value] of Object.entries(data.relations)) {
+        if (!allowed.has(key)) {
+            add(issues, "error", "unknown_relation", `relations.${key}`, `unknown relation '${key}'`);
+            continue;
+        }
+        validateStringList(value, `relations.${key}`, issues);
+    }
+}
+function validateAccess(data, issues) {
+    if (data.access === undefined)
+        return;
+    if (!isRecord(data.access)) {
+        add(issues, "error", "invalid_access", "access", "access must be a YAML mapping");
+        return;
+    }
+    const allowed = new Set(["roles", "viewers"]);
+    for (const key of Object.keys(data.access)) {
+        if (!allowed.has(key)) {
+            add(issues, "error", "unknown_access_field", `access.${key}`, `unknown access field '${key}'`);
+        }
+    }
+    if (data.access.roles !== undefined) {
+        validateStringList(data.access.roles, "access.roles", issues, SLUG);
+    }
+    if (data.access.viewers !== undefined) {
+        validateStringList(data.access.viewers, "access.viewers", issues, EMAIL);
+    }
+}
+function validateLifecycle(data, type, createdAt, updatedAt, issues) {
+    const status = requireString(data, "status", issues);
+    const allowed = type === "plan" ? PLAN_STATUSES : type === "issue" ? ISSUE_STATUSES : HANDOFF_STATUSES;
+    if (status && !allowed.has(status)) {
+        add(issues, "error", "invalid_status", "status", `status '${status}' is invalid for ${type}`);
+    }
+    const changedAt = validateTimestamp(data, "status_changed_at", issues);
+    if (createdAt !== null && changedAt !== null && changedAt < createdAt) {
+        add(issues, "error", "timestamp_order", "status_changed_at", "status_changed_at cannot precede created_at");
+    }
+    if (updatedAt !== null && changedAt !== null && changedAt > updatedAt) {
+        add(issues, "error", "timestamp_order", "status_changed_at", "status_changed_at cannot be later than updated_at");
+    }
+    validateOptionalString(data, "status_note", issues);
+    if (type === "issue") {
+        const severity = requireString(data, "severity", issues);
+        if (severity && !ISSUE_SEVERITIES.has(severity)) {
+            add(issues, "error", "invalid_severity", "severity", `severity '${severity}' must be low, medium, high, or critical`);
+        }
+        if (data.affected !== undefined)
+            validateStringList(data.affected, "affected", issues);
+        const resolvedAt = validateTimestamp(data, "resolved_at", issues, status === "resolved");
+        if (status !== "resolved" && resolvedAt !== null) {
+            add(issues, "error", "unexpected_resolved_at", "resolved_at", "resolved_at is only valid when status is resolved");
+        }
+        if (createdAt !== null && resolvedAt !== null && resolvedAt < createdAt) {
+            add(issues, "error", "timestamp_order", "resolved_at", "resolved_at cannot precede created_at");
+        }
+        if (updatedAt !== null && resolvedAt !== null && resolvedAt > updatedAt) {
+            add(issues, "error", "timestamp_order", "resolved_at", "resolved_at cannot be later than updated_at");
+        }
+    }
+    if (type === "handoff") {
+        const terminal = status === "resolved" || status === "abandoned";
+        if (terminal && !isRecord(data.resolution)) {
+            add(issues, "error", "missing_resolution", "resolution", "terminal handoffs require a resolution mapping");
+        }
+        if (!terminal && data.resolution !== undefined) {
+            add(issues, "error", "unexpected_resolution", "resolution", "open handoffs cannot carry resolution metadata");
+        }
+        if (isRecord(data.resolution)) {
+            if (typeof data.resolution.outcome !== "string" || !data.resolution.outcome.trim()) {
+                add(issues, "error", "invalid_resolution", "resolution.outcome", "resolution.outcome must be a non-empty string");
+            }
+            if (data.resolution.commits !== undefined) {
+                validateStringList(data.resolution.commits, "resolution.commits", issues);
+            }
+        }
+    }
+}
+function validateRunbook(data, updatedAt, issues) {
+    validateOptionalString(data, "title", issues);
+    validateOptionalString(data, "audience", issues);
+    validateOptionalString(data, "source", issues);
+    const reviewedAt = validateTimestamp(data, "reviewed_at", issues);
+    const reviewDueAt = validateTimestamp(data, "review_due_at", issues);
+    if (reviewedAt !== null && reviewDueAt !== null && reviewDueAt <= reviewedAt) {
+        add(issues, "error", "timestamp_order", "review_due_at", "review_due_at must be later than reviewed_at");
+    }
+    if (updatedAt !== null && reviewedAt !== null && reviewedAt > updatedAt) {
+        add(issues, "error", "timestamp_order", "reviewed_at", "reviewed_at cannot be later than updated_at");
+    }
+}
+function validateWiki(data, issues) {
+    requireString(data, "title", issues);
+    requireString(data, "category", issues);
+    if (data.aliases !== undefined)
+        validateStringList(data.aliases, "aliases", issues);
+    if (typeof data.source_count !== "number" ||
+        !Number.isInteger(data.source_count) ||
+        data.source_count < 0) {
+        add(issues, "error", "invalid_source_count", "source_count", "source_count must be a non-negative integer");
+    }
+    if (!isRecord(data.provenance)) {
+        add(issues, "error", "invalid_provenance", "provenance", "provenance must be a mapping");
+    }
+    else {
+        validateStringList(data.provenance.sources, "provenance.sources", issues);
+    }
+}
+function validateSynced(data, issues) {
+    requireString(data, "title", issues);
+    requireString(data, "handle", issues);
+    requireString(data, "source", issues);
+    validateTimestamp(data, "source_updated_at", issues);
+    if (typeof data.published !== "boolean") {
+        add(issues, "error", "invalid_boolean", "published", "published must be a boolean");
+    }
+    validateOptionalString(data, "source_id", issues);
+    validateOptionalString(data, "source_template", issues);
+}
+function validateQuoteSheet(data, issues) {
+    for (const field of ["title", "status", "product", "manufacturer", "quote_date", "source_pdf"]) {
+        requireString(data, field, issues);
+    }
+    if (typeof data.status === "string" &&
+        !new Set(["not-final", "unsigned", "signed", "final"]).has(data.status)) {
+        add(issues, "error", "invalid_status", "status", "quote-sheet status must be not-final, unsigned, signed, or final");
+    }
+}
+function validateWeeklyPost(data, issues) {
+    for (const field of ["title", "status", "week", "coverage"])
+        requireString(data, field, issues);
+}
+function validateInquiry(data, createdAt, updatedAt, issues) {
+    requireString(data, "title", issues);
+    const status = requireString(data, "status", issues);
+    if (status && !new Set(["open", "resolved", "abandoned"]).has(status)) {
+        add(issues, "error", "invalid_status", "status", `inquiry status '${status}' is invalid`);
+    }
+    const changedAt = validateTimestamp(data, "status_changed_at", issues);
+    if (createdAt !== null && changedAt !== null && changedAt < createdAt) {
+        add(issues, "error", "timestamp_order", "status_changed_at", "status_changed_at cannot precede created_at");
+    }
+    if (updatedAt !== null && changedAt !== null && changedAt > updatedAt) {
+        add(issues, "error", "timestamp_order", "status_changed_at", "status_changed_at cannot be later than updated_at");
+    }
+    const resolvedAt = validateTimestamp(data, "resolved_at", issues, status === "resolved");
+    if (status !== "resolved" && resolvedAt !== null) {
+        add(issues, "error", "unexpected_resolved_at", "resolved_at", "resolved_at is only valid when status is resolved");
+    }
+}
+/** Validate one parsed YAML frontmatter mapping against the harnery-doc/v2 contract. */
+export function validateDocsMetadataV2(data) {
+    const issues = [];
+    if (data.schema !== DOCS_METADATA_SCHEMA_V2) {
+        add(issues, "error", "invalid_schema", "schema", `schema must be '${DOCS_METADATA_SCHEMA_V2}'`);
+    }
+    const rawType = requireString(data, "type", issues);
+    const type = rawType && isDocsMetadataType(rawType) ? rawType : null;
+    if (rawType && !type) {
+        add(issues, "error", "invalid_type", "type", `unsupported document type '${rawType}'`);
+    }
+    const profile = type ? docsMetadataProfileForType(type) : null;
+    const createdAt = validateTimestamp(data, "created_at", issues);
+    const updatedAt = validateTimestamp(data, "updated_at", issues);
+    if (createdAt !== null && updatedAt !== null && updatedAt < createdAt) {
+        add(issues, "error", "timestamp_order", "updated_at", "updated_at cannot precede created_at");
+    }
+    if (data.tags !== undefined)
+        validateStringList(data.tags, "tags", issues, SLUG);
+    const lifecycleType = type !== null && LIFECYCLE_TYPES.has(type);
+    validateOwner(data, issues, lifecycleType || type === "runbook" || type === "inquiry");
+    validateSummary(data, issues, type !== null);
+    validateRelations(data, issues);
+    validateAccess(data, issues);
+    if (profile) {
+        const allowed = type && LIFECYCLE_TYPES.has(type)
+            ? LIFECYCLE_FIELDS[type]
+            : PROFILE_FIELDS[profile];
+        for (const key of Object.keys(data)) {
+            if (!allowed.has(key) && !key.startsWith("x_")) {
+                add(issues, "error", "unknown_field", key, `unknown ${profile} metadata field '${key}'`);
+            }
+        }
+    }
+    if (type && LIFECYCLE_TYPES.has(type)) {
+        validateLifecycle(data, type, createdAt, updatedAt, issues);
+    }
+    else if (type === "runbook") {
+        validateRunbook(data, updatedAt, issues);
+    }
+    else if (type && WIKI_TYPES.has(type)) {
+        validateWiki(data, issues);
+    }
+    else if (type === "synced-page") {
+        validateSynced(data, issues);
+    }
+    else if (type === "quote-sheet") {
+        validateQuoteSheet(data, issues);
+    }
+    else if (type === "weekly-post") {
+        validateWeeklyPost(data, issues);
+    }
+    else if (type === "inquiry") {
+        validateInquiry(data, createdAt, updatedAt, issues);
+    }
+    return {
+        valid: issues.every((issue) => issue.severity !== "error"),
+        profile,
+        issues,
+    };
+}
+export function isDocsMetadataV2(data) {
+    return data.schema === DOCS_METADATA_SCHEMA_V2;
+}

package/dist/lib/docs-new.d.ts

@@ -0,0 +1,11 @@
+export interface DocsNewOpts {
+    type: "plan" | "issue" | "handoff" | "runbook" | "topic";
+    path: string;
+    summary: string;
+    owner: string;
+    status?: string;
+    severity?: string;
+    now?: string;
+}
+export declare function createDocsFile(repoRoot: string, opts: DocsNewOpts): string;
+//# sourceMappingURL=docs-new.d.ts.map

package/dist/lib/docs-new.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-new.d.ts","sourceRoot":"","sources":["../../src/lib/docs-new.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CA8C1E"}

package/dist/lib/docs-new.js

@@ -0,0 +1,52 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { dump as dumpYaml, JSON_SCHEMA } from "js-yaml";
+import { validateDocsMetadataV2 } from "./docs-metadata-v2.js";
+export function createDocsFile(repoRoot, opts) {
+    const file = resolve(repoRoot, opts.path);
+    const relativePath = relative(resolve(repoRoot), file);
+    if (!relativePath || relativePath.startsWith("..") || isAbsolute(relativePath)) {
+        throw new Error("document path must stay inside the repository");
+    }
+    if (!file.endsWith(".md"))
+        throw new Error("document path must end in .md");
+    if (existsSync(file))
+        throw new Error(`document already exists: ${opts.path}`);
+    const now = opts.now ?? new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    const type = opts.type;
+    const data = {
+        schema: "harnery-doc/v2",
+        type,
+        created_at: now,
+        updated_at: now,
+        owner: opts.owner,
+        summary: opts.summary,
+    };
+    if (type === "plan" || type === "issue" || type === "handoff") {
+        data.status = opts.status ?? (type === "plan" ? "proposed" : "open");
+        data.status_changed_at = now;
+    }
+    if (type === "issue")
+        data.severity = opts.severity ?? "medium";
+    if (type === "runbook") {
+        data.reviewed_at = now;
+        const due = new Date(now);
+        due.setUTCDate(due.getUTCDate() + 180);
+        data.review_due_at = due.toISOString().replace(".000Z", "Z");
+    }
+    const validation = validateDocsMetadataV2(data);
+    if (!validation.valid) {
+        throw new Error(validation.issues.map((issue) => `${issue.field}: ${issue.message}`).join("; "));
+    }
+    const yaml = dumpYaml(data, { schema: JSON_SCHEMA, noRefs: true, lineWidth: -1 }).trimEnd();
+    const title = opts.path
+        .split("/")
+        .at(-1)
+        .replace(/\.md$/, "")
+        .replace(/^\d{4}-\d{2}-\d{2}_/, "")
+        .replace(/[-_]/g, " ")
+        .replace(/\b\w/g, (letter) => letter.toUpperCase());
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `---\n${yaml}\n---\n\n# ${title}\n\n${opts.summary}\n`, "utf8");
+    return file;
+}

package/dist/lib/docs-sweep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-sweep.d.ts","sourceRoot":"","sources":["../../src/lib/docs-sweep.ts"],"names":[],"mappings":"AAWA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAG/F;AAaD;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,SAAS,GACjB,cAAc,GACd,oBAAoB,GACpB,iBAAiB,GACjB,cAAc,GACd,oBAAoB,GACpB,iBAAiB,GACjB,mBAAmB,CAAC;AAUxB,KAAK,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,MAAM,CAgBlF;AAsND,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CA4BpE;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAKzD"}
+{"version":3,"file":"docs-sweep.d.ts","sourceRoot":"","sources":["../../src/lib/docs-sweep.ts"],"names":[],"mappings":"AAWA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAG/F;AAaD;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,SAAS,GACjB,cAAc,GACd,oBAAoB,GACpB,iBAAiB,GACjB,cAAc,GACd,oBAAoB,GACpB,iBAAiB,GACjB,mBAAmB,CAAC;AAUxB,KAAK,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,MAAM,CAgBlF;AAqOD,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CA4BpE;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAIzD"}

package/dist/lib/docs-sweep.js

@@ -1,6 +1,6 @@
 import { existsSync as __existsSyncForDocs } from "node:fs";
 import { resolve as __resolveForDocs } from "node:path";
-import { readDocStatus } from "./docs-frontmatter.js";
+import { parseFrontmatter, readDocStatus } from "./docs-frontmatter.js";
 import { sh } from "./exec.js";
 // Module-level docs context, initialized by initDocsContext() before any
 // other function in this file is called. The repo root + submodule list
@@ -17,7 +17,7 @@ function submodulePath(name) {
 function isSubmoduleInitialized(name) {
     return __existsSyncForDocs(__resolveForDocs(REPO_ROOT, name, ".git"));
 }
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 const STALLED_PLAN_DAYS = 90;
 const UNARCHIVED_SHIPPED_DAYS = 180;
@@ -97,7 +97,19 @@ function walkMdFiles(dir, skipReadme = false) {
     }
     return out;
 }
-function sweepPlans(repoName, repoPath, ages, items) {
+function metadataAgeDays(file, field, nowMs = Date.now()) {
+    try {
+        const value = parseFrontmatter(readFileSync(file, "utf8")).data[field];
+        if (typeof value !== "string")
+            return null;
+        const parsed = Date.parse(value);
+        return Number.isNaN(parsed) ? null : Math.floor((nowMs - parsed) / (1000 * 60 * 60 * 24));
+    }
+    catch {
+        return null;
+    }
+}
+function sweepPlans(repoName, repoPath, items) {
     const plansDir = join(repoPath, "docs", "plans");
     if (!existsSync(plansDir))
         return;
@@ -106,7 +118,7 @@ function sweepPlans(repoName, repoPath, ages, items) {
         const displayPath = join(repoName === "(root)" ? "" : repoName, rel);
         const isArchived = rel.includes("/archive/");
         const status = readDocStatus(full, "plan");
-        const age = ageDays(ages, rel);
+        const age = metadataAgeDays(full, "status_changed_at");
         if (age == null)
             continue;
         if (!isArchived && status === "in-progress" && age > STALLED_PLAN_DAYS) {
@@ -115,7 +127,7 @@ function sweepPlans(repoName, repoPath, ages, items) {
                 repo: repoName,
                 path: displayPath,
                 ageDays: age,
-                message: `plan is in-progress, last touched ${age}d ago; confirm still active or bump status`,
+                message: `plan has remained in-progress for ${age}d; confirm it is still active or change status`,
             });
         }
         if (!isArchived && status === "shipped" && age > UNARCHIVED_SHIPPED_DAYS) {
@@ -129,7 +141,7 @@ function sweepPlans(repoName, repoPath, ages, items) {
         }
     }
 }
-function sweepIssues(repoName, repoPath, ages, items) {
+function sweepIssues(repoName, repoPath, items) {
     const issuesDir = join(repoPath, "docs", "issues");
     if (!existsSync(issuesDir))
         return;
@@ -142,7 +154,7 @@ function sweepIssues(repoName, repoPath, ages, items) {
         const status = readDocStatus(full, "issue");
         if (status !== "open")
             continue;
-        const age = ageDays(ages, rel);
+        const age = metadataAgeDays(full, "status_changed_at");
         if (age == null || age <= OPEN_ISSUE_DAYS)
             continue;
         items.push({
@@ -154,7 +166,7 @@ function sweepIssues(repoName, repoPath, ages, items) {
         });
     }
 }
-function sweepHandoffs(repoName, repoPath, ages, items) {
+function sweepHandoffs(repoName, repoPath, items) {
     const handoffsDir = join(repoPath, "docs", "handoffs");
     if (!existsSync(handoffsDir))
         return;
@@ -163,7 +175,7 @@ function sweepHandoffs(repoName, repoPath, ages, items) {
         const status = readDocStatus(full, "handoff");
         if (status !== "open")
             continue;
-        const age = ageDays(ages, rel);
+        const age = metadataAgeDays(full, "status_changed_at");
         if (age == null || age <= COLD_HANDOFF_DAYS)
             continue;
         const displayPath = join(repoName === "(root)" ? "" : repoName, rel);
@@ -176,21 +188,26 @@ function sweepHandoffs(repoName, repoPath, ages, items) {
         });
     }
 }
-function sweepRunbook(repoName, repoPath, ages, items) {
-    const runbook = join(repoPath, "docs", "runbook.md");
-    if (!existsSync(runbook))
-        return;
-    const age = ageDays(ages, "docs/runbook.md");
-    if (age == null || age <= RUNBOOK_DAYS)
+function sweepRunbooks(repoName, repoPath, items) {
+    const docs = join(repoPath, "docs");
+    if (!existsSync(docs))
         return;
-    const displayPath = join(repoName === "(root)" ? "" : repoName, "docs/runbook.md");
-    items.push({
-        kind: "runbook-unverified",
-        repo: repoName,
-        path: displayPath,
-        ageDays: age,
-        message: `runbook hasn't been edited in ${age}d; re-verify procedures`,
-    });
+    for (const runbook of walkMdFiles(docs)) {
+        const metadata = parseFrontmatter(readFileSync(runbook, "utf8")).data;
+        if (metadata.schema !== "harnery-doc/v2" || metadata.type !== "runbook")
+            continue;
+        const age = metadataAgeDays(runbook, "reviewed_at");
+        if (age == null || age <= RUNBOOK_DAYS)
+            continue;
+        const rel = relative(repoPath, runbook);
+        items.push({
+            kind: "runbook-unverified",
+            repo: repoName,
+            path: join(repoName === "(root)" ? "" : repoName, rel),
+            ageDays: age,
+            message: `runbook has not been reviewed for ${age}d; verify it with docs metadata sync --reviewed`,
+        });
+    }
 }
 function sweepTopicDocs(repoName, repoPath, ages, items) {
     const docsDir = join(repoPath, "docs");
@@ -275,10 +292,10 @@ export async function runSweep(opts) {
     for (let i = 0; i < filtered.length; i++) {
         const { name, path } = filtered[i];
         const ages = ageMaps[i];
-        sweepPlans(name, path, ages, items);
-        sweepIssues(name, path, ages, items);
-        sweepHandoffs(name, path, ages, items);
-        sweepRunbook(name, path, ages, items);
+        sweepPlans(name, path, items);
+        sweepIssues(name, path, items);
+        sweepHandoffs(name, path, items);
+        sweepRunbooks(name, path, items);
         sweepTopicDocs(name, path, ages, items);
         await sweepDecisions(name, path, ages, items);
     }
@@ -293,7 +310,6 @@ export async function runSweep(opts) {
  */
 export async function countColdHandoffs() {
     const items = [];
-    const ages = await loadDocsAges(REPO_ROOT);
-    sweepHandoffs("(root)", REPO_ROOT, ages, items);
+    sweepHandoffs("(root)", REPO_ROOT, items);
     return items.length;
 }