nexarch 0.13.0 → 0.13.2

package/dist/lib/ansible-detect.js

@@ -0,0 +1,109 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join, relative, sep } from "path";
+import { environmentFromPath } from "./iac-detect.js";
+const SCAN_DEPTH = 8;
+const IGNORED = new Set([".git", "node_modules", ".venv", "venv", "dist", "build", ".next"]);
+const YAML = /\.ya?ml$/i;
+function walk(dir, depth = 0, files = []) {
+    if (depth > SCAN_DEPTH)
+        return files;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries) {
+        if (IGNORED.has(entry))
+            continue;
+        const full = join(dir, entry);
+        try {
+            if (statSync(full).isDirectory())
+                walk(full, depth + 1, files);
+            else
+                files.push(full);
+        }
+        catch { /* unreadable paths are not evidence */ }
+    }
+    return files;
+}
+function hasPlaybookShape(file) {
+    if (!YAML.test(file))
+        return false;
+    try {
+        const text = readFileSync(file, "utf8");
+        return /^\s*-?\s*hosts\s*:/m.test(text) && /^\s*(tasks|roles|pre_tasks|post_tasks|handlers)\s*:/m.test(text);
+    }
+    catch {
+        return false;
+    }
+}
+function normalise(repoDir, file) {
+    return relative(repoDir, file).split(sep).join("/");
+}
+/**
+ * The environment an inventory is for, from its path.
+ *
+ * Terraform gets this from a root module directory or a workspace. Ansible has
+ * neither, and this is the gap the plan called out as the hard part: the
+ * environment lives in how the inventory is filed. `inventories/production/hosts`
+ * and `inventory/prod.ini` both say it plainly, so the filename is consulted as
+ * well as the directories -- which is where `environmentFromPath` alone stops,
+ * since a Terraform root module is always a directory.
+ *
+ * The vocabulary is deliberately shared with `environmentFromPath` rather than
+ * copied: two lists of environment names drift, and then the same repository
+ * reports different environments depending on which tool read it.
+ */
+export function environmentFromInventoryPath(relativePath) {
+    const fromDirectories = environmentFromPath(relativePath);
+    if (fromDirectories)
+        return fromDirectories;
+    const base = (relativePath.split("/").at(-1) ?? "").replace(/\.(ini|ya?ml|json)$/i, "");
+    return base ? environmentFromPath(base) : null;
+}
+/**
+ * Detects Ansible from corroborating repository evidence.
+ *
+ * A YAML file containing `hosts:` is not enough: application configuration
+ * regularly has the same vocabulary. Like IaC detection, a playbook needs a
+ * second operational signal (inventory, roles, configuration, or collection)
+ * before it can change onboarding behaviour.
+ */
+export function detectAnsibleProject(repoDir) {
+    const files = walk(repoDir);
+    const relativeFiles = files.map((file) => normalise(repoDir, file));
+    const playbookFiles = files.filter(hasPlaybookShape).map((file) => normalise(repoDir, file)).sort();
+    const inventoryFiles = relativeFiles.filter((file) => {
+        const base = file.split("/").at(-1) ?? "";
+        return /(^|\/)(inventory|inventories)(\/|$)/i.test(file) || /^(hosts|inventory)(\.ini|\.ya?ml)?$/i.test(base);
+    }).sort();
+    const roleDirectories = relativeFiles
+        .filter((file) => /(^|\/)roles\/[^/]+\/(tasks|handlers|defaults|vars)\/main\.ya?ml$/i.test(file))
+        .map((file) => file.replace(/\/(tasks|handlers|defaults|vars)\/main\.ya?ml$/i, ""))
+        .filter((value, index, values) => values.indexOf(value) === index)
+        .sort();
+    const collectionDirectories = relativeFiles
+        .filter((file) => /(^|\/)collections\/requirements\.ya?ml$/i.test(file) || /(^|\/)galaxy\.ya?ml$/i.test(file))
+        .map((file) => file.replace(/\/(requirements|galaxy)\.ya?ml$/i, ""))
+        .filter((value, index, values) => values.indexOf(value) === index)
+        .sort();
+    const hasConfig = existsSync(join(repoDir, "ansible.cfg"));
+    const signals = [];
+    if (playbookFiles.length)
+        signals.push(`${playbookFiles.length} playbook${playbookFiles.length === 1 ? "" : "s"}`);
+    if (inventoryFiles.length)
+        signals.push(`${inventoryFiles.length} inventory file${inventoryFiles.length === 1 ? "" : "s"}`);
+    if (roleDirectories.length)
+        signals.push(`${roleDirectories.length} role${roleDirectories.length === 1 ? "" : "s"}`);
+    if (collectionDirectories.length)
+        signals.push(`${collectionDirectories.length} collection declaration${collectionDirectories.length === 1 ? "" : "s"}`);
+    if (hasConfig)
+        signals.push("ansible.cfg");
+    const environments = [...new Set(inventoryFiles.map(environmentFromInventoryPath).filter((e) => Boolean(e)))].sort();
+    if (environments.length)
+        signals.push(`environments: ${environments.join(", ")}`);
+    const corroborated = inventoryFiles.length > 0 || roleDirectories.length > 0 || collectionDirectories.length > 0 || hasConfig;
+    return { isAnsible: playbookFiles.length > 0 && corroborated, signals, playbookFiles, inventoryFiles, environments, roleDirectories, collectionDirectories };
+}

