@intentius/chant-lexicon-cedar 0.44.8

package/src/import/adapter.ts

@@ -0,0 +1,63 @@
+/**
+ * The seam between the cedar-shaped parser/generator above and the core
+ * `TemplateParser` / `TypeScriptGenerator` that `chant import` drives.
+ *
+ * Core's pipeline speaks `TemplateIR` — a flat list of `ResourceIR` with a
+ * `type` string it may reorganize into category files. A Cedar policy maps
+ * cleanly onto one: the logical id is the policy id, and the type records
+ * whether Cedar read it as a static policy or as a template, so the mapping
+ * reverses without guessing.
+ */
+
+import type { TemplateIR, TemplateParser, ResourceIR } from "@intentius/chant/import/parser";
+import type { GeneratedFile, TypeScriptGenerator } from "@intentius/chant/import/generator";
+import { CedarParser, type CedarEntityKind, type CedarPolicyIR } from "./parser";
+import { CedarGenerator, loadActionConstants } from "./generator";
+
+/** The `ResourceIR.type` each IR kind is filed under. */
+const TYPE_BY_KIND: Record<CedarEntityKind, string> = {
+  policy: "Cedar::Policy",
+  template: "Cedar::Template",
+};
+
+const KIND_BY_TYPE: Record<string, CedarEntityKind> = {
+  "Cedar::Policy": "policy",
+  "Cedar::Template": "template",
+};
+
+function toResource(entity: CedarPolicyIR): ResourceIR {
+  return {
+    logicalId: entity.name,
+    type: TYPE_BY_KIND[entity.kind],
+    properties: entity.props,
+  };
+}
+
+function toPolicyIR(resource: ResourceIR): CedarPolicyIR {
+  return {
+    kind: KIND_BY_TYPE[resource.type] ?? "policy",
+    name: resource.logicalId,
+    props: resource.properties,
+  };
+}
+
+/** `TemplateParser` over `.cedar` text and the JSON policy-set envelope. */
+export class CedarTemplateParser implements TemplateParser {
+  parse(content: string): TemplateIR {
+    const { entities, warnings } = new CedarParser().parse(content);
+    return {
+      resources: entities.map(toResource),
+      parameters: [],
+      ...(warnings.length > 0 ? { metadata: { warnings } } : {}),
+    };
+  }
+}
+
+/** `TypeScriptGenerator` emitting `new Policy({ … })` per imported policy. */
+export class CedarTemplateGenerator implements TypeScriptGenerator {
+  generate(ir: TemplateIR): GeneratedFile[] {
+    const generator = new CedarGenerator({ actionConstants: loadActionConstants() });
+    const { source } = generator.generate(ir.resources.map(toPolicyIR));
+    return [{ path: "main.ts", content: source }];
+  }
+}

package/src/import/clause-text.ts

