clud-bug 0.7.0-rc.2 → 0.7.0-rc.21

package/dist/core/configure-github.js

@@ -0,0 +1,289 @@
+// SPEC §7 canonical-ruleset applier — pure core half of `configure-github`.
+//
+// External users installing the App expect "best practice branch protection"
+// applied automatically. This module diffs the current GitHub state against
+// the canonical ruleset (bundled at `data/canonical-v1.json`) and emits the
+// minimal set of PATCH calls to converge.
+//
+// Architectural shape mirrors `formal-review.ts` and `review-writeback.ts`:
+// the pure rule-table + diff logic lives in core (no Octokit dep at compile
+// time — clud-bug-app already has `@octokit/rest` and passes its instance;
+// the CLI side wraps `gh api` in a tiny adapter that satisfies the same
+// structural interface). Core stays npm-side single-source-of-truth per the
+// Bug 9 / Phase 2-4 architectural lock.
+//
+// Idempotent contract (HARD GUARANTEE):
+//
+//   const a = await applyCanonicalRuleset(octokit, params);
+//   const b = await applyCanonicalRuleset(octokit, params);
+//   // b.alreadyCanonical === true; b.changes.length === 0
+//
+// A second `apply()` call against a freshly-converged repo MUST produce
+// `alreadyCanonical: true` with `changes: []` and zero PATCH calls. This
+// lets external automation (CI, dispatch loops, dashboard probes) call
+// `apply()` defensively without rate-limiting itself out of the API.
+//
+// SPEC pins honored here:
+//   - canonical-v1.json schema (frozen at v1; major bumps require coordinated
+//     tool releases per the `$comment` field).
+//   - `required_status_checks.contexts` are TREATED AS A SUPERSET: if the
+//     repo already requires MORE contexts than the canonical list, we leave
+//     them alone (a repo that runs additional CI gates legitimately needs
+//     them in the required set). We only ADD the canonical contexts that
+//     are missing.
+//   - `required_approving_review_count`: canonical floor is 1. If the repo
+//     already requires MORE than 1, we leave it alone (only raise to floor).
+//
+// Offline-resilient bundling: the canonical ruleset ships in `data/` at
+// the package root (alongside `bin/`, `templates/`, etc., per package.json
+// `files`). We read it at runtime via fs.readFile so the build stays out
+// of TypeScript's `rootDir` constraint, and so callers that re-bundle
+// clud-bug into a single file can override the ruleset by passing one
+// explicitly to `applyCanonicalRuleset({ ruleset })`.
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Resolves the package root from this file's URL. After tsc the file lives
+ * at `<pkg>/dist/core/configure-github.js`; three dirname() climbs land on
+ * `<pkg>`, parallel to the package.json `files` map entry for `data`.
+ */
+const PKG_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+/** Memoized canonical ruleset — loaded once per process. */
+let CANONICAL_V1_CACHE = null;
+/**
+ * Loads the bundled canonical-v1 ruleset from `data/canonical-v1.json`.
+ * Memoized so repeated calls don't re-hit the filesystem.
+ *
+ * Throws a wrapped error if the JSON file is missing — that's an
+ * install-time defect (package.json `files` excluded `data/`), not a
+ * runtime concern, and the loud failure surfaces it immediately.
+ */
+export async function loadCanonicalV1() {
+    if (CANONICAL_V1_CACHE)
+        return CANONICAL_V1_CACHE;
+    const path = join(PKG_ROOT, 'data', 'canonical-v1.json');
+    try {
+        const raw = await readFile(path, 'utf-8');
+        CANONICAL_V1_CACHE = JSON.parse(raw);
+        return CANONICAL_V1_CACHE;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`configure-github: failed to load bundled canonical-v1.json at ${path}: ${msg}`);
+    }
+}
+/**
+ * Applies the canonical ruleset to a GitHub repo. Reads current state via
+ * the Octokit-like instance, diffs against `ruleset` (default
+ * `CANONICAL_V1`), and PATCHes only what differs. Idempotent: second call
+ * returns `alreadyCanonical: true` with no PATCH side effects.
+ *
+ * Behavior on partial mismatch:
+ *
+ *   - `required_status_checks.contexts`: canonical contexts that are
+ *     missing get added; extra contexts on the repo are preserved (superset
+ *     contract — a repo that runs more CI gates legitimately needs them).
+ *   - `required_approving_review_count`: canonical floor is 1; if the repo
+ *     already requires more, we don't lower (raise-only contract).
+ *   - All booleans (allow_force_pushes, allow_deletions, etc.): converge
+ *     to the canonical value exactly.
+ *
+ * Throws on Octokit transport failure (auth, network, 403). The CLI
+ * wraps these with a friendly error message.
+ */
+export async function applyCanonicalRuleset(octokit, params) {
+    const { owner, repo, branch = 'main', dryRun = false, } = params;
+    const ruleset = params.ruleset ?? (await loadCanonicalV1());
+    const target = ruleset.branch_protection;
+    const changes = [];
+    // ----- Read current branch protection state ---------------------------
+    // 404 → no base protection rule. We treat that as "every canonical
+    // setting differs" so the apply path creates the rule. Other errors
+    // bubble up — callers can't recover from a 403.
+    let current = {};
+    let hasBaseProtection = true;
+    try {
+        const resp = await octokit.repos.getBranchProtection({
+            owner,
+            repo,
+            branch,
+        });
+        current = resp.data;
+    }
+    catch (err) {
+        if (isBranchNotProtected(err)) {
+            hasBaseProtection = false;
+        }
+        else {
+            throw err;
+        }
+    }
+    // ----- Diff: required_status_checks -----------------------------------
+    // Behavior: contexts are a SUPERSET. Strict mode must match exactly.
+    const currentChecks = current.required_status_checks ?? null;
+    const currentContexts = new Set(currentChecks?.contexts ?? []);
+    const targetContexts = new Set(target.required_status_checks.contexts);
+    const missingContexts = [...targetContexts].filter((c) => !currentContexts.has(c));
+    const strictMismatch = (currentChecks?.strict ?? false) !== target.required_status_checks.strict;
+    let needsChecksPatch = !hasBaseProtection;
+    if (missingContexts.length > 0) {
+        changes.push(`required_status_checks.contexts: add ${JSON.stringify(missingContexts)}`);
+        needsChecksPatch = true;
+    }
+    if (strictMismatch) {
+        changes.push(`required_status_checks.strict: ${currentChecks?.strict ?? false} → ${target.required_status_checks.strict}`);
+        needsChecksPatch = true;
+    }
+    // The merged context list: keep extras the repo already required.
+    const mergedContexts = [
+        ...new Set([
+            ...(currentChecks?.contexts ?? []),
+            ...target.required_status_checks.contexts,
+        ]),
+    ];
+    // ----- Diff: required_pull_request_reviews ----------------------------
+    // Behavior: approving_review_count is a FLOOR (only raise). Booleans
+    // converge exactly.
+    const currentReviews = current.required_pull_request_reviews ?? null;
+    const currentCount = currentReviews?.required_approving_review_count ?? 0;
+    const targetCount = target.required_pull_request_reviews.required_approving_review_count;
+    const effectiveCount = Math.max(currentCount, targetCount);
+    const targetDismiss = target.required_pull_request_reviews.dismiss_stale_reviews;
+    const targetCodeOwner = target.required_pull_request_reviews.require_code_owner_reviews;
+    let needsReviewsPatch = !hasBaseProtection;
+    if (effectiveCount !== currentCount) {
+        changes.push(`required_pull_request_reviews.required_approving_review_count: ${currentCount} → ${effectiveCount}`);
+        needsReviewsPatch = true;
+    }
+    if ((currentReviews?.dismiss_stale_reviews ?? false) !== targetDismiss) {
+        changes.push(`required_pull_request_reviews.dismiss_stale_reviews: ${currentReviews?.dismiss_stale_reviews ?? false} → ${targetDismiss}`);
+        needsReviewsPatch = true;
+    }
+    if ((currentReviews?.require_code_owner_reviews ?? false) !== targetCodeOwner) {
+        changes.push(`required_pull_request_reviews.require_code_owner_reviews: ${currentReviews?.require_code_owner_reviews ?? false} → ${targetCodeOwner}`);
+        needsReviewsPatch = true;
+    }
+    // ----- Diff: single-flag branch protection booleans -------------------
+    const conv = current.required_conversation_resolution?.enabled ?? false;
+    const enforceAdmins = current.enforce_admins?.enabled ?? false;
+    const allowFP = current.allow_force_pushes?.enabled ?? false;
+    const allowDel = current.allow_deletions?.enabled ?? false;
+    const linearHistory = current.required_linear_history?.enabled ?? false;
+    if (conv !== target.required_conversation_resolution) {
+        changes.push(`required_conversation_resolution: ${conv} → ${target.required_conversation_resolution}`);
+    }
+    if (enforceAdmins !== target.enforce_admins) {
+        changes.push(`enforce_admins: ${enforceAdmins} → ${target.enforce_admins}`);
+    }
+    if (allowFP !== target.allow_force_pushes) {
+        changes.push(`allow_force_pushes: ${allowFP} → ${target.allow_force_pushes}`);
+    }
+    if (allowDel !== target.allow_deletions) {
+        changes.push(`allow_deletions: ${allowDel} → ${target.allow_deletions}`);
+    }
+    if (linearHistory !== target.required_linear_history) {
+        changes.push(`required_linear_history: ${linearHistory} → ${target.required_linear_history}`);
+    }
+    // ----- Diff: repo-level settings --------------------------------------
+    // delete_branch_on_merge / allow_auto_merge / squash commit shape live
+    // on the REPO, not the branch protection rule. Fetched separately.
+    const repoResp = await octokit.repos.get({ owner, repo });
+    const repoData = repoResp.data;
+    const repoPatch = {
+        owner,
+        repo,
+    };
+    let needsRepoPatch = false;
+    if ((repoData.delete_branch_on_merge ?? false) !== target.delete_branch_on_merge) {
+        changes.push(`delete_branch_on_merge: ${repoData.delete_branch_on_merge ?? false} → ${target.delete_branch_on_merge}`);
+        repoPatch.delete_branch_on_merge = target.delete_branch_on_merge;
+        needsRepoPatch = true;
+    }
+    if ((repoData.allow_auto_merge ?? false) !== target.allow_auto_merge) {
+        changes.push(`allow_auto_merge: ${repoData.allow_auto_merge ?? false} → ${target.allow_auto_merge}`);
+        repoPatch.allow_auto_merge = target.allow_auto_merge;
+        needsRepoPatch = true;
+    }
+    if ((repoData.squash_merge_commit_title ?? '') !==
+        target.squash_merge_commit_title) {
+        changes.push(`squash_merge_commit_title: ${repoData.squash_merge_commit_title ?? '(unset)'} → ${target.squash_merge_commit_title}`);
+        repoPatch.squash_merge_commit_title = target.squash_merge_commit_title;
+        needsRepoPatch = true;
+    }
+    if ((repoData.squash_merge_commit_message ?? '') !==
+        target.squash_merge_commit_message) {
+        changes.push(`squash_merge_commit_message: ${repoData.squash_merge_commit_message ?? '(unset)'} → ${target.squash_merge_commit_message}`);
+        repoPatch.squash_merge_commit_message = target.squash_merge_commit_message;
+        needsRepoPatch = true;
+    }
+    const alreadyCanonical = changes.length === 0;
+    if (alreadyCanonical || dryRun) {
+        return {
+            changes,
+            alreadyCanonical,
+            ruleset: 'canonical-v1',
+        };
+    }
+    // ----- Apply: branch protection ---------------------------------------
+    // The REST API requires a PUT (not PATCH) with the full settings object.
+    // We always send a complete envelope; the diff above gates whether we
+    // call PUT at all.
+    if (needsChecksPatch || needsReviewsPatch || !hasBaseProtection || hasBranchProtectionLevelDiff(changes)) {
+        await octokit.repos.updateBranchProtection({
+            owner,
+            repo,
+            branch,
+            required_status_checks: {
+                strict: target.required_status_checks.strict,
+                contexts: mergedContexts,
+            },
+            enforce_admins: target.enforce_admins,
+            required_pull_request_reviews: {
+                required_approving_review_count: effectiveCount,
+                dismiss_stale_reviews: targetDismiss,
+                require_code_owner_reviews: targetCodeOwner,
+            },
+            restrictions: null,
+            required_conversation_resolution: target.required_conversation_resolution,
+            required_linear_history: target.required_linear_history,
+            allow_force_pushes: target.allow_force_pushes,
+            allow_deletions: target.allow_deletions,
+        });
+    }
+    // ----- Apply: repo-level settings -------------------------------------
+    if (needsRepoPatch) {
+        await octokit.repos.update(repoPatch);
+    }
+    return {
+        changes,
+        alreadyCanonical: false,
+        ruleset: 'canonical-v1',
+    };
+}
+/**
+ * Octokit (and gh's wrapping adapter) report a missing branch protection
+ * rule as a 404. We catch on the structural shape of the error so the
+ * downstream Octokit version doesn't matter.
+ */
+function isBranchNotProtected(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    if (e.status === 404)
+        return true;
+    if (typeof e.message === 'string') {
+        return /Branch not protected|Not Found|404/i.test(e.message);
+    }
+    return false;
+}
+/**
+ * Detect whether any of the per-branch protection settings (conversation
+ * resolution / force-pushes / deletions / linear-history / enforce-admins)
+ * appeared in the change list. Used to decide whether the branch protection
+ * PUT needs to fire when status_checks + reviews are both in sync.
+ */
+function hasBranchProtectionLevelDiff(changes) {
+    return changes.some((c) => /^(required_conversation_resolution|enforce_admins|allow_force_pushes|allow_deletions|required_linear_history):/.test(c));
+}
+//# sourceMappingURL=configure-github.js.map

