@intentius/chant-lexicon-cedar 0.44.14 → 0.45.0

package/src/init-templates.ts

@@ -17,7 +17,7 @@
  *
  * The policy files use `entityType`-string scopes (`{ is: "App::Document" }`)
  * and generated action constants, so a scaffolded project compiles the moment
- * `chant generate` has run against its own schema.
+ * `chant cedar generate` has run against its own schema (#1696).
  */
 
 import type { InitTemplateSet } from "@intentius/chant/lexicon";
@@ -30,12 +30,16 @@ function readme(title: string, body: string): string {
 
 \`\`\`bash
 npm install
-npx chant generate --lexicon cedar   # schema.cedarschema -> typed classes
-npx chant build                      # emits .cedar text + policies.cedar.json
+npx chant cedar generate   # schema.cedarschema -> src/generated/cedar/
+npx chant build            # emits .cedar text, policies.cedar.json, and the schema
 \`\`\`
 
-Generate first. The classes and action constants \`src/policies.ts\` imports do
-not exist until \`chant generate\` has read \`${SCHEMA_FILE}\`.
+Generate first. The classes and action constants \`src/policies.ts\` imports
+from \`./generated/cedar\` do not exist until \`chant cedar generate\` has read
+\`${SCHEMA_FILE}\`. The output is yours: it lives in this project, not in
+\`node_modules\`, so commit it (or regenerate it in CI before \`chant build\`)
+and re-run generate whenever the schema changes. \`cedar.outDir\` in
+\`chant.config.ts\` moves it.
 
 ${body}
 
@@ -63,6 +67,7 @@ this project never declared.
 |------|--------------|
 | \`dist/*.cedar\` | Every Cedar evaluator — AVP, cedar-agent, an embedded cedar-wasm |
 | \`dist/policies.cedar.json\` | The Cedar JSON policy format; also the parse source for import |
+| \`dist/${SCHEMA_FILE}\` | Your schema, beside the policies, so the build validates against it and a bundle can carry it |
 `;
 }
 
@@ -70,7 +75,7 @@ this project never declared.
 
 const DEFAULT_SCHEMA = `// The entity model your policies are typed against.
 //
-// \`chant generate --lexicon cedar\` turns every declaration below into a
+// \`chant cedar generate\` turns every declaration below into a
 // TypeScript class or constant, so a renamed entity type becomes a
 // compiler-guided refactor rather than a runtime validation failure.
 
@@ -96,7 +101,7 @@ namespace App {
 }
 `;
 
-const DEFAULT_POLICIES = `import { Policy, ReadAction, WriteAction } from "@intentius/chant-lexicon-cedar";
+const DEFAULT_POLICIES = `import { Policy, ReadAction, WriteAction } from "./generated/cedar";
 
 /**
  * A permit and a forbid — the smallest policy set worth deploying.
@@ -160,7 +165,7 @@ namespace Store {
 }
 `;
 
-const AVP_POLICIES = `import { Policy, EditAction, ViewAction } from "@intentius/chant-lexicon-cedar";
+const AVP_POLICIES = `import { Policy, EditAction, ViewAction } from "./generated/cedar";
 
 /**
  * Policies destined for an AVP policy store.
@@ -239,13 +244,8 @@ namespace Gateway {
 }
 `;
 
-const GATEWAY_POLICIES = `import {
-  DeleteAction,
-  DenyByDefaultSet,
-  GetAction,
-  Policy,
-  PostAction,
-} from "@intentius/chant-lexicon-cedar";
+const GATEWAY_POLICIES = `import { DenyByDefaultSet } from "@intentius/chant-lexicon-cedar";
+import { DeleteAction, GetAction, Policy, PostAction } from "./generated/cedar";
 
 /**
  * A gateway policy set with an explicit deny floor.
@@ -298,7 +298,7 @@ export const authenticatedWriteGrant = guarded.members[1];
  */
 export function cedarInitTemplates(template?: string): InitTemplateSet {
   const scripts = {
-    generate: "chant generate --lexicon cedar",
+    generate: "chant cedar generate",
     build: "chant build",
   };
 

package/src/lint/post-synth/cede010.ts

@@ -24,10 +24,11 @@
  * When the build emits no schema there is nothing to validate against, and
  * `validate()` cannot be called at all — it has no optional-schema mode, and an
  * empty schema is legal Cedar that reports every policy as inapplicable, which
- * would be worse than useless. Schema-driven codegen is #1650; until a schema
- * is emitted beside the policies, this check says so once, as an advisory,
- * rather than passing silently and claiming a guarantee it did not check.
- * CEDC010's parse gate still applies in that state.
+ * would be worse than useless. A project schema is emitted beside the policies
+ * by the plugin's `buildRoots` hook (#1697, `src/schema-artifact.ts`), so the
+ * no-schema state is now the project with no schema of its own; there this
+ * check says so once, as an advisory, rather than passing silently and
+ * claiming a guarantee it did not check. CEDC010's parse gate still applies.
  */
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
 import { parsedPolicySets } from "./cedar-helpers";

package/src/plugin.ts

@@ -20,6 +20,7 @@ import { CedarTemplateGenerator, CedarTemplateParser } from "./import/adapter";
 import type { ResourceMetadata } from "@intentius/chant/lexicon";
 import { AVP_OWNERSHIP_KEYS } from "./avp/ownership";
 import { AVP_AMBIENT_KINDS } from "./avp/ambient";
+import { cedarCommandGroup } from "./commands";
 
 /**
  * cedar lexicon plugin.
@@ -35,11 +36,17 @@ export const cedarPlugin: LexiconPlugin = {
   async generate(options?: { verbose?: boolean }): Promise<void> {
     // Cedar's codegen input is the project's own schema, so the `cedar` config
     // namespace is read here rather than being decoration (#1650).
-    const { generate, writeGeneratedFiles } = await import("./codegen/generate");
-    const { loadCedarConfig } = await import("./config");
-    const projectRoot = process.cwd();
-    const result = await generate({ ...options, projectRoot, config: await loadCedarConfig(projectRoot) });
-    writeGeneratedFiles(result);
+    //
+    // The output goes into the *project* (#1696): `cedar.outDir`, else
+    // `src/generated/cedar` under the config's directory. Only when the project
+    // is this package itself does it land in `src/generated/`.
+    const { generate, resolveGeneratedDir, writeGeneratedFiles } = await import("./codegen/generate");
+    const { loadCedarProject } = await import("./config");
+    const { projectRoot, config } = await loadCedarProject(process.cwd());
+    const result = await generate({ ...options, projectRoot, config });
+    const outDir = resolveGeneratedDir({ projectRoot, config });
+    writeGeneratedFiles(result, outDir);
+    if (options?.verbose) console.error(`cedar: wrote generated classes to ${outDir}`);
   },
 
   async validate(options?: { verbose?: boolean }): Promise<void> {
@@ -51,11 +58,15 @@ export const cedarPlugin: LexiconPlugin = {
 
   async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
     const { analyzeCedarCoverage } = await import("./coverage");
-    const { loadCedarConfig } = await import("./config");
-    const projectRoot = process.cwd();
+    const { resolveGeneratedDir } = await import("./codegen/generate");
+    const { loadCedarProject } = await import("./config");
+    const { projectRoot, config } = await loadCedarProject(process.cwd());
     analyzeCedarCoverage({
       projectRoot,
-      config: await loadCedarConfig(projectRoot),
+      config,
+      // Coverage compares the project's schema with the project's generated
+      // artifacts, which live where generate put them (#1696).
+      generatedDir: resolveGeneratedDir({ projectRoot, config }),
       verbose: options?.verbose,
       minOverall: options?.minOverall,
     });
@@ -76,6 +87,20 @@ export const cedarPlugin: LexiconPlugin = {
 
   // ── Optional extensions ────────────────────────────────────
 
+  // #1697 — the project's `.cedarschema` joins the build as a `Cedar::Schema`
+  // entity, so it is emitted beside the policies and CEDE010 validates
+  // against it rather than reporting that it could not. Nothing is
+  // contributed when only the bundled default schema applies.
+  async buildRoots(ctx) {
+    const { schemaBuildRoot } = await import("./schema-artifact");
+    return schemaBuildRoot(ctx);
+  },
+
+  // `chant cedar generate` and `chant cedar coverage` (#1696, via #1078).
+  commands() {
+    return cedarCommandGroup();
+  },
+
   lintRules() {
     return rules;
   },

package/src/schema-artifact.test.ts

@@ -0,0 +1,160 @@
+/**
+ * The project schema as a build artifact (#1697).
+ *
+ * End to end: a project schema goes in through the plugin's `buildRoots`
+ * hook, comes out of the serializer as `schema.cedarschema` beside the
+ * policies, and CEDE010 validates against it instead of saying it could not.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { cedarPlugin } from "./plugin";
+import { cedarSerializer, type CedarPolicyProps } from "./serializer";
+import { Policy, type PolicyProps } from "./generated/index";
+import { CEDAR_SCHEMA_ENTITY_NAME, CEDAR_SCHEMA_FILENAME, Schema, schemaBuildRoot } from "./schema-artifact";
+import { cede010 } from "./lint/post-synth/cede010";
+
+/**
+ * The package's `PolicyProps` narrows scopes to the bundled sample schema's
+ * names. These tests use the `Shop` schema above, so they build props as the
+ * string-typed `CedarPolicyProps` and widen at the constructor.
+ */
+function shopPolicy(props: CedarPolicyProps): InstanceType<typeof Policy> {
+  return new Policy(props as unknown as PolicyProps);
+}
+
+const SCHEMA = `namespace Shop {
+  entity Customer = { "email": String };
+  entity Order = { "owner": Customer };
+  action view appliesTo {
+    principal: [Customer],
+    resource: [Order],
+    context: { "mfa": Bool }
+  };
+}
+`;
+
+function serialize(entities: Map<string, Declarable>): SerializerResult {
+  const out = cedarSerializer.serialize(entities);
+  if (typeof out === "string") return { primary: out };
+  return out;
+}
+
+function postSynthCtx(result: SerializerResult): PostSynthContext {
+  return {
+    outputs: new Map([["cedar", result]]),
+    entities: new Map(),
+  } as unknown as PostSynthContext;
+}
+
+describe("Schema declarable", () => {
+  it("is emitted as a .cedarschema beside the policies", () => {
+    const entities = new Map<string, Declarable>([
+      ["authz", new Schema({ text: SCHEMA })],
+      [
+        "viewOwn",
+        shopPolicy({
+          effect: "permit",
+          principal: { is: "Shop::Customer" },
+          action: { in: ['Shop::Action::"view"'] },
+          resource: { is: "Shop::Order" },
+          when: ["resource.owner == principal"],
+        }),
+      ],
+    ]);
+
+    const result = serialize(entities);
+    expect(result.files?.[CEDAR_SCHEMA_FILENAME]).toBe(SCHEMA);
+    expect(result.primary).toContain("permit");
+  });
+
+  it("honours an explicit filename and is emitted even with no policies", () => {
+    const entities = new Map<string, Declarable>([["authz", new Schema({ text: SCHEMA, filename: "shop.cedarschema" })]]);
+    const result = serialize(entities);
+    expect(Object.keys(result.files ?? {})).toEqual(["shop.cedarschema"]);
+  });
+
+  it("warns rather than silently overwriting when two schemas share a filename", () => {
+    const entities = new Map<string, Declarable>([
+      ["a", new Schema({ text: "namespace A { entity X; }\n" })],
+      ["b", new Schema({ text: "namespace B { entity Y; }\n" })],
+    ]);
+    const result = serialize(entities);
+    expect(result.files?.[CEDAR_SCHEMA_FILENAME]).toBe("namespace A { entity X; }\n");
+    expect(result.warnings?.join("\n")).toMatch(/"b" targets schema\.cedarschema/);
+  });
+
+  it("turns CEDE010 from an advisory into validation", () => {
+    const badPolicy = shopPolicy({
+      effect: "permit",
+      principal: { is: "Shop::Customer" },
+      action: { in: ['Shop::Action::"view"'] },
+      resource: { is: "Shop::Nope" },
+    });
+
+    const without = cede010.check(postSynthCtx(serialize(new Map([["p", badPolicy]]))));
+    expect(without.map((d) => d.severity)).toEqual(["info"]);
+
+    const withSchema = cede010.check(
+      postSynthCtx(
+        serialize(
+          new Map<string, Declarable>([
+            ["p", badPolicy],
+            ["authz", new Schema({ text: SCHEMA })],
+          ]),
+        ),
+      ),
+    );
+    expect(withSchema.some((d) => d.severity === "error" && /Shop::Nope/.test(d.message))).toBe(true);
+  });
+});
+
+describe("schemaBuildRoot", () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "cedar-schema-root-"));
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("contributes the project schema when the project has one", async () => {
+    writeFileSync(join(root, "authz.cedarschema"), SCHEMA);
+    const contribution = await schemaBuildRoot({
+      projectRoot: root,
+      config: { cedar: { schema: "authz.cedarschema" } },
+    });
+
+    const entity = contribution.entities.get(CEDAR_SCHEMA_ENTITY_NAME);
+    expect(entity).toBeDefined();
+
+    const result = serialize(contribution.entities);
+    expect(result.files?.["authz.cedarschema"]).toBe(SCHEMA);
+  });
+
+  it("finds schema.cedarschema in the project root with no config at all", async () => {
+    writeFileSync(join(root, CEDAR_SCHEMA_FILENAME), SCHEMA);
+    const contribution = await schemaBuildRoot({ projectRoot: root, config: {} });
+    expect(contribution.entities.size).toBe(1);
+  });
+
+  it("contributes nothing when only the bundled default schema applies", async () => {
+    // Emitting the default would validate a project's policies against an
+    // entity model it never wrote; the CEDE010 advisory is the honest outcome.
+    const contribution = await schemaBuildRoot({ projectRoot: root, config: {} });
+    expect(contribution.entities.size).toBe(0);
+  });
+
+  it("is wired into the plugin", async () => {
+    writeFileSync(join(root, CEDAR_SCHEMA_FILENAME), SCHEMA);
+    const contribution = await cedarPlugin.buildRoots!({ projectRoot: root, config: {} });
+    expect(contribution.entities.has(CEDAR_SCHEMA_ENTITY_NAME)).toBe(true);
+  });
+});

