nexarch 0.12.6 → 0.12.7

package/dist/lib/terraform-catalogue-seed.js

@@ -0,0 +1,206 @@
+/**
+ * Seed catalogue for Terraform resource types.
+ *
+ * The catalogue proper is platform reference data (see the infrastructure
+ * ingestion ADR) so that supporting a new Azure service is a data change served
+ * to every tenant, not a CLI release. This list is the bootstrap: what the
+ * platform is seeded with, and what the CLI falls back to when it cannot reach
+ * the registry — the same pattern the Claude Code skill template already uses.
+ *
+ * Two rules when adding an entry:
+ *
+ *   - Name only attributes an application author must conform to. This is the
+ *     contract surface, not an inventory: Azure Resource Graph already knows
+ *     what exists, in more detail, in real time.
+ *   - Never name an attribute that can carry a credential. Terraform's
+ *     `sensitive_values` gate will drop it anyway, but the list should not be
+ *     relying on the second gate to be correct.
+ */
+const COMMON = ["name", "location", "resource_group_name"];
+export const TERRAFORM_CATALOGUE_SEED = [
+    // ---------------------------------------------------------------- compute
+    {
+        resourceType: "azurerm_container_app",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_runtime",
+        role: "compute_host",
+        bindable: true,
+        attributes: [...COMMON, "container_app_environment_id", "revision_mode", "workload_profile_name"],
+    },
+    {
+        resourceType: "azurerm_container_app_job",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_runtime",
+        role: "compute_host",
+        bindable: true,
+        attributes: [...COMMON, "container_app_environment_id", "replica_timeout_in_seconds", "workload_profile_name"],
+    },
+    {
+        resourceType: "azurerm_container_app_environment",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_runtime",
+        role: "compute_environment",
+        attributes: [...COMMON, "default_domain", "infrastructure_subnet_id", "internal_load_balancer_enabled", "static_ip_address", "zone_redundancy_enabled"],
+    },
+    {
+        resourceType: "azurerm_linux_web_app",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_runtime",
+        role: "compute_host",
+        bindable: true,
+        attributes: [...COMMON, "service_plan_id", "https_only", "default_hostname"],
+    },
+    {
+        resourceType: "azurerm_service_plan",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_runtime",
+        role: "compute_environment",
+        attributes: [...COMMON, "sku_name", "os_type", "worker_count"],
+    },
+    // ------------------------------------------------------------------- data
+    {
+        resourceType: "azurerm_postgresql_flexible_server",
+        entityTypeCode: "data_store",
+        entitySubtypeCode: "store_relational",
+        role: "data_store",
+        attributes: [...COMMON, "fqdn", "version", "sku_name", "storage_mb", "storage_tier", "public_network_access_enabled", "delegated_subnet_id", "private_dns_zone_id", "backup_retention_days", "geo_redundant_backup_enabled", "zone"],
+    },
+    {
+        resourceType: "azurerm_postgresql_flexible_server_database",
+        entityTypeCode: "data_store",
+        entitySubtypeCode: "store_relational",
+        role: "data_store",
+        attributes: ["name", "server_id", "charset", "collation"],
+    },
+    {
+        resourceType: "azurerm_storage_account",
+        entityTypeCode: "data_store",
+        entitySubtypeCode: "store_object",
+        role: "data_store",
+        attributes: [...COMMON, "account_kind", "account_tier", "account_replication_type", "access_tier", "https_traffic_only_enabled", "min_tls_version", "public_network_access_enabled", "allow_nested_items_to_be_public", "shared_access_key_enabled", "primary_blob_endpoint", "primary_location", "secondary_location"],
+    },
+    {
+        resourceType: "azurerm_storage_container",
+        entityTypeCode: "data_store",
+        entitySubtypeCode: "store_object",
+        role: "data_store",
+        attributes: ["name", "container_access_type", "storage_account_id", "has_immutability_policy"],
+    },
+    {
+        resourceType: "azurerm_cosmosdb_account",
+        entityTypeCode: "data_store",
+        entitySubtypeCode: "store_document",
+        role: "data_store",
+        attributes: [...COMMON, "kind", "offer_type", "public_network_access_enabled", "endpoint"],
+    },
+    // ---------------------------------------------------------------- secrets
+    {
+        resourceType: "azurerm_key_vault",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "secret_store",
+        attributes: [...COMMON, "vault_uri", "sku_name", "enable_rbac_authorization", "rbac_authorization_enabled", "public_network_access_enabled", "purge_protection_enabled", "soft_delete_retention_days"],
+    },
+    // -------------------------------------------------------------- messaging
+    {
+        resourceType: "azurerm_servicebus_namespace",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "messaging",
+        attributes: [...COMMON, "sku", "public_network_access_enabled"],
+    },
+    {
+        resourceType: "azurerm_servicebus_queue",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "messaging",
+        attributes: ["name", "namespace_id", "max_delivery_count", "requires_session"],
+    },
+    // ---------------------------------------------------------------- network
+    {
+        resourceType: "azurerm_virtual_network",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "network_boundary",
+        attributes: [...COMMON, "address_space", "guid"],
+    },
+    {
+        resourceType: "azurerm_subnet",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "network_boundary",
+        attributes: ["name", "resource_group_name", "virtual_network_name", "address_prefixes", "default_outbound_access_enabled", "private_endpoint_network_policies"],
+    },
+    {
+        resourceType: "azurerm_private_endpoint",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "network_boundary",
+        attributes: [...COMMON, "subnet_id"],
+    },
+    {
+        resourceType: "azurerm_private_dns_zone",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "network_boundary",
+        attributes: ["name", "resource_group_name", "number_of_record_sets"],
+    },
+    // ---------------------------------------------------------------- identity
+    {
+        resourceType: "azurerm_user_assigned_identity",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_control_plane",
+        role: "identity",
+        attributes: [...COMMON, "client_id", "principal_id", "tenant_id"],
+    },
+    {
+        resourceType: "azurerm_role_assignment",
+        entityTypeCode: "policy_control",
+        role: "identity",
+        attributes: ["name", "principal_id", "principal_type", "role_definition_name", "scope"],
+    },
+    // ---------------------------------------------------------------- registry
+    {
+        resourceType: "azurerm_container_registry",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "registry",
+        attributes: [...COMMON, "login_server", "sku", "admin_enabled", "public_network_access_enabled"],
+    },
+    // ----------------------------------------------------------------- edge/AI
+    {
+        resourceType: "azurerm_cdn_frontdoor_profile",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "edge",
+        attributes: [...COMMON, "sku_name", "response_timeout_seconds"],
+    },
+    {
+        resourceType: "azurerm_cdn_frontdoor_endpoint",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "edge",
+        attributes: ["name", "host_name", "enabled", "cdn_frontdoor_profile_id"],
+    },
+    {
+        resourceType: "azurerm_cdn_frontdoor_firewall_policy",
+        entityTypeCode: "policy_control",
+        role: "edge",
+        attributes: [...COMMON, "sku_name", "mode", "enabled"],
+    },
+    {
+        resourceType: "azurerm_cognitive_account",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "compute_host",
+        attributes: [...COMMON, "kind", "sku_name", "endpoint", "custom_subdomain_name", "public_network_access_enabled", "local_auth_enabled"],
+    },
+    // ----------------------------------------------------------- observability
+    {
+        resourceType: "azurerm_log_analytics_workspace",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "observability",
+        attributes: [...COMMON, "sku", "retention_in_days", "workspace_id"],
+    },
+];

