@intentius/chant 0.37.2 → 0.38.0

package/dist/ownership.d.ts

@@ -78,4 +78,37 @@ export declare function tagArrayToMap(tags: ReadonlyArray<{
  * undefined when the managed-by marker is absent.
  */
 export declare function readOwnership(tagsOrLabels: Record<string, unknown> | undefined, keys: ChannelKeys): OwnershipMarker | undefined;
+/**
+ * A read path that can resolve an ownership verdict from the marker (#1348).
+ *
+ * Per-path rather than per-lexicon because the answer genuinely differs by
+ * path: aws stamps tags at synthesis and reads them on the deep observation and
+ * on live export, but `describeResources` is sourced from
+ * `describe-stack-resources`, which returns no tags at all — so an `owned: true`
+ * thin read against aws can only answer `unknown`.
+ */
+export type OwnershipReadPath = "describeResources" | "observeResourcesDeep" | "exportResources";
+/**
+ * Where a lexicon can stamp and read chant's ownership marker (#1348).
+ *
+ * `ResourceMetadata.ownership` documents an obligation — a lexicon with no
+ * marker channel on a path must stamp `unknown` rather than degrade silently,
+ * because the change set never escalates `unknown` to a delete — and that
+ * obligation had no type, no declaration, and no check. A caller could not
+ * learn whether `owned: true` was answerable except by asking and reading a
+ * warning on stderr afterwards, which is invisible to `lifecycle plan`, which
+ * is where the wrong delete gets proposed.
+ *
+ * Absent means the lexicon has no marker channel at all: every verdict it
+ * returns must be `unknown`. Declaring one is a claim the conformance suite
+ * checks — on a declared path, verdicts must be `owned` or `foreign`.
+ */
+export interface OwnershipChannel {
+    /** The provider-native keys this lexicon stamps into. */
+    readonly keys: ChannelKeys;
+    /** The read paths that resolve a verdict from the marker. */
+    readonly reads: readonly OwnershipReadPath[];
+}
+/** Whether this lexicon resolves a real verdict on `path`, or can only say `unknown`. */
+export declare function resolvesOwnershipOn(channel: OwnershipChannel | undefined, path: OwnershipReadPath): boolean;
 //# sourceMappingURL=ownership.d.ts.map

package/dist/ownership.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ownership.d.ts","sourceRoot":"","sources":["../src/ownership.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,0BAA0B,UAAU,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAIlC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,eAAe,GACtB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACjD,IAAI,EAAE,WAAW,GAChB,OAAO,CAGT;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACjD,IAAI,EAAE,WAAW,GAChB,OAAO,GAAG,SAAS,CAErB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,CAAC;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,SAAS,GACjE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACjD,IAAI,EAAE,WAAW,GAChB,eAAe,GAAG,SAAS,CAQ7B"}
+{"version":3,"file":"ownership.d.ts","sourceRoot":"","sources":["../src/ownership.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,0BAA0B,UAAU,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAIlC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,eAAe,GACtB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACjD,IAAI,EAAE,WAAW,GAChB,OAAO,CAGT;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACjD,IAAI,EAAE,WAAW,GAChB,OAAO,GAAG,SAAS,CAErB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,CAAC;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,SAAS,GACjE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACjD,IAAI,EAAE,WAAW,GAChB,eAAe,GAAG,SAAS,CAQ7B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,mBAAmB,GAAG,sBAAsB,GAAG,iBAAiB,CAAC;AAEjG;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC9C;AAED,yFAAyF;AACzF,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAET"}

package/dist/serializer.d.ts

@@ -46,6 +46,21 @@ export interface Serializer {
      * Prefix used for rules in this lexicon
      */
     rulePrefix: string;
+    /**
+     * Further id families this lexicon owns, beyond {@link rulePrefix} (#1349).
+     *
+     * The prefix exists so ids do not collide when several lexicons are loaded
+     * together — forgejo wraps github's rules as `WFJ-GHA0xx` for exactly that
+     * reason. It was declared and checked by nothing, and k8s quietly shipped
+     * five `ARGO0xx` checks outside its own `WK8`.
+     *
+     * A second family is sometimes right: Argo CD is a distinct product surface
+     * that happens to be covered by the k8s lexicon, and renaming published ids
+     * would break every `chant-disable ARGO001` in the wild. Declaring it keeps
+     * the collision guarantee while allowing the split — an undeclared family is
+     * a tier-1 failure.
+     */
+    extraRulePrefixes?: readonly string[];
     /**
      * Serializes the entities to a string representation
      * @param entities - Map of entity name to Declarable entity

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAE5B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,SAAS,CACP,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACjC,OAAO,CAAC,EAAE,aAAa,EAAE,EACzB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,gBAAgB,CAAC;IAE7B;;;;;OAKG;IACH,iBAAiB,CAAC,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC;CACpD"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAE5B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEtC;;;;;OAKG;IACH,SAAS,CACP,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACjC,OAAO,CAAC,EAAE,aAAa,EAAE,EACzB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,gBAAgB,CAAC;IAE7B;;;;;OAKG;IACH,iBAAiB,CAAC,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC;CACpD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.37.2",
+  "version": "0.38.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/audit/catalog.test.ts

@@ -1,10 +1,24 @@
 import { describe, test, expect } from "vitest";
+import { readdirSync } from "fs";
+import { join } from "path";
 import { RULE_CATALOG, RULE_CATEGORY, auditRule, resolveAuditCatalog } from "./catalog";
 import { loadPlugins } from "../cli/plugins";
 
-const AUDIT_LEXICONS = ["github", "gitlab", "forgejo", "k8s", "docker", "aws", "azure", "gcp", "helm"];
-
-/** All post-synth check ids the audit can actually surface, from the lexicons. */
+/**
+ * Every lexicon in the repo, enumerated rather than listed (#1346).
+ *
+ * This was nine hardcoded names. It missed fountain, which contributes a
+ * catalog, and could not notice fly and temporal, which did not — so their six
+ * post-synth checks reached `chant audit` with no title, tier, fix kind, or
+ * category, and the guard meant to catch exactly that was blind to them. A
+ * thirteenth lexicon would have been invisible to it on arrival.
+ */
+const AUDIT_LEXICONS = readdirSync(join(__dirname, "../../../../lexicons"), { withFileTypes: true })
+  .filter((e) => e.isDirectory())
+  .map((e) => e.name)
+  .sort();
+
+/** Post-synth check ids — what the catalog is required to cover. */
 async function realCheckIds(): Promise<Set<string>> {
   const plugins = await loadPlugins(AUDIT_LEXICONS);
   const ids = new Set<string>();
@@ -16,6 +30,27 @@ async function realCheckIds(): Promise<Set<string>> {
   return ids;
 }
 
+/**
+ * Every rule id a lexicon ships, post-synth or lint — what a catalog entry is
+ * allowed to name.
+ *
+ * Wider than {@link realCheckIds} on purpose. A catalog must cover the
+ * post-synth checks, because those are what `chant audit` surfaces, but an
+ * entry for a lint rule is not stale: fountain documents FTN001, a lint rule,
+ * because a reader hitting it wants the same metadata. Requiring the reverse —
+ * an entry for every lint rule in every lexicon — would be a much larger claim
+ * than the audit makes.
+ */
+async function shippedRuleIds(): Promise<Set<string>> {
+  const plugins = await loadPlugins(AUDIT_LEXICONS);
+  const ids = new Set<string>();
+  for (const plugin of plugins) {
+    for (const check of plugin.postSynthChecks?.() ?? []) ids.add(check.id);
+    for (const rule of plugin.lintRules?.() ?? []) ids.add(rule.id);
+  }
+  return ids;
+}
+
 /** The effective catalog the auditor uses — core static + every lexicon's contributed entries (#687). */
 const aggregate = () => resolveAuditCatalog(AUDIT_LEXICONS);
 
@@ -26,12 +61,29 @@ describe("RULE_CATALOG (aggregated: core static + lexicon-contributed, #687)", (
     expect(missing).toEqual([]);
   });
 
-  test("has no stale entries that aren't real checks", async () => {
-    const [real, catalog] = [await realCheckIds(), await aggregate()];
-    const stale = Object.keys(catalog).filter((id) => !real.has(id)).sort();
+  test("has no stale entries that aren't real rules", async () => {
+    const [shipped, catalog] = [await shippedRuleIds(), await aggregate()];
+    const stale = Object.keys(catalog)
+      .filter((id) => !shipped.has(id))
+      // Core's own cross-cutting ids are not any one lexicon's to ship.
+      .filter((id) => !(id in RULE_CATALOG))
+      .sort();
     expect(stale).toEqual([]);
   });
 
+  test("every lexicon that ships post-synth checks contributes a catalog for them", async () => {
+    const plugins = await loadPlugins(AUDIT_LEXICONS);
+    const uncatalogued = plugins
+      .map((plugin) => {
+        const checks = (plugin.postSynthChecks?.() ?? []).map((c) => c.id);
+        const catalog = plugin.auditCatalog?.() ?? {};
+        const missing = checks.filter((id) => !(id in catalog) && !(id in RULE_CATALOG));
+        return missing.length > 0 ? `${plugin.name}: ${missing.join(", ")}` : undefined;
+      })
+      .filter((entry): entry is string => entry !== undefined);
+    expect(uncatalogued).toEqual([]);
+  });
+
   test("every entry has a title, remediation, and valid tier/fixKind/category", async () => {
     for (const [id, m] of Object.entries(await aggregate())) {
       expect(m.id, `${id} id matches key`).toBe(id);

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

@@ -0,0 +1,73 @@
+/**
+ * The completeness checklist and the tool it describes must agree (#1343).
+ *
+ * They did not. The doc listed 16/16/14 checks where the tool ran 18/14/9 —
+ * seven rows described checks that do not exist anywhere in `check-lexicon.ts`
+ * (`default-labels.test.ts`, `coverage.test.ts`, the three `import/*` tests,
+ * `exportResources()` implemented, and the ownership marker), and two real
+ * tier-1 checks were documented nowhere. The two missing ones were the damaging
+ * direction: an author reading the checklist would have believed live export and
+ * ownership marking were verified somewhere, and nothing verifies either.
+ *
+ * A hand-maintained parallel description of a tool drifts. This test makes the
+ * doc's first column the check's own `name`, so drift is a build failure rather
+ * than something a reviewer has to notice.
+ */
+
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { checkLexicon } from "./check-lexicon";
+
+const CHECKLIST = join(
+  __dirname,
+  "../../../../../docs/src/content/docs/lexicon-authoring/completeness-checklist.mdx",
+);
+
+/** The check names listed under `## Tier <n>` in the checklist. */
+function documentedChecks(markdown: string, tier: 1 | 2 | 3): string[] {
+  const section = markdown.split(new RegExp(`^## Tier ${tier}\\b`, "m"))[1];
+  if (section === undefined) throw new Error(`no "## Tier ${tier}" section in the checklist`);
+  const body = section.split(/^## /m)[0];
+  const names: string[] = [];
+  for (const line of body.split("\n")) {
+    // A table row whose first cell is a backticked check name.
+    const match = /^\|\s*`(.+?)`\s*\|/.exec(line);
+    if (match) names.push(match[1]);
+  }
+  return names;
+}
+
+describe("the completeness checklist matches check-lexicon (#1343)", () => {
+  const markdown = readFileSync(CHECKLIST, "utf-8");
+
+  // aws is the reference lexicon; the set of checks run is the same for any
+  // directory, since every check is pushed unconditionally.
+  const resultPromise = checkLexicon(join(__dirname, "../../../../../lexicons/aws"));
+
+  for (const tier of [1, 2, 3] as const) {
+    test(`tier ${tier} documents exactly the checks the tool runs`, async () => {
+      const executed = (await resultPromise).items.filter((i) => i.tier === tier).map((i) => i.name);
+      const documented = documentedChecks(markdown, tier);
+
+      const undocumented = executed.filter((n) => !documented.includes(n));
+      const phantom = documented.filter((n) => !executed.includes(n));
+
+      expect({ undocumented, phantom }).toEqual({ undocumented: [], phantom: [] });
+      expect(documented).toHaveLength(executed.length);
+    });
+  }
+
+  test("the checklist lists the checks in the order the tool reports them", async () => {
+    for (const tier of [1, 2, 3] as const) {
+      const executed = (await resultPromise).items.filter((i) => i.tier === tier).map((i) => i.name);
+      expect(documentedChecks(markdown, tier)).toEqual(executed);
+    }
+  });
+
+  test("no tier section is empty — a parsing regression would silently pass the set comparison", () => {
+    for (const tier of [1, 2, 3] as const) {
+      expect(documentedChecks(markdown, tier).length).toBeGreaterThan(0);
+    }
+  });
+});

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

@@ -0,0 +1,93 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { mcpNameViolations, lexiconNameFor } from "./check-lexicon-mcp";
+
+const tools = (...names: string[]) => names.map((name) => ({ name }));
+const resources = (...uris: string[]) => uris.map((uri) => ({ uri }));
+
+describe("mcpNameViolations (#1341)", () => {
+  test("a bare tool name is fine — core supplies the namespace", () => {
+    expect(mcpNameViolations("gitlab", tools("migrate"), [])).toEqual([]);
+  });
+
+  test("a self-prefixed tool name is fine — core does not double it", () => {
+    expect(mcpNameViolations("gitlab", tools("gitlab:diff"), [])).toEqual([]);
+  });
+
+  test("a name carrying another lexicon's prefix is a violation", () => {
+    // This is the shape the doubling bug produced: `gitlab:gitlab:diff`.
+    const found = mcpNameViolations("git", tools("gitlab:diff"), []);
+    expect(found).toHaveLength(1);
+    expect(found[0]).toContain("git:gitlab:diff");
+  });
+
+  test("an uppercase or spaced tool name is a violation", () => {
+    expect(mcpNameViolations("aws", tools("Diff Resources"), [])).toHaveLength(1);
+    expect(mcpNameViolations("aws", tools("Diff"), [])).toHaveLength(1);
+  });
+
+  test("hyphenated verbs are allowed", () => {
+    expect(mcpNameViolations("github", tools("github:workflow-yaml"), [])).toEqual([]);
+  });
+
+  test("a bare resource path is fine", () => {
+    expect(mcpNameViolations("aws", [], resources("examples/s3-bucket"))).toEqual([]);
+  });
+
+  test("the colon form the shared catalog helper emits is fine", () => {
+    expect(mcpNameViolations("aws", [], resources("aws:resource-catalog"))).toEqual([]);
+  });
+
+  test("the chant://lexicon/<name>/ form the authoring docs taught is fine once normalized", () => {
+    expect(mcpNameViolations("azure", [], resources("chant://lexicon/azure/catalog"))).toEqual([]);
+  });
+
+  test("a uri carrying a foreign scheme is a violation", () => {
+    // azure shipped `chant://azure/chant://lexicon/azure/catalog` this way when
+    // the lexicon name in the uri did not match the lexicon being registered.
+    const found = mcpNameViolations("aws", [], resources("chant://lexicon/azure/catalog"));
+    expect(found).toHaveLength(1);
+    expect(found[0]).toContain("chant://aws/chant://lexicon/azure/catalog");
+  });
+
+  test("an already-registered uri passes through", () => {
+    expect(mcpNameViolations("aws", [], resources("chant://aws/catalog"))).toEqual([]);
+  });
+
+  test("tools and resources are reported together", () => {
+    expect(mcpNameViolations("aws", tools("Bad Name"), resources("chant://other/x"))).toHaveLength(2);
+  });
+
+  test("a lexicon contributing nothing has nothing to violate", () => {
+    expect(mcpNameViolations("fly", [], [])).toEqual([]);
+  });
+});
+
+describe("lexiconNameFor", () => {
+  function fixture(pkg?: Record<string, unknown>): string {
+    const dir = mkdtempSync(join(tmpdir(), "chant-mcp-name-"));
+    mkdirSync(dir, { recursive: true });
+    if (pkg) writeFileSync(join(dir, "package.json"), JSON.stringify(pkg));
+    return dir;
+  }
+
+  test("reads the lexicon name out of the package name", () => {
+    expect(lexiconNameFor(fixture({ name: "@intentius/chant-lexicon-aws" }))).toBe("aws");
+  });
+
+  test("handles a hyphenated lexicon name", () => {
+    expect(lexiconNameFor(fixture({ name: "@intentius/chant-lexicon-my-cloud" }))).toBe("my-cloud");
+  });
+
+  test("falls back to the directory name when package.json is missing", () => {
+    const dir = fixture();
+    expect(lexiconNameFor(dir)).toBe(dir.split("/").pop());
+  });
+
+  test("falls back when the package name is not a lexicon package", () => {
+    const dir = fixture({ name: "@intentius/chant" });
+    expect(lexiconNameFor(dir)).toBe(dir.split("/").pop());
+  });
+});

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

@@ -0,0 +1,103 @@
+/**
+ * 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";
+
+export interface McpNameAudit {
+  /** How many tools + resources were examined. */
+  checked: number;
+  /** One human-readable line per malformed registered name. */
+  violations: string[];
+  /** False when the lexicon could not be loaded — the audit is then vacuous. */
+  loaded: boolean;
+}
+
+/** `@intentius/chant-lexicon-aws` → `aws`; falls back to the directory name. */
+export function lexiconNameFor(dir: string): string {
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { name?: string };
+    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: string): RegExp =>
+  new RegExp(`^${lexicon}:[a-z0-9][a-z0-9-]*$`);
+
+const resourcePattern = (lexicon: string): RegExp =>
+  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: string,
+  tools: Array<{ name: string }>,
+  resources: Array<{ uri: string }>,
+): string[] {
+  const violations: string[] = [];
+  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: string): Promise<McpNameAudit> {
+  const lexicon = lexiconNameFor(dir);
+  let plugin: {
+    mcpTools?(): Array<{ name: string }>;
+    mcpResources?(): Array<{ uri: string }>;
+  };
+  try {
+    const { loadPlugins } = await import("../plugins");
+    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/src/cli/commands/check-lexicon-plugin.test.ts

@@ -0,0 +1,149 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { loadLexiconFromDir, pluginEntryFor, registers, safeList } from "./check-lexicon-plugin";
+import type { LexiconPlugin } from "../../lexicon";
+
+const roots: string[] = [];
+
+function lexiconDir(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-lexicon-load-"));
+  roots.push(dir);
+  for (const [rel, content] of Object.entries(files)) {
+    const path = join(dir, rel);
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, content);
+  }
+  return dir;
+}
+
+/** A module source exporting a minimally valid LexiconPlugin. */
+const pluginSource = (name: string, extra = "") => `
+export const plugin = {
+  name: ${JSON.stringify(name)},
+  serializer: { name: ${JSON.stringify(name)}, rulePrefix: "XYZ", serialize: () => "" },
+  generate: async () => {},
+  validate: async () => {},
+  coverage: async () => {},
+  package: async () => {},
+  ${extra}
+};
+`;
+
+afterAll(() => {
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+});
+
+describe("pluginEntryFor", () => {
+  test("prefers the entry the package declares", () => {
+    const dir = lexiconDir({
+      "package.json": JSON.stringify({ exports: { ".": { default: "./src/index.ts" } } }),
+      "src/index.ts": "",
+      "src/plugin.ts": "",
+    });
+    expect(pluginEntryFor(dir)).toBe(join(dir, "src/index.ts"));
+  });
+
+  test("falls back to src/index.ts when no entry is declared", () => {
+    const dir = lexiconDir({ "src/index.ts": "" });
+    expect(pluginEntryFor(dir)).toBe(join(dir, "src/index.ts"));
+  });
+
+  test("falls back to src/plugin.ts when there is no index", () => {
+    const dir = lexiconDir({ "src/plugin.ts": "" });
+    expect(pluginEntryFor(dir)).toBe(join(dir, "src/plugin.ts"));
+  });
+
+  test("skips a declared entry that does not exist", () => {
+    const dir = lexiconDir({
+      "package.json": JSON.stringify({ exports: { ".": { default: "./dist/index.js" } } }),
+      "src/index.ts": "",
+    });
+    expect(pluginEntryFor(dir)).toBe(join(dir, "src/index.ts"));
+  });
+
+  test("returns undefined when nothing is importable", () => {
+    expect(pluginEntryFor(lexiconDir({ "README.md": "" }))).toBeUndefined();
+  });
+});
+
+describe("loadLexiconFromDir", () => {
+  test("finds the plugin among the module's exports", async () => {
+    const dir = lexiconDir({ "src/index.ts": pluginSource("mock") });
+    const loaded = await loadLexiconFromDir(dir);
+    expect(loaded.error).toBeUndefined();
+    expect(loaded.plugin?.name).toBe("mock");
+  });
+
+  test("reports a directory with no importable entry rather than throwing", async () => {
+    const loaded = await loadLexiconFromDir(lexiconDir({ "README.md": "" }));
+    expect(loaded.plugin).toBeUndefined();
+    expect(loaded.error).toContain("no importable entry point");
+  });
+
+  test("reports a module that exports no plugin", async () => {
+    const dir = lexiconDir({ "src/index.ts": "export const notAPlugin = { name: 'x' };" });
+    const loaded = await loadLexiconFromDir(dir);
+    expect(loaded.plugin).toBeUndefined();
+    expect(loaded.error).toBe("the module exports no LexiconPlugin");
+  });
+
+  test("reports an import failure as a finding, not a crash", async () => {
+    const dir = lexiconDir({ "src/index.ts": "this is not valid typescript ((((" });
+    const loaded = await loadLexiconFromDir(dir);
+    expect(loaded.plugin).toBeUndefined();
+    expect(loaded.error).toContain("import failed");
+  });
+
+  test("a plugin missing a required lifecycle method is not a LexiconPlugin", async () => {
+    const dir = lexiconDir({
+      "src/index.ts": `
+        export const plugin = {
+          name: "half",
+          serializer: { name: "half", serialize: () => "" },
+          generate: async () => {},
+        };
+      `,
+    });
+    expect((await loadLexiconFromDir(dir)).error).toBe("the module exports no LexiconPlugin");
+  });
+});
+
+describe("registers", () => {
+  const plugin = { name: "x", hoverProvider: () => undefined } as unknown as LexiconPlugin;
+
+  test("true for a function member", () => {
+    expect(registers(plugin, "hoverProvider")).toBe(true);
+  });
+
+  test("false for an absent member — the helm case", () => {
+    expect(registers(plugin, "completionProvider")).toBe(false);
+  });
+
+  test("false when there is no plugin at all", () => {
+    expect(registers(undefined, "hoverProvider")).toBe(false);
+  });
+});
+
+describe("safeList", () => {
+  test("returns the list", () => {
+    expect(safeList(() => [1, 2])).toEqual({ items: [1, 2] });
+  });
+
+  test("an absent member is an empty list, not an error", () => {
+    expect(safeList<number>(undefined)).toEqual({ items: [] });
+  });
+
+  test("a member that throws is reported rather than aborting the run", () => {
+    const result = safeList<number>(() => {
+      throw new Error("no rules directory");
+    });
+    expect(result.items).toEqual([]);
+    expect(result.error).toBe("no rules directory");
+  });
+
+  test("a member returning undefined is an empty list", () => {
+    expect(safeList(() => undefined as unknown as number[])).toEqual({ items: [] });
+  });
+});