@dataparade/cli 0.0.1

package/dist/src/ai-enrichment/pii-signal-rules.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearPiiSignalRulesCacheForTest = clearPiiSignalRulesCacheForTest;
+exports.loadPiiSignalRules = loadPiiSignalRules;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const yaml_1 = __importDefault(require("yaml"));
+const zod_1 = require("zod");
+const piiSignalRuleSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1),
+    category: zod_1.z.enum(["identifiers", "profile_data", "credentials"]),
+    labels: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+    patterns: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+});
+const piiSignalCatalogSchema = zod_1.z.object({
+    pii_signal_rules: zod_1.z.array(piiSignalRuleSchema).default([]),
+});
+let cachedRules;
+function clearPiiSignalRulesCacheForTest() {
+    cachedRules = undefined;
+}
+function getPiiSignalRulesPath() {
+    const parts = __dirname.split(path_1.default.sep);
+    const distIndex = parts.lastIndexOf("dist");
+    const cliRoot = distIndex !== -1
+        ? parts.slice(0, distIndex).join(path_1.default.sep)
+        : path_1.default.resolve(__dirname, "..", "..");
+    return path_1.default.join(cliRoot, "patterns", "pii-signals.rules.yaml");
+}
+function loadPiiSignalRules() {
+    if (cachedRules)
+        return cachedRules;
+    const configPath = getPiiSignalRulesPath();
+    let raw;
+    try {
+        raw = fs_1.default.readFileSync(configPath, "utf8");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`PII signal rules are required but could not be read from '${configPath}': ${message}`);
+    }
+    let parsed;
+    try {
+        parsed = yaml_1.default.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`PII signal rules at '${configPath}' could not be parsed as YAML: ${message}`);
+    }
+    let normalized;
+    try {
+        normalized = piiSignalCatalogSchema.parse(parsed);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`PII signal rules at '${configPath}' failed schema validation: ${message}`);
+    }
+    cachedRules = normalized.pii_signal_rules.map((rule) => ({
+        id: rule.id.trim().toLowerCase(),
+        category: rule.category,
+        labels: rule.labels.map((label) => label.trim()).filter(Boolean),
+        patterns: rule.patterns.map((pattern) => new RegExp(pattern, "i")),
+    }));
+    return cachedRules;
+}

package/dist/src/ai-enrichment/pipeline.d.ts

@@ -0,0 +1,2 @@
+import type { InferencePipelineResult, RunInferencePipelineInput, RunInferencePipelineOptions } from "./types";
+export declare function runInferencePipeline(input: RunInferencePipelineInput, options?: RunInferencePipelineOptions): Promise<InferencePipelineResult>;

package/dist/src/ai-enrichment/pipeline.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInferencePipeline = runInferencePipeline;
+const candidate_selector_1 = require("./candidate-selector");
+const merge_rules_1 = require("./merge-rules");
+const planner_1 = require("./planner");
+const DEFAULT_PLANNER_OPTIONS = {
+    totalBudgetTokens: 12_000,
+    maxModelCalls: 12,
+    maxCandidatesPerAgent: 25,
+};
+async function runInferencePipeline(input, options = {}) {
+    const components = input.components;
+    const candidates = (0, candidate_selector_1.selectInferenceCandidates)({
+        components,
+        dataFlows: input.dataFlows,
+        sections: input.sections,
+        inferenceScope: input.inferenceScope ?? "default",
+    });
+    const plannerOptions = {
+        ...DEFAULT_PLANNER_OPTIONS,
+        ...(input.plannerOptions ?? {}),
+    };
+    const plan = (0, planner_1.planInferenceQueues)(candidates, plannerOptions);
+    const proposalContext = {
+        candidates,
+        plan,
+        components: input.components,
+        dataFlows: input.dataFlows,
+        sections: input.sections,
+        files: input.files,
+        findings: input.findings,
+    };
+    const generation = options.generateProposals
+        ? await options.generateProposals(proposalContext)
+        : { proposals: [] };
+    const proposals = generation.proposals;
+    const mergeResult = (0, merge_rules_1.mergeAiProposals)(components, input.dataFlows, proposals, {}, {
+        enforceIntraSectionFlowChangesOnly: true,
+    });
+    return {
+        candidates,
+        plan,
+        proposals,
+        usageSummary: generation.usageSummary,
+        mergeResult,
+    };
+}

