@intentius/chant 0.124.12 → 0.124.14

package/dist/config.js

@@ -0,0 +1,605 @@
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { z } from "zod";
+import { DEFAULT_SBOM_FORMAT } from "./components/verbs/sbom-generator.js";
+import { findProjectConfig } from "./project-root.js";
+import { evaluateProjectConfig } from "./config-sandbox.js";
+import { lexiconNames, pathLexiconRoot, registerLexiconDeclarations } from "./lexicon-module.js";
+import { decideConfigSchema } from "./op/decide-config.js";
+/** The declared name of one `environments` entry, whichever form it takes. */
+export function environmentName(entry) {
+    return typeof entry === "string" ? entry : entry.name;
+}
+/**
+ * Every declared environment's name, in `environments` order. `undefined` in,
+ * `undefined` out — mirrors the field itself being optional, so a caller that
+ * already writes `config.environments?.something` can keep doing so:
+ * `environmentNames(config.environments)?.includes(name)`.
+ */
+export function environmentNames(environments) {
+    return environments?.map(environmentName);
+}
+/**
+ * Whether a declared environment name is a glob pattern rather than a literal
+ * (#1221) — it contains at least one `*`.
+ */
+export function isEnvironmentPattern(declaredName) {
+    return declaredName.includes("*");
+}
+/**
+ * Anchored `*`-glob match (#1221): each `*` in `pattern` matches any run of
+ * characters (possibly empty); everything else matches itself. Deliberately
+ * the whole surface — no `?`, no character classes, no regex. A pattern with
+ * no `*` degenerates to string equality.
+ */
+export function matchesEnvironmentPattern(pattern, name) {
+    const parts = pattern.split("*");
+    if (parts.length === 1)
+        return pattern === name;
+    const first = parts[0];
+    const last = parts[parts.length - 1];
+    if (!name.startsWith(first))
+        return false;
+    let cursor = first.length;
+    for (let i = 1; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (part === "")
+            continue;
+        const at = name.indexOf(part, cursor);
+        if (at === -1)
+            return false;
+        cursor = at + part.length;
+    }
+    return name.length - cursor >= last.length && name.endsWith(last);
+}
+/**
+ * Environment-membership test (#1221): is `name` covered by this project's
+ * declared `environments`? A literal entry matches by equality; an entry
+ * containing `*` matches as a glob pattern (`"pr-*"` covers `pr-42`).
+ * Literals are checked first across the whole list, then patterns — so a
+ * name that is declared outright never depends on pattern order. `undefined`
+ * / empty `environments` returns `false`; callers that treat "no declared
+ * environments" as "anything goes" (e.g. {@link unknownEnvError} in
+ * `./env.ts`) guard that case themselves.
+ */
+export function matchesDeclaredEnvironment(environments, name) {
+    const names = environmentNames(environments) ?? [];
+    if (names.includes(name))
+        return true;
+    return names.some((declared) => isEnvironmentPattern(declared) && matchesEnvironmentPattern(declared, name));
+}
+/**
+ * The endpoint `name` declares (chant #1166) — `undefined` for a bare-string
+ * entry, an entry with no `endpoint` set, or a name this project doesn't
+ * declare at all. `./live-endpoint.ts`'s `applyLiveEndpoint` is the consumer:
+ * it injects this into the ambient env var each observing lexicon's CLI
+ * shell-out reads (e.g. `AWS_ENDPOINT_URL`), unless that var is already set —
+ * ambient always wins.
+ *
+ * A pattern entry (#1221) can carry an endpoint too: `{ name: "pr-*",
+ * endpoint }` supplies the endpoint for every `pr-<n>` environment. A literal
+ * entry always wins over a pattern — declaring `pr-special` alongside
+ * `pr-*` resolves `pr-special` to the literal entry's endpoint (or none).
+ */
+export function environmentEndpoint(environments, name) {
+    const found = environments?.find((e) => environmentName(e) === name) ??
+        environments?.find((e) => isEnvironmentPattern(environmentName(e)) && matchesEnvironmentPattern(environmentName(e), name));
+    return found && typeof found !== "string" ? found.endpoint : undefined;
+}
+/**
+ * Zod schema for ChantConfig validation.
+ */
+const EnvironmentEntrySchema = z.union([
+    z.string().min(1),
+    z.object({
+        name: z.string().min(1),
+        endpoint: z.string().min(1).optional(),
+    }),
+]);
+const LexiconEntrySchema = z.union([
+    z.string().min(1),
+    z.object({
+        name: z.string().min(1),
+        module: z.string().min(1),
+        root: z.string().min(1).optional(),
+    }).strict(),
+]);
+export const ChantConfigSchema = z.object({
+    lexicons: z.array(LexiconEntrySchema).optional(),
+    capabilities: z.array(z.string().min(1)).optional(),
+    environments: z.array(EnvironmentEntrySchema).optional(),
+    sourceDir: z.string().min(1).optional(),
+    lint: z.record(z.string(), z.unknown()).optional(),
+    ownership: z.object({
+        stack: z.string().min(1).optional(),
+        env: z.union([z.string().min(1), z.object({ param: z.string().min(1) })]).optional(),
+        enabled: z.boolean().optional(),
+    }).optional(),
+    build: z.object({
+        fold: z.boolean().optional(),
+    }).optional(),
+    buildParams: z.record(z.string(), z.object({
+        type: z.enum(["string", "number", "boolean"]),
+        default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+        enum: z.array(z.union([z.string(), z.number(), z.boolean()])).optional(),
+        env: z.string().min(1).optional(),
+        required: z.boolean().optional(),
+        description: z.string().optional(),
+    })).optional(),
+    release: z.object({
+        autoRecord: z.boolean().optional(),
+    }).optional(),
+    // Strict: a misspelt key here would leave Ops on the local runtime with
+    // nothing said (#2523).
+    run: z.object({
+        on: z.string().min(1).optional(),
+    }).strict().optional(),
+    sbom: z.object({
+        format: z.enum(["spdx", "cyclonedx"]).optional(),
+        enabled: z.boolean().optional(),
+    }).optional(),
+    signing: z.object({
+        keyless: z.boolean().optional(),
+        oidcIssuer: z.string().min(1).optional(),
+        identity: z.string().min(1).optional(),
+        identityIsRegexp: z.boolean().optional(),
+        key: z.string().min(1).optional(),
+    }).optional(),
+    vulnPolicy: z.object({
+        failSeverity: z.enum(["critical", "high", "medium", "low", "negligible", "unknown"]).optional(),
+        fixableOnly: z.boolean().optional(),
+        warnSeverity: z.enum(["critical", "high", "medium", "low", "negligible", "unknown"]).optional(),
+        failOnLicense: z.boolean().optional(),
+        failOnUnknownSeverity: z.boolean().optional(),
+        failOnKev: z.boolean().optional(),
+        failEpssAtOrAbove: z.number().min(0).max(1).optional(),
+        warnEpssAtOrAbove: z.number().min(0).max(1).optional(),
+        exploitabilityFixableOnly: z.boolean().optional(),
+        license: z.object({
+            allow: z.array(z.string()).optional(),
+            deny: z.array(z.string()).optional(),
+        }).optional(),
+        scanner: z.enum(["grype", "trivy"]).optional(),
+        vexSources: z.array(z.string()).optional(),
+    }).optional(),
+    knowledge: z.object({
+        dir: z.string().min(1).optional(),
+    }).optional(),
+    codegen: z.object({
+        outDir: z.string().min(1).optional(),
+    }).strict().optional(),
+    decide: decideConfigSchema.optional(),
+    exclude: z.array(z.string().min(1)).optional(),
+    include: z.array(z.string().min(1)).optional(),
+    rootOnly: z.boolean().optional(),
+}).passthrough();
+/**
+ * Default configuration when no config file exists.
+ */
+export const DEFAULT_CHANT_CONFIG = {};
+/**
+ * Load project configuration from a directory.
+ *
+ * Tries `chant.config.ts` first, then `chant.config.json`. Returns default
+ * config if neither exists.
+ *
+ * chant #1113 — `chant.config.ts` is project-authored code, so *where* it is
+ * evaluated is a security question, and the answer is
+ * `./config-sandbox.ts`'s: in a sandboxed child when this process was armed by
+ * `chant build --sandbox`, in-process (exactly as before) otherwise. Either
+ * way the result is the same plain configuration object, and validation
+ * ({@link normalizeConfig}) happens here, in the trusted process.
+ * `chant.config.json` is data, not code — it is parsed in-process under
+ * `--sandbox` too, because there is nothing to execute.
+ */
+export async function loadChantConfig(dir) {
+    // Try chant.config.ts first
+    const tsPath = join(dir, "chant.config.ts");
+    if (existsSync(tsPath)) {
+        const config = await evaluateProjectConfig(tsPath, dir);
+        return { config: normalizeConfig(config, tsPath), configPath: tsPath };
+    }
+    // Fall back to chant.config.json
+    const jsonPath = join(dir, "chant.config.json");
+    if (existsSync(jsonPath)) {
+        const { readFileSync } = await import("fs");
+        const content = readFileSync(jsonPath, "utf-8");
+        const parsed = JSON.parse(content);
+        return { config: normalizeConfig(parsed, jsonPath), configPath: jsonPath };
+    }
+    return { config: DEFAULT_CHANT_CONFIG };
+}
+/**
+ * Load project configuration by walking up from `startDir` to the project
+ * root (chant #1117), instead of trying only `startDir` itself.
+ *
+ * `chant build src/<stack>` (and anything else invoked with a subdirectory —
+ * `lint.policies`' `evaluateProjectPolicies`, `--components --generate`)
+ * builds scoped to that subdirectory, but `chant.config.ts` almost always
+ * lives at the project root, one or more levels up. Before this, callers
+ * either read `startDir` alone or bolted on a single `dirname()` fallback —
+ * fine for a one-level-deep stack, silently blind to anything deeper
+ * (a `src/<stack>` layout is exactly one level too deep: `buildParams`' declared
+ * `env:` mappings never resolved, so the env vars they named were inert under
+ * every `npm run synth:*` for two releases). Uses the same walk `chant
+ * lint`/`chant graph` already used ({@link findProjectConfig},
+ * shared with `./lint/config.ts`'s `findProjectRoot`) — one config-discovery
+ * contract for the whole CLI.
+ *
+ * chant #1502 — a lint-scoping fragment does not end the walk. The convention
+ * of a `src/chant.config.json` holding only `extends`/`rules` (cc-aws-canonical
+ * and most of examples/) sits BETWEEN the build directory and the real
+ * `chant.config.ts`, and stopping there re-introduced the exact silent
+ * fallback this walk exists to prevent: `chant build src` resolved the
+ * fragment, found no `ownership`, and built unstamped manifests that every
+ * owned-scoped live read then withheld. A fragment is skipped, not merged —
+ * lint resolution keeps its own nearest-wins walk untouched, and a JSON
+ * config declaring any project-level key still wins where it stands.
+ */
+export async function loadChantConfigUpward(startDir) {
+    const { dir, configPath } = findProjectConfigPastFragments(startDir);
+    if (configPath)
+        warnIfFragmentShadowsProjectConfig(configPath);
+    return loadChantConfig(dir);
+}
+/** The walk {@link loadChantConfigUpward} makes, lint-only fragments skipped, without its warning. */
+export function findProjectConfigPastFragments(startDir) {
+    let { dir, configPath } = findProjectConfig(startDir);
+    while (configPath && isLintOnlyFragment(configPath)) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        ({ dir, configPath } = findProjectConfig(parent));
+    }
+    return { dir, configPath };
+}
+/**
+ * The `exclude`/`include` globs of the project `startDir` belongs to, found by
+ * the same upward walk as {@link loadChantConfigUpward}. `undefined` when the
+ * project declares neither. `include` re-admits what `exclude` skips, and
+ * also what the discovery walk skips by default (#2527), so it means
+ * something on its own.
+ *
+ * A config that fails to load is left to the command's own config load to
+ * report, so discovery keeps working where it did before, unless the failure
+ * is in `exclude` or `include` themselves: ignoring those would discover the
+ * very files the project asked to skip.
+ */
+export async function resolveDiscoveryGlobs(startDir) {
+    const { dir, configPath } = findProjectConfigPastFragments(startDir);
+    if (!configPath)
+        return undefined;
+    let config;
+    try {
+        ({ config } = await loadChantConfig(dir));
+    }
+    catch (err) {
+        if (err instanceof InvalidChantConfigError && (err.key === "exclude" || err.key === "include"))
+            throw err;
+        return undefined;
+    }
+    const exclude = config.exclude ?? [];
+    const include = config.include ?? [];
+    if (exclude.length === 0 && include.length === 0)
+        return undefined;
+    return { root: dir, exclude, include };
+}
+/**
+ * The top-level keys of `./lint/config.ts`'s `LintConfigSchema` (plus the
+ * `$schema` editor convention). A `chant.config.json` whose keys all come from
+ * this set is a lint-scoping fragment, not a project config — see
+ * {@link loadChantConfigUpward}. `chant.config.ts` is never a fragment: it is
+ * project-authored code, and inspecting it would mean evaluating it.
+ */
+const LINT_FRAGMENT_KEYS = new Set(["$schema", "extends", "rules", "overrides", "plugins", "policies"]);
+/**
+ * JSON has no comments, so a project that wants to explain why it disabled a
+ * rule reaches for an underscore-prefixed key. chant #1711: both CockroachDB
+ * examples carried a `_ruleNotes` object in every stack's fragment, and one
+ * unrecognized key was enough to stop the walk — `chant build src/east`
+ * resolved the fragment as the project config, found no `buildParams`, no
+ * `ownership` and no `lexicons`, and emitted
+ * `gke-crdb-east-crdb@undefined.iam.gserviceaccount.com`. Silently.
+ *
+ * An underscore key is a comment. It does not make a fragment a project config.
+ */
+const isCommentKey = (k) => k.startsWith("_");
+export function isLintOnlyFragment(configPath) {
+    if (!configPath.endsWith("chant.config.json"))
+        return false;
+    try {
+        const parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return false;
+        const keys = Object.keys(parsed).filter((k) => !isCommentKey(k));
+        return keys.length > 0 && keys.every((k) => LINT_FRAGMENT_KEYS.has(k));
+    }
+    catch {
+        // Unreadable/unparseable JSON: let loadChantConfig surface the real error
+        // in place rather than silently walking past it.
+        return false;
+    }
+}
+/**
+ * The `chant.config.json` the walk stopped at declares no project-level key at
+ * all — so it is about to be used as the project config while carrying none of
+ * the things a project config exists to carry.
+ *
+ * The comment-key rule above fixes the case that bit (chant #1711), but the
+ * hole it came from is general: any key outside {@link LINT_FRAGMENT_KEYS}
+ * turns a fragment into the project config, and the consequence is a build
+ * that silently loses every parameter, the ownership marker and the lexicon
+ * list. This says so, naming the key responsible, instead of leaving it to be
+ * discovered in the output.
+ */
+function warnIfFragmentShadowsProjectConfig(configPath) {
+    if (!configPath.endsWith("chant.config.json"))
+        return;
+    try {
+        const parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return;
+        const keys = Object.keys(parsed).filter((k) => !isCommentKey(k));
+        if (keys.some((k) => !LINT_FRAGMENT_KEYS.has(k)) && !keys.some((k) => PROJECT_CONFIG_KEYS.has(k))) {
+            const offenders = keys.filter((k) => !LINT_FRAGMENT_KEYS.has(k));
+            console.error(`warning: ${configPath} is being used as the project config, but declares no project-level ` +
+                `key (${[...PROJECT_CONFIG_KEYS].slice(0, 4).join(", ")}, …). ` +
+                `${offenders.length === 1 ? "The key" : "The keys"} ${offenders.map((k) => `"${k}"`).join(", ")} ` +
+                `stopped the walk to the real one — any config above this file is being ignored. ` +
+                `Prefix a comment key with "_", or move the key to the project config. (chant #1711)`);
+        }
+    }
+    catch {
+        // Unreadable/unparseable: loadChantConfig reports it properly.
+    }
+}
+/** Top-level keys that make a config a *project* config rather than a lint fragment. */
+const PROJECT_CONFIG_KEYS = new Set(Object.keys(ChantConfigSchema.shape).filter((k) => k !== "lint"));
+/** Whether an `ownership.env` entry is a build-parameter reference rather than a literal. */
+export function isOwnershipParamRef(env) {
+    return typeof env === "object" && env !== null && typeof env.param === "string";
+}
+/**
+ * The ownership stack identity alone — `ownership.stack` when marking is on
+ * (no `stack`, or `enabled: false`, means off). For callers that need the
+ * stack and nothing else (a field manager, a prune selector) and so have no
+ * build parameters to resolve `env` against.
+ */
+export function resolveOwnershipStack(config) {
+    const o = config.ownership;
+    if (!o || !o.stack || o.enabled === false)
+        return undefined;
+    return o.stack;
+}
+/**
+ * Resolve the `env` half of the ownership marker (#1396). A literal is
+ * returned as-is. A `{ param }` reference is looked up in this build's resolved
+ * build parameters and must find one: a reference to a parameter that was
+ * never declared, or that resolved to no value, throws rather than quietly
+ * stamping a marker without an env — an env-less marker is exactly what lets
+ * a prod deployment go unseen by `--owned` filtering scoped to prod.
+ */
+export function resolveOwnershipEnv(config, buildParams) {
+    const env = config.ownership?.env;
+    if (!isOwnershipParamRef(env))
+        return env;
+    const name = env.param;
+    const declared = config.buildParams?.[name];
+    if (!declared) {
+        throw new Error(`ownership.env references build parameter "${name}", which chant.config.ts's buildParams does not declare`);
+    }
+    const resolved = buildParams?.find((p) => p.name === name);
+    if (!resolved) {
+        throw new Error(`ownership.env references build parameter "${name}", which resolved to no value for this build — pass --param ${name}=<value>${declared.env ? `, set ${declared.env}` : ""}, or give it a default`);
+    }
+    return String(resolved.value);
+}
+/**
+ * Resolve the ownership marker to stamp from project config, or undefined when
+ * ownership marking is off (no `stack`, or `enabled: false`). `buildParams` is
+ * this build's resolved parameters (`resolveBuildParams`'s provenance), which
+ * an `ownership.env: { param }` reference resolves against — see {@link
+ * resolveOwnershipEnv}; it throws when the reference cannot be satisfied.
+ */
+export function resolveOwnershipMarker(config, buildParams) {
+    const stack = resolveOwnershipStack(config);
+    if (stack === undefined)
+        return undefined;
+    return { stack, env: resolveOwnershipEnv(config, buildParams) };
+}
+/**
+ * The divergence #1396 is about, made loud when it cannot be removed: a
+ * project whose `ownership.env` is a literal while it also declares a build
+ * parameter named `env` has two answers to "which environment is this", and
+ * the manifest carries both (the ownership marker from config, the labels
+ * from the parameter). Returns a warning naming both values when they differ;
+ * undefined when there is nothing to say (no literal, no `env` parameter, or
+ * the two agree). The fix is the `{ param: "env" }` reference.
+ */
+export function ownershipEnvDisagreement(config, buildParams) {
+    const literal = config.ownership?.env;
+    if (typeof literal !== "string")
+        return undefined;
+    if (resolveOwnershipStack(config) === undefined)
+        return undefined;
+    const param = buildParams?.find((p) => p.name === "env");
+    if (!param || String(param.value) === literal)
+        return undefined;
+    return (`ownership.env is "${literal}" but the env build parameter resolved to ${JSON.stringify(param.value)} (${param.source}) — ` +
+        `the ownership marker and params.env disagree about which environment this build is for. ` +
+        `Use ownership: { env: { param: "env" } } so the marker follows the parameter.`);
+}
+/**
+ * Whether auto-emitting a release-ledger record after a successful `chant
+ * run --components` deploy should be skipped (#597). Opt-out, not opt-in:
+ * recording happens unless the CLI's `--no-release-record` flag was passed
+ * (`cliFlag`) or the project config sets `release.autoRecord: false` — the
+ * flag always wins for that one invocation, regardless of config.
+ */
+export function resolveAutoReleaseDisabled(config, cliFlag) {
+    if (cliFlag)
+        return true;
+    return config.release?.autoRecord === false;
+}
+/**
+ * Whether `chant build` should use the fold path (#1022, epic #1019)
+ * instead of running each source module. DEFAULT-ON since chant #1134: fold
+ * is the build path unless something turns it off. Precedence, most specific
+ * wins: an explicit CLI flag (`--fold` → true, `--no-fold` → false, arriving
+ * here as `cliFlag`), then the project config's `build.fold`, then the
+ * default of `true`. The epic's evidence base for the flip — coverage,
+ * byte-identity, and the sandbox execution boundary — is recorded on #1134
+ * and #1090.
+ */
+export function resolveFoldEnabled(config, cliFlag) {
+    if (cliFlag !== undefined)
+        return cliFlag;
+    if (config.build?.fold !== undefined)
+        return config.build.fold;
+    return true;
+}
+/**
+ * Whether `chant build` should run its run-fallback files (or, without
+ * `--fold`, every file) in an isolated sandboxed child process rather than
+ * in-process (chant #1045 Phase 2). Opt-in: off unless the CLI's `--sandbox`
+ * flag was passed (`cliFlag`) or the project config sets `build.sandbox:
+ * true` — the flag always wins for that one invocation, regardless of
+ * config. Independent of {@link resolveFoldEnabled}: sandboxing without
+ * folding isolates every discovered file; sandboxing with folding isolates
+ * only the per-file run-fallback remainder.
+ */
+export function resolveSandboxEnabled(config, cliFlag) {
+    if (cliFlag)
+        return true;
+    return config.build?.sandbox === true;
+}
+/**
+ * Resolve which SBOM format a `generate-sbom` step should request (#606),
+ * given the project's `chant.config.ts` `sbom.format` and an optional
+ * component/step-level override. Precedence, most to least specific:
+ * `stepFormat` (the component's own `build.sbom.format` or an explicit
+ * `generate-sbom` step input) > `config.sbom.format` (project default) >
+ * `DEFAULT_SBOM_FORMAT` ("spdx", ./components/verbs/sbom-generator.ts).
+ * Never hardcodes one format as *the* format — this is purely precedence
+ * resolution over the two first-class formats SPDX/CycloneDX.
+ */
+export function resolveSbomFormat(config, stepFormat) {
+    return stepFormat ?? config.sbom?.format ?? DEFAULT_SBOM_FORMAT;
+}
+/**
+ * Resolve project-wide signing defaults from `chant.config.ts`'s `signing`
+ * section (#622). Keyless unless `signing.keyless === false` — the same
+ * "default is the safe choice, override is explicit" precedence
+ * `resolveOwnershipMarker`/`resolveAutoReleaseDisabled` already use for their
+ * respective opt-outs.
+ */
+export function resolveSigningDefaults(config) {
+    const s = config.signing;
+    const keyless = s?.keyless !== false;
+    return {
+        keyless,
+        ...(!keyless && s?.key ? { key: { key: s.key } } : {}),
+        identityPolicyDefaults: {
+            expectedIssuer: s?.oidcIssuer,
+            expectedIdentity: s?.identity,
+            identityIsRegexp: s?.identityIsRegexp,
+            key: s?.keyless === false ? s?.key : undefined,
+        },
+    };
+}
+/**
+ * Resolve the `vuln-gate` policy overrides from `chant.config.ts`'s
+ * `vulnPolicy` section (#626). Returns only the fields the project set; the
+ * gate merges these over its own `DEFAULT_VULN_POLICY`
+ * (`./components/verbs/vuln-gate.ts`), so an empty/absent section yields the
+ * beginner-safe defaults. `scanner`/`vexSources` are not policy fields — they
+ * configure how the capability is constructed and are read separately.
+ */
+export function resolveVulnPolicy(config) {
+    const v = config.vulnPolicy;
+    if (!v)
+        return {};
+    const out = {};
+    if (v.failSeverity)
+        out.failSeverity = v.failSeverity;
+    if (v.fixableOnly !== undefined)
+        out.fixableOnly = v.fixableOnly;
+    if (v.warnSeverity)
+        out.warnSeverity = v.warnSeverity;
+    if (v.failOnLicense !== undefined)
+        out.failOnLicense = v.failOnLicense;
+    if (v.failOnUnknownSeverity !== undefined)
+        out.failOnUnknownSeverity = v.failOnUnknownSeverity;
+    // `!== undefined`, never truthiness: `failEpssAtOrAbove: 0` (match any scored
+    // finding) and an explicit `failOnKev: false` override must both survive.
+    if (v.failOnKev !== undefined)
+        out.failOnKev = v.failOnKev;
+    if (v.failEpssAtOrAbove !== undefined)
+        out.failEpssAtOrAbove = v.failEpssAtOrAbove;
+    if (v.warnEpssAtOrAbove !== undefined)
+        out.warnEpssAtOrAbove = v.warnEpssAtOrAbove;
+    if (v.exploitabilityFixableOnly !== undefined)
+        out.exploitabilityFixableOnly = v.exploitabilityFixableOnly;
+    if (v.license)
+        out.license = v.license;
+    return out;
+}
+/**
+ * Resolve the OKF knowledge bundle directory (#1864, design #1059):
+ * `knowledge.dir` relative to `projectPath` when configured, else the
+ * `knowledge/` convention beside `chant.config.ts`. Never checks existence —
+ * a project with no bundle yet resolves a path all the same, and
+ * `okf-read.ts`'s `loadOkfBundle` treats a missing directory as an empty
+ * bundle rather than an error.
+ */
+export function resolveKnowledgeDir(config, projectPath) {
+    return join(projectPath, config.knowledge?.dir ?? "knowledge");
+}
+/**
+ * A config that failed schema validation. `key` is the top-level key of the
+ * first problem. `name` stays `"Error"`, so the printed error reads as before.
+ */
+export class InvalidChantConfigError extends Error {
+    constructor(message, key) {
+        super(message);
+        this.key = key;
+    }
+}
+/**
+ * Validate and normalize a raw config object into ChantConfig shape.
+ */
+function normalizeConfig(raw, source) {
+    if (typeof raw !== "object" || raw === null) {
+        return DEFAULT_CHANT_CONFIG;
+    }
+    const result = ChantConfigSchema.safeParse(raw);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const path = issue.path.length > 0 ? issue.path.join(".") : undefined;
+        const loc = source ? ` in ${source}` : "";
+        throw new InvalidChantConfigError(`Invalid chant config${loc}: ${path ? `${path}: ` : ""}${issue.message}`, issue.path.length > 0 ? String(issue.path[0]) : undefined);
+    }
+    // chant #2520 — a lexicon declared by module path. The path is recorded for
+    // the loaders and the entry becomes its name, so every reader of `lexicons`
+    // keeps seeing names. A config of plain names is returned untouched.
+    const lexicons = raw.lexicons;
+    const baseDir = source !== undefined ? dirname(source) : process.cwd();
+    const sourceDir = raw.sourceDir;
+    // chant#2590 — a declared `root` must stay inside the project and must not
+    // contain its source directory. Refused here rather than narrowed, since
+    // the project asked for it by name.
+    for (const [i, entry] of (lexicons ?? []).entries()) {
+        if (typeof entry === "string" || entry.root === undefined)
+            continue;
+        const { problem } = pathLexiconRoot(entry, baseDir, sourceDir);
+        if (problem !== undefined) {
+            const loc = source ? ` in ${source}` : "";
+            throw new InvalidChantConfigError(`Invalid chant config${loc}: lexicons.${i}.root: ${problem}`, "lexicons");
+        }
+    }
+    const recorded = registerLexiconDeclarations(lexicons, baseDir, sourceDir);
+    if (Object.keys(recorded).length > 0) {
+        return { ...raw, lexicons: lexiconNames(lexicons), lexiconModules: recorded };
+    }
+    return raw;
+}

package/dist/content-digest.js

@@ -0,0 +1,23 @@
+/**
+ * The one content digest chant computes itself (chant #2514).
+ *
+ * `contentDigest(x)` is `"sha256:"` followed by the lowercase hex SHA-256 of
+ * the UTF-8 bytes of `x`. Anything core hashes goes through it, and anything
+ * structured is first put in canonical form with `canonicalJson`
+ * (./effect-receipt.ts), so the same value always hashes the same way. The
+ * build archive re-exports it from ./components/verbs/build-archive.ts, where
+ * it used to live.
+ *
+ * Before #2514 this function computed a 32-bit string hash and repeated its
+ * eight hex digits eight times. Values recorded then are recognised and
+ * flagged by ./lifecycle/legacy-digest.ts.
+ */
+import { createHash } from "node:crypto";
+/** `sha256:<64 hex>` over the UTF-8 bytes of `input`. */
+export function contentDigest(input) {
+    return `sha256:${createHash("sha256").update(input, "utf8").digest("hex")}`;
+}
+/** Lowercase hex SHA-256 of `bytes`, with no prefix: the form a decision's evidence pin holds (#2549). */
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}