@isaacriehm/cairn-core 0.1.0

package/dist/ground/quality-grades.js

@@ -0,0 +1,98 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { logger } from "../logger.js";
+import { qualityGradesPath, runsTerminalDir } from "./paths.js";
+const log = logger("ground.quality-grades");
+export function buildQualityGrades(opts) {
+    const dir = runsTerminalDir(opts.repoRoot);
+    const limit = opts.recentRunCount ?? 50;
+    const moduleAccum = new Map();
+    if (existsSync(dir)) {
+        const runIds = listRecentRuns(dir, limit);
+        for (const runId of runIds) {
+            const meta = readJsonIfExists(join(dir, runId, "meta.json"));
+            const sensors = readYamlIfExists(join(dir, runId, "sensor-results.yaml"));
+            const moduleKey = meta?.scoped_module ?? "unscoped";
+            const acc = moduleAccum.get(moduleKey) ?? {
+                passes: 0,
+                total: 0,
+                drifts: 0,
+                latest: "",
+            };
+            if (sensors) {
+                for (const s of sensors) {
+                    if (s.status === "skip")
+                        continue;
+                    acc.total += 1;
+                    if (s.status === "pass")
+                        acc.passes += 1;
+                }
+            }
+            if (meta?.finished_at && (!acc.latest || meta.finished_at > acc.latest)) {
+                acc.latest = meta.finished_at;
+            }
+            moduleAccum.set(moduleKey, acc);
+        }
+    }
+    const modules = [];
+    for (const [module, acc] of moduleAccum) {
+        const passRate = acc.total === 0 ? 1 : acc.passes / acc.total;
+        const score = Math.round(passRate * 100);
+        modules.push({
+            module,
+            score,
+            pass_rate: Number(passRate.toFixed(3)),
+            drift_count: acc.drifts,
+            last_updated: acc.latest || new Date().toISOString(),
+            recent_run_count: acc.total === 0 ? 0 : Math.ceil(acc.total / 10), // rough run count proxy
+        });
+    }
+    modules.sort((a, b) => a.score - b.score); // weakest first
+    return { version: 1, generated: new Date().toISOString(), modules };
+}
+export function writeQualityGrades(opts) {
+    const grades = buildQualityGrades(opts);
+    const path = qualityGradesPath(opts.repoRoot);
+    mkdirSync(resolve(path, ".."), { recursive: true });
+    writeFileSync(path, stringifyYaml(grades), "utf8");
+    log.debug({ path, modules: grades.modules.length }, "wrote quality grades");
+    return { grades, path };
+}
+function listRecentRuns(dir, limit) {
+    let dirents;
+    try {
+        dirents = readdirSync(dir, { withFileTypes: true, encoding: "utf8" });
+    }
+    catch {
+        return [];
+    }
+    const dirs = dirents.filter((d) => d.isDirectory()).map((d) => d.name);
+    dirs.sort((a, b) => {
+        const sa = statSync(join(dir, a)).mtimeMs;
+        const sb = statSync(join(dir, b)).mtimeMs;
+        return sb - sa;
+    });
+    return dirs.slice(0, limit);
+}
+function readJsonIfExists(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function readYamlIfExists(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return parseYaml(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=quality-grades.js.map

package/dist/ground/quality-grades.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-grades.js","sourceRoot":"","sources":["../../src/ground/quality-grades.ts"],"names":[],"mappings":"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"}

package/dist/ground/schemas.d.ts

@@ -0,0 +1,306 @@
+import { z } from "zod";
+export declare const Audience: z.ZodEnum<{
+    "ai-only": "ai-only";
+    dual: "dual";
+    "human-only": "human-only";
+}>;
+export type Audience = z.infer<typeof Audience>;
+export declare const ProvenanceFrontmatter: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodString>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        "ai-only": "ai-only";
+        dual: "dual";
+        "human-only": "human-only";
+    }>>;
+    generated: z.ZodOptional<z.ZodString>;
+    "verified-at": z.ZodOptional<z.ZodString>;
+    "source-commits": z.ZodOptional<z.ZodArray<z.ZodString>>;
+    supersedes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type ProvenanceFrontmatter = z.infer<typeof ProvenanceFrontmatter>;
+export declare const ManifestEntry: z.ZodObject<{
+    path: z.ZodString;
+    sha256: z.ZodString;
+    classification: z.ZodString;
+    audience: z.ZodOptional<z.ZodString>;
+    verified_at: z.ZodOptional<z.ZodString>;
+    generator: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    related_invariants: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ManifestEntry = z.infer<typeof ManifestEntry>;
+export declare const Manifest: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generated: z.ZodString;
+    generator: z.ZodOptional<z.ZodString>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodString;
+        classification: z.ZodString;
+        audience: z.ZodOptional<z.ZodString>;
+        verified_at: z.ZodOptional<z.ZodString>;
+        generator: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+        related_invariants: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Manifest = z.infer<typeof Manifest>;
+export declare const DecisionAssertion: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"schema_must_contain">;
+    table: z.ZodString;
+    column: z.ZodString;
+    column_type: z.ZodOptional<z.ZodString>;
+    nullable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"text_must_match">;
+    pattern: z.ZodString;
+    in_globs: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"text_must_not_match">;
+    pattern: z.ZodString;
+    in_globs: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"index_must_exist">;
+    table: z.ZodString;
+    columns: z.ZodArray<z.ZodString>;
+    where: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"ast_pattern">;
+    language: z.ZodString;
+    pattern: z.ZodString;
+    in_globs: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"file_must_not_be_modified">;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"query_must_filter_by">;
+    orm: z.ZodString;
+    in_globs: z.ZodArray<z.ZodString>;
+    table: z.ZodString;
+    columns: z.ZodArray<z.ZodString>;
+    operator: z.ZodEnum<{
+        in: "in";
+        eq: "eq";
+        between: "between";
+        is_not_null: "is_not_null";
+    }>;
+    require_combination: z.ZodEnum<{
+        and: "and";
+        or: "or";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"route_must_have_guard">;
+    in_globs: z.ZodArray<z.ZodString>;
+    guard: z.ZodString;
+    require_on: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"event_must_emit">;
+    in_globs: z.ZodArray<z.ZodString>;
+    after_method: z.ZodString;
+    event_key: z.ZodString;
+    payload_must_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"service_method_must_call">;
+    in_globs: z.ZodArray<z.ZodString>;
+    in_method: z.ZodString;
+    must_call: z.ZodString;
+    before_returning: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"human_review_hint">;
+    description: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type DecisionAssertion = z.infer<typeof DecisionAssertion>;
+export declare const DecisionFrontmatter: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    type: z.ZodOptional<z.ZodLiteral<"adr">>;
+    status: z.ZodEnum<{
+        draft: "draft";
+        accepted: "accepted";
+        superseded: "superseded";
+        archived: "archived";
+    }>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        "ai-only": "ai-only";
+        dual: "dual";
+        "human-only": "human-only";
+    }>>;
+    generated: z.ZodOptional<z.ZodString>;
+    "verified-at": z.ZodOptional<z.ZodString>;
+    "source-commits": z.ZodOptional<z.ZodArray<z.ZodString>>;
+    decided_at: z.ZodOptional<z.ZodString>;
+    decided_by: z.ZodOptional<z.ZodString>;
+    scope_globs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    supersedes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    superseded_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    assertions: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"schema_must_contain">;
+        table: z.ZodString;
+        column: z.ZodString;
+        column_type: z.ZodOptional<z.ZodString>;
+        nullable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"text_must_match">;
+        pattern: z.ZodString;
+        in_globs: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"text_must_not_match">;
+        pattern: z.ZodString;
+        in_globs: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"index_must_exist">;
+        table: z.ZodString;
+        columns: z.ZodArray<z.ZodString>;
+        where: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"ast_pattern">;
+        language: z.ZodString;
+        pattern: z.ZodString;
+        in_globs: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"file_must_not_be_modified">;
+        path: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"query_must_filter_by">;
+        orm: z.ZodString;
+        in_globs: z.ZodArray<z.ZodString>;
+        table: z.ZodString;
+        columns: z.ZodArray<z.ZodString>;
+        operator: z.ZodEnum<{
+            in: "in";
+            eq: "eq";
+            between: "between";
+            is_not_null: "is_not_null";
+        }>;
+        require_combination: z.ZodEnum<{
+            and: "and";
+            or: "or";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"route_must_have_guard">;
+        in_globs: z.ZodArray<z.ZodString>;
+        guard: z.ZodString;
+        require_on: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"event_must_emit">;
+        in_globs: z.ZodArray<z.ZodString>;
+        after_method: z.ZodString;
+        event_key: z.ZodString;
+        payload_must_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"service_method_must_call">;
+        in_globs: z.ZodArray<z.ZodString>;
+        in_method: z.ZodString;
+        must_call: z.ZodString;
+        before_returning: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"human_review_hint">;
+        description: z.ZodString;
+    }, z.core.$strip>], "kind">>>;
+    human_review_hint: z.ZodOptional<z.ZodString>;
+    related_invariants: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export type DecisionFrontmatter = z.infer<typeof DecisionFrontmatter>;
+export declare const InvariantFrontmatter: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    type: z.ZodOptional<z.ZodLiteral<"invariant">>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        superseded: "superseded";
+    }>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        "ai-only": "ai-only";
+        dual: "dual";
+        "human-only": "human-only";
+    }>>;
+    generated: z.ZodOptional<z.ZodString>;
+    "verified-at": z.ZodOptional<z.ZodString>;
+    source_run: z.ZodOptional<z.ZodString>;
+    source_decision: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    introduced_for_bug: z.ZodOptional<z.ZodString>;
+    sensor: z.ZodOptional<z.ZodString>;
+    e2e: z.ZodOptional<z.ZodString>;
+    naming_convention: z.ZodOptional<z.ZodString>;
+    superseded_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type InvariantFrontmatter = z.infer<typeof InvariantFrontmatter>;
+export declare const DecisionLedgerEntry: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodString;
+    scope_globs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    supersedes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    superseded_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type DecisionLedgerEntry = z.infer<typeof DecisionLedgerEntry>;
+export declare const InvariantLedgerEntry: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodString;
+    source_decision: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    superseded_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type InvariantLedgerEntry = z.infer<typeof InvariantLedgerEntry>;
+export declare const QualityGrade: z.ZodObject<{
+    module: z.ZodString;
+    score: z.ZodNumber;
+    pass_rate: z.ZodNumber;
+    drift_count: z.ZodNumber;
+    last_updated: z.ZodString;
+    recent_run_count: z.ZodNumber;
+}, z.core.$strip>;
+export type QualityGrade = z.infer<typeof QualityGrade>;
+export declare const QualityGrades: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generated: z.ZodString;
+    modules: z.ZodArray<z.ZodObject<{
+        module: z.ZodString;
+        score: z.ZodNumber;
+        pass_rate: z.ZodNumber;
+        drift_count: z.ZodNumber;
+        last_updated: z.ZodString;
+        recent_run_count: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type QualityGrades = z.infer<typeof QualityGrades>;
+export declare const DriftEvent: z.ZodObject<{
+    ts: z.ZodString;
+    kind: z.ZodEnum<{
+        frontmatter_stale: "frontmatter_stale";
+        generator_drift: "generator_drift";
+        broken_link: "broken_link";
+        orphan_path: "orphan_path";
+        manifest_hash_changed: "manifest_hash_changed";
+    }>;
+    path: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        soft: "soft";
+        hard: "hard";
+    }>>;
+}, z.core.$strip>;
+export type DriftEvent = z.infer<typeof DriftEvent>;