package/dist/src/ai-enrichment/planner.d.ts

@@ -0,0 +1,2 @@
+import type { AiInferenceCandidate, InferencePlannerOptions, InferencePlannerResult } from "./types";
+export declare function planInferenceQueues(candidates: AiInferenceCandidate[], options: InferencePlannerOptions): InferencePlannerResult;

package/dist/src/ai-enrichment/planner.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planInferenceQueues = planInferenceQueues;
+const AGENT_BY_CANDIDATE_TYPE = {
+    third_party: "tpAgent",
+    node_property: "propertyAgent",
+    flow_direction: "directionAgent",
+    missing_interaction: "interactionAgent",
+};
+function divideEvenly(total, buckets) {
+    if (buckets <= 0)
+        return [];
+    const base = Math.floor(total / buckets);
+    const rem = total % buckets;
+    return Array.from({ length: buckets }, (_, i) => base + (i < rem ? 1 : 0));
+}
+function planInferenceQueues(candidates, options) {
+    const grouped = new Map();
+    const droppedCandidates = [];
+    // `0` or omitted → no per-agent cap (queue every candidate). Otherwise cap
+    // queue length; pipeline defaults pass `25` from `ScanConfiguration`.
+    const rawCap = options.maxCandidatesPerAgent;
+    const maxCandidatesPerAgent = rawCap === 0 || rawCap === undefined
+        ? Number.MAX_SAFE_INTEGER
+        : Math.max(1, rawCap);
+    for (const candidate of candidates) {
+        const agent = AGENT_BY_CANDIDATE_TYPE[candidate.candidateType];
+        const queue = grouped.get(agent) ?? [];
+        if (queue.length >= maxCandidatesPerAgent) {
+            droppedCandidates.push({
+                candidateId: candidate.id,
+                reason: "agent_queue_capacity_exceeded",
+            });
+            continue;
+        }
+        queue.push(candidate);
+        grouped.set(agent, queue);
+    }
+    const queues = Array.from(grouped.entries())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([agent, queue]) => ({
+        agent,
+        queue: queue.sort((x, y) => {
+            if (x.priority !== y.priority)
+                return y.priority - x.priority;
+            return x.id.localeCompare(y.id);
+        }),
+        budgetTokens: 0,
+        maxModelCalls: 0,
+    }));
+    const totalBudgetTokens = options.totalBudgetTokens;
+    const totalMaxModelCalls = options.maxModelCalls;
+    const tokenSlices = divideEvenly(totalBudgetTokens, queues.length);
+    const callSlices = divideEvenly(totalMaxModelCalls, queues.length);
+    for (let i = 0; i < queues.length; i += 1) {
+        queues[i].budgetTokens = tokenSlices[i] ?? 0;
+        queues[i].maxModelCalls = callSlices[i] ?? 0;
+    }
+    return { queues, droppedCandidates };
+}

package/dist/src/ai-enrichment/prompts/provider-enrichment-prompts.d.ts