@@ -0,0 +1,178 @@
+/**
+ * Recover the `when`/`unless` bodies of a policy exactly as they were written.
+ *
+ * The round-trip this lexicon promises is byte-identical `.cedar` output, and
+ * the JSON leg cannot deliver it: an expression that goes to `PolicyJson` and
+ * back comes out defensively parenthesized — `resource.owner == principal`
+ * returns as `(resource.owner) == principal` — and `formatPolicies` does not
+ * undo that. The tree is semantically lossless; the text is not preserved.
+ *
+ * So when there *is* source text, the condition bodies are lifted out of it
+ * verbatim, and the module still decides what they mean: every body this file
+ * hands back is re-parsed and compared against the tree `policyToJson` produced
+ * for the same clause before the importer trusts it (see `parser.ts`). A
+ * mismatch falls back to the rendered form.
+ *
+ * What is here is a *delimiter scanner*, not a Cedar parser. It knows three
+ * things — that a `"` starts a string with backslash escapes, that `//` runs
+ * to end of line, and that `@`, `(` and `{` have partners — and it knows the
+ * two clause keywords. It has no opinion about expressions, which remains the
+ * module's job. Anything it does not recognize returns `null`, and the caller
+ * uses the rendered bodies instead.
+ */
+
+/** One `when`/`unless` clause, with its body as the author typed it. */
+export interface SourceClause {
+  kind: "when" | "unless";
+  /** The text between the braces, trimmed. */
+  body: string;
+}
+
+const WHITESPACE = /\s/;
+const WORD_CHAR = /[A-Za-z0-9_]/;
+
+class Scanner {
+  private index = 0;
+
+  constructor(private readonly text: string) {}
+
+  atEnd(): boolean {
+    return this.index >= this.text.length;
+  }
+
+  peek(): string {
+    return this.text[this.index] ?? "";
+  }
+
+  /** Consume whitespace and `//` line comments. */
+  skipTrivia(): void {
+    while (this.index < this.text.length) {
+      const ch = this.text[this.index];
+      if (WHITESPACE.test(ch)) {
+        this.index++;
+        continue;
+      }
+      if (ch === "/" && this.text[this.index + 1] === "/") {
+        while (this.index < this.text.length && this.text[this.index] !== "\n") this.index++;
+        continue;
+      }
+      return;
+    }
+  }
+
+  /** Consume one `[A-Za-z0-9_]+` run, or `null` if the cursor is not on one. */
+  word(): string | null {
+    const start = this.index;
+    while (this.index < this.text.length && WORD_CHAR.test(this.text[this.index])) this.index++;
+    return this.index > start ? this.text.slice(start, this.index) : null;
+  }
+
+  /** Consume the single character `ch`, reporting whether it was there. */
+  expect(ch: string): boolean {
+    if (this.text[this.index] !== ch) return false;
+    this.index++;
+    return true;
+  }
+
+  /**
+   * Consume a balanced `open`…`close` run starting at the cursor and return
+   * what was between them.
+   *
+   * Strings and line comments are skipped wholesale, so a `}` inside
+   * `"}; hi {"` or behind a `//` never closes anything.
+   */
+  delimited(open: string, close: string): string | null {
+    if (!this.expect(open)) return null;
+    const start = this.index;
+    let depth = 1;
+
+    while (this.index < this.text.length) {
+      const ch = this.text[this.index];
+
+      if (ch === '"') {
+        if (!this.skipString()) return null;
+        continue;
+      }
+      if (ch === "/" && this.text[this.index + 1] === "/") {
+        this.skipTrivia();
+        continue;
+      }
+      if (ch === open) depth++;
+      if (ch === close) {
+        depth--;
+        if (depth === 0) {
+          const body = this.text.slice(start, this.index);
+          this.index++;
+          return body;
+        }
+      }
+      this.index++;
+    }
+    return null;
+  }
+
+  /** Consume a double-quoted literal, honouring backslash escapes. */
+  private skipString(): boolean {
+    this.index++; // opening quote
+    while (this.index < this.text.length) {
+      const ch = this.text[this.index];
+      if (ch === "\\") {
+        this.index += 2;
+        continue;
+      }
+      this.index++;
+      if (ch === '"') return true;
+    }
+    return false;
+  }
+}
+
+/**
+ * Split one policy's source into its clause bodies.
+ *
+ * Returns `null` for anything that does not walk cleanly — an unbalanced
+ * brace, a keyword that is neither `when` nor `unless`, trailing text after
+ * the terminating `;`. `null` is not a diagnosis, only a decision to use the
+ * module's rendering instead.
+ */
+export function extractClauses(policyText: string): SourceClause[] | null {
+  const scanner = new Scanner(policyText);
+
+  // Annotations: `@key( "value" )`, any number of them.
+  scanner.skipTrivia();
+  while (scanner.peek() === "@") {
+    scanner.expect("@");
+    if (scanner.word() === null) return null;
+    scanner.skipTrivia();
+    if (scanner.delimited("(", ")") === null) return null;
+    scanner.skipTrivia();
+  }
+
+  const effect = scanner.word();
+  if (effect !== "permit" && effect !== "forbid") return null;
+
+  // The scope block. Its contents are of no interest here; skipping it is what
+  // keeps the `(` of `@id(` from being mistaken for the scope's own.
+  scanner.skipTrivia();
+  if (scanner.delimited("(", ")") === null) return null;
+
+  const clauses: SourceClause[] = [];
+  for (;;) {
+    scanner.skipTrivia();
+    if (scanner.expect(";")) break;
+
+    const keyword = scanner.word();
+    if (keyword !== "when" && keyword !== "unless") return null;
+
+    scanner.skipTrivia();
+    const body = scanner.delimited("{", "}");
+    if (body === null) return null;
+
+    clauses.push({ kind: keyword, body: body.trim() });
+  }
+
+  scanner.skipTrivia();
+  if (!scanner.atEnd()) return null;
+
+  return clauses;
+}

