@intentius/chant 0.37.2 → 0.39.0

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: [] });
+  });
+});

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

@@ -0,0 +1,115 @@
+/**
+ * Loading a lexicon's plugin so completeness checks can look at what it
+ * actually registers (#1342).
+ *
+ * `check-lexicon`'s checks were almost all existence assertions over the
+ * directory: `src/lsp/completions.ts exists`, `At least 1 lint rule in
+ * src/lint/rules/`. A file with the right name is not the contract — the
+ * contract is the member the plugin exposes, because that is what core
+ * dispatches through. helm is the proof: it ships `src/lsp/completions.ts` and
+ * `src/lsp/hover.ts`, both with passing tests, exports `helmCompletions` and
+ * `helmHover` from its index, and never sets `completionProvider` or
+ * `hoverProvider` on the plugin. `cli/lsp/server.ts` dispatches through exactly
+ * those fields, so helm's LSP support is unreachable in an editor — while tier 1
+ * (the files) and tier 2 (the tests) both passed.
+ *
+ * Resolution is directory-local rather than by package name: `chant dev
+ * check-lexicon <dir>` should work on a lexicon that is not installed, and
+ * `loadPlugin` in ../plugins.ts imports `@intentius/chant-lexicon-<name>`,
+ * which requires it to be.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { isAbsolute, join, resolve } from "path";
+import { pathToFileURL } from "url";
+import { isLexiconPlugin, type LexiconPlugin } from "../../lexicon";
+
+export interface LoadedLexicon {
+  /** The plugin, when the package exported one. */
+  plugin?: LexiconPlugin;
+  /** Why loading failed, for a check's `detail`. */
+  error?: string;
+  /** The entry point that was imported, for diagnostics. */
+  entry?: string;
+}
+
+/**
+ * The module a lexicon package presents to consumers.
+ *
+ * Tier 1 requires `exports["."].default` to be `./src/index.ts`, so that is the
+ * first choice — it is the module core itself imports. The fallbacks keep this
+ * usable on a lexicon that has not reached that check yet.
+ */
+export function pluginEntryFor(dir: string): string | undefined {
+  const candidates: string[] = [];
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as {
+      exports?: { "."?: { default?: string } };
+      main?: string;
+    };
+    for (const declared of [pkg.exports?.["."]?.default, pkg.main]) {
+      if (typeof declared === "string") candidates.push(declared);
+    }
+  } catch {
+    // no package.json, or unreadable — fall through to the conventional paths
+  }
+  candidates.push("./src/index.ts", "./src/plugin.ts");
+
+  for (const candidate of candidates) {
+    const path = isAbsolute(candidate) ? candidate : resolve(dir, candidate);
+    if (existsSync(path)) return path;
+  }
+  return undefined;
+}
+
+/**
+ * Import a lexicon directory and return the `LexiconPlugin` it exports.
+ *
+ * Never throws: a lexicon that cannot be loaded is a finding, not a crash, and
+ * every caller reports it as a failed check rather than aborting the run.
+ */
+export async function loadLexiconFromDir(dir: string): Promise<LoadedLexicon> {
+  const entry = pluginEntryFor(dir);
+  if (!entry) {
+    return { error: "no importable entry point (looked for package.json exports, src/index.ts, src/plugin.ts)" };
+  }
+
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(pathToFileURL(entry).href)) as Record<string, unknown>;
+  } catch (error) {
+    return { entry, error: `import failed: ${error instanceof Error ? error.message : String(error)}` };
+  }
+
+  for (const value of Object.values(mod)) {
+    if (isLexiconPlugin(value)) return { plugin: value, entry };
+  }
+  // A default export whose own members are the plugin (some lexicons re-export
+  // a namespace rather than the object itself).
+  const fallback = (mod.default ?? {}) as Record<string, unknown>;
+  for (const value of Object.values(fallback)) {
+    if (isLexiconPlugin(value)) return { plugin: value, entry };
+  }
+
+  return { entry, error: "the module exports no LexiconPlugin" };
+}
+
+/** Whether the plugin exposes a callable member under `name`. */
+export function registers(plugin: LexiconPlugin | undefined, name: keyof LexiconPlugin): boolean {
+  return typeof plugin?.[name] === "function";
+}
+
+/**
+ * Call a plugin member that returns a list, treating a throw as an empty list.
+ *
+ * A member that throws is not a registration — it is worse than an absent one,
+ * and the check that counts its results should fail rather than the whole run.
+ */
+export function safeList<T>(fn: (() => T[]) | undefined): { items: T[]; error?: string } {
+  if (typeof fn !== "function") return { items: [] };
+  try {
+    return { items: fn() ?? [] };
+  } catch (error) {
+    return { items: [], error: error instanceof Error ? error.message : String(error) };
+  }
+}

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

