@dataparade/cli 0.0.1

package/dist/src/classifier/enhance.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enhanceComponent = enhanceComponent;
+exports.enhanceComponents = enhanceComponents;
+const enhance_defaults_1 = require("./enhance-defaults");
+const property_detection_config_1 = require("../config/property-detection-config");
+const main_application_selection_1 = require("./main-application-selection");
+const application_injection_1 = require("./application-injection");
+const frontend_frameworks_1 = require("../patterns/frontend-frameworks");
+function setIfMissing(props, key, value) {
+    const current = props[key];
+    if (current === undefined || current === "" || current === null) {
+        props[key] = value;
+    }
+}
+function toTitleCase(s) {
+    return s
+        .split(/\s+/)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+        .join(" ");
+}
+function normalizeApiDisplayName(rawName, properties) {
+    const name = (rawName || "").trim();
+    if (!name)
+        return name;
+    const lower = name.toLowerCase();
+    const isGenericApiName = lower === "route handler" ||
+        lower.startsWith("nest_controller") ||
+        /^(get|post|put|delete|patch|options|head)\s+/.test(lower);
+    if (!isGenericApiName)
+        return name;
+    const sectionLabel = properties?.section_label;
+    if (typeof sectionLabel === "string" && sectionLabel.trim()) {
+        return `${sectionLabel.trim()} API`;
+    }
+    const sectionId = properties?.section_id;
+    if (typeof sectionId === "string" &&
+        sectionId.trim() &&
+        sectionId !== "root" &&
+        sectionId !== "global" &&
+        sectionId !== "<unsectioned>") {
+        return `${sectionId.trim()} API`;
+    }
+    return "API";
+}
+/**
+ * Enhances a single component with defaults for all inferrable properties
+ * per node type (asset, actor, third_party). Does not set isMainApplication
+ * (that is applied in enhanceComponents).
+ */
+function enhanceComponent(component) {
+    const properties = { ...component.properties };
+    // Apply all Engineering, Privacy, and Security property defaults for this type (only when missing)
+    const defaults = (0, enhance_defaults_1.getDefaultsForType)(component.type);
+    for (const key of Object.keys(defaults)) {
+        if (properties[key] === undefined) {
+            properties[key] = defaults[key];
+        }
+    }
+    switch (component.type) {
+        case "asset":
+            enhanceAsset(component, properties);
+            break;
+        case "third_party":
+            enhanceThirdParty(component, properties);
+            break;
+        case "actor":
+            enhanceActor(component, properties);
+            break;
+    }
+    return {
+        ...component,
+        properties,
+    };
+}
+function enhanceAsset(component, properties) {
+    const { subType } = component;
+    const { cloudAssetSubtypes, onPremAssetSubtypes, supportedOperationsBySubType } = (0, property_detection_config_1.loadPropertyDetectionConfig)().enhance;
+    // technology_stack: infer from databaseType or known name (only when we have a value)
+    const techStack = inferTechnologyStack(component);
+    if (techStack) {
+        setIfMissing(properties, "technology_stack", techStack);
+    }
+    // hosting_type: cloud for api/database/cache/etc., on_premise for config
+    if (subType && cloudAssetSubtypes.has(subType)) {
+        setIfMissing(properties, "hosting_type", "cloud");
+    }
+    else if (subType && onPremAssetSubtypes.has(subType)) {
+        setIfMissing(properties, "hosting_type", "on_premise");
+    }
+    else {
+        setIfMissing(properties, "hosting_type", "cloud");
+    }
+    // database_engine: for database/cache, from databaseType
+    if (subType === "database" || subType === "cache") {
+        const dbType = component.properties.databaseType;
+        if (typeof dbType === "string" && dbType.trim()) {
+            setIfMissing(properties, "database_engine", `${dbType.trim().charAt(0).toUpperCase()}${dbType.trim().slice(1).toLowerCase()}`);
+        }
+    }
+    // supported_operations: by subType from config
+    if (subType && supportedOperationsBySubType[subType]?.length) {
+        setIfMissing(properties, "supported_operations", supportedOperationsBySubType[subType]);
+    }
+}
+function inferTechnologyStack(component) {
+    const existing = component.properties.technology_stack;
+    if (existing !== undefined && existing !== "") {
+        return String(existing);
+    }
+    const dbType = component.properties.databaseType;
+    if (typeof dbType === "string" && dbType.trim()) {
+        return dbType.trim().toLowerCase();
+    }
+    const name = component.name?.trim().toLowerCase();
+    const { knownDatabaseNames } = (0, property_detection_config_1.loadPropertyDetectionConfig)();
+    if (name &&
+        (component.subType === "database" || component.subType === "cache") &&
+        knownDatabaseNames.has(name)) {
+        return name;
+    }
+    // Do not fall back to generic "database" / "cache" — leave technology_stack unset (default null)
+    return "";
+}
+function enhanceThirdParty(component, properties) {
+    const { defaultThirdPartyHosting } = (0, property_detection_config_1.loadPropertyDetectionConfig)().enhance;
+    setIfMissing(properties, "hosting_type", defaultThirdPartyHosting);
+    setIfMissing(properties, "integration_method", "api");
+    if (component.name && !properties.vendor) {
+        properties.vendor = toTitleCase(component.name.trim());
+    }
+}
+function enhanceActor(component, properties) {
+    if (component.subType === "customer") {
+        properties.isDataSubject = true; // override default false for customer
+    }
+}
+function isSingleRouteApiAsset(component) {
+    if (component.type !== "asset" || component.subType !== "api") {
+        return false;
+    }
+    const name = (component.name || "").trim();
+    if (!name)
+        return false;
+    const lower = name.toLowerCase();
+    if (lower === "route handler") {
+        return true;
+    }
+    if (lower.startsWith("nest_controller")) {
+        return true;
+    }
+    if (/^(get|post|put|delete|patch|options|head)\s+/.test(lower)) {
+        return true;
+    }
+    return false;
+}
+function getFrameworkPriority(component) {
+    const value = component.properties.framework;
+    const frameworks = [];
+    if (typeof value === "string") {
+        frameworks.push(value);
+    }
+    else if (Array.isArray(value)) {
+        for (const v of value) {
+            if (typeof v === "string") {
+                frameworks.push(v);
+            }
+        }
+    }
+    if (frameworks.length === 0)
+        return 100;
+    let best = 100;
+    for (const raw of frameworks) {
+        const fw = raw.toLowerCase();
+        if (frontend_frameworks_1.FRONTEND_FRAMEWORK_HINTS_SET.has(fw)) {
+            best = Math.min(best, 0);
+        }
+        else if (frontend_frameworks_1.SERVER_FRAMEWORK_HINTS.has(fw)) {
+            best = Math.min(best, 1);
+        }
+        else {
+            best = Math.min(best, 2);
+        }
+    }
+    return best;
+}
+/**
+ * Enhances all components with defaults for all node types, then sets
+ * isMainApplication on a "primary" app asset per section_id (framework-aware),
+ * and normalizes generic API display names.
+ */
+function enhanceComponents(components) {
+    const enhanced = components.map(enhanceComponent);
+    const { mainAppSubtypes } = (0, property_detection_config_1.loadPropertyDetectionConfig)().enhance;
+    // Clear any existing isMainApplication markers so the selection is deterministic.
+    for (const c of enhanced) {
+        if (c.type === "asset" &&
+            c.subType !== undefined &&
+            mainAppSubtypes.has(c.subType)) {
+            if ("isMainApplication" in c.properties) {
+                delete c.properties.isMainApplication;
+            }
+        }
+    }
+    const sectionIdFor = (c) => typeof c.properties?.section_id === "string" && c.properties.section_id.trim()
+        ? c.properties.section_id.trim()
+        : "<unsectioned>";
+    const bySectionRegular = new Map();
+    const bySectionSingleRoute = new Map();
+    for (let i = 0; i < enhanced.length; i++) {
+        const c = enhanced[i];
+        if (c.type === "asset" &&
+            c.subType !== undefined &&
+            mainAppSubtypes.has(c.subType)) {
+            if ((0, main_application_selection_1.isTerraformGraphResourceAsset)(c)) {
+                continue;
+            }
+            if ((0, main_application_selection_1.isTerraformUtilityInfrastructureAsset)(c)) {
+                continue;
+            }
+            if ((0, main_application_selection_1.isTerraformStructuralInfrastructureAsset)(c)) {
+                continue;
+            }
+            if ((0, main_application_selection_1.isTerraformModuleCallShellAsset)(c)) {
+                continue;
+            }
+            const sid = sectionIdFor(c);
+            const priority = getFrameworkPriority(c);
+            if (isSingleRouteApiAsset(c)) {
+                const list = bySectionSingleRoute.get(sid);
+                if (list)
+                    list.push({ index: i, frameworkPriority: priority });
+                else
+                    bySectionSingleRoute.set(sid, [{ index: i, frameworkPriority: priority }]);
+            }
+            else {
+                const list = bySectionRegular.get(sid);
+                if (list)
+                    list.push({ index: i, frameworkPriority: priority });
+                else
+                    bySectionRegular.set(sid, [{ index: i, frameworkPriority: priority }]);
+            }
+        }
+    }
+    if (bySectionRegular.size + bySectionSingleRoute.size === 0)
+        return enhanced;
+    const sectionKeys = new Set([
+        ...Array.from(bySectionRegular.keys()),
+        ...Array.from(bySectionSingleRoute.keys()),
+    ]);
+    const hasNonGlobal = Array.from(sectionKeys).some((sid) => sid !== "global");
+    const updated = [...enhanced];
+    for (const sid of sectionKeys) {
+        if (hasNonGlobal && sid === "global")
+            continue;
+        const candidates = bySectionRegular.get(sid) ?? bySectionSingleRoute.get(sid);
+        if (!candidates || candidates.length === 0)
+            continue;
+        candidates.sort((a, b) => {
+            const aCtx = updated[a.index]?.properties?.sourceContext;
+            const bCtx = updated[b.index]?.properties?.sourceContext;
+            const aInj = aCtx === application_injection_1.INJECTED_PROJECT_PLACEHOLDER_SOURCE_CONTEXT ? 0 : 1;
+            const bInj = bCtx === application_injection_1.INJECTED_PROJECT_PLACEHOLDER_SOURCE_CONTEXT ? 0 : 1;
+            if (aInj !== bInj)
+                return aInj - bInj;
+            if (a.frameworkPriority !== b.frameworkPriority) {
+                return a.frameworkPriority - b.frameworkPriority;
+            }
+            return a.index - b.index;
+        });
+        const pick = candidates[0];
+        const main = updated[pick.index];
+        const sectionLabelRaw = main.properties?.section_label;
+        const sectionLabel = typeof sectionLabelRaw === "string" && sectionLabelRaw.trim()
+            ? sectionLabelRaw.trim()
+            : undefined;
+        const preferredMainName = sid !== "<unsectioned>" && sid !== "root"
+            ? sectionLabel ?? sid
+            : main.name;
+        updated[pick.index] = {
+            ...main,
+            name: preferredMainName,
+            properties: { ...main.properties, isMainApplication: true },
+        };
+    }
+    return updated.map((component) => {
+        if (component.type === "asset" && component.subType === "api") {
+            return {
+                ...component,
+                name: normalizeApiDisplayName(component.name, component.properties),
+            };
+        }
+        return component;
+    });
+}

