@intentius/chant 0.19.1 → 0.21.0

package/src/cli/commands/check-lexicon-intrinsics.ts

@@ -0,0 +1,348 @@
+/**
+ * Static audit of a lexicon's intrinsic registrations (chant #1067).
+ *
+ * `check-lexicon.ts`'s original 29 checks are all existence/count assertions
+ * — they never look at whether a registration is actually *correct*.
+ * Foldability (`IntrinsicDef.isTag`, ../../lexicon.ts) is the sharpest case:
+ * it drives both `chant build --fold` (which registered tags it recognizes)
+ * and the generated per-lexicon intrinsics doc page (its "Folds?" column,
+ * via `intrinsicFolds()`), so a wrong value doesn't just mislead a reader —
+ * it silently changes what `--fold` does. #1039 shipped with the flag wrong
+ * in both directions at once (aws's `Sub` missing `isTag` entirely; gitlab's
+ * `reference()` claiming `isTag: true` for a plain call) and neither was
+ * caught by anything until someone measured fold coverage by hand.
+ *
+ * This module answers two questions per registered intrinsic, purely by
+ * parsing source (no execution, no `chant generate` required first):
+ *
+ * 1. Is `name` actually exported from the package's public entry
+ *    (`src/index.ts`)? A registration that names something the package
+ *    doesn't export is documenting a function that doesn't exist.
+ * 2. Does the exported declaration's own shape agree with `isTag`? A tagged
+ *    template is a function whose first parameter is typed
+ *    `TemplateStringsArray` — the only shape `fold()` ever recognizes as a
+ *    tag (see ../../fold/fold.ts). Anything else (a plain function, a class,
+ *    a const object/proxy) cannot be invoked as `` Name`...` `` and must be
+ *    `isTag: false`.
+ *
+ * chant #1044 adds a third question, for the same reason the first two
+ * exist: `foldsAsCall` opts an intrinsic's PLAIN-CALL form into folding, so
+ * declaring it on something authored as a tagged template claims a form that
+ * cannot be called that way. The two flags are mutually exclusive, and a
+ * registration setting both is a failure here rather than a silently ignored
+ * field.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+import * as ts from "typescript";
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export interface IntrinsicAuditItem {
+  name: string;
+  /** The `isTag` value as registered in `src/plugin.ts`'s `intrinsics()`. */
+  declaredIsTag: boolean | undefined;
+  /** The `foldsAsCall` opt-in as registered in `src/plugin.ts` (chant #1044); `undefined` when absent, which means "not opted in". */
+  declaredFoldsAsCall: boolean | undefined;
+  /** Whether `name` resolves to a real export of `src/index.ts`. */
+  exported: boolean;
+  /**
+   * Whether the resolved declaration is genuinely authored as a tagged
+   * template (first parameter typed `TemplateStringsArray`). `undefined`
+   * when the declaration couldn't be located or its shape can't be
+   * determined statically — treated as a failure, not a pass, since a
+   * foldability claim that can't be verified is exactly the unvalidated
+   * state #1067 is closing.
+   */
+  actualIsTag: boolean | undefined;
+  /** True only when exported AND the authored shape matches `declaredIsTag`. */
+  ok: boolean;
+  detail?: string;
+  /**
+   * chant #1044 — false only when `foldsAsCall: true` is registered on
+   * something authored as a tagged template. Tracked separately from
+   * {@link ok} so the two failures report as the two different registration
+   * mistakes they are, rather than one message covering both.
+   */
+  callFormOk: boolean;
+  callFormDetail?: string;
+}
+
+interface DeclaredIntrinsic {
+  name: string;
+  isTag: boolean | undefined;
+  foldsAsCall: boolean | undefined;
+}
+
+interface ExportTarget {
+  /** Relative module specifier as written, e.g. "./intrinsics". */
+  modulePath: string;
+  /** The name as declared in the target module (post `as` rename resolution). */
+  localName: string;
+}
+
+// ── Parsing helpers ──────────────────────────────────────────────────
+
+function parseFile(path: string): ts.SourceFile | undefined {
+  if (!existsSync(path)) return undefined;
+  let text: string;
+  try {
+    text = readFileSync(path, "utf-8");
+  } catch {
+    return undefined;
+  }
+  return ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+}
+
+/**
+ * Find `intrinsics(): IntrinsicDef[] { return [ ... ]; }` (or the arrow-
+ * function-property equivalent) in a plugin.ts source file and extract each
+ * registered `{ name, isTag, foldsAsCall }` triple from the array literal. Returns
+ * `undefined` when no `intrinsics` method exists at all (lexicons with no
+ * intrinsics, e.g. gcp/k8s, still return `[]` — that's a real empty array,
+ * not `undefined`).
+ */
+function extractDeclaredIntrinsics(pluginPath: string): DeclaredIntrinsic[] | undefined {
+  const sf = parseFile(pluginPath);
+  if (!sf) return undefined;
+
+  let arrayLiteral: ts.ArrayLiteralExpression | undefined;
+
+  const findReturnedArray = (body: ts.Block): ts.ArrayLiteralExpression | undefined => {
+    for (const stmt of body.statements) {
+      if (ts.isReturnStatement(stmt) && stmt.expression && ts.isArrayLiteralExpression(stmt.expression)) {
+        return stmt.expression;
+      }
+    }
+    return undefined;
+  };
+
+  const visit = (node: ts.Node): void => {
+    if (arrayLiteral) return;
+
+    if (ts.isMethodDeclaration(node) && node.name && ts.isIdentifier(node.name) && node.name.text === "intrinsics" && node.body) {
+      arrayLiteral = findReturnedArray(node.body);
+    } else if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && node.name.text === "intrinsics") {
+      const init = node.initializer;
+      if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+        if (init.body && ts.isBlock(init.body)) {
+          arrayLiteral = findReturnedArray(init.body);
+        } else if (init.body && ts.isArrayLiteralExpression(init.body)) {
+          arrayLiteral = init.body;
+        }
+      }
+    }
+
+    if (!arrayLiteral) ts.forEachChild(node, visit);
+  };
+  visit(sf);
+
+  if (!arrayLiteral) return undefined;
+
+  const result: DeclaredIntrinsic[] = [];
+  for (const el of arrayLiteral.elements) {
+    if (!ts.isObjectLiteralExpression(el)) continue;
+    let name: string | undefined;
+    let isTag: boolean | undefined;
+    let foldsAsCall: boolean | undefined;
+
+    for (const prop of el.properties) {
+      if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue;
+      const key = prop.name.text;
+      if (key === "name" && ts.isStringLiteralLike(prop.initializer)) {
+        name = prop.initializer.text;
+      } else if (key === "isTag") {
+        if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) isTag = true;
+        else if (prop.initializer.kind === ts.SyntaxKind.FalseKeyword) isTag = false;
+      } else if (key === "foldsAsCall") {
+        if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) foldsAsCall = true;
+        else if (prop.initializer.kind === ts.SyntaxKind.FalseKeyword) foldsAsCall = false;
+      }
+    }
+
+    if (name !== undefined) result.push({ name, isTag, foldsAsCall });
+  }
+
+  return result;
+}
+
+/**
+ * Build a map of publicly-exported name -> where it's really declared, by
+ * parsing `src/index.ts`'s top-level `export { a, b as c } from "./file"`
+ * statements (every lexicon's intrinsics are re-exported this way) plus
+ * direct top-level exported declarations in index.ts itself (`modulePath:
+ * "."`). Wildcard re-exports (`export * from "./generated"`) are not
+ * expanded — none of the 8 lexicons that register intrinsics export them
+ * that way, so this is a deliberate, documented gap rather than a silent one.
+ */
+function extractExportMap(indexPath: string): Map<string, ExportTarget> {
+  const map = new Map<string, ExportTarget>();
+  const sf = parseFile(indexPath);
+  if (!sf) return map;
+
+  const hasExportModifier = (node: ts.Node): boolean =>
+    !!ts.canHaveModifiers(node) && (ts.getModifiers(node) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+
+  for (const stmt of sf.statements) {
+    if (ts.isExportDeclaration(stmt) && stmt.moduleSpecifier && ts.isStringLiteralLike(stmt.moduleSpecifier)) {
+      const modulePath = stmt.moduleSpecifier.text;
+      if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+        for (const spec of stmt.exportClause.elements) {
+          const exportedName = spec.name.text;
+          const localName = spec.propertyName ? spec.propertyName.text : exportedName;
+          map.set(exportedName, { modulePath, localName });
+        }
+      }
+      continue;
+    }
+
+    if (ts.isFunctionDeclaration(stmt) && stmt.name && hasExportModifier(stmt)) {
+      map.set(stmt.name.text, { modulePath: ".", localName: stmt.name.text });
+    } else if (ts.isClassDeclaration(stmt) && stmt.name && hasExportModifier(stmt)) {
+      map.set(stmt.name.text, { modulePath: ".", localName: stmt.name.text });
+    } else if (ts.isVariableStatement(stmt) && hasExportModifier(stmt)) {
+      for (const decl of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name)) {
+          map.set(decl.name.text, { modulePath: ".", localName: decl.name.text });
+        }
+      }
+    }
+  }
+
+  return map;
+}
+
+/** True when a parameter list's first entry is typed `TemplateStringsArray`. */
+function firstParamIsTemplateStringsArray(params: ts.NodeArray<ts.ParameterDeclaration>): boolean {
+  const first = params[0];
+  if (!first?.type || !ts.isTypeReferenceNode(first.type)) return false;
+  const typeName = first.type.typeName;
+  const text = ts.isIdentifier(typeName) ? typeName.text : typeName.right.text;
+  return text === "TemplateStringsArray";
+}
+
+/**
+ * Resolve whether the declaration named `target.localName` in the module
+ * `target.modulePath` (relative to `indexPath`) is authored as a tagged
+ * template. Returns `{ found: false }` when the declaration can't be
+ * located — a function declared but never found is treated as unverifiable,
+ * not as a pass.
+ */
+function resolveActualIsTag(
+  indexPath: string,
+  target: ExportTarget,
+): { found: boolean; isTag?: boolean } {
+  const filePath =
+    target.modulePath === "."
+      ? indexPath
+      : join(dirname(indexPath), `${target.modulePath.replace(/^\.\//, "")}.ts`);
+
+  const sf = parseFile(filePath);
+  if (!sf) return { found: false };
+
+  let result: { found: boolean; isTag?: boolean } | undefined;
+
+  for (const stmt of sf.statements) {
+    if (result) break;
+
+    if (ts.isFunctionDeclaration(stmt) && stmt.name?.text === target.localName) {
+      result = { found: true, isTag: firstParamIsTemplateStringsArray(stmt.parameters) };
+    } else if (ts.isClassDeclaration(stmt) && stmt.name?.text === target.localName) {
+      // A class is invoked with `new X(...)`, never as a tagged template.
+      result = { found: true, isTag: false };
+    } else if (ts.isVariableStatement(stmt)) {
+      for (const decl of stmt.declarationList.declarations) {
+        if (!ts.isIdentifier(decl.name) || decl.name.text !== target.localName) continue;
+        const init = decl.initializer;
+        if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+          result = { found: true, isTag: firstParamIsTemplateStringsArray(init.parameters) };
+        } else {
+          // A const object, proxy, `new X()`, etc. — not callable as a tag.
+          result = { found: true, isTag: false };
+        }
+      }
+    }
+  }
+
+  return result ?? { found: false };
+}
+
+// ── Public entry point ───────────────────────────────────────────────
+
+/**
+ * Audit every intrinsic a lexicon registers in `src/plugin.ts` against
+ * `src/index.ts`'s real export surface and each export's authored shape.
+ * Returns `[]` for a lexicon with no `intrinsics()` method, or one that
+ * registers none — nothing to audit either way.
+ */
+export function auditIntrinsics(lexiconDir: string): IntrinsicAuditItem[] {
+  const pluginPath = join(lexiconDir, "src/plugin.ts");
+  const indexPath = join(lexiconDir, "src/index.ts");
+
+  const declared = extractDeclaredIntrinsics(pluginPath);
+  if (!declared || declared.length === 0) return [];
+
+  const exportMap = extractExportMap(indexPath);
+  const items: IntrinsicAuditItem[] = [];
+
+  for (const d of declared) {
+    const target = exportMap.get(d.name);
+
+    if (!target) {
+      items.push({
+        name: d.name,
+        declaredIsTag: d.isTag,
+        declaredFoldsAsCall: d.foldsAsCall,
+        exported: false,
+        actualIsTag: undefined,
+        ok: false,
+        detail: `"${d.name}" is registered in plugin.ts intrinsics() but is not exported from src/index.ts`,
+        callFormOk: true,
+      });
+      continue;
+    }
+
+    const resolved = resolveActualIsTag(indexPath, target);
+    if (!resolved.found) {
+      items.push({
+        name: d.name,
+        declaredIsTag: d.isTag,
+        declaredFoldsAsCall: d.foldsAsCall,
+        exported: true,
+        actualIsTag: undefined,
+        ok: false,
+        detail: `could not locate the declaration of "${d.name}" (exported from ${target.modulePath}) to verify it against isTag`,
+        callFormOk: true,
+      });
+      continue;
+    }
+
+    const declaredTag = d.isTag === true;
+    const ok = resolved.isTag === declaredTag;
+    // chant #1044 — `foldsAsCall` opts the PLAIN-CALL form in, so it is
+    // meaningless (and, if honored, wrong) on a tagged template. Judged
+    // against how the export is really authored, not against the sibling
+    // `isTag` claim, which may itself be the thing that's wrong.
+    const callFormOk = !(d.foldsAsCall === true && resolved.isTag === true);
+    items.push({
+      name: d.name,
+      declaredIsTag: d.isTag,
+      declaredFoldsAsCall: d.foldsAsCall,
+      exported: true,
+      actualIsTag: resolved.isTag,
+      ok,
+      callFormOk,
+      callFormDetail: callFormOk
+        ? undefined
+        : `"${d.name}" is authored as a tagged template but registered with foldsAsCall: true — the call-form opt-in applies to plain-call intrinsics only`,
+      detail: ok
+        ? undefined
+        : resolved.isTag
+          ? `"${d.name}" is authored as a tagged template (first param: TemplateStringsArray) but registered with isTag: ${d.isTag ?? "undefined"}`
+          : `"${d.name}" is a plain call/declaration (not a tagged template) but registered with isTag: true`,
+    });
+  }
+
+  return items;
+}

