@intentius/chant 0.124.13 → 0.124.14

package/dist/agents/importer.js

@@ -0,0 +1,17 @@
+/**
+ * The seam between neutral agent-config discovery and a lexicon's vocabulary.
+ *
+ * `discover.ts` deliberately knows nothing about chant resources — it reads
+ * five harnesses' config dialects and stops. Turning an {@link AgentConfigSite}
+ * into resources is a statement about a *target* (fountain's `Agent` and
+ * `Environment`, today), and that judgement belongs to the lexicon that owns
+ * those types, exactly as `templateParser()` puts CloudFormation's JSON
+ * vocabulary in the aws lexicon rather than in core.
+ *
+ * So a lexicon that can express local agent configuration implements
+ * {@link AgentConfigImporter} and returns it from
+ * `LexiconPlugin.agentConfigImporter()`. `chant import --agents` loads the
+ * plugin, hands it the scan, and pipes the resulting IR through the same
+ * `templateGenerator()` every other import path uses.
+ */
+export {};

package/dist/agents/index.js

@@ -0,0 +1,12 @@
+/**
+ * Agent-configuration discovery and checks.
+ *
+ * Finds the agent configs on a machine (`discover.ts`), judges them
+ * (`checks.ts`), and normalizes both onto one vendor-neutral model
+ * (`types.ts`). The two consumers are `chant audit --agents`, which reports on
+ * what it finds, and `chant import --agents`, which re-expresses it as chant
+ * code via a lexicon's IR mapper.
+ */
+export { AGENT_RUNTIMES, AGENT_SCOPES } from "./types.js";
+export { scanAgentConfigs, normalizeMcpServers, frontmatter, systemSettingsPaths, unscannedProjectCount } from "./discover.js";
+export { checkAgentConfigs, AGENT_RULE_IDS } from "./checks.js";

package/dist/agents/types.js

@@ -0,0 +1,19 @@
+/**
+ * The normalized model for an agent configuration found on a machine.
+ *
+ * Five harnesses (claude, codex, gemini, opencode, cursor) each spell the same
+ * four ideas differently — standing instructions, tool servers, reusable
+ * skills, and ambient settings. `discover.ts` reads each harness's own dialect
+ * and lands here; everything downstream (`checks.ts`, the report, the fountain
+ * IR mapping) reads only this shape and never a vendor file format again.
+ *
+ * The `AgentConfigSite` boundary is deliberately "one config that governs one
+ * root, for one runtime" rather than "one file". A single Claude Code site is
+ * assembled from `CLAUDE.md` + `settings.json` + `settings.local.json` +
+ * `mcp.json` + `~/.claude.json` + a `skills/` tree — six files that are only
+ * meaningful together, and that the agent itself experiences as one merged
+ * configuration. `sources` keeps the receipts so a finding can point at the
+ * actual file the reader has to edit.
+ */
+export const AGENT_SCOPES = ["system", "user", "project"];
+export const AGENT_RUNTIMES = ["claude", "codex", "gemini", "opencode", "cursor"];

package/dist/apply.js