package/dist/src/classifier/external-url-third-party.d.ts

@@ -0,0 +1,26 @@
+import type { RawFinding } from "../core/types/detection";
+export declare function shouldIgnoreExternalHttpUrl(url: string | undefined): boolean;
+/**
+ * Stable third-party key: registrable-style host (last two DNS labels), e.g.
+ * api.openai.com → openai.com, clipdrop-api.co → clipdrop-api.co.
+ */
+export declare function deriveServiceKeyFromHostname(host: string): string;
+/**
+ * Hostname + registrable domain keys from an absolute http(s) URL (for matching
+ * external_api_call findings to third_party nodes by endpoint).
+ */
+export declare function urlHostMatchKeys(url: string): Set<string>;
+/**
+ * When YAML `url_host_patterns` do not match, derive a stable service key from the
+ * URL hostname (registrable-style). Skips env-interpolated and local/private hosts.
+ * Used at detection time so we do not maintain an exhaustive vendor URL list.
+ */
+export declare function defaultServiceNameFromLiteralPublicUrl(url: string | undefined): string | undefined;
+/**
+ * When a finding is an external_api_call with a literal public http(s) URL and no
+ * env interpolation, treat it as a third-party SaaS/API for classification.
+ */
+export declare function inferThirdPartyFromLiteralHttpUrl(finding: RawFinding): {
+    serviceName: string;
+    subType: string;
+} | undefined;