package/dist/core/configure-github.js.map

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

package/dist/core/design.d.ts

@@ -0,0 +1,37 @@
+import type { ReviewTrigger } from './plan-review.js';
+/** How design findings interact with the merge gate. */
+export type DesignGate = 'advisory' | 'strict';
+/** Resolved `.clud-bug.json` `design` block (defaults applied). */
+export interface DesignConfig {
+    /** Master switch. Default OFF — the design pass never runs unless this is true. */
+    enabled: boolean;
+    /**
+     * `advisory` (default) — design findings post as comments, never block merge.
+     * `strict` — a design `critical` turns the check RED (opt-in).
+     */
+    gate: DesignGate;
+    /** Themes to render + critique. Default both. */
+    themes: string[];
+    /** Viewports to render. Default a single desktop viewport. */
+    viewports: string[];
+}
+/** Off-by-default builtin — the cost-control floor. */
+export declare const BUILTIN_DESIGN_CONFIG: DesignConfig;
+/**
+ * Read + normalize the `design` block from a parsed `.clud-bug.json` manifest.
+ * Tolerant: a missing/malformed block resolves to the off-by-default builtin,
+ * so a typo can never silently *enable* the (cost-bearing) pass.
+ */
+export declare function readDesignConfig(manifest: unknown): DesignConfig;
+/**
+ * Consumer-agnostic run-gate for the design-critic. Pure.
+ *
+ * True only when the repo opted in (`enabled`), at least one `kind: design`
+ * skill applies, and this is a PR-level review (the pass is too expensive for
+ * per-commit / per-push triggers). Consumers layer their own runtime
+ * preconditions on top: the local recipe defers the deploy-preview-URL check to
+ * the agent; the hosted bot additionally requires a paying tier + a resolved
+ * preview URL before it spends a render.
+ */
+export declare function shouldRunDesign(config: DesignConfig, designSkillCount: number, trigger: ReviewTrigger): boolean;
+//# sourceMappingURL=design.d.ts.map