package/dist/ground/schemas.js

@@ -0,0 +1,188 @@
+import { z } from "zod";
+export const Audience = z.enum(["ai-only", "dual", "human-only"]);
+export const ProvenanceFrontmatter = z
+    .object({
+    type: z.string().optional(),
+    status: z.string().optional(),
+    audience: Audience.optional(),
+    generated: z.string().optional(),
+    "verified-at": z.string().optional(),
+    "source-commits": z.array(z.string()).optional(),
+    supersedes: z.string().nullable().optional(),
+})
+    .passthrough();
+export const ManifestEntry = z.object({
+    path: z.string(),
+    sha256: z.string().length(64),
+    classification: z.string(),
+    audience: z.string().optional(),
+    verified_at: z.string().optional(),
+    generator: z.string().optional(),
+    source: z.string().optional(),
+    related_invariants: z.array(z.string()).optional(),
+});
+export const Manifest = z.object({
+    version: z.literal(1),
+    generated: z.string(),
+    generator: z.string().optional(),
+    files: z.array(ManifestEntry),
+});
+export const DecisionAssertion = z.discriminatedUnion("kind", [
+    z.object({
+        id: z.string(),
+        kind: z.literal("schema_must_contain"),
+        table: z.string(),
+        column: z.string(),
+        column_type: z.string().optional(),
+        nullable: z.boolean().optional(),
+    }),
+    z.object({
+        id: z.string(),
+        kind: z.literal("text_must_match"),
+        pattern: z.string(),
+        in_globs: z.array(z.string()),
+    }),
+    z.object({
+        id: z.string(),
+        kind: z.literal("text_must_not_match"),
+        pattern: z.string(),
+        in_globs: z.array(z.string()),
+    }),
+    z.object({
+        id: z.string(),
+        kind: z.literal("index_must_exist"),
+        table: z.string(),
+        columns: z.array(z.string()),
+        where: z.string().optional(),
+    }),
+    z.object({
+        id: z.string(),
+        kind: z.literal("ast_pattern"),
+        language: z.string(),
+        pattern: z.string(),
+        in_globs: z.array(z.string()),
+    }),
+    z.object({
+        id: z.string(),
+        kind: z.literal("file_must_not_be_modified"),
+        path: z.string(),
+    }),
+    z.object({
+        id: z.string(),
+        kind: z.literal("query_must_filter_by"),
+        orm: z.string(),
+        in_globs: z.array(z.string()),
+        table: z.string(),
+        columns: z.array(z.string()),
+        operator: z.enum(["eq", "in", "between", "is_not_null"]),
+        require_combination: z.enum(["and", "or"]),
+    }),
+    z.object({
+        id: z.string(),
+        kind: z.literal("route_must_have_guard"),
+        in_globs: z.array(z.string()),
+        guard: z.string(),
+        require_on: z.array(z.string()),
+    }),
+    z.object({
+        id: z.string(),
+        kind: z.literal("event_must_emit"),
+        in_globs: z.array(z.string()),
+        after_method: z.string(),
+        event_key: z.string(),
+        payload_must_include: z.array(z.string()).optional(),
+    }),
+    z.object({
+        id: z.string(),
+        kind: z.literal("service_method_must_call"),
+        in_globs: z.array(z.string()),
+        in_method: z.string(),
+        must_call: z.string(),
+        before_returning: z.boolean().optional(),
+    }),
+    z.object({
+        id: z.string(),
+        kind: z.literal("human_review_hint"),
+        description: z.string(),
+    }),
+]);
+export const DecisionFrontmatter = z
+    .object({
+    id: z.string().regex(/^DEC-\d{4,}$/, "decision id must match DEC-NNNN"),
+    title: z.string(),
+    type: z.literal("adr").optional(),
+    status: z.enum(["draft", "accepted", "superseded", "archived"]),
+    audience: Audience.optional(),
+    generated: z.string().optional(),
+    "verified-at": z.string().optional(),
+    "source-commits": z.array(z.string()).optional(),
+    decided_at: z.string().optional(),
+    decided_by: z.string().optional(),
+    scope_globs: z.array(z.string()).optional(),
+    supersedes: z.string().nullable().optional(),
+    superseded_by: z.string().nullable().optional(),
+    assertions: z.array(DecisionAssertion).optional(),
+    human_review_hint: z.string().optional(),
+    related_invariants: z.array(z.string()).optional(),
+})
+    .passthrough();
+export const InvariantFrontmatter = z
+    .object({
+    id: z.string().regex(/^V\d{4,}$/, "invariant id must match V<NNNN>"),
+    title: z.string(),
+    type: z.literal("invariant").optional(),
+    status: z.enum(["active", "superseded"]).optional(),
+    audience: Audience.optional(),
+    generated: z.string().optional(),
+    "verified-at": z.string().optional(),
+    source_run: z.string().optional(),
+    source_decision: z.string().nullable().optional(),
+    introduced_for_bug: z.string().optional(),
+    sensor: z.string().optional(),
+    e2e: z.string().optional(),
+    naming_convention: z.string().optional(),
+    superseded_by: z.string().nullable().optional(),
+})
+    .passthrough();
+export const DecisionLedgerEntry = z.object({
+    id: z.string(),
+    title: z.string(),
+    status: z.string(),
+    scope_globs: z.array(z.string()).optional(),
+    supersedes: z.string().nullable().optional(),
+    superseded_by: z.string().nullable().optional(),
+});
+export const InvariantLedgerEntry = z.object({
+    id: z.string(),
+    title: z.string(),
+    status: z.string(),
+    source_decision: z.string().nullable().optional(),
+    superseded_by: z.string().nullable().optional(),
+});
+export const QualityGrade = z.object({
+    module: z.string(),
+    score: z.number().min(0).max(100),
+    pass_rate: z.number().min(0).max(1),
+    drift_count: z.number().int().nonnegative(),
+    last_updated: z.string(),
+    recent_run_count: z.number().int().nonnegative(),
+});
+export const QualityGrades = z.object({
+    version: z.literal(1),
+    generated: z.string(),
+    modules: z.array(QualityGrade),
+});
+export const DriftEvent = z.object({
+    ts: z.string(),
+    kind: z.enum([
+        "frontmatter_stale",
+        "generator_drift",
+        "broken_link",
+        "orphan_path",
+        "manifest_hash_changed",
+    ]),
+    path: z.string(),
+    detail: z.string().optional(),
+    severity: z.enum(["soft", "hard"]).default("soft"),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/ground/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/ground/schemas.ts"],"names":[],"mappings":"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"}

package/dist/ground/scope-index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Scope index — forward map from every file path in the repo to the decisions
+ * and invariants that apply to that file.
+ *
+ * Built at init by the Tier-2 mapper LLM, maintained by the daemon. Read by
+ * the read-enricher / write-guardian hooks (via cached accessor in
+ * `hooks/post-tool-use/ledger-cache.ts`) and by the GC scope-coverage pass.
+ *
+ * Spec: docs/DOCS_SPEC.md §3.8.
+ */
+export interface ScopeIndexEntry {
+    decisions: string[];
+    invariants: string[];
+    unscoped?: true;
+}
+export interface ScopeIndex {
+    generated: string;
+    files: Record<string, ScopeIndexEntry>;
+}
+export declare function scopeIndexPath(repoRoot: string): string;
+export declare function readScopeIndex(repoRoot: string): ScopeIndex | null;
+export declare function lookupScope(index: ScopeIndex, repoRelativePath: string): ScopeIndexEntry | null;
+export declare function writeScopeIndex(repoRoot: string, index: ScopeIndex): void;
+export interface RebuildScopeIndexOptions {
+    repoRoot: string;
+    /** Hard timeout for the mapper LLM call (ms). Default 300000. */
+    timeoutMs?: number;
+}
+export interface RebuildScopeIndexResult {
+    /** Absolute path to the file written. */
+    path: string;
+    /** Number of files classified in the new index. */
+    filesClassified: number;
+    /** Mapper duration in ms. */
+    mapperDurationMs: number;
+    /** Resolved model id. */
+    model: string;
+}
+/**
+ * Re-run the init mapper LLM scoped to the scope-index field of its output and
+ * write the result to `.cairn/ground/scope-index.yaml`. Used by the
+ * `cairn scope rebuild` CLI subcommand to populate scope coverage after
+ * decisions/invariants land — the init-time skeleton ships empty.
+ *
+ * Throws if the LLM call fails. Caller (CLI) catches and prints a user-facing
+ * error.
+ */
+export declare function rebuildScopeIndex(opts: RebuildScopeIndexOptions): Promise<RebuildScopeIndexResult>;