package/dist/lib/ansible-projection.js

@@ -0,0 +1,150 @@
+import { parse } from "yaml";
+export const DEFAULT_ANSIBLE_HOST_MAPPING = {
+    entityTypeCode: "platform_component",
+    entitySubtypeCode: null,
+    role: "compute_host",
+    resourceType: "ansible_host",
+};
+/** Ansible's own bookkeeping groups: every host is in them, so they classify nothing. */
+const BOOKKEEPING_GROUPS = new Set(["all", "ungrouped"]);
+function hostNamesOf(raw) {
+    const hosts = raw.hosts;
+    const names = Array.isArray(hosts) ? hosts : hosts && typeof hosts === "object" ? Object.keys(hosts) : [];
+    return names.filter((name) => typeof name === "string" && Boolean(name.trim()));
+}
+function childNamesOf(raw) {
+    const children = raw.children;
+    const names = Array.isArray(children) ? children : children && typeof children === "object" ? Object.keys(children) : [];
+    return names.filter((name) => typeof name === "string" && Boolean(name.trim()));
+}
+/**
+ * Resolves group membership, following `children`.
+ *
+ * Nested groups are how real inventories express environment: `prod` holds no
+ * hosts of its own, only `children: [web, db]`. Reading `hosts` alone gives a
+ * host the group it was listed under and loses every ancestor -- which is to
+ * say, it loses the environment, the one thing the group tree is usually for.
+ *
+ * Shared by both parsers on purpose. JSON and INI express the same tree in
+ * different syntax, and resolving it twice is how the two formats come to
+ * disagree about the same estate.
+ *
+ * The seen set is against cycles, which Ansible rejects at runtime but which
+ * can sit in a file and must not hang the scan.
+ */
+function resolveMemberships(tree) {
+    const hostsUnder = (group, seen = new Set()) => {
+        if (seen.has(group))
+            return [];
+        seen.add(group);
+        return [
+            ...(tree.hosts.get(group) ?? []),
+            ...(tree.children.get(group) ?? []).flatMap((child) => hostsUnder(child, seen)),
+        ];
+    };
+    const memberships = new Map();
+    for (const group of new Set([...tree.hosts.keys(), ...tree.children.keys()])) {
+        for (const name of hostsUnder(group)) {
+            const memberOf = memberships.get(name) ?? new Set();
+            if (!BOOKKEEPING_GROUPS.has(group))
+                memberOf.add(group);
+            memberships.set(name, memberOf);
+        }
+    }
+    return [...memberships.entries()]
+        .map(([name, groups]) => ({ name, groups: [...groups].sort() }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function groupsFromObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return [];
+    const tree = { hosts: new Map(), children: new Map() };
+    for (const [group, raw] of Object.entries(value)) {
+        if (group === "_meta" || !raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        tree.hosts.set(group, hostNamesOf(raw));
+        tree.children.set(group, childNamesOf(raw));
+    }
+    return resolveMemberships(tree);
+}
+function parseIni(text) {
+    const tree = { hosts: new Map(), children: new Map() };
+    let group = "ungrouped";
+    // "hosts", "children" or "vars" — an INI section header says which, and a
+    // `:children` section is the nesting the JSON form spells as `children`.
+    let section = "hosts";
+    const push = (map, key, value) => {
+        map.set(key, [...(map.get(key) ?? []), value]);
+    };
+    for (const line of text.split(/\r?\n/)) {
+        const clean = line.replace(/\s[;#].*$/, "").trim();
+        const header = clean.match(/^\[([^\]]+)\]$/);
+        if (header) {
+            const suffix = /:(children|vars)$/.exec(header[1])?.[1];
+            section = suffix === "children" ? "children" : suffix === "vars" ? "vars" : "hosts";
+            group = header[1].replace(/:(children|vars)$/, "");
+            continue;
+        }
+        if (!clean || section === "vars" || clean.startsWith("#") || clean.startsWith(";"))
+            continue;
+        // `web-01 ansible_host=10.0.0.5` is an ordinary host line: inline variables
+        // are how INI inventories are usually written. Skipping every line
+        // containing `=` dropped exactly those hosts, which is most of them. The
+        // `:vars` section is already excluded above, so the only thing that rule
+        // caught was the common case.
+        const name = clean.split(/\s+/)[0];
+        if (!name || name.includes("=") || name.includes(":"))
+            continue;
+        push(section === "children" ? tree.children : tree.hosts, group, name);
+    }
+    return resolveMemberships(tree);
+}
+/** Parses `ansible-inventory --list --export` JSON/YAML, or a conventional INI inventory. */
+export function parseAnsibleInventory(input) {
+    if (input && typeof input === "object")
+        return { hosts: groupsFromObject(input) };
+    const text = input.trim();
+    if (!text)
+        return { hosts: [] };
+    // `{` only. An INI inventory conventionally opens with a group header, so
+    // treating a leading `[` as JSON sent every one of them to JSON.parse and
+    // threw on the most common inventory format there is. A JSON array is not
+    // valid `ansible-inventory --list` output anyway.
+    if (text.startsWith("{"))
+        return { hosts: groupsFromObject(JSON.parse(text)) };
+    if (/^\s*\w[\w-]*\s*:/m.test(text) && !/^\s*\[/m.test(text))
+        return { hosts: groupsFromObject(parse(text)) };
+    return { hosts: parseIni(text) };
+}
+/**
+ * Projects only inventory identity and group membership. In particular,
+ * `_meta.hostvars`, inline `ansible_*` variables, vault values, and connection
+ * settings are intentionally not present in either attributes or tags.
+ */
+export function projectAnsibleInventory(params) {
+    const mapping = params.mapping ?? DEFAULT_ANSIBLE_HOST_MAPPING;
+    const resources = params.inventory.hosts.map((host) => ({
+        address: `ansible:${host.name}`,
+        resourceType: mapping.resourceType,
+        entityTypeCode: mapping.entityTypeCode,
+        entitySubtypeCode: mapping.entitySubtypeCode ?? null,
+        role: mapping.role,
+        // Not "managed". Ansible configures hosts that already exist -- the
+        // inventory is a list of machines someone else provisioned. Recording them
+        // as managed would have the graph claim we created a server we only
+        // installed packages on, and `IacTool.provisions` exists to carry exactly
+        // this distinction.
+        mode: "declared",
+        name: host.name,
+        attributes: { inventory_hostname: host.name, ansible_groups: [...host.groups].sort() },
+        tags: {},
+        identityIds: [],
+    }));
+    return {
+        environment: params.environment,
+        iacToolVersion: null,
+        resources,
+        unknownTypes: [],
+        stats: { resourcesSeen: resources.length, resourcesProjected: resources.length, attributesDroppedNotAllowlisted: 0, attributesDroppedSensitive: 0 },
+    };
+}

package/dist/lib/iac-detect.js

@@ -0,0 +1,414 @@
+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"]);
+/**
+ * Path segments whose contents demonstrate Terraform rather than run it.
+ *
+ * An `examples/complete` directory configures a provider and looks exactly like
+ * an estate root by every local signal — which is why terraform-aws-vpc
+ * reported thirteen of them as environments while missing the modules that are
+ * the point of the repository. Worse than missing the real architecture: the
+ * examples are mutually exclusive demonstrations, so graphing them together
+ * describes an estate that has never existed anywhere.
+ */
+const NON_ESTATE_SEGMENT = /(^|[\\/])(examples?|docs?|test|tests|fixtures?|testdata|_example|sample|samples)([\\/]|$)/i;
+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;
+}
+/**
+ * Recognises a repository that publishes reusable modules rather than running an estate.
+ *
+ * The Terraform registry convention is a module at the repository root —
+ * `main.tf` with `variables.tf` and `outputs.tf` beside it — deliberately
+ * configuring no provider and no backend, because both are supplied by whoever
+ * calls it. Every signal that identifies an estate is therefore absent by
+ * design, and the signals that *are* present belong to the examples directory.
+ *
+ * This matters more than tidiness. terraform-aws-vpc has no estate to ingest:
+ * asking it for one and getting thirteen mutually exclusive demonstrations is
+ * worse than getting nothing, because nothing is honest.
+ */
+function detectPublishedModules(dir) {
+    const rootFiles = (() => {
+        try {
+            return readdirSync(dir);
+        }
+        catch {
+            return [];
+        }
+    })();
+    const hasRootModule = rootFiles.includes("variables.tf") && rootFiles.includes("outputs.tf") && rootFiles.some((f) => f.endsWith(".tf") && f !== "variables.tf" && f !== "outputs.tf");
+    const modules = [];
+    const modulesDir = join(dir, "modules");
+    try {
+        for (const child of readdirSync(modulesDir)) {
+            const full = join(modulesDir, child);
+            if (statSync(full).isDirectory() && readdirSync(full).some((f) => f.endsWith(".tf")))
+                modules.push(child);
+        }
+    }
+    catch {
+        // No modules directory; a single-module repository is still a library.
+    }
+    return { isLibrary: hasRootModule, modules: modules.sort() };
+}
+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);
+        const isDemonstration = NON_ESTATE_SEGMENT.test(relative);
+        if (tfFiles.length > 0 && !isUnderModules && !isDemonstration) {
+            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;
+            }
+            // A `.terraform` directory only proves provider plugins were downloaded.
+            // The backend — the thing `terraform show` needs — is initialised when
+            // `.terraform/terraform.tfstate` records its configuration. Treating the
+            // directory as proof reports a root as ready, the caller runs ingest, and
+            // Terraform answers "Backend initialization required" from somewhere the
+            // caller was told not to expect it.
+            const hasPluginDir = existsSync(join(dir, ".terraform"));
+            const initialised = existsSync(join(dir, ".terraform", "terraform.tfstate"));
+            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");
+            else if (hasPluginDir)
+                signals.push("providers downloaded, backend not initialised");
+            if (hasTfvars)
+                signals.push("tfvars");
+            if (underStacksDir)
+                signals.push("stacks directory");
+            // A provider block alone no longer qualifies. It is the one signal an
+            // example shares with a real estate, and treating it as sufficient is
+            // what let demonstration fixtures in. What distinguishes an estate is
+            // evidence that state exists or is configured somewhere: a backend, an
+            // initialised working directory, or a conventional stacks layout.
+            const isEstateRoot = hasBackend || initialised || hasPluginDir || (underStacksDir && (hasTfvars || Boolean(environmentHint)));
+            if (isEstateRoot) {
+                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 library = detectPublishedModules(dir);
+    // An estate is claimed only by root modules that survived the tightened
+    // acceptance above. A repository with a root module and no estate roots is
+    // publishing modules, not running anything.
+    const repoKind = rootModules.length > 0 ? "estate" : library.isLibrary ? "module_library" : "unknown";
+    if (repoKind === "module_library") {
+        signals.push(library.modules.length > 0 ? `publishes ${library.modules.length + 1} modules` : "publishes a reusable module");
+    }
+    const isInfrastructure = rootModules.length > 0 ||
+        repoKind === "module_library" ||
+        (files.length > 0 && (files.length >= 3 || hasRemoteBackend || hasProviderBlock || moduleDirectories.length > 0));
+    return {
+        isInfrastructure,
+        rootModules,
+        signals,
+        iacFileCount: files.length,
+        hasRemoteBackend,
+        hasProviderBlock,
+        moduleDirectories,
+        repoKind,
+        publishedModules: repoKind === "module_library" ? library.modules : [],
+        ...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, executable = "terraform") {
+    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 IaC pipeline, after the apply step",
+        snippet: [`${executable} show -json > tfstate.json`, "npx nexarch@latest ingest-infra --state tfstate.json"].join("\n"),
+    };
+}