package/dist/core/design.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"design.d.ts","sourceRoot":"","sources":["../../src/core/design.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE/C,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,IAAI,EAAE,UAAU,CAAC;IACjB,iDAAiD;IACjD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,uDAAuD;AACvD,eAAO,MAAM,qBAAqB,EAAE,YAKnC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,YAAY,CAYhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,YAAY,EACpB,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,aAAa,GACrB,OAAO,CAET"}

package/dist/core/design.js

@@ -0,0 +1,47 @@
+// Design-critic lens config + gate (Track B, rc.15).
+//
+// The design-critic is an OPTIONAL, off-by-default visual review pass that
+// renders the changed UI (light + dark) and critiques it against `kind: design`
+// skills. It is gated tightly so it only ever runs — and only ever costs — when
+// a repo has explicitly opted in. This module is the shared, pure brain: the
+// local recipe (`review-prompt`) and the hosted bot both resolve the config and
+// the run-gate here so the policy can't fork (SPEC §11.5 / §12).
+/** Off-by-default builtin — the cost-control floor. */
+export const BUILTIN_DESIGN_CONFIG = {
+    enabled: false,
+    gate: 'advisory',
+    themes: ['light', 'dark'],
+    viewports: ['desktop'],
+};
+/**
+ * Read + normalize the `design` block from a parsed `.clud-bug.json` manifest.
+ * Tolerant: a missing/malformed block resolves to the off-by-default builtin,
+ * so a typo can never silently *enable* the (cost-bearing) pass.
+ */
+export function readDesignConfig(manifest) {
+    const raw = manifest?.design;
+    if (!raw || typeof raw !== 'object')
+        return { ...BUILTIN_DESIGN_CONFIG };
+    const d = raw;
+    const strArr = (v, fallback) => Array.isArray(v) && v.length > 0 ? v.map(String) : [...fallback];
+    return {
+        enabled: d['enabled'] === true,
+        gate: d['gate'] === 'strict' ? 'strict' : 'advisory',
+        themes: strArr(d['themes'], BUILTIN_DESIGN_CONFIG.themes),
+        viewports: strArr(d['viewports'], BUILTIN_DESIGN_CONFIG.viewports),
+    };
+}
+/**
+ * Consumer-agnostic run-gate for the design-critic. Pure.
+ *
+ * True only when the repo opted in (`enabled`), at least one `kind: design`
+ * skill applies, and this is a PR-level review (the pass is too expensive for
+ * per-commit / per-push triggers). Consumers layer their own runtime
+ * preconditions on top: the local recipe defers the deploy-preview-URL check to
+ * the agent; the hosted bot additionally requires a paying tier + a resolved
+ * preview URL before it spends a render.
+ */
+export function shouldRunDesign(config, designSkillCount, trigger) {
+    return config.enabled && designSkillCount > 0 && trigger === 'pr';
+}
+//# sourceMappingURL=design.js.map