package/dist/src/classifier/external-url-third-party.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldIgnoreExternalHttpUrl = shouldIgnoreExternalHttpUrl;
+exports.deriveServiceKeyFromHostname = deriveServiceKeyFromHostname;
+exports.urlHostMatchKeys = urlHostMatchKeys;
+exports.defaultServiceNameFromLiteralPublicUrl = defaultServiceNameFromLiteralPublicUrl;
+exports.inferThirdPartyFromLiteralHttpUrl = inferThirdPartyFromLiteralHttpUrl;
+const config_1 = require("./config");
+/**
+ * Structural heuristics (not a vendor list): URLs that are obviously templated or
+ * env-driven should not be treated as static third-party endpoints.
+ */
+const ENV_OR_DYNAMIC_URL = /\$\{|process\.env|import\.meta\.env|\bgetenv\s*\(/i;
+function extractLiteralHttpUrl(finding) {
+    if (finding.pattern !== "external_api_call") {
+        return undefined;
+    }
+    const props = finding.properties ?? {};
+    const fromProp = typeof props.url === "string" ? props.url.trim() : "";
+    const fromName = typeof finding.name === "string" && /^https?:\/\//i.test(finding.name)
+        ? finding.name.trim()
+        : "";
+    const raw = fromProp || fromName;
+    if (!raw || !/^https?:\/\//i.test(raw)) {
+        return undefined;
+    }
+    if (ENV_OR_DYNAMIC_URL.test(raw)) {
+        return undefined;
+    }
+    return raw;
+}
+function isLocalOrPrivateHost(hostname) {
+    const h = hostname.toLowerCase();
+    if (h === "localhost" || h.endsWith(".localhost"))
+        return true;
+    if (h === "127.0.0.1" || h === "0.0.0.0" || h === "::1")
+        return true;
+    if (h.endsWith(".local") || h.endsWith(".internal"))
+        return true;
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(h)) {
+        const p = h.split(".").map((x) => Number(x));
+        if (p[0] === 10)
+            return true;
+        if (p[0] === 172 && p[1] >= 16 && p[1] <= 31)
+            return true;
+        if (p[0] === 192 && p[1] === 168)
+            return true;
+    }
+    return false;
+}
+function shouldIgnoreExternalHttpUrl(url) {
+    if (typeof url !== "string")
+        return true;
+    const t = url.trim();
+    if (!/^https?:\/\//i.test(t))
+        return true;
+    if (ENV_OR_DYNAMIC_URL.test(t))
+        return true;
+    if (/^https?:\/\/\.\.\.(\/|$)/i.test(t))
+        return true;
+    try {
+        const hostnameRaw = new URL(t).hostname;
+        if (hostnameRaw == null || !hostnameRaw || hostnameRaw.includes("${")) {
+            return true;
+        }
+        const hostname = hostnameRaw.toLowerCase();
+        if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/i.test(hostname)) {
+            return true;
+        }
+        if (isLocalOrPrivateHost(hostname))
+            return true;
+    }
+    catch {
+        return true;
+    }
+    return false;
+}
+/**
+ * Stable third-party key: registrable-style host (last two DNS labels), e.g.
+ * api.openai.com → openai.com, clipdrop-api.co → clipdrop-api.co.
+ */
+function deriveServiceKeyFromHostname(host) {
+    const h = host.replace(/^www\./, "").toLowerCase();
+    const parts = h.split(".").filter(Boolean);
+    if (parts.length < 2) {
+        return parts[0] ?? h;
+    }
+    return `${parts[parts.length - 2]}.${parts[parts.length - 1]}`;
+}
+/**
+ * Hostname + registrable domain keys from an absolute http(s) URL (for matching
+ * external_api_call findings to third_party nodes by endpoint).
+ */
+function urlHostMatchKeys(url) {
+    const keys = new Set();
+    const t = url.trim();
+    if (!/^https?:\/\//i.test(t)) {
+        return keys;
+    }
+    try {
+        const hostnameRaw = new URL(t).hostname;
+        if (hostnameRaw == null || !hostnameRaw) {
+            return keys;
+        }
+        const hostname = hostnameRaw.toLowerCase();
+        keys.add(hostname);
+        keys.add(deriveServiceKeyFromHostname(hostname));
+    }
+    catch {
+        // ignore malformed URLs
+    }
+    return keys;
+}
+/**
+ * When YAML `url_host_patterns` do not match, derive a stable service key from the
+ * URL hostname (registrable-style). Skips env-interpolated and local/private hosts.
+ * Used at detection time so we do not maintain an exhaustive vendor URL list.
+ */
+function defaultServiceNameFromLiteralPublicUrl(url) {
+    if (shouldIgnoreExternalHttpUrl(url)) {
+        return undefined;
+    }
+    const t = url.trim();
+    try {
+        const hostname = new URL(t).hostname;
+        if (hostname == null || !hostname) {
+            return undefined;
+        }
+        return deriveServiceKeyFromHostname(hostname);
+    }
+    catch {
+        return undefined;
+    }
+}
+const DEFAULT_INFERRED_THIRD_PARTY_SUBTYPE = "saas_service";
+/**
+ * Pick subType from third-party.classifier.yaml by longest matchKey substring
+ * contained in the hostname (import-style keys like @scope/pkg are skipped).
+ */
+function inferSubTypeFromClassifierCatalog(hostname) {
+    const hostLower = hostname.toLowerCase();
+    const { thirdParties } = (0, config_1.loadClassifierConfig)();
+    let bestLen = 0;
+    let bestSubType = DEFAULT_INFERRED_THIRD_PARTY_SUBTYPE;
+    for (const tp of thirdParties) {
+        for (const mk of tp.matchKeys) {
+            const k = mk.toLowerCase().trim();
+            if (k.length < 3)
+                continue;
+            if (k.startsWith("@"))
+                continue;
+            if (k.includes("/") && !k.includes("."))
+                continue;
+            if (!hostLower.includes(k))
+                continue;
+            if (k.length > bestLen) {
+                bestLen = k.length;
+                bestSubType = tp.subType;
+            }
+        }
+    }
+    return bestSubType;
+}
+/**
+ * When a finding is an external_api_call with a literal public http(s) URL and no
+ * env interpolation, treat it as a third-party SaaS/API for classification.
+ */
+function inferThirdPartyFromLiteralHttpUrl(finding) {
+    const urlString = extractLiteralHttpUrl(finding);
+    if (!urlString || shouldIgnoreExternalHttpUrl(urlString)) {
+        return undefined;
+    }
+    let hostname;
+    try {
+        const hostnameRaw = new URL(urlString).hostname;
+        if (hostnameRaw == null || !hostnameRaw) {
+            return undefined;
+        }
+        hostname = hostnameRaw;
+    }
+    catch {
+        return undefined;
+    }
+    if (isLocalOrPrivateHost(hostname)) {
+        return undefined;
+    }
+    const serviceName = deriveServiceKeyFromHostname(hostname);
+    if (!serviceName) {
+        return undefined;
+    }
+    return {
+        serviceName,
+        subType: inferSubTypeFromClassifierCatalog(hostname),
+    };
+}

package/dist/src/classifier/grouping.d.ts

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

package/dist/src/classifier/grouping.js

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

package/dist/src/classifier/main-application-selection.d.ts

@@ -0,0 +1,41 @@
+import type { DetectedComponent } from "../core/types/component";
+import { PREFERRED_WEB_APP_FRAMEWORKS } from "../patterns/frontend-frameworks";
+export { PREFERRED_WEB_APP_FRAMEWORKS };
+/**
+ * Thin / single-endpoint API surfaces that should not be treated as the primary
+ * application hub (e.g. one handler named "POST /foo").
+ */
+export declare function isSingleRouteApiAsset(component: DetectedComponent): boolean;
+/**
+ * Outbound HTTP client calls to absolute URLs (e.g. fetch("https://api.vendor/..."))
+ * classified as api assets — not the project's own HTTP API surface.
+ */
+export declare function isOutboundExternalHttpApiAsset(component: DetectedComponent): boolean;
+/**
+ * Terraform resources from utility providers (names, time sleeps, etc.) are not
+ * application entrypoints; they should not win isMainApplication when that is
+ * the only "application" subtype asset in a section.
+ */
+export declare function isTerraformUtilityInfrastructureAsset(component: DetectedComponent): boolean;
+/**
+ * Networking / IAM / orchestration / data-plane stores from Terraform should not
+ * become the product "main app" when no real service code exists — use the injected
+ * placeholder instead.
+ */
+export declare function isTerraformStructuralInfrastructureAsset(component: DetectedComponent): boolean;
+/**
+ * Terraform resource/data blocks in the diagram are infrastructure, not the
+ * product application hub (e.g. `kubernetes_deployment.*`, `aws_s3_bucket.*`).
+ */
+export declare function isTerraformGraphResourceAsset(component: DetectedComponent): boolean;
+/**
+ * `module.vpc` / `module.frontend` call shells: not the product application.
+ */
+export declare function isTerraformModuleCallShellAsset(component: DetectedComponent): boolean;
+export declare function isExcludedFromMainApplicationHub(component: DetectedComponent): boolean;
+/**
+ * Index of the asset that should be the main application hub, or -1 if none.
+ * Uses the same rules as enhanceComponents (subtype allowlist, exclusions, then
+ * framework priority).
+ */
+export declare function pickMainApplicationAssetIndex(components: DetectedComponent[]): number;