@intentius/chant-lexicon-cedar 0.44.8

package/src/lint/post-synth/wasm-helpers.ts

@@ -0,0 +1,315 @@
+/**
+ * The `cedar-wasm` seam for the cedar post-synth checks.
+ *
+ * Cedar's real parser and validator ship as `@cedar-policy/cedar-wasm`, which
+ * runs in-process — no CLI on PATH, no Docker. Everything the checks need from
+ * it goes through this module so the traps live in one place. The traps, all
+ * of them empirically verified against 4.12.0 (chant #1648):
+ *
+ * 1. **`type: "success"` does not mean valid.** `failure` means the *call*
+ *    failed; `success` means validation *ran*, and can carry any number of
+ *    `validationErrors`. {@link validatePolicySet} asserts both.
+ * 2. **`validationErrors` ordering is non-deterministic** — the validator
+ *    parallelizes across policies and never re-sorts. Forty identical calls
+ *    produced six distinct orderings. Everything this module returns is sorted
+ *    by `policyId` then `message`, so a check's output is stable.
+ * 3. **Malformed input throws instead of returning a failure answer.** Missing
+ *    fields on a call struct raise a bare serde `Error` whose `line 1 column N`
+ *    refers to the internal call struct, not to anything the user wrote — it is
+ *    meaningless to surface. {@link call} wraps every entry point and normalizes
+ *    both channels into one result type.
+ * 4. **A bare-string policy set gets synthesized ids** (`policy0`, `policy1`),
+ *    and `@id` annotations do *not* become the policy id. Everything here
+ *    passes `staticPolicies` as a `Record<PolicyId, Policy>` keyed by chant's
+ *    own ids, so a diagnostic names something a reader can find.
+ * 5. **Only `strict` validation mode exists** in this build; any other value
+ *    throws. The settings are left at their default rather than passed.
+ *
+ * Only the `/nodejs` flavor is imported. The root/`esm` flavor imports the
+ * `.wasm` as an ES module, which Bun cannot start (`__wbindgen_start is not a
+ * function`) and Node only supports behind an experimental warning printed on
+ * every run; `/web` needs an explicit `initSync`. `/nodejs` is the one flavor
+ * that loads under `node`, `tsx`, `vitest`, and `bun` alike.
+ *
+ * Excluded from check auto-discovery by the "helper" filename filter.
+ */
+import { createRequire } from "module";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import type * as CedarWasm from "@cedar-policy/cedar-wasm/nodejs";
+import {
+  isRecord,
+  type CedarPolicyJson,
+  type CedarPolicySet,
+  type CedarPolicySetDoc,
+} from "./cedar-helpers";
+
+// ── Loading ───────────────────────────────────────────────────────
+
+type Wasm = typeof CedarWasm;
+
+let cached: Wasm | undefined;
+let loadError: string | undefined;
+
+/**
+ * The wasm module, loaded on first use.
+ *
+ * Lazy and `require`-based on purpose. The post-synth barrel is imported
+ * statically by `plugin.ts`, and every `chant lint`/`chant audit` run loads
+ * every active lexicon's plugin — a top-level import would pull 4 MB of wasm
+ * into any build that merely has cedar installed. `check()` is synchronous, so
+ * `await import()` is not available; `createRequire` is. The `/nodejs` flavor
+ * is CommonJS with a synchronous `readFileSync` init, so there is nothing to
+ * await anyway.
+ */
+export function loadWasm(): Wasm | undefined {
+  if (cached || loadError) return cached;
+  try {
+    const require = createRequire(import.meta.url);
+    cached = require("@cedar-policy/cedar-wasm/nodejs") as Wasm;
+  } catch (err) {
+    loadError = err instanceof Error ? err.message : String(err);
+  }
+  return cached;
+}
+
+/** Why the wasm could not be loaded, if it could not be. */
+export function wasmLoadError(): string | undefined {
+  loadWasm();
+  return loadError;
+}
+
+/** Reset the module cache. Test-only — lets a test exercise the load-failure path. */
+export function resetWasmCache(): void {
+  cached = undefined;
+  loadError = undefined;
+}
+
+// ── Calling ───────────────────────────────────────────────────────
+
+export type WasmResult<T> = { ok: true; value: T } | { ok: false; message: string };
+
+/**
+ * Run a wasm call, turning a thrown serde error into a result rather than an
+ * exception (trap 3 above). The thrown message is deliberately not passed
+ * through verbatim: its positions point into the internal call struct.
+ */
+export function call<T>(what: string, fn: () => T): WasmResult<T> {
+  try {
+    return { ok: true, value: fn() };
+  } catch (err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    // Strip the internal `at line 1 column 42` suffix — it locates a field in
+    // the serialized call struct, never anything in the user's policy.
+    const message = raw.replace(/\s+at line \d+ column \d+\.?$/, "");
+    return { ok: false, message: `${what} could not be run by cedar-wasm: ${message}` };
+  }
+}
+
+/** The first line of a Cedar `DetailedError`, with its `help` when it has one. */
+export function describeError(error: { message: string; help?: string | null }): string {
+  return error.help ? `${error.message} (${error.help})` : error.message;
+}
+
+// ── Condition bodies ──────────────────────────────────────────────
+
+/**
+ * chant's serializer carries a `when`/`unless` body as Cedar expression
+ * *source* under a `__expr` key, because the authored model holds expression
+ * strings until schema-driven codegen (#1650) makes them typed trees. `__expr`
+ * is not part of Cedar's JSON policy grammar — the deserializer rejects it
+ * ("unknown variant `__expr`") — so anything handed to the wasm has to have
+ * those bodies parsed into real expression JSON first.
+ *
+ * There is no expression-level entry point in the package, so the expression
+ * is parsed inside a throwaway policy and the resulting condition body lifted
+ * back out. A source expression that does not parse is the finding CEDC011
+ * reports.
+ */
+export const EXPR_KEY = "__expr";
+
+export interface ExpressionFailure {
+  /** The policy key the clause belongs to. */
+  key: string;
+  /** `when` or `unless`, as the document spelled it. */
+  kind: string;
+  /** The expression source that failed. */
+  expression: string;
+  message: string;
+}
+
+export interface NormalizedPolicySet {
+  /** A policy set the wasm will accept, keyed by chant's own policy ids. */
+  policySet: CedarWasm.PolicySet;
+  /** Condition bodies whose expression source did not parse. */
+  expressionFailures: ExpressionFailure[];
+}
+
+function parseExpression(wasm: Wasm, expression: string): WasmResult<unknown> {
+  const answer = call("condition expression", () =>
+    wasm.policyToJson(`permit(principal, action, resource) when { ${expression} };`),
+  );
+  if (!answer.ok) return answer;
+  if (answer.value.type === "failure") {
+    return { ok: false, message: answer.value.errors.map(describeError).join("; ") };
+  }
+  const conditions = answer.value.json.conditions;
+  const body = Array.isArray(conditions) && isRecord(conditions[0]) ? conditions[0].body : undefined;
+  if (body === undefined) return { ok: false, message: "expression parsed to no condition body" };
+  return { ok: true, value: body };
+}
+
+/** Replace every `__expr` body in a policy set with parsed expression JSON. */
+export function normalizePolicySet(wasm: Wasm, set: CedarPolicySet): NormalizedPolicySet {
+  const staticPolicies: Record<string, unknown> = {};
+  const templates: Record<string, unknown> = {};
+  const expressionFailures: ExpressionFailure[] = [];
+
+  for (const entry of set.entries) {
+    const target = entry.template ? templates : staticPolicies;
+    target[entry.key] = normalizePolicy(wasm, entry.key, entry.policy, expressionFailures);
+  }
+
+  const doc: CedarPolicySetDoc = set.doc ?? {};
+  const policySet = {
+    staticPolicies,
+    templates,
+    templateLinks: Array.isArray(doc.templateLinks) ? doc.templateLinks : [],
+  } as unknown as CedarWasm.PolicySet;
+
+  return { policySet, expressionFailures };
+}
+
+function normalizePolicy(
+  wasm: Wasm,
+  key: string,
+  policy: CedarPolicyJson,
+  failures: ExpressionFailure[],
+): CedarPolicyJson {
+  if (!Array.isArray(policy.conditions)) return policy;
+
+  const conditions = policy.conditions.map((clause) => {
+    if (!isRecord(clause) || !isRecord(clause.body)) return clause;
+    const expression = clause.body[EXPR_KEY];
+    if (typeof expression !== "string") return clause;
+
+    const parsed = parseExpression(wasm, expression);
+    if (!parsed.ok) {
+      failures.push({
+        key,
+        kind: typeof clause.kind === "string" ? clause.kind : "when",
+        expression,
+        message: parsed.message,
+      });
+      // Leave a body the deserializer accepts so the rest of the set still
+      // validates — the unparseable clause is reported by CEDC011, not by a
+      // cascade of confusing structural errors from every other check.
+      return { ...clause, body: { Value: true } };
+    }
+    return { ...clause, body: parsed.value };
+  });
+
+  return { ...policy, conditions };
+}
+
+// ── Schema discovery ──────────────────────────────────────────────
+
+/** A Cedar schema found beside the policies in the build output. */
+export interface DiscoveredSchema {
+  /** Human-readable `.cedarschema` source, or a parsed JSON schema object. */
+  schema: CedarWasm.Schema;
+  /** The filename it came from. */
+  source: string;
+}
+
+/**
+ * The project's Cedar schema, if the build emitted one beside the policies.
+ *
+ * Two forms, both of which the wasm accepts — but only as the right JS type: a
+ * `string` is *always* read as human-readable `.cedarschema`, never as JSON, so
+ * a `.cedarschema.json` file has to be `JSON.parse`d into a live object first
+ * or the parser reports "unexpected token `{`" against perfectly valid JSON.
+ *
+ * Reads `ctx.outputs` only. Nothing emits a schema today — schema-driven
+ * codegen is #1650 — which is exactly why CEDE010 says so out loud instead of
+ * passing silently.
+ */
+export function findSchema(ctx: PostSynthContext): DiscoveredSchema | undefined {
+  for (const [, output] of ctx.outputs) {
+    if (typeof output === "string") continue;
+    for (const [filename, content] of Object.entries(output.files ?? {})) {
+      if (typeof content !== "string") continue;
+      if (filename.endsWith(".cedarschema.json")) {
+        try {
+          const parsed: unknown = JSON.parse(content);
+          if (isRecord(parsed)) return { schema: parsed as CedarWasm.Schema, source: filename };
+        } catch {
+          continue; // a schema that is not JSON is not a schema we can use
+        }
+      } else if (filename.endsWith(".cedarschema")) {
+        return { schema: content, source: filename };
+      }
+    }
+  }
+  return undefined;
+}
+
+// ── Validation ────────────────────────────────────────────────────
+
+/** One validator finding, already flattened and safe to sort. */
+export interface ValidationFinding {
+  policyId: string;
+  message: string;
+}
+
+export interface ValidationOutcome {
+  /** Sorted by `policyId` then `message` — the wasm's own order is not stable. */
+  errors: ValidationFinding[];
+  /** Same sort. */
+  warnings: ValidationFinding[];
+  /** Set when the call itself failed (a parse error, a malformed call struct). */
+  failure?: string;
+}
+
+function sortFindings(findings: ValidationFinding[]): ValidationFinding[] {
+  return [...findings].sort(
+    (a, b) => a.policyId.localeCompare(b.policyId) || a.message.localeCompare(b.message),
+  );
+}
+
+function flatten(errors: CedarWasm.ValidationError[]): ValidationFinding[] {
+  return errors.map((e) => ({ policyId: e.policyId, message: describeError(e.error) }));
+}
+
+/** Validate a normalized policy set against a schema. Never throws. */
+export function validatePolicySet(
+  wasm: Wasm,
+  policySet: CedarWasm.PolicySet,
+  schema: CedarWasm.Schema,
+): ValidationOutcome {
+  const answer = call("validate", () => wasm.validate({ schema, policies: policySet }));
+  if (!answer.ok) return { errors: [], warnings: [], failure: answer.message };
+
+  if (answer.value.type === "failure") {
+    return {
+      errors: [],
+      warnings: [],
+      failure: answer.value.errors.map(describeError).join("; "),
+    };
+  }
+
+  // `success` only means validation RAN. The findings are in the arrays.
+  return {
+    errors: sortFindings(flatten(answer.value.validationErrors)),
+    warnings: sortFindings(flatten(answer.value.validationWarnings)),
+  };
+}
+
+/** Parse-only gate, for when there is no schema to validate against. */
+export function parsePolicySet(wasm: Wasm, policySet: CedarWasm.PolicySet): WasmResult<string[]> {
+  const answer = call("checkParsePolicySet", () => wasm.checkParsePolicySet(policySet));
+  if (!answer.ok) return answer;
+  if (answer.value.type === "failure") {
+    return { ok: true, value: answer.value.errors.map(describeError).sort() };
+  }
+  return { ok: true, value: [] };
+}