package/src/import/generator.test.ts

@@ -0,0 +1,133 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { CedarParser } from "./parser";
+import { CedarGenerator, loadActionConstants, sanitizeName } from "./generator";
+import type { CedarPolicyIR } from "./parser";
+
+const testdata = (file: string) => readFileSync(join(import.meta.dirname, "testdata", file), "utf8");
+
+const generate = (entities: CedarPolicyIR[], actionConstants?: Record<string, string>) =>
+  new CedarGenerator({ actionConstants }).generate(entities).source;
+
+const fromFixture = (file: string, actionConstants?: Record<string, string>) =>
+  generate(new CedarParser().parse(testdata(file)).entities, actionConstants);
+
+// ── 1–3. The shape of a generated policy ───────────────────────────
+
+describe("emitting a policy", () => {
+  test("1. a policy becomes an exported Policy construction", () => {
+    expect(fromFixture("simple.cedar")).toContain("export const allowAliceRead = new Policy({");
+  });
+
+  test("2. every captured prop is emitted, with identifier keys unquoted", () => {
+    const source = fromFixture("simple.cedar");
+    expect(source).toContain('effect: "permit"');
+    expect(source).toContain('principal: {\n    eq: "App::User::\\"alice\\""\n  }');
+    expect(source).toContain('resource: {\n    is: "App::Document"\n  }');
+    expect(source).toContain('id: "allow-alice-read"');
+  });
+
+  test("3. when and unless clauses are emitted as the strings they are", () => {
+    const source = fromFixture("realistic.cedar");
+    expect(source).toContain('when: [\n    "resource.owner == principal"\n  ]');
+    expect(source).toContain('unless: [\n    "context.mfa == false"\n  ]');
+  });
+});
+
+// ── 4–5. The import line ───────────────────────────────────────────
+
+describe("the import line", () => {
+  test("4. one line, naming the authoring class", () => {
+    const lines = fromFixture("simple.cedar").split("\n");
+    expect(lines[0]).toBe('import { Policy } from "@intentius/chant-lexicon-cedar";');
+    expect(lines.filter((l) => l.startsWith("import "))).toHaveLength(1);
+  });
+
+  test("5. generated action constants join it, sorted, when the schema is known", () => {
+    const source = fromFixture("realistic.cedar", loadActionConstants());
+    expect(source.split("\n")[0]).toBe(
+      'import { DeleteAction, ListAction, Policy, ReadAction, WriteAction } from "@intentius/chant-lexicon-cedar";',
+    );
+  });
+});
+
+// ── 6–7. Typed refs vs. literal fallback ───────────────────────────
+
+describe("action refs", () => {
+  test("6. a known action UID is emitted as its generated constant", () => {
+    const source = fromFixture("realistic.cedar", loadActionConstants());
+    expect(source).toContain("action: {\n    in: [\n      ReadAction,\n      ListAction\n    ]\n  }");
+    expect(source).toContain("action: {\n    eq: DeleteAction\n  }");
+  });
+
+  test("7. with no registry the UID literal is the fallback, and still typechecks", () => {
+    const source = fromFixture("realistic.cedar");
+    expect(source).toContain('eq: "App::Action::\\"delete\\""');
+    expect(source).not.toContain("DeleteAction");
+  });
+
+  test("an action UID inside a when clause is left as expression text", () => {
+    const source = generate(
+      [{ kind: "policy", name: "p", props: { effect: "permit", when: ['action == App::Action::"read"'] } }],
+      { 'App::Action::"read"': "ReadAction" },
+    );
+    expect(source).toContain('"action == App::Action::\\"read\\""');
+    expect(source.split("\n")[0]).toBe('import { Policy } from "@intentius/chant-lexicon-cedar";');
+  });
+});
+
+// ── 8–9. Names ─────────────────────────────────────────────────────
+
+describe("export names", () => {
+  test("8. kebab-case and snake_case ids become camelCase exports", () => {
+    expect(sanitizeName("allow-alice-read")).toBe("allowAliceRead");
+    expect(sanitizeName("legacy_policy_name")).toBe("legacyPolicyName");
+    expect(sanitizeName("simple")).toBe("simple");
+    expect(sanitizeName("SOC2-AC-3")).toBe("soc2AC3");
+    expect(sanitizeName("2fa-required")).toBe("policy2faRequired");
+    expect(sanitizeName("class")).toBe("classPolicy");
+    expect(sanitizeName("!!!")).toBe("policy");
+  });
+
+  test("9. two ids that reduce to the same identifier still get one export each", () => {
+    const source = generate([
+      { kind: "policy", name: "allow-read", props: { effect: "permit" } },
+      { kind: "policy", name: "allow.read", props: { effect: "forbid" } },
+    ]);
+    expect(source).toContain("export const allowRead = ");
+    expect(source).toContain("export const allowRead2 = ");
+  });
+});
+
+// ── 10–11. Templates and empty input ───────────────────────────────
+
+describe("templates and empty documents", () => {
+  test("10. a template is emitted with its slots, and called out in a comment", () => {
+    const source = fromFixture("full.cedar");
+    expect(source).toContain("/** Cedar template");
+    expect(source).toContain("export const shareWithSlots = new Policy({");
+    expect(source).toContain('eq: "?principal"');
+    expect(source).toContain('in: "?resource"');
+  });
+
+  test("11. an empty document still emits a compilable file, with a warning", () => {
+    const { source, warnings } = new CedarGenerator().generate([]);
+    expect(source).toBe('import { Policy } from "@intentius/chant-lexicon-cedar";\n');
+    expect(warnings).toEqual(["no Cedar policies were found in this document"]);
+  });
+});
+
+// ── The registry lookup ────────────────────────────────────────────
+
+describe("loadActionConstants", () => {
+  test("maps every generated action UID to its constant", () => {
+    const constants = loadActionConstants();
+    expect(constants['App::Action::"read"']).toBe("ReadAction");
+    expect(Object.values(constants).every((name) => name.endsWith("Action"))).toBe(true);
+  });
+
+  test("a package with no generated registry yields no constants, not a throw", () => {
+    expect(loadActionConstants("/nowhere/at/all")).toEqual({});
+  });
+});

