@delfini/drift-engine 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,293 @@
+import { z } from 'zod';
+export declare const ContradictionSchema: z.ZodObject<{
+    targetDocPath: z.ZodString;
+    targetSection: z.ZodString;
+    targetLineStart: z.ZodNumber;
+    targetLineEnd: z.ZodNumber;
+    whatChanged: z.ZodString;
+    whatContradicts: z.ZodString;
+    proposedReplacement: z.ZodNullable<z.ZodString>;
+    severity: z.ZodEnum<["High", "Medium", "Low"]>;
+    confidence: z.ZodNumber;
+    quotedDocText: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    targetDocPath: string;
+    targetSection: string;
+    targetLineStart: number;
+    targetLineEnd: number;
+    whatChanged: string;
+    whatContradicts: string;
+    proposedReplacement: string | null;
+    severity: "High" | "Medium" | "Low";
+    confidence: number;
+    quotedDocText: string;
+}, {
+    targetDocPath: string;
+    targetSection: string;
+    targetLineStart: number;
+    targetLineEnd: number;
+    whatChanged: string;
+    whatContradicts: string;
+    proposedReplacement: string | null;
+    severity: "High" | "Medium" | "Low";
+    confidence: number;
+    quotedDocText: string;
+}>;
+export declare const AdditionSchema: z.ZodObject<{
+    targetDocPath: z.ZodString;
+    anchorSection: z.ZodString;
+    insertionMode: z.ZodEnum<["before", "after"]>;
+    proposedContent: z.ZodString;
+    severity: z.ZodEnum<["High", "Medium", "Low"]>;
+    confidence: z.ZodNumber;
+    whatChanged: z.ZodString;
+    rationaleForAddition: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    targetDocPath: string;
+    whatChanged: string;
+    severity: "High" | "Medium" | "Low";
+    confidence: number;
+    anchorSection: string;
+    insertionMode: "before" | "after";
+    proposedContent: string;
+    rationaleForAddition: string;
+}, {
+    targetDocPath: string;
+    whatChanged: string;
+    severity: "High" | "Medium" | "Low";
+    confidence: number;
+    anchorSection: string;
+    insertionMode: "before" | "after";
+    proposedContent: string;
+    rationaleForAddition: string;
+}>;
+export declare const AnalysisResultSchema: z.ZodObject<{
+    contradictions: z.ZodArray<z.ZodObject<{
+        targetDocPath: z.ZodString;
+        targetSection: z.ZodString;
+        targetLineStart: z.ZodNumber;
+        targetLineEnd: z.ZodNumber;
+        whatChanged: z.ZodString;
+        whatContradicts: z.ZodString;
+        proposedReplacement: z.ZodNullable<z.ZodString>;
+        severity: z.ZodEnum<["High", "Medium", "Low"]>;
+        confidence: z.ZodNumber;
+        quotedDocText: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        targetDocPath: string;
+        targetSection: string;
+        targetLineStart: number;
+        targetLineEnd: number;
+        whatChanged: string;
+        whatContradicts: string;
+        proposedReplacement: string | null;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        quotedDocText: string;
+    }, {
+        targetDocPath: string;
+        targetSection: string;
+        targetLineStart: number;
+        targetLineEnd: number;
+        whatChanged: string;
+        whatContradicts: string;
+        proposedReplacement: string | null;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        quotedDocText: string;
+    }>, "many">;
+    additions: z.ZodArray<z.ZodObject<{
+        targetDocPath: z.ZodString;
+        anchorSection: z.ZodString;
+        insertionMode: z.ZodEnum<["before", "after"]>;
+        proposedContent: z.ZodString;
+        severity: z.ZodEnum<["High", "Medium", "Low"]>;
+        confidence: z.ZodNumber;
+        whatChanged: z.ZodString;
+        rationaleForAddition: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        targetDocPath: string;
+        whatChanged: string;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        anchorSection: string;
+        insertionMode: "before" | "after";
+        proposedContent: string;
+        rationaleForAddition: string;
+    }, {
+        targetDocPath: string;
+        whatChanged: string;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        anchorSection: string;
+        insertionMode: "before" | "after";
+        proposedContent: string;
+        rationaleForAddition: string;
+    }>, "many">;
+    rawConfidence: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    contradictions: {
+        targetDocPath: string;
+        targetSection: string;
+        targetLineStart: number;
+        targetLineEnd: number;
+        whatChanged: string;
+        whatContradicts: string;
+        proposedReplacement: string | null;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        quotedDocText: string;
+    }[];
+    additions: {
+        targetDocPath: string;
+        whatChanged: string;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        anchorSection: string;
+        insertionMode: "before" | "after";
+        proposedContent: string;
+        rationaleForAddition: string;
+    }[];
+    rawConfidence: number;
+}, {
+    contradictions: {
+        targetDocPath: string;
+        targetSection: string;
+        targetLineStart: number;
+        targetLineEnd: number;
+        whatChanged: string;
+        whatContradicts: string;
+        proposedReplacement: string | null;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        quotedDocText: string;
+    }[];
+    additions: {
+        targetDocPath: string;
+        whatChanged: string;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        anchorSection: string;
+        insertionMode: "before" | "after";
+        proposedContent: string;
+        rationaleForAddition: string;
+    }[];
+    rawConfidence: number;
+}>;
+export declare const analysisSchema: z.ZodObject<{
+    contradictions: z.ZodArray<z.ZodObject<{
+        targetDocPath: z.ZodString;
+        targetSection: z.ZodString;
+        targetLineStart: z.ZodNumber;
+        targetLineEnd: z.ZodNumber;
+        whatChanged: z.ZodString;
+        whatContradicts: z.ZodString;
+        proposedReplacement: z.ZodNullable<z.ZodString>;
+        severity: z.ZodEnum<["High", "Medium", "Low"]>;
+        confidence: z.ZodNumber;
+        quotedDocText: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        targetDocPath: string;
+        targetSection: string;
+        targetLineStart: number;
+        targetLineEnd: number;
+        whatChanged: string;
+        whatContradicts: string;
+        proposedReplacement: string | null;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        quotedDocText: string;
+    }, {
+        targetDocPath: string;
+        targetSection: string;
+        targetLineStart: number;
+        targetLineEnd: number;
+        whatChanged: string;
+        whatContradicts: string;
+        proposedReplacement: string | null;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        quotedDocText: string;
+    }>, "many">;
+    additions: z.ZodArray<z.ZodObject<{
+        targetDocPath: z.ZodString;
+        anchorSection: z.ZodString;
+        insertionMode: z.ZodEnum<["before", "after"]>;
+        proposedContent: z.ZodString;
+        severity: z.ZodEnum<["High", "Medium", "Low"]>;
+        confidence: z.ZodNumber;
+        whatChanged: z.ZodString;
+        rationaleForAddition: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        targetDocPath: string;
+        whatChanged: string;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        anchorSection: string;
+        insertionMode: "before" | "after";
+        proposedContent: string;
+        rationaleForAddition: string;
+    }, {
+        targetDocPath: string;
+        whatChanged: string;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        anchorSection: string;
+        insertionMode: "before" | "after";
+        proposedContent: string;
+        rationaleForAddition: string;
+    }>, "many">;
+    rawConfidence: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    contradictions: {
+        targetDocPath: string;
+        targetSection: string;
+        targetLineStart: number;
+        targetLineEnd: number;
+        whatChanged: string;
+        whatContradicts: string;
+        proposedReplacement: string | null;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        quotedDocText: string;
+    }[];
+    additions: {
+        targetDocPath: string;
+        whatChanged: string;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        anchorSection: string;
+        insertionMode: "before" | "after";
+        proposedContent: string;
+        rationaleForAddition: string;
+    }[];
+    rawConfidence: number;
+}, {
+    contradictions: {
+        targetDocPath: string;
+        targetSection: string;
+        targetLineStart: number;
+        targetLineEnd: number;
+        whatChanged: string;
+        whatContradicts: string;
+        proposedReplacement: string | null;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        quotedDocText: string;
+    }[];
+    additions: {
+        targetDocPath: string;
+        whatChanged: string;
+        severity: "High" | "Medium" | "Low";
+        confidence: number;
+        anchorSection: string;
+        insertionMode: "before" | "after";
+        proposedContent: string;
+        rationaleForAddition: string;
+    }[];
+    rawConfidence: number;
+}>;
+export type ContradictionShape = z.infer<typeof ContradictionSchema>;
+export type AdditionShape = z.infer<typeof AdditionSchema>;
+export type AnalysisResultShape = z.infer<typeof AnalysisResultSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgB9B,CAAA;AAQF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;EASzB,CAAA;AASF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAI/B,CAAA;AAKF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAuB,CAAA;AAElD,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AACpE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAC1D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA"}