@@ -0,0 +1,151 @@
+/**
+ * The apply contract (#1446) — what a lexicon's applier is allowed to mean.
+ *
+ * The peer of `./observation.ts`, and it exists for the same reason on the other
+ * side of the lifecycle.
+ *
+ * The read path had two ways to return nothing for a declared entity and no way
+ * to tell them apart — "the provider says it is absent" versus "I never looked"
+ * — and the second was classifying as `create`. #1089 made that a tri-state and
+ * #1201 built a conformance suite so a lexicon could not pass by returning a
+ * well-shaped result that still proposed a create.
+ *
+ * The write path had the identical hole. An applier could skip a resource and
+ * report nothing:
+ *
+ *     const mapper = MAPPERS[r.kind];
+ *     if (!mapper) {
+ *       console.log(`skip: no mapper for kind ${r.kind}`);
+ *       continue;                    // never appears in `applied`, or anywhere
+ *     }
+ *
+ * A caller receiving `{ applied: [...] }` could not distinguish a complete apply
+ * from one that dropped half the manifest, and `ApplyOp` had nothing to gate on.
+ * A `console.log` on stdout is not a signal in a result, the same way a warn on
+ * stderr was not a signal in a change set (#1447 was the concrete bug; #1457
+ * found the same shape in two more appliers).
+ *
+ * The contract is a tri-state, per resource in the plan:
+ *
+ *   - **APPLIED** — the provider was called and converged. Carries the action
+ *     (`created` / `updated` / `unchanged`) and the physical id when resolved.
+ *   - **PRUNED** — owned, no longer declared, deleted.
+ *   - **NOT-ATTEMPTED** — carrying a total {@link NotAttemptedReason}. Never
+ *     silent, never inferred from absence.
+ *
+ * The three are **disjoint and total**: every resource the applier was given
+ * appears in exactly one. That is the assertion the conformance suite exists to
+ * make, and the one the gcp skip failed.
+ *
+ * Compatibility: an applier may keep returning its own shape. The envelope is
+ * discriminated by its literal `apply: "v1"` field, the same mechanism
+ * `observation: "v1"` uses, so an un-migrated applier normalizes to "everything
+ * I was handed, I attempted" and nothing breaks. Reporting NOT-ATTEMPTED
+ * requires the envelope — which is the point: you cannot claim the guarantee
+ * without adopting the shape that can express its absence.
+ */
+/** Every legal {@link NotAttemptedReason}, for validation and conformance checks. */
+export const NOT_ATTEMPTED_REASONS = [
+    "unsupported-kind",
+    "no-credentials",
+    "no-binding",
+    "dependency-failed",
+    "filtered",
+    "not-prunable",
+];
+/** True when `value` is a legal {@link NotAttemptedReason}. */
+export function isNotAttemptedReason(value) {
+    return typeof value === "string" && NOT_ATTEMPTED_REASONS.includes(value);
+}
+/** Every legal {@link AppliedAction}. */
+export const APPLIED_ACTIONS = ["created", "updated", "unchanged"];
+/** True when `value` is the versioned {@link ApplyResult} envelope. */
+export function isApplyResult(value) {
+    return typeof value === "object" && value !== null && value.apply === "v1";
+}
+/**
+ * Build an {@link ApplyResult}. Appliers use this rather than writing the
+ * discriminant by hand.
+ */
+export function applyResult(applied, pruned, notAttempted) {
+    return {
+        apply: "v1",
+        applied,
+        ...(pruned && pruned.length > 0 ? { pruned } : {}),
+        ...(notAttempted && notAttempted.length > 0 ? { notAttempted } : {}),
+    };
+}
+/**
+ * Normalize an applier's return value.
+ *
+ * A non-envelope value normalizes to "everything I was handed, I attempted" —
+ * an empty `notAttempted`. That is the compatibility path, and it is also
+ * exactly the claim an un-migrated applier is implicitly making, so nothing is
+ * invented on its behalf.
+ *
+ * `undefined` normalizes to three empty arrays. An applier that means "I applied
+ * nothing because I could not" must say so with {@link notAttemptedAll} rather
+ * than returning nothing, for the same reason `unobservedAll` exists on the read
+ * side.
+ */
+export function normalizeApply(value) {
+    if (!value)
+        return { applied: [], pruned: [], notAttempted: [] };
+    return {
+        applied: value.applied ?? [],
+        pruned: value.pruned ?? [],
+        notAttempted: value.notAttempted ?? [],
+    };
+}
+/**
+ * Mark every named resource NOT-ATTEMPTED with one reason — the whole-run
+ * failure case (no credentials, no binding, the transport never came up). Core
+ * applies this when an applier throws, so a thrown apply degrades to an honest
+ * "did not attempt" per resource instead of an empty result that reads as a
+ * successful no-op.
+ */
+export function notAttemptedAll(refs, reason, detail) {
+    return [...refs].map((ref) => ({ ...ref, reason, ...(detail ? { detail } : {}) }));
+}
+/** A resource's identity within one apply, for disjointness checks. */
+export function applyRefKey(ref) {
+    return `${ref.kind}/${ref.name}`;
+}
+/**
+ * Every resource that appears in more than one bucket. Empty is the contract;
+ * a non-empty result means the applier both wrote and skipped the same
+ * resource, which is not a state that can be true.
+ *
+ * Pruned is checked against the other two but not against itself: an applier
+ * may legitimately apply a resource and prune a different, same-named one only
+ * if their kinds differ, and {@link applyRefKey} already separates those.
+ */
+export function overlappingRefs(result) {
+    const seen = new Map();
+    const note = (bucket, refs) => {
+        for (const ref of refs) {
+            const key = applyRefKey(ref);
+            (seen.get(key) ?? seen.set(key, new Set()).get(key)).add(bucket);
+        }
+    };
+    note("applied", result.applied);
+    note("pruned", result.pruned);
+    note("notAttempted", result.notAttempted);
+    return [...seen.entries()].filter(([, buckets]) => buckets.size > 1).map(([key]) => key);
+}
+/**
+ * Resources in `plan` that the result accounts for in no bucket — the silent
+ * drop this contract exists to make impossible.
+ *
+ * The conformance suite's central assertion. Before #1447, gcp's applier failed
+ * exactly this: an unmapped kind was in the plan, in no bucket, and the result
+ * looked complete.
+ */
+export function unaccountedRefs(plan, result) {
+    const accounted = new Set();
+    for (const bucket of [result.applied, result.pruned, result.notAttempted]) {
+        for (const ref of bucket)
+            accounted.add(applyRefKey(ref));
+    }
+    return [...plan].map(applyRefKey).filter((key) => !accounted.has(key));
+}