@@ -3,6 +3,9 @@ import { join, basename } from "path";
 import { auditIntrinsics } from "./check-lexicon-intrinsics";
 import { checkExamplesBuild } from "./check-lexicon-examples";
 import { auditDocsReachability } from "./check-lexicon-docs";
+import { auditMcpNames, lexiconNameFor } from "./check-lexicon-mcp";
+import { loadLexiconFromDir, registers, safeList } from "./check-lexicon-plugin";
+import { RULE_CATALOG } from "../../audit/catalog";
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -73,45 +76,100 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
 
   // ── Tier 1: Required ───────────────────────────────────────────
 
+  // #1342 — a capability is present when the plugin exposes it, not when a file
+  // with the right name sits on disk. The checks below used to be existence
+  // assertions, which is how helm shipped `src/lsp/completions.ts` and
+  // `src/lsp/hover.ts` (with tests) while registering neither provider, and
+  // passed every tier. `cli/lsp/server.ts` dispatches through the plugin
+  // members, so those files were unreachable in an editor.
+  const loaded = await loadLexiconFromDir(dir);
+  const plugin = loaded.plugin;
+
+  items.push({
+    name: "The package exports a LexiconPlugin",
+    tier: 1,
+    pass: plugin !== undefined,
+    detail: loaded.error ?? (loaded.entry ? `exported by ${basename(loaded.entry)}` : undefined),
+  });
+
+  const serializer = plugin?.serializer as { name?: unknown; rulePrefix?: unknown; serialize?: unknown } | undefined;
+  const serializerOk =
+    typeof serializer?.name === "string" &&
+    typeof serializer?.rulePrefix === "string" &&
+    typeof serializer?.serialize === "function";
   items.push({
-    name: "src/plugin.ts exists",
+    name: "The plugin exposes a Serializer with a name and rule prefix",
     tier: 1,
-    pass: existsSync(join(dir, "src/plugin.ts")),
+    pass: serializerOk,
+    detail: serializerOk
+      ? `${String(serializer?.name)} (${String(serializer?.rulePrefix)})`
+      : plugin
+        ? "serializer is missing name, rulePrefix, or serialize"
+        : undefined,
   });
 
+  const lintRules = safeList(plugin?.lintRules?.bind(plugin));
   items.push({
-    name: "src/serializer.ts exists",
+    name: "lintRules() returns at least 1 rule",
     tier: 1,
-    pass: existsSync(join(dir, "src/serializer.ts")),
+    pass: lintRules.items.length > 0,
+    detail: lintRules.error ? `threw: ${lintRules.error}` : `${lintRules.items.length} rule(s)`,
   });
 