package/src/lint/rules/index.ts

@@ -0,0 +1,12 @@
+import type { LintRule } from "@intentius/chant/lint/rule";
+import { cedarPolicyShapeRule } from "./policy-shape";
+
+export { cedarPolicyShapeRule, CEDAR_EFFECTS } from "./policy-shape";
+
+/**
+ * All lint rules provided by this lexicon (imported by plugin.ts's lintRules()).
+ *
+ * Pre-synth rules are wired by hand — unlike post-synth checks, they are not
+ * auto-discovered. Add the import above and the entry below.
+ */
+export const rules: LintRule[] = [cedarPolicyShapeRule];

package/src/lint/rules/policy-shape.test.ts

@@ -0,0 +1,90 @@
+import { describe, test, expect } from "vitest";
+import { createMockLintContext } from "@intentius/chant-test-utils";
+import { cedarPolicyShapeRule } from "./policy-shape";
+import { rules } from ".";
+
+function check(source: string, filePath = "policies.ts") {
+  return cedarPolicyShapeRule.check(createMockLintContext(source, filePath));
+}
+
+const IMPORT = `import { Policy } from "@intentius/chant-lexicon-cedar";\n`;
+
+describe("CEDC001: Cedar policy shape", () => {
+  test("is wired into the lexicon's rule list", () => {
+    expect(rules.map((r) => r.id)).toContain("CEDC001");
+    expect(cedarPolicyShapeRule.severity).toBe("error");
+    expect(cedarPolicyShapeRule.category).toBe("correctness");
+  });
+
+  test('flags effect: "deny" — the word every other policy language uses', () => {
+    const diags = check(`${IMPORT}export const p = new Policy("blockOutsiders", { effect: "deny" });`);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("CEDC001");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain('"deny"');
+    expect(diags[0].line).toBe(2);
+    expect(diags[0].column).toBeGreaterThan(0);
+  });
+
+  test("flags any other non-Cedar effect", () => {
+    const diags = check(`${IMPORT}export const p = new Policy("p", { effect: "Permit" });`);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("Permit");
+  });
+
+  test("flags an empty when entry", () => {
+    const diags = check(`${IMPORT}export const p = new Policy("p", { when: ["", "context.mfa"] });`);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("empty when clause");
+  });
+
+  test("flags a whitespace-only unless entry", () => {
+    const diags = check(`${IMPORT}export const p = new Policy("p", { unless: ["   "] });`);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("empty unless clause");
+  });
+
+  test("flags an empty guard given as a bare string rather than an array", () => {
+    const diags = check(`${IMPORT}export const p = new Policy("p", { when: "" });`);
+    expect(diags).toHaveLength(1);
+  });
+
+  test("reports both problems on one declaration", () => {
+    const diags = check(`${IMPORT}export const p = new Policy("p", { effect: "allow", when: [""] });`);
+    expect(diags).toHaveLength(2);
+  });
+
+  test("works on a factory call as well as a constructor", () => {
+    const source = `import { policy } from "@intentius/chant-lexicon-cedar";\nexport const p = policy({ effect: "deny" });`;
+    expect(check(source)).toHaveLength(1);
+  });
+
+  test("passes a well-formed permit", () => {
+    const source = `${IMPORT}export const p = new Policy("allowAdminRead", {
+      effect: "permit",
+      principal: { in: 'Chant::Group::"admins"' },
+      when: ["context.mfa == true"],
+    });`;
+    expect(check(source)).toHaveLength(0);
+  });
+
+  test("passes a well-formed forbid, and an omitted effect", () => {
+    expect(check(`${IMPORT}export const p = new Policy("p", { effect: "forbid" });`)).toHaveLength(0);
+    expect(check(`${IMPORT}export const p = new Policy("p", { when: ["resource.frozen"] });`)).toHaveLength(0);
+  });
+
+  test("ignores an effect built from anything but a string literal", () => {
+    const source = `${IMPORT}const e = "deny";\nexport const p = new Policy("p", { effect: e });`;
+    expect(check(source)).toHaveLength(0);
+  });
+
+  test("ignores a file that imports nothing from this lexicon", () => {
+    const source = `import { Bucket } from "@intentius/chant-lexicon-aws";\nexport const b = new Bucket("b", { effect: "deny", when: [""] });`;
+    expect(check(source)).toHaveLength(0);
+  });
+
+  test("ignores a call to something not imported from this lexicon", () => {
+    const source = `${IMPORT}export const other = new Something({ effect: "deny" });`;
+    expect(check(source)).toHaveLength(0);
+  });
+});