package/dist/attrref.js

@@ -0,0 +1,70 @@
+var _a;
+import { INTRINSIC_MARKER } from "./intrinsic.js";
+/**
+ * Reference to an attribute of a parent entity.
+ * Lexicon serializers read `getLogicalName()` and `attribute` to produce
+ * their own output format (e.g. CloudFormation `Fn::GetAttr`).
+ */
+export class AttrRef {
+    constructor(parent, attribute) {
+        this[_a] = true;
+        this.parent = new WeakRef(parent);
+        this.attribute = attribute;
+    }
+    /**
+     * Set the logical name for this attribute reference
+     * @internal
+     */
+    _setLogicalName(name) {
+        this.logicalName = name;
+    }
+    /**
+     * Get the logical name assigned to this attribute reference.
+     */
+    getLogicalName() {
+        return this.logicalName;
+    }
+    /**
+     * Refuse to become a string (#2349).
+     *
+     * An `AttrRef` stands for a value the build resolves later, so it has no
+     * string form here. Without this, `` `${bucket.arn}-suffix` `` produced
+     * `"[object Object]-suffix"` and shipped it — and the fold path produced
+     * exactly the same wrong string from the `{__attrRef}` envelope, so the two
+     * paths agreed and the differential harness reported nothing. Agreement on a
+     * wrong value is the failure this class of check exists to catch, which is
+     * why this throws rather than returning something more helpful-looking.
+     *
+     * `toJSON` below is the honest serialization and is untouched: a serializer
+     * that wants the envelope asks for it by name.
+     */
+    toString() {
+        const where = this.logicalName ? `${this.logicalName}.${this.attribute}` : `.${this.attribute}`;
+        throw new Error(`A resource attribute reference (${where}) has no string form: it stands for a value the build ` +
+            "resolves later, and interpolating it into a plain template literal would produce " +
+            '"[object Object]". Use the lexicon\'s own intrinsic, whose interior handles references — ' +
+            "`Sub`${…}`` for CloudFormation — or move the reference out of the template.");
+    }
+    /**
+     * The same refusal for `+` and for anything else that coerces, so
+     * `"prefix" + bucket.arn` fails where `` `${bucket.arn}` `` fails rather
+     * than taking a different path to the same wrong string.
+     */
+    [(_a = INTRINSIC_MARKER, Symbol.toPrimitive)]() {
+        return this.toString();
+    }
+    /**
+     * Serialize to a generic envelope. Lexicon-specific serializers should
+     * read `getLogicalName()` and `attribute` directly instead of relying
+     * on this format.
+     * @throws {Error} If logical name has not been set
+     */
+    toJSON() {
+        if (!this.logicalName) {
+            throw new Error(`Cannot serialize AttrRef for attribute "${this.attribute}": logical name not set`);
+        }
+        return {
+            __attrRef: { entity: this.logicalName, attribute: this.attribute },
+        };
+    }
+}

package/dist/audit/catalog.js

