nexarch 0.12.16 → 0.12.19

package/dist/commands/ingest-infra.js

@@ -174,7 +174,13 @@ export function buildIngestPayload(params) {
             attributes: { source: "terraform_ingest", terraform_version: projection.terraformVersion },
         },
     ];
-    const relationships = [];
+    const relationships = [
+        // The environment lives on the platform. Without this edge the two nodes
+        // this payload always creates float beside each other, and no query can
+        // answer "which cloud is dev on" — every resource knows both, but the
+        // environment itself knows neither.
+        { relationshipTypeCode: "runs_on", fromEntityRef: environmentRef, toEntityRef: platformRef },
+    ];
     // Lookup tables for the topology pass below, populated alongside entities so
     // a single loop over projection.resources is enough for both.
     const entityRefByTypeAndName = new Map();
@@ -189,6 +195,7 @@ export function buildIngestPayload(params) {
     const identityEntityRefByName = new Map();
     const identityRefByPrincipalId = new Map();
     const catalogueByResourceType = new Map(catalogue.map((entry) => [entry.resourceType, entry]));
+    const canonicalTechnologies = new Set();
     for (const resource of projection.resources) {
         const entityRef = `${resource.entityTypeCode}:${slug(resource.name ?? resource.address)}`;
         entities.push({
@@ -219,6 +226,22 @@ export function buildIngestPayload(params) {
             relationships.push({ relationshipTypeCode: "runs_on", fromEntityRef: entityRef, toEntityRef: environmentRef });
             relationships.push({ relationshipTypeCode: "runs_on", fromEntityRef: entityRef, toEntityRef: platformRef });
         }
+        // What product is this? Without it the graph holds a resource that knows
+        // where it runs and whose cloud it is on, but not what it *is* — the only
+        // record of that being a raw `terraform_type` attribute, which no reader
+        // can join across environments or tenants. The canonical entry is shared
+        // vocabulary, so one query answers "everything we run on Azure AI
+        // Services" across every environment and every IaC tool.
+        const canonicalRef = catalogueByResourceType.get(resource.resourceType)?.canonicalEntityRef;
+        if (canonicalRef && !canonicalTechnologies.has(canonicalRef)) {
+            canonicalTechnologies.add(canonicalRef);
+        }
+        if (canonicalRef) {
+            // `instance_of`, not `runs_on`: this vault does not run on Azure Key
+            // Vault, it is one. runs_on is a hosting relation and is already covered
+            // above by the edges to the platform and the environment.
+            relationships.push({ relationshipTypeCode: "instance_of", fromEntityRef: entityRef, toEntityRef: canonicalRef });
+        }
         if (resource.name) {
             entityRefByTypeAndName.set(`${resource.resourceType}::${resource.name}`, entityRef);
             entityRefByName.set(resource.name, entityRef);
@@ -298,8 +321,38 @@ export function buildIngestPayload(params) {
                 addTopologyEdge("depends_on", entityRef, identityEntityRefByName.get(identityName));
         }
     }
+    // The canonical technologies referenced above, upserted so the edges have
+    // something to land on. Named from the ref rather than invented per tenant:
+    // these are shared vocabulary, and a tenant-local "Azure AI Services" that
+    // differs by a word defeats the point of having a canonical entry at all.
+    for (const canonicalRef of canonicalTechnologies) {
+        const canonicalTypeCode = canonicalRef.split(":")[1] ?? "platform_component";
+        entities.push({
+            entityRef: canonicalRef,
+            entityTypeCode: canonicalTypeCode,
+            name: canonicalTechnologyName(canonicalRef),
+            description: "Cloud service referenced by infrastructure ingestion.",
+            attributes: { source: "terraform_ingest", canonical: true },
+        });
+        // A managed service belongs to the cloud that offers it. Only from a
+        // platform_component: part_of does not accept a technology_component
+        // source, so a canonical that is one is left unattached rather than sent
+        // to fail governance.
+        if (canonicalTypeCode === "platform_component") {
+            relationships.push({ relationshipTypeCode: "part_of", fromEntityRef: canonicalRef, toEntityRef: platformRef });
+        }
+    }
     return { entities, relationships, environmentRef };
 }
+/** Turns global:platform_component:azure_ai_services into "Azure AI Services". */
+function canonicalTechnologyName(canonicalRef) {
+    const slugPart = canonicalRef.split(":").slice(2).join(":") || canonicalRef;
+    return slugPart
+        .split("_")
+        .filter(Boolean)
+        .map((word) => (word.length <= 3 && word === word.toLowerCase() && ["ai", "api", "dns", "sql", "cdn"].includes(word) ? word.toUpperCase() : word[0].toUpperCase() + word.slice(1)))
+        .join(" ");
+}
 function chunk(items, size) {
     const out = [];
     for (let i = 0; i < items.length; i += size)
@@ -338,6 +391,22 @@ export async function ingestInfra(args) {
             `    4. if this repository has several root modules, ingest each separately with --dir\n` +
             `  The estate may also simply not have been applied yet.`);
     }
+    // Nothing recognised is a coverage problem, and has to be said before the
+    // environment is even considered. Otherwise a root whose every resource type
+    // is missing from the catalogue fails with "could not determine the
+    // environment — 0 of those carried any tags", which sends the reader off to
+    // tag resources that would still not be ingested afterwards. The environment
+    // is the next question only once there is something to attach it to.
+    if (projection.stats.resourcesProjected === 0) {
+        const seen = projection.unknownTypes
+            .slice(0, 12)
+            .map((entry) => `    ${String(entry.count).padStart(3)}  ${entry.resourceType}`)
+            .join("\n");
+        throw new Error(`Nothing in this root module is in the catalogue yet — read ${projection.stats.resourcesSeen} resources, matched none.\n` +
+            `  Tagging or naming an environment will not help: there would still be nothing to ingest.\n` +
+            `\n  Resource types found here:\n${seen}\n` +
+            `\n  These need adding to the platform catalogue before this root can be ingested.`);
+    }
     const { environment, how } = resolveEnvironment(projection, environmentOverride, workingDir, statePath ? null : workingDir);
     projection.environment = environment;
     // Azure is the only provider the seed catalogue covers today; resolving it
@@ -359,6 +428,26 @@ export async function ingestInfra(args) {
             // Reference resolution is an optimisation, not a requirement.
         }
     }
+    // Types the catalogue does not cover are filed as reference candidates, the
+    // same way an unrecognised package name is. Printing them to a console nobody
+    // aggregates meant the platform could never learn which services customers
+    // actually run: curation happened when someone happened to notice. A resource
+    // type is vendor vocabulary — `azurerm_static_web_app` contains nothing of the
+    // tenant's — so it is safe to file in a cross-tenant queue, where seen_count
+    // accumulates the evidence for covering it.
+    //
+    // Resolving doubles as filing: a type someone has already promoted comes back
+    // resolved, and only genuine misses become candidates.
+    if (!dryRun && projection.unknownTypes.length > 0) {
+        try {
+            await callMcpTool("nexarch_resolve_reference", {
+                names: projection.unknownTypes.slice(0, 200).map((entry) => entry.resourceType),
+            });
+        }
+        catch {
+            // Coverage reporting must never fail an ingest: the estate is the point.
+        }
+    }
     const { entities, relationships } = buildIngestPayload({ projection, environment, platformRef, platformName, catalogue });
     const report = {
         ok: true,

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

@@ -12,7 +12,7 @@
  * ahead of it: editing it by hand recreates the two-sources-of-truth problem
  * moving the catalogue out of the CLI was meant to end.
  *
- * 25 entries, exported 2026-08-21.
+ * 30 entries, exported 2026-08-21.
  */
 export const IAC_CATALOGUE_SEED = [
     {
@@ -22,6 +22,7 @@ export const IAC_CATALOGUE_SEED = [
         role: "compute_environment",
         attributes: ["name", "location", "resource_group_name", "default_domain", "infrastructure_subnet_id", "internal_load_balancer_enabled", "static_ip_address", "zone_redundancy_enabled"],
         references: { "infrastructure_subnet_id": "azurerm_subnet" },
+        canonicalEntityRef: "global:platform_component:azure_container_apps",
         cloudResourceType: "Microsoft.App/managedEnvironments",
     },
     {
@@ -30,6 +31,7 @@ export const IAC_CATALOGUE_SEED = [
         entitySubtypeCode: "platform_runtime",
         role: "compute_environment",
         attributes: ["name", "location", "resource_group_name", "sku_name", "os_type", "worker_count"],
+        canonicalEntityRef: "global:platform_component:azure_app_service",
         cloudResourceType: "Microsoft.Web/serverfarms",
     },
     {
@@ -38,6 +40,7 @@ export const IAC_CATALOGUE_SEED = [
         entitySubtypeCode: "platform_service",
         role: "compute_host",
         attributes: ["name", "location", "resource_group_name", "kind", "sku_name", "endpoint", "custom_subdomain_name", "public_network_access_enabled", "local_auth_enabled"],
+        canonicalEntityRef: "global:platform_component:azure_ai_services",
         cloudResourceType: "Microsoft.CognitiveServices/accounts",
     },
     {
@@ -48,6 +51,7 @@ export const IAC_CATALOGUE_SEED = [
         bindable: true,
         attributes: ["name", "location", "resource_group_name", "container_app_environment_id", "revision_mode", "workload_profile_name"],
         references: { "container_app_environment_id": "azurerm_container_app_environment" },
+        canonicalEntityRef: "global:platform_component:azure_container_apps",
         cloudResourceType: "Microsoft.App/containerApps",
     },
     {
@@ -58,6 +62,7 @@ export const IAC_CATALOGUE_SEED = [
         bindable: true,
         attributes: ["name", "location", "resource_group_name", "container_app_environment_id", "replica_timeout_in_seconds", "workload_profile_name"],
         references: { "container_app_environment_id": "azurerm_container_app_environment" },
+        canonicalEntityRef: "global:platform_component:azure_container_apps",
         cloudResourceType: "Microsoft.App/jobs",
     },
     {
@@ -68,14 +73,26 @@ export const IAC_CATALOGUE_SEED = [
         bindable: true,
         attributes: ["name", "location", "resource_group_name", "service_plan_id", "https_only", "default_hostname"],
         references: { "service_plan_id": "azurerm_service_plan" },
+        canonicalEntityRef: "global:platform_component:azure_app_service",
         cloudResourceType: "Microsoft.Web/sites",
     },
+    {
+        resourceType: "azurerm_static_web_app",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "compute_host",
+        bindable: true,
+        attributes: ["name", "location", "resource_group_name", "default_host_name", "sku_tier", "sku_size", "public_network_access_enabled", "preview_environments_enabled", "repository_url"],
+        canonicalEntityRef: "global:platform_component:azure_static_web_apps",
+        cloudResourceType: "Microsoft.Web/staticSites",
+    },
     {
         resourceType: "azurerm_cosmosdb_account",
         entityTypeCode: "data_store",
         entitySubtypeCode: "store_document",
         role: "data_store",
         attributes: ["name", "location", "resource_group_name", "kind", "offer_type", "public_network_access_enabled", "endpoint"],
+        canonicalEntityRef: "global:platform_component:azure_cosmos_db",
         cloudResourceType: "Microsoft.DocumentDB/databaseAccounts",
     },
     {
@@ -84,6 +101,7 @@ export const IAC_CATALOGUE_SEED = [
         entitySubtypeCode: "store_relational",
         role: "data_store",
         attributes: ["name", "location", "resource_group_name", "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"],
+        canonicalEntityRef: "global:platform_component:azure_database_for_postgresql",
         cloudResourceType: "Microsoft.DBforPostgreSQL/flexibleServers",
     },
     {
@@ -92,6 +110,7 @@ export const IAC_CATALOGUE_SEED = [
         entitySubtypeCode: "store_relational",
         role: "data_store",
         attributes: ["name", "server_id", "charset", "collation"],
+        canonicalEntityRef: "global:platform_component:azure_database_for_postgresql",
         cloudResourceType: "Microsoft.DBforPostgreSQL/flexibleServers/databases",
     },
     {
@@ -100,6 +119,7 @@ export const IAC_CATALOGUE_SEED = [
         entitySubtypeCode: "store_object",
         role: "data_store",
         attributes: ["name", "location", "resource_group_name", "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"],
+        canonicalEntityRef: "global:platform_component:azure_storage",
         cloudResourceType: "Microsoft.Storage/storageAccounts",
     },
     {
@@ -108,6 +128,7 @@ export const IAC_CATALOGUE_SEED = [
         entitySubtypeCode: "store_object",
         role: "data_store",
         attributes: ["name", "container_access_type", "storage_account_id", "has_immutability_policy"],
+        canonicalEntityRef: "global:platform_component:azure_storage",
         cloudResourceType: "Microsoft.Storage/storageAccounts/blobServices/containers",
     },
     {
@@ -117,6 +138,7 @@ export const IAC_CATALOGUE_SEED = [
         role: "edge",
         attributes: ["name", "host_name", "enabled", "cdn_frontdoor_profile_id"],
         references: { "cdn_frontdoor_profile_id": "azurerm_cdn_frontdoor_profile" },
+        canonicalEntityRef: "global:platform_component:azure_front_door",
         cloudResourceType: "Microsoft.Cdn/profiles/afdEndpoints",
     },
     {
@@ -124,6 +146,7 @@ export const IAC_CATALOGUE_SEED = [
         entityTypeCode: "policy_control",
         role: "edge",
         attributes: ["name", "location", "resource_group_name", "sku_name", "mode", "enabled"],
+        canonicalEntityRef: "global:platform_component:azure_web_application_firewall",
         cloudResourceType: "Microsoft.Network/frontDoorWebApplicationFirewallPolicies",
     },
     {
@@ -132,13 +155,44 @@ export const IAC_CATALOGUE_SEED = [
         entitySubtypeCode: "platform_service",
         role: "edge",
         attributes: ["name", "location", "resource_group_name", "sku_name", "response_timeout_seconds"],
+        canonicalEntityRef: "global:platform_component:azure_front_door",
         cloudResourceType: "Microsoft.Cdn/profiles",
     },
+    {
+        resourceType: "azurerm_static_web_app_custom_domain",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "edge",
+        attributes: ["domain_name", "validation_type"],
+        references: { "static_web_app_id": "azurerm_static_web_app" },
+        canonicalEntityRef: "global:platform_component:azure_static_web_apps",
+        cloudResourceType: "Microsoft.Web/staticSites/customDomains",
+    },
+    {
+        resourceType: "azurerm_traffic_manager_external_endpoint",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "edge",
+        attributes: ["name", "target", "endpoint_location", "enabled", "priority", "weight", "always_serve_enabled"],
+        references: { "profile_id": "azurerm_traffic_manager_profile" },
+        canonicalEntityRef: "global:platform_component:azure_traffic_manager",
+        cloudResourceType: "Microsoft.Network/trafficManagerProfiles/externalEndpoints",
+    },
+    {
+        resourceType: "azurerm_traffic_manager_profile",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "edge",
+        attributes: ["name", "resource_group_name", "fqdn", "traffic_routing_method", "profile_status", "traffic_view_enabled", "max_return"],
+        canonicalEntityRef: "global:platform_component:azure_traffic_manager",
+        cloudResourceType: "Microsoft.Network/trafficManagerProfiles",
+    },
     {
         resourceType: "azurerm_role_assignment",
         entityTypeCode: "policy_control",
         role: "identity",
         attributes: ["name", "principal_id", "principal_type", "role_definition_name", "scope"],
+        canonicalEntityRef: "global:platform_component:azure_rbac",
         cloudResourceType: "Microsoft.Authorization/roleAssignments",
     },
     {
@@ -147,6 +201,7 @@ export const IAC_CATALOGUE_SEED = [
         entitySubtypeCode: "platform_control_plane",
         role: "identity",
         attributes: ["name", "location", "resource_group_name", "client_id", "principal_id", "tenant_id"],
+        canonicalEntityRef: "global:platform_component:azure_managed_identity",
         cloudResourceType: "Microsoft.ManagedIdentity/userAssignedIdentities",
     },
     {
@@ -155,6 +210,7 @@ export const IAC_CATALOGUE_SEED = [
         entitySubtypeCode: "platform_service",
         role: "messaging",
         attributes: ["name", "location", "resource_group_name", "sku", "public_network_access_enabled"],
+        canonicalEntityRef: "global:platform_component:azure_service_bus",
         cloudResourceType: "Microsoft.ServiceBus/namespaces",
     },
     {
@@ -164,6 +220,7 @@ export const IAC_CATALOGUE_SEED = [
         role: "messaging",
         attributes: ["name", "namespace_id", "max_delivery_count", "requires_session"],
         references: { "namespace_id": "azurerm_servicebus_namespace" },
+        canonicalEntityRef: "global:platform_component:azure_service_bus",
         cloudResourceType: "Microsoft.ServiceBus/namespaces/queues",
     },
     {
@@ -172,6 +229,7 @@ export const IAC_CATALOGUE_SEED = [
         entitySubtypeCode: "platform_service",
         role: "network_boundary",
         attributes: ["name", "resource_group_name", "number_of_record_sets"],
+        canonicalEntityRef: "global:platform_component:azure_private_dns",
         cloudResourceType: "Microsoft.Network/privateDnsZones",
     },
     {
@@ -181,6 +239,7 @@ export const IAC_CATALOGUE_SEED = [
         role: "network_boundary",
         attributes: ["name", "location", "resource_group_name", "subnet_id"],
         references: { "subnet_id": "azurerm_subnet" },
+        canonicalEntityRef: "global:platform_component:azure_private_link",
         cloudResourceType: "Microsoft.Network/privateEndpoints",
     },
     {
@@ -190,6 +249,7 @@ export const IAC_CATALOGUE_SEED = [
         role: "network_boundary",
         attributes: ["name", "resource_group_name", "virtual_network_name", "address_prefixes", "default_outbound_access_enabled", "private_endpoint_network_policies"],
         nameReferences: { "virtual_network_name": "azurerm_virtual_network" },
+        canonicalEntityRef: "global:platform_component:azure_virtual_network",
         cloudResourceType: "Microsoft.Network/virtualNetworks/subnets",
     },
     {
@@ -198,6 +258,7 @@ export const IAC_CATALOGUE_SEED = [
         entitySubtypeCode: "platform_service",
         role: "network_boundary",
         attributes: ["name", "location", "resource_group_name", "address_space", "guid"],
+        canonicalEntityRef: "global:platform_component:azure_virtual_network",
         cloudResourceType: "Microsoft.Network/virtualNetworks",
     },
     {
@@ -206,6 +267,7 @@ export const IAC_CATALOGUE_SEED = [
         entitySubtypeCode: "platform_service",
         role: "observability",
         attributes: ["name", "location", "resource_group_name", "sku", "retention_in_days", "workspace_id"],
+        canonicalEntityRef: "global:platform_component:azure_monitor",
         cloudResourceType: "Microsoft.OperationalInsights/workspaces",
     },
     {
@@ -214,14 +276,25 @@ export const IAC_CATALOGUE_SEED = [
         entitySubtypeCode: "platform_service",
         role: "registry",
         attributes: ["name", "location", "resource_group_name", "login_server", "sku", "admin_enabled", "public_network_access_enabled"],
+        canonicalEntityRef: "global:platform_component:azure_container_registry",
         cloudResourceType: "Microsoft.ContainerRegistry/registries",
     },
+    {
+        resourceType: "azurerm_resource_group",
+        entityTypeCode: "platform_component",
+        entitySubtypeCode: "platform_service",
+        role: "resource_group",
+        attributes: ["name", "location"],
+        canonicalEntityRef: "global:platform_component:azure_resource_group",
+        cloudResourceType: "Microsoft.Resources/resourceGroups",
+    },
     {
         resourceType: "azurerm_key_vault",
         entityTypeCode: "platform_component",
         entitySubtypeCode: "platform_service",
         role: "secret_store",
         attributes: ["name", "location", "resource_group_name", "vault_uri", "sku_name", "enable_rbac_authorization", "rbac_authorization_enabled", "public_network_access_enabled", "purge_protection_enabled", "soft_delete_retention_days"],
+        canonicalEntityRef: "global:platform_component:azure_key_vault",
         cloudResourceType: "Microsoft.KeyVault/vaults",
     },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.12.16",
+  "version": "0.12.19",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",