@dataparade/cli 0.0.1

package/dist/src/ai-enrichment/providers/provider-json-parse.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Providers sometimes wrap JSON in fences or append stray text.
+ * These helpers recover a single top-level `{ ... }` object when possible.
+ */
+export declare function stripJsonFences(text: string): string;
+/**
+ * First complete `{ ... }` from `start`, respecting string escapes and nesting.
+ * Returns null if braces never balance (e.g. truncated response).
+ */
+export declare function extractBalancedJsonObject(s: string, start: number): string | null;
+export declare function jsonParseErrorPosition(err: unknown): number | null;
+/**
+ * Parse model text as JSON: strict parse first, then balanced slice from first `{`.
+ */
+export declare function parseProviderJsonContent(content: string): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: unknown;
+    /** Snippet around JSON.parse error index when available */
+    contextSnippet?: string;
+};

package/dist/src/ai-enrichment/providers/provider-json-parse.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Providers sometimes wrap JSON in fences or append stray text.
+ * These helpers recover a single top-level `{ ... }` object when possible.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripJsonFences = stripJsonFences;
+exports.extractBalancedJsonObject = extractBalancedJsonObject;
+exports.jsonParseErrorPosition = jsonParseErrorPosition;
+exports.parseProviderJsonContent = parseProviderJsonContent;
+function stripJsonFences(text) {
+    const t = text.trim();
+    const fence = /^```(?:json)?\s*([\s\S]*?)```$/im.exec(t);
+    if (fence?.[1])
+        return fence[1].trim();
+    return t;
+}
+/**
+ * First complete `{ ... }` from `start`, respecting string escapes and nesting.
+ * Returns null if braces never balance (e.g. truncated response).
+ */
+function extractBalancedJsonObject(s, start) {
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let i = start; i < s.length; i++) {
+        const c = s[i];
+        if (inString) {
+            if (escape) {
+                escape = false;
+            }
+            else if (c === "\\") {
+                escape = true;
+            }
+            else if (c === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            continue;
+        }
+        if (c === "{") {
+            depth++;
+        }
+        else if (c === "}") {
+            depth--;
+            if (depth === 0) {
+                return s.slice(start, i + 1);
+            }
+        }
+    }
+    return null;
+}
+function firstObjectBraceIndex(s) {
+    return s.indexOf("{");
+}
+function jsonParseErrorPosition(err) {
+    const m = String(err).match(/position (\d+)/);
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 10);
+    return Number.isFinite(n) ? n : null;
+}
+/**
+ * Parse model text as JSON: strict parse first, then balanced slice from first `{`.
+ */
+function parseProviderJsonContent(content) {
+    const cleaned = stripJsonFences(content.trim()).replace(/^\uFEFF/, "");
+    const tryParse = (raw) => {
+        try {
+            return { ok: true, value: JSON.parse(raw) };
+        }
+        catch (err) {
+            return { ok: false, err };
+        }
+    };
+    const first = tryParse(cleaned);
+    if (first.ok)
+        return first;
+    const braceAt = firstObjectBraceIndex(cleaned);
+    if (braceAt >= 0) {
+        const slice = extractBalancedJsonObject(cleaned, braceAt);
+        if (slice != null && slice !== cleaned) {
+            const second = tryParse(slice);
+            if (second.ok)
+                return second;
+        }
+    }
+    const pos = jsonParseErrorPosition(first.err);
+    const contextSnippet = pos != null && cleaned.length > 0
+        ? cleaned.slice(Math.max(0, pos - 120), Math.min(cleaned.length, pos + 120))
+        : undefined;
+    return { ok: false, error: first.err, contextSnippet };
+}

package/dist/src/ai-enrichment/providers/provider-output-token-budget.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Completion (output) token budget for providers that return large JSON blobs
+ * (e.g. many propertyEvidence rows). Too low a ceiling yields truncated JSON.
+ */
+export declare function clampStructuredJsonCompletionTokens(requested: number | undefined): number;

package/dist/src/ai-enrichment/providers/provider-output-token-budget.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clampStructuredJsonCompletionTokens = clampStructuredJsonCompletionTokens;
+/**
+ * Completion (output) token budget for providers that return large JSON blobs
+ * (e.g. many propertyEvidence rows). Too low a ceiling yields truncated JSON.
+ */
+function clampStructuredJsonCompletionTokens(requested) {
+    const r = requested ?? 8192;
+    return Math.min(16_384, Math.max(4096, Math.floor(r)));
+}