@@ -0,0 +1,12 @@
+/**
+ * System prompts for scan enrichment. Kept separate from provider HTTP implementations
+ * so each provider can compose instructions without duplicating the full contract text.
+ */
+/** Shared system instructions for OpenAI, Anthropic, Gemini, and local/Ollama providers. */
+export declare const AI_PROVIDER_SYSTEM_PROMPT = "You are enriching a DataParade data-flow scan. Respond with a JSON object matching the response schema: top-level key \"proposals\" (array). No markdown fences.\n\nPrimary goal: **only** populate node properties when each value is **directly supported** by code or config text in `relevantFileContents` (when present) or by explicit paths in `detectedFrom` / `sourceLocations` for that component. If support is weak, indirect, or guessed, **omit** the property. It is always valid to return **zero** proposals or a patch with **few** `setProperties` keys.\n\nUse **ComponentPatch only** in the proposals array (schema may list a flow variant for compatibility; omit it).\n\nComponentPatch (property filling):\n- kind: \"component_patch\"\n- targetComponentId: string (**must exactly equal one of the componentContext object keys / canonical component IDs**)\n- candidateType: match the user payload agent/candidates (usually \"third_party\" or \"node_property\")\n- setSubType: string \u2014 **required** when componentContext.subType is empty/null; use one taxonomy token: b2b_customer, saas_service, payment_processor, cloud_provider, api_provider, ai_provider, data_provider, government_regulator, partner, ad_network, professional_services, data_processor, other (snake_case). Omit setSubType only when componentContext already has subType.\n- setDescription?: string when helpful\n- setProperties: object with snake_case keys; **only** keys you can tie to cited evidence (see propertyEvidence)\n- propertyEvidence: **required**. Object whose keys are exactly the keys you put in setProperties; each value is a **non-empty** array of evidence rows: { \"filePath\", \"startLine\", \"endLine\", \"reason\" }. Every property must cite where in the repo that value comes from; different properties may cite different files or line ranges.\n- confidence: { \"score\": number 0.72\u20130.95 when patch is well supported, \"band\": \"high\" | \"medium\" | \"low\" }\n- evidence: optional legacy field; prefer propertyEvidence only.\n\nPrefer **one ComponentPatch per target component** when you have support \u2014 not a large speculative bag of guesses.\n\n**Do not emit FlowPatch proposals.** Connectivity comes from deterministic scan rules.\n\nRules:\n- Do not contradict propertiesSet unless fixing a clear error with cited proof.\n- `targetComponentId` must be a canonical component ID from componentContext keys only. Never emit file paths or folder names as targetComponentId.\n- **Anti-fabrication:** same as above \u2014 if the fact is not in the cited lines / excerpt text, omit the property.\n- Do not emit placeholder `setProperties` values (null, \"none\", empty arrays, empty strings), and do not set `inference_status`.\n\nsetProperties value shapes: use snake_case keys from sparsePropertyKeys. integration_method must be a string array (e.g. [\"api\"]), never a single string. authentication_method must be one string token (e.g. api_key, oauth_2_0), never an array. processing_purpose must be a string array of taxonomy tokens (authentication, security, analytics, service_provision, payment_processing, marketing, compliance, other, etc.)\u2014snake_case. Other multi-value fields must be string arrays, not comma-joined strings.";
+/**
+ * Anthropic has no server-side JSON schema for this path; truncated output yields invalid JSON.
+ * Reinforce brevity so the model completes a single well-formed object.
+ */
+export declare const ANTHROPIC_ENRICHMENT_SYSTEM_PROMPT_SUPPLEMENT = "Output discipline: Your entire reply must be one parseable JSON object (no markdown). Keep each propertyEvidence \"reason\" to one short clause. If many properties apply, return fewer patches or fewer keys per patch so the JSON always completes \u2014 never stop mid-string or mid-object.";
+export declare function buildAnthropicEnrichmentSystemPrompt(): string;

