@intentius/chant-lexicon-cedar 0.44.8

package/src/lsp/completions.ts

@@ -0,0 +1,55 @@
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
+import { cedarIndex, cedarRegistry } from "./registry";
+
+/**
+ * Completions over the schema-derived registry.
+ *
+ * Two shapes come out of core's generic provider: class names after `new `,
+ * and property names inside a constructor's object literal. Both are useful
+ * here — `new Policy({` completes `effect`/`principal`/`action`/…, and
+ * `new Doc` completes `Document`.
+ *
+ * The third shape is Cedar's own: a scope names an *action constant*, not a
+ * class, and those are plain `const` exports rather than constructors, so no
+ * `new ` ever precedes them. {@link actionCompletions} covers that position.
+ */
+export function completions(ctx: CompletionContext): CompletionItem[] {
+  const generic = lexiconCompletions(ctx, cedarIndex(), "Cedar declaration");
+  if (generic.length > 0) return generic;
+  return actionCompletions(ctx);
+}
+
+/**
+ * Action constants in a scope position.
+ *
+ * `action: { eq: <cursor> }` and `action: { in: [<cursor>` are where an action
+ * is named, and the generated constants (`ReadAction`, `WriteAction`, …) are
+ * the only correct values. Matching on the surrounding text rather than on a
+ * parsed AST keeps this cheap and is what the other lexicons' providers do.
+ */
+export function actionCompletions(ctx: CompletionContext): CompletionItem[] {
+  const linePrefix = ctx.linePrefix ?? "";
+  if (!/\baction\s*:\s*\{\s*(eq|in)\s*:\s*\[?\s*[A-Za-z]*$/.test(linePrefix)) return [];
+
+  const prefix = (ctx.wordAtCursor ?? "").toLowerCase();
+  const registry = cedarRegistry();
+
+  return Object.entries(registry)
+    .filter(([, entry]) => entry.kind === "resource" && entry.resourceType.includes("::Action::"))
+    .filter(([className]) => !prefix || className.toLowerCase().startsWith(prefix))
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([className, entry]) => ({
+      label: className,
+      insertText: className,
+      kind: "resource" as const,
+      detail: entry.resourceType,
+      documentation: [
+        `Cedar action: \`${entry.resourceType}\``,
+        entry.principalTypes?.length ? `Principals: ${entry.principalTypes.join(", ")}` : "",
+        entry.resourceTypes?.length ? `Resources: ${entry.resourceTypes.join(", ")}` : "",
+      ]
+        .filter(Boolean)
+        .join("\n"),
+    }));
+}

package/src/lsp/hover.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "vitest";
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import type { HoverContext } from "@intentius/chant/lsp/types";
+import { hover } from "./hover";
+
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const lexiconPath = join(pkgDir, "src", "generated", "lexicon-cedar.json");
+const hasGenerated =
+  existsSync(lexiconPath) &&
+  (() => {
+    try {
+      return Object.keys(JSON.parse(readFileSync(lexiconPath, "utf-8"))).length > 0;
+    } catch {
+      return false;
+    }
+  })();
+
+function ctx(word: string): HoverContext {
+  return {
+    uri: "file:///policies.ts",
+    content: "",
+    position: { line: 0, character: 0 },
+    word,
+    lineText: "",
+  };
+}
+
+describe("cedar hover", () => {
+  test("returns undefined for a word the registry does not know", () => {
+    expect(hover(ctx("NotACedarThing"))).toBeUndefined();
+    expect(hover(ctx(""))).toBeUndefined();
+  });
+
+  test.skipIf(!hasGenerated)("describes Policy with its prop table", () => {
+    const info = hover(ctx("Policy"));
+
+    expect(info?.contents).toContain("**Policy**");
+    expect(info?.contents).toContain("Cedar::Policy");
+    expect(info?.contents).toContain("`effect`");
+    expect(info?.contents).toContain("permit");
+  });
+
+  test.skipIf(!hasGenerated)("describes an entity type with its attributes", () => {
+    const info = hover(ctx("Document"));
+
+    expect(info?.contents).toContain("App::Document");
+    expect(info?.contents).toContain("**Attributes:**");
+    expect(info?.contents).toContain("classification");
+  });
+
+  test.skipIf(!hasGenerated)("marks an optional attribute", () => {
+    const info = hover(ctx("User"));
+
+    // `manager` is declared `"manager"?: User` in the default schema.
+    expect(info?.contents).toContain("`manager`? —");
+    expect(info?.contents).toContain("`email` —");
+  });
+
+  test.skipIf(!hasGenerated)("reports what an entity type is a member of", () => {
+    expect(hover(ctx("Team"))?.contents).toContain("**Member of:** `App::Group`");
+  });
+
+  test.skipIf(!hasGenerated)("describes an action's principals, resources and context", () => {
+    const info = hover(ctx("ReadAction"));
+
+    expect(info?.contents).toContain('App::Action::"read"');
+    expect(info?.contents).toContain("**Principals:**");
+    expect(info?.contents).toContain("App::ServiceAccount");
+    expect(info?.contents).toContain("**Resources:**");
+    expect(info?.contents).toContain("**Context:**");
+    expect(info?.contents).toContain("mfa");
+  });
+
+  test.skipIf(!hasGenerated)("describes a record property type as fields", () => {
+    const info = hover(ctx("DocumentAttributes"));
+
+    expect(info?.contents).toContain("App::Document.Attributes");
+    expect(info?.contents).toContain("**Fields:**");
+  });
+});

package/src/lsp/hover.ts

@@ -0,0 +1,75 @@
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+import { cedarIndex, cedarRegistry } from "./registry";
+
+/**
+ * Hover over a generated declaration.
+ *
+ * Core's default formatter reports CloudFormation-shaped facts (primary
+ * identifier, create-only, write-only) a Cedar declaration does not have. The
+ * facts that matter here are the Cedar ones: what a `Policy` prop means, which
+ * groups an entity type is `in`, and what an action applies to.
+ */
+export function hover(ctx: HoverContext): HoverInfo | undefined {
+  return lexiconHover(ctx, cedarIndex(), formatCedarHover);
+}
+
+function formatCedarHover(className: string, indexed: LexiconEntry): HoverInfo | undefined {
+  const entry = cedarRegistry()[className];
+  if (!entry) return undefined;
+
+  const lines = [`**${className}**`, "", `Cedar type: \`${entry.resourceType}\``];
+
+  if (entry.description) {
+    lines.push("", entry.description);
+  }
+
+  if (entry.resourceType === "Cedar::Policy") {
+    lines.push(
+      "",
+      "The unit this lexicon serializes — one `.cedar` policy plus its entry in the JSON policy set.",
+      "",
+      "| Prop | Meaning |",
+      "|------|---------|",
+      "| `effect` | `permit` or `forbid`; defaults to `permit` |",
+      "| `principal`, `action`, `resource` | scope constraints — `{}`, `{ eq }`, `{ in }`, `{ is }` |",
+      "| `when`, `unless` | Cedar expression strings, one clause each |",
+      "| `annotations` | emitted as `@key(\"value\")` above the policy |",
+    );
+    return { contents: lines.join("\n") };
+  }
+
+  if (entry.resourceType.includes("::Action::")) {
+    if (entry.principalTypes?.length) {
+      lines.push("", `**Principals:** ${entry.principalTypes.map((t) => `\`${t}\``).join(", ")}`);
+    }
+    if (entry.resourceTypes?.length) {
+      lines.push("", `**Resources:** ${entry.resourceTypes.map((t) => `\`${t}\``).join(", ")}`);
+    }
+    const context = Object.entries(entry.properties ?? {});
+    if (context.length > 0) {
+      lines.push("", "**Context:**");
+      for (const [name, spec] of context) {
+        lines.push(`- \`${name}\`${spec.required ? "" : "?"} — \`${spec.type}\``);
+      }
+    }
+    return { contents: lines.join("\n") };
+  }
+
+  if (entry.memberOfTypes?.length) {
+    lines.push("", `**Member of:** ${entry.memberOfTypes.map((t) => `\`${t}\``).join(", ")}`);
+  }
+  if (entry.enumValues?.length) {
+    lines.push("", `**Enum values:** ${entry.enumValues.map((v) => `\`${v}\``).join(", ")}`);
+  }
+
+  const attributes = Object.entries(entry.properties ?? {});
+  if (attributes.length > 0) {
+    lines.push("", indexed.kind === "property" ? "**Fields:**" : "**Attributes:**");
+    for (const [name, spec] of attributes) {
+      lines.push(`- \`${name}\`${spec.required ? "" : "?"} — \`${spec.type}\``);
+    }
+  }
+
+  return { contents: lines.join("\n") };
+}