package/dist/src/ai-enrichment/providers/provider-pricing.d.ts

@@ -0,0 +1,7 @@
+import type { AiProviderId } from "../types";
+export declare function estimateTokenCostUsd(input: {
+    provider: AiProviderId;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+}): number | undefined;

package/dist/src/ai-enrichment/providers/provider-pricing.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateTokenCostUsd = estimateTokenCostUsd;
+// Best-effort public list; keep intentionally narrow and explicit.
+const MODEL_PRICING_USD_PER_MILLION = {
+    "gpt-4o-mini": { inputPerMillionUsd: 0.15, outputPerMillionUsd: 0.6 },
+    "openai/gpt-4o-mini": { inputPerMillionUsd: 0.15, outputPerMillionUsd: 0.6 },
+    "claude-sonnet-4-5": { inputPerMillionUsd: 3.0, outputPerMillionUsd: 15.0 },
+    "gemini-1.5-flash": { inputPerMillionUsd: 0.075, outputPerMillionUsd: 0.3 },
+};
+function resolvePricing(model) {
+    const normalized = model.trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    if (MODEL_PRICING_USD_PER_MILLION[normalized]) {
+        return MODEL_PRICING_USD_PER_MILLION[normalized];
+    }
+    // Match dated suffixes (for example: claude-sonnet-4-5-20250929).
+    const entry = Object.entries(MODEL_PRICING_USD_PER_MILLION).find(([key]) => normalized.startsWith(`${key}-`));
+    return entry?.[1];
+}
+function estimateTokenCostUsd(input) {
+    // Local and mock providers are not billable from this CLI's perspective.
+    if (input.provider === "local" || input.provider === "mock")
+        return 0;
+    const pricing = resolvePricing(input.model);
+    if (!pricing)
+        return undefined;
+    const inCost = (Math.max(0, input.inputTokens) / 1_000_000) * pricing.inputPerMillionUsd;
+    const outCost = (Math.max(0, input.outputTokens) / 1_000_000) * pricing.outputPerMillionUsd;
+    return inCost + outCost;
+}

package/dist/src/ai-enrichment/providers/provider-runtime.d.ts

@@ -0,0 +1,9 @@
+export declare function readJsonOrWarn(response: Response, providerLabel: string): Promise<unknown | null>;
+export declare function parseJsonTextOrWarn(text: string, options: {
+    providerLabel: string;
+    finishReason?: string | null;
+}): unknown | null;
+export declare function joinAnthropicTextBlocks(content: Array<{
+    type?: string;
+    text?: string;
+}> | undefined): string;

package/dist/src/ai-enrichment/providers/provider-runtime.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readJsonOrWarn = readJsonOrWarn;
+exports.parseJsonTextOrWarn = parseJsonTextOrWarn;
+exports.joinAnthropicTextBlocks = joinAnthropicTextBlocks;
+const provider_json_parse_1 = require("./provider-json-parse");
+const provider_contract_1 = require("./provider-contract");
+const SECRET_BODY_RE = /(?:api[_-]?key|authorization|bearer|x-api-key|key=)[^\s]{8,}/gi;
+function redactSecretSubstrings(text) {
+    return text.replace(SECRET_BODY_RE, (match) => {
+        const eq = match.indexOf("=");
+        if (eq >= 0) {
+            return `${match.slice(0, eq + 1)}<redacted>`;
+        }
+        const space = match.indexOf(" ");
+        if (space >= 0) {
+            return `${match.slice(0, space + 1)}<redacted>`;
+        }
+        return "<redacted>";
+    });
+}
+async function readJsonOrWarn(response, providerLabel) {
+    if (!response.ok) {
+        const errBody = await response.text().catch(() => "");
+        if ((0, provider_contract_1.aiDebugEnabled)()) {
+            const safe = redactSecretSubstrings(errBody).slice(0, 1200);
+            console.warn(`[dataparade-ai] ${providerLabel} HTTP ${response.status}: ${safe}`);
+        }
+        return null;
+    }
+    return response.json();
+}
+function parseJsonTextOrWarn(text, options) {
+    const parsed = (0, provider_json_parse_1.parseProviderJsonContent)(text);
+    if (!parsed.ok) {
+        if ((0, provider_contract_1.aiDebugEnabled)()) {
+            console.warn(`[dataparade-ai] ${options.providerLabel} failed to parse model JSON:`, parsed.error);
+            if (parsed.contextSnippet != null) {
+                console.warn(`[dataparade-ai] JSON context (near error): ...${parsed.contextSnippet}...`);
+            }
+            if (options.finishReason != null) {
+                console.warn(`[dataparade-ai] finish_reason=${options.finishReason}`);
+            }
+        }
+        return null;
+    }
+    return parsed.value;
+}
+function joinAnthropicTextBlocks(content) {
+    return (content ?? [])
+        .filter((block) => block?.type === "text" && typeof block.text === "string")
+        .map((block) => String(block.text))
+        .join("\n");
+}

