@intentius/chant 0.124.13 → 0.124.15

package/dist/cli/commands/lint.js

@@ -0,0 +1,948 @@
+import { resolve, relative, dirname } from "path";
+import { readFileSync, writeFileSync, readdirSync } from "fs";
+import { runLint, parseDisableComments } from "../../lint/engine.js";
+import { loadPlugin, loadPlugins, resolveProjectLexicons } from "../plugins.js";
+import { findInfraFiles, detectLexicons } from "../../index.js";
+import { formatStylish, formatJson, formatSarif } from "../reporters/stylish.js";
+import { loadLocalRules } from "../../lint/rule-loader.js";
+import { loadCoreRules } from "../../lint/rules/index.js";
+import { loadComponentChecks } from "../../lint/rules/comp/index.js";
+import { runComponentChecks } from "../../lint/component-checks.js";
+import { buildCapabilityRegistry } from "../../components/capability-plugin-loader.js";
+import { coreOpChecks } from "../../lint/rules/op/index.js";
+import { loadActivityContracts } from "../../op/activity-contract-registry.js";
+import { runPostSynthChecks } from "../../lint/post-synth.js";
+import { rule } from "../../lint/declarative.js";
+import { watchDirectory, formatTimestamp, formatChangedFiles } from "../watch.js";
+import { formatError, formatInfo } from "../format.js";
+import { hasDiscoveryMarkerSync, isSourceFileName } from "../../discovery/files.js";
+import { walkDiscovery, workspaceMemberDirs } from "../../discovery/walk.js";
+import { buildParamValues, resolveBuildParams } from "../../build-params.js";
+import { setBuildParams } from "../../params.js";
+import { isNoLexiconDetected } from "../../detectLexicon.js";
+import { build } from "../../build.js";
+import { loadChantConfigUpward, resolveOwnershipEnv, resolveOwnershipMarker } from "../../config.js";
+import { resolveBuildModes, resolveProjectBuildOptions } from "../build-options.js";
+import { resolveTelemetryAttribution } from "../../telemetry-attribution.js";
+import { applyConfiguredPreset, applyConfiguredSeverity, resolvePresetIds } from "../../lint/config.js";
+import { applyInlineSuppressions } from "../../lint/suppressions.js";
+import { getProvenance } from "../../provenance.js";
+import { runLexiconPostSynthChecks } from "./build.js";
+import { armSandboxPolicyExecution, runProjectPolicies } from "../../lint/policy-sandbox.js";
+import { ensureTypeScriptLoader } from "../../ts-loader.js";
+// Import config loader
+import { loadConfig, resolveRulesForFile, resolveConfiguredSeverity, findProjectRoot } from "../../lint/config.js";
+import { loadChantConfig, resolveKnowledgeDir, resolveDiscoveryGlobs } from "../../config.js";
+import { findProjectConfig } from "../../project-root.js";
+import { loadOkfBundle } from "../../okf-read.js";
+/**
+ * Type guard to check if a value conforms to the LintRule interface.
+ */
+export function isLintRule(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "id" in value &&
+        typeof value.id === "string" &&
+        "severity" in value &&
+        "category" in value &&
+        "check" in value &&
+        typeof value.check === "function");
+}
+/**
+ * Load custom lint rules from plugin files.
+ * Each plugin file is dynamically imported and all exports conforming to LintRule are collected.
+ *
+ * chant #1051 — this (and `loadLocalRules`, `../../lint/rule-loader.ts`, for
+ * `.chant/rules/*.ts`) is unconditional project-source `import()` with no
+ * `--sandbox` equivalent, the same class of gap #1051 closes for
+ * `discoverComponents`. Deliberately NOT sandboxed here, and not a "decide by
+ * omission": a `LintRule` is not a one-shot data producer like `Component`/
+ * `Declarable` — its `check(context)` is a function the rule engine invokes
+ * inline, once per linted file, for the whole `chant lint` run. There is no
+ * cheap "collect once, JSON-serialize the result, hand it back" shape the way
+ * there is for a `Component` (plain JSON) or an entity (a wire codec) —
+ * `check` has to keep running as live JS in whichever process calls it. A
+ * shallow fix that sandboxed only the *import* step (mirroring
+ * `discoverComponents`) would give a false sense of safety: it would close
+ * off "malicious top-level module code" but leave `check()`'s own executable
+ * body — the dominant part of a rule's attack surface, since it runs for
+ * every file, every lint invocation — entirely unsandboxed regardless. A real
+ * fix needs either the AST/`ts.SourceFile` itself to cross the sandbox
+ * boundary or the whole custom-rule evaluation to run inside the child; both
+ * are materially harder, separate design problems from this issue's `Component`
+ * fix and are tracked separately (chant #1052).
+ */
+export async function loadPluginRules(plugins, configDir) {
+    const pluginRules = new Map();
+    for (const pluginPath of plugins) {
+        const resolved = resolve(configDir, pluginPath);
+        let mod;
+        try {
+            ensureTypeScriptLoader();
+            mod = await import(resolved);
+        }
+        catch (err) {
+            throw new Error(`Failed to load plugin "${pluginPath}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+        for (const value of Object.values(mod)) {
+            if (isLintRule(value)) {
+                pluginRules.set(value.id, value);
+            }
+        }
+    }
+    return pluginRules;
+}
+/**
+ * The diagnostic id `chant lint` reports a lexicon it could not resolve under
+ * (chant #2222).
+ *
+ * Deliberately outside the COR/EVL/COMP/OPS families: those are *rules*, each
+ * with a `check()` the engine runs per file, a documented page, a configurable
+ * severity and a `chant-disable` escape hatch. This is none of those. It is
+ * the lint run reporting that it could not assemble the rule set the project
+ * asked for, so it is not silenceable through `rules: { ... : "off" }` or a
+ * disable comment. Silencing it would put back the exact "green on a broken
+ * project" this id exists to prevent.
+ */
+export const LEXICON_RESOLUTION_RULE_ID = "LEX001";
+/**
+ * Turn a lexicon-resolution failure into the error diagnostic `chant lint`
+ * reports it as. The message is the underlying error's own, unwrapped, so it
+ * is character-for-character what `chant build` prints after `error: ` for the
+ * same project (`loadPluginsOrExit`, ../main.ts): one failure, one wording.
+ *
+ * Attributed to the project's `chant.config.*` where there is one, since that
+ * is the file that names the lexicon; to the project root otherwise.
+ */
+function lexiconResolutionDiagnostic(projectRoot, error) {
+    return {
+        file: findProjectConfig(projectRoot).configPath ?? projectRoot,
+        line: 1,
+        column: 1,
+        ruleId: LEXICON_RESOLUTION_RULE_ID,
+        severity: "error",
+        message: error.message,
+    };
+}
+/**
+ * The diagnostic id `chant lint` reports a lint target that does not build
+ * under (chant #3750). The lexicons' post-synth checks read a build result, so
+ * when the build fails they cannot run; this says so instead of letting the
+ * lint pass in silence. Like {@link LEXICON_RESOLUTION_RULE_ID} it is not a
+ * rule: it has no severity setting and no disable form. The message is the
+ * build's own.
+ */
+export const BUILD_FAILURE_RULE_ID = "LEX002";
+/**
+ * The plugins of lexicons that the project's source imports from and that are not in `configured`, for their
+ * property-kind class names (#3184). A package that is not installed, or that fails to load, is skipped.
+ */
+async function loadImportedPropertyPlugins(projectPath, configured) {
+    let imported;
+    try {
+        imported = await detectLexicons(await findInfraFiles(projectPath));
+    }
+    catch {
+        return [];
+    }
+    const plugins = [];
+    for (const name of imported) {
+        if (configured.includes(name))
+            continue;
+        try {
+            plugins.push(await loadPlugin(name));
+        }
+        catch {
+            // Not installed here; the import is the build's problem to report, not lint's.
+        }
+    }
+    return plugins;
+}
+/**
+ * Load all lint rules: core COR/EVL rules, then lexicon plugin rules.
+ *
+ * Also returns the active lexicons' registered intrinsics (chant #1106) —
+ * gathered here because this is where the project's lexicon plugins are
+ * already resolved and loaded (`loadPlugins`), the same set `../commands/
+ * build.ts` reads `plugin.intrinsics?.()` off of for the fold path. Handed
+ * back alongside `rules` so `lintCommand` can thread it into every
+ * `runLint` call without loading plugins a second time.
+ */
+async function loadAllPluginRules(projectPath) {
+    const rules = new Map();
+    // Load core COR/EVL rules directly
+    for (const r of loadCoreRules()) {
+        rules.set(r.id, r);
+    }
+    // Resolve project lexicons (e.g. ["aws"]) from config or detection, then
+    // load their plugins.
+    //
+    // chant #2222: a failure in either step is handed back to `lintCommand`
+    // (which reports it as {@link LEXICON_RESOLUTION_RULE_ID}) rather than
+    // swallowed or thrown. Both steps fail on the same project state: a
+    // `chant.config.ts` that names a lexicon whose package is not installed
+    // throws out of `loadPlugins`, and one that *imports* that package throws
+    // out of `resolveProjectLexicons` before the names are ever read. Before
+    // this, the first case crashed `chant lint` with a stack trace and the
+    // second was caught here and discarded, so `chant lint` printed "No
+    // problems found" and exited 0 on a project `chant build` refuses to
+    // build. A CI job that lints before it builds reported green on a project
+    // whose lexicon was missing.
+    //
+    // The one failure that stays quiet is the one the original `catch` was
+    // written for and named in its comment: a project that declares no
+    // `lexicons` and imports none from its source files, where the detection
+    // fallback throws `NO_LEXICON_DETECTED_MESSAGE`. That project lints under
+    // the core rules alone and always has. It is told apart by the exported
+    // sentinel rather than by a string literal copied to this file, so the two
+    // cannot drift apart.
+    let lexiconNames = [];
+    let lexiconError;
+    try {
+        lexiconNames = await resolveProjectLexicons(projectPath);
+    }
+    catch (err) {
+        if (!isNoLexiconDetected(err)) {
+            lexiconError = err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    // Load only project lexicon plugins (no "chant" injection)
+    let plugins = [];
+    if (!lexiconError) {
+        try {
+            plugins = await loadPlugins(lexiconNames);
+        }
+        catch (err) {
+            lexiconError = err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    // chant #1106 — the same plugins' registered intrinsics (`Ref`, `GetAtt`,
+    // ...), so EVL001 can answer "does this call fold?" exactly like fold()
+    // does instead of flagging every call as a violation. A plugin's
+    // `intrinsics` is an optional extension (not every lexicon defines any),
+    // hence the guard.
+    const intrinsics = plugins.flatMap((plugin) => plugin.intrinsics?.() ?? []);
+    // chant #2957 — the class names these plugins declare property-kind, so
+    // COR001, COR004 and COR009 leave out declarables that live inside a
+    // resource (a Grafana panel inside its dashboard) instead of treating
+    // them as resources.
+    const propertyClasses = new Set(plugins.flatMap((plugin) => plugin.propertyClassNames?.() ?? []));
+    // chant #3184: a lexicon the source imports from but the config does not list (grafana in a k8s project that
+    // holds a dashboard ConfigMap, after `chant import`) still declares which of its classes are property-kind. Only
+    // those names are taken from it; its rules and intrinsics stay out, since the project did not ask for them.
+    if (!lexiconError) {
+        for (const plugin of await loadImportedPropertyPlugins(projectPath, lexiconNames)) {
+            for (const name of plugin.propertyClassNames?.() ?? [])
+                propertyClasses.add(name);
+        }
+    }
+    for (const plugin of plugins) {
+        if (plugin.lintRules) {
+            for (const r of plugin.lintRules()) {
+                rules.set(r.id, r);
+            }
+        }
+        // Compile declarative rules from plugins
+        if (plugin.declarativeRules) {
+            for (const spec of plugin.declarativeRules()) {
+                const compiled = rule(spec);
+                rules.set(compiled.id, compiled);
+            }
+        }
+    }
+    // Load project-local rules from .chant/rules/
+    const localRules = await loadLocalRules(projectPath);
+    for (const r of localRules) {
+        rules.set(r.id, r);
+    }
+    return { rules, intrinsics, propertyClasses, plugins, ...(lexiconError ? { lexiconError } : {}) };
+}
+/**
+ * Every TypeScript file `chant lint` reads under `dir`, through the one
+ * discovery walk (`../../discovery/walk.ts`, #2527): git-ignored paths
+ * (vendored trees and the like, which the project never wrote), dot-directories,
+ * `dist` and, inside a project, child projects are skipped, and so is what the
+ * project's `exclude` globs (#2519) name, unless `include` re-admits it. Test
+ * and spec files, chant-generated files and skip-marked files are left out.
+ * Symlinks are followed, as lint always did.
+ */
+async function getTypeScriptFiles(dir) {
+    // A missing or non-directory path fails here, as lint's own walk always did;
+    // the shared walk skips an unreadable directory in silence.
+    readdirSync(dir);
+    return walkDiscovery({
+        walker: "lint",
+        root: dir,
+        globs: await resolveDiscoveryGlobs(dir),
+        excludeDirs: await workspaceMemberDirs(dir),
+        followSymlinks: true,
+        accept: (name, full) => isSourceFileName(name) && !hasDiscoveryMarkerSync(full),
+    });
+}
+/**
+ * Get default rules and options, optionally applying per-file overrides.
+ *
+ * `projectRoot` is where the config lives (see `findProjectRoot`); `filePath`,
+ * when given, must be relative to that root so `lint.overrides` globs
+ * (`src/lib/**`) match regardless of which subpath is being linted.
+ */
+function getDefaultRules(projectRoot, filePath, allRules = new Map()) {
+    const config = loadConfig(projectRoot);
+    const effectiveRules = filePath ? resolveRulesForFile(config, filePath) : config.rules;
+    const rules = [];
+    const ruleOptions = new Map();
+    for (const [ruleId, rule] of allRules) {
+        // chant #1138 — the same resolution post-synth checks and COMP* checks
+        // now go through too (`resolveConfiguredSeverity`, ../../lint/config.ts),
+        // so `lint.rules: { ID: "off" }` suppresses a rule id identically no
+        // matter which phase produced it.
+        const { severity, options } = resolveConfiguredSeverity(effectiveRules, ruleId, rule.severity);
+        // Skip rules that are explicitly turned off
+        if (severity === "off")
+            continue;
+        // Override severity from config (a no-op when the rule wasn't mentioned —
+        // `severity` is then just `rule.severity` again)
+        rules.push({ ...rule, severity });
+        // Store options if present
+        if (options) {
+            ruleOptions.set(ruleId, options);
+        }
+    }
+    return { rules, ruleOptions };
+}
+/**
+ * Run the COMP* composition checks (#562) over the discovered `Component`
+ * graph and convert their results into plain `LintDiagnostic`s so they merge
+ * into the same `chant lint` output (stylish/json/sarif) and the same
+ * error-count gating as every COR/EVL diagnostic.
+ *
+ * These checks operate on the whole discovered component graph, not one
+ * `ts.SourceFile`, so they carry no real line/column — reported at `1:1` in
+ * the file the component was declared in (matching COR009's whole-file
+ * diagnostic convention, see ../../lint/rules/file-declarable-limit.ts).
+ * Config severity overrides (`lint.rules["COMP001"]`, including `"off"`) are
+ * honored the same way `getDefaultRules` honors them for AST rules. Only the
+ * *file-level* disable directive form (`// chant-disable` /
+ * `// chant-disable COMP004 -- reason`, anywhere in the file) is honored —
+ * `-line`/`-next-line` need an exact line to match against, which a
+ * whole-component diagnostic does not have; see
+ * docs/lint-rules/composition.mdx for this documented limitation.
+ */
+/**
+ * Build the registry-derived context composition checks need — the set of
+ * capability kinds registered for this project (core's starter set plus the
+ * active lexicons' leaves, e.g. `cfn-deploy` when `lexicons: ["aws"]`) and each
+ * verb's rollback disposition — so COMP005/COMP003 read real registry facts
+ * rather than hard-coding verb lists. A verb's rollback policy is its own
+ * declaration (`rollbackPolicy`), else derived: a paired `rollback` method is
+ * `"native"`, everything else `"none-by-design"`. Tolerant: any failure (an
+ * unresolvable lexicon, a config-less directory) returns `undefined` fields,
+ * letting the checks fall back to core's starter set.
+ */
+async function resolveRegistryContext(infraPath) {
+    try {
+        const lexicons = await resolveProjectLexicons(infraPath).catch(() => []);
+        const registry = await buildCapabilityRegistry({ lexicons });
+        const kinds = registry.kinds();
+        const rollbackPolicies = new Map();
+        for (const kind of kinds) {
+            const capability = registry.resolve(kind);
+            rollbackPolicies.set(kind, capability.rollbackPolicy ?? (capability.rollback ? "native" : "none-by-design"));
+        }
+        return { knownKinds: new Set(kinds), rollbackPolicies };
+    }
+    catch {
+        return {};
+    }
+}
+async function runComponentCheckDiagnostics(infraPath, sandbox, buildParams) {
+    // Discovery stays scoped to the lint arg; COMP* severity overrides come from
+    // the project-root config, same as the AST-rule pass.
+    const config = loadConfig(findProjectRoot(infraPath));
+    const checks = loadComponentChecks();
+    const allCheckIds = new Set(checks.map((c) => c.id));
+    const registryContext = await resolveRegistryContext(infraPath);
+    const raw = await runComponentChecks(infraPath, checks, registryContext, sandbox, buildParams);
+    const fileDirectivesCache = new Map();
+    const fileLevelDisable = (file, checkId) => {
+        let directives = fileDirectivesCache.get(file);
+        if (!directives) {
+            let content = "";
+            try {
+                content = readFileSync(file, "utf-8");
+            }
+            catch {
+                // File may be unreadable (e.g. a synthetic discovery-error path) — no directives to honor.
+            }
+            directives = parseDisableComments(content);
+            fileDirectivesCache.set(file, directives);
+        }
+        for (const directive of directives) {
+            if (directive.type !== "file")
+                continue;
+            if (!directive.ruleIds)
+                return { suppressed: true, reason: directive.reason };
+            if (directive.ruleIds.some((id) => allCheckIds.has(id) || id === "COMP000") && directive.ruleIds.includes(checkId)) {
+                return { suppressed: true, reason: directive.reason };
+            }
+        }
+        return { suppressed: false };
+    };
+    const toLintDiagnostic = (d, severity) => ({
+        file: d.file,
+        line: 1,
+        column: 1,
+        ruleId: d.checkId,
+        severity,
+        message: d.message,
+    });
+    const diagnostics = [];
+    const suppressed = [];
+    for (const d of raw) {
+        // Discovery errors (COMP000) always surface at error severity — not user-configurable.
+        let severity = d.severity;
+        if (d.checkId !== "COMP000") {
+            // chant #1138 — same resolution function AST rules and post-synth
+            // checks use (`resolveConfiguredSeverity`, ../../lint/config.ts).
+            const resolved = resolveConfiguredSeverity(config.rules, d.checkId, d.severity);
+            if (resolved.severity === "off")
+                continue;
+            severity = resolved.severity;
+        }
+        const disable = fileLevelDisable(d.file, d.checkId);
+        const diagnostic = toLintDiagnostic(d, severity);
+        if (disable.suppressed) {
+            suppressed.push({ ...diagnostic, reason: disable.reason });
+        }
+        else {
+            diagnostics.push(diagnostic);
+        }
+    }
+    return { diagnostics, suppressed };
+}
+/**
+ * Run the OPS* Op-model post-synth checks (#2122, epic #2114 sub-issue 6 —
+ * OPS012/OPS013/OPS014, ported from a hosting lexicon's own
+ * TMP012/TMP013/TMP014) over every `*.op.ts` file under the lint target and
+ * merge them into the same diagnostics/suppressed lists `chant lint` already
+ * reports through, the same treatment {@link runComponentCheckDiagnostics}
+ * above gives COMP*.
+ *
+ * Deliberately scoped DOWNWARD from `infraPath` — the same scan
+ * `getTypeScriptFiles` already ran to build `files` — rather than
+ * `../../op/discover.ts`'s `discoverOps`, which walks UP to the nearest
+ * project root (or the git root, absent a config file) precisely because a
+ * real project's `ops/` convention sits outside `sourceDir`. That upward
+ * walk is right for `chant run`/`chant build`, which always operate on one
+ * whole project; it is wrong here, because `chant lint <path>` (and every
+ * fixture-scoped test that calls this file's `lintCommand`) may point at a
+ * directory with no `chant.config.*` above it short of this repo's own git
+ * root — which would make this check import every `*.op.ts` file in the
+ * entire monorepo on every such call. Scanning only under `infraPath`, like
+ * every other check in this function, keeps this check's cost proportional
+ * to the target the caller actually asked to lint.
+ *
+ * Each `*.op.ts` file's default export is imported directly and used as-is
+ * (it is already the `Declarable` `OpResource` instance `Op()` built) — no
+ * serializer and no lexicon plugin needed, since OPS012/OPS013/OPS014 only
+ * ever read `ctx.entities`, never `ctx.outputs`. That's what lets this fire
+ * even on a project with no lexicons configured at all.
+ *
+ * The project's configured lexicon NAMES are read, though (chant #2101), to
+ * resolve the activity contracts each one declares at
+ * `@intentius/chant-lexicon-<name>/op/activity-contracts`. The plugins
+ * `lintCommand` already loaded are passed in (chant #2520), so a plugin's
+ * `activityContracts()` member counts here as it does in `chant build`, and
+ * a lexicon declared by module path is covered. Without them a step calling a
+ * lexicon's activity is flagged for the absence of a contract that lexicon
+ * does declare, which is the whole point of OPS013 firing outside a build.
+ *
+ * Reported at `1:1` in the file the Op was declared in, the same whole-file
+ * convention COMP* diagnostics use — a post-synth finding carries no real
+ * line/column (../../lint/post-synth.ts's `PostSynthDiagnostic` doc) and
+ * there's no per-file disable-directive suppression for the same reason
+ * (that doc again), so this reads only `lint.rules` severity overrides, not
+ * `chant-disable` comments.
+ */
+async function runOpCheckDiagnostics(infraPath, files, buildParams, plugins = []) {
+    const config = loadConfig(findProjectRoot(infraPath));
+    const opFiles = files.filter((f) => f.endsWith(".op.ts"));
+    if (opFiles.length === 0)
+        return { diagnostics: [], suppressed: [] };
+    // chant #2251 — the same step `discover()` runs before it imports or folds a
+    // project file (../../discovery/index.ts): populate the shared build-time
+    // parameters object BEFORE the imports below, so an Op that takes a step
+    // argument from `params.<name>` reads the value this invocation resolved
+    // rather than `undefined`. Unconditional, so a stale value from a prior
+    // lint in the same process (a test, `--watch`) never leaks into one that
+    // resolved none.
+    setBuildParams(buildParamValues(buildParams ?? []));
+    const entities = new Map();
+    const fileByOpName = new Map();
+    for (const filePath of opFiles) {
+        try {
+            ensureTypeScriptLoader();
+            const mod = await import(filePath);
+            const entity = mod.default;
+            if (!entity || typeof entity !== "object")
+                continue;
+            const opConfig = entity.props;
+            if (!opConfig || typeof opConfig.name !== "string" || !Array.isArray(opConfig.phases))
+                continue;
+            entities.set(opConfig.name, entity);
+            fileByOpName.set(opConfig.name, filePath);
+        }
+        catch {
+            // A file that fails to import is somebody else's problem — a syntax
+            // error surfaces through the AST rule pass over the same file instead
+            // of crashing this one.
+            continue;
+        }
+    }
+    if (entities.size === 0)
+        return { diagnostics: [], suppressed: [] };
+    // chant #2520 — hand over the loaded plugin objects when there are any, as
+    // `chant build` does, so a plugin's `activityContracts()` member is read
+    // here too. Names alone are the fallback when no plugin loaded.
+    const activityContracts = plugins.length > 0
+        ? await loadActivityContracts(plugins)
+        : await loadActivityContracts(await resolveProjectLexicons(infraPath).catch(() => []));
+    // SYS010 (#2828) also reads `decide.backends` from the project's config.
+    // A directory whose config does not load simply has none to check.
+    const decideBackends = await loadChantConfig(findProjectRoot(infraPath))
+        .then((loaded) => loaded.config.decide?.backends)
+        .catch(() => undefined);
+    const raw = runPostSynthChecks(coreOpChecks({ decideBackends }), {
+        outputs: new Map(),
+        entities: entities,
+        warnings: [],
+        errors: [],
+        sourceFileCount: opFiles.length,
+    }, undefined, { activityContracts });
+    const diagnostics = [];
+    const suppressed = [];
+    for (const d of raw) {
+        const resolved = resolveConfiguredSeverity(config.rules, d.checkId, d.severity);
+        if (resolved.severity === "off")
+            continue;
+        diagnostics.push({
+            file: (d.entity && fileByOpName.get(d.entity)) ?? infraPath,
+            line: 1,
+            column: 1,
+            ruleId: d.checkId,
+            severity: resolved.severity,
+            message: d.message,
+        });
+    }
+    return { diagnostics, suppressed };
+}
+/**
+ * Run each loaded lexicon's own post-synth checks (#3750), the ones `chant
+ * build` runs after it serializes, over an in-memory build of the lint target.
+ *
+ * The build is `chant build`'s: the same `build()` call with options from the
+ * same assembler (`../build-options.ts`), and the same per-lexicon scoping of
+ * outputs (`runLexiconPostSynthChecks`, ./build.ts). Nothing is written. It
+ * builds `infraPath`, the target the caller asked to lint, never the project
+ * root above it, so `chant lint <dir>` costs a build of `<dir>` and nothing
+ * more (the same scoping {@link runOpCheckDiagnostics} documents). It is
+ * skipped outright when no loaded lexicon ships post-synth checks and the
+ * project declares no `lint.policies`, which keeps a project with no lexicon,
+ * and every core-only fixture, from building at all.
+ *
+ * The project's `lint.policies` run over the same build after the lexicons'
+ * checks (#3870), with every lexicon's output and the env, as `chant build`
+ * runs them, and sandboxed when the build is. `lint.rules` applies to their
+ * ids; a policy that does not load is reported under
+ * {@link BUILD_FAILURE_RULE_ID}.
+ *
+ * A target that does not build reports each build error under
+ * {@link BUILD_FAILURE_RULE_ID} and skips the checks. Findings go through
+ * `lint.presets`, then `lint.rules`, then inline `chant-ignore` comments, the
+ * order `chant build` applies them in. A finding carries no line (see
+ * ../../lint/post-synth.ts's `PostSynthDiagnostic`), so it is reported at
+ * `1:1` in the file that declared its entity, or at the config file (the
+ * project root without one) when it names none.
+ */
+async function runLexiconPostSynthDiagnostics(infraPath, plugins, buildParams, sandbox) {
+    const diagnostics = [];
+    const suppressed = [];
+    const withChecks = plugins.filter((plugin) => (plugin.postSynthChecks?.() ?? []).length > 0);
+    const projectRoot = findProjectRoot(infraPath);
+    const lintConfig = loadConfig(projectRoot);
+    if (withChecks.length === 0 && (lintConfig.policies ?? []).length === 0)
+        return { diagnostics, suppressed };
+    // Where a finding that names no declared entity is reported: the config the
+    // build loads once it is known (past a lint-only fragment), else the nearest.
+    let fallbackFile = findProjectConfig(projectRoot).configPath ?? projectRoot;
+    const buildFailure = (message, at) => ({
+        file: at?.file ?? fallbackFile,
+        line: at?.line ?? 1,
+        column: at?.column ?? 1,
+        ruleId: BUILD_FAILURE_RULE_ID,
+        severity: "error",
+        message,
+    });
+    let result;
+    let env;
+    let telemetry;
+    let configDir = infraPath;
+    let loadedConfig;
+    let policies = [];
+    try {
+        const loaded = await loadChantConfigUpward(infraPath);
+        const config = loaded.config;
+        loadedConfig = config;
+        configDir = loaded.configPath ? dirname(loaded.configPath) : infraPath;
+        if (loaded.configPath)
+            fallbackFile = loaded.configPath;
+        // The caller's parameters when it resolved them (the CLI does, from the
+        // same upward config walk); otherwise the declared defaults and `env`
+        // mappings of the config this build loads. Not lintCommand's own fallback:
+        // that one reads the config at the lint root, which may be a lint-only
+        // fragment with no `buildParams` (a `src/chant.config.json`).
+        const params = buildParams ?? resolveBuildParams(config.buildParams, { env: process.env }).provenance;
+        env = resolveOwnershipEnv(config, params);
+        policies = config.lint?.policies ?? [];
+        // #3870: a sandboxed build sandboxes the policies too, as `chant build` arms it.
+        const modes = resolveBuildModes(config, { sandbox });
+        if (modes.sandbox && policies.length > 0)
+            armSandboxPolicyExecution();
+        telemetry = await resolveTelemetryAttribution(configDir, config, env);
+        // Every lexicon the lint loaded, as `chant build` serializes with every
+        // lexicon it loaded: a check may read another lexicon's entities, and the
+        // outputs are scoped per plugin below either way.
+        result = await build(infraPath, plugins.map((plugin) => plugin.serializer), undefined, resolveProjectBuildOptions({
+            config,
+            configDir,
+            plugins,
+            modes,
+            ownership: resolveOwnershipMarker(config, params),
+            buildParams: params,
+            telemetry,
+        }));
+    }
+    catch (err) {
+        diagnostics.push(buildFailure(err instanceof Error ? err.message : String(err)));
+        return { diagnostics, suppressed };
+    }
+    if (result.errors.length > 0) {
+        const seen = new Set();
+        for (const error of result.errors) {
+            const at = error;
+            const key = `${at.file ?? ""}:${at.line ?? ""}:${error.message}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            diagnostics.push(buildFailure(error.message, at));
+        }
+        return { diagnostics, suppressed };
+    }
+    const activityContracts = await loadActivityContracts(plugins);
+    const fileOf = (entity) => {
+        const declared = entity ? result.entities.get(entity) : undefined;
+        return (declared && getProvenance(declared)?.sourceFile) || fallbackFile;
+    };
+    const toLint = (d) => ({
+        file: fileOf(d.entity),
+        line: 1,
+        column: 1,
+        ruleId: d.checkId,
+        severity: d.severity,
+        message: `${d.entity ? `[${d.entity}] ` : ""}${d.message}`,
+    });
+    for (const { plugin, diagnostics: raw } of runLexiconPostSynthChecks(withChecks, result, env, { activityContracts, telemetry, projectDir: configDir, ...(loadedConfig ? { projectConfig: loadedConfig } : {}) })) {
+        const presetIds = resolvePresetIds(plugin.lintPresets?.(), lintConfig.presets?.[plugin.name] ?? "recommended");
+        const afterPreset = applyConfiguredPreset(raw, presetIds, lintConfig.rules).diagnostics;
+        const afterConfig = applyConfiguredSeverity(afterPreset, lintConfig.rules).diagnostics;
+        const inline = applyInlineSuppressions(afterConfig, result.entities, lintConfig.rules);
+        for (const d of inline.diagnostics)
+            diagnostics.push(toLint(d));
+        for (const d of inline.suppressed)
+            suppressed.push({ ...toLint(d), reason: "chant-ignore" });
+        for (const m of inline.meta) {
+            diagnostics.push({ file: m.file, line: m.line, column: 1, ruleId: m.checkId, severity: m.severity, message: m.message });
+        }
+    }
+    // #3870: the project's `lint.policies`, over the same build, as `chant
+    // build` runs them: every lexicon's output at once, with the env, and
+    // `lint.rules` applied to their ids.
+    if (policies.length > 0) {
+        let raw;
+        try {
+            raw = await runProjectPolicies({ policies, configDir, buildResult: result, env });
+        }
+        catch (err) {
+            diagnostics.push(buildFailure(err instanceof Error ? err.message : String(err)));
+            return { diagnostics, suppressed };
+        }
+        const configured = applyConfiguredSeverity(raw, lintConfig.rules);
+        for (const d of configured.diagnostics)
+            diagnostics.push(toLint(d));
+    }
+    return { diagnostics, suppressed };
+}
+/**
+ * Apply fixes to a file
+ */
+function applyFixes(filePath, fixes) {
+    if (fixes.length === 0)
+        return;
+    let content = readFileSync(filePath, "utf-8");
+    // Sort fixes by position descending so we can apply from end to start
+    const sortedFixes = [...fixes].sort((a, b) => b.range[0] - a.range[0]);
+    for (const fix of sortedFixes) {
+        content = content.slice(0, fix.range[0]) + fix.replacement + content.slice(fix.range[1]);
+    }
+    writeFileSync(filePath, content);
+}
+/**
+ * Execute the lint command
+ */
+export async function lintCommand(options) {
+    const infraPath = resolve(options.path);
+    // Config, rules, and lexicons anchor on the project root so a scoped lint
+    // (`chant lint src`, the `graph --format ir` gate) still sees `lint.overrides`
+    // and the declared lexicons; only the file scan stays scoped to `infraPath`.
+    const projectRoot = findProjectRoot(infraPath);
+    const config = loadConfig(projectRoot);
+    const hasOverrides = config.overrides && config.overrides.length > 0;
+    // chant #1221 — the project's chant.config slice for config-aware rules
+    // (COR021 reads `environments` + `ownership`), threaded into every
+    // runLint() call below via LintContext.projectConfig. Best-effort: a
+    // directory with no project config lints with those rules silent.
+    let projectConfig;
+    // chant #1866 — the loaded OKF knowledge bundle, threaded into
+    // `formatStylish` below so its suppressed section can resolve `okf:`
+    // citations. Best-effort like `projectConfig` above (same
+    // `loadChantConfig` call): a directory with no chant config, or no
+    // `knowledge/` bundle, lints with citations rendering unresolved rather
+    // than a failure — `loadOkfBundle` already treats a missing directory as
+    // an empty bundle.
+    let knowledgeBundle;
+    /**
+     * chant #2249 — this invocation's build-time parameters, falling back to
+     * the project's own declared `buildParams` when the caller passed none.
+     *
+     * `chant lint` resolves them in ./handlers/lint.ts (#2251) because only
+     * the CLI knows about `--param`/`--params-file`, and passes them here. An
+     * in-process caller has no such flags to read, and before this fell
+     * through to the empty parameter object: the OPS* checks import each
+     * `*.op.ts`, an Op taking a step argument from `params.<name>` read
+     * `undefined` at module load, and OPS012 reported the activity contract
+     * violated for source `chant lint` on the command line passes. That made
+     * `lintCommand` disagree with its own CLI (the root-examples gate,
+     * `handleLint` over MCP, test-utils' example harness). Resolving the
+     * declared defaults + `env` mappings here is what the command line
+     * already gets; anything a flag would override still arrives in
+     * `options.buildParams` and wins. Best-effort like `projectConfig`:
+     * `resolveBuildParams` collects failures per parameter without throwing,
+     * and the ones that did resolve are still better than none.
+     */
+    let buildParams = options.buildParams;
+    try {
+        const chantConfig = (await loadChantConfig(projectRoot)).config;
+        projectConfig = chantConfig;
+        knowledgeBundle = await loadOkfBundle(resolveKnowledgeDir(chantConfig, projectRoot));
+        buildParams ?? (buildParams = resolveBuildParams(chantConfig.buildParams, { env: process.env }).provenance);
+    }
+    catch {
+        projectConfig = undefined;
+        knowledgeBundle = undefined;
+    }
+    // Load all rules from lexicon plugins (core "chant" + lexicon-specific)
+    const loaded = await loadAllPluginRules(projectRoot);
+    let allRules = loaded.rules;
+    // chant #1106 — the active lexicons' registered intrinsics, threaded into
+    // every runLint() call below so EVL001 answers exactly like fold() does
+    // for a registered, opted-in call (`Ref(...)`, `GetAtt(...)`) instead of
+    // flagging it. Computed once here regardless of which branch below runs,
+    // same as `allRules`.
+    const intrinsics = loaded.intrinsics;
+    const propertyClasses = loaded.propertyClasses;
+    // Merge in any config-level plugin rules (custom .ts rule files)
+    if (config.plugins && config.plugins.length > 0) {
+        const pluginRules = await loadPluginRules(config.plugins, projectRoot);
+        allRules = new Map([...allRules, ...pluginRules]);
+    }
+    // Get all TypeScript files, through the one discovery walk (#2527)
+    const files = await getTypeScriptFiles(infraPath);
+    // Run lint — use per-file rules when overrides are present
+    let diagnostics;
+    let suppressed = [];
+    if (options.rules) {
+        const result = await runLint(files, options.rules, undefined, intrinsics, projectConfig, propertyClasses);
+        diagnostics = result.diagnostics;
+        suppressed = result.suppressed;
+    }
+    else if (hasOverrides) {
+        diagnostics = [];
+        for (const file of files) {
+            const relativePath = relative(projectRoot, file);
+            const { rules: fileRules, ruleOptions } = getDefaultRules(projectRoot, relativePath, allRules);
+            const result = await runLint([file], fileRules, ruleOptions, intrinsics, projectConfig, propertyClasses);
+            diagnostics.push(...result.diagnostics);
+            suppressed.push(...result.suppressed);
+        }
+    }
+    else {
+        const { rules, ruleOptions } = getDefaultRules(projectRoot, undefined, allRules);
+        const result = await runLint(files, rules, ruleOptions, intrinsics, projectConfig, propertyClasses);
+        diagnostics = result.diagnostics;
+        suppressed = result.suppressed;
+    }
+    // Run the COMP* composition checks (#562) over the discovered `Component`
+    // graph and merge them into the same diagnostics/suppressed lists — a
+    // structurally distinct check family (whole-project, post-discovery,
+    // see ../../lint/component-checks.ts) but the same `chant lint` output and
+    // the same error-severity gating as every COR/EVL diagnostic.
+    const componentResult = await runComponentCheckDiagnostics(infraPath, options.sandbox, buildParams);
+    diagnostics.push(...componentResult.diagnostics);
+    suppressed.push(...componentResult.suppressed);
+    // Run the OPS* Op-model post-synth checks (#2122) over every `*.op.ts`
+    // file under the lint target — see runOpCheckDiagnostics's doc for why
+    // this needs no lexicon or build to fire.
+    const opResult = await runOpCheckDiagnostics(infraPath, files, buildParams, loaded.plugins);
+    diagnostics.push(...opResult.diagnostics);
+    suppressed.push(...opResult.suppressed);
+    // Apply fixes if requested
+    if (options.fix) {
+        // Group fixes by file
+        const fixesByFile = new Map();
+        for (const diag of diagnostics) {
+            if (diag.fix) {
+                const existing = fixesByFile.get(diag.file) ?? [];
+                existing.push(diag.fix);
+                fixesByFile.set(diag.file, existing);
+            }
+        }
+        // Apply fixes to each file
+        for (const [file, fixes] of fixesByFile) {
+            applyFixes(file, fixes);
+        }
+        // Re-lint after fixes to get updated diagnostics
+        if (options.rules) {
+            const postResult = await runLint(files, options.rules, undefined, intrinsics, projectConfig, propertyClasses);
+            diagnostics = postResult.diagnostics;
+            suppressed = postResult.suppressed;
+        }
+        else if (hasOverrides) {
+            diagnostics = [];
+            suppressed = [];
+            for (const file of files) {
+                const relativePath = relative(projectRoot, file);
+                const { rules: fileRules, ruleOptions } = getDefaultRules(projectRoot, relativePath, allRules);
+                const postResult = await runLint([file], fileRules, ruleOptions, intrinsics, projectConfig, propertyClasses);
+                diagnostics.push(...postResult.diagnostics);
+                suppressed.push(...postResult.suppressed);
+            }
+        }
+        else {
+            const { rules, ruleOptions } = getDefaultRules(projectRoot, undefined, allRules);
+            const postResult = await runLint(files, rules, ruleOptions, intrinsics, projectConfig, propertyClasses);
+            diagnostics = postResult.diagnostics;
+            suppressed = postResult.suppressed;
+        }
+        // COMP* checks have no `.fix` (nothing above could have touched a
+        // `*.component.ts` file on their behalf), but a fix applied to another
+        // rule could still be in the same file a component was discovered from —
+        // re-run for consistency with the AST re-lint above.
+        const postComponentResult = await runComponentCheckDiagnostics(infraPath, options.sandbox, buildParams);
+        diagnostics.push(...postComponentResult.diagnostics);
+        suppressed.push(...postComponentResult.suppressed);
+        // OPS* checks have no `.fix` either; re-run for the same consistency
+        // reason as the COMP* re-run just above.
+        const postOpResult = await runOpCheckDiagnostics(infraPath, files, buildParams, loaded.plugins);
+        diagnostics.push(...postOpResult.diagnostics);
+        suppressed.push(...postOpResult.suppressed);
+    }
+    // chant #3750: each lexicon's own post-synth checks, over an in-memory
+    // build of the lint target. Run once, after any `--fix` above, so it sees
+    // the source as fixed; a post-synth finding has no fix of its own. Skipped
+    // when a lexicon failed to resolve, which LEX001 below already reports.
+    if (!loaded.lexiconError && options.postSynth !== false) {
+        const lexiconResult = await runLexiconPostSynthDiagnostics(infraPath, loaded.plugins, options.buildParams, options.sandbox);
+        diagnostics.push(...lexiconResult.diagnostics);
+        suppressed.push(...lexiconResult.suppressed);
+    }
+    // chant #2222: a lexicon the project declared but this run could not
+    // resolve. Appended here, after the `--fix` re-lint block above has finished
+    // reassigning `diagnostics`, so it survives every path; it is a property of
+    // the run, not of any file a fix could touch.
+    if (loaded.lexiconError) {
+        diagnostics.push(lexiconResolutionDiagnostic(projectRoot, loaded.lexiconError));
+    }
+    // Count errors and warnings
+    let errorCount = 0;
+    let warningCount = 0;
+    for (const diag of diagnostics) {
+        if (diag.severity === "error") {
+            errorCount++;
+        }
+        else if (diag.severity === "warning") {
+            warningCount++;
+        }
+    }
+    // Collect all loaded rules for SARIF enrichment
+    const allLoadedRules = options.rules
+        ? options.rules
+        : [...allRules.values()];
+    // Format output
+    let output;
+    switch (options.format) {
+        case "json":
+            output = formatJson(diagnostics);
+            break;
+        case "sarif":
+            output = formatSarif(diagnostics, allLoadedRules, suppressed);
+            break;
+        case "stylish":
+        default:
+            output = formatStylish(diagnostics, suppressed, knowledgeBundle);
+            break;
+    }
+    return {
+        success: errorCount === 0,
+        errorCount,
+        warningCount,
+        diagnostics,
+        output,
+    };
+}
+/**
+ * Print lint result to console
+ */
+export function printLintResult(result) {
+    if (result.output) {
+        console.log(result.output);
+    }
+}
+/**
+ * Run lint in watch mode. Runs an initial lint, then watches for changes
+ * and triggers re-lints. Returns a cleanup function.
+ */
+export function lintCommandWatch(options, onReLint) {
+    const infraPath = resolve(options.path);
+    console.error(formatInfo(`[${formatTimestamp()}] Watching for changes...`));
+    // Run initial lint
+    lintCommand(options).then((result) => {
+        printLintResult(result);
+        onReLint?.(result);
+        console.error(formatInfo(`[${formatTimestamp()}] Waiting for changes...`));
+    });
+    // Watch for changes and trigger re-lints
+    const cleanup = watchDirectory(infraPath, async (changedFiles) => {
+        console.error("");
+        console.error(formatInfo(`[${formatTimestamp()}] Changes detected: ${formatChangedFiles(changedFiles, infraPath)}`));
+        try {
+            const result = await lintCommand(options);
+            printLintResult(result);
+            onReLint?.(result);
+        }
+        catch (err) {
+            console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        }
+        console.error(formatInfo(`[${formatTimestamp()}] Waiting for changes...`));
+    });
+    return cleanup;
+}