package/dist/src/ai-enrichment/prompts/provider-enrichment-prompts.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * System prompts for scan enrichment. Kept separate from provider HTTP implementations
+ * so each provider can compose instructions without duplicating the full contract text.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANTHROPIC_ENRICHMENT_SYSTEM_PROMPT_SUPPLEMENT = exports.AI_PROVIDER_SYSTEM_PROMPT = void 0;
+exports.buildAnthropicEnrichmentSystemPrompt = buildAnthropicEnrichmentSystemPrompt;
+/** Shared system instructions for OpenAI, Anthropic, Gemini, and local/Ollama providers. */
+exports.AI_PROVIDER_SYSTEM_PROMPT = `You are enriching a DataParade data-flow scan. Respond with a JSON object matching the response schema: top-level key "proposals" (array). No markdown fences.
+
+Primary goal: **only** populate node properties when each value is **directly supported** by code or config text in \`relevantFileContents\` (when present) or by explicit paths in \`detectedFrom\` / \`sourceLocations\` for that component. If support is weak, indirect, or guessed, **omit** the property. It is always valid to return **zero** proposals or a patch with **few** \`setProperties\` keys.
+
+Use **ComponentPatch only** in the proposals array (schema may list a flow variant for compatibility; omit it).
+
+ComponentPatch (property filling):
+- kind: "component_patch"
+- targetComponentId: string (**must exactly equal one of the componentContext object keys / canonical component IDs**)
+- candidateType: match the user payload agent/candidates (usually "third_party" or "node_property")
+- setSubType: string — **required** when componentContext.subType is empty/null; use one taxonomy token: b2b_customer, saas_service, payment_processor, cloud_provider, api_provider, ai_provider, data_provider, government_regulator, partner, ad_network, professional_services, data_processor, other (snake_case). Omit setSubType only when componentContext already has subType.
+- setDescription?: string when helpful
+- setProperties: object with snake_case keys; **only** keys you can tie to cited evidence (see propertyEvidence)
+- propertyEvidence: **required**. Object whose keys are exactly the keys you put in setProperties; each value is a **non-empty** array of evidence rows: { "filePath", "startLine", "endLine", "reason" }. Every property must cite where in the repo that value comes from; different properties may cite different files or line ranges.
+- confidence: { "score": number 0.72–0.95 when patch is well supported, "band": "high" | "medium" | "low" }
+- evidence: optional legacy field; prefer propertyEvidence only.
+
+Prefer **one ComponentPatch per target component** when you have support — not a large speculative bag of guesses.
+
+**Do not emit FlowPatch proposals.** Connectivity comes from deterministic scan rules.
+
+Rules:
+- Do not contradict propertiesSet unless fixing a clear error with cited proof.
+- \`targetComponentId\` must be a canonical component ID from componentContext keys only. Never emit file paths or folder names as targetComponentId.
+- **Anti-fabrication:** same as above — if the fact is not in the cited lines / excerpt text, omit the property.
+- Do not emit placeholder \`setProperties\` values (null, "none", empty arrays, empty strings), and do not set \`inference_status\`.
+
+setProperties value shapes: use snake_case keys from sparsePropertyKeys. integration_method must be a string array (e.g. ["api"]), never a single string. authentication_method must be one string token (e.g. api_key, oauth_2_0), never an array. processing_purpose must be a string array of taxonomy tokens (authentication, security, analytics, service_provision, payment_processing, marketing, compliance, other, etc.)—snake_case. Other multi-value fields must be string arrays, not comma-joined strings.`;
+/**
+ * Anthropic has no server-side JSON schema for this path; truncated output yields invalid JSON.
+ * Reinforce brevity so the model completes a single well-formed object.
+ */
+exports.ANTHROPIC_ENRICHMENT_SYSTEM_PROMPT_SUPPLEMENT = `Output discipline: Your entire reply must be one parseable JSON object (no markdown). Keep each propertyEvidence "reason" to one short clause. If many properties apply, return fewer patches or fewer keys per patch so the JSON always completes — never stop mid-string or mid-object.`;
+function buildAnthropicEnrichmentSystemPrompt() {
+    return `${exports.AI_PROVIDER_SYSTEM_PROMPT}\n\n${exports.ANTHROPIC_ENRICHMENT_SYSTEM_PROMPT_SUPPLEMENT}`;
+}