package/src/lsp/registry.ts

@@ -0,0 +1,74 @@
+/**
+ * The generated registry, adapted to what core's `LexiconIndex` reads.
+ *
+ * `lexicon-cedar.json` describes every declaration the project's schema
+ * produced (#1650): the `Policy` authoring class, one entry per entity type,
+ * one per action, and the attribute/context record types beside them. Its
+ * property table is keyed `properties`, while `LexiconIndex.getPropertyNames`
+ * looks at `propertyConstraints` — the CloudFormation-shaped name the class was
+ * written against. Renaming the generated key to match would put a
+ * CloudFormation word in a Cedar artifact; translating here does not, and it is
+ * the only reason this module exists.
+ *
+ * The require is lazy and cached. `generate()` writes the registry, so a
+ * checkout that has not run it yet must still be able to import this file —
+ * the LSP tests skip on exactly that condition.
+ */
+
+import { createRequire } from "module";
+import { LexiconIndex, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+import { LEXICON_JSON_FILENAME } from "../codegen/generate";
+
+const require = createRequire(import.meta.url);
+
+/** One `lexicon-cedar.json` entry, as {@link generateRegistry} writes it. */
+export interface CedarRegistryEntry {
+  resourceType: string;
+  kind: "resource" | "property";
+  lexicon: string;
+  description?: string;
+  /** Cedar namespace the declaration came from, e.g. `App`. */
+  namespace?: string;
+  /** Entity types this one is `in`, for an entity declaration. */
+  memberOfTypes?: string[];
+  /** `appliesTo.principal`, for an action declaration. */
+  principalTypes?: string[];
+  /** `appliesTo.resource`, for an action declaration. */
+  resourceTypes?: string[];
+  enumValues?: string[];
+  properties?: Record<string, { type: string; required: boolean }>;
+}
+
+export type CedarRegistry = Record<string, CedarRegistryEntry>;
+
+let cachedRegistry: CedarRegistry | null = null;
+let cachedIndex: LexiconIndex | null = null;
+
+/** The raw registry, for the hover formatter's Cedar-specific fields. */
+export function cedarRegistry(): CedarRegistry {
+  if (cachedRegistry) return cachedRegistry;
+  cachedRegistry = require(`../generated/${LEXICON_JSON_FILENAME}`) as CedarRegistry;
+  return cachedRegistry;
+}
+
+/** The same registry as a `LexiconIndex`, with the property table translated. */
+export function cedarIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const entries: Record<string, LexiconEntry> = {};
+  for (const [className, entry] of Object.entries(cedarRegistry())) {
+    entries[className] = {
+      resourceType: entry.resourceType,
+      kind: entry.kind,
+      lexicon: entry.lexicon,
+      propertyConstraints: entry.properties ?? {},
+    };
+  }
+  cachedIndex = new LexiconIndex(entries);
+  return cachedIndex;
+}
+
+/** Reset the caches. Tests that swap the registry on disk need this; nothing else does. */
+export function resetCedarIndexCache(): void {
+  cachedRegistry = null;
+  cachedIndex = null;
+}