package/dist/core/design.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"design.js","sourceRoot":"","sources":["../../src/core/design.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,EAAE;AACF,2EAA2E;AAC3E,gFAAgF;AAChF,gFAAgF;AAChF,6EAA6E;AAC7E,gFAAgF;AAChF,iEAAiE;AAsBjE,uDAAuD;AACvD,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,OAAO,EAAE,KAAK;IACd,IAAI,EAAE,UAAU;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,CAAC,SAAS,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAiB;IAChD,MAAM,GAAG,GAAI,QAAoD,EAAE,MAAM,CAAC;IAC1E,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,GAAG,qBAAqB,EAAE,CAAC;IACzE,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,MAAM,MAAM,GAAG,CAAC,CAAU,EAAE,QAAkB,EAAY,EAAE,CAC1D,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC;IACnE,OAAO;QACL,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,IAAI;QAC9B,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU;QACpD,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC,MAAM,CAAC;QACzD,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC;KACnE,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAoB,EACpB,gBAAwB,EACxB,OAAsB;IAEtB,OAAO,MAAM,CAAC,OAAO,IAAI,gBAAgB,GAAG,CAAC,IAAI,OAAO,KAAK,IAAI,CAAC;AACpE,CAAC"}

package/dist/core/diff-findings.d.ts