package/dist/schema.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+export const ContradictionSchema = z.object({
+    targetDocPath: z.string().min(1),
+    targetSection: z.string().min(1),
+    targetLineStart: z.number().int().positive(),
+    targetLineEnd: z.number().int().positive(),
+    whatChanged: z.string().min(1),
+    whatContradicts: z.string().min(1),
+    proposedReplacement: z.string().nullable(),
+    severity: z.enum(['High', 'Medium', 'Low']),
+    confidence: z.number().int().min(1).max(5),
+    // Story 3.9b — verbatim doc-side excerpt the LLM cites as contradicted by
+    // the code change. Used by the orchestrator's reconciler to locate the cited
+    // text in the doc body and overwrite `targetLineStart` / `targetLineEnd`
+    // with the actual line range. Min length 1 — empty quotes are rejected so
+    // the LLM can't bypass grounding by emitting an empty string.
+    quotedDocText: z.string().min(1),
+});
+// Story 4.25 / 4.26 — additive finding LLM output shape. The diff introduces
+// a foundational new concept that no doc section covers but that the doc
+// would naturally describe. The LLM cites an anchor SECTION HEADING (not a
+// quoted line) plus an insertion mode + the verbatim new content to splice.
+// The orchestrator's reconciler locates the anchor section's line in the doc
+// body before the finding leaves the orchestrator.
+export const AdditionSchema = z.object({
+    targetDocPath: z.string().min(1),
+    anchorSection: z.string().min(1),
+    insertionMode: z.enum(['before', 'after']),
+    proposedContent: z.string().min(1),
+    severity: z.enum(['High', 'Medium', 'Low']),
+    confidence: z.number().int().min(1).max(5),
+    whatChanged: z.string().min(1),
+    rationaleForAddition: z.string().min(1),
+});
+// Story 4.26 — `additions` is REQUIRED (not `.optional().default([])`).
+// Mirrors `contradictions`' shape so the LLM is forced to emit an explicit
+// `[]` when no additive findings apply. The Story 4.25 shape used
+// `.optional().default([])` which the Zod→JSON-Schema conversion under
+// `withStructuredOutput` surfaces as a non-required field to the LLM — a
+// likely contributor to additive under-emission spotted in the 4.25 code
+// review.
+export const AnalysisResultSchema = z.object({
+    contradictions: z.array(ContradictionSchema),
+    additions: z.array(AdditionSchema),
+    rawConfidence: z.number().min(0).max(1),
+});
+// Public-API alias (architecture.md L1055–L1070). `AnalysisResultSchema` is
+// the historical internal name; `analysisSchema` is the camelCase public
+// surface re-exported from the barrel.
+export const analysisSchema = AnalysisResultSchema;

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+export type Severity = 'High' | 'Medium' | 'Low';
+export interface DocFile {
+    path: string;
+    content: string;
+    frontMatterLineCount: number;
+}
+export interface PRMetadata {
+    owner: string;
+    repo: string;
+    prNumber: number;
+    headSha: string;
+    baseSha: string;
+    title: string;
+}
+export interface AnalysisInput {
+    diff: string;
+    docs: DocFile[];
+    prMetadata: PRMetadata;
+}
+export interface Contradiction {
+    targetDocPath: string;
+    targetSection: string;
+    targetLineStart: number;
+    targetLineEnd: number;
+    whatChanged: string;
+    whatContradicts: string;
+    proposedReplacement: string | null;
+    severity: Severity;
+    confidence: number;
+    quotedDocText: string;
+}
+export interface Addition {
+    targetDocPath: string;
+    anchorSection: string;
+    anchorLine: number;
+    insertionMode: 'before' | 'after';
+    proposedContent: string;
+    severity: Severity;
+    confidence: number;
+    whatChanged: string;
+    rationaleForAddition: string;
+}
+export interface AnalysisResult {
+    contradictions: Contradiction[];
+    additions: Addition[];
+    rawConfidence: number;
+    narrativeOnlyContradictions?: Contradiction[];
+}
+export interface BuildPromptOptions {
+    /**
+     * When set to a positive integer, docs whose relevance score is below
+     * this threshold are dropped from the prompt before rendering. Score is
+     * computed by `selectRelevantDocs` (file-path overlap + identifier
+     * overlap + heading overlap + doc-path-in-diff). When undefined or 0,
+     * every doc in `input.docs` is included verbatim.
+     */
+    relevanceThreshold?: number;
+    /**
+     * Story P3.7.3 / FR152 — ranked-fill prompt budget. When set to a positive
+     * finite integer AND `relevanceThreshold` is also positive, retained doc
+     * sections are ranked most-relevant-first and included only while the
+     * running token total stays at-or-below this budget. Sections that don't
+     * fit are surfaced as `droppedSections` from `buildPromptWithDrops`.
+     *
+     * Default (undefined / <= 0 / non-finite) → no budget cap; every retained
+     * section is rendered (P3.7.1 retrieval-on path is unchanged). When
+     * `relevanceThreshold` is undefined / <= 0 / non-finite this option is
+     * IGNORED — there are no scored candidates to rank.
+     *
+     * Budget unit: estimated tokens via `estimatePromptTokens` (Math.ceil(len/3.5)).
+     */
+    promptTokenBudget?: number;
+}
+export interface ClarifyingQuestion {
+    whatChanged: string;
+    naturalHomeDoc: string;
+    naturalHomeSection: string;
+    question: string;
+    proposedReplacement: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAA;AAEhD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IAMf,oBAAoB,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,EAAE,CAAA;IACf,UAAU,EAAE,UAAU,CAAA;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,MAAM,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,MAAM,CAAA;IACvB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,QAAQ,EAAE,QAAQ,CAAA;IAElB,UAAU,EAAE,MAAM,CAAA;IAOlB,aAAa,EAAE,MAAM,CAAA;CACtB;AAOD,MAAM,WAAW,QAAQ;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IAIrB,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,QAAQ,GAAG,OAAO,CAAA;IACjC,eAAe,EAAE,MAAM,CAAA;IACvB,QAAQ,EAAE,QAAQ,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,oBAAoB,EAAE,MAAM,CAAA;CAC7B;AAeD,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,aAAa,EAAE,CAAA;IAC/B,SAAS,EAAE,QAAQ,EAAE,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,2BAA2B,CAAC,EAAE,aAAa,EAAE,CAAA;CAC9C;AAQD,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAQD,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC"}

package/dist/types.js

@@ -0,0 +1,6 @@
+// Pure-logic types for the drift-detection algorithm. No I/O, no wire shapes,
+// no platform-specific schema fields. The wire-shape types used by the Action
+// to talk to the hosted platform (Intake*, Config*, ReviewStatus, etc.) live
+// in `apps/action/src/ports/intake-types.ts` — those carry snake_case field
+// names load-bearing for the FR88d/FR88g contract and have no business here.
+export {};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@delfini/drift-engine",
+  "version": "0.1.0",
+  "private": false,
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "Pure-logic drift analysis core shared by @delfini/action and @delfini/cli. No I/O, no LLM client, no credentials, no fetch. Runtime deps: zod + picomatch (both pure CPU). Public API: buildPrompt, validateAndReconcile, estimatePromptTokens, analysisSchema, and the doc-scope algebra (normalizeDocScope, validateDocScopeEntry, classifyEntry, isFileInDocScope).",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./prompt.md": "./src/prompt.md"
+  },
+  "files": [
+    "dist",
+    "src/prompt.md",
+    "README.md"
+  ],
+  "dependencies": {
+    "picomatch": "^4.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/picomatch": "^4.0.0",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.5"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}