@dataparade/cli 0.0.1

package/dist/src/ai-enrichment/provider-topology-rules.js

@@ -0,0 +1,190 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearProviderTopologyRulesCacheForTest = clearProviderTopologyRulesCacheForTest;
+exports.loadProviderTopologyRules = loadProviderTopologyRules;
+exports.loadProviderTopologyFallbackPolicy = loadProviderTopologyFallbackPolicy;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const yaml_1 = __importDefault(require("yaml"));
+const zod_1 = require("zod");
+const managedResourceSchema = zod_1.z.object({
+    kind: zod_1.z.enum(["database", "cache"]),
+    viaClients: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+    directClients: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+    matchHints: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+});
+const managedServiceNodeSchema = zod_1.z.object({
+    key: zod_1.z.string().min(1),
+    label: zod_1.z.string().min(1),
+    componentType: zod_1.z.enum(["asset", "third_party"]).default("asset"),
+    componentSubType: zod_1.z.string().min(1),
+    flowType: zod_1.z
+        .enum(["api_call", "database_query", "message_queue", "file_transfer", "webhook", "rpc"])
+        .default("api_call"),
+    usageSignals: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+    alwaysInclude: zod_1.z.boolean().default(false),
+    evidencePatterns: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+    /** HashiCorp AWS provider-style `resource` type names (lowercase), e.g. `aws_lambda_function`. */
+    terraformResourceTypes: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+    /** Prefixes on `resource_type`, e.g. `aws_s3_` matches `aws_s3_bucket`, `aws_s3_bucket_acl`. */
+    terraformResourceTypePrefixes: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+});
+const providerConfidenceSchema = zod_1.z.object({
+    managedNodeMinConfidence: zod_1.z.number().min(0).max(1).default(0.78),
+    providerToManagedNodeFlowConfidence: zod_1.z.number().min(0).max(1).default(0.78),
+    providerToManagedResourceFlowConfidence: zod_1.z.number().min(0).max(1).default(0.75),
+    sourceToProviderFlowConfidenceFloor: zod_1.z.number().min(0).max(1).default(0.72),
+    rewiredFlowConfidenceFloor: zod_1.z.number().min(0).max(1).default(0.75),
+    collapseManagedPostgresFlowConfidence: zod_1.z.number().min(0).max(1).default(0.78),
+});
+const managedResourceMatchHintsByKindSchema = zod_1.z.object({
+    database: zod_1.z.array(zod_1.z.string().min(1)).default(["postgres", "pg", "mysql", "mongo", "sql"]),
+    cache: zod_1.z.array(zod_1.z.string().min(1)).default(["redis", "cache", "kv"]),
+});
+const fallbackPolicySchema = zod_1.z.object({
+    nonConcreteSectionIds: zod_1.z.array(zod_1.z.string().min(1)).default(["root", "<unsectioned>", "global"]),
+    actorTargetReverseConfidenceFloor: zod_1.z.number().min(0).max(1).default(0.8),
+    preferredApiSourceConfidenceFloor: zod_1.z.number().min(0).max(1).default(0.75),
+    crossSectionActorAssetFlowConfidence: zod_1.z.number().min(0).max(1).default(0.7),
+    rewriteThroughProviderFlowTypes: zod_1.z
+        .array(zod_1.z.enum(["api_call", "database_query", "message_queue", "file_transfer", "webhook", "rpc"]))
+        .default(["database_query", "api_call"]),
+    postgresLikeSignals: zod_1.z.array(zod_1.z.string().min(1)).default(["postgres", "pg", "postgresql"]),
+    genericPgNodeNames: zod_1.z.array(zod_1.z.string().min(1)).default(["pg", "postgres", "postgresql"]),
+    genericPgClientSignals: zod_1.z
+        .array(zod_1.z.string().min(1))
+        .default(["pg", "postgres", "postgresql", "node-postgres", "psycopg", "psycopg2"]),
+    implicitManagedPostgresNodeKeys: zod_1.z.array(zod_1.z.string().min(1)).default(["postgres"]),
+    managedResourceMatchHintsByKind: managedResourceMatchHintsByKindSchema.optional(),
+});
+const defaultProviderConfidence = {
+    managedNodeMinConfidence: 0.78,
+    providerToManagedNodeFlowConfidence: 0.78,
+    providerToManagedResourceFlowConfidence: 0.75,
+    sourceToProviderFlowConfidenceFloor: 0.72,
+    rewiredFlowConfidenceFloor: 0.75,
+    collapseManagedPostgresFlowConfidence: 0.78,
+};
+const providerTopologyRuleSchema = zod_1.z.object({
+    providerId: zod_1.z.string().min(1),
+    providerDisplayName: zod_1.z.string().min(1).optional(),
+    canonicalServiceName: zod_1.z.string().min(1).optional(),
+    providerMatchKeys: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+    allowManagedDatabaseSharedFileInference: zod_1.z.boolean().default(false),
+    confidence: providerConfidenceSchema.optional(),
+    managedResources: zod_1.z.array(managedResourceSchema).default([]),
+    managedServiceNodes: zod_1.z.array(managedServiceNodeSchema).default([]),
+});
+const providerTopologyCatalogSchema = zod_1.z.object({
+    provider_topology_rules: zod_1.z.array(providerTopologyRuleSchema).default([]),
+    fallback_policy: fallbackPolicySchema.optional(),
+});
+let cachedRules;
+let cachedFallbackPolicy;
+function clearProviderTopologyRulesCacheForTest() {
+    cachedRules = undefined;
+    cachedFallbackPolicy = undefined;
+}
+function getProviderTopologyRulesPath() {
+    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", "provider-topology.rules.yaml");
+}
+function loadProviderTopologyRules() {
+    if (cachedRules)
+        return cachedRules;
+    const configPath = getProviderTopologyRulesPath();
+    let raw;
+    try {
+        raw = fs_1.default.readFileSync(configPath, "utf8");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Provider topology 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(`Provider topology rules at '${configPath}' could not be parsed as YAML: ${message}`);
+    }
+    let normalized;
+    try {
+        normalized = providerTopologyCatalogSchema.parse(parsed);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Provider topology rules at '${configPath}' failed schema validation: ${message}`);
+    }
+    cachedRules = normalized.provider_topology_rules.map((rule) => ({
+        providerId: rule.providerId.trim().toLowerCase(),
+        providerDisplayName: (rule.providerDisplayName ?? rule.providerId).trim(),
+        canonicalServiceName: (rule.canonicalServiceName ?? rule.providerId)
+            .trim()
+            .toLowerCase(),
+        providerMatchKeys: rule.providerMatchKeys.map((k) => k.trim().toLowerCase()),
+        allowManagedDatabaseSharedFileInference: rule.allowManagedDatabaseSharedFileInference,
+        confidence: { ...defaultProviderConfidence, ...(rule.confidence ?? {}) },
+        managedResources: rule.managedResources.map((resource) => ({
+            kind: resource.kind,
+            viaClients: resource.viaClients.map((k) => k.trim().toLowerCase()),
+            directClients: resource.directClients.map((k) => k.trim().toLowerCase()),
+            matchHints: resource.matchHints.map((k) => k.trim().toLowerCase()),
+        })),
+        managedServiceNodes: rule.managedServiceNodes.map((node) => ({
+            key: node.key.trim().toLowerCase(),
+            label: node.label.trim(),
+            componentType: node.componentType,
+            componentSubType: node.componentSubType.trim().toLowerCase(),
+            flowType: node.flowType,
+            usageSignals: node.usageSignals.map((k) => k.trim().toLowerCase()),
+            alwaysInclude: node.alwaysInclude,
+            evidencePatterns: node.evidencePatterns.map((k) => k.trim().toLowerCase()),
+            terraformResourceTypes: node.terraformResourceTypes.map((t) => t.trim().toLowerCase()),
+            terraformResourceTypePrefixes: node.terraformResourceTypePrefixes.map((p) => p.trim().toLowerCase()),
+        })),
+    }));
+    const rawPolicy = normalized.fallback_policy ?? fallbackPolicySchema.parse({});
+    const managedResourceMatchHintsByKind = rawPolicy.managedResourceMatchHintsByKind ?? managedResourceMatchHintsByKindSchema.parse({});
+    cachedFallbackPolicy = {
+        nonConcreteSectionIds: rawPolicy.nonConcreteSectionIds.map((value) => value.trim().toLowerCase()),
+        actorTargetReverseConfidenceFloor: rawPolicy.actorTargetReverseConfidenceFloor,
+        preferredApiSourceConfidenceFloor: rawPolicy.preferredApiSourceConfidenceFloor,
+        crossSectionActorAssetFlowConfidence: rawPolicy.crossSectionActorAssetFlowConfidence,
+        rewriteThroughProviderFlowTypes: rawPolicy.rewriteThroughProviderFlowTypes,
+        postgresLikeSignals: rawPolicy.postgresLikeSignals.map((value) => value.trim().toLowerCase()),
+        genericPgNodeNames: rawPolicy.genericPgNodeNames.map((value) => value.trim().toLowerCase()),
+        genericPgClientSignals: rawPolicy.genericPgClientSignals.map((value) => value.trim().toLowerCase()),
+        implicitManagedPostgresNodeKeys: rawPolicy.implicitManagedPostgresNodeKeys.map((value) => value.trim().toLowerCase()),
+        managedResourceMatchHintsByKind: {
+            database: managedResourceMatchHintsByKind.database.map((value) => value.trim().toLowerCase()),
+            cache: managedResourceMatchHintsByKind.cache.map((value) => value.trim().toLowerCase()),
+        },
+    };
+    return cachedRules;
+}
+function loadProviderTopologyFallbackPolicy() {
+    if (!cachedFallbackPolicy) {
+        loadProviderTopologyRules();
+    }
+    if (cachedFallbackPolicy)
+        return cachedFallbackPolicy;
+    const fallback = fallbackPolicySchema.parse({});
+    const managedResourceMatchHintsByKind = fallback.managedResourceMatchHintsByKind ?? managedResourceMatchHintsByKindSchema.parse({});
+    return {
+        ...fallback,
+        implicitManagedPostgresNodeKeys: fallback.implicitManagedPostgresNodeKeys.map((value) => value.trim().toLowerCase()),
+        managedResourceMatchHintsByKind: {
+            database: managedResourceMatchHintsByKind.database.map((value) => value.trim().toLowerCase()),
+            cache: managedResourceMatchHintsByKind.cache.map((value) => value.trim().toLowerCase()),
+        },
+    };
+}

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

@@ -0,0 +1,48 @@
+import type { DetectedComponent } from "../core/types/component";
+import type { DetectedDataFlow } from "../core/types/data-flow";
+import type { ManagedResourceRule } from "./provider-topology-rules";
+export declare function getStringValues(value: unknown): string[];
+export declare function componentMatchesProvider(component: DetectedComponent, keys: string[]): boolean;
+export declare function isManagedResourceComponent(component: DetectedComponent, managedResource: ManagedResourceRule): boolean;
+export declare function hasAnyClientMatch(component: DetectedComponent, keys: string[]): boolean;
+export declare function hasDirectClientMatch(component: DetectedComponent, directKeys: string[], viaKeys: string[]): boolean;
+export declare function normalizeSectionId(raw: unknown): string;
+export declare function areSectionCompatible(source: DetectedComponent, provider: DetectedComponent, target: DetectedComponent): boolean;
+export declare function areComponentsSectionCompatible(left: DetectedComponent, right: DetectedComponent): boolean;
+export declare function providerUsageCorpus(provider: DetectedComponent, flows: DetectedDataFlow[]): string[];
+export declare function providerEvidenceForManagedNode(provider: DetectedComponent, managedServiceKey: string): Pick<DetectedComponent, "detectedFrom" | "sourceLocations">;
+export declare function isProviderManagedDatabaseTarget(target: DetectedComponent, provider: DetectedComponent, providerId: string): boolean;
+/**
+ * Terraform analogue of {@link providerUsageCorpus}: strings derived from
+ * `resource_type`, `block_name`, and addresses (legacy / diagnostics; AWS
+ * topology uses `terraformResourceTypePrefixes` in YAML instead).
+ */
+export declare function providerUsageCorpusFromTerraformAssets(provider: DetectedComponent, components: DetectedComponent[]): string[];
+export declare function terraformAssetBelongsToProviderRule(component: DetectedComponent, providerId: string): boolean;
+/** Subset of managed-service node fields used for Terraform `resource_type` matching. */
+export interface ManagedServiceTerraformTopologyRule {
+    key: string;
+    usageSignals: string[];
+    terraformResourceTypes: string[];
+    terraformResourceTypePrefixes: string[];
+}
+/**
+ * Match Terraform `resource_type` against HashiCorp-provider-style names
+ * (e.g. `aws_s3_bucket`, prefix `aws_s3_`).
+ */
+export declare function terraformResourceTypeMatchesTopologyRule(resourceType: string, exactTypes: string[], prefixes: string[]): boolean;
+/**
+ * When `terraformResourceTypes` / `terraformResourceTypePrefixes` are set on the
+ * rule (see `provider-topology.rules.yaml`), Terraform matching uses **only**
+ * `resource_type` — not block labels like `lambda_bucket`. Otherwise falls back
+ * to `usageSignals` + {@link terraformManagedNodeConsistentWithResourceType}.
+ */
+export declare function terraformAssetMatchesManagedServiceTopologyRule(component: DetectedComponent, managedNode: ManagedServiceTerraformTopologyRule): boolean;
+export declare function terraformSectionMatchesManagedServiceTopologyRule(provider: DetectedComponent, providerId: string, components: DetectedComponent[], managedNode: ManagedServiceTerraformTopologyRule): boolean;
+export declare function terraformAssetMatchesManagedServiceSignals(component: DetectedComponent, usageSignals: string[]): boolean;
+/**
+ * Disambiguates Terraform resources when block names include words like "lambda"
+ * but the resource is IAM, etc. Used only for **legacy** matching when YAML does
+ * not define `terraformResourceTypePrefixes` / `terraformResourceTypes`.
+ */
+export declare function terraformManagedNodeConsistentWithResourceType(component: DetectedComponent, managedServiceKey: string): boolean;

package/dist/src/ai-enrichment/provider-topology-shared.js

@@ -0,0 +1,329 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getStringValues = getStringValues;
+exports.componentMatchesProvider = componentMatchesProvider;
+exports.isManagedResourceComponent = isManagedResourceComponent;
+exports.hasAnyClientMatch = hasAnyClientMatch;
+exports.hasDirectClientMatch = hasDirectClientMatch;
+exports.normalizeSectionId = normalizeSectionId;
+exports.areSectionCompatible = areSectionCompatible;
+exports.areComponentsSectionCompatible = areComponentsSectionCompatible;
+exports.providerUsageCorpus = providerUsageCorpus;
+exports.providerEvidenceForManagedNode = providerEvidenceForManagedNode;
+exports.isProviderManagedDatabaseTarget = isProviderManagedDatabaseTarget;
+exports.providerUsageCorpusFromTerraformAssets = providerUsageCorpusFromTerraformAssets;
+exports.terraformAssetBelongsToProviderRule = terraformAssetBelongsToProviderRule;
+exports.terraformResourceTypeMatchesTopologyRule = terraformResourceTypeMatchesTopologyRule;
+exports.terraformAssetMatchesManagedServiceTopologyRule = terraformAssetMatchesManagedServiceTopologyRule;
+exports.terraformSectionMatchesManagedServiceTopologyRule = terraformSectionMatchesManagedServiceTopologyRule;
+exports.terraformAssetMatchesManagedServiceSignals = terraformAssetMatchesManagedServiceSignals;
+exports.terraformManagedNodeConsistentWithResourceType = terraformManagedNodeConsistentWithResourceType;
+function getStringValues(value) {
+    if (typeof value === "string")
+        return [value.toLowerCase()];
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((v) => typeof v === "string")
+        .map((v) => v.toLowerCase());
+}
+function componentMatchesProvider(component, keys) {
+    const serviceNameValues = getStringValues(component.properties?.serviceName);
+    const name = (component.name || "").trim().toLowerCase();
+    const corpus = new Set([name, ...serviceNameValues]);
+    const providerKey = component.properties?.provider_name;
+    if (typeof providerKey === "string" && providerKey.trim()) {
+        corpus.add(providerKey.trim().toLowerCase());
+    }
+    return keys.some((k) => corpus.has(k) || name.includes(k));
+}
+function isManagedResourceComponent(component, managedResource) {
+    if (!(component.type === "asset" && component.subType === "database"))
+        return false;
+    const clients = getStringValues(component.properties?.client);
+    const dbTypeValues = getStringValues(component.properties?.databaseType);
+    const name = (component.name || "").toLowerCase();
+    const corpus = [...clients, ...dbTypeValues, name];
+    if (managedResource.kind === "database") {
+        return corpus.some((v) => v.includes("postgres") ||
+            v.includes("pg") ||
+            v.includes("mysql") ||
+            v.includes("mongo") ||
+            v.includes("sql"));
+    }
+    if (managedResource.kind === "cache") {
+        return corpus.some((v) => v.includes("redis") ||
+            v.includes("cache") ||
+            v.includes("kv"));
+    }
+    return false;
+}
+function hasAnyClientMatch(component, keys) {
+    if (keys.length === 0)
+        return false;
+    const clients = getStringValues(component.properties?.client);
+    return clients.some((client) => keys.some((k) => client.includes(k)));
+}
+function hasDirectClientMatch(component, directKeys, viaKeys) {
+    if (directKeys.length === 0)
+        return false;
+    const clients = getStringValues(component.properties?.client);
+    return clients.some((client) => {
+        const matchesDirect = directKeys.some((k) => client.includes(k));
+        if (!matchesDirect)
+            return false;
+        const matchesVia = viaKeys.some((k) => client.includes(k));
+        return !matchesVia;
+    });
+}
+function normalizeSectionId(raw) {
+    const value = String(raw ?? "").trim().toLowerCase();
+    if (!value || value === "root" || value === "<unsectioned>" || value === "global") {
+        return "";
+    }
+    return value;
+}
+function areSectionCompatible(source, provider, target) {
+    const sourceSection = normalizeSectionId(source.properties?.section_id);
+    const providerSection = normalizeSectionId(provider.properties?.section_id);
+    const targetSection = normalizeSectionId(target.properties?.section_id);
+    if (providerSection && targetSection && providerSection !== targetSection) {
+        return false;
+    }
+    if (sourceSection && providerSection && sourceSection !== providerSection) {
+        return false;
+    }
+    return true;
+}
+function areComponentsSectionCompatible(left, right) {
+    const leftSection = normalizeSectionId(left.properties?.section_id);
+    const rightSection = normalizeSectionId(right.properties?.section_id);
+    if (leftSection && rightSection && leftSection !== rightSection) {
+        return false;
+    }
+    return true;
+}
+function providerUsageCorpus(provider, flows) {
+    const corpus = [];
+    for (const loc of provider.sourceLocations ?? []) {
+        if (loc.filePath)
+            corpus.push(loc.filePath.toLowerCase());
+    }
+    for (const ref of provider.detectedFrom ?? []) {
+        if (ref.pattern)
+            corpus.push(String(ref.pattern).toLowerCase());
+        const fp = ref.sourceLocation?.filePath;
+        if (fp)
+            corpus.push(fp.toLowerCase());
+    }
+    for (const flow of flows) {
+        if (flow.targetComponentId !== provider.id && flow.sourceComponentId !== provider.id) {
+            continue;
+        }
+        if (flow.description)
+            corpus.push(flow.description.toLowerCase());
+        for (const loc of flow.sourceLocations ?? []) {
+            if (loc.filePath)
+                corpus.push(loc.filePath.toLowerCase());
+        }
+    }
+    return corpus;
+}
+function dedupeTopologyEvidenceSourceLocations(locations) {
+    const seen = new Set();
+    const result = [];
+    for (const loc of locations) {
+        const key = `${loc.filePath}:${loc.startLine}:${loc.endLine}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(loc);
+    }
+    return result;
+}
+function providerEvidenceForManagedNode(provider, managedServiceKey) {
+    const detectedFrom = provider.detectedFrom ?? [];
+    const sourceLocations = provider.sourceLocations ?? [];
+    const normalizedKey = managedServiceKey.trim().toLowerCase();
+    const evidencePatterns = normalizedKey === "postgres"
+        ? new Set(["database_connection"])
+        : normalizedKey === "auth"
+            ? new Set(["auth_middleware"])
+            : normalizedKey === "storage"
+                ? new Set()
+                : new Set();
+    if (evidencePatterns.size === 0) {
+        return {
+            detectedFrom: [...detectedFrom],
+            sourceLocations: [...sourceLocations],
+        };
+    }
+    const filteredDetectedFrom = detectedFrom.filter((ref) => evidencePatterns.has(String(ref.pattern ?? "").toLowerCase()));
+    const filteredSourceLocations = dedupeTopologyEvidenceSourceLocations(filteredDetectedFrom
+        .map((ref) => ref.sourceLocation)
+        .filter((loc) => Boolean(loc)));
+    return {
+        detectedFrom: filteredDetectedFrom.length > 0 ? filteredDetectedFrom : [...detectedFrom],
+        sourceLocations: filteredSourceLocations.length > 0
+            ? filteredSourceLocations
+            : [...sourceLocations],
+    };
+}
+function isProviderManagedDatabaseTarget(target, provider, providerId) {
+    const cloudProvider = String(target.properties?.cloud_provider ?? "").toLowerCase();
+    const targetService = String(target.properties?.serviceName ?? "").toLowerCase();
+    const targetVendor = String(target.properties?.vendor ?? "").toLowerCase();
+    const providerKey = providerId.toLowerCase();
+    const hints = [cloudProvider, targetService, targetVendor];
+    if (hints.some((h) => h.includes(providerKey)))
+        return true;
+    const targetClients = getStringValues(target.properties?.client);
+    const targetName = String(target.name ?? "").toLowerCase();
+    const allowsSharedFileProviderInference = [...targetClients, targetName].some((value) => value.includes("pg") ||
+        value.includes("postgres") ||
+        value.includes("postgresql"));
+    if (!allowsSharedFileProviderInference) {
+        return false;
+    }
+    const targetFiles = new Set((target.sourceLocations ?? [])
+        .map((loc) => loc.filePath)
+        .filter((p) => typeof p === "string"));
+    const providerFiles = new Set((provider.sourceLocations ?? [])
+        .map((loc) => loc.filePath)
+        .filter((p) => typeof p === "string"));
+    for (const file of targetFiles) {
+        if (providerFiles.has(file))
+            return true;
+    }
+    return false;
+}
+/**
+ * Terraform analogue of {@link providerUsageCorpus}: strings derived from
+ * `resource_type`, `block_name`, and addresses (legacy / diagnostics; AWS
+ * topology uses `terraformResourceTypePrefixes` in YAML instead).
+ */
+function providerUsageCorpusFromTerraformAssets(provider, components) {
+    const corpus = [];
+    for (const c of components) {
+        if (c.type !== "asset")
+            continue;
+        const addr = c.properties?.terraform_address;
+        if (typeof addr !== "string" || addr.startsWith("provider."))
+            continue;
+        if (!areComponentsSectionCompatible(provider, c))
+            continue;
+        const rt = String(c.properties?.resource_type ?? "").toLowerCase();
+        const bn = String(c.properties?.block_name ?? "").toLowerCase();
+        if (rt)
+            corpus.push(rt);
+        if (bn)
+            corpus.push(bn);
+        corpus.push(addr.toLowerCase());
+        const cp = String(c.properties?.cloud_provider ?? "").toLowerCase();
+        if (cp)
+            corpus.push(cp);
+    }
+    return corpus;
+}
+function terraformAssetBelongsToProviderRule(component, providerId) {
+    const rt = String(component.properties?.resource_type ?? "").toLowerCase();
+    const cp = String(component.properties?.cloud_provider ?? "").toLowerCase();
+    const id = providerId.trim().toLowerCase();
+    if (id === "aws") {
+        return rt.startsWith("aws_") || cp === "aws";
+    }
+    if (id === "azure") {
+        return rt.startsWith("azurerm_") || rt.startsWith("azapi_") || cp === "azure";
+    }
+    if (id === "kubernetes") {
+        return rt.startsWith("kubernetes_") || cp === "kubernetes";
+    }
+    if (id === "supabase") {
+        return rt.startsWith("supabase_") || cp === "supabase" || rt.includes("supabase");
+    }
+    if (id === "vercel") {
+        return rt.startsWith("vercel_") || cp === "vercel";
+    }
+    return false;
+}
+/**
+ * Match Terraform `resource_type` against HashiCorp-provider-style names
+ * (e.g. `aws_s3_bucket`, prefix `aws_s3_`).
+ */
+function terraformResourceTypeMatchesTopologyRule(resourceType, exactTypes, prefixes) {
+    const rt = resourceType.trim().toLowerCase();
+    if (!rt)
+        return false;
+    for (const t of exactTypes) {
+        if (rt === t.trim().toLowerCase())
+            return true;
+    }
+    for (const p of prefixes) {
+        const prefix = p.trim().toLowerCase();
+        if (prefix.length > 0 && rt.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * When `terraformResourceTypes` / `terraformResourceTypePrefixes` are set on the
+ * rule (see `provider-topology.rules.yaml`), Terraform matching uses **only**
+ * `resource_type` — not block labels like `lambda_bucket`. Otherwise falls back
+ * to `usageSignals` + {@link terraformManagedNodeConsistentWithResourceType}.
+ */
+function terraformAssetMatchesManagedServiceTopologyRule(component, managedNode) {
+    const hasTfSchema = managedNode.terraformResourceTypePrefixes.length > 0 ||
+        managedNode.terraformResourceTypes.length > 0;
+    if (hasTfSchema) {
+        const rt = String(component.properties?.resource_type ?? "");
+        return terraformResourceTypeMatchesTopologyRule(rt, managedNode.terraformResourceTypes, managedNode.terraformResourceTypePrefixes);
+    }
+    return (terraformAssetMatchesManagedServiceSignals(component, managedNode.usageSignals) &&
+        terraformManagedNodeConsistentWithResourceType(component, managedNode.key));
+}
+function terraformSectionMatchesManagedServiceTopologyRule(provider, providerId, components, managedNode) {
+    return components.some((c) => {
+        if (c.type !== "asset")
+            return false;
+        const addr = c.properties?.terraform_address;
+        if (typeof addr !== "string" || addr.startsWith("provider."))
+            return false;
+        if (!areComponentsSectionCompatible(provider, c))
+            return false;
+        if (!terraformAssetBelongsToProviderRule(c, providerId))
+            return false;
+        return terraformAssetMatchesManagedServiceTopologyRule(c, managedNode);
+    });
+}
+function terraformAssetMatchesManagedServiceSignals(component, usageSignals) {
+    const hay = `${String(component.properties?.resource_type ?? "").toLowerCase()} ${String(component.properties?.block_name ?? "").toLowerCase()} ${String(component.properties?.terraform_address ?? "").toLowerCase()}`;
+    return usageSignals.some((sig) => hay.includes(sig.trim().toLowerCase()));
+}
+/**
+ * Disambiguates Terraform resources when block names include words like "lambda"
+ * but the resource is IAM, etc. Used only for **legacy** matching when YAML does
+ * not define `terraformResourceTypePrefixes` / `terraformResourceTypes`.
+ */
+function terraformManagedNodeConsistentWithResourceType(component, managedServiceKey) {
+    const rt = String(component.properties?.resource_type ?? "").toLowerCase();
+    if (!rt)
+        return true;
+    const k = managedServiceKey.trim().toLowerCase();
+    if (k === "lambda") {
+        return rt.includes("lambda") && !rt.includes("iam");
+    }
+    if (k === "s3") {
+        return rt.includes("s3");
+    }
+    if (k === "postgres") {
+        return (rt.includes("rds") ||
+            rt.includes("db_instance") ||
+            rt.includes("aurora") ||
+            rt.includes("postgres") ||
+            rt.includes("redshift") ||
+            rt.includes("dynamodb") ||
+            rt.includes("neptune") ||
+            rt.includes("documentdb"));
+    }
+    return true;
+}

package/dist/src/ai-enrichment/providers/endpoint-resolution.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Family-specific endpoint normalization. Defaults come from {@link AI_PROVIDER_PRESETS};
+ * these helpers only apply path/shape rules (e.g. bare OpenAI host → chat/completions URL).
+ */
+/** Normalize an OpenAI-style chat-completions URL (preset default is the canonical full path). */
+export declare function resolveChatCompletionsEndpoint(endpoint: string | undefined, presetDefaultEndpoint: string): string;
+/** True when the URL is not a chat/completions path (legacy `{ model, prompt }` shim). */
+export declare function shouldUseChatCompletionsJsonShim(url: string): boolean;
+/**
+ * Build a Gemini `generateContent` URL from a preset base (or full URL) and model id.
+ * `presetDefaultEndpoint` is typically `…/v1beta/models` without the model suffix.
+ */
+export declare function resolveGeminiGenerateContentEndpoint(endpoint: string | undefined, model: string, presetDefaultEndpoint: string): string;

package/dist/src/ai-enrichment/providers/endpoint-resolution.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Family-specific endpoint normalization. Defaults come from {@link AI_PROVIDER_PRESETS};
+ * these helpers only apply path/shape rules (e.g. bare OpenAI host → chat/completions URL).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveChatCompletionsEndpoint = resolveChatCompletionsEndpoint;
+exports.shouldUseChatCompletionsJsonShim = shouldUseChatCompletionsJsonShim;
+exports.resolveGeminiGenerateContentEndpoint = resolveGeminiGenerateContentEndpoint;
+/** Normalize an OpenAI-style chat-completions URL (preset default is the canonical full path). */
+function resolveChatCompletionsEndpoint(endpoint, presetDefaultEndpoint) {
+    const raw = endpoint?.trim();
+    if (!raw)
+        return presetDefaultEndpoint;
+    if (raw.includes("chat/completions"))
+        return raw;
+    if (raw.includes("api.openai.com"))
+        return presetDefaultEndpoint;
+    return raw;
+}
+/** True when the URL is not a chat/completions path (legacy `{ model, prompt }` shim). */
+function shouldUseChatCompletionsJsonShim(url) {
+    return !url.toLowerCase().includes("chat/completions");
+}
+/**
+ * Build a Gemini `generateContent` URL from a preset base (or full URL) and model id.
+ * `presetDefaultEndpoint` is typically `…/v1beta/models` without the model suffix.
+ */
+function resolveGeminiGenerateContentEndpoint(endpoint, model, presetDefaultEndpoint) {
+    const raw = endpoint?.trim() || presetDefaultEndpoint;
+    if (raw.includes(":generateContent"))
+        return raw;
+    const trimmed = raw.endsWith("/") ? raw.slice(0, -1) : raw;
+    if (trimmed.endsWith("/models")) {
+        return `${trimmed}/${encodeURIComponent(model)}:generateContent`;
+    }
+    if (trimmed.includes("/models/")) {
+        return `${trimmed}:generateContent`;
+    }
+    return `${trimmed}/${encodeURIComponent(model)}:generateContent`;
+}

package/dist/src/ai-enrichment/providers/families/chat-completions-family.d.ts

@@ -0,0 +1,13 @@
+import type { AiProviderId } from "../../types";
+import { type ResolvedProviderConfig } from "../resolve-provider";
+import type { AiProvider, AiProviderRequest, AiProviderResult } from "../types";
+/**
+ * OpenAI-style Chat Completions API. Used by the `openai` preset; also supports a
+ * legacy `{ model, prompt, max_tokens }` shim when the endpoint is not chat-completions-shaped.
+ */
+export declare class ChatCompletionsFamilyProvider implements AiProvider {
+    private readonly resolved;
+    readonly id: AiProviderId;
+    constructor(resolved: ResolvedProviderConfig);
+    infer(request: AiProviderRequest): Promise<AiProviderResult>;
+}