@intentius/chant 0.124.12 → 0.124.14

package/dist/lint/discover.js

@@ -0,0 +1,138 @@
+/**
+ * Auto-discovery for lint rules and post-synth checks.
+ *
+ * Scans directories for .ts files and loads exported rules/checks,
+ * eliminating the need to manually list every rule in plugin.ts.
+ */
+import { readdirSync } from "fs";
+import { join } from "path";
+import { createRequire } from "module";
+import { ensureTypeScriptLoader } from "../ts-loader.js";
+let cjsTypeScript = false;
+/**
+ * Register tsx so createRequire can load TypeScript files in Node.js ESM
+ * context. Does nothing when tsx is not available; then only pre-compiled .js
+ * files can be require()'d.
+ *
+ * From source this runs when the module loads, as it always has: vitest and
+ * the source CLI rely on tsx's CommonJS hook being in place from then on. The
+ * compiled CLI imports this module on every start and most commands read no
+ * rule directory, so there it waits for the first one (#3878).
+ */
+function registerTypeScriptRequire() {
+    if (cjsTypeScript)
+        return;
+    cjsTypeScript = true;
+    if (ensureTypeScriptLoader())
+        return;
+    try {
+        const _req = createRequire(import.meta.url);
+        const { register } = _req("tsx/cjs/api");
+        register();
+    }
+    catch {
+        // tsx not available; only pre-compiled .js files can be require()'d
+    }
+}
+if (!import.meta.url.endsWith(".js"))
+    registerTypeScriptRequire();
+/**
+ * Discover lint rules from a directory.
+ *
+ * Scans the directory for .ts files (excluding tests, helpers, and index files),
+ * loads each module, and collects any exported objects that look like a LintRule
+ * (has `id`, `severity`, `category`, and `check` function).
+ *
+ * @param dir - Absolute path to the rules directory
+ * @param importMetaUrl - The caller's import.meta.url (for createRequire)
+ */
+export function discoverLintRules(dir, importMetaUrl) {
+    registerTypeScriptRequire();
+    const require = createRequire(importMetaUrl);
+    const rules = [];
+    for (const file of listRuleFiles(dir)) {
+        try {
+            // Strip .ts extension — require() resolves without it
+            const modPath = join(dir, file.replace(/\.ts$/, ""));
+            const mod = require(modPath);
+            for (const exp of Object.values(mod)) {
+                if (isLintRule(exp))
+                    rules.push(exp);
+            }
+        }
+        catch {
+            // Skip files that fail to load
+        }
+    }
+    return rules.sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * Discover post-synth checks from a directory.
+ *
+ * Scans the directory for .ts files (excluding tests, helpers, and index files),
+ * loads each module, and collects any exported objects that look like a PostSynthCheck
+ * (has `id`, `description`, and `check` function).
+ *
+ * @param dir - Absolute path to the post-synth rules directory
+ * @param importMetaUrl - The caller's import.meta.url (for createRequire)
+ */
+export function discoverPostSynthChecks(dir, importMetaUrl) {
+    registerTypeScriptRequire();
+    const require = createRequire(importMetaUrl);
+    const checks = [];
+    for (const file of listRuleFiles(dir)) {
+        try {
+            // Strip .ts extension — require() resolves without it
+            const modPath = join(dir, file.replace(/\.ts$/, ""));
+            const mod = require(modPath);
+            for (const exp of Object.values(mod)) {
+                if (isPostSynthCheck(exp))
+                    checks.push(exp);
+            }
+        }
+        catch {
+            // Skip files that fail to load
+        }
+    }
+    return checks.sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * List rule files in a directory (excluding tests, helpers, index).
+ */
+export function listRuleFiles(dir) {
+    try {
+        return readdirSync(dir).filter((f) => {
+            if (!f.endsWith(".ts"))
+                return false;
+            if (f.endsWith(".test.ts"))
+                return false;
+            if (f === "index.ts")
+                return false;
+            if (f.includes("helper"))
+                return false;
+            return true;
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function isLintRule(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const o = obj;
+    return (typeof o.id === "string" &&
+        typeof o.severity === "string" &&
+        typeof o.category === "string" &&
+        typeof o.check === "function");
+}
+function isPostSynthCheck(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const o = obj;
+    return (typeof o.id === "string" &&
+        typeof o.description === "string" &&
+        typeof o.check === "function" &&
+        // Exclude LintRules (which also have check) by checking for PostSynthCheck-specific fields
+        typeof o.severity !== "string");
+}

package/dist/lint/engine.js

@@ -0,0 +1,246 @@
+import { parseFile } from "./parser.js";
+import { readFileSync } from "fs";
+/**
+ * Parse disable comments from source code
+ * Supports:
+ * - // chant-disable - disable all rules for entire file
+ * - // chant-disable-line - disable all rules for current line
+ * - // chant-disable-next-line - disable all rules for next line
+ * - // chant-disable rule-id1 rule-id2 - disable specific rules for file
+ * - // chant-disable-line rule-id1 - disable specific rules for line
+ * - // chant-disable-next-line rule-id1 - disable specific rules for next line
+ */
+/**
+ * Parse the text after a directive keyword, splitting rule IDs from an optional reason.
+ * Reason is separated by ` -- ` (first occurrence only).
+ * Trailing `--` with no text is treated as no reason.
+ */
+function parseDirectiveText(afterDirective) {
+    if (!afterDirective)
+        return {};
+    const trimmed = afterDirective.trim();
+    if (!trimmed)
+        return {};
+    // Handle `-- reason` at the start (no rule IDs, just reason)
+    if (trimmed.startsWith("-- ")) {
+        const reasonPart = trimmed.slice(3).trim();
+        return { reason: reasonPart || undefined };
+    }
+    // Handle bare `--` (no rule IDs, no reason)
+    if (trimmed === "--") {
+        return {};
+    }
+    // Handle `RULE_ID -- reason` (rule IDs + reason separated by ` -- `)
+    const dashIdx = trimmed.indexOf(" -- ");
+    if (dashIdx >= 0) {
+        const idsPart = trimmed.slice(0, dashIdx).trim();
+        const reasonPart = trimmed.slice(dashIdx + 4).trim();
+        const ruleIds = idsPart ? idsPart.split(/\s+/).filter(Boolean) : undefined;
+        const reason = reasonPart || undefined;
+        return {
+            ruleIds: ruleIds && ruleIds.length > 0 ? ruleIds : undefined,
+            reason,
+        };
+    }
+    // Handle trailing ` --` with no reason text
+    if (trimmed.endsWith(" --")) {
+        const idsPart = trimmed.slice(0, -3).trim();
+        const ruleIds = idsPart ? idsPart.split(/\s+/).filter(Boolean) : undefined;
+        return {
+            ruleIds: ruleIds && ruleIds.length > 0 ? ruleIds : undefined,
+        };
+    }
+    // No `--` at all — just rule IDs
+    const ruleIds = trimmed.split(/\s+/).filter(Boolean);
+    return {
+        ruleIds: ruleIds.length > 0 ? ruleIds : undefined,
+    };
+}
+/**
+ * Parse `chant-disable`/`chant-disable-line`/`chant-disable-next-line`
+ * comments out of raw file content. Exported (in addition to being used
+ * internally by `runLint`) so other diagnostic sources that are not plain
+ * per-file AST `LintRule`s — e.g. ../lint/rules/comp's component composition
+ * checks, which produce whole-component diagnostics rather than
+ * exact-line ones — can still honor at least the file-level directive form
+ * without duplicating this parsing.
+ */
+export function parseDisableComments(content) {
+    const directives = [];
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNumber = i + 1;
+        // Match disable comments
+        const disableFileMatch = line.match(/\/\/\s*chant-disable(?:\s+(.+))?$/);
+        const disableLineMatch = line.match(/\/\/\s*chant-disable-line(?:\s+(.+))?$/);
+        const disableNextLineMatch = line.match(/\/\/\s*chant-disable-next-line(?:\s+(.+))?$/);
+        if (disableNextLineMatch) {
+            const { ruleIds, reason } = parseDirectiveText(disableNextLineMatch[1]);
+            directives.push({
+                line: lineNumber + 1, // Next line
+                type: "next-line",
+                ruleIds,
+                reason,
+            });
+        }
+        else if (disableLineMatch) {
+            const { ruleIds, reason } = parseDirectiveText(disableLineMatch[1]);
+            directives.push({
+                line: lineNumber,
+                type: "line",
+                ruleIds,
+                reason,
+            });
+        }
+        else if (disableFileMatch) {
+            const { ruleIds, reason } = parseDirectiveText(disableFileMatch[1]);
+            directives.push({
+                line: lineNumber,
+                type: "file",
+                ruleIds,
+                reason,
+            });
+        }
+    }
+    return directives;
+}
+/**
+ * Check if a diagnostic should be suppressed based on disable directives.
+ * Returns suppression info if suppressed, or null if not suppressed.
+ */
+function isDiagnosticDisabled(diagnostic, directives, allRuleIds) {
+    // Check for file-level disables
+    const fileDisables = directives.filter((d) => d.type === "file");
+    for (const directive of fileDisables) {
+        if (!directive.ruleIds) {
+            // Disable all rules
+            return { suppressed: true, reason: directive.reason };
+        }
+        // Check if rule ID exists before checking if it's disabled
+        if (directive.ruleIds.some((id) => allRuleIds.has(id))) {
+            if (directive.ruleIds.includes(diagnostic.ruleId)) {
+                return { suppressed: true, reason: directive.reason };
+            }
+        }
+        // Silently ignore non-existent rule IDs
+    }
+    // Check for line-specific disables
+    const lineDisables = directives.filter((d) => (d.type === "line" || d.type === "next-line") && d.line === diagnostic.line);
+    for (const directive of lineDisables) {
+        if (!directive.ruleIds) {
+            // Disable all rules
+            return { suppressed: true, reason: directive.reason };
+        }
+        // Check if rule ID exists before checking if it's disabled
+        if (directive.ruleIds.some((id) => allRuleIds.has(id))) {
+            if (directive.ruleIds.includes(diagnostic.ruleId)) {
+                return { suppressed: true, reason: directive.reason };
+            }
+        }
+        // Silently ignore non-existent rule IDs
+    }
+    return { suppressed: false };
+}
+/**
+ * The error reported when a rule throws while checking a file (#2511). It
+ * names the rule, the file and the thrown message, at error severity so
+ * `chant lint` exits non-zero.
+ */
+export function ruleThrewDiagnostic(ruleId, filePath, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        file: filePath,
+        line: 1,
+        column: 1,
+        ruleId,
+        severity: "error",
+        message: `Rule ${ruleId} threw while checking ${filePath}: ${message}`,
+    };
+}
+/**
+ * Execute lint rules on a set of files
+ * @param files - Array of file paths to lint
+ * @param rules - Array of lint rules to execute
+ * @param ruleOptions - Optional map of rule ID to options object
+ * @param intrinsics - chant #1106 — the active lexicons' registered
+ *   intrinsics (e.g. AWS's `Ref`, `GetAtt`), put on every file's
+ *   `LintContext.intrinsics` so a rule built on `../fold/subset.ts`'s
+ *   shared predicate (EVL001) answers exactly like `fold()` does for a
+ *   registered, opted-in call, instead of degrading to "every call is a
+ *   violation". Mirrors how `discover()` has threaded the same
+ *   `IntrinsicDef[]` into the fold path since #1039/#1105. Optional and
+ *   defaulting to none, so a caller that hasn't resolved a project's
+ *   lexicons (a unit test, `bench.test.ts`) is unaffected.
+ * @param projectConfig - chant #1221 — the project's config slice for
+ *   config-aware rules (COR021 reads `environments` + `ownership`), put on
+ *   every file's `LintContext.projectConfig`. Optional; without it those
+ *   rules stay silent.
+ * @param propertyClasses - chant #2957 — the class names the active
+ *   lexicons declare property-kind (`LexiconPlugin.propertyClassNames()`),
+ *   put on every file's `LintContext.propertyClasses` so COR001, COR004 and
+ *   COR009 leave those declarables out. Optional; without it every
+ *   declarable counts.
+ * @returns LintRunResult with diagnostics and suppressed items
+ */
+export async function runLint(files, rules, ruleOptions, intrinsics, projectConfig, propertyClasses) {
+    const allDiagnostics = [];
+    const allSuppressed = [];
+    const allRuleIds = new Set(rules.map((r) => r.id));
+    for (const filePath of files) {
+        try {
+            // Parse the file
+            const sourceFile = parseFile(filePath);
+            // Read file content for disable comment parsing
+            const content = readFileSync(filePath, "utf-8");
+            const directives = parseDisableComments(content);
+            // Create lint context
+            const context = {
+                sourceFile,
+                entities: [],
+                filePath,
+                lexicon: undefined,
+                intrinsics,
+                projectConfig,
+                propertyClasses,
+            };
+            // Execute each rule. A rule that throws is reported as an error for
+            // this file (#2511) and the remaining rules still run.
+            const ruleErrors = [];
+            for (const rule of rules) {
+                const options = ruleOptions?.get(rule.id);
+                try {
+                    const diagnostics = rule.check(context, options);
+                    allDiagnostics.push(...diagnostics);
+                }
+                catch (error) {
+                    ruleErrors.push(ruleThrewDiagnostic(rule.id, filePath, error));
+                }
+            }
+            // Partition file diagnostics into active and suppressed
+            const fileDiags = allDiagnostics.filter((d) => d.file === filePath);
+            const otherFileDiags = allDiagnostics.filter((d) => d.file !== filePath);
+            const keptDiags = [];
+            for (const diagnostic of fileDiags) {
+                const result = isDiagnosticDisabled(diagnostic, directives, allRuleIds);
+                if (result.suppressed) {
+                    allSuppressed.push({ ...diagnostic, reason: result.reason });
+                }
+                else {
+                    keptDiags.push(diagnostic);
+                }
+            }
+            // Replace file diagnostics with filtered ones
+            allDiagnostics.length = 0;
+            // A rule's own failure is never suppressed by a disable comment: the
+            // comment is aimed at the rule's findings, and hiding the failure would
+            // make a rule that did not run look like a clean lint.
+            allDiagnostics.push(...otherFileDiags, ...keptDiags, ...ruleErrors);
+        }
+        catch (error) {
+            // If parsing fails, skip this file and continue with others
+            continue;
+        }
+    }
+    return { diagnostics: allDiagnostics, suppressed: allSuppressed };
+}

package/dist/lint/knowledge-checks.js

@@ -0,0 +1,64 @@
+import { bindConcepts } from "../okf-read.js";
+/**
+ * COR026: Stale Knowledge Binding (#1865, design #1059, epic #1057)
+ *
+ * A concept's `binds` frontmatter key names a discovered entity's logical
+ * name (#1864, `../okf-read.ts`'s `bindConcepts`). A name that resolves to
+ * nothing is a stale binding — the entity was renamed or removed, or the
+ * concept was authored against a name that never existed — and per #1059's
+ * stated failure posture ("the spec permits broken links, which argues for
+ * warn") that is a warning, never a build failure: knowledge is deliberately
+ * softer than the typed graph it describes, and OKF itself tolerates broken
+ * links (epic #1057).
+ *
+ * The converse is deliberately silent: a concept with no `binds` at all is
+ * orphaned knowledge, not an omission (a runbook, a decision about the
+ * project as a whole), and `bindConcepts` never reports it as unresolved in
+ * the first place — see its own doc comment. A project with no knowledge
+ * bundle loads an empty one (`loadOkfBundle`), so this check produces no
+ * diagnostics either.
+ *
+ * Wired into `chant build` (`../cli/commands/build.ts`) alongside
+ * `coreReceiptChecks` — same reasons COR023/COR024 are build-owned rather
+ * than a per-file `LintRule`: the check needs the full discovered entity map
+ * (`ctx.entities`), not one `ts.SourceFile`, and that map only exists after
+ * discovery has run. Unlike COR023/024 it never reads `ctx.outputs` — the
+ * bundle is loaded once, up front (async — `loadOkfBundle` reads the
+ * filesystem), and closed over here so the check itself stays the same sync
+ * shape every other `PostSynthCheck` has.
+ */
+export const STALE_KNOWLEDGE_BINDING_CHECK_ID = "COR026";
+/**
+ * Build the COR026 check for one loaded bundle. A factory, not a bare
+ * constant, because — unlike `coreReceiptChecks`, which needs nothing but
+ * `ctx.entities` — this check needs the bundle loaded from disk, and
+ * `loadOkfBundle` is async while `PostSynthCheck#check` is not. The caller
+ * loads the bundle once (`resolveKnowledgeDir` + `loadOkfBundle`) and passes
+ * it in; see `../cli/commands/build.ts`.
+ */
+export function staleKnowledgeBindingCheck(bundle) {
+    return {
+        id: STALE_KNOWLEDGE_BINDING_CHECK_ID,
+        description: "A knowledge concept's `binds` entry must name a discovered entity — a name that resolves to nothing is a stale binding",
+        check(ctx) {
+            const { unresolved } = bindConcepts(bundle, ctx.entities);
+            return unresolved.map(({ concept, name }) => ({
+                checkId: STALE_KNOWLEDGE_BINDING_CHECK_ID,
+                severity: "warning",
+                message: `Knowledge concept "${concept.path}" binds "${name}", but no discovered entity has that name — ` +
+                    `a stale binding. The entity may have been renamed or removed, or the concept was authored ` +
+                    `against a name that never existed. Update the concept's \`binds\` frontmatter, or remove the ` +
+                    `entry if the concept no longer applies.`,
+            }));
+        },
+    };
+}
+/**
+ * Core's own post-synth check over knowledge bindings, run by `chant build`
+ * over the full build result — unscoped, like `coreReceiptChecks`, since a
+ * concept's `binds` can name any discovered entity regardless of which
+ * lexicon owns it.
+ */
+export function coreKnowledgeChecks(bundle) {
+    return [staleKnowledgeBindingCheck(bundle)];
+}

package/dist/lint/named-checks.js

@@ -0,0 +1,22 @@
+/**
+ * Registry of named check functions.
+ */
+const checkRegistry = new Map();
+/**
+ * Register a named check function.
+ */
+export function registerCheck(name, fn) {
+    checkRegistry.set(name, fn);
+}
+/**
+ * Get a named check by name. Returns undefined if not found.
+ */
+export function getNamedCheck(name) {
+    return checkRegistry.get(name);
+}
+/**
+ * List all registered check names.
+ */
+export function listChecks() {
+    return Array.from(checkRegistry.keys());
+}

package/dist/lint/output-checks.js

@@ -0,0 +1,87 @@
+import { getPrimaryOutput } from "./post-synth.js";
+/**
+ * COR025: Stringified Reference in Serialized Output (#1526)
+ *
+ * kubemicrovm-ops composed a bucket policy's resource ARN with a template
+ * literal — `` `${bucket.Arn}/*` `` — over an `AttrRef`, not a string.
+ * JavaScript stringifies any non-primitive interpolated into a template
+ * literal via `Object.prototype.toString`, so the emitted policy carried the
+ * literal substring `"[object Object]/*"` in place of the resolved ARN. That
+ * built clean and linted clean — nothing upstream of serialization sees a
+ * type error, because `AttrRef` IS an object and a template literal accepts
+ * any coercible value — and it deployed clean on floci, which does no
+ * policy validation. It failed the first real deploy with S3 rejecting the
+ * policy's `Resource` and rolling back the stack.
+ *
+ * `[object Object]` (and its array-of-objects sibling `[object Object,object
+ * Object]`) never appears in a serialized template/manifest on purpose: no
+ * lexicon's serializer ever emits it, and no cloud provider's schema ever
+ * expects it as a literal value. Its presence is only ever a reference that
+ * got coerced to a string instead of resolved. That makes this check cheap,
+ * universal across lexicons (it scans the emitted text, not any one
+ * lexicon's schema), and free of false positives worth caring about — see
+ * `stringifiedReferenceCheck` below.
+ *
+ * Scans `ctx.outputs` (the SYNTHESIZED text) rather than `ctx.entities`
+ * because the coercion already happened in the user's own declaration code,
+ * upstream of anything chant's model retains structurally — by the time an
+ * entity reaches `ctx.entities` its prop is already a plain string containing
+ * the marker, indistinguishable from any other string prop. The only place
+ * left to catch it lexicon-independently is the text chant actually emits.
+ */
+const MARKER = "[object Object]";
+export const STRINGIFIED_REFERENCE_CHECK_ID = "COR025";
+/** Trim a matched line down to a readable snippet without truncating mid-marker. */
+const MAX_SNIPPET_LENGTH = 200;
+function lineContaining(text, index) {
+    const lineStart = text.lastIndexOf("\n", index) + 1;
+    const nextNewline = text.indexOf("\n", index);
+    const lineEnd = nextNewline === -1 ? text.length : nextNewline;
+    const line = text.slice(lineStart, lineEnd).trim();
+    return line.length > MAX_SNIPPET_LENGTH ? `${line.slice(0, MAX_SNIPPET_LENGTH)}…` : line;
+}
+/** Every serialized file for one lexicon's output: the primary plus any nested files. */
+function serializedFiles(output) {
+    const files = { primary: getPrimaryOutput(output) };
+    if (typeof output !== "string" && output.files) {
+        Object.assign(files, output.files);
+    }
+    return files;
+}
+const stringifiedReferenceCheck = {
+    id: STRINGIFIED_REFERENCE_CHECK_ID,
+    description: 'A serialized output contains the literal substring "[object Object]" — a reference that was ' +
+        "stringified (e.g. through a template literal or string concatenation) instead of resolved. " +
+        "Always an authoring error, never intentional output.",
+    check(ctx) {
+        const diagnostics = [];
+        for (const [lexicon, output] of ctx.outputs) {
+            for (const [fileLabel, content] of Object.entries(serializedFiles(output))) {
+                const seenLines = new Set();
+                let index = content.indexOf(MARKER);
+                while (index !== -1) {
+                    const line = lineContaining(content, index);
+                    const dedupeKey = `${fileLabel}::${line}`;
+                    if (!seenLines.has(dedupeKey)) {
+                        seenLines.add(dedupeKey);
+                        const location = fileLabel === "primary" ? "" : ` (${fileLabel})`;
+                        diagnostics.push({
+                            checkId: STRINGIFIED_REFERENCE_CHECK_ID,
+                            severity: "error",
+                            lexicon,
+                            message: `Serialized output${location} contains "${MARKER}" — a reference was stringified ` +
+                                `instead of resolved (a template literal or string concatenation over an object, ` +
+                                `not the raw value/ref). Emitted line: ${line}`,
+                        });
+                    }
+                    index = content.indexOf(MARKER, index + MARKER.length);
+                }
+            }
+        }
+        return diagnostics;
+    },
+};
+/** Core-owned post-synth checks over serialized output text (#1526). */
+export function coreOutputChecks() {
+    return [stringifiedReferenceCheck];
+}