@@ -0,0 +1,350 @@
+/**
+ * Rule catalog — classifies every CI post-synth check the auditor can surface.
+ *
+ * Two axes drive how a finding is presented:
+ *  - `tier`: `merge-worthy` (a security vuln/supply-chain exposure or a hard
+ *    correctness bug — worth opening a PR to the target) vs `report-only`
+ *    (hygiene/style/perf/deprecation — shown in the report, never a PR title).
+ *  - `fixKind`: `deterministic` (a safe mechanical fix can be auto-applied or
+ *    diffed) vs `guidance` (needs human/LLM judgment — emit remediation text
+ *    only; never auto-applied; never run by the hosted service).
+ *
+ * Each provider's rule metadata lives in its own lexicon's `auditCatalog()`
+ * (#687); this module owns the shared machinery — the `RuleMeta` shape, the
+ * `auditRule()` constructor lexicons build entries with, the shared authority
+ * citations, and `resolveAuditCatalog()` which merges the lexicons' catalogs
+ * over the small static core map (the cross-cutting COR/EXT ids). A drift-guard
+ * test asserts the aggregate stays in sync with the lexicons' post-synth checks.
+ */
+import { applyLineage as attachLineage } from "./prior-art.js";
+import { coreAuditLineage } from "./lineage.js";
+export { PRIOR_ART, applyLineage, lineageLabel } from "./prior-art.js";
+// ── Authority references ─────────────────────────────────────────────
+export const SCORECARD_TOKEN = {
+    name: "OSSF Scorecard — Token-Permissions",
+    url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions",
+};
+export const GH_TOKEN = {
+    name: "GitHub — Automatic token authentication",
+    url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication",
+};
+export const SCORECARD_PINNED = {
+    name: "OSSF Scorecard — Pinned-Dependencies",
+    url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#pinned-dependencies",
+};
+export const GH_THIRD_PARTY = {
+    name: "GitHub — Using third-party actions",
+    url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-third-party-actions",
+};
+export const GH_INJECTION = {
+    name: "GitHub — Understanding the risk of script injections",
+    url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections",
+};
+export const GH_PWN = {
+    name: "GitHub Security Lab — Preventing pwn requests",
+    url: "https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/",
+};
+export const GH_SECRETS = {
+    name: "GitHub — Using secrets in GitHub Actions",
+    url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions",
+};
+export const GH_OIDC = {
+    name: "GitHub — Security hardening with OpenID Connect",
+    url: "https://docs.github.com/en/actions/concepts/security/openid-connect",
+};
+export const K8S_PSS = {
+    name: "Kubernetes — Pod Security Standards",
+    url: "https://kubernetes.io/docs/concepts/security/pod-security-standards/",
+};
+export const K8S_SECRETS = {
+    name: "Kubernetes — Good practices for Secrets",
+    url: "https://kubernetes.io/docs/concepts/security/secrets-good-practices/",
+};
+export const GH_SECRET_SCANNING = {
+    name: "GitHub — About secret scanning",
+    url: "https://docs.github.com/en/code-security/secret-scanning/introduction/about-secret-scanning",
+};
+export const SCORECARD_VULN = {
+    name: "OSSF Scorecard — Vulnerabilities",
+    url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#vulnerabilities",
+};
+export const CF_WORKERS_DEV = {
+    name: "Cloudflare Workers — workers.dev",
+    url: "https://developers.cloudflare.com/workers/configuration/routing/workers-dev/",
+};
+export const CF_SECRETS = {
+    name: "Cloudflare Workers — Secrets",
+    url: "https://developers.cloudflare.com/workers/configuration/secrets/",
+};
+export const CF_ROUTES = {
+    name: "Cloudflare Workers — Routes",
+    url: "https://developers.cloudflare.com/workers/configuration/routing/routes/",
+};
+export const CF_ENVIRONMENTS = {
+    name: "Cloudflare Workers — Wrangler environments",
+    url: "https://developers.cloudflare.com/workers/wrangler/configuration/#environments",
+};
+export const CF_STATIC_ASSETS = {
+    name: "Cloudflare Workers — Static assets",
+    url: "https://developers.cloudflare.com/workers/static-assets/",
+};
+export const MOZILLA_TLS = {
+    name: "Mozilla — Server Side TLS",
+    url: "https://wiki.mozilla.org/Security/Server_Side_TLS",
+};
+export const CWE_DIR_LISTING = {
+    name: "CWE-548 — Exposure of Information Through Directory Listing",
+    url: "https://cwe.mitre.org/data/definitions/548.html",
+};
+export const GIXY_ALIAS = {
+    name: "Gixy — alias traversal",
+    url: "https://github.com/yandex/gixy/blob/master/docs/en/plugins/aliastraversal.md",
+};
+export const NGINX_STUB_STATUS = {
+    name: "nginx — ngx_http_stub_status_module",
+    url: "https://nginx.org/en/docs/http/ngx_http_stub_status_module.html",
+};
+export const CWE_HARDCODED_CREDS = {
+    name: "CWE-798 — Use of Hard-coded Credentials",
+    url: "https://cwe.mitre.org/data/definitions/798.html",
+};
+export const HASHICORP_STYLE_GITIGNORE = {
+    name: "HashiCorp Terraform style guide — .gitignore",
+    url: "https://developer.hashicorp.com/terraform/language/style#gitignore",
+};
+export const CWE_CLEARTEXT = {
+    name: "CWE-319 — Cleartext Transmission of Sensitive Information",
+    url: "https://cwe.mitre.org/data/definitions/319.html",
+};
+function meta(id, tier, fixKind, title, remediation, authority, lineage) {
+    // An authority citation is the strongest security signal, so it wins. Otherwise
+    // the curated RULE_CATEGORY map (defined below, before RULE_CATALOG runs)
+    // decides correctness vs best-practice vs security-without-authority; the drift
+    // test guarantees every id is mapped, so the fallback is only a type belt.
+    const category = authority && authority.length > 0 ? "security" : RULE_CATEGORY[id] ?? "best-practice";
+    return { id, tier, fixKind, category, title, remediation, authority, ...(lineage?.length ? { lineage } : {}), yamlBased: true };
+}
+const M = "merge-worthy";
+const R = "report-only";
+const D = "deterministic";
+const G = "guidance";
+/**
+ * An AGT (agent-configuration) rule. Unlike every other family in the catalog
+ * these do not run against emitted YAML — they run against the agent config
+ * discovered on a machine (`packages/core/src/agents/`), so `yamlBased` is
+ * false: feeding a workflow file to the auditor will never produce one.
+ *
+ * All eight are `guidance`. There is no safe mechanical fix for any of them —
+ * pinning someone's MCP server picks a version on their behalf, and narrowing a
+ * permission grant requires knowing which commands they actually run.
+ */
+function agentMeta(id, tier, title, remediation, authority) {
+    const category = authority && authority.length > 0 ? "security" : RULE_CATEGORY[id] ?? "best-practice";
+    return { id, tier, fixKind: G, category, title, remediation, authority, yamlBased: false };
+}
+/**
+ * Finding category per rule (#415). Curated: security rules are those that
+ * cite an authority or guard an exposure; correctness rules flag structural
+ * bugs (broken references, invalid schema, never-runs); the rest are
+ * best-practice. A drift test asserts this covers every catalogued rule.
+ */
+export const RULE_CATEGORY = {
+    COR020: "correctness",
+    EXT001: "correctness",
+    SEC001: "security",
+    SEC002: "security",
+    SEC003: "security",
+    SEC004: "security",
+    SEC005: "security",
+    SEC006: "security",
+    SEC007: "security",
+    SEC008: "security",
+    SEC009: "security",
+    SEC010: "security",
+    WRG001: "security",
+    WRG002: "security",
+    WRG003: "best-practice",
+    WRG004: "security",
+    WRG005: "security",
+    WRG006: "security",
+    // NGX — nginx config audit (#1979), lexicon-independent like SEC/WRG.
+    NGX001: "security",
+    NGX002: "security",
+    NGX003: "security",
+    NGX004: "security",
+    NGX005: "security",
+    NGX006: "best-practice",
+    NGX007: "best-practice",
+    // TF023 — Terraform state committed to the repository. Core-owned for the
+    // same reason SEC/WRG/NGX are: it reads the discovered file list, not a
+    // parsed root module. See ./terraform-state.ts.
+    TF023: "security",
+    // AGT — agent configuration (`chant audit --agents`). Core-owned like COR/EXT:
+    // these run against the machine's own agent config, not against any one
+    // lexicon's emitted output, so no lexicon ships them.
+    AGT001: "security",
+    AGT002: "security",
+    AGT003: "security",
+    AGT004: "security",
+    AGT005: "security",
+    AGT006: "best-practice",
+    AGT007: "correctness",
+    AGT008: "best-practice",
+};
+/**
+ * Core's static portion of the audit catalog — now only the cross-cutting
+ * CloudFormation ids (COR/EXT) that aren't owned by a single lexicon. Every
+ * per-provider block moved to its lexicon's `auditCatalog()` (#687): WAW→aws,
+ * WGC→gcp, AZR→azure, DKRD→docker, WK8/ARGO→k8s, WHM→helm, GHA→github,
+ * WGL→gitlab, WFJ→forgejo. `resolveAuditCatalog` merges those over this map,
+ * alongside the lexicon-independent SEC/WRG/AGT families core owns outright.
+ */
+export const RULE_CATALOG = {
+    COR020: meta("COR020", M, G, "Circular resource dependency", "Break the dependency cycle between resources."),
+    EXT001: meta("EXT001", M, G, "Extension constraint violation", "Fix the cross-property constraint flagged by the cfn-lint extension schema."),
+    // Secrets & credentials (#443) — lexicon-independent: `secrets.ts` scans the
+    // raw text of every candidate file, so these ids apply regardless of which
+    // (if any) audit lexicons are installed. `fixKind` is `guidance`: removing
+    // a hardcoded credential and rotating it needs a human, never an auto-fix.
+    SEC001: meta("SEC001", M, G, "AWS access key ID found", "Remove the key from source, rotate it in IAM, and load it from a secret store or environment variable instead.", [GH_SECRET_SCANNING]),
+    SEC002: meta("SEC002", M, G, "AWS secret access key found", "Remove the key from source, rotate it in IAM, and load it from a secret store or environment variable instead.", [GH_SECRET_SCANNING]),
+    SEC003: meta("SEC003", M, G, "GitHub token found", "Remove the token from source and revoke it at github.com/settings/tokens; use a GitHub Actions secret instead.", [GH_SECRET_SCANNING]),
+    SEC004: meta("SEC004", M, G, "Slack token found", "Remove the token from source and revoke it in the Slack app's OAuth settings.", [GH_SECRET_SCANNING]),
+    SEC005: meta("SEC005", M, G, "Google API key found", "Remove the key from source and regenerate it in the Google Cloud Console credentials page.", [GH_SECRET_SCANNING]),
+    SEC006: meta("SEC006", M, G, "Stripe live secret key found", "Remove the key from source and roll it in the Stripe dashboard immediately — this is a live-mode key.", [GH_SECRET_SCANNING]),
+    SEC007: meta("SEC007", M, G, "Private key block found", "Remove the private key from source, rotate the keypair, and load the key from a secret store instead.", [GH_SECRET_SCANNING]),
+    SEC008: meta("SEC008", M, G, "Bearer/authorization token found", "Remove the token from source; if it's long-lived, revoke and reissue it via the issuing service.", [GH_SECRET_SCANNING]),
+    SEC009: meta("SEC009", M, G, "Credentials embedded in a connection string", "Move the username/password out of the URI into a secret store, and rotate the credential.", [GH_SECRET_SCANNING]),
+    SEC010: meta("SEC010", M, G, "High-entropy string — possible secret", "Confirm whether this is a live credential; if so, remove it from source and rotate it. If it's a false positive, suppress with a `chant-audit-ignore` comment or an allowlist entry.", [GH_SECRET_SCANNING]),
+    // Wrangler config audit (#446) — lexicon-independent, same shape as the SEC
+    // family above: `wrangler.ts` scans every `wrangler.toml` it finds
+    // regardless of which (if any) audit lexicons are installed.
+    WRG001: meta("WRG001", M, G, "Production environment exposed on *.workers.dev", "Remove workers_dev (or set it to false) for this environment and rely on its custom domain/route instead of the shared public subdomain.", [CF_WORKERS_DEV]),
+    WRG002: meta("WRG002", M, G, "Credential-shaped key stored in [vars]", "Move the value out of [vars] and into `wrangler secret put <name>` so it isn't committed to source or visible in `wrangler dev`/the dashboard.", [CF_SECRETS]),
+    WRG003: meta("WRG003", R, G, "Observability explicitly disabled", "Set observability.enabled = true (or remove the override) so Workers Logs are recorded for this deployment."),
+    WRG004: meta("WRG004", M, G, "Unscoped wildcard route", "Scope the route pattern to the intended zone (e.g. \"example.com/*\") instead of a bare \"*\" or \"*/*\" that matches every zone on the account.", [CF_ROUTES]),
+    WRG005: meta("WRG005", M, G, "Non-production environment shares a data store with production", "Give the non-production environment its own KV namespace/R2 bucket/D1 database id instead of reusing production's.", [CF_ENVIRONMENTS]),
+    WRG006: meta("WRG006", M, G, "Static assets served from the project root", "Point [site].bucket / [assets].directory at a dedicated public output folder, not the project root, so non-public files (config, source maps, .git) aren't served.", [CF_STATIC_ASSETS]),
+    // nginx config audit (#1979, the #446 follow-up) — lexicon-independent,
+    // same shape as SEC/WRG: `nginx.ts` scans every nginx config it detects
+    // regardless of which (if any) audit lexicons are installed.
+    NGX001: meta("NGX001", M, G, "Deprecated TLS protocol enabled", "Remove SSLv2/SSLv3/TLSv1/TLSv1.1 from ssl_protocols and serve TLSv1.2 and TLSv1.3 only.", [MOZILLA_TLS]),
+    NGX002: meta("NGX002", M, G, "Weak cipher suite enabled", "Remove the RC4/DES/MD5/NULL/EXPORT-class entries from ssl_ciphers and use a modern cipher list (e.g. Mozilla's intermediate configuration).", [MOZILLA_TLS]),
+    NGX003: meta("NGX003", M, G, "Directory listing enabled", "Remove `autoindex on` (or scope it to a directory that is genuinely meant to be enumerated) so file listings aren't served to anyone who asks.", [CWE_DIR_LISTING]),
+    NGX004: meta("NGX004", M, G, "alias path traversal", "End the location prefix with \"/\" so it matches the trailing slash of the alias target — without it, a request for \"<prefix>../\" escapes the aliased directory.", [GIXY_ALIAS]),
+    NGX005: meta("NGX005", M, G, "Status endpoint with no access restriction", "Restrict the stub_status location with allow/deny (or auth_basic/auth_request) so connection metrics aren't public reconnaissance.", [NGINX_STUB_STATUS]),
+    NGX006: meta("NGX006", R, G, "Server version disclosure", "Add `server_tokens off;` in the http block so nginx stops advertising its exact version in the Server header and error pages."),
+    NGX007: meta("NGX007", R, G, "Access logging disabled at server scope", "Re-enable access_log at http/server scope (silencing a single noisy location is fine) so requests are recorded for incident investigation."),
+    // TF023 (#2110) — Terraform state, or the `.terraform/` working directory,
+    // committed to the repository. The one TF rule core owns: every other TF id
+    // is a post-synth check over a parsed root module (the terraform lexicon's
+    // `auditCatalog()`), while this one reads the discovered file list and never
+    // runs during `chant build`. Same shape as SEC/WRG/NGX above, and the same
+    // reason it lives here: `terraform-state.ts` needs no lexicon installed.
+    TF023: meta("TF023", M, G, "Terraform state committed to the repository", "Delete the state file (or `.terraform/`) from version control, add it to .gitignore, move the state to a remote backend, and rotate every credential the file held.", [HASHICORP_STYLE_GITIGNORE]),
+    // ── Agent configuration (`chant audit --agents`) ──────────────────
+    AGT001: agentMeta("AGT001", M, "MCP server runs an unpinned package", "Pin the package spec to an exact version (`server@1.2.3`), so a new upstream release can't execute on this machine unreviewed.", [SCORECARD_PINNED]),
+    AGT002: agentMeta("AGT002", M, "Literal credential in agent config", "Replace the value with an environment reference (`${TOKEN}`) and keep the secret in a secret store — agent config files sync, back up, and get shared.", [CWE_HARDCODED_CREDS]),
+    AGT003: agentMeta("AGT003", M, "MCP server reached over cleartext HTTP", "Use an https:// endpoint. Tool arguments and results — including data the agent read locally — otherwise cross the network in the clear.", [CWE_CLEARTEXT]),
+    AGT004: agentMeta("AGT004", M, "Remote skill or plugin is unpinned", "Pin the source to a tag or commit sha, so the instructions the agent follows can't change upstream without a local edit.", [SCORECARD_PINNED]),
+    AGT005: agentMeta("AGT005", M, "Tool permission granted without constraint", "Scope the grant to the specific commands you run (`Bash(git status:*)`), and re-enable the confirmation prompt for dangerous operations."),
+    AGT006: agentMeta("AGT006", R, "User-scope config applies to every project", "Move project-specific instructions, MCP servers, and skills to that project's own config so they don't follow you into unrelated repos."),
+    AGT007: agentMeta("AGT007", R, "MCP server declared in multiple files", "Delete the shadowed declarations. The harness silently picks one, so the file you read may not be the one that decides what runs."),
+    AGT008: agentMeta("AGT008", R, "Instruction file exceeds the attention budget", "Move situational guidance into skills that load on demand, so the always-on instructions stay short enough to be followed reliably."),
+};
+// Prior art credits for the core static rules (SEC/WRG/NGX/AGT/EXT) — ./lineage.ts.
+attachLineage(RULE_CATALOG, coreAuditLineage);
+/**
+ * Build one catalog entry — the lexicon-facing constructor for
+ * `LexiconPlugin.auditCatalog()` (#687), so a lexicon can declare its own rules'
+ * metadata next to the rules. Unlike the internal `meta()` it takes `category`
+ * explicitly (a lexicon owns its rules' categories) rather than reading core's
+ * curated `RULE_CATEGORY` map: an authority citation still forces `security`,
+ * otherwise the passed `category` (default `best-practice`) applies.
+ */
+export function auditRule(id, tier, fixKind, title, remediation, opts) {
+    const category = opts?.authority && opts.authority.length > 0 ? "security" : (opts?.category ?? "best-practice");
+    return {
+        id,
+        tier,
+        fixKind,
+        category,
+        title,
+        remediation,
+        authority: opts?.authority,
+        ...(opts?.lineage?.length ? { lineage: opts.lineage } : {}),
+        yamlBased: true,
+    };
+}
+/**
+ * Resolve the effective audit catalog for a set of lexicons: core's static
+ * `RULE_CATALOG` with each active lexicon's contributed `auditCatalog()` merged
+ * on top (a lexicon's own entry wins for its ids). This is the aggregation seam
+ * (#687, epic #350) that lets per-provider metadata move out of core into the
+ * lexicon that owns the rules, while the auditor — which already loads those
+ * lexicons to run the rules — reads one merged catalog. Tolerant: a lexicon
+ * that can't be loaded or contributes no catalog is skipped.
+ */
+export async function resolveAuditCatalog(lexicons) {
+    const catalog = { ...RULE_CATALOG };
+    // Forgejo workflows are GitHub-dialect: `audit/core.ts` runs github's checks
+    // against them, so their GHA* findings need github's catalog too (#687).
+    const needed = lexicons.includes("forgejo") && !lexicons.includes("github") ? [...lexicons, "github"] : lexicons;
+    if (needed.length === 0)
+        return catalog;
+    // Lazy import so importing this module doesn't pull in the plugin/config graph
+    // (matches ./core.ts's `load` — see #408). Loaded one at a time (rather than
+    // the bulk `loadPlugins`, which aborts on the first failure) so one
+    // not-yet-installed lexicon (e.g. terraform, #2085) doesn't drop every other
+    // lexicon's contributed catalog back to the static core map.
+    const { loadPlugin } = await import("../cli/plugins.js");
+    for (const name of needed) {
+        let plugin;
+        try {
+            plugin = await loadPlugin(name);
+        }
+        catch {
+            continue; // a lexicon package isn't installed, its catalog just doesn't contribute.
+        }
+        const contributed = plugin?.auditCatalog?.();
+        if (contributed)
+            Object.assign(catalog, contributed);
+    }
+    return catalog;
+}
+/** Look up catalog metadata for a check id, if known. */
+export function ruleMeta(id) {
+    return RULE_CATALOG[id];
+}
+/**
+ * Resolve a rule id to its canonical form against `catalog` (chant #2113). An
+ * id that is itself a key of `catalog` passes through unchanged (this covers
+ * the common case without scanning every entry's `aliases`); otherwise every
+ * entry's `aliases` is searched for a match, and the id it belongs to is
+ * returned. An id neither a key nor anyone's alias passes through unchanged
+ * too, since this is a best-effort resolver, not a validator, so an unknown
+ * id is a caller's problem, not this function's.
+ *
+ * Exported so a `lint.rules`/preset key that names an alias resolves to the
+ * rule that actually runs (see `resolveConfiguredSeverity`,
+ * `../lint/config.ts`), and so #2111's HCL suppression code can key an
+ * inline `# chant-ignore <id>` off the same resolution once it lands — that
+ * suppression mechanism does not exist yet in this worktree (#2111 is a
+ * separate, parallel issue), so this function is exported now for it to call
+ * later rather than being wired into it here.
+ */
+export function canonicalRuleId(id, catalog = RULE_CATALOG) {
+    if (id in catalog)
+        return id;
+    for (const [canonicalId, meta] of Object.entries(catalog)) {
+        if (meta.aliases?.includes(id))
+            return canonicalId;
+    }
+    return id;
+}
+/** Docs path for the audit rules reference (one anchor per rule id). */
+export const RULES_DOC_PATH = "/chant/lint-rules/audit-rules/";
+/** Absolute URL to a rule's entry in the audit rules reference. */
+export function ruleDocUrl(id) {
+    return `https://intentius.io${RULES_DOC_PATH}#${id.toLowerCase()}`;
+}