package/dist/src/ai-enrichment/provider-prompt.d.ts

@@ -0,0 +1,32 @@
+import type { ServiceSection } from "../core/sectioning/discover-service-sections";
+import type { DetectedComponent } from "../core/types/component";
+import type { DetectedDataFlow } from "../core/types/data-flow";
+import type { FileInfo } from "../core/types/file";
+import type { AiAgentName, AiInferenceCandidate } from "./types";
+/**
+ * Collect repo-relative paths tied to queued candidates (components and flow endpoints).
+ */
+export declare function collectReferencedPathsForQueue(queue: AiInferenceCandidate[], components: DetectedComponent[], dataFlows: DetectedDataFlow[]): string[];
+/**
+ * Map path → file text for paths referenced by the queue, bounded for LLM prompts.
+ */
+export declare function buildFileExcerptsForQueue(files: FileInfo[], queue: AiInferenceCandidate[], components: DetectedComponent[], dataFlows: DetectedDataFlow[]): Record<string, string>;
+export declare function buildFileExcerptsForPaths(files: FileInfo[], preferredPaths: string[]): Record<string, string>;
+/**
+ * Compact component view for LLM prompts: real paths from structural scan,
+ * plus which property keys are still empty so the model can target patches.
+ */
+export declare function slimComponentForLlm(component: DetectedComponent): Record<string, unknown>;
+/**
+ * JSON user message for {@link AiProvider.infer}: candidates plus enough graph
+ * context to produce evidence-backed `proposals`.
+ */
+export declare function buildProviderPromptPayload(input: {
+    agent: AiAgentName;
+    queue: AiInferenceCandidate[];
+    components: DetectedComponent[];
+    dataFlows: DetectedDataFlow[];
+    sections?: ServiceSection[];
+    files?: FileInfo[];
+    preferredPaths?: string[];
+}): Record<string, unknown>;