package/src/mcp/index.ts

@@ -0,0 +1,103 @@
+/**
+ * The cedar lexicon's MCP contributions.
+ *
+ * Two of the three are the conventional pair every lexicon ships, built from
+ * core's shared helpers: `cedar:diff` and `chant://cedar/resource-catalog`.
+ * The third is the one only this lexicon can answer — see
+ * ./policy-coverage.ts.
+ *
+ * Names are written as bare verbs and single-segment URIs. Core namespaces both
+ * (`cedar:<verb>`, `chant://cedar/<path>`), and applying the prefix is
+ * idempotent, so the helpers' pre-namespaced output and the bare `coverage`
+ * below both register as exactly one well-formed identifier (chant #1341).
+ */
+
+import { createDiffTool, createCatalogResource } from "@intentius/chant/lexicon-plugin-helpers";
+import type { McpToolContribution, McpResourceContribution } from "@intentius/chant/mcp/types";
+import { cedarSerializer } from "../serializer";
+import { computePolicyCoverage, formatPolicyCoverage } from "./policy-coverage";
+
+/**
+ * `cedar:coverage` — which schema declarations the built policy set reaches.
+ *
+ * Builds the project the same way `chant build` does rather than reading a
+ * committed `.cedar` file, so the answer is about the policies in source, not
+ * about whatever was last written to disk.
+ */
+export const cedarCoverageTool: McpToolContribution = {
+  name: "coverage",
+  description:
+    "Report which Cedar schema entity types and actions the project's policy set can apply to, " +
+    "which are reachable only from a forbid, and which no policy covers at all.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      path: {
+        type: "string",
+        description: "Path to the infrastructure project directory (defaults to the current directory)",
+      },
+      format: {
+        type: "string",
+        enum: ["json", "text"],
+        description: "Return the full report as JSON (default) or a human-readable summary",
+      },
+    },
+  },
+  async handler(params: Record<string, unknown>): Promise<unknown> {
+    const { join } = await import("path");
+    const { existsSync } = await import("fs");
+    const { build } = await import("@intentius/chant/build");
+    const { loadCedarConfig } = await import("../config");
+
+    const projectRoot = (params.path as string) ?? ".";
+    const srcDir = existsSync(join(projectRoot, "src")) ? join(projectRoot, "src") : projectRoot;
+
+    const result = await build(srcDir, [cedarSerializer]);
+    if (result.errors.length > 0) {
+      return { error: "build failed", details: result.errors.map((e) => String(e)) };
+    }
+
+    const output = result.outputs.get("cedar");
+    const policySetText = typeof output === "string" ? output : (output?.primary ?? "");
+
+    const report = computePolicyCoverage({
+      policySetText,
+      projectRoot,
+      config: await loadCedarConfig(projectRoot),
+    });
+
+    return params.format === "text" ? formatPolicyCoverage(report) : report;
+  },
+};
+
+/** Every MCP tool this lexicon contributes. */
+export function cedarMcpTools(): McpToolContribution[] {
+  return [
+    createDiffTool(
+      cedarSerializer,
+      "Compare the current Cedar policy set against the previous build's output",
+      "cedar",
+    ),
+    cedarCoverageTool,
+  ];
+}
+
+/**
+ * Every MCP resource this lexicon contributes.
+ *
+ * `createCatalogResource` locates the registry relative to the module URL it is
+ * given, resolving `<dir>/generated/lexicon-cedar.json`. That has to be
+ * `src/`, not `src/mcp/`, so the caller in plugin.ts passes its own
+ * `import.meta.url` rather than this file deriving one by walking up.
+ */
+export function cedarMcpResources(pluginUrl: string): McpResourceContribution[] {
+  return [
+    createCatalogResource(
+      pluginUrl,
+      "Cedar Resource Catalog",
+      "Every declaration generated from the project's Cedar schema — entity types, actions, and the Policy class",
+      "lexicon-cedar.json",
+      "cedar",
+    ),
+  ];
+}