package/src/import/generator.ts

@@ -0,0 +1,219 @@
+/**
+ * TypeScript generator for `chant import`.
+ *
+ * Turns the parser's IR back into the authoring source it came from: one
+ * `import` line, then an `export const … = new Policy({ … })` per policy.
+ *
+ * `Policy` is the schema-driven class `chant generate` emits, and the scope
+ * refs it accepts are string-literal unions — so `action: { eq: 'App::Action::"read"' }`
+ * is already checked against the schema by the compiler, and an action the
+ * schema never declared is an error at the import site. Where the generated
+ * registry is on hand, an action UID is emitted as the generated *constant*
+ * (`ReadAction`) instead, which reads better and survives a rename; without a
+ * registry the literal is the fallback, and it typechecks just the same.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import type { CedarPolicyIR } from "./parser";
+
+/** The package this generated source imports from. */
+export const CEDAR_PACKAGE = "@intentius/chant-lexicon-cedar";
+
+/** The authoring class every imported policy is emitted against. */
+const POLICY_CLASS = "Policy";
+
+export interface CedarGenerateOptions {
+  /**
+   * `App::Action::"read"` → `ReadAction`, from the generated registry.
+   *
+   * Empty by default: the generator is a pure function of its IR, and the
+   * adapter is what goes looking for a registry to fill this in.
+   */
+  actionConstants?: Record<string, string>;
+}
+
+export interface CedarGenerateResult {
+  source: string;
+  warnings: string[];
+}
+
+// ── Identifier sanitization ───────────────────────────────────────
+
+/**
+ * A word no export may be called. Not the full reserved list — only the ones a
+ * policy id plausibly reduces to.
+ */
+const RESERVED = new Set([
+  "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do",
+  "else", "enum", "export", "extends", "false", "finally", "for", "function", "if", "import",
+  "in", "instanceof", "new", "null", "return", "super", "switch", "this", "throw", "true", "try",
+  "typeof", "var", "void", "while", "with", "yield", "let", "static", "await", "interface",
+  "package", "private", "protected", "public", "implements",
+]);
+
+/**
+ * A Cedar policy id as a JavaScript identifier.
+ *
+ * `allow-alice-read` → `allowAliceRead`, `legacy_policy` → `legacyPolicy`,
+ * `SOC2-AC-3` → `soc2AC3`. A leading segment that is already mixed case keeps
+ * its shape apart from the first letter; one that is all caps is lowered whole,
+ * so an id like `SOC2` does not come back as `sOC2`.
+ */
+export function sanitizeName(id: string): string {
+  const segments = id.split(/[^A-Za-z0-9]+/).filter(Boolean);
+  if (segments.length === 0) return "policy";
+
+  const [first, ...rest] = segments;
+  const head = /[a-z]/.test(first) ? first[0].toLowerCase() + first.slice(1) : first.toLowerCase();
+  const tail = rest.map((segment) => segment[0].toUpperCase() + segment.slice(1)).join("");
+
+  let name = head + tail;
+  if (/^[0-9]/.test(name)) name = `policy${name[0].toUpperCase()}${name.slice(1)}`;
+  if (RESERVED.has(name)) name = `${name}Policy`;
+  return name;
+}
+
+/** Give every export a distinct name, in a way a second run reproduces. */
+function uniqueNames(entities: CedarPolicyIR[]): string[] {
+  const taken = new Set<string>();
+  return entities.map((entity) => {
+    const base = sanitizeName(entity.name);
+    let candidate = base;
+    let n = 2;
+    while (taken.has(candidate)) candidate = `${base}${n++}`;
+    taken.add(candidate);
+    return candidate;
+  });
+}
+
+// ── Props emission ────────────────────────────────────────────────
+
+/**
+ * A marker no Cedar value can contain, so a substitution cannot be confused
+ * for content. The props go through `JSON.stringify` as data; identifiers are
+ * swapped in afterwards by matching the encoded marker exactly.
+ */
+const MARKER = "\u0000chant:";
+
+const SCOPE_KEYS = ["principal", "action", "resource"] as const;
+
+/**
+ * Swap recognized action UIDs for their generated constant, in scope positions
+ * only.
+ *
+ * Not inside `when`/`unless`: those are Cedar expression text, where the UID is
+ * part of a larger expression the compiler never sees as a ref.
+ */
+function markScopeConstants(
+  props: Record<string, unknown>,
+  actionConstants: Record<string, string>,
+  used: Set<string>,
+): Record<string, unknown> {
+  if (Object.keys(actionConstants).length === 0) return props;
+
+  const mark = (value: unknown): unknown => {
+    if (typeof value !== "string") return value;
+    const constant = actionConstants[value];
+    if (!constant) return value;
+    used.add(constant);
+    return `${MARKER}${constant}`;
+  };
+
+  const out: Record<string, unknown> = { ...props };
+  for (const key of SCOPE_KEYS) {
+    const scope = out[key];
+    if (!scope || typeof scope !== "object") continue;
+    const marked: Record<string, unknown> = { ...(scope as Record<string, unknown>) };
+    if ("eq" in marked) marked.eq = mark(marked.eq);
+    if (Array.isArray(marked.in)) marked.in = marked.in.map(mark);
+    else if ("in" in marked) marked.in = mark(marked.in);
+    out[key] = marked;
+  }
+  return out;
+}
+
+/** `{"effect": "permit"}` → `{ effect: "permit" }`, and markers → identifiers. */
+function emitProps(props: Record<string, unknown>): string {
+  const json = JSON.stringify(props, null, 2)
+    // Unquote keys that are already valid identifiers. A quote inside a string
+    // value is escaped as `\"` by `JSON.stringify`, so no value can present the
+    // `"ident":` shape this matches.
+    .replace(/"([A-Za-z_$][A-Za-z0-9_$]*)":/g, "$1:");
+
+  return json.replace(/"\\u0000chant:([A-Za-z_$][A-Za-z0-9_$]*)"/g, "$1");
+}
+
+// ── Generator ─────────────────────────────────────────────────────
+
+export class CedarGenerator {
+  private readonly actionConstants: Record<string, string>;
+
+  constructor(options: CedarGenerateOptions = {}) {
+    this.actionConstants = options.actionConstants ?? {};
+  }
+
+  generate(entities: CedarPolicyIR[]): CedarGenerateResult {
+    const warnings: string[] = [];
+    const imports = new Set<string>([POLICY_CLASS]);
+    const names = uniqueNames(entities);
+    const blocks: string[] = [];
+
+    for (const [index, entity] of entities.entries()) {
+      const props = markScopeConstants(entity.props, this.actionConstants, imports);
+
+      if (entity.kind === "template") {
+        blocks.push(
+          "/** Cedar template — its `?principal`/`?resource` slots are filled at link time. */",
+        );
+      }
+      blocks.push(`export const ${names[index]} = new ${POLICY_CLASS}(${emitProps(props)});`);
+      blocks.push("");
+    }
+
+    if (entities.length === 0) warnings.push("no Cedar policies were found in this document");
+
+    const importLine = `import { ${[...imports].sort().join(", ")} } from "${CEDAR_PACKAGE}";`;
+    const source = [importLine, "", ...blocks].join("\n");
+
+    return { source: source.endsWith("\n") ? source : `${source}\n`, warnings };
+  }
+}
+
+// ── Generated registry lookup ─────────────────────────────────────
+
+/** Filename of the registry `chant generate` writes beside the typed classes. */
+const REGISTRY_FILE = "lexicon-cedar.json";
+
+interface RegistryEntry {
+  resourceType?: string;
+  kind?: string;
+}
+
+/**
+ * Read `App::Action::"read"` → `ReadAction` out of the generated registry.
+ *
+ * Best-effort by design: a project that has not run `chant generate` has no
+ * registry, and the generator falls back to emitting UID literals — which the
+ * `Policy` class accepts and the compiler still checks.
+ */
+export function loadActionConstants(packageDir?: string): Record<string, string> {
+  const base = packageDir ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  const path = join(base, "generated", REGISTRY_FILE);
+  if (!existsSync(path)) return {};
+
+  try {
+    const registry = JSON.parse(readFileSync(path, "utf-8")) as Record<string, RegistryEntry>;
+    const constants: Record<string, string> = {};
+    for (const [tsName, entry] of Object.entries(registry)) {
+      if (entry.kind !== "resource") continue;
+      if (typeof entry.resourceType !== "string") continue;
+      if (!/::Action::"/.test(entry.resourceType)) continue;
+      constants[entry.resourceType] = tsName;
+    }
+    return constants;
+  } catch {
+    return {};
+  }
+}