package/dist/src/ai-enrichment/providers/resolve-provider.d.ts

@@ -0,0 +1,27 @@
+import type { AiProviderId } from "../types";
+import { type AiApiFamily, type AiProviderAuthStyle, type AiStructuredOutputMode } from "./presets";
+export interface ResolvedProviderConfig {
+    presetId: AiProviderId;
+    family: AiApiFamily;
+    endpoint: string;
+    model: string;
+    apiKey?: string;
+    auth: AiProviderAuthStyle;
+    structuredOutput?: AiStructuredOutputMode;
+}
+export interface ResolveProviderOverrides {
+    endpoint?: string;
+    model?: string;
+    apiKey?: string;
+}
+/** Request wins; otherwise use the key from {@link resolveProviderConfig} / `createAiProvider`. */
+export declare function resolveInferApiKey(request: {
+    apiKey?: string;
+}, resolved: {
+    apiKey?: string;
+}): string | undefined;
+/**
+ * Maps a user-facing provider preset (e.g. `openai`) to an API family + resolved endpoint/model.
+ * Unknown preset ids fall back to `mock` (same as createAiProvider default).
+ */
+export declare function resolveProviderConfig(presetId: string | undefined, overrides?: ResolveProviderOverrides): ResolvedProviderConfig;

package/dist/src/ai-enrichment/providers/resolve-provider.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveInferApiKey = resolveInferApiKey;
+exports.resolveProviderConfig = resolveProviderConfig;
+const endpoint_resolution_1 = require("./endpoint-resolution");
+const presets_1 = require("./presets");
+/** Request wins; otherwise use the key from {@link resolveProviderConfig} / `createAiProvider`. */
+function resolveInferApiKey(request, resolved) {
+    const key = request.apiKey?.trim() || resolved.apiKey?.trim();
+    return key || undefined;
+}
+const KNOWN_PRESETS = new Set(Object.keys(presets_1.AI_PROVIDER_PRESETS));
+function normalizePresetId(presetId) {
+    if (presetId && KNOWN_PRESETS.has(presetId)) {
+        return presetId;
+    }
+    return "mock";
+}
+/**
+ * Maps a user-facing provider preset (e.g. `openai`) to an API family + resolved endpoint/model.
+ * Unknown preset ids fall back to `mock` (same as createAiProvider default).
+ */
+function resolveProviderConfig(presetId, overrides = {}) {
+    const id = normalizePresetId(presetId);
+    const preset = presets_1.AI_PROVIDER_PRESETS[id];
+    const rawEndpoint = overrides.endpoint?.trim() || preset.defaultEndpoint;
+    const endpoint = preset.family === "chat-completions"
+        ? (0, endpoint_resolution_1.resolveChatCompletionsEndpoint)(rawEndpoint, preset.defaultEndpoint)
+        : rawEndpoint;
+    const model = overrides.model?.trim() || preset.defaultModel;
+    const apiKey = overrides.apiKey?.trim() || undefined;
+    return {
+        presetId: id,
+        family: preset.family,
+        endpoint,
+        model,
+        apiKey,
+        auth: preset.auth,
+        structuredOutput: preset.structuredOutput,
+    };
+}

package/dist/src/ai-enrichment/providers/types.d.ts

@@ -0,0 +1,24 @@
+import type { AiProposal, AiProviderId } from "../types";
+export interface AiProviderRequest {
+    prompt: string;
+    model: string;
+    apiKey?: string;
+    endpoint?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+export interface AiProviderUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    /** Best-effort estimate; only present when pricing info is known. */
+    estimatedCostUsd?: number;
+}
+export interface AiProviderResult {
+    proposals: AiProposal[];
+    usage?: AiProviderUsage;
+}
+export interface AiProvider {
+    id: AiProviderId;
+    infer(request: AiProviderRequest): Promise<AiProviderResult>;
+}

package/dist/src/ai-enrichment/providers/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/ai-enrichment/scan-paths.d.ts