package/src/lint/rules/policy-shape.ts

@@ -0,0 +1,148 @@
+/**
+ * CEDC001: a Cedar policy declaration must have a usable effect and no empty guard
+ *
+ * Two authoring mistakes that the serializer cannot report and the emitted
+ * artifact hides:
+ *
+ * - **An effect that is not `permit` or `forbid`.** Cedar has exactly two, and
+ *   the serializer coerces anything that is not the literal string `"forbid"`
+ *   into `permit`. So `effect: "deny"` — the word every other policy language
+ *   in the world uses, and the one a reader will reach for — silently emits a
+ *   *grant*. There is no downstream stage that can catch this: by the time the
+ *   policy set exists, the mistake looks like a deliberate permit.
+ * - **An empty `when`/`unless` entry.** `when: ["", "context.mfa"]` emits
+ *   `when {  }`, which is not a Cedar expression; the policy set then fails to
+ *   parse and the error arrives as a byte offset into a generated file. The
+ *   typo is here, in the source, and so is the line number worth printing.
+ *
+ * Source-level because both are visible only before serialization, and both
+ * are about a literal the author typed. A guard built from a variable or a
+ * template expression is out of reach of an AST rule and is left alone —
+ * CEDC011 covers the emitted form.
+ *
+ * Scoped by import: only calls to bindings imported from this lexicon are
+ * considered, so an unrelated `{ effect: "deny" }` in a file that has nothing
+ * to do with Cedar is never flagged.
+ */
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/** Module specifiers whose exports construct Cedar declarables. */
+const CEDAR_MODULE = /chant-lexicon-cedar/;
+
+/** The two effects Cedar has. */
+export const CEDAR_EFFECTS = ["permit", "forbid"] as const;
+
+function importedCedarBindings(sourceFile: ts.SourceFile): Set<string> {
+  const names = new Set<string>();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    if (!CEDAR_MODULE.test(statement.moduleSpecifier.text)) continue;
+
+    const bindings = statement.importClause?.namedBindings;
+    if (bindings && ts.isNamedImports(bindings)) {
+      for (const element of bindings.elements) names.add(element.name.text);
+    }
+    if (statement.importClause?.name) names.add(statement.importClause.name.text);
+  }
+  return names;
+}
+
+/** The callee identifier of a `new X(…)` / `X(…)` expression, if it has one. */
+function calleeName(node: ts.CallExpression | ts.NewExpression): string | undefined {
+  return ts.isIdentifier(node.expression) ? node.expression.text : undefined;
+}
+
+/** The last object-literal argument — where chant resources carry their props. */
+function propsLiteral(node: ts.CallExpression | ts.NewExpression): ts.ObjectLiteralExpression | undefined {
+  const args = [...(node.arguments ?? [])];
+  for (let i = args.length - 1; i >= 0; i--) {
+    const arg = args[i];
+    if (ts.isObjectLiteralExpression(arg)) return arg;
+  }
+  return undefined;
+}
+
+function property(obj: ts.ObjectLiteralExpression, key: string): ts.PropertyAssignment | undefined {
+  for (const prop of obj.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+    if (!ts.isIdentifier(prop.name) && !ts.isStringLiteral(prop.name)) continue;
+    if (prop.name.text === key) return prop;
+  }
+  return undefined;
+}
+
+function lineCol(sourceFile: ts.SourceFile, node: ts.Node): { line: number; column: number } {
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+  return { line: line + 1, column: character + 1 };
+}
+
+export const cedarPolicyShapeRule: LintRule = {
+  id: "CEDC001",
+  severity: "error",
+  category: "correctness",
+  description:
+    "A Cedar policy declaration must use effect permit or forbid, and must not carry an empty when/unless clause",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+    const cedarBindings = importedCedarBindings(sourceFile);
+    if (cedarBindings.size === 0) return diagnostics;
+
+    const report = (node: ts.Node, message: string): void => {
+      const { line, column } = lineCol(sourceFile, node);
+      diagnostics.push({
+        file: sourceFile.fileName,
+        line,
+        column,
+        ruleId: "CEDC001",
+        severity: "error",
+        message,
+      });
+    };
+
+    function inspect(node: ts.CallExpression | ts.NewExpression): void {
+      const callee = calleeName(node);
+      if (!callee || !cedarBindings.has(callee)) return;
+      const props = propsLiteral(node);
+      if (!props) return;
+
+      const effect = property(props, "effect");
+      if (effect && ts.isStringLiteral(effect.initializer)) {
+        const value = effect.initializer.text;
+        if (!(CEDAR_EFFECTS as readonly string[]).includes(value)) {
+          report(
+            effect,
+            `Cedar policy effect "${value}" is not a Cedar effect — the language has only permit and forbid, and anything that is not "forbid" is emitted as a permit. Write effect: "forbid" if that is what was meant.`,
+          );
+        }
+      }
+
+      for (const clause of ["when", "unless"] as const) {
+        const guard = property(props, clause);
+        if (!guard) continue;
+        const entries = ts.isArrayLiteralExpression(guard.initializer)
+          ? guard.initializer.elements
+          : [guard.initializer];
+        for (const entry of entries) {
+          if (!ts.isStringLiteral(entry) && !ts.isNoSubstitutionTemplateLiteral(entry)) continue;
+          if (entry.text.trim() !== "") continue;
+          report(
+            entry,
+            `Cedar policy has an empty ${clause} clause. An empty guard serializes to ${clause} {  }, which is not a Cedar expression and makes the whole policy set unparseable — write the condition, or drop the entry.`,
+          );
+        }
+      }
+    }
+
+    function visit(node: ts.Node): void {
+      if (ts.isCallExpression(node) || ts.isNewExpression(node)) inspect(node);
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/src/lsp/completions.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from "vitest";
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import type { CompletionContext } from "@intentius/chant/lsp/types";
+import { completions } from "./completions";
+
+// The registry is a build artifact of `npm run generate`, and a fresh clone has
+// not run it. Everything below that names a generated class skips when it is
+// absent; the two cases that do not depend on it always run.
+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(partial: Partial<CompletionContext>): CompletionContext {
+  return {
+    uri: "file:///policies.ts",
+    content: "",
+    position: { line: 0, character: 0 },
+    wordAtCursor: "",
+    linePrefix: "",
+    ...partial,
+  };
+}
+
+describe("cedar completions", () => {
+  test("returns nothing in an unrelated position", () => {
+    expect(completions(ctx({ linePrefix: "const x = 1" }))).toEqual([]);
+  });
+
+  test("returns an array even with no cursor context", () => {
+    expect(Array.isArray(completions(ctx({})))).toBe(true);
+  });
+
+  test.skipIf(!hasGenerated)("suggests Policy after `new `", () => {
+    const items = completions(ctx({ linePrefix: "export const p = new " }));
+
+    expect(items.length).toBeGreaterThan(0);
+    expect(items.map((i) => i.label)).toContain("Policy");
+    expect(items.every((i) => i.kind === "resource")).toBe(true);
+  });
+
+  test.skipIf(!hasGenerated)("suggests schema-derived entity classes", () => {
+    const labels = completions(ctx({ linePrefix: "new " })).map((i) => i.label);
+
+    expect(labels).toContain("Document");
+    expect(labels).toContain("User");
+  });
+
+  test.skipIf(!hasGenerated)("narrows on a typed prefix", () => {
+    const items = completions(ctx({ linePrefix: "new Docu", wordAtCursor: "Docu" }));
+
+    expect(items.map((i) => i.label)).toContain("Document");
+    expect(items.every((i) => i.label.toLowerCase().startsWith("docu"))).toBe(true);
+  });
+
+  test.skipIf(!hasGenerated)("carries the Cedar type name as the detail", () => {
+    const policy = completions(ctx({ linePrefix: "new Poli", wordAtCursor: "Poli" })).find(
+      (i) => i.label === "Policy",
+    );
+
+    expect(policy?.detail).toBe("Cedar::Policy");
+  });
+
+  test.skipIf(!hasGenerated)("suggests Policy props inside the constructor", () => {
+    const content = "export const p = new Policy({\n  ";
+    const labels = completions(
+      ctx({
+        content,
+        position: { line: 1, character: 2 },
+        linePrefix: "  ",
+      }),
+    ).map((i) => i.label);
+
+    expect(labels).toContain("effect");
+    expect(labels).toContain("principal");
+    expect(labels).toContain("when");
+  });
+
+  test.skipIf(!hasGenerated)("suggests action constants in an `eq` scope", () => {
+    const items = completions(ctx({ linePrefix: "  action: { eq: " }));
+
+    expect(items.map((i) => i.label)).toContain("ReadAction");
+    expect(items.map((i) => i.label)).toContain("WriteAction");
+    // Entity classes are not actions and must not leak into this position.
+    expect(items.map((i) => i.label)).not.toContain("Document");
+  });
+
+  test.skipIf(!hasGenerated)("suggests action constants inside an `in` list", () => {
+    const labels = completions(ctx({ linePrefix: "  action: { in: [Rea", wordAtCursor: "Rea" })).map(
+      (i) => i.label,
+    );
+
+    expect(labels).toEqual(["ReadAction"]);
+  });
+
+  test.skipIf(!hasGenerated)("documents an action's principals and resources", () => {
+    const read = completions(ctx({ linePrefix: "  action: { eq: " })).find((i) => i.label === "ReadAction");
+
+    expect(read?.documentation).toContain("App::User");
+    expect(read?.documentation).toContain("App::Document");
+  });
+});