package/src/mcp/policy-coverage.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, it } from "vitest";
+import { computePolicyCoverage, formatPolicyCoverage } from "./policy-coverage";
+import { cedarMcpResources, cedarMcpTools } from "./index";
+import { mcpNameViolations } from "@intentius/chant/cli/commands/check-lexicon-mcp";
+
+// No projectRoot and no config, so every call resolves the bundled default
+// schema — the same one the examples build against.
+const against = (policySetText: string) => computePolicyCoverage({ policySetText, projectRoot: "/nonexistent" });
+
+const ownerRead = `@id("owner-read")
+permit (
+  principal is App::User,
+  action == App::Action::"read",
+  resource is App::Document
+)
+when { resource.owner == principal };`;
+
+const secretFloor = `@id("secret-floor")
+forbid (
+  principal,
+  action,
+  resource is App::Folder
+)
+when { resource.name == "secrets" };`;
+
+describe("computePolicyCoverage", () => {
+  it("reports nothing covered for an empty policy set", () => {
+    const report = against("");
+
+    expect(report.policyCount).toBe(0);
+    expect(report.entityTypesCovered).toBe(0);
+    expect(report.actionsCovered).toBe(0);
+    expect(report.uncovered).toContain("App::Document");
+    expect(report.uncovered).toContain('App::Action::"read"');
+  });
+
+  it("counts the declarations one policy can apply to", () => {
+    const report = against(ownerRead);
+
+    expect(report.policyCount).toBe(1);
+    const document = report.items.find((i) => i.name === "App::Document");
+    expect(document?.policies).toBe(1);
+    expect(document?.policyIds).toEqual(["owner-read"]);
+    expect(document?.permitted).toBe(true);
+    expect(document?.forbidden).toBe(false);
+
+    // `read` also applies to Folder in the schema, but this policy's resource
+    // scope excludes it — the resolver, not the scope text, is what decides.
+    expect(report.items.find((i) => i.name === "App::Folder")?.policies).toBe(0);
+  });
+
+  it("resolves an action group rather than reading the scope literally", () => {
+    const report = against(ownerRead);
+
+    expect(report.items.find((i) => i.name === 'App::Action::"read"')?.policies).toBe(1);
+    expect(report.items.find((i) => i.name === 'App::Action::"write"')?.policies).toBe(0);
+  });
+
+  it("flags a declaration reachable only from a forbid", () => {
+    const report = against(secretFloor);
+
+    expect(report.forbidOnly).toContain("App::Folder");
+    expect(report.items.find((i) => i.name === "App::Folder")?.forbidden).toBe(true);
+    expect(report.uncovered).not.toContain("App::Folder");
+  });
+
+  it("stops flagging it once a permit reaches it too", () => {
+    const report = against(`${ownerRead}\n\n${secretFloor}`);
+
+    expect(report.policyCount).toBe(2);
+    expect(report.forbidOnly).toContain("App::Folder");
+    expect(report.forbidOnly).not.toContain("App::Document");
+  });
+
+  it("names a bare permit as covering every action and every reachable entity type", () => {
+    const report = against("permit (principal, action, resource);");
+
+    expect(report.actionsCovered).toBe(report.actions);
+
+    // Group and Team appear in no action's `appliesTo` — they exist only as
+    // containers to be `in`. Not even `permit (principal, action, resource)`
+    // reaches them, which is the resolver telling the truth: no request can
+    // ever name them as a principal or a resource. Reporting them as covered
+    // would be the more comfortable answer and the wrong one.
+    expect(report.uncovered).toEqual(["App::Group", "App::Team"]);
+    expect(report.entityTypesCovered).toBe(report.entityTypes - 2);
+  });
+
+  it("reads the effect from Cedar's parse, not from the surrounding text", () => {
+    // A permit whose annotation contains the word `forbid` at the start of a
+    // line, and a policy id containing an escaped quote. Both defeated the
+    // text-scanning version of this.
+    const report = against(`@id("say \\"forbid\\" here")
+@note("
+forbid (this is prose)")
+permit (
+  principal is App::User,
+  action == App::Action::"read",
+  resource is App::Document
+);`);
+
+    const document = report.items.find((i) => i.name === "App::Document");
+    expect(document?.permitted).toBe(true);
+    expect(document?.forbidden).toBe(false);
+    expect(document?.policyIds).toEqual(['say "forbid" here']);
+    expect(report.forbidOnly).not.toContain("App::Document");
+  });
+
+  it("falls back to a positional id when a policy carries no @id", () => {
+    const report = against("permit (principal, action, resource);");
+
+    expect(report.items.find((i) => i.name === "App::Document")?.policyIds).toEqual(["policy-1"]);
+  });
+
+  it("distinguishes a policy set that will not parse from one with no policies", () => {
+    const report = against("permit (principal, action");
+
+    expect(report.parseErrors.length).toBeGreaterThan(0);
+    expect(report.policyCount).toBe(0);
+    // Same counts as an empty set — the parseErrors field is the only thing
+    // that tells the two apart, which is why it exists.
+    expect(report.uncovered).toContain("App::Document");
+  });
+
+  it("names a policy that can never fire", () => {
+    // App::Ghost parses — it is a syntactically valid entity type — and the
+    // resolver answers "success, nothing" rather than failing. A permit no
+    // request can ever match is almost always a typo'd entity type, so the
+    // empty envelope is reported rather than swallowed.
+    const report = against(`@id("ghost")
+permit (
+  principal,
+  action,
+  resource is App::Ghost
+);`);
+
+    expect(report.inert).toEqual(["ghost"]);
+    expect(report.unresolved).toEqual([]);
+    expect(report.uncovered).toContain("App::Document");
+    expect(formatPolicyCoverage(report)).toContain("Never fires:  ghost");
+  });
+});
+
+describe("formatPolicyCoverage", () => {
+  it("summarises counts, uncovered declarations and forbid-only ones", () => {
+    const text = formatPolicyCoverage(against(`${ownerRead}\n\n${secretFloor}`));
+
+    expect(text).toContain("2 policy/policies");
+    expect(text).toContain("Entity types:");
+    expect(text).toContain("Uncovered:");
+    expect(text).toMatch(/Forbid only:.*App::Folder/);
+  });
+});
+
+describe("MCP contributions", () => {
+  it("registers three contributions under one well-formed cedar namespace", () => {
+    const tools = cedarMcpTools();
+    const resources = cedarMcpResources(import.meta.url);
+
+    expect(tools).toHaveLength(2);
+    expect(resources).toHaveLength(1);
+    expect(mcpNameViolations("cedar", tools, resources)).toEqual([]);
+  });
+
+  it("ships the conventional diff tool and catalog resource beside the cedar-specific one", () => {
+    expect(cedarMcpTools().map((t) => t.name)).toEqual(["cedar:diff", "coverage"]);
+    expect(cedarMcpResources(import.meta.url).map((r) => r.uri)).toEqual(["cedar:resource-catalog"]);
+  });
+
+  it("declares an input schema the agent can fill in", () => {
+    const coverage = cedarMcpTools().find((t) => t.name === "coverage");
+
+    expect(coverage?.inputSchema.properties).toHaveProperty("path");
+    expect(coverage?.inputSchema.properties).toHaveProperty("format");
+  });
+});