-  const ruleFiles = listTsFiles(join(dir, "src/lint/rules"), ["index.ts"]);
+  const postSynthChecks = safeList(plugin?.postSynthChecks?.bind(plugin));
   items.push({
-    name: "At least 1 lint rule in src/lint/rules/",
+    name: "postSynthChecks() returns at least 1 check",
     tier: 1,
-    pass: ruleFiles.length > 0,
-    detail: ruleFiles.length > 0 ? `${ruleFiles.length} rule(s)` : undefined,
+    pass: postSynthChecks.items.length > 0,
+    detail: postSynthChecks.error
+      ? `threw: ${postSynthChecks.error}`
+      : `${postSynthChecks.items.length} check(s)`,
+  });
+
+  // #1349 — `rulePrefix` exists so ids do not collide when several lexicons are
+  // loaded together (forgejo wraps github's rules as `WFJ-GHA0xx` for exactly
+  // that reason), and it was checked by nothing. k8s shipped five `ARGO0xx`
+  // checks outside its declared `WK8`. Core's cross-cutting ids are exempt:
+  // they belong to core, not to whichever lexicon surfaces them.
+  const declaredPrefixes = [
+    typeof serializer?.rulePrefix === "string" ? serializer.rulePrefix : "",
+    ...((plugin?.serializer as { extraRulePrefixes?: readonly string[] } | undefined)?.extraRulePrefixes ?? []),
+  ].filter((p) => p.length > 0);
+  const allRuleIds = [
+    ...lintRules.items.map((r) => (r as { id?: string }).id),
+    ...postSynthChecks.items.map((c) => (c as { id?: string }).id),
+  ].filter((id): id is string => typeof id === "string");
+  const offPrefix = allRuleIds.filter(
+    (id) => !(id in RULE_CATALOG) && !declaredPrefixes.some((p) => id.startsWith(p)),
+  );
+  items.push({
+    name: "Every rule id starts with a declared rule prefix",
+    tier: 1,
+    pass: declaredPrefixes.length > 0 && offPrefix.length === 0,
+    detail:
+      offPrefix.length > 0
+        ? `${offPrefix.length} outside ${declaredPrefixes.join("/")}: ${[...new Set(offPrefix)].slice(0, 6).join(", ")}`
+        : declaredPrefixes.length > 0
+          ? `${allRuleIds.length} id(s) under ${declaredPrefixes.join("/")}`
+          : "no rule prefix declared",
   });
 
-  const postSynthFiles = listTsFiles(join(dir, "src/lint/post-synth"), ["index.ts"])
-    .filter((f) => !f.endsWith("-helpers.ts") && f !== "helpers.ts");
   items.push({
-    name: "At least 1 post-synth check",
+    name: "The plugin registers completionProvider",
     tier: 1,
-    pass: postSynthFiles.length > 0,
-    detail: postSynthFiles.length > 0 ? `${postSynthFiles.length} check(s)` : undefined,
+    pass: registers(plugin, "completionProvider"),
   });
 
   items.push({
-    name: "src/lsp/completions.ts exists",
+    name: "The plugin registers hoverProvider",
     tier: 1,
-    pass: existsSync(join(dir, "src/lsp/completions.ts")),
+    pass: registers(plugin, "hoverProvider"),
   });
 
   items.push({
-    name: "src/lsp/hover.ts exists",
+    name: "The plugin registers docs()",
     tier: 1,
-    pass: existsSync(join(dir, "src/lsp/hover.ts")),
+    pass: registers(plugin, "docs"),
   });
 
   items.push({
@@ -262,6 +320,24 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
           : undefined,
   });
 
