srclawyer 0.4.0

package/dist/engine/discoverFiles.d.ts

@@ -0,0 +1,7 @@
+export interface DiscoveredFiles {
+    codeFiles: string[];
+    htmlFiles: string[];
+    schemaFiles: string[];
+    manifestFiles: string[];
+}
+export declare function discoverFiles(root: string): Promise<DiscoveredFiles>;

package/dist/engine/discoverFiles.js

@@ -0,0 +1,25 @@
+import fg from "fast-glob";
+const CODE_PATTERNS = ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.mjs", "**/*.cjs"];
+const HTML_PATTERNS = ["**/*.html", "**/*.htm"];
+const SCHEMA_PATTERNS = ["**/*.graphql", "**/*.gql", "**/openapi.yaml", "**/openapi.yml", "**/openapi.json", "**/swagger.yaml", "**/swagger.yml", "**/swagger.json"];
+const MANIFEST_PATTERNS = ["**/package.json", "**/requirements.txt"];
+const IGNORE = [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/coverage/**",
+    "**/*.min.js",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/*.d.ts",
+];
+export async function discoverFiles(root) {
+    const [codeFiles, htmlFiles, schemaFiles, manifestFiles] = await Promise.all([
+        fg(CODE_PATTERNS, { cwd: root, absolute: true, ignore: IGNORE, dot: false }),
+        fg(HTML_PATTERNS, { cwd: root, absolute: true, ignore: IGNORE, dot: false }),
+        fg(SCHEMA_PATTERNS, { cwd: root, absolute: true, ignore: ["**/node_modules/**"], dot: false }),
+        fg(MANIFEST_PATTERNS, { cwd: root, absolute: true, ignore: ["**/node_modules/**"], dot: false }),
+    ]);
+    return { codeFiles, htmlFiles, schemaFiles, manifestFiles };
+}

package/dist/engine/discoverProjects.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectManifest } from "./types.js";
+export declare function discoverProjects(root: string): Promise<ProjectManifest[]>;
+export declare function describeProject(root: string, project: ProjectManifest): string;

package/dist/engine/discoverProjects.js

@@ -0,0 +1,34 @@
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import fg from "fast-glob";
+export async function discoverProjects(root) {
+    const rootPackageJsonPath = join(root, "package.json");
+    if (!existsSync(rootPackageJsonPath)) {
+        return [{ root, kind: "unknown", manifestPath: null }];
+    }
+    const rootPackageJson = JSON.parse(readFileSync(rootPackageJsonPath, "utf8"));
+    const workspacePatterns = Array.isArray(rootPackageJson.workspaces)
+        ? rootPackageJson.workspaces
+        : rootPackageJson.workspaces?.packages;
+    const lernaPath = join(root, "lerna.json");
+    const nxPath = join(root, "nx.json");
+    const hasWorkspaceConfig = Boolean(workspacePatterns) || existsSync(lernaPath) || existsSync(nxPath);
+    if (!hasWorkspaceConfig) {
+        return [{ root, kind: "node", manifestPath: rootPackageJsonPath }];
+    }
+    const patterns = workspacePatterns ?? ["packages/*", "apps/*"];
+    const manifestPaths = await fg(patterns.map((p) => join(p, "package.json")), { cwd: root, absolute: true, ignore: ["**/node_modules/**"] });
+    const projects = manifestPaths.map((manifestPath) => ({
+        root: dirname(manifestPath),
+        kind: "node",
+        manifestPath,
+    }));
+    if (projects.length === 0) {
+        return [{ root, kind: "node", manifestPath: rootPackageJsonPath }];
+    }
+    return projects;
+}
+export function describeProject(root, project) {
+    const rel = relative(root, project.root);
+    return rel === "" ? "." : rel;
+}

package/dist/engine/languageDetection.d.ts

@@ -0,0 +1 @@
+export declare function detectUnsupportedStack(root: string): Promise<string | null>;

package/dist/engine/languageDetection.js

