@deftai/directive-core 0.102.0 → 0.104.0

package/dist/telemetry-coverage/evaluate.js

@@ -0,0 +1,148 @@
+/**
+ * verify:telemetry-coverage — dead-surface detector (#3362).
+ *
+ * Two checks, one remediation that names the missing half:
+ *  1. Every RUN_SUMMARY_EVENT_KINDS member (and exported emitter method)
+ *     has a production caller outside the emitter module.
+ *  2. Every kind is enrolled, has a trial step, and appears in a run of
+ *     the shared fake-trial harness JSONL.
+ *
+ * Default is warn-only (exit 0). Pass --enforce to fail closed.
+ */
+import { existsSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { DEFAULT_TRIAL_STEPS, runFakeTrial } from "./fake-trial.js";
+import { ENROLLED_FIELD_FIXTURE_KINDS, kindForMethod, RUN_SUMMARY_EVENT_KINDS } from "./kinds.js";
+import { scanProductionCallers } from "./scan-callers.js";
+const EXIT_OK = 0;
+const EXIT_ENFORCE_FINDINGS = 1;
+const EXIT_CONFIG = 2;
+export function remediationFor(subject, missingCaller, missingFixture) {
+    if (missingCaller && missingFixture) {
+        return `event kind ${subject} has no production caller / no field fixture — wire it or remove it from the schema.`;
+    }
+    if (missingCaller) {
+        return `event kind ${subject} has no production caller — wire it or remove it from the schema.`;
+    }
+    return `event kind ${subject} has no field fixture — wire it or remove it from the schema.`;
+}
+function failedDeclaredSteps(outcomes) {
+    const failed = new Set();
+    if (outcomes === undefined) {
+        return failed;
+    }
+    for (const outcome of outcomes) {
+        if (!outcome.emittedKinds.includes(outcome.declaredKind)) {
+            failed.add(outcome.declaredKind);
+        }
+    }
+    return failed;
+}
+export function evaluateTelemetryCoverage(options) {
+    const root = resolve(options.projectRoot);
+    const enforce = options.enforce === true;
+    if (!existsSync(root)) {
+        return {
+            code: EXIT_CONFIG,
+            message: `verify:telemetry-coverage: project root not found: ${root}`,
+            stream: "stderr",
+            findings: [],
+            enforce,
+            failOpen: !enforce,
+        };
+    }
+    const kinds = options.kinds ?? [...RUN_SUMMARY_EVENT_KINDS];
+    const enrolled = new Set(options.enrolledKinds ?? ENROLLED_FIELD_FIXTURE_KINDS);
+    const trialKinds = new Set(options.trialKinds ?? DEFAULT_TRIAL_STEPS.map((step) => step.kind));
+    let trialRoot;
+    let presentFromTrial;
+    let failedStepKinds;
+    const findings = [];
+    try {
+        if (options.trialResult !== undefined) {
+            presentFromTrial = new Set(options.trialResult.presentKinds);
+            failedStepKinds = failedDeclaredSteps(options.trialResult.stepOutcomes);
+        }
+        else if (options.skipTrial !== true) {
+            const trial = runFakeTrial();
+            trialRoot = trial.projectRoot;
+            presentFromTrial = new Set(trial.presentKinds);
+            failedStepKinds = failedDeclaredSteps(trial.stepOutcomes);
+        }
+        const scan = scanProductionCallers({
+            projectRoot: root,
+            scanRoots: options.scanRoots,
+            kinds,
+        });
+        for (const kind of kinds) {
+            const missingCaller = (scan.callersByKind[kind] ?? []).length === 0;
+            const missingFromTrial = presentFromTrial !== undefined && !presentFromTrial.has(kind);
+            const brokenDeclaredStep = failedStepKinds?.has(kind) === true;
+            const missingFixture = !enrolled.has(kind) || !trialKinds.has(kind) || missingFromTrial || brokenDeclaredStep;
+            if (missingCaller || missingFixture) {
+                findings.push({
+                    subject: kind,
+                    missingCaller,
+                    missingFixture,
+                    remediation: remediationFor(kind, missingCaller, missingFixture),
+                });
+            }
+        }
+        for (const method of scan.discoveredMethods) {
+            const mappedKind = kindForMethod(method);
+            if (mappedKind !== undefined && kinds.includes(mappedKind)) {
+                continue;
+            }
+            const hits = scan.callersByMethod[method] ?? [];
+            if (hits.length === 0) {
+                findings.push({
+                    subject: method,
+                    missingCaller: true,
+                    missingFixture: false,
+                    remediation: `event kind ${method} has no production caller — wire it or remove it from the schema.`,
+                });
+            }
+        }
+        if (findings.length === 0) {
+            return {
+                code: EXIT_OK,
+                message: `OK: verify:telemetry-coverage — every event kind has a production caller ` +
+                    `and a field fixture (enforce=${enforce}).`,
+                stream: "stdout",
+                findings: [],
+                enforce,
+                failOpen: !enforce,
+            };
+        }
+        const lines = [
+            `verify:telemetry-coverage: ${findings.length} dead telemetry surface(s):`,
+            ...findings.map((f) => `  ${f.remediation}`),
+        ];
+        if (enforce) {
+            lines.push("FAIL: --enforce is set; wire the missing half or remove the kind from the schema (#3362).");
+            return {
+                code: EXIT_ENFORCE_FINDINGS,
+                message: lines.join("\n"),
+                stream: "stderr",
+                findings,
+                enforce: true,
+                failOpen: false,
+            };
+        }
+        lines.push("ADVISORY (warn-only): exit 0. Pass --enforce to fail closed after #3355/#3356 land (#3362).");
+        return {
+            code: EXIT_OK,
+            message: lines.join("\n"),
+            stream: "stdout",
+            findings,
+            enforce: false,
+            failOpen: true,
+        };
+    }
+    finally {
+        if (trialRoot !== undefined) {
+            rmSync(trialRoot, { recursive: true, force: true });
+        }
+    }
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/telemetry-coverage/fake-trial.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared fake-trial harness for field-shaped run-summary fixtures (#3362).
+ *
+ * One harness: temp consumer-shaped root, DEFT_RUN_SUMMARY_PATH set, production
+ * emitter write path, multi-invocation identity. Enroll kinds via trial steps
+ * rather than rebuilding a per-kind fixture.
+ */
+import { RunSummaryEmitter } from "../run-summary/emit.js";
+import { type RunSummaryEventKind, type RunSummaryLine } from "../run-summary/index.js";
+export interface FakeTrialStep {
+    readonly kind: RunSummaryEventKind;
+    readonly invoke: (emitter: RunSummaryEmitter) => void;
+}
+export declare const DEFAULT_TRIAL_STEPS: readonly FakeTrialStep[];
+export interface FakeTrialOptions {
+    /** Existing root. When omitted, a temp consumer-shaped deposit is created. */
+    readonly projectRoot?: string;
+    readonly sessionId?: string;
+    readonly destPath?: string;
+    readonly steps?: readonly FakeTrialStep[];
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface FakeTrialStepOutcome {
+    readonly declaredKind: RunSummaryEventKind;
+    readonly emittedKinds: readonly RunSummaryEventKind[];
+}
+export interface FakeTrialResult {
+    readonly projectRoot: string;
+    readonly destPath: string;
+    readonly sessionId: string;
+    readonly lines: readonly RunSummaryLine[];
+    readonly presentKinds: readonly RunSummaryEventKind[];
+    readonly stepOutcomes: readonly FakeTrialStepOutcome[];
+    readonly seqMonotonic: boolean;
+    readonly sessionIdStable: boolean;
+}
+/**
+ * Run one fake trial: write JSONL via the production emitter, then read it back.
+ * A second emitter instance appends so seq/session_id identity is asserted
+ * across invocations (#3350 class).
+ */
+export declare function runFakeTrial(options?: FakeTrialOptions): FakeTrialResult;
+/** Assert every enrolled kind appears in a trial result. */
+export declare function missingEnrolledKinds(result: FakeTrialResult, enrolled?: readonly RunSummaryEventKind[]): readonly RunSummaryEventKind[];
+//# sourceMappingURL=fake-trial.d.ts.map

package/dist/telemetry-coverage/fake-trial.js

@@ -0,0 +1,194 @@
+/**
+ * Shared fake-trial harness for field-shaped run-summary fixtures (#3362).
+ *
+ * One harness: temp consumer-shaped root, DEFT_RUN_SUMMARY_PATH set, production
+ * emitter write path, multi-invocation identity. Enroll kinds via trial steps
+ * rather than rebuilding a per-kind fixture.
+ */
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
+import { RunSummaryEmitter } from "../run-summary/emit.js";
+import { ENV_RUN_SUMMARY_PATH, ENV_TOTAL_TOOL_TURNS, parseRunSummaryJsonl, } from "../run-summary/index.js";
+import { ENROLLED_FIELD_FIXTURE_KINDS } from "./kinds.js";
+export const DEFAULT_TRIAL_STEPS = [
+    {
+        kind: "session_start",
+        invoke: (emitter) => {
+            emitter.emitSessionStart({ ready: true, exit_code: 0 });
+        },
+    },
+    {
+        kind: "dial_escalation_evaluation",
+        invoke: (emitter) => {
+            emitter.emitDialEscalationEvaluation({
+                tier: "standard",
+                outcome: "declined",
+                reason: "fake-trial",
+            });
+        },
+    },
+    {
+        kind: "dial_transition",
+        invoke: (emitter) => {
+            emitter.emitDialTransition({
+                from: "rapid",
+                to: "standard",
+                reason: "fake-trial",
+            });
+        },
+    },
+    {
+        kind: "check_invocation",
+        invoke: (emitter) => {
+            emitter.emitCheckInvocation({
+                target: "check:framework-source",
+                exit_code: 0,
+                gates: [],
+            });
+        },
+    },
+    {
+        kind: "verification",
+        invoke: (emitter) => {
+            emitter.emitVerification({
+                check_id: "fake-trial",
+                method_fingerprint: "fake-trial",
+                outcome: "pass",
+            });
+        },
+    },
+    {
+        kind: "acceptance",
+        invoke: (emitter) => {
+            emitter.emitAcceptance({
+                resolved_command_count: 1,
+                outcome: "verified-pass",
+            });
+        },
+    },
+    {
+        kind: "acceptance_stamp",
+        invoke: (emitter) => {
+            emitter.emitAcceptanceStamp({
+                rung: "stated",
+                none_stated: false,
+                command_count: 1,
+                clause_count: 0,
+            });
+        },
+    },
+    {
+        kind: "tool_turn_denominator",
+        invoke: (emitter) => {
+            emitter.emitKnownToolTurnDenominator();
+        },
+    },
+];
+function createConsumerShapedRoot() {
+    const root = mkdtempSync(join(tmpdir(), "deft-telemetry-trial-"));
+    try {
+        mkdirSync(join(root, "xbrief"), { recursive: true });
+        containedWrite({
+            root,
+            target: ".gitignore",
+            data: ".deft-run-summary.json\n",
+            mode: "create",
+        });
+        containedWrite({
+            root,
+            target: "package.json",
+            data: '{"name":"fake-trial-consumer"}\n',
+            mode: "create",
+        });
+        return root;
+    }
+    catch (error) {
+        rmSync(root, { recursive: true, force: true });
+        throw error;
+    }
+}
+function seqIsMonotonic(lines) {
+    if (lines.length === 0) {
+        return true;
+    }
+    for (let i = 0; i < lines.length; i += 1) {
+        if (lines[i]?.seq !== i + 1) {
+            return false;
+        }
+    }
+    return true;
+}
+function sessionIdIsStable(lines, sessionId) {
+    return lines.every((line) => line.session_id === sessionId);
+}
+/** Missing dest after a silent / fail-open step is empty emit, not ENOENT. */
+function readTrialLines(destPath) {
+    if (!existsSync(destPath)) {
+        return [];
+    }
+    return parseRunSummaryJsonl(readFileSync(destPath, "utf8"));
+}
+/**
+ * Run one fake trial: write JSONL via the production emitter, then read it back.
+ * A second emitter instance appends so seq/session_id identity is asserted
+ * across invocations (#3350 class).
+ */
+export function runFakeTrial(options = {}) {
+    const ownsTempRoot = options.projectRoot === undefined;
+    const projectRoot = options.projectRoot ?? createConsumerShapedRoot();
+    try {
+        const destPath = options.destPath ?? join(projectRoot, "trial-run-summary.jsonl");
+        const sessionId = options.sessionId ?? "fake-trial-session";
+        const steps = options.steps ?? DEFAULT_TRIAL_STEPS;
+        const env = {
+            ...(options.env ?? process.env),
+            [ENV_RUN_SUMMARY_PATH]: destPath,
+            [ENV_TOTAL_TOOL_TURNS]: "8",
+        };
+        const first = new RunSummaryEmitter({ projectRoot, sessionId, env });
+        const stepOutcomes = [];
+        let seenLines = 0;
+        for (const step of steps) {
+            step.invoke(first);
+            const current = readTrialLines(destPath);
+            const emittedKinds = current.slice(seenLines).map((line) => line.event);
+            seenLines = current.length;
+            stepOutcomes.push({ declaredKind: step.kind, emittedKinds });
+        }
+        const second = new RunSummaryEmitter({ projectRoot, sessionId, env });
+        second.emitCheckInvocation({
+            target: "check:framework-source",
+            exit_code: 0,
+            gates: [],
+        });
+        const lines = readTrialLines(destPath);
+        const present = new Set();
+        for (const line of lines) {
+            present.add(line.event);
+        }
+        return {
+            projectRoot,
+            destPath,
+            sessionId,
+            lines,
+            presentKinds: [...present],
+            stepOutcomes,
+            seqMonotonic: seqIsMonotonic(lines),
+            sessionIdStable: sessionIdIsStable(lines, sessionId),
+        };
+    }
+    catch (error) {
+        if (ownsTempRoot) {
+            rmSync(projectRoot, { recursive: true, force: true });
+        }
+        throw error;
+    }
+}
+/** Assert every enrolled kind appears in a trial result. */
+export function missingEnrolledKinds(result, enrolled = ENROLLED_FIELD_FIXTURE_KINDS) {
+    const present = new Set(result.presentKinds);
+    return enrolled.filter((kind) => !present.has(kind));
+}
+//# sourceMappingURL=fake-trial.js.map

package/dist/telemetry-coverage/index.d.ts

@@ -0,0 +1,5 @@
+export { evaluateTelemetryCoverage, remediationFor, type TelemetryCoverageFinding, type TelemetryCoverageOptions, type TelemetryCoverageResult, } from "./evaluate.js";
+export { DEFAULT_TRIAL_STEPS, type FakeTrialOptions, type FakeTrialResult, type FakeTrialStep, type FakeTrialStepOutcome, missingEnrolledKinds, runFakeTrial, } from "./fake-trial.js";
+export { ENROLLED_FIELD_FIXTURE_KINDS, EVENT_KIND_TO_EMITTER_METHODS, isKindEmitterMethod, kindForMethod, methodsForKind, RUN_SUMMARY_EVENT_KINDS, type RunSummaryEventKind, } from "./kinds.js";
+export { type CallerHit, type CallerScanResult, DEFAULT_SCAN_ROOTS, EMITTER_MODULE_REL, scanProductionCallers, } from "./scan-callers.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry-coverage/index.js

@@ -0,0 +1,5 @@
+export { evaluateTelemetryCoverage, remediationFor, } from "./evaluate.js";
+export { DEFAULT_TRIAL_STEPS, missingEnrolledKinds, runFakeTrial, } from "./fake-trial.js";
+export { ENROLLED_FIELD_FIXTURE_KINDS, EVENT_KIND_TO_EMITTER_METHODS, isKindEmitterMethod, kindForMethod, methodsForKind, RUN_SUMMARY_EVENT_KINDS, } from "./kinds.js";
+export { DEFAULT_SCAN_ROOTS, EMITTER_MODULE_REL, scanProductionCallers, } from "./scan-callers.js";
+//# sourceMappingURL=index.js.map

package/dist/telemetry-coverage/kinds.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Event-kind ↔ emitter-method mapping for verify:telemetry-coverage (#3362).
+ */
+import { RUN_SUMMARY_EVENT_KINDS, type RunSummaryEventKind } from "../run-summary/types.js";
+export { RUN_SUMMARY_EVENT_KINDS, type RunSummaryEventKind };
+/** Typed RunSummaryEmitter methods that write each schema kind. */
+export declare const EVENT_KIND_TO_EMITTER_METHODS: Readonly<Record<RunSummaryEventKind, readonly string[]>>;
+/**
+ * Kinds asserted by the shared fake-trial harness.
+ * Author this list independently of RUN_SUMMARY_EVENT_KINDS — spreading the
+ * schema would make a missing fixture undetectable (#3362 Greptile).
+ * Enroll here and add a DEFAULT_TRIAL_STEPS entry; do not rebuild a per-kind harness.
+ */
+export declare const ENROLLED_FIELD_FIXTURE_KINDS: readonly RunSummaryEventKind[];
+/** True when a discovered class method is a distinct event surface (not the generic emit). */
+export declare function isKindEmitterMethod(name: string): boolean;
+export declare function methodsForKind(kind: string): readonly string[];
+export declare function kindForMethod(method: string): RunSummaryEventKind | undefined;
+//# sourceMappingURL=kinds.d.ts.map

package/dist/telemetry-coverage/kinds.js

@@ -0,0 +1,52 @@
+/**
+ * Event-kind ↔ emitter-method mapping for verify:telemetry-coverage (#3362).
+ */
+import { RUN_SUMMARY_EVENT_KINDS } from "../run-summary/types.js";
+export { RUN_SUMMARY_EVENT_KINDS };
+/** Typed RunSummaryEmitter methods that write each schema kind. */
+export const EVENT_KIND_TO_EMITTER_METHODS = {
+    session_start: ["emitSessionStart"],
+    dial_transition: ["emitDialTransition"],
+    dial_escalation_evaluation: ["emitDialEscalationEvaluation"],
+    check_invocation: ["emitCheckInvocation"],
+    tool_turn_denominator: ["emitToolTurnDenominator", "emitKnownToolTurnDenominator"],
+    verification: ["emitVerification"],
+    acceptance: ["emitAcceptance"],
+    acceptance_stamp: ["emitAcceptanceStamp"],
+};
+/**
+ * Kinds asserted by the shared fake-trial harness.
+ * Author this list independently of RUN_SUMMARY_EVENT_KINDS — spreading the
+ * schema would make a missing fixture undetectable (#3362 Greptile).
+ * Enroll here and add a DEFAULT_TRIAL_STEPS entry; do not rebuild a per-kind harness.
+ */
+export const ENROLLED_FIELD_FIXTURE_KINDS = [
+    "session_start",
+    "dial_transition",
+    "dial_escalation_evaluation",
+    "check_invocation",
+    "tool_turn_denominator",
+    "verification",
+    "acceptance",
+    "acceptance_stamp",
+];
+const GENERIC_EMIT_METHODS = new Set(["emit"]);
+/** True when a discovered class method is a distinct event surface (not the generic emit). */
+export function isKindEmitterMethod(name) {
+    return name.startsWith("emit") && !GENERIC_EMIT_METHODS.has(name);
+}
+export function methodsForKind(kind) {
+    if (kind in EVENT_KIND_TO_EMITTER_METHODS) {
+        return EVENT_KIND_TO_EMITTER_METHODS[kind];
+    }
+    return [];
+}
+export function kindForMethod(method) {
+    for (const kind of RUN_SUMMARY_EVENT_KINDS) {
+        if (EVENT_KIND_TO_EMITTER_METHODS[kind].includes(method)) {
+            return kind;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=kinds.js.map

package/dist/telemetry-coverage/scan-callers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Production call-site scan for run-summary event kinds / emitter methods (#3362).
+ */
+export declare const DEFAULT_SCAN_ROOTS: readonly string[];
+export declare const EMITTER_MODULE_REL = "packages/core/src/run-summary/emit.ts";
+export interface CallerHit {
+    readonly path: string;
+    readonly line: number;
+    readonly match: string;
+}
+export interface CallerScanResult {
+    readonly callersByKind: Readonly<Record<string, readonly CallerHit[]>>;
+    readonly callersByMethod: Readonly<Record<string, readonly CallerHit[]>>;
+    readonly discoveredMethods: readonly string[];
+}
+/**
+ * Scan production TypeScript for emitter method / event-kind call sites.
+ * Excludes the emitter module, this detector, and `*.test.ts`.
+ */
+export declare function scanProductionCallers(options: {
+    readonly projectRoot: string;
+    readonly scanRoots?: readonly string[];
+    readonly kinds?: readonly string[];
+}): CallerScanResult;
+//# sourceMappingURL=scan-callers.d.ts.map

package/dist/telemetry-coverage/scan-callers.js

@@ -0,0 +1,168 @@
+/**
+ * Production call-site scan for run-summary event kinds / emitter methods (#3362).
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { isKindEmitterMethod, methodsForKind, RUN_SUMMARY_EVENT_KINDS } from "./kinds.js";
+export const DEFAULT_SCAN_ROOTS = ["packages/core/src"];
+export const EMITTER_MODULE_REL = "packages/core/src/run-summary/emit.ts";
+const SKIP_DIR_NAMES = new Set(["node_modules", "dist", ".git", "coverage"]);
+function toPosix(rel) {
+    return rel.split(sep).join("/");
+}
+function isTestFile(relPosix) {
+    return relPosix.endsWith(".test.ts") || relPosix.endsWith(".test.tsx");
+}
+function isExcludedProductionPath(relPosix) {
+    if (isTestFile(relPosix)) {
+        return true;
+    }
+    if (relPosix.includes("/telemetry-coverage/")) {
+        return true;
+    }
+    return relPosix === EMITTER_MODULE_REL;
+}
+function walkTsFiles(dir, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (SKIP_DIR_NAMES.has(name)) {
+            continue;
+        }
+        const full = join(dir, name);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            walkTsFiles(full, out);
+        }
+        else if (st.isFile() && (name.endsWith(".ts") || name.endsWith(".tsx"))) {
+            out.push(full);
+        }
+    }
+}
+function skipNoiseLine(trimmed) {
+    return (trimmed.startsWith("import ") ||
+        trimmed.startsWith("export ") ||
+        trimmed.startsWith("//") ||
+        trimmed.startsWith("*") ||
+        trimmed.startsWith("/*"));
+}
+function discoverEmitterMethods(emitSource) {
+    const names = new Set();
+    const re = /^\s+(emit[A-Z][A-Za-z0-9]*)\s*\(/gm;
+    let match = re.exec(emitSource);
+    while (match !== null) {
+        const name = match[1];
+        if (name !== undefined && isKindEmitterMethod(name)) {
+            names.add(name);
+        }
+        match = re.exec(emitSource);
+    }
+    return [...names].sort();
+}
+function kindLiteralPatterns(kind) {
+    const escaped = kind.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return [
+        new RegExp(`\\.emit\\s*\\(\\s*['"]${escaped}['"]`),
+        new RegExp(`event\\s*:\\s*['"]${escaped}['"]`),
+    ];
+}
+function methodCallPattern(method) {
+    const escaped = method.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`\\b${escaped}\\s*\\(`);
+}
+function collectHits(relPosix, lines, patterns) {
+    const hits = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        const trimmed = line.trim();
+        if (skipNoiseLine(trimmed)) {
+            continue;
+        }
+        for (const re of patterns) {
+            if (re.test(line)) {
+                hits.push({
+                    path: relPosix,
+                    line: i + 1,
+                    match: trimmed.length > 100 ? `${trimmed.slice(0, 97)}...` : trimmed,
+                });
+                break;
+            }
+        }
+    }
+    return hits;
+}
+/**
+ * Scan production TypeScript for emitter method / event-kind call sites.
+ * Excludes the emitter module, this detector, and `*.test.ts`.
+ */
+export function scanProductionCallers(options) {
+    const root = resolve(options.projectRoot);
+    const scanRoots = options.scanRoots ?? DEFAULT_SCAN_ROOTS;
+    const kinds = options.kinds ?? [...RUN_SUMMARY_EVENT_KINDS];
+    const callersByKind = {};
+    const callersByMethod = {};
+    for (const kind of kinds) {
+        callersByKind[kind] = [];
+        for (const method of methodsForKind(kind)) {
+            callersByMethod[method] = callersByMethod[method] ?? [];
+        }
+    }
+    let discoveredMethods = [];
+    const emitAbs = resolve(root, EMITTER_MODULE_REL);
+    if (existsSync(emitAbs)) {
+        try {
+            discoveredMethods = discoverEmitterMethods(readFileSync(emitAbs, "utf8"));
+            for (const method of discoveredMethods) {
+                callersByMethod[method] = callersByMethod[method] ?? [];
+            }
+        }
+        catch {
+            discoveredMethods = [];
+        }
+    }
+    for (const scanRel of scanRoots) {
+        const scanAbs = resolve(root, scanRel);
+        if (!existsSync(scanAbs)) {
+            continue;
+        }
+        const files = [];
+        walkTsFiles(scanAbs, files);
+        for (const abs of files) {
+            const relPosix = toPosix(relative(root, abs));
+            if (isExcludedProductionPath(relPosix)) {
+                continue;
+            }
+            let text;
+            try {
+                text = readFileSync(abs, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const lines = text.split(/\r?\n/);
+            for (const kind of kinds) {
+                const patterns = [
+                    ...kindLiteralPatterns(kind),
+                    ...methodsForKind(kind).map(methodCallPattern),
+                ];
+                callersByKind[kind]?.push(...collectHits(relPosix, lines, patterns));
+            }
+            for (const method of Object.keys(callersByMethod)) {
+                callersByMethod[method]?.push(...collectHits(relPosix, lines, [methodCallPattern(method)]));
+            }
+        }
+    }
+    return { callersByKind, callersByMethod, discoveredMethods };
+}
+//# sourceMappingURL=scan-callers.js.map

package/dist/vbrief-reconcile/index.d.ts

@@ -1,6 +1,8 @@
 export { depResolved, graphOutcomeToJson, RESOLVED_FOLDERS, reconcileGraph, renderGraphReport, } from "./graph.js";
 export { computeDesiredLabels, labelsOutcomeToJson, MANAGED_LABELS, reconcileLabels, renderLabelsReport, SCAN_FOLDERS, ScmLabelClient, ScmLabelError, } from "./labels.js";
 export { cmdVbriefReconcile, run, usage } from "./main.js";
+export type { EvaluateOriginFreshnessOptions, FetchOriginUpdatedAt, GithubIssueOrigin, OriginFreshnessKind, OriginFreshnessResult, } from "./origin-freshness.js";
+export { briefUpdatedOf, compareOriginFreshness, evaluateOriginFreshness, extractGithubIssueOrigin, extractGithubIssueOrigins, fetchGithubIssueUpdatedAt, formatOriginStaleMessage, ORIGIN_FRESHNESS_REMEDIATION, } from "./origin-freshness.js";
 export { PARITY_SCENARIO_NAMES, renderScenarioOutput, runParityScenario, } from "./parity-scenarios.js";
 export { pyRepr } from "./py-repr.js";
 export { buildSpecTaskIndex, detectStatusMarker, folderFromStatus, formatReconciliationMarkdown, hasDisagreement, loadOverrides, normalizeTaskId, OVERRIDES_FILENAME, parseOverridesYaml, reconcileScopeItems, writeReconciliationReport, } from "./reconciliation.js";