@@ -0,0 +1,96 @@
+/** One parsed finding from a prior `docs/reviews/PR-<n>.md`. */
+export type ParsedFinding = {
+    /** Relative path. Falls back to '(unknown file)' when the prior file
+     *  itself rendered the unknown-file marker; we keep it intact for
+     *  identity stability. */
+    file: string;
+    /**
+     * 1-indexed line number. Zero when the prior file had no `:N` suffix
+     * (cross-cutting findings). Zero participates in identity as-is.
+     */
+    line: number;
+    severity: 'critical' | 'minor' | 'preexisting';
+    skillName: string;
+    summary: string;
+};
+export type ParsedReview = {
+    findings: ParsedFinding[];
+};
+/**
+ * Parse a `docs/reviews/PR-<n>.md` markdown back into structured findings.
+ *
+ * Robust to:
+ *   - `null` / `undefined` input            → returns `null`
+ *   - empty / whitespace-only markdown      → returns `null`
+ *   - missing severity sections             → those sections contribute 0
+ *   - lines that don't match the SPEC bullet shape → silently dropped
+ *   - mixed unknown-file markers (`(unknown file)` vs absent)
+ *
+ * Parsing strategy: walk top-down, switch active severity on each
+ * `### <emoji> <Label>` header (one of the three SPEC §1.8.1 buckets),
+ * then collect every line starting with `- **` until the next header
+ * (or `---` end marker). Each `- **<file>:<line>** — <skill>: <summary>`
+ * line is split into its 4 fields; `:<line>` is optional (cross-cutting).
+ *
+ * `(unknown file)` files are preserved verbatim — they participate in
+ * identity, so the same cross-cutting finding can still be diffed across
+ * rounds even when neither pass has a line anchor.
+ */
+export declare function parsePriorReviewFile(markdown: string | null | undefined): ParsedReview | null;
+/**
+ * Diff prior vs current.
+ *
+ * `resolvedFindings`: findings that appeared in `prior` but NOT in
+ * `current`. The PR author (or auto-fix) addressed them.
+ *
+ * `stillOpenFindings`: findings that appeared in BOTH `prior` and
+ * `current`. These are persistent — the PR author hasn't fixed them
+ * (or the bot still considers them findings post-fix-push).
+ *
+ * Findings unique to `current` (newly raised this round) appear in
+ * neither list — those are surfaced directly by the renderer's normal
+ * severity-bucket emission.
+ *
+ * Order is preserved from `prior` for stability across rounds.
+ */
+export declare function diffFindings(prior: ParsedReview | null, current: {
+    critical_findings?: Array<{
+        skill: string;
+        file?: string;
+        line?: number;
+        summary: string;
+    }>;
+    minor_findings?: Array<{
+        skill: string;
+        file?: string;
+        line?: number;
+        summary: string;
+    }>;
+    preexisting_findings?: Array<{
+        skill: string;
+        file?: string;
+        line?: number;
+        summary: string;
+    }>;
+}): {
+    resolvedFindings: ParsedFinding[];
+    stillOpenFindings: ParsedFinding[];
+};
+/**
+ * Stable identity for a finding. Used for diffing prior vs current
+ * across review rounds AND (by intention) shareable with the
+ * clud-bug-app inline-thread anchor hash so future cross-feature
+ * surfaces (e.g. "the auto-fix that resolved this thread also resolves
+ * this doc-file finding") align without re-computing.
+ *
+ * Exposed for tests + downstream callers that want to align their own
+ * finding storage on the same scheme.
+ */
+export declare function findingIdentity(f: {
+    file: string;
+    line: number;
+    severity: 'critical' | 'minor' | 'preexisting';
+    skillName: string;
+    summary: string;
+}): string;
+//# sourceMappingURL=diff-findings.d.ts.map

package/dist/core/diff-findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-findings.d.ts","sourceRoot":"","sources":["../../src/core/diff-findings.ts"],"names":[],"mappings":"AAgCA,gEAAgE;AAChE,MAAM,MAAM,aAAa,GAAG;IAC1B;;8BAE0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,UAAU,GAAG,OAAO,GAAG,aAAa,CAAC;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAClC,YAAY,GAAG,IAAI,CA+DrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,YAAY,GAAG,IAAI,EAC1B,OAAO,EAAE;IACP,iBAAiB,CAAC,EAAE,KAAK,CAAC;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,cAAc,CAAC,EAAE,KAAK,CAAC;QACrB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,oBAAoB,CAAC,EAAE,KAAK,CAAC;QAC3B,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ,GACA;IACD,gBAAgB,EAAE,aAAa,EAAE,CAAC;IAClC,iBAAiB,EAAE,aAAa,EAAE,CAAC;CACpC,CAgDA;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,UAAU,GAAG,OAAO,GAAG,aAAa,CAAC;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAST"}