@@ -0,0 +1,48 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import fg from "fast-glob";
+const IGNORE = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**", "**/vendor/**"];
+const SUPPORTED_EXTENSIONS = ["ts", "tsx", "js", "jsx", "mjs", "cjs", "html", "htm"];
+const UNSUPPORTED_LANGUAGES = [
+    { label: "Python", extensions: ["py"] },
+    { label: "Ruby", extensions: ["rb"] },
+    { label: "Go", extensions: ["go"] },
+    { label: "Java", extensions: ["java"] },
+    { label: "PHP", extensions: ["php"] },
+    { label: "C#", extensions: ["cs"] },
+];
+function bannerize(message) {
+    return `UNSUPPORTED CODEBASE — ${message} SrcLawyer only analyzes JavaScript/TypeScript and HTML today; the findings below (if any) are incomplete and MUST NOT be treated as a full compliance scan.`;
+}
+async function detectFrameworkSignature(root) {
+    if (existsSync(join(root, "manage.py"))) {
+        return bannerize("Django detected (manage.py found at the project root).");
+    }
+    const hasGemfile = existsSync(join(root, "Gemfile"));
+    const hasRailsLayout = existsSync(join(root, "config", "routes.rb")) || existsSync(join(root, "app", "controllers"));
+    if (hasGemfile && hasRailsLayout) {
+        return bannerize("Rails detected (Gemfile + a Rails app/config layout found).");
+    }
+    const protoFiles = await fg("**/*.proto", { cwd: root, ignore: IGNORE, dot: false });
+    if (protoFiles.length > 0) {
+        return bannerize(`gRPC/Protocol Buffers detected (${protoFiles.length} .proto file(s) found) — protobuf schemas are not parsed.`);
+    }
+    return null;
+}
+async function detectDominantUnsupportedLanguage(root) {
+    const [supportedFiles, ...unsupportedGroups] = await Promise.all([
+        fg(SUPPORTED_EXTENSIONS.map((ext) => `**/*.${ext}`), { cwd: root, ignore: IGNORE, dot: false }),
+        ...UNSUPPORTED_LANGUAGES.map((lang) => fg(lang.extensions.map((ext) => `**/*.${ext}`), { cwd: root, ignore: IGNORE, dot: false })),
+    ]);
+    const counts = UNSUPPORTED_LANGUAGES.map((lang, i) => ({ label: lang.label, count: unsupportedGroups[i].length }));
+    const dominant = counts.filter((c) => c.count > 0).sort((a, b) => b.count - a.count)[0];
+    if (!dominant || dominant.count <= supportedFiles.length)
+        return null;
+    return bannerize(`${dominant.label} detected as the primary language (${dominant.count} file(s), vs ${supportedFiles.length} supported JS/TS/HTML file(s)).`);
+}
+export async function detectUnsupportedStack(root) {
+    const frameworkWarning = await detectFrameworkSignature(root);
+    if (frameworkWarning)
+        return frameworkWarning;
+    return detectDominantUnsupportedLanguage(root);
+}

package/dist/engine/scanEngine.d.ts

@@ -0,0 +1,11 @@
+import type { ScanResult } from "./types.js";
+/**
+ * Pure, local, offline — no network access anywhere in this function or anything it calls. Zod
+ * schemas and confidence scoring can no longer be fully resolved here (see pendingZodCandidates and
+ * every Finding.confidenceFactors) — resolving those against the protected-logic service is a
+ * separate, explicit step in src/cloud/resolveProtectedLogic.ts, called from commands/scan.ts, the
+ * same way Layer 2's resolveAmbiguousFindings.ts is a separate step layered on top of this function
+ * rather than folded into it. Anyone auditing "does this touch the network" can still answer that by
+ * reading this file alone.
+ */
+export declare function scan(root: string): Promise<ScanResult>;

package/dist/engine/scanEngine.js