package/src/cli/commands/check-lexicon.test.ts

@@ -0,0 +1,34 @@
+import { describe, test, expect } from "vitest";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkLexicon } from "./check-lexicon";
+
+// chant #1067 — check-lexicon.ts had zero tests before this issue, despite
+// being the tool meant to gate every lexicon's completeness. This locks in
+// that checkLexicon() actually wires the new semantic checks (intrinsic
+// foldability audit, example-build audit) into its tier-1 results — not
+// just the pre-existing existence/count checks — against a real,
+// already-built lexicon in this repo.
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..", "..");
+const gitlabDir = join(repoRoot, "lexicons", "gitlab");
+
+describe("checkLexicon", () => {
+  test("includes the new #1067 tier-1 checks by name", async () => {
+    const result = await checkLexicon(gitlabDir);
+    const names = result.items.map((i) => i.name);
+    expect(names).toContain("Every shipped example builds");
+    expect(names).toContain("Registered intrinsics are exported by the package");
+    expect(names).toContain("Registered intrinsics' isTag matches how they're authored");
+    expect(names).toContain("dist/manifest.json declares a chantVersion");
+    expect(names).toContain('package.json routes exports["."].default at ./src/index.ts and deletes emitted JS in build');
+  });
+
+  test("gitlab's own reference() intrinsic passes both the export and isTag audits", async () => {
+    const result = await checkLexicon(gitlabDir);
+    const exported = result.items.find((i) => i.name === "Registered intrinsics are exported by the package");
+    const matches = result.items.find((i) => i.name === "Registered intrinsics' isTag matches how they're authored");
+    expect(exported?.pass).toBe(true);
+    expect(matches?.pass).toBe(true);
+  });
+});

