@intentius/chant 0.124.13 → 0.124.15

package/dist/audit/discover.js

@@ -0,0 +1,633 @@
+/**
+ * Unified, detectTemplate-driven discovery (prototype for #391).
+ *
+ * Today `commands/audit.ts` ships six bespoke discoverers — `discoverManifests`,
+ * `discoverGcp`, `discoverCloudFormation`, `discoverArm`, `discoverDocker`,
+ * `discoverHelm` — each walking the tree and re-implementing a `looksLike*`
+ * content heuristic that mostly duplicates the lexicon plugin's own
+ * `detectTemplate(parsed)` (already used by `chant import`).
+ *
+ * This module collapses that into ONE walk plus a single content-detection
+ * pass that delegates to each plugin's `detectTemplate`. A new content-detected
+ * lexicon then needs only a `detectTemplate` and a precedence entry — no new
+ * walk, no new heuristic.
+ *
+ * It is deliberately a HYBRID, because some classification can't be expressed
+ * by content shape alone:
+ *   - CI (github/forgejo/gitlab) stays a PATH fast-path. github and forgejo
+ *     workflows are byte-for-byte the same shape (`on:` + `jobs:`), so only the
+ *     directory (`.github` vs `.forgejo`) disambiguates them.
+ *   - Dockerfiles are matched by FILENAME — they aren't YAML/JSON, so
+ *     `detectTemplate` (which only knows Compose's `services:`) can't see them.
+ *   - Helm charts are a directory BUNDLE keyed by `Chart.yaml`; the helm checks
+ *     read `output.files`, so the whole chart is one AuditInput.
+ *   - Terraform is also a directory BUNDLE, keyed by that directory's own
+ *     `.tf` filenames, not recursively: a nested directory with its own
+ *     `.tf` files (e.g. `modules/foo`) is its own AuditInput, UNLESS another
+ *     directory's `.tf` calls it as a local module, in which case it is a
+ *     child module of that root and is parsed as part of it (#2217). `.tf`
+ *     isn't YAML/JSON either, so `detectTemplate` can't see it.
+ *   - k8s `detectTemplate` matches any `apiVersion`+`kind`, including GCP Config
+ *     Connector (`cnrm.cloud.google.com`) resources and fountain
+ *     (`fountain.dev/v1`) manifests, so gcp and fountain must be tried first.
+ *   - aws/azure checks `JSON.parse` their input, so YAML/templated content is
+ *     normalized to a JSON string here.
+ */
+import { readFileSync, statSync } from "fs";
+import { basename, join, relative, resolve } from "path";
+import { parseYAML } from "../yaml.js";
+import { isNginxConfigPath } from "./nginx.js";
+import { walkDiscovery } from "../discovery/walk.js";
+import { findProjectConfig } from "../project-root.js";
+import { gitignoreCoversTerraformState, isTerraformStatePath, nestedGitignoreCovering } from "./terraform-state.js";
+/** Lexicons the auditor knows how to detect and run checks for. */
+export const AUDIT_LEXICONS = ["github", "gitlab", "forgejo", "k8s", "docker", "aws", "azure", "gcp", "helm", "fountain", "terraform"];
+/**
+ * Load the plugins used for detection. Each is loaded in isolation (no
+ * cross-lexicon conflict aggregation — detection only reads `detectTemplate`),
+ * and a lexicon that isn't installed is skipped rather than failing the audit.
+ * `init()` is intentionally not called: `detectTemplate` is a pure function of
+ * its input and needs no plugin setup.
+ */
+export async function loadAuditPlugins(names = AUDIT_LEXICONS) {
+    // Lazy import: a top-level `cli/plugins` import would pull the root barrel
+    // (index.ts -> lint/parser -> the TypeScript compiler) into anyone importing
+    // `classifyFiles`, crashing edge runtimes. Edge callers build detectors from
+    // static `detect` imports and never call this. See #408/#426.
+    const { loadPlugin } = await import("../cli/plugins.js");
+    const plugins = [];
+    for (const name of names) {
+        try {
+            plugins.push(await loadPlugin(name));
+        }
+        catch {
+            // lexicon package not installed — its files simply won't be detected
+        }
+    }
+    return plugins;
+}
+/** Terraform's local working directory: recorded by the walk, never entered (TF023). */
+const TERRAFORM_WORK_DIR = ".terraform";
+/**
+ * How many files the local walk takes before it stops. Every file it reaches
+ * counts, candidate or not, so a tree with a large `docs/` or `assets/` can hit
+ * it long before a thousand auditable files. `--max-files` raises it (#2528).
+ */
+export const DEFAULT_MAX_WALK_FILES = 1000;
+/** Skip absurdly large files before parsing — mirrors the fetch layer's caps. */
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+/**
+ * The project's `exclude`/`include` globs for the audit walk, read from a
+ * `chant.config.json` only. The audit reads repositories it has no reason to
+ * trust, so it never runs a `chant.config.ts` to find them.
+ */
+function auditGlobs(root) {
+    const { dir, configPath } = findProjectConfig(root);
+    if (!configPath?.endsWith(".json"))
+        return undefined;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+    const list = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string" && x !== "") : []);
+    const exclude = list(raw?.exclude);
+    const include = list(raw?.include);
+    return exclude.length === 0 && include.length === 0 ? undefined : { root: dir, exclude, include };
+}
+/**
+ * Collect file paths under a root through the one discovery walk
+ * (`../discovery/walk.ts`, #2527), sorted per directory.
+ *
+ * The audit's own departures from the other walkers: `.github` and `.forgejo`
+ * are entered, since they hold the CI files it audits; `.terraform/` is
+ * recorded but never entered, since it is machine-generated, routinely
+ * hundreds of megabytes of provider binaries, and its presence is itself the
+ * finding (TF023); and Terraform state paths are left to TF023's own
+ * `.gitignore` reading rather than dropped for being git-ignored.
+ *
+ * Stops at `state.max` paths. Once full it keeps looking only until it meets
+ * one more path it would have taken, which is what sets `truncated`: a tree of
+ * exactly `max` files, or one whose remaining entries are all skipped
+ * directories, was not truncated.
+ */
+function walkFiles(root, state, excludeDirs) {
+    return walkDiscovery({
+        walker: "audit",
+        root,
+        excludeDirs,
+        globs: auditGlobs(root),
+        sorted: true,
+        limit: state,
+        takeSkippedDir: (name) => name === TERRAFORM_WORK_DIR,
+        keepIgnored: (full) => isTerraformStatePath(relative(root, full)),
+        accept: () => true,
+    });
+}
+function readSafe(full) {
+    try {
+        if (statSync(full).size > MAX_FILE_BYTES)
+            return undefined;
+        return readFileSync(full, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function isYaml(name) {
+    return name.endsWith(".yml") || name.endsWith(".yaml");
+}
+function isDockerfileName(name) {
+    return name === "Dockerfile" || name.startsWith("Dockerfile.") || name.endsWith(".Dockerfile") || name.endsWith(".dockerfile");
+}
+function isTerraformFileName(name) {
+    // `terragrunt.hcl` and `root.hcl` ride in the terraform bundle (#3417): the
+    // terraform lexicon reads them into Terragrunt entities, apart from modules.
+    return /\.tf$/i.test(name) || name === "terragrunt.hcl" || name === "root.hcl";
+}
+/**
+ * Filenames the secrets scan (#443) wants that no lexicon otherwise reads —
+ * dotenv files and key/cert material. Included in `isCandidatePath` so both
+ * the local walk and the remote fetch pick them up; `classifyFiles` doesn't
+ * claim them for any lexicon, they just ride along for `scanForSecrets`.
+ */
+function isSecretBearingName(name) {
+    if (/^\.env(\..+)?$/i.test(name))
+        return true;
+    return /\.(pem|key|crt|cer|pfx|p12)$/i.test(name);
+}
+/**
+ * `wrangler.toml` (#446) — Cloudflare Workers' declarative deploy config.
+ * Native TOML, so it rides along the same way secret-bearing filenames do:
+ * `wrangler.ts` reads it directly (no lexicon plugin, no authoring surface),
+ * so it only needs to be a candidate path, not a `detectTemplate` entry.
+ */
+function isWranglerConfigName(name) {
+    return name === "wrangler.toml";
+}
+/** Split a possibly multi-document YAML string into per-doc parsed objects. */
+function parseDocs(content) {
+    const docs = [];
+    for (const raw of content.split(/\n---\n/)) {
+        const t = raw.trim();
+        if (!t)
+            continue;
+        try {
+            const obj = parseYAML(t);
+            if (obj && typeof obj === "object")
+                docs.push(obj);
+        }
+        catch {
+            // a non-parseable doc just doesn't contribute a candidate
+        }
+    }
+    return docs;
+}
+/** Parse JSON or YAML content into a single object, or undefined. */
+function parseStructured(content) {
+    try {
+        const j = JSON.parse(content);
+        if (j && typeof j === "object")
+            return j;
+    }
+    catch {
+        // not JSON — try YAML
+    }
+    try {
+        const y = parseYAML(content);
+        if (y && typeof y === "object")
+            return y;
+    }
+    catch {
+        // not YAML either
+    }
+    return undefined;
+}
+/** Run a plugin's detectTemplate over each parsed doc; true if any matches. */
+function anyDoc(plugin, content) {
+    return parseDocs(content).some((doc) => plugin.detectTemplate?.(doc) ?? false);
+}
+/**
+ * Precedence-ordered content detectors. Order matters: gcp before k8s (Config
+ * Connector resources are also valid k8s manifests).
+ */
+const CONTENT_DETECTORS = [
+    {
+        // GCP Config Connector — must win over k8s for cnrm.cloud.google.com docs.
+        lexicon: "gcp",
+        accepts: isYaml,
+        detect: (plugin, _name, content) => (anyDoc(plugin, content) ? content : null),
+    },
+    {
+        // fountain (`apiVersion: fountain.dev/v1`) — must win over k8s, whose
+        // detectTemplate matches any apiVersion+kind document (#1566).
+        lexicon: "fountain",
+        accepts: isYaml,
+        detect: (plugin, _name, content) => (anyDoc(plugin, content) ? content : null),
+    },
+    {
+        lexicon: "k8s",
+        accepts: isYaml,
+        detect: (plugin, _name, content) => (anyDoc(plugin, content) ? content : null),
+    },
+    {
+        // CloudFormation — JSON, YAML, or `.template`; normalized to a JSON string
+        // because the aws checks JSON.parse their input.
+        lexicon: "aws",
+        accepts: (name) => /\.(json|ya?ml|template)$/i.test(name),
+        detect: (plugin, _name, content) => {
+            const parsed = parseStructured(content);
+            return parsed && plugin.detectTemplate?.(parsed) ? JSON.stringify(parsed) : null;
+        },
+    },
+    {
+        // Azure ARM — JSON only; azure's detectTemplate takes the raw string.
+        lexicon: "azure",
+        accepts: (name) => /\.json$/i.test(name),
+        detect: (plugin, _name, content) => {
+            if (!plugin.detectTemplate?.(content))
+                return null;
+            const parsed = parseStructured(content);
+            return parsed ? JSON.stringify(parsed) : null;
+        },
+    },
+    {
+        // Docker Compose (services:). Dockerfiles are handled separately by name.
+        lexicon: "docker",
+        accepts: isYaml,
+        detect: (plugin, _name, content) => {
+            const parsed = parseStructured(content);
+            return parsed && plugin.detectTemplate?.(parsed) ? content : null;
+        },
+    },
+];
+/**
+ * Which CI lexicon a path belongs to (by location — content can't disambiguate
+ * github vs forgejo). Exported for the fetch module: known-path lexicons stay a
+ * direct path match even in search-first (large-repo) discovery (#520).
+ */
+export function ciLexiconForPath(path) {
+    if (/^\.github\/workflows\/[^/]+\.ya?ml$/.test(path))
+        return "github";
+    if (/^\.forgejo\/workflows\/[^/]+\.ya?ml$/.test(path))
+        return "forgejo";
+    if (path === ".gitlab-ci.yml")
+        return "gitlab";
+    return undefined;
+}
+/**
+ * Whether a path is worth reading/fetching at all. Bounds the local walk and,
+ * crucially, the remote fetch (so we never pull a whole repo's contents).
+ *
+ * nginx configs (#1979) ride along the way `wrangler.toml` does: the NGX
+ * scanner (`./nginx.ts`) reads them directly, no lexicon plugin — but a
+ * scanner can only see what this filter admits, so its own path detector is
+ * part of the candidate set. (Found the hard way: the checks shipped wired
+ * into the CLI while no `.conf` ever survived collection, so they were
+ * unreachable on both the local and hosted paths.) Content confirmation —
+ * a `conf.d/` file that isn't nginx — happens at parse time in the scanner,
+ * never here.
+ */
+export function isCandidatePath(path) {
+    const name = basename(path);
+    if (ciLexiconForPath(path))
+        return true;
+    if (isDockerfileName(name))
+        return true;
+    if (name === "Chart.yaml")
+        return true;
+    if (isSecretBearingName(name))
+        return true;
+    if (isWranglerConfigName(name))
+        return true;
+    if (isNginxConfigPath(path))
+        return true;
+    return /\.(ya?ml|json|template)$/i.test(name);
+}
+export function hintLexiconForFile(path, content) {
+    const name = basename(path);
+    const ci = ciLexiconForPath(path);
+    if (ci)
+        return ci;
+    if (isDockerfileName(name))
+        return "docker";
+    if (name === "Chart.yaml")
+        return "helm";
+    if (isTerraformFileName(name))
+        return "terraform";
+    const head = content.slice(0, 64 * 1024);
+    if (/cnrm\.cloud\.google\.com/.test(head))
+        return "gcp";
+    if (/fountain\.dev\/v1/.test(head))
+        return "fountain";
+    if (/AWSTemplateFormatVersion|["']?Type["']?\s*:\s*["']AWS::/.test(head))
+        return "aws";
+    if (/deploymentTemplate\.json/.test(head))
+        return "azure";
+    if (isYaml(name)) {
+        if (/^apiVersion:/m.test(head) && /^kind:/m.test(head))
+            return "k8s";
+        if (/^services:/m.test(head))
+            return "docker";
+    }
+    return undefined;
+}
+/**
+ * Files no loaded lexicon claimed, paired with the lexicon core guesses they
+ * wanted. Only files whose guessed lexicon is absent are reported; a file an
+ * installed lexicon declined is that plugin's call, not a coverage gap.
+ */
+export function unclaimedFiles(files, inputs, plugins) {
+    const loaded = new Set(plugins.map((p) => p.name));
+    const claimed = new Set();
+    for (const i of inputs) {
+        if (i.files)
+            for (const rel of Object.keys(i.files))
+                claimed.add(i.path === "." ? rel : `${i.path}/${rel}`);
+        else
+            claimed.add(i.path);
+    }
+    const out = [];
+    for (const f of files) {
+        if (claimed.has(f.path))
+            continue;
+        const lexicon = hintLexiconForFile(f.path, f.content);
+        if (!lexicon || loaded.has(lexicon))
+            continue;
+        out.push({ path: f.path, lexicon });
+    }
+    return out;
+}
+/** Collect Helm charts as bundles from an in-memory file set; returns inputs + chart path-prefixes. */
+function classifyHelm(files, plugin) {
+    const inputs = [];
+    const prefixes = [];
+    if (!plugin)
+        return { inputs, prefixes };
+    const charts = files.filter((f) => f.path === "Chart.yaml" || f.path.endsWith("/Chart.yaml"));
+    for (const chartFile of charts) {
+        const dir = chartFile.path === "Chart.yaml" ? "" : chartFile.path.slice(0, -"/Chart.yaml".length);
+        const prefix = dir === "" ? "" : `${dir}/`;
+        const bundle = {};
+        for (const f of files) {
+            if (prefix !== "" && !f.path.startsWith(prefix))
+                continue;
+            bundle[prefix === "" ? f.path : f.path.slice(prefix.length)] = f.content;
+        }
+        const chart = bundle["Chart.yaml"];
+        if (chart === undefined)
+            continue;
+        const parsed = parseStructured(chart);
+        if (!parsed || !plugin.detectTemplate?.(parsed))
+            continue;
+        inputs.push({ path: dir || ".", content: chart, lexicon: "helm", files: bundle });
+        prefixes.push(prefix);
+    }
+    return { inputs, prefixes };
+}
+/**
+ * A `source` attribute naming a local path, the only module source Terraform
+ * reads from the repository itself. A registry or git source ("hashicorp/aws",
+ * "git::https://...") never starts with `./` or `../`, and `source` inside
+ * `required_providers` is a registry address, so the prefix is what tells the
+ * two apart without an HCL parser here. `classifyTerraform` uses this to tell
+ * a root module from a directory that is somebody's child module; the lexicon
+ * plugin parses the calls properly once it has the root.
+ */
+const LOCAL_MODULE_SOURCE = /(?:^|[\s{,])source\s*=\s*"(\.{1,2}\/[^"]*)"/g;
+/**
+ * Resolve `rel` against the repo-relative directory `dir`. Returns undefined
+ * when the path climbs above the audited root, which is a directory this walk
+ * never read and so can never be one of its inputs.
+ */
+function resolveRepoDir(dir, rel) {
+    const parts = dir === "" ? [] : dir.split("/");
+    for (const segment of rel.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..") {
+            if (parts.length === 0)
+                return undefined;
+            parts.pop();
+            continue;
+        }
+        parts.push(segment);
+    }
+    return parts.join("/");
+}
+/**
+ * The directories that are somebody's local child module: a `.tf` file in
+ * another directory of this walk calls them with a relative `source`.
+ *
+ * They are dropped as audit inputs of their own, because the root that calls
+ * them parses them as child scopes (the terraform plugin's `auditEntities`
+ * descends from `AuditInput.dir`, #2217). Auditing them twice would report
+ * every finding in them twice, once per scope, and auditing them as roots is
+ * what made `chant audit` disagree with `chant build` about which rules apply
+ * to a child module at all.
+ *
+ * A directory a cycle reaches but no root does is kept: `a` calling `b`
+ * calling `a` is a configuration Terraform refuses, and dropping both would
+ * leave the files audited by nothing.
+ */
+function calledAsLocalModule(byDir) {
+    const callees = new Map();
+    const called = new Set();
+    for (const [dir, bundle] of byDir) {
+        const targets = new Set();
+        for (const [name, source] of Object.entries(bundle)) {
+            // A Terragrunt unit's `terraform { source = "../modules/x" }` is not a
+            // `module` call: the directory it names stays a root of its own (#3417).
+            if (name === "terragrunt.hcl" || name === "root.hcl")
+                continue;
+            for (const match of source.matchAll(LOCAL_MODULE_SOURCE)) {
+                const target = resolveRepoDir(dir, match[1]);
+                if (target === undefined || target === dir || !byDir.has(target))
+                    continue;
+                targets.add(target);
+                called.add(target);
+            }
+        }
+        callees.set(dir, targets);
+    }
+    const queue = [...byDir.keys()].filter((dir) => !called.has(dir));
+    const reached = new Set(queue);
+    while (queue.length > 0) {
+        for (const target of callees.get(queue.shift()) ?? []) {
+            if (reached.has(target))
+                continue;
+            reached.add(target);
+            queue.push(target);
+        }
+    }
+    return new Set([...called].filter((dir) => reached.has(dir)));
+}
+/**
+ * Collect Terraform root modules as directory bundles from an in-memory file
+ * set, modeled on `classifyHelm`. Unlike a Helm chart (its whole subtree is
+ * one bundle), a Terraform root module references only its own sibling
+ * files, so grouping is by each `.tf` file's immediate directory, not
+ * recursive.
+ *
+ * A directory another one calls as a local module is not a root module and
+ * gets no input of its own (#2217): the root that calls it parses it as a
+ * child scope, which is what Terraform does and what `chant build` already
+ * did. That descent reads the child's directory from disk, so it only happens
+ * when `baseDir` says a local walk found these files; an in-memory file set
+ * with no directory behind it keeps every `.tf` directory as its own input,
+ * as before.
+ *
+ * Returns inputs plus the exact `.tf` paths claimed, so the loose-file pass in
+ * `classifyFiles` can skip them — a child module's files are claimed too, by
+ * the root that will parse them.
+ */
+function classifyTerraform(files, plugin, baseDir) {
+    const inputs = [];
+    const claimed = new Set();
+    if (!plugin)
+        return { inputs, claimed };
+    const byDir = new Map();
+    for (const f of files) {
+        if (!isTerraformFileName(basename(f.path)))
+            continue;
+        const slash = f.path.lastIndexOf("/");
+        const dir = slash === -1 ? "" : f.path.slice(0, slash);
+        const name = slash === -1 ? f.path : f.path.slice(slash + 1);
+        const bundle = byDir.get(dir) ?? {};
+        bundle[name] = f.content;
+        byDir.set(dir, bundle);
+        claimed.add(f.path);
+    }
+    const childModules = baseDir === undefined ? new Set() : calledAsLocalModule(byDir);
+    for (const [dir, bundle] of byDir) {
+        if (childModules.has(dir))
+            continue;
+        // `content` is the whole root module, every `.tf` in filename order with a
+        // `# file:` line comment (legal HCL) marking each boundary, so a lexicon's
+        // `auditEntities(content)` sees the module Terraform itself would load,
+        // not one arbitrary file of it. `files` keeps the per-file split, and
+        // `dir` is where the local modules it calls are read from.
+        const content = Object.keys(bundle)
+            .sort()
+            .map((name) => `# file: ${name}\n${bundle[name]}`)
+            .join("\n");
+        inputs.push({
+            path: dir === "" ? "." : dir,
+            content,
+            lexicon: "terraform",
+            files: bundle,
+            ...(baseDir === undefined ? {} : { dir: resolve(baseDir, dir), baseDir }),
+        });
+    }
+    return { inputs, claimed };
+}
+/**
+ * Classify an in-memory set of repo files into per-lexicon audit inputs. Pure
+ * (no fs, no network) so the local walk and the remote tree-fetch share exactly
+ * one detection path. Each file maps to at most one lexicon: CI by path,
+ * Dockerfiles by name, Helm charts and Terraform root modules as directory
+ * bundles, everything else by the precedence-ordered content detectors
+ * (delegating to each plugin's `detectTemplate`). Lexicons whose plugin isn't
+ * provided are skipped.
+ */
+export function classifyFiles(files, plugins, opts = {}) {
+    const byName = new Map(plugins.map((p) => [p.name, p]));
+    const baseDir = opts.baseDir === undefined ? undefined : resolve(opts.baseDir);
+    // Helm claims whole chart directories first; chart-internal files are excluded
+    // from the loose-file pass so templates aren't double-audited.
+    const helm = classifyHelm(files, byName.get("helm"));
+    const underChart = (p) => helm.prefixes.some((pre) => (pre === "" ? true : p.startsWith(pre)));
+    const terraform = classifyTerraform(files, byName.get("terraform"), baseDir);
+    const inputs = [...helm.inputs, ...terraform.inputs];
+    for (const { path, content } of files) {
+        if (underChart(path))
+            continue;
+        if (terraform.claimed.has(path))
+            continue;
+        const name = basename(path);
+        const ci = ciLexiconForPath(path);
+        if (ci) {
+            if (byName.has(ci))
+                inputs.push({ path, content, lexicon: ci });
+            continue;
+        }
+        if (isDockerfileName(name)) {
+            if (byName.has("docker"))
+                inputs.push({ path, content, lexicon: "docker" });
+            continue;
+        }
+        for (const det of CONTENT_DETECTORS) {
+            const plugin = byName.get(det.lexicon);
+            if (!plugin || !det.accepts(name))
+                continue;
+            const normalized = det.detect(plugin, name, content);
+            if (normalized !== null) {
+                inputs.push({ path, content: normalized, lexicon: det.lexicon });
+                break; // first detector in precedence wins — one lexicon per file
+            }
+        }
+    }
+    return inputs;
+}
+/**
+ * Local discovery: one filesystem walk, candidate-filtered, read into memory,
+ * then handed to the shared `classifyFiles`. Detection is skipped for any
+ * lexicon whose plugin isn't provided, so a caller can scope discovery.
+ */
+export function discoverByDetection(root, plugins) {
+    return classifyFiles(collectCandidates(root), plugins, { baseDir: root });
+}
+/** The walk half of `discoverByDetection`: candidate files read into memory, paths relative to the root. */
+export function collectCandidates(root) {
+    return walkCandidates(root).files;
+}
+/**
+ * `collectCandidates` plus whether the walk stopped at its limit with files
+ * left unread, which the audit report states (#2528).
+ */
+export function walkCandidates(root, opts = {}) {
+    const state = { max: opts.maxFiles ?? DEFAULT_MAX_WALK_FILES, truncated: false };
+    const all = walkFiles(root, state, opts.excludeDirs);
+    // TF023 reads paths, not content: a `.tfstate` can be tens of megabytes of
+    // machine-generated JSON, and the finding is that it is in the repository at
+    // all. The `.gitignore` files are what separate "committed" from "merely on
+    // disk" here. A Terraform working tree almost always has an ignored
+    // `.terraform/` in it, and reporting that would make TF023 fire on every
+    // local audit. Every `.gitignore` from the scan root down to the file's own
+    // directory is read (#2528), so auditing from the root and from a
+    // subdirectory agree. A fetched repository has no such ambiguity (its file
+    // list is the tracked files) and is not filtered.
+    const gitignore = readSafe(join(root, ".gitignore")) ?? "";
+    const nestedBodies = new Map();
+    const nestedGitignoreAt = (dir) => {
+        if (!nestedBodies.has(dir))
+            nestedBodies.set(dir, readSafe(join(root, dir, ".gitignore")));
+        return nestedBodies.get(dir);
+    };
+    const files = [];
+    for (const full of all) {
+        const path = relative(root, full);
+        if (isTerraformStatePath(path)) {
+            const ignored = gitignoreCoversTerraformState(gitignore, path) || nestedGitignoreCovering(path, nestedGitignoreAt) !== undefined;
+            if (!ignored)
+                files.push({ path, content: "" });
+            continue;
+        }
+        // `.tf` is read locally so `classifyTerraform` can bundle real content.
+        // It stays out of `isCandidatePath` so remote fetches still never pull HCL.
+        if (isTerraformFileName(basename(path))) {
+            const content = readSafe(full);
+            if (content !== undefined)
+                files.push({ path, content });
+            continue;
+        }
+        if (!isCandidatePath(path))
+            continue;
+        const content = readSafe(full);
+        if (content !== undefined)
+            files.push({ path, content });
+    }
+    return { files, maxFiles: state.max, truncated: state.truncated };
+}