@@ -0,0 +1,130 @@
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import { discoverProjects } from "./discoverProjects.js";
+import { discoverFiles } from "./discoverFiles.js";
+import { detectUnsupportedStack } from "./languageDetection.js";
+import { parseSource } from "./astUtils.js";
+import { runSdkRules } from "../rules/sdkRules.js";
+import { runFrameworkRules } from "../rules/frameworkRules.js";
+import { runWebApiRules } from "../rules/webApiRules.js";
+import { runTypedRequestBodyRules } from "../rules/typedRequestBodyRules.js";
+import { findZodCandidates } from "../rules/zodPreFilter.js";
+import { buildTsProject } from "./tsProject.js";
+import { runHtmlInputRules, extractInlineScripts } from "../rules/htmlRules.js";
+import { parseOpenApiSpec } from "../schemaParsers/openapi.js";
+import { parseGraphQLSchema } from "../schemaParsers/graphql.js";
+const OPENAPI_NAME = /(openapi|swagger)\.(ya?ml|json)$/i;
+const GRAPHQL_NAME = /\.(graphql|gql)$/i;
+// Built at most once per project root, per scan, and only the first time a rule actually needs it
+// (see typedRequestBodyRules.ts) — measured against the real dub/formbricks golden-corpus repos at
+// ~2.5s/~800MB and ~2.2s/~650MB respectively for a full ts.Program build. Eager construction would tax
+// every scan of a large project regardless of whether it ever hits the one pattern that needs it;
+// memoized-lazy pays that cost at most once, only on the scan that actually earns it.
+function makeLazyTsProject(files) {
+    let handle;
+    return () => {
+        if (handle === undefined) {
+            try {
+                handle = buildTsProject(files);
+            }
+            catch {
+                handle = null;
+            }
+        }
+        return handle;
+    };
+}
+function runCodeRules(filePath, source, root, getTsProject, zodCandidates) {
+    const ast = parseSource(source, filePath);
+    zodCandidates.push(...findZodCandidates(source, filePath, root));
+    if (!ast)
+        return [];
+    return [
+        ...runSdkRules(ast, filePath, source, root),
+        ...runFrameworkRules(ast, filePath, source, root),
+        ...runWebApiRules(ast, filePath, source, root),
+        ...runTypedRequestBodyRules(ast, filePath, source, root, getTsProject),
+    ];
+}
+/**
+ * Pure, local, offline — no network access anywhere in this function or anything it calls. Zod
+ * schemas and confidence scoring can no longer be fully resolved here (see pendingZodCandidates and
+ * every Finding.confidenceFactors) — resolving those against the protected-logic service is a
+ * separate, explicit step in src/cloud/resolveProtectedLogic.ts, called from commands/scan.ts, the
+ * same way Layer 2's resolveAmbiguousFindings.ts is a separate step layered on top of this function
+ * rather than folded into it. Anyone auditing "does this touch the network" can still answer that by
+ * reading this file alone.
+ */
+export async function scan(root) {
+    const [projects, unsupportedStackWarning] = await Promise.all([discoverProjects(root), detectUnsupportedStack(root)]);
+    const findings = [];
+    const pendingZodCandidates = [];
+    let filesScanned = 0;
+    const projectRootList = [...new Set(projects.map((p) => p.root))];
+    const fileSets = await Promise.all(projectRootList.map((projectRoot) => discoverFiles(projectRoot)));
+    const allCodeFiles = new Set();
+    const allHtmlFiles = new Set();
+    const allSchemaFiles = new Set();
+    const rootForFile = new Map();
+    const tsProjectByRoot = new Map();
+    fileSets.forEach((set, i) => {
+        const projectRoot = projectRootList[i];
+        tsProjectByRoot.set(projectRoot, makeLazyTsProject(set.codeFiles));
+        set.codeFiles.forEach((f) => {
+            allCodeFiles.add(f);
+            rootForFile.set(f, projectRoot);
+        });
+        set.htmlFiles.forEach((f) => allHtmlFiles.add(f));
+        set.schemaFiles.forEach((f) => allSchemaFiles.add(f));
+    });
+    // HTML files (and their inline <script> blocks) aren't part of any codeFiles list and never carry
+    // a resolvable TS type, so they get a permanently-null thunk rather than a project association.
+    const noTsProject = () => null;
+    for (const filePath of allCodeFiles) {
+        filesScanned += 1;
+        let source;
+        try {
+            source = readFileSync(filePath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const getTsProject = tsProjectByRoot.get(rootForFile.get(filePath) ?? "") ?? noTsProject;
+        findings.push(...runCodeRules(filePath, source, root, getTsProject, pendingZodCandidates));
+    }
+    for (const filePath of allHtmlFiles) {
+        filesScanned += 1;
+        let html;
+        try {
+            html = readFileSync(filePath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        findings.push(...runHtmlInputRules(html, filePath, root));
+        for (const script of extractInlineScripts(html)) {
+            findings.push(...runCodeRules(filePath, script.code, root, noTsProject, pendingZodCandidates));
+        }
+    }
+    for (const filePath of allSchemaFiles) {
+        filesScanned += 1;
+        if (OPENAPI_NAME.test(filePath)) {
+            try {
+                findings.push(...parseOpenApiSpec(filePath, root));
+            }
+            catch {
+                continue;
+            }
+        }
+        else if (GRAPHQL_NAME.test(filePath) || extname(filePath) === ".graphql") {
+            try {
+                findings.push(...parseGraphQLSchema(filePath, root));
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    const ambiguousCount = findings.filter((f) => f.requiresReview).length;
+    return { projects, findings, ambiguousCount, filesScanned, unsupportedStackWarning, pendingZodCandidates };
+}

package/dist/engine/secretRedaction.d.ts

@@ -0,0 +1,2 @@
+export declare function redactSecrets(source: string): string;
+export declare function containsLikelySecret(source: string): boolean;

package/dist/engine/secretRedaction.js

@@ -0,0 +1,31 @@
+const SECRET_PATTERNS = [
+    /sk_live_[A-Za-z0-9]{16,}/g,
+    /sk_test_[A-Za-z0-9]{16,}/g,
+    /pk_live_[A-Za-z0-9]{16,}/g,
+    // Anthropic API keys — matched by shape alone (like the patterns above), not by the surrounding
+    // variable name or quoting, so `key = "sk-ant-..."` and an unquoted `KEY=sk-ant-...` both redact.
+    /sk-ant-[A-Za-z0-9_-]{20,}/g,
+    /AKIA[0-9A-Z]{16}/g,
+    /AIza[0-9A-Za-z\-_]{35}/g,
+    /ghp_[A-Za-z0-9]{36}/g,
+    /xox[baprs]-[A-Za-z0-9-]{10,}/g,
+    /SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/g,
+    /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
+    /postgres(?:ql)?:\/\/[^\s"'`]+/gi,
+    /mongodb(?:\+srv)?:\/\/[^\s"'`]+/gi,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]+?-----END [A-Z ]*PRIVATE KEY-----/g,
+    /(?:api[_-]?key|secret|token|password|passwd)\s*[:=]\s*["'`][^"'`\s]{12,}["'`]/gi,
+];
+export function redactSecrets(source) {
+    let redacted = source;
+    for (const pattern of SECRET_PATTERNS) {
+        redacted = redacted.replace(pattern, "[REDACTED]");
+    }
+    return redacted;
+}
+export function containsLikelySecret(source) {
+    return SECRET_PATTERNS.some((pattern) => {
+        pattern.lastIndex = 0;
+        return pattern.test(source);
+    });
+}

package/dist/engine/tsProject.d.ts

@@ -0,0 +1,4 @@
+export interface TsProjectHandle {
+    getObjectTypeMembersAt(filePath: string, line: number, column: number): string[] | null;
+}
+export declare function buildTsProject(files: string[]): TsProjectHandle;

package/dist/engine/tsProject.js

@@ -0,0 +1,68 @@
+import ts from "typescript";
+// Purely defensive, not a tuned threshold: the largest repo actually measured (dub, 4211 files) took
+// ~2.5s/~800MB to build. This is ~5x that, so a project this large skips type resolution entirely
+// rather than attempting an untested, unbounded-cost ts.createProgram call.
+const MAX_PROGRAM_FILES = 20_000;
+const NULL_HANDLE = {
+    getObjectTypeMembersAt: () => null,
+};
+function findNodeAtPosition(root, position) {
+    if (position < root.getFullStart() || position >= root.getEnd()) {
+        return root.getStart() <= position && position < root.getEnd() ? root : undefined;
+    }
+    let found;
+    root.forEachChild((child) => {
+        if (found)
+            return;
+        if (position >= child.getFullStart() && position < child.getEnd()) {
+            found = findNodeAtPosition(child, position) ?? child;
+        }
+    });
+    return found ?? (root.getStart() <= position && position < root.getEnd() ? root : undefined);
+}
+export function buildTsProject(files) {
+    if (files.length === 0 || files.length > MAX_PROGRAM_FILES)
+        return NULL_HANDLE;
+    let program;
+    let checker;
+    try {
+        program = ts.createProgram(files, {
+            allowJs: true,
+            checkJs: false,
+            noEmit: true,
+            skipLibCheck: true,
+        });
+        checker = program.getTypeChecker();
+    }
+    catch {
+        return NULL_HANDLE;
+    }
+    return {
+        getObjectTypeMembersAt(filePath, line, column) {
+            try {
+                const sourceFile = program.getSourceFile(filePath);
+                if (!sourceFile)
+                    return null;
+                const position = ts.getPositionOfLineAndCharacter(sourceFile, line - 1, column);
+                const node = findNodeAtPosition(sourceFile, position);
+                if (!node)
+                    return null;
+                const type = checker.getTypeAtLocation(node);
+                // Primitives (number/string/boolean) have non-empty "properties" too — their boxed prototype
+                // methods (toFixed, toUpperCase, ...) — which getPropertiesOfType happily returns. Only a real
+                // object type (an interface, a type literal, a class) is a genuine request-body shape.
+                if (!(type.flags & ts.TypeFlags.Object))
+                    return null;
+                const properties = checker.getPropertiesOfType(type);
+                if (properties.length === 0)
+                    return null;
+                return properties.map((p) => p.getName());
+            }
+            catch {
+                // Never let a target project's own type errors, an out-of-range position, or any other
+                // resolution failure break the scan — an honest "couldn't resolve this" is a null, not a throw.
+                return null;
+            }
+        },
+    };
+}

package/dist/engine/types.d.ts

@@ -0,0 +1,71 @@
+export type DataCategory = "email" | "name" | "phone" | "physical_address" | "payment_info" | "government_id" | "device_id" | "ip_address" | "location" | "analytics_usage" | "authentication_credentials" | "childrens_data" | "health_data" | "microphone_audio" | "camera_video" | "generic_pii";
+export type Confidence = "high" | "medium" | "low";
+export type ResolutionOutcome = "resolved" | "declined" | "unresolved";
+export interface LlmResolution {
+    outcome: ResolutionOutcome;
+    reason: string | null;
+    provider: string;
+    model: string | null;
+    resolvedDataCategories?: DataCategory[];
+    resolvedDescription?: string;
+}
+export interface CodeLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+export interface Finding {
+    id: string;
+    dataCategories: DataCategory[];
+    processor: string | null;
+    description: string;
+    confidence: Confidence;
+    source: "sdk-rule" | "framework-rule" | "web-api-rule" | "html-input-rule" | "openapi" | "graphql" | "zod-rule" | "type-rule";
+    location: CodeLocation;
+    evidence: string;
+    requiresReview: boolean;
+    /**
+     * Present only for findings that were run through Layer 2 resolution.
+     * Absent means: free tier, --no-llm, or requiresReview was already false —
+     * this finding was never sent to an LLM at all.
+     */
+    llmResolution?: LlmResolution;
+    /**
+     * Present ONLY for findings whose confidence/requiresReview are provisional, pending the
+     * protected-logic scoring call (src/cloud/protectedLogicClient.ts) — the fields captured here are
+     * exactly what that endpoint needs (field names and derived yes/no signals, never source code).
+     * Until scored, `confidence`/`requiresReview` hold the safe fallback ("low"/true). Absent entirely
+     * for findings whose confidence is fixed locally (sdkRules, webApiRules, htmlRules, schema parsers)
+     * and never sent anywhere.
+     */
+    confidenceFactors?: Record<string, boolean | number | string | null>;
+}
+export interface ProcessorProfile {
+    name: string;
+    dataCategories: DataCategory[];
+    disclosureNotes: string;
+}
+export interface ProjectManifest {
+    root: string;
+    kind: "node" | "unknown";
+    manifestPath: string | null;
+}
+export interface ScanResult {
+    projects: ProjectManifest[];
+    findings: Finding[];
+    ambiguousCount: number;
+    filesScanned: number;
+    unsupportedStackWarning: string | null;
+    /**
+     * Files that look like they might define a Zod schema used to validate incoming request data —
+     * unconfirmed, since the actual schema/anchor detection is protected logic and runs server-side.
+     * Resolved (or, on failure, honestly left unresolved) by resolveProtectedLogic() in
+     * commands/scan.ts, exactly like requiresReview findings are resolved by Layer 2's
+     * resolveAmbiguousFindings() — not inside scan() itself, which stays pure/offline.
+     */
+    pendingZodCandidates: Array<{
+        id: string;
+        codeFragment: string;
+        fragmentLineToSourceLine: number[];
+    }>;
+}

package/dist/engine/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public library surface for `srclawyer`.
+ *
+ * This is the ONLY supported way for other packages (including the private detection-rules
+ * package) to depend on this repo's code. Everything else under src/ is an internal implementation
+ * detail and may change without notice — import from here, never from a deep relative/dist path.
+ */
+export { redactSecrets, containsLikelySecret } from "./engine/secretRedaction.js";
+export { parseSource } from "./engine/astUtils.js";
+export type { DataCategory, Confidence, ResolutionOutcome, LlmResolution, CodeLocation, Finding, ProcessorProfile, ProjectManifest, ScanResult, } from "./engine/types.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * Public library surface for `srclawyer`.
+ *
+ * This is the ONLY supported way for other packages (including the private detection-rules
+ * package) to depend on this repo's code. Everything else under src/ is an internal implementation
+ * detail and may change without notice — import from here, never from a deep relative/dist path.
+ */
+export { redactSecrets, containsLikelySecret } from "./engine/secretRedaction.js";
+export { parseSource } from "./engine/astUtils.js";

package/dist/llm/anthropicProvider.d.ts

@@ -0,0 +1,8 @@
+import type { LlmBatchRequest, LlmProvider, LlmResponseItem } from "./types.js";
+export declare class AnthropicProvider implements LlmProvider {
+    readonly name = "anthropic";
+    readonly model: string;
+    private readonly apiKey;
+    constructor(apiKey: string, model?: string);
+    resolveBatch(request: LlmBatchRequest): Promise<LlmResponseItem[]>;
+}

package/dist/llm/anthropicProvider.js

@@ -0,0 +1,130 @@
+import { DATA_CATEGORY_LABELS } from "../policy/dataCategoryLabels.js";
+const ANTHROPIC_API_URL = "https://api.anthropic.com/v1/messages";
+const ANTHROPIC_VERSION = "2023-06-01";
+// Confirm this is still current at implementation/release time.
+const DEFAULT_MODEL = "claude-sonnet-5";
+const REQUEST_TIMEOUT_MS = 30_000;
+// Same source of truth resolveAmbiguousFindings.ts validates responses against (KNOWN_CATEGORIES) —
+// constraining the tool schema to this enum means a legitimate resolution can no longer be discarded
+// as "unrecognized category" just because the model wasn't told what vocabulary to stay inside.
+const DATA_CATEGORY_VALUES = Object.keys(DATA_CATEGORY_LABELS);
+const RESOLUTION_TOOL = {
+    name: "report_resolutions",
+    description: "Report a classification decision for each numbered data-collection finding provided.",
+    input_schema: {
+        type: "object",
+        properties: {
+            resolutions: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        findingId: { type: "string" },
+                        outcome: { type: "string", enum: ["resolved", "declined"] },
+                        reason: {
+                            type: ["string", "null"],
+                            description: 'Required when outcome is "declined": explain concretely why this could not be confidently classified. Null when resolved.',
+                        },
+                        resolvedDataCategories: {
+                            type: "array",
+                            items: { type: "string", enum: DATA_CATEGORY_VALUES },
+                            description: "Only when outcome is \"resolved\". Must use these exact category values — never a category outside this list.",
+                        },
+                        resolvedDescription: { type: "string" },
+                    },
+                    required: ["findingId", "outcome", "reason"],
+                },
+            },
+        },
+        required: ["resolutions"],
+    },
+};
+function buildSystemPrompt() {
+    return [
+        "You are assisting a static-analysis privacy-compliance tool. You will be given a list of code-derived findings that automated pattern matching could not confidently classify into a personal-data category.",
+        "For each item, decide whether you can confidently classify what kind of personal data it represents based ONLY on the redacted evidence and description given — do not assume context that isn't shown.",
+        'If confident, set outcome to "resolved" and provide resolvedDataCategories and a short resolvedDescription.',
+        'If not confident, set outcome to "declined" and give a concrete, specific reason — never guess.',
+        'Any item marked isHighStakes must ALWAYS be "declined" with a reason noting it requires manual/legal review, regardless of how confident you feel — this is a hard rule, not a suggestion.',
+        "Respond only by calling the report_resolutions tool with exactly one entry per item given, in the same findingId order.",
+    ].join(" ");
+}
+export class AnthropicProvider {
+    name = "anthropic";
+    model;
+    apiKey;
+    constructor(apiKey, model = DEFAULT_MODEL) {
+        this.apiKey = apiKey;
+        this.model = model;
+    }
+    async resolveBatch(request) {
+        const userContent = JSON.stringify(request.items.map((item) => ({
+            findingId: item.findingId,
+            dataCategories: item.dataCategories,
+            isHighStakes: item.isHighStakes,
+            evidence: item.redactedEvidence,
+            description: item.redactedDescription,
+        })), null, 2);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        let response;
+        try {
+            response = await fetch(ANTHROPIC_API_URL, {
+                method: "POST",
+                headers: {
+                    "x-api-key": this.apiKey,
+                    "anthropic-version": ANTHROPIC_VERSION,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({
+                    model: this.model,
+                    max_tokens: 4096,
+                    system: buildSystemPrompt(),
+                    messages: [{ role: "user", content: userContent }],
+                    tools: [RESOLUTION_TOOL],
+                    tool_choice: { type: "tool", name: "report_resolutions" },
+                }),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            throw new Error(`Anthropic API request failed (${response.status}): ${body.slice(0, 200)}`);
+        }
+        const payload = (await response.json());
+        const toolUse = payload.content?.find((block) => block.type === "tool_use" && block.name === "report_resolutions");
+        if (!toolUse || typeof toolUse.input !== "object" || toolUse.input === null) {
+            throw new Error("Anthropic response did not include a valid report_resolutions tool call");
+        }
+        const input = toolUse.input;
+        if (!Array.isArray(input.resolutions)) {
+            throw new Error("Anthropic tool response missing a resolutions array");
+        }
+        return input.resolutions.map(normalizeResponseItem).filter((item) => item !== null);
+    }
+}
+// Anthropic's tool-use output reliably omits `reason` entirely for a "resolved" item — despite it being
+// listed in `required` — rather than sending an explicit `null` (confirmed against a real response during
+// live verification on 2026-09-13). Treating an omitted key as invalid, rather than as the `null` the field
+// means when resolved, was silently discarding otherwise-correct resolutions as "malformed."
+function normalizeResponseItem(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const item = value;
+    if (typeof item.findingId !== "string")
+        return null;
+    if (item.outcome !== "resolved" && item.outcome !== "declined")
+        return null;
+    if (item.reason !== null && item.reason !== undefined && typeof item.reason !== "string")
+        return null;
+    return {
+        findingId: item.findingId,
+        outcome: item.outcome,
+        reason: item.reason ?? null,
+        resolvedDataCategories: item.resolvedDataCategories,
+        resolvedDescription: item.resolvedDescription,
+    };
+}

package/dist/llm/buildRequestItem.d.ts

@@ -0,0 +1,10 @@
+import type { Finding } from "../engine/types.js";
+import type { LlmRequestItem } from "./types.js";
+/**
+ * The only function permitted to read finding.evidence/description for
+ * Layer 2 purposes. Both fields are passed through redactSecrets() before
+ * they leave this function — LlmRequestItem has no raw-evidence field, so a
+ * provider implementation is structurally incapable of receiving
+ * unredacted content.
+ */
+export declare function buildRequestItem(finding: Finding, collectsChildrensData: boolean): LlmRequestItem;

package/dist/llm/buildRequestItem.js

@@ -0,0 +1,17 @@
+import { redactSecrets } from "../engine/secretRedaction.js";
+/**
+ * The only function permitted to read finding.evidence/description for
+ * Layer 2 purposes. Both fields are passed through redactSecrets() before
+ * they leave this function — LlmRequestItem has no raw-evidence field, so a
+ * provider implementation is structurally incapable of receiving
+ * unredacted content.
+ */
+export function buildRequestItem(finding, collectsChildrensData) {
+    return {
+        findingId: finding.id,
+        redactedEvidence: redactSecrets(finding.evidence),
+        redactedDescription: redactSecrets(finding.description),
+        dataCategories: finding.dataCategories,
+        isHighStakes: finding.dataCategories.includes("childrens_data") || collectsChildrensData,
+    };
+}

package/dist/llm/resolveAmbiguousFindings.d.ts

@@ -0,0 +1,7 @@
+import type { Finding } from "../engine/types.js";
+import type { LlmProvider } from "./types.js";
+export interface ResolveAmbiguousFindingsOptions {
+    collectsChildrensData: boolean;
+    batchSize?: number;
+}
+export declare function resolveAmbiguousFindings(findings: Finding[], provider: LlmProvider, options: ResolveAmbiguousFindingsOptions): Promise<Finding[]>;