package/src/cli/commands/check-lexicon.ts

@@ -1,5 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "fs";
 import { join, basename } from "path";
+import { auditIntrinsics } from "./check-lexicon-intrinsics";
+import { checkExamplesBuild } from "./check-lexicon-examples";
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -65,7 +67,7 @@ function countSubdirs(dir: string): number {
 /**
  * Run all completeness checks against a lexicon directory.
  */
-export function checkLexicon(dir: string): CheckResult {
+export async function checkLexicon(dir: string): Promise<CheckResult> {
   const items: CheckItem[] = [];
 
   // ── Tier 1: Required ───────────────────────────────────────────
@@ -117,6 +119,70 @@ export function checkLexicon(dir: string): CheckResult {
     pass: existsSync(join(dir, "dist/manifest.json")),
   });
 
+  // chant #1067 — chantVersion was "optional, unchecked": a lexicon could
+  // declare (or omit) a core-version constraint and nothing failed. This
+  // does not validate compatibility against the running core version — that
+  // needs a live check at plugin-load time (a different tool: candidates are
+  // `loadPlugin`/`loadPlugins` in ../plugins.ts), which is a deliberate
+  // non-goal here (see PR description). It closes the narrower gap that the
+  // field can be silently absent or malformed in the shipped manifest.
+  const manifestJson = readOr(join(dir, "dist/manifest.json"));
+  let chantVersionOk = false;
+  let chantVersionDetail: string | undefined;
+  if (manifestJson) {
+    try {
+      const parsed = JSON.parse(manifestJson) as { chantVersion?: unknown };
+      const cv = parsed.chantVersion;
+      chantVersionOk = typeof cv === "string" && /\d/.test(cv);
+      chantVersionDetail = chantVersionOk ? `chantVersion: ${cv as string}` : `chantVersion: ${JSON.stringify(cv)}`;
+    } catch {
+      chantVersionDetail = "dist/manifest.json is not valid JSON";
+    }
+  } else {
+    chantVersionDetail = "dist/manifest.json missing or unreadable";
+  }
+  items.push({
+    name: "dist/manifest.json declares a chantVersion",
+    tier: 1,
+    pass: chantVersionOk,
+    detail: chantVersionDetail,
+  });
+
+  // chant #1067 — packaging shape ("all 11 lexicons route exports['.'].default
+  // at ./src/index.ts and delete emitted JS in build") was real but
+  // unenforced; a lexicon shipping differently would break consumers
+  // silently. Cheap structural check on package.json, not a build execution.
+  const packageJsonRaw = readOr(join(dir, "package.json"));
+  let packagingOk = false;
+  let packagingDetail: string | undefined;
+  if (packageJsonRaw) {
+    try {
+      const pkg = JSON.parse(packageJsonRaw) as {
+        exports?: { "."?: { default?: string } };
+        scripts?: { build?: string };
+      };
+      const defaultExport = pkg.exports?.["."]?.default;
+      const buildScript = pkg.scripts?.build ?? "";
+      const exportOk = defaultExport === "./src/index.ts";
+      const deletesEmittedJs = /-delete/.test(buildScript) && /\.js/.test(buildScript);
+      packagingOk = exportOk && deletesEmittedJs;
+      const problems: string[] = [];
+      if (!exportOk) problems.push(`exports["."].default is ${JSON.stringify(defaultExport)}, expected "./src/index.ts"`);
+      if (!deletesEmittedJs) problems.push(`build script doesn't delete emitted .js from dist/: ${JSON.stringify(buildScript)}`);
+      packagingDetail = problems.length > 0 ? problems.join("; ") : undefined;
+    } catch {
+      packagingDetail = "package.json is not valid JSON";
+    }
+  } else {
+    packagingDetail = "package.json missing or unreadable";
+  }
+  items.push({
+    name: 'package.json routes exports["."].default at ./src/index.ts and deletes emitted JS in build',
+    tier: 1,
+    pass: packagingOk,
+    detail: packagingDetail,
+  });
+
   const exampleCount = countSubdirs(join(dir, "examples"));
   items.push({
     name: "At least 1 example in examples/",
@@ -125,6 +191,76 @@ export function checkLexicon(dir: string): CheckResult {
     detail: exampleCount > 0 ? `${exampleCount} example(s)` : undefined,
   });
 
+  // chant #1067 — every shipped example must actually build. The prior
+  // checks only ever counted example directories; none tried to build one,
+  // so `lexicons/aws/examples/core-concepts` shipped with a discovery-time
+  // "Duplicate export name" error while this tool reported "All tier-1
+  // checks passed." See ./check-lexicon-examples.ts for exactly what
+  // "builds" means here (discovery + serialization, not post-synth/lint).
+  const exampleBuilds = await checkExamplesBuild(dir);
+  const brokenExamples = exampleBuilds.filter((e) => !e.ok);
+  items.push({
+    name: "Every shipped example builds",
+    tier: 1,
+    pass: brokenExamples.length === 0,
+    detail:
+      brokenExamples.length > 0
+        ? brokenExamples.map((e) => `${e.example}: ${e.detail}`).join(" | ")
+        : exampleBuilds.length > 0
+          ? `${exampleBuilds.length} example(s) built`
+          : undefined,
+  });
+
+  // chant #1067 — foldability (isTag) is required and validated, not an
+  // optional flag nobody checks. #1039 shipped with it wrong in both
+  // directions (aws's Sub missing isTag; gitlab's reference() claiming
+  // isTag: true for a plain call) and nothing caught either half. See
+  // ./check-lexicon-intrinsics.ts for what "exported"/"matches" mean.
+  const intrinsicAudit = auditIntrinsics(dir);
+  const unexportedIntrinsics = intrinsicAudit.filter((i) => !i.exported);
+  items.push({
+    name: "Registered intrinsics are exported by the package",
+    tier: 1,
+    pass: unexportedIntrinsics.length === 0,
+    detail:
+      unexportedIntrinsics.length > 0
+        ? unexportedIntrinsics.map((i) => i.detail).join(" | ")
+        : intrinsicAudit.length > 0
+          ? `${intrinsicAudit.length} intrinsic(s) checked`
+          : undefined,
+  });
+
+  const mismatchedIntrinsics = intrinsicAudit.filter((i) => !i.ok);
+  items.push({
+    name: "Registered intrinsics' isTag matches how they're authored",
+    tier: 1,
+    pass: mismatchedIntrinsics.length === 0,
+    detail:
+      mismatchedIntrinsics.length > 0
+        ? mismatchedIntrinsics.map((i) => i.detail).join(" | ")
+        : intrinsicAudit.length > 0
+          ? `${intrinsicAudit.length} intrinsic(s) checked`
+          : undefined,
+  });
+
+  // chant #1044 — the call-form opt-in (`foldsAsCall`) admits a plain call
+  // into `fold()`, which has no general CallExpression case. Declaring it on
+  // a tagged template claims a form the intrinsic cannot be invoked in, so
+  // it fails here rather than being quietly ignored — the same reasoning as
+  // the isTag check above.
+  const badCallForm = intrinsicAudit.filter((i) => !i.callFormOk);
+  items.push({
+    name: "Registered intrinsics' foldsAsCall opt-in is only on plain calls",
+    tier: 1,
+    pass: badCallForm.length === 0,
+    detail:
+      badCallForm.length > 0
+        ? badCallForm.map((i) => i.callFormDetail).join(" | ")
+        : intrinsicAudit.length > 0
+          ? `${intrinsicAudit.length} intrinsic(s) checked`
+          : undefined,
+  });
+
   const hasPluginTest = findFiles(join(dir, "src"), (n) => n === "plugin.test.ts").length > 0;
   items.push({
     name: "plugin.test.ts exists",

package/src/cli/commands/lint.ts

@@ -39,6 +39,26 @@ export function isLintRule(value: unknown): value is LintRule {
 /**
  * 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: string[],
@@ -122,6 +142,13 @@ export interface LintOptions {
   format: "stylish" | "json" | "sarif";
   /** Rules to use (defaults to all) */
   rules?: LintRule[];
+  /**
+   * chant #1051 — opt-in: discover `*.component.ts` files (for the COMP*
+   * composition checks) in a sandboxed child process instead of the CLI's
+   * own process (`chant lint --sandbox`). See `discoverComponents`'s
+   * `sandbox` option (../../components/discover.ts).
+   */
+  sandbox?: boolean;
 }
 
 /**
@@ -296,6 +323,7 @@ async function resolveRegistryContext(
 
 async function runComponentCheckDiagnostics(
   infraPath: string,
+  sandbox?: boolean,
 ): Promise<{ diagnostics: LintDiagnostic[]; suppressed: Array<LintDiagnostic & { reason?: string }> }> {
   // Discovery stays scoped to the lint arg; COMP* severity overrides come from
   // the project-root config, same as the AST-rule pass.
@@ -304,7 +332,7 @@ async function runComponentCheckDiagnostics(
   const allCheckIds = new Set(checks.map((c) => c.id));
 
   const registryContext = await resolveRegistryContext(infraPath);
-  const raw = await runComponentChecks(infraPath, checks, registryContext);
+  const raw = await runComponentChecks(infraPath, checks, registryContext, sandbox);
 
   const fileDirectivesCache = new Map<string, ReturnType<typeof parseDisableComments>>();
   const fileLevelDisable = (
@@ -439,7 +467,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   // 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);
+  const componentResult = await runComponentCheckDiagnostics(infraPath, options.sandbox);
   diagnostics.push(...componentResult.diagnostics);
   suppressed.push(...componentResult.suppressed);
 
@@ -487,7 +515,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
     // `*.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);
+    const postComponentResult = await runComponentCheckDiagnostics(infraPath, options.sandbox);
     diagnostics.push(...postComponentResult.diagnostics);
     suppressed.push(...postComponentResult.suppressed);
   }

package/src/cli/commands/onboard.ts

@@ -307,7 +307,7 @@ export async function printOnboardResult(result: OnboardResult, name: string): P
     console.log("");
     console.log("Lexicon completeness:");
     const { checkLexicon, printCheckResult } = await import("./check-lexicon");
-    const checkResult = checkLexicon(lexiconDir);
+    const checkResult = await checkLexicon(lexiconDir);
     printCheckResult(checkResult, false);
   }
 }