+  // #1341 — core namespaces MCP contributions, and so do the shared helpers and
+  // most lexicons, so the names agents actually saw were `gitlab:gitlab:diff`
+  // and `chant://azure/chant://lexicon/azure/catalog`. The check is on the
+  // registered name rather than the declared one: three authored forms are in
+  // use and all of them are fine, but only one registered shape is.
+  const mcpNames = await auditMcpNames(dir);
+  items.push({
+    name: "MCP tools and resources register under one well-formed namespace",
+    tier: 1,
+    pass: mcpNames.violations.length === 0,
+    detail:
+      mcpNames.violations.length > 0
+        ? mcpNames.violations.join(" | ")
+        : mcpNames.loaded
+          ? `${mcpNames.checked} contribution(s) checked`
+          : "lexicon could not be loaded — not checked",
+  });
+
   const hasPluginTest = findFiles(join(dir, "src"), (n) => n === "plugin.test.ts").length > 0;
   items.push({
     name: "plugin.test.ts exists",
@@ -302,21 +378,95 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
 
   const pluginContent = readOr(join(dir, "src/plugin.ts"));
 
+  // #1342 — these were a regex over plugin.ts source text, which passed on a
+  // method declared in a form the regex happened to match and on one that
+  // throws when called. Ask the plugin instead.
   for (const method of ["mcpTools", "mcpResources", "skills", "detectTemplate", "initTemplates"] as const) {
-    // Check for uncommented method: line starts with optional whitespace, then the method name
-    // Exclude lines that start with // or * (comment blocks)
-    const lines = pluginContent.split("\n");
-    const hasUncommented = lines.some((line) => {
-      const trimmed = line.trim();
-      return trimmed.startsWith(`${method}(`) || trimmed.startsWith(`${method} (`);
-    });
     items.push({
-      name: `plugin.ts has uncommented ${method}`,
+      name: `The plugin registers ${method}`,
       tier: 2,
-      pass: hasUncommented,
+      pass: registers(plugin, method),
     });
   }
 
+  // #1346 — `resolveAuditCatalog` contributes nothing for a lexicon that omits
+  // the method, silently, so its checks surface in `chant audit` with no title,
+  // tier, fix kind, or category. Tier 2 rather than tier 1: the lexicon builds
+  // and lints correctly without it; what suffers is one command's output.
+  const auditCatalog = (() => {
+    try {
+      return plugin?.auditCatalog?.() ?? {};
+    } catch {
+      return {};
+    }
+  })();
+  const uncatalogued = postSynthChecks.items
+    .map((c) => (c as { id?: string }).id)
+    .filter((id): id is string => typeof id === "string" && !(id in auditCatalog) && !(id in RULE_CATALOG));
+  items.push({
+    name: "auditCatalog() covers every post-synth check",
+    tier: 2,
+    pass: uncatalogued.length === 0,
+    detail:
+      uncatalogued.length > 0
+        ? `${uncatalogued.length} without metadata: ${uncatalogued.slice(0, 6).join(", ")}`
+        : `${Object.keys(auditCatalog).length} entry/entries`,
+  });
+
+  // #1348 — the marker channel is a claim: declaring `reads: ["exportResources"]`
+  // while not implementing `exportResources` promises a verdict from a path
+  // that does not exist. The behavioral half lives in the observation
+  // conformance suite, which holds a declared path to a real verdict and an
+  // undeclared one to `unknown`; this is the static half.
+  const channel = plugin?.ownershipChannel;
+  const channelProblems: string[] = [];
+  if (channel) {
+    for (const path of channel.reads) {
+      if (!registers(plugin, path as keyof typeof plugin)) {
+        channelProblems.push(`declares a marker channel on ${path}, which the plugin does not implement`);
+      }
+    }
+    const keys = channel.keys as { managedBy?: unknown; stack?: unknown; env?: unknown } | undefined;
+    for (const key of ["managedBy", "stack", "env"] as const) {
+      if (typeof keys?.[key] !== "string" || (keys[key] as string).length === 0) {
+        channelProblems.push(`marker keys are missing ${key}`);
+      }
+    }
+    if (channel.reads.length === 0) {
+      channelProblems.push("declares marker keys but no read path — nothing can resolve a verdict");
+    }
+  }
+  items.push({
+    name: "Any declared ownership channel names paths the plugin implements",
+    tier: 2,
+    pass: channelProblems.length === 0,
+    detail:
+      channelProblems.length > 0
+        ? channelProblems.join("; ")
+        : channel
+          ? `marker on ${channel.reads.join(", ")}`
+          : "no marker channel — every verdict must be unknown",
+  });
+
+  // #1344 — a lexicon that reads its own `chant.config.ts` namespace should
+  // declare its shape, or a typo inside that namespace is accepted and silently
+  // ignored: `forgejo: { runnerLabel: … }` left the dialect on its defaults with
+  // nothing said. Source scan, because the read happens deep in a serializer
+  // rather than anywhere the plugin object can be asked.
+  const lexiconName = lexiconNameFor(dir);
+  const readsOwnNamespace = findFiles(join(dir, "src"), (n) => n.endsWith(".ts") && !n.endsWith(".test.ts"))
+    .some((file) => new RegExp(`config\\s*\\??\\.\\s*${lexiconName}\\b`).test(readOr(file)));
+  items.push({
+    name: "Declares a configSchema if it reads its own config namespace",
+    tier: 2,
+    pass: !readsOwnNamespace || plugin?.configSchema !== undefined,
+    detail: readsOwnNamespace
+      ? plugin?.configSchema
+        ? `config.${lexiconName} is declared and validated`
+        : `reads config.${lexiconName} but declares no schema — unknown keys there are silently ignored`
+      : "reads no config namespace of its own",
+  });
+
   const compositeFiles = listTsFiles(join(dir, "src/composites"), ["index.ts"]);
   items.push({
     name: "At least 1 composite in src/composites/",

package/src/cli/handlers/components.test.ts

@@ -4,6 +4,18 @@ import type { LexiconPlugin, ResourceMetadata } from "../../lexicon";
 import type { BuildResult } from "../../build";
 import type { ParsedArgs } from "../registry";
 
+/**
+ * The aws emulator capability, as the real plugin declares it. `--live`
+ * endpoint injection reads the endpoint var off this rather than off a map
+ * keyed by lexicon name (#1345), so a mock that omits it gets no injection —
+ * the same thing that would happen in production.
+ */
+const awsEmulatorStub = {
+  spec: { name: "chant-floci", image: "floci/floci:1.5.34", containerPort: 4566, healthPath: "/_localstack/health" },
+  env: (endpoint: string) => ({ AWS_ENDPOINT_URL: endpoint, AWS_ACCESS_KEY_ID: "test" }),
+};
+
+
 const getHeadCommitMock = vi.fn();
 const fetchLifecycleMock = vi.fn();
 const pushLifecycleMock = vi.fn();
@@ -256,6 +268,7 @@ describe("components handlers", () => {
       const plugins: LexiconPlugin[] = [
         createMockPlugin({
           name: "aws",
+          emulator: awsEmulatorStub,
           describeResources: staticDescribeResources({ svc: meta() }),
         }),
       ];
@@ -306,6 +319,7 @@ describe("components handlers", () => {
         const plugins: LexiconPlugin[] = [
           createMockPlugin({
             name: "aws",
+            emulator: awsEmulatorStub,
             describeResources: async () => {
               seenDuringDescribe = process.env.AWS_ENDPOINT_URL;
               return { svc: meta() };
@@ -339,6 +353,7 @@ describe("components handlers", () => {
       const plugins: LexiconPlugin[] = [
         createMockPlugin({
           name: "aws",
+          emulator: awsEmulatorStub,
           describeResources: staticDescribeResources({ mystery: meta() }),
         }),
       ];
@@ -391,6 +406,7 @@ describe("components handlers", () => {
       const plugins: LexiconPlugin[] = [
         createMockPlugin({
           name: "aws",
+          emulator: awsEmulatorStub,
           describeResources: staticDescribeResources({ "search-service-v2": meta() }),
         }),
       ];
@@ -434,6 +450,7 @@ describe("components handlers", () => {
       const plugins: LexiconPlugin[] = [
         createMockPlugin({
           name: "aws",
+          emulator: awsEmulatorStub,
           describeResources: staticDescribeResources({ svc: meta() }),
         }),
       ];