package/src/schema-artifact.ts

@@ -0,0 +1,87 @@
+/**
+ * The project schema as a build artifact (#1697).
+ *
+ * CEDE010 can only validate a policy set against a schema the build emitted
+ * beside it, and until now nothing emitted one: the `.cedarschema` drove
+ * codegen and then stayed in the source tree, so every consumer build got the
+ * parse-only advisory. This module closes that gap from two directions.
+ *
+ * `Schema` is a declarable a project can author by hand when it wants a
+ * particular filename or a schema that is not the one in `chant.config.ts`.
+ * `schemaBuildRoot` is the automatic path: the plugin's `buildRoots` hook
+ * contributes one `Schema` entity per build, holding the resolved project
+ * schema, so a project with a `cedar.schema` gets `dist/schema.cedarschema`
+ * and full validation without declaring anything.
+ *
+ * The bundled default schema is never emitted. A project without its own
+ * schema has policies the default may well reject, and CEDE010 failing a
+ * build against a schema the project never wrote would be a worse surprise
+ * than the advisory it replaces.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+import type { BuildRootContext, BuildRootContribution } from "@intentius/chant/lexicon";
+import { createResource } from "@intentius/chant/runtime";
+import { getProps } from "./policy-text";
+import { resolveSchemaPath } from "./spec/fetch";
+import type { CedarGenerateConfig } from "./codegen/generate";
+import { readFileSync } from "fs";
+import { basename } from "path";
+
+/** The entity type of a {@link Schema}. */
+export const CEDAR_SCHEMA_TYPE = "Cedar::Schema";
+
+/** The logical name the build-root contribution uses. */
+export const CEDAR_SCHEMA_ENTITY_NAME = "cedarSchema";
+
+/** Filename the schema is emitted under when `filename` is unset. */
+export const CEDAR_SCHEMA_FILENAME = "schema.cedarschema";
+
+export interface SchemaProps {
+  /** Human-readable Cedar schema text, emitted verbatim. */
+  text: string;
+  /** Defaults to {@link CEDAR_SCHEMA_FILENAME}. Must end in `.cedarschema`. */
+  filename?: string;
+}
+
+/** A `.cedarschema` emitted with the policy set, so post-synth validation has something to validate against. */
+export const Schema = createResource(CEDAR_SCHEMA_TYPE, "cedar", {}) as unknown as new (props: SchemaProps) => Declarable;
+
+/** One schema file the serializer should write. */
+export interface SchemaFile {
+  name: string;
+  filename: string;
+  text: string;
+}
+
+/** Every `Cedar::Schema` in the entity map, with its props read. */
+export function schemaEntities(entities: Map<string, Declarable>): SchemaFile[] {
+  const files: SchemaFile[] = [];
+  for (const [name, entity] of entities) {
+    if (isPropertyDeclarable(entity)) continue;
+    if (entity.entityType !== CEDAR_SCHEMA_TYPE) continue;
+    const props = getProps(entity) as Partial<SchemaProps>;
+    if (typeof props.text !== "string") continue;
+    files.push({
+      name,
+      filename: typeof props.filename === "string" ? props.filename : CEDAR_SCHEMA_FILENAME,
+      text: props.text.endsWith("\n") ? props.text : props.text + "\n",
+    });
+  }
+  return files;
+}
+
+/**
+ * The `buildRoots` contribution: the project's resolved schema as one
+ * {@link Schema} entity, or nothing when only the bundled default applies.
+ */
+export async function schemaBuildRoot(ctx: BuildRootContext): Promise<BuildRootContribution> {
+  const config = (ctx.config as { cedar?: CedarGenerateConfig }).cedar ?? {};
+  const source = resolveSchemaPath({ projectRoot: ctx.projectRoot, config });
+  if (source.isDefault) return { entities: new Map() };
+
+  const text = readFileSync(source.path, "utf-8");
+  const entity = new Schema({ text, filename: basename(source.path) });
+  return { entities: new Map([[CEDAR_SCHEMA_ENTITY_NAME, entity]]) };
+}