@@ -0,0 +1,9 @@
+import type { FileInfo } from "../core/types/file";
+export declare function normScanPath(p: string): string;
+/** Exact repo-relative path match only (preferred for AI prompt excerpts). */
+export declare function resolveScannedFileExact(files: FileInfo[], pathKey: string): FileInfo | undefined;
+/**
+ * Legacy fuzzy match (suffix/prefix). Do not use for security-sensitive or evidence paths.
+ * Prefer {@link resolveScannedFileExact}.
+ */
+export declare function resolveScannedFile(files: FileInfo[], pathKey: string): FileInfo | undefined;

package/dist/src/ai-enrichment/scan-paths.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normScanPath = normScanPath;
+exports.resolveScannedFileExact = resolveScannedFileExact;
+exports.resolveScannedFile = resolveScannedFile;
+function normScanPath(p) {
+    return p.split("\\").join("/");
+}
+/** Exact repo-relative path match only (preferred for AI prompt excerpts). */
+function resolveScannedFileExact(files, pathKey) {
+    const n = normScanPath(pathKey.trim());
+    if (!n)
+        return undefined;
+    return files.find((f) => normScanPath(f.path) === n);
+}
+/**
+ * Legacy fuzzy match (suffix/prefix). Do not use for security-sensitive or evidence paths.
+ * Prefer {@link resolveScannedFileExact}.
+ */
+function resolveScannedFile(files, pathKey) {
+    const exact = resolveScannedFileExact(files, pathKey);
+    if (exact)
+        return exact;
+    const n = normScanPath(pathKey.trim());
+    if (!n)
+        return undefined;
+    return files.find((f) => n.endsWith(normScanPath(f.path)) || normScanPath(f.path).endsWith(n));
+}

package/dist/src/ai-enrichment/sensitive-paths.d.ts

@@ -0,0 +1,5 @@
+import type { FileInfo } from "../core/types/file";
+import { isSensitiveEnvPath } from "../ingest/sensitive-paths";
+export { isSensitiveEnvPath };
+/** True when file content must not be embedded in provider prompts. */
+export declare function isSensitiveFileForAiPrompt(file: FileInfo): boolean;

package/dist/src/ai-enrichment/sensitive-paths.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSensitiveEnvPath = void 0;
+exports.isSensitiveFileForAiPrompt = isSensitiveFileForAiPrompt;
+const sensitive_paths_1 = require("../ingest/sensitive-paths");
+Object.defineProperty(exports, "isSensitiveEnvPath", { enumerable: true, get: function () { return sensitive_paths_1.isSensitiveEnvPath; } });
+/** True when file content must not be embedded in provider prompts. */
+function isSensitiveFileForAiPrompt(file) {
+    return file.language === "env" || (0, sensitive_paths_1.isSensitiveEnvPath)(file.path);
+}

package/dist/src/ai-enrichment/third-party-data-flow.d.ts

@@ -0,0 +1,27 @@
+import type { AiCandidateAgentTrace, AiProposal } from "./types";
+import type { DetectedComponent } from "../core/types/component";
+import type { FileInfo } from "../core/types/file";
+import type { ThirdPartyDataFlowSummary } from "../core/types/result";
+interface BuildThirdPartyDataFlowSummaryInput {
+    proposals: Array<{
+        id: string;
+        proposal: AiProposal;
+    }>;
+    appliedProposalIds: string[];
+    /** Final third-party components (post-fallback, post-stable-id assignment). */
+    componentsAfterAi: DetectedComponent[];
+    files: FileInfo[];
+    agenticTrace?: AiCandidateAgentTrace[];
+    /** Maps post-AI-merge component ids to final graph ids (via stableComponentKey). */
+    proposalTargetComponentIdRemap?: Map<string, string>;
+}
+/**
+ * Bridge AI proposal/trace target ids (post-merge) to final diagram component ids.
+ */
+export declare function buildProposalTargetComponentIdRemap(postAiComponents: DetectedComponent[], finalComponents: DetectedComponent[]): Map<string, string>;
+/**
+ * Files referenced by two or more distinct AI third-party providers (shared route/handler).
+ */
+export declare function buildSharedHandlerAiFileIndex(thirdParties: DetectedComponent[], files: FileInfo[]): Set<string>;
+export declare function buildThirdPartyDataFlowSummary(input: BuildThirdPartyDataFlowSummaryInput): ThirdPartyDataFlowSummary;
+export {};