@intentius/chant 0.124.13 → 0.124.14

package/dist/cli/commands/check-lexicon-docs.js

@@ -0,0 +1,79 @@
+/**
+ * Docs reachability audit for the lexicon completeness contract (#1312).
+ *
+ * The contract used to check documentation by counting files — "at least 1
+ * .mdx page" at tier 1, "at least 8" at tier 2 — and never opened one. That
+ * counts a page nothing links to exactly the same as a page a reader can
+ * actually find, so azure, helm and github each accumulated
+ * hand-added pages that appear in no sidebar and are reachable only by typing
+ * their URL. Azure's getting-started, resource reference and composites pages
+ * were all invisible while its ≥8-page check passed comfortably — the count
+ * check was, if anything, rewarded by the orphans.
+ *
+ * Starlight does not auto-discover pages (see docs/README.md), so sidebar
+ * membership is the whole of reachability for a lexicon site.
+ */
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join } from "path";
+/**
+ * Slugs the sidebar reaches, including nested group `items`.
+ *
+ * Read textually rather than by importing the config: `astro.config.mjs` is an
+ * ESM module that imports `@astrojs/starlight`, which a lexicon under check is
+ * not required to have installed. The generator emits `JSON.stringify` output
+ * (double-quoted), but a hand-edited config may use single quotes or a bare
+ * key, so accept all three.
+ */
+export function sidebarSlugs(configSource) {
+    const slugs = new Set();
+    for (const match of configSource.matchAll(/["']?slug["']?\s*:\s*["']([^"']+)["']/g)) {
+        slugs.add(match[1]);
+    }
+    return slugs;
+}
+/**
+ * Audit one lexicon directory for doc pages nothing links to.
+ *
+ * A lexicon with no docs site is not a failure here — tier 1's "at least 1
+ * .mdx doc page" already covers that case, and reporting the same absence
+ * twice would just be noise.
+ */
+export function auditDocsReachability(lexiconDir) {
+    const contentDir = join(lexiconDir, "docs", "src", "content", "docs");
+    const configPath = join(lexiconDir, "docs", "astro.config.mjs");
+    if (!existsSync(contentDir) || !existsSync(configPath)) {
+        return { hasSite: false, pages: [], unreachable: [] };
+    }
+    const slugs = sidebarSlugs(readFileSync(configPath, "utf-8"));
+    const pages = readdirSync(contentDir)
+        .filter((f) => f.endsWith(".mdx") || f.endsWith(".md"))
+        .map((f) => f.replace(/\.mdx?$/, ""))
+        .sort();
+    // `index` is the site root; Starlight reaches it without a sidebar entry.
+    const unreachable = pages.filter((slug) => slug !== "index" && !slugs.has(slug));
+    return { hasSite: true, pages, unreachable };
+}
+const QUADRANTS = new Set(["tutorial", "how-to", "reference", "explanation"]);
+/**
+ * Audit docs/pages/ for authored pages with no Diátaxis quadrant (#1731).
+ *
+ * The docs pipeline throws on the same condition, so this is the cheap
+ * pre-flight that reports every offender at once instead of the first one.
+ */
+export function auditDocsClassification(lexiconDir) {
+    const pagesDir = join(lexiconDir, "docs", "pages");
+    if (!existsSync(pagesDir))
+        return { hasPages: false, unclassified: [] };
+    const unclassified = [];
+    for (const file of readdirSync(pagesDir).sort()) {
+        if (!file.endsWith(".mdx") && !file.endsWith(".md"))
+            continue;
+        const text = readFileSync(join(pagesDir, file), "utf-8");
+        const end = text.startsWith("---\n") ? text.indexOf("\n---", 4) : -1;
+        const fm = end === -1 ? "" : text.slice(4, end);
+        const value = fm.match(/^diataxis:\s*(.+)$/m)?.[1].trim();
+        if (!value || !QUADRANTS.has(value))
+            unclassified.push(file);
+    }
+    return { hasPages: true, unclassified };
+}

package/dist/cli/commands/check-lexicon-examples.js

@@ -0,0 +1,177 @@
+/**
+ * "Every shipped example builds" (chant #1067) and "every shipped example
+ * passes its own lexicon's post-synth checks" (chant #1400).
+ *
+ * `check-lexicon.ts`'s existing example checks only count directories
+ * ("At least 1 example", "At least 3 examples", "At least 5 examples with
+ * tests") — nothing ever tries to build one. `lexicons/aws/examples/core-concepts`
+ * shipped with a discovery-time error (two files independently exporting a
+ * top-level `dataBucket`) and `chant dev check-lexicon lexicons/aws` still
+ * reported "All tier-1 checks passed," because none of its 29 checks touch
+ * build output. This module closes that gap directly: for every non-empty
+ * `examples/<name>/src/` directory, run the same discover-and-serialize
+ * pipeline `chant build` runs and report whether it produced output with no
+ * structural error.
+ *
+ * #1067 scoped "builds" to discovery + serialization on purpose, and said
+ * so here: three aws examples (lambda-api, lambda-s3, shared-alb) failed
+ * WAW042/WAW054 at error severity at the time, for defects that issue never
+ * set out to fix. #1400 fixed those three and added the second axis: after
+ * serialization, the post-synth checks each loaded plugin ships run against
+ * that plugin's own output, exactly as `chant build` runs them (scoped per
+ * plugin, `lint.rules` from the example's chant.config applied), and any
+ * diagnostic left at `error` severity fails the example. Warnings do not.
+ * An example is what a user copies wholesale; it must not teach a pattern
+ * the lexicon it demonstrates flags as an error.
+ *
+ * #2101 added the third axis: core's own Op-model checks (OPS012/OPS013/
+ * OPS014, `../../lint/rules/op/`) run over the same result, as `chant build`
+ * runs them, so an example carrying an Op has that Op validated here rather
+ * than only when a user builds the example themselves. They are given the
+ * activity contracts every loaded lexicon declares, resolved the same way
+ * `chant build` resolves them, so a step calling that lexicon's own activity
+ * validates against its own schemas.
+ */
+import { lexiconNames as declaredLexiconNames } from "../../lexicon-module.js";
+import { existsSync, readdirSync } from "fs";
+import { join } from "path";
+import { build } from "../../build.js";
+import { findInfraFiles } from "../../discovery/files.js";
+import { detectLexicons } from "../../detectLexicon.js";
+import { loadChantConfig } from "../../config.js";
+import { loadPlugins, collectBuildRootContributors } from "../plugins.js";
+import { runPostSynthChecks } from "../../lint/post-synth.js";
+import { coreOpChecks } from "../../lint/rules/op/index.js";
+import { loadActivityContracts } from "../../op/activity-contract-registry.js";
+import { applyConfiguredSeverity } from "../../lint/config.js";
+/**
+ * Run core's Op-model checks over the whole result, then each plugin's own
+ * post-synth checks against that plugin's output — the same scoping and
+ * `lint.rules` severity resolution `cli/commands/build.ts` applies — and
+ * return what is left at `error` severity. Project `lint.policies` are not
+ * run here: those are the example author's organizational policy, not the
+ * lexicon's contract.
+ */
+export function postSynthErrors(plugins, result, lintRules, activityContracts) {
+    const errors = [];
+    // Core's Op-model checks first (#2101). An Op is recognized by entity type,
+    // not by which lexicon declared it, so these run over the FULL result the
+    // way `chant build` runs them — unscoped, and regardless of which plugins
+    // loaded. Without this an example's Op reached output unvalidated, which is
+    // why the terraform, aws and render examples kept their Ops outside `src/`.
+    const opDiags = runPostSynthChecks(coreOpChecks(), result, undefined, { activityContracts });
+    for (const diag of applyConfiguredSeverity(opDiags, lintRules).diagnostics) {
+        if (diag.severity === "error")
+            errors.push(diag);
+    }
+    for (const plugin of plugins) {
+        if (!plugin.postSynthChecks)
+            continue;
+        const checks = plugin.postSynthChecks();
+        if (checks.length === 0)
+            continue;
+        const outputKey = plugin.serializer.name;
+        const scopedOutputs = new Map();
+        const pluginOutput = result.outputs.get(outputKey);
+        if (pluginOutput !== undefined)
+            scopedOutputs.set(outputKey, pluginOutput);
+        const diags = runPostSynthChecks(checks, { ...result, outputs: scopedOutputs }, undefined, { activityContracts });
+        const { diagnostics } = applyConfiguredSeverity(diags, lintRules);
+        for (const diag of diagnostics) {
+            if (diag.severity === "error")
+                errors.push(diag);
+        }
+    }
+    return errors;
+}
+function formatPostSynthError(diag) {
+    const prefix = diag.entity ? `[${diag.entity}] ` : "";
+    return `${diag.checkId}: ${prefix}${diag.message}`;
+}
+/**
+ * Build every non-empty example under `<lexiconDir>/examples/*\/src` and
+ * report per-example pass/fail. Returns `[]` when the lexicon has no
+ * `examples/` directory at all (a separate tier-1 check already covers
+ * that).
+ */
+export async function checkExamplesBuild(lexiconDir) {
+    const examplesDir = join(lexiconDir, "examples");
+    if (!existsSync(examplesDir))
+        return [];
+    const results = [];
+    const entries = readdirSync(examplesDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+    for (const entry of entries) {
+        const srcDir = join(examplesDir, entry.name, "src");
+        if (!existsSync(srcDir))
+            continue;
+        const contents = readdirSync(srcDir);
+        if (contents.length === 0 || (contents.length === 1 && contents[0] === ".gitkeep"))
+            continue;
+        try {
+            const files = await findInfraFiles(srcDir);
+            if (files.length === 0)
+                continue;
+            // An example's own chant.config.{ts,json} (living beside src/, not in
+            // it) can declare `lexicons` explicitly — the same precedence real
+            // `chant build` gives it via resolveProjectLexicons() in ../plugins.ts.
+            // Needed for examples like helm's HelmRender ones, whose composite
+            // legitimately produces entities tagged with a lexicon (e.g. "k8s")
+            // that no source-file import mentions — detection from imports alone
+            // can never see it, so the example built with only its "own" lexicon's
+            // plugin and silently dropped every entity of the other, undetectable
+            // one. Detection from source-file imports (unchanged) remains the
+            // fallback for the many examples with no declared `lexicons` list.
+            const { config: exampleConfig } = await loadChantConfig(join(examplesDir, entry.name));
+            const lexiconNames = exampleConfig.lexicons && exampleConfig.lexicons.length > 0
+                ? declaredLexiconNames(exampleConfig.lexicons)
+                : await detectLexicons(files);
+            if (lexiconNames.length === 0) {
+                results.push({
+                    example: entry.name,
+                    ok: false,
+                    detail: "no lexicon imports detected in src/ — cannot determine which plugin(s) to build with",
+                });
+                continue;
+            }
+            const plugins = await loadPlugins(lexiconNames);
+            // Bind each plugin's `buildRoots()` hook exactly as `chant build` does
+            // (#2083): a lexicon whose entities come from config-declared roots
+            // rather than typed source (k8s kustomize roots, terraform roots) has
+            // nothing to serialize otherwise, and its example would read as
+            // "produced no output" for a reason that is this harness's, not the
+            // example's.
+            const exampleDir = join(examplesDir, entry.name);
+            const buildRoots = collectBuildRootContributors(plugins, exampleConfig, exampleDir);
+            const result = await build(srcDir, plugins.map((p) => p.serializer), undefined, { buildRoots });
+            const structuralErrors = result.errors.map((e) => e.message);
+            const producedOutput = result.outputs.size > 0;
+            const structurallyOk = structuralErrors.length === 0 && producedOutput;
+            // #1400 — only once the build is structurally sound. A discovery error
+            // already explains the failure, and partial output is not the output
+            // the checks are meant to see.
+            const postSynth = structurallyOk
+                ? postSynthErrors(plugins, result, exampleConfig.lint?.rules, await loadActivityContracts(plugins))
+                : [];
+            const ok = structurallyOk && postSynth.length === 0;
+            results.push({
+                example: entry.name,
+                ok,
+                detail: ok
+                    ? undefined
+                    : structuralErrors.length > 0
+                        ? structuralErrors.join("; ")
+                        : !producedOutput
+                            ? "discovered source but produced no output"
+                            : `post-synth error(s): ${postSynth.map(formatPostSynthError).join("; ")}`,
+            });
+        }
+        catch (err) {
+            results.push({
+                example: entry.name,
+                ok: false,
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return results;
+}

package/dist/cli/commands/check-lexicon-intrinsics.js

@@ -0,0 +1,291 @@
+/**
+ * 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";
+// ── Parsing helpers ──────────────────────────────────────────────────
+function parseFile(path) {
+    if (!existsSync(path))
+        return undefined;
+    let text;
+    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) {
+    const sf = parseFile(pluginPath);
+    if (!sf)
+        return undefined;
+    let arrayLiteral;
+    const findReturnedArray = (body) => {
+        for (const stmt of body.statements) {
+            if (ts.isReturnStatement(stmt) && stmt.expression && ts.isArrayLiteralExpression(stmt.expression)) {
+                return stmt.expression;
+            }
+        }
+        return undefined;
+    };
+    const visit = (node) => {
+        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 = [];
+    for (const el of arrayLiteral.elements) {
+        if (!ts.isObjectLiteralExpression(el))
+            continue;
+        let name;
+        let isTag;
+        let foldsAsCall;
+        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) {
+    const map = new Map();
+    const sf = parseFile(indexPath);
+    if (!sf)
+        return map;
+    const hasExportModifier = (node) => !!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) {
+    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, target) {
+    const filePath = target.modulePath === "."
+        ? indexPath
+        : join(dirname(indexPath), `${target.modulePath.replace(/^\.\//, "")}.ts`);
+    const sf = parseFile(filePath);
+    if (!sf)
+        return { found: false };
+    let result;
+    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) {
+    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 = [];
+    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/dist/cli/commands/check-lexicon-mcp.js

@@ -0,0 +1,82 @@
+/**
+ * Audit of the names a lexicon's MCP contributions are registered under (#1341).
+ *
+ * Core namespaces every contribution — `<lexicon>:<verb>` for a tool,
+ * `chant://<lexicon>/<path>` for a resource — but core is not the only place
+ * that applies a prefix. `createDiffTool`/`createCatalogResource`
+ * (../../lexicon-plugin-helpers.ts) emit `<lexicon>:diff` and
+ * `<lexicon>:resource-catalog`, eleven lexicons write the prefix into the name
+ * by hand, and `lexicon-authoring/lsp-mcp.mdx` taught a third form for URIs.
+ * Applying the namespace unconditionally shipped `gitlab:gitlab:diff`,
+ * `aws:aws:diff`, and `chant://azure/chant://lexicon/azure/catalog` in every
+ * `chant serve mcp` session, while every doc named the single-prefixed form.
+ *
+ * The rule this checks is the one an agent experiences, not the one a lexicon
+ * author typed: whatever the declaration style, the registered name must be a
+ * single well-formed namespaced identifier. That keeps the check indifferent to
+ * which of the three authored forms a lexicon uses, and still fails the moment a
+ * name doubles or carries an embedded scheme.
+ */
+import { readFileSync } from "fs";
+import { basename, join } from "path";
+import { namespacedToolName, namespacedResourceUri } from "../mcp/server.js";
+/** `@intentius/chant-lexicon-aws` → `aws`; falls back to the directory name. */
+export function lexiconNameFor(dir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+        const match = /chant-lexicon-([a-z0-9-]+)$/.exec(pkg.name ?? "");
+        if (match)
+            return match[1];
+    }
+    catch {
+        // fall through to the directory name
+    }
+    return basename(dir);
+}
+const toolPattern = (lexicon) => new RegExp(`^${lexicon}:[a-z0-9][a-z0-9-]*$`);
+const resourcePattern = (lexicon) => new RegExp(`^chant://${lexicon}/[A-Za-z0-9][A-Za-z0-9._/-]*$`);
+/**
+ * The malformed registered names among a lexicon's contributions. Pure, so the
+ * rule can be tested without loading a lexicon package.
+ */
+export function mcpNameViolations(lexicon, tools, resources) {
+    const violations = [];
+    for (const tool of tools) {
+        const registered = namespacedToolName(lexicon, tool.name);
+        if (!toolPattern(lexicon).test(registered)) {
+            violations.push(`tool ${JSON.stringify(tool.name)} registers as ${JSON.stringify(registered)}`);
+        }
+    }
+    for (const resource of resources) {
+        const registered = namespacedResourceUri(lexicon, resource.uri);
+        if (!resourcePattern(lexicon).test(registered)) {
+            violations.push(`resource ${JSON.stringify(resource.uri)} registers as ${JSON.stringify(registered)}`);
+        }
+    }
+    return violations;
+}
+/**
+ * Register this lexicon's MCP contributions the way the server does and check
+ * the resulting names.
+ */
+export async function auditMcpNames(dir) {
+    const lexicon = lexiconNameFor(dir);
+    let plugin;
+    try {
+        const { loadPlugins } = await import("../plugins.js");
+        const plugins = await loadPlugins([lexicon]);
+        if (plugins.length === 0)
+            return { checked: 0, violations: [], loaded: false };
+        plugin = plugins[0];
+    }
+    catch {
+        return { checked: 0, violations: [], loaded: false };
+    }
+    const tools = plugin.mcpTools?.() ?? [];
+    const resources = plugin.mcpResources?.() ?? [];
+    return {
+        checked: tools.length + resources.length,
+        violations: mcpNameViolations(lexicon, tools, resources),
+        loaded: true,
+    };
+}

package/dist/cli/commands/check-lexicon-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-lexicon-plugin.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/check-lexicon-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAEpE,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoB9D;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAwB5E;AAED,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,aAAa,GAAG,OAAO,CAE/F;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,GAAG;IAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAOvF"}
+{"version":3,"file":"check-lexicon-plugin.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/check-lexicon-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAGpE,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoB9D;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAyB5E;AAED,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,aAAa,GAAG,OAAO,CAE/F;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,GAAG;IAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAOvF"}