package/src/serializer.ts

@@ -34,6 +34,7 @@ import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { policyToJson, splitPolicySet, templateToJson, type PolicyJson } from "./spec/wasm";
 import { serializeDogwood } from "./dogwood/serialize";
+import { schemaEntities } from "./schema-artifact";
 import {
   conditionStrings,
   getProps,
@@ -263,10 +264,25 @@ export const cedarSerializer: Serializer = {
     // and a project holding only temporal policies still gets its files.
     const dogwood = serializeDogwood(entities);
 
-    if (policyText.length === 0 && !dogwood) return "";
+    // The project schema, as a file beside the policies (#1697). This is what
+    // turns CEDE010's parse-only advisory into validation: `findSchema` in
+    // lint/post-synth/wasm-helpers.ts reads it straight back out of `files`.
+    const schemas = schemaEntities(entities);
+
+    if (policyText.length === 0 && !dogwood && schemas.length === 0) return "";
 
     const files: Record<string, string> = {};
     const warnings: string[] = [...(dogwood?.warnings ?? [])];
+
+    for (const schema of schemas) {
+      if (files[schema.filename] !== undefined) {
+        warnings.push(
+          `cedar: schema "${schema.name}" targets ${schema.filename}, which another schema already wrote; give one of them an explicit \`filename\``,
+        );
+        continue;
+      }
+      files[schema.filename] = schema.text;
+    }
     let primary = "";
 
     if (policyText.length > 0) {

package/src/skills/chant-cedar-authoring.md

@@ -51,9 +51,15 @@ between "your entity types" and "somebody else's" is invisible.
 ### 2. Run generate
 
 ```bash
-npx chant generate --lexicon cedar
+npx chant cedar generate
 ```
 
+The output is written into the project, at `src/generated/cedar/` (or
+`cedar.outDir`), never into `node_modules`. Commit it or regenerate it in CI;
+re-run it whenever the schema changes. Policies import from that directory,
+not from `@intentius/chant-lexicon-cedar`, whose own `Policy` and classes
+describe the package's bundled sample schema.
+
 That produces, per declaration in the schema:
 
 | Schema declaration | Generated |
@@ -68,7 +74,7 @@ compile error, not a validation error hours later.
 ### 3. Write policies
 
 ```typescript
-import { Policy, ReadAction, WriteAction, type UserUid } from "@intentius/chant-lexicon-cedar";
+import { Policy, ReadAction, WriteAction, type UserUid } from "./generated/cedar";
 
 const archivist: UserUid = 'App::User::"archivist"';
 
@@ -159,7 +165,7 @@ wider grant.
 
 ```bash
 npx chant build                         # emits both artifacts, runs the CED rules
-npx chant coverage --lexicon cedar      # is every schema declaration generated?
+npx chant cedar coverage                # is every schema declaration generated?
 ```
 
 The MCP tool `cedar:coverage` answers the other question: which schema entity

package/src/spec/fetch.ts

@@ -32,11 +32,32 @@ export const DEFAULT_SCHEMA_FILENAME = "default-schema.cedarschema";
 /** Map key used for the single schema entry, so `parseSchema` can tell them apart. */
 export const DEFAULT_SCHEMA_KEY = "<bundled-default>";
 
-const specDir = dirname(fileURLToPath(import.meta.url));
+let specDir: string | undefined;
+
+/**
+ * Directory this module lives in, resolved on first use.
+ *
+ * Kept lazy so importing the module never touches `import.meta.url`; edge
+ * bundles that pull this file in through the lint barrel have no such URL and
+ * would crash at module init otherwise.
+ */
+function resolveSpecDir(): string | undefined {
+  if (specDir !== undefined) return specDir;
+  try {
+    specDir = dirname(fileURLToPath(import.meta.url));
+  } catch {
+    return undefined;
+  }
+  return specDir;
+}
 
 /** Absolute path to the schema bundled with this package. */
 export function defaultSchemaPath(): string {
-  return join(specDir, DEFAULT_SCHEMA_FILENAME);
+  const dir = resolveSpecDir();
+  if (dir === undefined) {
+    throw new Error("cedar: the bundled default schema is not reachable from this runtime (no module URL).");
+  }
+  return join(dir, DEFAULT_SCHEMA_FILENAME);
 }
 
 export interface SchemaSource {