package/dist/src/ai-enrichment/provider-prompt.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectReferencedPathsForQueue = collectReferencedPathsForQueue;
+exports.buildFileExcerptsForQueue = buildFileExcerptsForQueue;
+exports.buildFileExcerptsForPaths = buildFileExcerptsForPaths;
+exports.slimComponentForLlm = slimComponentForLlm;
+exports.buildProviderPromptPayload = buildProviderPromptPayload;
+const sensitive_paths_1 = require("./sensitive-paths");
+const scan_paths_1 = require("./scan-paths");
+const MAX_DETECTED_FROM = 14;
+const MAX_SOURCE_LOCS = 12;
+/** Cap how many files we embed per provider call (token budget). */
+const MAX_FILES_IN_PROMPT = 28;
+const MAX_CHARS_PER_FILE = 14_000;
+const MAX_TOTAL_EXCERPT_CHARS = 100_000;
+const NON_ENRICHMENT_PROPERTY_KEYS = new Set(["inference_status"]);
+function truncateChars(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max)}\n\n...[truncated]`;
+}
+function pathsFromComponent(comp) {
+    if (!comp)
+        return [];
+    const out = [];
+    for (const ref of comp.detectedFrom ?? []) {
+        const p = ref.sourceLocation?.filePath;
+        if (p)
+            out.push((0, scan_paths_1.normScanPath)(p));
+    }
+    for (const loc of comp.sourceLocations ?? []) {
+        if (loc.filePath)
+            out.push((0, scan_paths_1.normScanPath)(loc.filePath));
+    }
+    return out;
+}
+/**
+ * Collect repo-relative paths tied to queued candidates (components and flow endpoints).
+ */
+function collectReferencedPathsForQueue(queue, components, dataFlows) {
+    const byId = new Map(components.map((c) => [c.id, c]));
+    const ordered = new Set();
+    for (const cand of queue) {
+        if (cand.componentId) {
+            for (const p of pathsFromComponent(byId.get(cand.componentId)))
+                ordered.add(p);
+        }
+        if (cand.flowId) {
+            const flow = dataFlows.find((f) => f.id === cand.flowId);
+            if (flow) {
+                for (const p of pathsFromComponent(byId.get(flow.sourceComponentId)))
+                    ordered.add(p);
+                for (const p of pathsFromComponent(byId.get(flow.targetComponentId)))
+                    ordered.add(p);
+            }
+        }
+    }
+    return [...ordered].sort((a, b) => a.localeCompare(b));
+}
+/**
+ * Map path → file text for paths referenced by the queue, bounded for LLM prompts.
+ */
+function buildFileExcerptsForQueue(files, queue, components, dataFlows) {
+    const paths = collectReferencedPathsForQueue(queue, components, dataFlows);
+    const out = {};
+    let total = 0;
+    for (const p of paths) {
+        if (Object.keys(out).length >= MAX_FILES_IN_PROMPT)
+            break;
+        const fi = (0, scan_paths_1.resolveScannedFileExact)(files, p);
+        if (!fi || (0, sensitive_paths_1.isSensitiveFileForAiPrompt)(fi))
+            continue;
+        const key = (0, scan_paths_1.normScanPath)(fi.path);
+        if (out[key])
+            continue;
+        const excerpt = truncateChars(fi.content, MAX_CHARS_PER_FILE);
+        if (total + excerpt.length > MAX_TOTAL_EXCERPT_CHARS)
+            break;
+        out[key] = excerpt;
+        total += excerpt.length;
+    }
+    return out;
+}
+function buildFileExcerptsForPaths(files, preferredPaths) {
+    const out = {};
+    let total = 0;
+    const ordered = [...new Set(preferredPaths.map((p) => (0, scan_paths_1.normScanPath)(p)))].sort((a, b) => a.localeCompare(b));
+    for (const p of ordered) {
+        if (Object.keys(out).length >= MAX_FILES_IN_PROMPT)
+            break;
+        const fi = (0, scan_paths_1.resolveScannedFileExact)(files, p);
+        if (!fi || (0, sensitive_paths_1.isSensitiveFileForAiPrompt)(fi))
+            continue;
+        const key = (0, scan_paths_1.normScanPath)(fi.path);
+        if (out[key])
+            continue;
+        const excerpt = truncateChars(fi.content, MAX_CHARS_PER_FILE);
+        if (total + excerpt.length > MAX_TOTAL_EXCERPT_CHARS)
+            break;
+        out[key] = excerpt;
+        total += excerpt.length;
+    }
+    return out;
+}
+function isSparseValue(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === "string")
+        return value.trim() === "";
+    if (Array.isArray(value))
+        return value.length === 0;
+    return false;
+}
+/**
+ * Compact component view for LLM prompts: real paths from structural scan,
+ * plus which property keys are still empty so the model can target patches.
+ */
+function slimComponentForLlm(component) {
+    const props = component.properties ?? {};
+    const sparseKeys = [];
+    const propertiesSet = {};
+    for (const [key, value] of Object.entries(props)) {
+        if (NON_ENRICHMENT_PROPERTY_KEYS.has(key))
+            continue;
+        if (isSparseValue(value)) {
+            sparseKeys.push(key);
+        }
+        else {
+            propertiesSet[key] = value;
+        }
+    }
+    sparseKeys.sort((a, b) => a.localeCompare(b));
+    return {
+        id: component.id,
+        name: component.name,
+        type: component.type,
+        subType: component.subType,
+        description: component.description,
+        confidence: component.confidence,
+        propertiesSet,
+        /** Every property key that is still null/empty/[] — LLM should try to fill these. */
+        sparsePropertyKeys: sparseKeys,
+        detectedFrom: (component.detectedFrom ?? []).slice(0, MAX_DETECTED_FROM).map((ref) => ({
+            pattern: ref.pattern,
+            filePath: ref.sourceLocation?.filePath,
+            startLine: ref.sourceLocation?.startLine,
+            endLine: ref.sourceLocation?.endLine,
+        })),
+        sourceLocations: (component.sourceLocations ?? []).slice(0, MAX_SOURCE_LOCS).map((loc) => ({
+            filePath: loc.filePath,
+            startLine: loc.startLine,
+            endLine: loc.endLine,
+        })),
+    };
+}
+/**
+ * JSON user message for {@link AiProvider.infer}: candidates plus enough graph
+ * context to produce evidence-backed `proposals`.
+ */
+function buildProviderPromptPayload(input) {
+    const excerpts = input.files && input.files.length > 0
+        ? input.preferredPaths && input.preferredPaths.length > 0
+            ? buildFileExcerptsForPaths(input.files, input.preferredPaths)
+            : buildFileExcerptsForQueue(input.files, input.queue, input.components, input.dataFlows)
+        : {};
+    const byId = new Map(input.components.map((c) => [c.id, c]));
+    const componentContext = {};
+    for (const cand of input.queue) {
+        if (!cand.componentId)
+            continue;
+        const comp = byId.get(cand.componentId);
+        if (comp && !componentContext[cand.componentId]) {
+            componentContext[cand.componentId] = slimComponentForLlm(comp);
+        }
+    }
+    const flowContext = {};
+    for (const cand of input.queue) {
+        if (!cand.flowId)
+            continue;
+        const flow = input.dataFlows.find((f) => f.id === cand.flowId);
+        if (!flow || flowContext[cand.flowId])
+            continue;
+        const src = byId.get(flow.sourceComponentId);
+        const tgt = byId.get(flow.targetComponentId);
+        flowContext[cand.flowId] = {
+            id: flow.id,
+            type: flow.type,
+            confidence: flow.confidence,
+            sourceComponentId: flow.sourceComponentId,
+            targetComponentId: flow.targetComponentId,
+            sourceName: src?.name,
+            targetName: tgt?.name,
+        };
+    }
+    const sectionSummary = input.sections?.map((s) => ({
+        id: s.id,
+        label: s.label,
+        role: s.role,
+    })) ?? [];
+    const hasExcerpts = Object.keys(excerpts).length > 0;
+    const canonicalComponentIds = Object.keys(componentContext).sort((a, b) => a.localeCompare(b));
+    const propertyShapeHints = " **Property shapes (match DataParade scan/schema):** Use snake_case keys from sparsePropertyKeys. " +
+        "`integration_method` must always be an array of lowercase tokens (e.g. [\"api\"], [\"sdk\",\"api\"]); never a single string. " +
+        "`authentication_method` must be a single string token (e.g. \"api_key\", \"oauth_2_0\", \"openid_connect\", \"jwt\", \"saml\", \"mtls\", \"certificate\", \"basic_auth\", \"none\")—not an array—so it matches product dropdowns. " +
+        "`processing_purpose` must be a string array of **taxonomy** tokens the app lists (e.g. authentication, security, analytics, service_provision, payment_processing, marketing, compliance, other)—snake_case only, not sentences. " +
+        "Other multi-value fields such as `data_categories_received`, `supported_export_formats`, `cloud_services_used`, `regions_availability_zones` must be string arrays, not one comma-joined string. " +
+        "Booleans must be true/false (not strings). Prefer enum-like values in lowercase snake_case (e.g. integration_status: \"active\"). " +
+        "For any field that corresponds to an app dropdown or multi-select, use the product's option tokens (snake_case / exact strings) — e.g. legal_basis: \"contractual_necessity\" not \"contract\"; pci_scope: \"saq_d\" not \"full\"; data_transfer_mechanism: \"standard_contractual_clauses\" not raw \"HTTPS\"; risk_rating and encrypt_at_rest must match allowed values.";
+    const groundedInstructions = "You may output multiple component_patch proposals when they are independently grounded in code/config text. Prefer at most one component_patch per target component, and only for properties you can **ground in code/config text**. Use propertiesSet as truth for fields already set. For every key in setProperties, **propertyEvidence[key]** must be a non-empty array citing filePath + startLine/endLine + reason where that key's value appears in relevantFileContents (when provided) or in the file paths listed on that component in detectedFrom/sourceLocations. If you cannot tie a property to cited text or a cited path, **omit that key**. Indirect guesses are not allowed. It is valid to return **no proposals** or a patch with only one or two setProperties. Never invent URLs, vendor names, analytics products, retention numbers, or compliance labels without a literal basis in the excerpts or cited lines. `targetComponentId` must be exactly one of canonicalComponentIds (componentContext keys). ";
+    return {
+        instructions: hasExcerpts
+            ? `${groundedInstructions} relevantFileContents may be truncated; line ranges must fall within the excerpt for that file. confidence.score should reflect how well the patch is supported (>= 0.72 when merge thresholds apply).`.concat(propertyShapeHints)
+            : `${groundedInstructions} sourceLocations paths and line ranges you rely on; if you cannot cite support, omit the property. confidence.score should reflect how well the patch is supported (>= 0.72 when merge thresholds apply).`.concat(propertyShapeHints),
+        agent: input.agent,
+        candidates: input.queue,
+        componentContext,
+        canonicalComponentIds,
+        ...(Object.keys(flowContext).length > 0 ? { flowContext } : {}),
+        ...(sectionSummary.length > 0 ? { sectionSummary } : {}),
+        ...(hasExcerpts ? { relevantFileContents: excerpts } : {}),
+    };
+}

package/dist/src/ai-enrichment/provider-topology-rules.d.ts

@@ -0,0 +1,52 @@
+export interface ManagedResourceRule {
+    kind: "database" | "cache";
+    viaClients: string[];
+    directClients: string[];
+    matchHints: string[];
+}
+export interface ProviderTopologyRule {
+    providerId: string;
+    providerDisplayName: string;
+    canonicalServiceName: string;
+    providerMatchKeys: string[];
+    allowManagedDatabaseSharedFileInference: boolean;
+    confidence: {
+        managedNodeMinConfidence: number;
+        providerToManagedNodeFlowConfidence: number;
+        providerToManagedResourceFlowConfidence: number;
+        sourceToProviderFlowConfidenceFloor: number;
+        rewiredFlowConfidenceFloor: number;
+        collapseManagedPostgresFlowConfidence: number;
+    };
+    managedResources: ManagedResourceRule[];
+    managedServiceNodes: Array<{
+        key: string;
+        label: string;
+        componentType: "asset" | "third_party";
+        componentSubType: string;
+        flowType: "api_call" | "database_query" | "message_queue" | "file_transfer" | "webhook" | "rpc";
+        usageSignals: string[];
+        alwaysInclude: boolean;
+        evidencePatterns: string[];
+        terraformResourceTypes: string[];
+        terraformResourceTypePrefixes: string[];
+    }>;
+}
+export interface FallbackPolicy {
+    nonConcreteSectionIds: string[];
+    actorTargetReverseConfidenceFloor: number;
+    preferredApiSourceConfidenceFloor: number;
+    crossSectionActorAssetFlowConfidence: number;
+    rewriteThroughProviderFlowTypes: Array<"api_call" | "database_query" | "message_queue" | "file_transfer" | "webhook" | "rpc">;
+    postgresLikeSignals: string[];
+    genericPgNodeNames: string[];
+    genericPgClientSignals: string[];
+    implicitManagedPostgresNodeKeys: string[];
+    managedResourceMatchHintsByKind: {
+        database: string[];
+        cache: string[];
+    };
+}
+export declare function clearProviderTopologyRulesCacheForTest(): void;
+export declare function loadProviderTopologyRules(): ProviderTopologyRule[];
+export declare function loadProviderTopologyFallbackPolicy(): FallbackPolicy;