@docsworth/cli 0.0.0-stage → 0.2.0

package/dist/core/config.d.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { UserError } from "./errors.js";
+export declare const CONFIG_PATH = ".knowledge/config.yaml";
+/** The MCP tools a policy can name (kept here so config doesn't import the server). */
+export declare const POLICY_TOOLS: readonly ["search", "read", "list", "stale", "propose_edit", "verify", "draft_page"];
+declare const MirrorSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"confluence">;
+    name: z.ZodDefault<z.ZodString>;
+    base_url: z.ZodString;
+    spaces: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        acl: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"notion">;
+    name: z.ZodDefault<z.ZodString>;
+    root_page_ids: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    acl: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>], "kind">;
+export declare const ConfigSchema: z.ZodObject<{
+    format: z.ZodDefault<z.ZodLiteral<1>>;
+    knowledge_root: z.ZodDefault<z.ZodString>;
+    github: z.ZodObject<{
+        org: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        repo: z.ZodOptional<z.ZodString>;
+        default_branch: z.ZodOptional<z.ZodString>;
+        api_url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    sla: z.ZodDefault<z.ZodObject<{
+        due_soon_days: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    usage_log: z.ZodDefault<z.ZodBoolean>;
+    audit_log: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        dir: z.ZodOptional<z.ZodString>;
+        include_queries: z.ZodDefault<z.ZodBoolean>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        retention_days: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    skills: z.ZodDefault<z.ZodObject<{
+        out_dir: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    mirror: z.ZodDefault<z.ZodObject<{
+        out_dir: z.ZodDefault<z.ZodString>;
+        sources: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"confluence">;
+            name: z.ZodDefault<z.ZodString>;
+            base_url: z.ZodString;
+            spaces: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                acl: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"notion">;
+            name: z.ZodDefault<z.ZodString>;
+            root_page_ids: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            acl: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>], "kind">>>;
+        serve: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    policy: z.ZodDefault<z.ZodObject<{
+        admins: z.ZodOptional<z.ZodString>;
+        tools: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+            draft_page: "draft_page";
+            list: "list";
+            propose_edit: "propose_edit";
+            read: "read";
+            search: "search";
+            stale: "stale";
+            verify: "verify";
+        }> & z.core.$partial, z.ZodObject<{
+            teams: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>>;
+        writes: z.ZodDefault<z.ZodEnum<{
+            disabled: "disabled";
+            enabled: "enabled";
+        }>>;
+        require_human_approval: z.ZodDefault<z.ZodBoolean>;
+        include_stale: z.ZodDefault<z.ZodEnum<{
+            allowed: "allowed";
+            denied: "denied";
+        }>>;
+        identity_cache_seconds: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    digest: z.ZodDefault<z.ZodObject<{
+        slack_webhook_env: z.ZodDefault<z.ZodString>;
+        team_webhooks: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    audit_http: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>;
+export type Config = z.infer<typeof ConfigSchema>;
+export type MirrorSourceConfig = z.infer<typeof MirrorSourceSchema>;
+export declare class ConfigError extends UserError {
+}
+export declare function loadConfig(repoRoot: string): Config;
+export {};

package/dist/core/config.js

@@ -0,0 +1,131 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { UserError } from "./errors.js";
+import { insecureUrl } from "./url.js";
+export const CONFIG_PATH = ".knowledge/config.yaml";
+/** The MCP tools a policy can name (kept here so config doesn't import the server). */
+export const POLICY_TOOLS = ["search", "read", "list", "stale", "propose_edit", "verify", "draft_page"];
+const TeamSlug = z.string().regex(/^[a-z0-9][a-z0-9_-]*$/, "a lowercase team slug like `platform`");
+const MirrorSourceSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("confluence"),
+        name: z.string().default("confluence"),
+        base_url: z.string().url().superRefine((u, ctx) => {
+            const why = insecureUrl(u);
+            if (why)
+                ctx.addIssue({ code: "custom", message: `base_url ${why}` });
+        }),
+        spaces: z.array(z.object({ key: z.string().min(1), acl: z.string().default("internal") })).min(1),
+    }),
+    z.object({
+        kind: z.literal("notion"),
+        name: z.string().default("notion"),
+        root_page_ids: z.array(z.string()).default([]),
+        acl: z.string().default("internal"),
+    }),
+]);
+export const ConfigSchema = z.object({
+    format: z.literal(1).default(1),
+    knowledge_root: z.string().default("knowledge"),
+    github: z.object({
+        /** Team owners resolve to @<org>/<team>. Required even for local-only repos. */
+        org: z.string().min(1).transform((s) => s.toLowerCase()),
+        /** owner/name. When set, GitHub is the ACL authority and a token is required. */
+        repo: z
+            .string()
+            .regex(/^[\w.-]+\/[\w.-]+$/, "owner/name")
+            .optional(),
+        default_branch: z.string().optional(),
+        /** REST API base for GitHub Enterprise Server, e.g. https://ghe.example.com/api/v3. */
+        api_url: z
+            .string()
+            .url()
+            .superRefine((u, ctx) => {
+            const why = insecureUrl(u);
+            if (why)
+                ctx.addIssue({ code: "custom", message: `github.api_url ${why}` });
+        })
+            .optional(),
+    }),
+    sla: z.object({ due_soon_days: z.number().int().min(0).default(14) }).default({ due_soon_days: 14 }),
+    /** Append page-id-only read events to .knowledge/usage.jsonl (feeds the digest). */
+    usage_log: z.boolean().default(false),
+    /** The attributed audit log (src/core/audit-log.ts). Off unless enabled. */
+    audit_log: z
+        .object({
+        enabled: z.boolean().default(false),
+        /** Default: a state directory outside the checkout. Inside it, git must ignore it. */
+        dir: z.string().min(1).optional(),
+        /** Record search query text. Off: queries can carry sensitive text. */
+        include_queries: z.boolean().default(false),
+        /** Fail a tool call (closed) when its event can't be written. */
+        required: z.boolean().default(false),
+        retention_days: z.number().int().min(1).default(365),
+    })
+        .strict() // `requred: true` must fail, not quietly make the log optional
+        // "Required" with nothing enabled would quietly mean no audit log at all.
+        .refine((a) => !a.required || a.enabled, { message: "audit_log.required needs audit_log.enabled: true (otherwise nothing is audited)" })
+        .default({ enabled: false, include_queries: false, required: false, retention_days: 365 }),
+    skills: z.object({ out_dir: z.string().default("skills") }).default({ out_dir: "skills" }),
+    mirror: z
+        .object({
+        out_dir: z.string().default(".knowledge/mirror"),
+        sources: z.array(MirrorSourceSchema).default([]),
+        /** Serve mirrored pages to agents as non-citable context (v0.2 L2). Off by default. */
+        serve: z.boolean().default(false),
+    })
+        .default({ out_dir: ".knowledge/mirror", sources: [], serve: false }),
+    /** Org policy and roles (src/core/policy.ts). Every default keeps v0.1 behaviour. */
+    policy: z
+        .object({
+        /** The team that must own .knowledge/config.yaml and CODEOWNERS in CODEOWNERS (lint). */
+        admins: TeamSlug.optional(),
+        /** Per-tool allowlists. An empty list disables the tool for everyone. */
+        tools: z.partialRecord(z.enum(POLICY_TOOLS), z.object({ teams: z.array(TeamSlug) }).strict()).default({}),
+        /** `disabled`: propose_edit and verify are not offered at all. */
+        writes: z.enum(["enabled", "disabled"]).default("enabled"),
+        /** Mark write tools so Claude Code asks a human on every call (defence in depth). */
+        require_human_approval: z.boolean().default(false),
+        /** `denied`: search never returns gated pages inline, even with include_stale. */
+        include_stale: z.enum(["allowed", "denied"]).default("allowed"),
+        /** How long team membership is cached for reads: the deprovisioning window. */
+        identity_cache_seconds: z.number().int().min(30).max(3600).default(300),
+    })
+        // A typo here must be an error, not a silently ignored key: `write: disabled`
+        // would otherwise leave writes on.
+        .strict()
+        .default({ tools: {}, writes: "enabled", require_human_approval: false, include_stale: "allowed", identity_cache_seconds: 300 }),
+    digest: z
+        .object({
+        /** Env var holding the shared Slack incoming-webhook URL. */
+        slack_webhook_env: z.string().default("SLACK_WEBHOOK_URL"),
+        /**
+         * Per-team webhook env vars. Each MUST point at that team's own private channel:
+         * restricted page titles are posted there by name. Shared channels go through
+         * slack_webhook_env, where restricted pages are only counted.
+         */
+        team_webhooks: z.record(z.string(), z.string()).default({}),
+    })
+        .default({ slack_webhook_env: "SLACK_WEBHOOK_URL", team_webhooks: {} }),
+    /** Pro: the audit collector. Docsworth pro parses it; core only reserves the key. */
+    audit_http: z.unknown().optional(),
+})
+    // Every top-level key is known, so a misspelled block (`polciy:`, `audit_lgo:`) is an
+    // error rather than a silently dropped one that would leave writes on or auditing off.
+    .strict();
+export class ConfigError extends UserError {
+}
+export function loadConfig(repoRoot) {
+    const abs = join(repoRoot, CONFIG_PATH);
+    if (!existsSync(abs))
+        throw new ConfigError(`no ${CONFIG_PATH} in ${repoRoot} (run \`docsworth init\`)`);
+    const raw = parseYaml(readFileSync(abs, "utf8"), { schema: "core" });
+    const result = ConfigSchema.safeParse(raw ?? {});
+    if (!result.success) {
+        const detail = result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+        throw new ConfigError(`invalid ${CONFIG_PATH}: ${detail}`);
+    }
+    return result.data;
+}

package/dist/core/coverage.d.ts

@@ -0,0 +1,25 @@
+import type { Repo } from "./repo.js";
+export interface CoverageRow {
+    team: string;
+    pages: number;
+    owned: number;
+    owned_pct: number;
+    /** Pages subject to review: everything except deprecated pages. */
+    reviewable: number;
+    within_sla: number;
+    within_sla_pct: number;
+}
+export interface Coverage {
+    as_of: string;
+    total: CoverageRow;
+    teams: CoverageRow[];
+}
+/** Team bucket for pages whose frontmatter is too broken to name an owner. */
+export declare const UNASSIGNED = "(unassigned)";
+/**
+ * Ownership coverage (§4.3): % of pages team-owned and % verified within SLA, per team.
+ * Invalid pages count as neither owned nor verified, so a broken page lowers coverage
+ * instead of disappearing from it.
+ */
+export declare function computeCoverage(repo: Repo, now: Date): Coverage;
+export declare function formatCoverage(c: Coverage): string;

package/dist/core/coverage.js

@@ -0,0 +1,41 @@
+import { pageStatus } from "./gate.js";
+import { withinSla } from "./sla.js";
+/** Team bucket for pages whose frontmatter is too broken to name an owner. */
+export const UNASSIGNED = "(unassigned)";
+const pct = (n, d) => (d === 0 ? 100 : Math.round((n / d) * 1000) / 10);
+function row(team, items) {
+    const owned = items.filter((i) => i.owned).length;
+    const reviewable = items.filter((i) => i.reviewable).length;
+    const within = items.filter((i) => i.reviewable && i.within).length;
+    return {
+        team,
+        pages: items.length,
+        owned,
+        owned_pct: pct(owned, items.length),
+        reviewable,
+        within_sla: within,
+        within_sla_pct: pct(within, reviewable),
+    };
+}
+/**
+ * Ownership coverage (§4.3): % of pages team-owned and % verified within SLA, per team.
+ * Invalid pages count as neither owned nor verified, so a broken page lowers coverage
+ * instead of disappearing from it.
+ */
+export function computeCoverage(repo, now) {
+    const byTeam = new Map();
+    const add = (team, item) => byTeam.set(team, [...(byTeam.get(team) ?? []), item]);
+    for (const page of repo.pages) {
+        const s = pageStatus(page, repo, now);
+        add(page.owner_team, { owned: s.owned, reviewable: page.status !== "deprecated", within: withinSla(s.sla.state) });
+    }
+    for (const _ of repo.invalid)
+        add(UNASSIGNED, { owned: false, reviewable: true, within: false });
+    const teams = [...byTeam.entries()].map(([team, items]) => row(team, items)).sort((a, b) => a.team.localeCompare(b.team));
+    return { as_of: now.toISOString().slice(0, 10), total: row("total", [...byTeam.values()].flat()), teams };
+}
+export function formatCoverage(c) {
+    const header = "team            pages  owned          within SLA";
+    const fmt = (r) => `${r.team.padEnd(15)} ${String(r.pages).padStart(5)}  ${`${r.owned}/${r.pages}`.padStart(6)} ${`${r.owned_pct}%`.padStart(6)}  ${`${r.within_sla}/${r.reviewable}`.padStart(6)} ${`${r.within_sla_pct}%`.padStart(6)}`;
+    return [`Ownership coverage as of ${c.as_of}`, header, ...c.teams.map(fmt), fmt(c.total)].join("\n");
+}

package/dist/core/duration.d.ts

@@ -0,0 +1,20 @@
+export type DurationUnit = "d" | "w" | "m" | "y";
+export interface Duration {
+    n: number;
+    unit: DurationUnit;
+}
+export declare const DURATION_RE: RegExp;
+export declare function parseDuration(s: unknown): Duration | null;
+/** Parse `YYYY-MM-DD` to UTC midnight; rejects impossible dates like 2026-02-30. */
+export declare function parseDate(s: unknown): Date | null;
+export declare function formatDate(d: Date): string;
+/** The UTC calendar day containing `now`. */
+export declare function utcToday(now: Date): Date;
+/**
+ * Add a duration. Days and weeks are fixed; months and years are calendar units
+ * clamped to the end of the target month (Jan 31 + 1m = Feb 28/29).
+ */
+export declare function addDuration(date: Date, dur: Duration): Date;
+/** Go back by a duration, clamping the same way (Mar 31 − 1m = Feb 28/29). */
+export declare function subtractDuration(date: Date, dur: Duration): Date;
+export declare function daysBetween(from: Date, to: Date): number;

package/dist/core/duration.js

@@ -0,0 +1,60 @@
+// Date-only calendar arithmetic for review SLAs.
+//
+// All dates are UTC midnight `Date`s produced by `parseDate`, so a page verified on
+// 2026-10-15 is due on the same calendar day for every reader regardless of timezone.
+export const DURATION_RE = /^([1-9]\d{0,3})([dwmy])$/;
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DAY_MS = 86_400_000;
+export function parseDuration(s) {
+    if (typeof s !== "string")
+        return null;
+    const m = DURATION_RE.exec(s.trim());
+    return m ? { n: Number(m[1]), unit: m[2] } : null;
+}
+/** Parse `YYYY-MM-DD` to UTC midnight; rejects impossible dates like 2026-02-30. */
+export function parseDate(s) {
+    if (typeof s !== "string")
+        return null;
+    const m = DATE_RE.exec(s.trim());
+    if (!m)
+        return null;
+    const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const date = new Date(Date.UTC(y, mo - 1, d));
+    const roundTrips = date.getUTCFullYear() === y && date.getUTCMonth() === mo - 1 && date.getUTCDate() === d;
+    return roundTrips ? date : null;
+}
+export function formatDate(d) {
+    return d.toISOString().slice(0, 10);
+}
+/** The UTC calendar day containing `now`. */
+export function utcToday(now) {
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+}
+/**
+ * Add a duration. Days and weeks are fixed; months and years are calendar units
+ * clamped to the end of the target month (Jan 31 + 1m = Feb 28/29).
+ */
+export function addDuration(date, dur) {
+    if (dur.unit === "d" || dur.unit === "w") {
+        return new Date(date.getTime() + dur.n * (dur.unit === "w" ? 7 : 1) * DAY_MS);
+    }
+    const months = dur.unit === "y" ? dur.n * 12 : dur.n;
+    const y = date.getUTCFullYear();
+    const targetMonth = date.getUTCMonth() + months;
+    const lastDayOfTarget = new Date(Date.UTC(y, targetMonth + 1, 0)).getUTCDate();
+    return new Date(Date.UTC(y, targetMonth, Math.min(date.getUTCDate(), lastDayOfTarget)));
+}
+/** Go back by a duration, clamping the same way (Mar 31 − 1m = Feb 28/29). */
+export function subtractDuration(date, dur) {
+    if (dur.unit === "d" || dur.unit === "w") {
+        return new Date(date.getTime() - dur.n * (dur.unit === "w" ? 7 : 1) * DAY_MS);
+    }
+    const months = dur.unit === "y" ? dur.n * 12 : dur.n;
+    const y = date.getUTCFullYear();
+    const targetMonth = date.getUTCMonth() - months;
+    const lastDayOfTarget = new Date(Date.UTC(y, targetMonth + 1, 0)).getUTCDate();
+    return new Date(Date.UTC(y, targetMonth, Math.min(date.getUTCDate(), lastDayOfTarget)));
+}
+export function daysBetween(from, to) {
+    return Math.round((to.getTime() - from.getTime()) / DAY_MS);
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * An error the person running the CLI can act on: it prints as its message alone and exits
+ * 2, rather than as a stack. It's recognized by a brand, not by its class, so the CLI tells
+ * Docsworth pro's errors apart without importing pro: pro is another package, and its errors
+ * may extend another copy of this class.
+ */
+export declare class UserError extends Error {
+    readonly userError: true;
+}
+/** Whether `err` is a UserError, from this copy of core or any other. */
+export declare function isUserError(err: unknown): err is Error;

package/dist/core/errors.js

@@ -0,0 +1,13 @@
+/**
+ * An error the person running the CLI can act on: it prints as its message alone and exits
+ * 2, rather than as a stack. It's recognized by a brand, not by its class, so the CLI tells
+ * Docsworth pro's errors apart without importing pro: pro is another package, and its errors
+ * may extend another copy of this class.
+ */
+export class UserError extends Error {
+    userError = true;
+}
+/** Whether `err` is a UserError, from this copy of core or any other. */
+export function isUserError(err) {
+    return err instanceof Error && err.userError === true;
+}

package/dist/core/frontmatter.d.ts

@@ -0,0 +1,17 @@
+export interface SplitDoc {
+    /** Parsed frontmatter mapping, or null when absent/unparseable (see `error`). */
+    data: Record<string, unknown> | null;
+    body: string;
+    error?: string;
+}
+export declare const FRONTMATTER_MAX: number;
+/**
+ * Split `---` frontmatter from a markdown file and parse it as YAML.
+ *
+ * The YAML "core" schema is used on purpose: under YAML 1.1 rules `2026-10-15` would
+ * become a Date and `review_every: 90d` could be coerced oddly. Here every scalar that
+ * isn't a plain number/bool/null stays a string, so dates round-trip exactly.
+ */
+export declare function splitFrontmatter(text: string): SplitDoc;
+/** Serialize frontmatter + body back to a markdown file (used by writes and promote). */
+export declare function joinFrontmatter(yaml: string, body: string): string;

package/dist/core/frontmatter.js

@@ -0,0 +1,40 @@
+import { parse as parseYaml } from "yaml";
+const OPEN = /^---\r?\n/;
+export const FRONTMATTER_MAX = 16 * 1024;
+const CLOSE = /\r?\n---[ \t]*(\r?\n|$)/;
+/**
+ * Split `---` frontmatter from a markdown file and parse it as YAML.
+ *
+ * The YAML "core" schema is used on purpose: under YAML 1.1 rules `2026-10-15` would
+ * become a Date and `review_every: 90d` could be coerced oddly. Here every scalar that
+ * isn't a plain number/bool/null stays a string, so dates round-trip exactly.
+ */
+export function splitFrontmatter(text) {
+    const open = OPEN.exec(text);
+    if (!open)
+        return { data: null, body: text, error: "missing frontmatter block" };
+    const rest = text.slice(open[0].length);
+    const close = CLOSE.exec(rest);
+    if (!close)
+        return { data: null, body: text, error: "unterminated frontmatter block" };
+    const yamlSrc = rest.slice(0, close.index);
+    const body = rest.slice(close.index + close[0].length);
+    // A page's frontmatter is a few hundred bytes; YAML parsing slows past linear on
+    // hostile input (64 KB of `}&`: 650 ms, paid on every reload).
+    if (Buffer.byteLength(yamlSrc, "utf8") > FRONTMATTER_MAX)
+        return { data: null, body, error: `frontmatter is over ${FRONTMATTER_MAX / 1024} KB` };
+    try {
+        const data = parseYaml(yamlSrc, { schema: "core" });
+        if (data === null || typeof data !== "object" || Array.isArray(data)) {
+            return { data: null, body, error: "frontmatter is not a mapping" };
+        }
+        return { data: data, body };
+    }
+    catch (err) {
+        return { data: null, body, error: `invalid YAML: ${err.message.split("\n")[0]}` };
+    }
+}
+/** Serialize frontmatter + body back to a markdown file (used by writes and promote). */
+export function joinFrontmatter(yaml, body) {
+    return `---\n${yaml.trimEnd()}\n---\n${body.startsWith("\n") ? body : `\n${body}`}`;
+}

package/dist/core/gate.d.ts

@@ -0,0 +1,17 @@
+import type { Page, Repo } from "./repo.js";
+import { type Sla } from "./sla.js";
+export interface PageStatus {
+    sla: Sla;
+    /** CODEOWNERS resolves to exactly one team of the org, and it equals owner_team. */
+    owned: boolean;
+    ownership_problem?: string;
+    /** May an agent cite this page? canonical + within SLA + owned. Not configurable. */
+    citable: boolean;
+    /** Why it is not citable, phrased for an agent's answer ("excluded: …"). */
+    gate_reason?: string;
+}
+/**
+ * The citation gate. Hard-coded on purpose (spec R11): no config may widen it, because
+ * a gate a team can switch off is the "rebuild Confluence with vectors" failure mode.
+ */
+export declare function pageStatus(page: Page, repo: Repo, now: Date): PageStatus;

package/dist/core/gate.js

@@ -0,0 +1,25 @@
+import { describeOwnershipProblem, resolveTeamOwner } from "./codeowners.js";
+import { computeSla, withinSla } from "./sla.js";
+/**
+ * The citation gate. Hard-coded on purpose (spec R11): no config may widen it, because
+ * a gate a team can switch off is the "rebuild Confluence with vectors" failure mode.
+ */
+export function pageStatus(page, repo, now) {
+    const sla = computeSla(page.last_verified, page.review_every, now, repo.config.sla.due_soon_days);
+    const own = resolveTeamOwner(repo.codeowners, page.path, repo.config.github.org);
+    const owned = own.ok && own.team === page.owner_team.toLowerCase();
+    const ownership_problem = own.ok
+        ? owned
+            ? undefined
+            : `owner_team is \`${page.owner_team}\` but CODEOWNERS assigns @${repo.config.github.org}/${own.team}`
+        : describeOwnershipProblem(own.problem, repo.config.github.org);
+    let gate_reason;
+    if (page.status !== "canonical")
+        gate_reason = `status is ${page.status}`;
+    else if (!withinSla(sla.state))
+        gate_reason =
+            sla.state === "overdue" ? `past review date (due ${sla.due}), owned by ${page.owner_team}` : "never verified";
+    else if (!owned)
+        gate_reason = `ownership unresolved: ${ownership_problem}`;
+    return { sla, owned, ownership_problem, citable: gate_reason === undefined, gate_reason };
+}

package/dist/core/github.d.ts

@@ -0,0 +1,152 @@
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export declare class GitHubError extends Error {
+    /** The HTTP status; 0 when GitHub didn't answer (a network error or a timeout). */
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    /** Response headers, e.g. `x-github-sso` on a 403 from an SSO-enforcing org. */
+    readonly headers: Headers | null;
+    /** GitHub's rate limits: a 429, or a 403 that says so (primary or secondary limit). */
+    readonly rateLimited: boolean;
+    /** Seconds GitHub asked to wait (`retry-after`, or until `x-ratelimit-reset`), if it said. */
+    readonly retryAfter: number | null;
+    constructor(
+    /** The HTTP status; 0 when GitHub didn't answer (a network error or a timeout). */
+    status: number, method: string, path: string, message: string, 
+    /** Response headers, e.g. `x-github-sso` on a 403 from an SSO-enforcing org. */
+    headers?: Headers | null, now?: number);
+}
+export interface RepoInfo {
+    full_name: string;
+    default_branch: string;
+    private: boolean;
+    permissions?: {
+        admin?: boolean;
+        push?: boolean;
+        pull?: boolean;
+    };
+    owner?: {
+        login: string;
+        id: number;
+    };
+}
+export interface TeamInfo {
+    slug: string;
+    organization: {
+        login: string;
+    };
+}
+export interface ContentFile {
+    sha: string;
+    content: string;
+    encoding: string;
+    path: string;
+}
+export interface PullInfo {
+    number: number;
+    html_url: string;
+    head: {
+        ref: string;
+    };
+    base: {
+        ref: string;
+    };
+}
+export declare class GitHubClient {
+    private readonly token;
+    private readonly fetch;
+    private readonly baseUrl;
+    private readonly sleep;
+    private readonly now;
+    private readonly timeoutMs;
+    constructor(token: string, opts?: {
+        fetch?: FetchLike;
+        baseUrl?: string;
+        sleep?: (ms: number) => Promise<void>;
+        now?: () => number;
+        timeoutMs?: number;
+    });
+    request<T>(method: string, path: string, body?: unknown, accept?: string): Promise<{
+        data: T;
+        headers: Headers;
+    }>;
+    private get;
+    /** Follow `Link: rel="next"` pagination; `onHeaders` sees every page's headers. */
+    paginate<T>(path: string, onHeaders?: (h: Headers) => void): Promise<T[]>;
+    getUser(): Promise<{
+        login: string;
+    }>;
+    getRepo(repo: string): Promise<RepoInfo>;
+    /**
+     * The caller's teams, and the ids of orgs GitHub left out because the token isn't
+     * authorized for their SAML SSO (`x-github-sso: partial-results; organizations=…`).
+     */
+    listMyTeams(): Promise<{
+        teams: TeamInfo[];
+        ssoWithheldOrgIds: string[];
+    }>;
+    /** Logins of a team's members (needs read:org, or members:read on a fine-grained token). */
+    listTeamMembers(org: string, team: string): Promise<string[]>;
+    /**
+     * Does a team have write access to a repo? GitHub ignores a CODEOWNERS team without it.
+     * true/false when GitHub shows the permission; null on a 404, which GitHub gives both
+     * for "no access" and for a team this caller can't see, so it proves nothing.
+     */
+    teamCanPush(org: string, team: string, repo: string): Promise<boolean | null>;
+    /** A user's permission on a repo: admin, maintain, write, triage, read or none. */
+    getUserPermission(repo: string, login: string): Promise<string>;
+    /** Ruleset rules that apply to a branch (readable with read access). */
+    getBranchRules(repo: string, branch: string): Promise<{
+        type: string;
+        parameters?: Record<string, unknown>;
+        ruleset_id?: number;
+    }[]>;
+    /** A ruleset, with `bypass_actors` when this token may see them (admins). */
+    getRuleset(repo: string, id: number): Promise<{
+        bypass_actors?: {
+            actor_type: string;
+            bypass_mode?: string;
+        }[];
+    }>;
+    /** Classic branch protection (GitHub answers 403/404 to callers without admin). */
+    getBranchProtection(repo: string, branch: string): Promise<{
+        required_pull_request_reviews?: {
+            require_code_owner_reviews?: boolean;
+            bypass_pull_request_allowances?: {
+                users?: unknown[];
+                teams?: unknown[];
+                apps?: unknown[];
+            };
+        };
+        enforce_admins?: {
+            enabled?: boolean;
+        };
+    }>;
+    getFile(repo: string, path: string, ref: string): Promise<ContentFile>;
+    getBranchSha(repo: string, branch: string): Promise<string>;
+    createBranch(repo: string, branch: string, sha: string): Promise<void>;
+    deleteBranch(repo: string, branch: string): Promise<void>;
+    /** Always pass `branch`: omitting it makes GitHub write to the default branch. */
+    putFile(repo: string, path: string, args: {
+        message: string;
+        content: string;
+        sha: string | undefined;
+        branch: string;
+    }): Promise<void>;
+    /** An open PR from `branch` into `base` in the same repo, if one exists. */
+    findPull(repo: string, branch: string, base: string): Promise<PullInfo | null>;
+    createPull(repo: string, args: {
+        title: string;
+        head: string;
+        base: string;
+        body: string;
+        draft?: boolean;
+    }): Promise<PullInfo>;
+}
+/** `required; url=https://…` or `partial-results; organizations=1,2`. */
+export declare function parseSsoHeader(value: string | null): {
+    required: boolean;
+    url: string | null;
+    organizations: string[];
+};
+export declare function decodeContent(file: ContentFile): string;