package/dist/lib/terraform-detect.js

@@ -0,0 +1,338 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join, sep } from "path";
+const SCAN_DEPTH = 8;
+const IGNORED_DIRS = new Set(["node_modules", ".git", ".terraform", "dist", "build", ".next"]);
+function collectTerraformFiles(dir, depth = 0, out = []) {
+    if (depth > SCAN_DEPTH)
+        return out;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (IGNORED_DIRS.has(entry))
+            continue;
+        const full = join(dir, entry);
+        let isDir = false;
+        try {
+            isDir = statSync(full).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir)
+            collectTerraformFiles(full, depth + 1, out);
+        else if (entry.endsWith(".tf"))
+            out.push(full);
+    }
+    return out;
+}
+function detectCiSystem(dir) {
+    if (existsSync(join(dir, ".gitlab-ci.yml")))
+        return { ciSystem: "gitlab", ciFile: ".gitlab-ci.yml" };
+    if (existsSync(join(dir, ".github", "workflows")))
+        return { ciSystem: "github", ciFile: ".github/workflows" };
+    const seen = [];
+    const visit = (current, depth) => {
+        if (depth > 3 || seen.length > 0)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(current);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (IGNORED_DIRS.has(entry))
+                continue;
+            const full = join(current, entry);
+            let isDir = false;
+            try {
+                isDir = statSync(full).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (isDir) {
+                visit(full, depth + 1);
+                continue;
+            }
+            const relative = full.slice(dir.length + 1).split(sep).join("/");
+            if (/azure-pipelines.*\.ya?ml$/i.test(entry)) {
+                seen.push({ ciSystem: "azure-pipelines", ciFile: relative });
+                return;
+            }
+            if (entry === ".gitlab-ci.yml") {
+                seen.push({ ciSystem: "gitlab", ciFile: relative });
+                return;
+            }
+        }
+    };
+    visit(dir, 0);
+    return seen[0] ?? { ciSystem: null, ciFile: null };
+}
+/** Collects reusable module directories wherever they live, not only at the root. */
+function collectModuleDirectories(dir, depth = 0, out = []) {
+    if (depth > 3)
+        return out;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (IGNORED_DIRS.has(entry))
+            continue;
+        const full = join(dir, entry);
+        try {
+            if (!statSync(full).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (entry === "modules") {
+            // The children of a modules directory are the reusable building blocks:
+            // network, database, keyvault, and so on — the vocabulary of the estate.
+            try {
+                for (const child of readdirSync(full)) {
+                    if (statSync(join(full, child)).isDirectory())
+                        out.push(child);
+                }
+            }
+            catch {
+                // Unreadable modules directory is not fatal.
+            }
+            continue;
+        }
+        collectModuleDirectories(full, depth + 1, out);
+    }
+    return out;
+}
+const ROOT_SCAN_DEPTH = 4;
+const ENVIRONMENT_DIR = /^(dev|development|test|qa|uat|sit|stag|staging|preprod|pre-prod|prod|production|live|dr)$/i;
+/**
+ * Infers an environment from a root module's path.
+ *
+ * A directory called `environments/prod` is a stronger statement about which
+ * environment is being ingested than anything inside the state, and it is
+ * available before Terraform is run at all.
+ */
+export function environmentFromPath(relativePath) {
+    const segments = relativePath.split(/[\\/]+/).filter(Boolean);
+    for (let i = segments.length - 1; i >= 0; i -= 1) {
+        if (ENVIRONMENT_DIR.test(segments[i]))
+            return segments[i].toLowerCase();
+    }
+    return null;
+}
+/**
+ * Finds the root modules in a repository.
+ *
+ * Real estates are not one directory with one state. A repository commonly
+ * carries a root module per environment plus separate stacks for shared
+ * services, each with its own state, so assuming the current directory is
+ * *the* root module fails on the first serious layout it meets.
+ *
+ * Distinguishing a root from a shared module is the crux: both contain `.tf`
+ * files and both may declare `required_providers`. A root is what configures a
+ * backend or a provider, is initialised, carries tfvars, or lives under a
+ * conventional stacks directory — and never lives under `modules/`.
+ */
+export function discoverRootModules(repoDir) {
+    const found = [];
+    const visit = (dir, relative, depth) => {
+        if (depth > ROOT_SCAN_DEPTH)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        const tfFiles = entries.filter((entry) => entry.endsWith(".tf"));
+        const isUnderModules = /(^|[\\/])modules([\\/]|$)/i.test(relative);
+        if (tfFiles.length > 0 && !isUnderModules) {
+            const signals = [];
+            let hasBackend = false;
+            let hasLocalBackend = false;
+            let hasProvider = false;
+            for (const file of tfFiles.slice(0, 25)) {
+                let content = "";
+                try {
+                    content = readFileSync(join(dir, file), "utf8");
+                }
+                catch {
+                    continue;
+                }
+                const backendMatch = content.match(/\bbackend\s+"([a-z0-9_]+)"\s*\{/);
+                if (backendMatch) {
+                    hasBackend = true;
+                    if (backendMatch[1] === "local")
+                        hasLocalBackend = true;
+                }
+                // A provider *configuration*, not a required_providers declaration —
+                // shared modules declare requirements but must not configure providers.
+                if (/^\s*provider\s+"[a-z0-9_]+"\s*\{/m.test(content))
+                    hasProvider = true;
+            }
+            const initialised = existsSync(join(dir, ".terraform"));
+            const hasTfvars = entries.some((entry) => entry.endsWith(".tfvars") || entry.endsWith(".tfvars.json"));
+            const environmentHint = environmentFromPath(relative);
+            const underStacksDir = /(^|[\\/])(environments|envs|stacks|live)([\\/]|$)/i.test(relative);
+            if (hasBackend)
+                signals.push(hasLocalBackend ? "local backend" : "remote backend");
+            if (hasProvider)
+                signals.push("provider configuration");
+            if (initialised)
+                signals.push("initialised");
+            if (hasTfvars)
+                signals.push("tfvars");
+            if (underStacksDir)
+                signals.push("stacks directory");
+            if (hasBackend || hasProvider || initialised || (underStacksDir && hasTfvars) || (underStacksDir && environmentHint)) {
+                found.push({ dir, relative: relative || ".", signals, environmentHint, initialised, usesLocalBackend: hasLocalBackend });
+                // A root module's subdirectories are its own modules, not further roots.
+                return;
+            }
+        }
+        for (const entry of entries) {
+            if (IGNORED_DIRS.has(entry))
+                continue;
+            const full = join(dir, entry);
+            try {
+                if (!statSync(full).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            visit(full, relative ? `${relative}/${entry}` : entry, depth + 1);
+        }
+    };
+    visit(repoDir, "", 0);
+    return found.sort((a, b) => a.relative.localeCompare(b.relative));
+}
+export function detectInfrastructureProject(dir) {
+    const files = collectTerraformFiles(dir);
+    const signals = [];
+    if (files.length > 0)
+        signals.push(`${files.length} Terraform file${files.length === 1 ? "" : "s"}`);
+    if (existsSync(join(dir, ".terraform.lock.hcl")))
+        signals.push("provider lock file");
+    if (existsSync(join(dir, ".terraform")))
+        signals.push("initialised working directory");
+    let hasRemoteBackend = false;
+    let hasProviderBlock = false;
+    // The cap guards against a pathological repo, not against a large one: now
+    // that the scan reaches the whole tree, a low cap would read only whichever
+    // subtree the walk happened to enter first and miss the backend entirely.
+    for (const file of files.slice(0, 400)) {
+        let content = "";
+        try {
+            content = readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        // `backend "local"` marks a root module but is emphatically not remote
+        // state — a bootstrap stack uses it precisely because it creates the remote
+        // backend everything else then uses.
+        const backendMatch = content.match(/\bbackend\s+"([a-z0-9_]+)"\s*\{/);
+        if (backendMatch && backendMatch[1] !== "local")
+            hasRemoteBackend = true;
+        if (/\bprovider\s+"[a-z0-9_]+"\s*\{/.test(content))
+            hasProviderBlock = true;
+    }
+    if (hasRemoteBackend)
+        signals.push("remote state backend");
+    if (hasProviderBlock)
+        signals.push("provider configuration");
+    const moduleDirectories = [...new Set(collectModuleDirectories(dir))].sort();
+    if (moduleDirectories.length > 0)
+        signals.push(`${moduleDirectories.length} reusable modules`);
+    // One stray .tf file inside an application repo is not an infrastructure
+    // repo. Requiring corroboration keeps the classification from hijacking
+    // onboarding for a project that merely ships a snippet of Terraform.
+    // Deep layouts keep every .tf file below the two-level scan above, so
+    // discovery is consulted as well: a repository whose roots live in
+    // infra/environments/<env> is unmistakably an infrastructure repository even
+    // though its top two levels contain no Terraform at all.
+    const rootModules = discoverRootModules(dir);
+    if (rootModules.length > 0) {
+        signals.push(`${rootModules.length} root module${rootModules.length === 1 ? "" : "s"}`);
+    }
+    const isInfrastructure = rootModules.length > 0 || (files.length > 0 && (files.length >= 3 || hasRemoteBackend || hasProviderBlock || moduleDirectories.length > 0));
+    return {
+        isInfrastructure,
+        rootModules,
+        signals,
+        terraformFileCount: files.length,
+        hasRemoteBackend,
+        hasProviderBlock,
+        moduleDirectories,
+        ...detectCiSystem(dir),
+    };
+}
+/**
+ * The pipeline step to add, for whichever CI system the repo already uses.
+ * Onboarding hands this over rather than pointing at documentation: an
+ * ingestion command nobody wires up is a graph that lies within a week.
+ */
+export function ciSnippetFor(ciSystem, ciFile = null) {
+    if (ciSystem === "github") {
+        return {
+            file: ".github/workflows/terraform.yml (in the apply job)",
+            snippet: [
+                "      - name: Sync architecture graph",
+                "        run: |",
+                "          terraform show -json > tfstate.json",
+                "          npx nexarch@latest ingest-infra --state tfstate.json",
+                "        env:",
+                "          NEXARCH_TOKEN: ${{ secrets.NEXARCH_TOKEN }}",
+            ].join("\n"),
+        };
+    }
+    if (ciSystem === "azure-pipelines") {
+        return {
+            file: `${ciFile ?? "azure-pipelines.yml"} (after the apply step)`,
+            snippet: [
+                "  - script: |",
+                "      terraform show -json > tfstate.json",
+                "      npx nexarch@latest ingest-infra --state tfstate.json",
+                "    displayName: Sync architecture graph",
+                "    env:",
+                "      NEXARCH_TOKEN: $(NEXARCH_TOKEN)",
+            ].join("\n"),
+        };
+    }
+    if (ciSystem === "gitlab") {
+        return {
+            file: ciFile ?? ".gitlab-ci.yml",
+            snippet: [
+                "nexarch-ingest:",
+                "  stage: .post",
+                "  script:",
+                "    - terraform show -json > tfstate.json",
+                "    - npx nexarch@latest ingest-infra --state tfstate.json",
+                "  variables:",
+                "    NEXARCH_TOKEN: $NEXARCH_TOKEN",
+            ].join("\n"),
+        };
+    }
+    // Nothing was detected. Handing over a GitLab job here — the previous
+    // behaviour — states as fact something never observed, and a team on another
+    // CI system has to work out why the advice does not fit. The two commands are
+    // the part that is actually known; the wrapper is not.
+    return {
+        file: "your Terraform pipeline, after the apply step",
+        snippet: ["terraform show -json > tfstate.json", "npx nexarch@latest ingest-infra --state tfstate.json"].join("\n"),
+    };
+}