@intentius/chant-lexicon-cedar 0.44.8 → 0.44.9

package/src/dogwood/index.ts

@@ -0,0 +1,198 @@
+/**
+ * The dogwood temporal dialect (#1658, epic #1646).
+ *
+ * A dialect of the cedar lexicon, not a lexicon of its own: `.dw` policies are
+ * Cedar policies with temporal clauses, their entity and action schemas are
+ * Cedar schemas, and the rendering is shared with the `.cedar` leg. Checks
+ * ship under the `DWD` id family, declared on the cedar serializer's
+ * `extraRulePrefixes`.
+ *
+ * Pre-release. Upstream (dogwood-policy/dogwood, Apache-2.0) is a read-only
+ * squash-sync mirror with no tags, no releases and no stability statement, and
+ * calls itself "NOT intended for production use". The surface here is built
+ * against the revision recorded in `./upstream.ts` and re-verified per
+ * sub-issue.
+ */
+
+export {
+  DEFAULT_MAX_WINDOW,
+  isWindowParam,
+  renderWindow,
+  renderWindowValue,
+  window,
+  windowParam,
+  windowSeconds,
+  windowValue,
+} from "./window";
+export type { TemporalWindow, TimeUnit, WindowLike, WindowParam, WindowValue } from "./window";
+
+export {
+  and,
+  arrayOf,
+  binderName,
+  bool,
+  call,
+  compare,
+  count,
+  ctx,
+  decimalOf,
+  entityUid,
+  exists,
+  formerly,
+  int,
+  interval,
+  not,
+  predicate,
+  previous,
+  raw,
+  renderCondition,
+  renderTerm,
+  scopeRef,
+  sigilCondition,
+  since,
+  str,
+  sum,
+  temporalMarker,
+  term,
+  tp,
+  typedBinder,
+  varRef,
+  wildcard,
+} from "./temporal";
+export type {
+  AndNode,
+  ArrayTerm,
+  CallNode,
+  ComparisonNode,
+  ComparisonOperator,
+  CountTerm,
+  ExistsNode,
+  FormerlyNode,
+  IntervalArg,
+  MacroArg,
+  NotNode,
+  PredicateNode,
+  PreviousNode,
+  RawCondition,
+  SigilCondition,
+  SinceNode,
+  SumTerm,
+  TemporalCondition,
+  TemporalTerm,
+  TermInput,
+  TermText,
+  TpNode,
+  TypedBinder,
+  WindowArgument,
+} from "./temporal";
+
+export {
+  DEFAULT_MACRO_NAMES,
+  bind,
+  countDistinctWithin,
+  countWithin,
+  defCedarMacro,
+  defTemporalMacro,
+  defaultMacroLibrary,
+  macroCondition,
+  macroTerm,
+  macroWindow,
+  renderMacroDefinition,
+  renderMacroLibrary,
+  sumWithin,
+} from "./macros";
+export type { MacroDefinition, MacroKind } from "./macros";
+
+export {
+  concrete,
+  declaredEventKinds,
+  defaultEventSchema,
+  eventDeclaration,
+  eventSchema,
+  field,
+  pinContext,
+  pinPrincipal,
+  pinResource,
+  pinnedField,
+  principalType,
+  record,
+  renderEventSchema,
+  resourceType,
+  spreadInputs,
+  spreadOutputs,
+} from "./event-schema";
+export type {
+  EventDeclaration,
+  EventField,
+  EventFieldType,
+  EventSchema,
+  EventSelector,
+  NamedField,
+  PinTarget,
+  SpreadField,
+} from "./event-schema";
+
+export {
+  DOGWOOD_EVENT_SCHEMA_FILENAME,
+  DOGWOOD_EVENT_SCHEMA_TYPE,
+  DOGWOOD_LEXICON,
+  DOGWOOD_MACRO_FILENAME,
+  DOGWOOD_MACRO_LIBRARY_TYPE,
+  DOGWOOD_POLICY_FILENAME,
+  DOGWOOD_POLICY_TYPE,
+  TemporalEventSchema,
+  TemporalMacroLibrary,
+  TemporalPolicy,
+} from "./policy";
+export type { EventSchemaProps, MacroLibraryProps, TemporalPolicyProps } from "./policy";
+
+export {
+  DOGWOOD_EVENT_SCHEMA_SUFFIX,
+  DOGWOOD_POLICY_SUFFIX,
+  renderTemporalPolicyText,
+  serializeDogwood,
+} from "./serialize";
+export type { DogwoodSerializeResult } from "./serialize";
+
+export {
+  blankComments,
+  dogwoodPolicyFiles,
+  dogwoodSchemaFiles,
+  effectiveMaxWindowSeconds,
+  readEventSchema,
+  scanPredicates,
+  scanWindowlessOperators,
+  scanWindows,
+  temporalRegions,
+} from "./scan";
+export type { DogwoodArtifact, EventSchemaFacts, TemporalPredicateRef, WindowRef } from "./scan";
+
+export { DOGWOOD_UPSTREAM } from "./upstream";
+
+export {
+  DOGWOOD_BINARY_ENV,
+  DOGWOOD_BINARY_NAME,
+  DOGWOOD_SEARCH_ORDER,
+  configureDogwoodCli,
+  findDogwoodBinary,
+  formatDogwoodDiagnostic,
+  parseLowerOutput,
+  parseValidateOutput,
+  resetDogwoodCli,
+  runDogwoodLower,
+  runDogwoodValidate,
+} from "./cli";
+export type {
+  DogwoodBinary,
+  DogwoodBinarySource,
+  DogwoodBundle,
+  DogwoodDiagnostic,
+  DogwoodFatal,
+  DogwoodLabel,
+  DogwoodLowerResult,
+  DogwoodLowered,
+  DogwoodRun,
+  DogwoodRunner,
+  DogwoodUnusable,
+  DogwoodValidateResult,
+} from "./cli";

package/src/dogwood/macros.test.ts

@@ -0,0 +1,104 @@
+import { describe, test, expect } from "vitest";
+import {
+  DEFAULT_MACRO_NAMES,
+  bind,
+  defCedarMacro,
+  defTemporalMacro,
+  defaultMacroLibrary,
+  macroCondition,
+  macroTerm,
+  macroWindow,
+  renderMacroDefinition,
+  renderMacroLibrary,
+} from "./macros";
+import { and, count, formerly, renderCondition, tp, typedBinder } from "./temporal";
+
+describe("def-macro authoring", () => {
+  test("a temporal macro renders as upstream's def_decl", () => {
+    const def = defTemporalMacro("once", ["?w", "?s"], formerly(macroWindow("?w"), macroCondition("?s")));
+    expect(renderMacroDefinition(def)).toBe(
+      "def temporal once(?w, ?s) {\n    formerly within ?w ?s\n};",
+    );
+  });
+
+  test("a temporal macro body may be a bare aggregation value", () => {
+    const def = defTemporalMacro(
+      "count_within",
+      ["?w", "?s"],
+      count(
+        [typedBinder("$t", "Timepoint")],
+        formerly(macroWindow("?w"), and(macroCondition("?s"), tp("$t"))),
+      ),
+    );
+    expect(renderMacroDefinition(def)).toContain("count for ($t: Timepoint). where formerly within ?w (?s && tp($t))");
+  });
+
+  test("a cedar macro keeps its body as Cedar expression text", () => {
+    const def = defCedarMacro("is_small", ["?n"], "?n < 100");
+    expect(renderMacroDefinition(def)).toBe("def cedar is_small(?n) {\n    ?n < 100\n};");
+  });
+
+  test("a comment is emitted above the definition", () => {
+    const def = defCedarMacro("is_small", ["?n"], "?n < 100", "Under a hundred.\nNothing more.");
+    expect(renderMacroDefinition(def).split("\n").slice(0, 2)).toEqual([
+      "// Under a hundred.",
+      "// Nothing more.",
+    ]);
+  });
+
+  test("a parameter without the ? sigil is refused, and the message says which to write", () => {
+    expect(() => defCedarMacro("is_small", ["n"], "n < 100")).toThrow(/carries the "\?" sigil.*"\?n"/s);
+  });
+
+  test("a macro name that is not an identifier is refused", () => {
+    expect(() => defCedarMacro("is small", [], "true")).toThrow(/must be an identifier/);
+  });
+});
+
+describe("the two sigils", () => {
+  test("?p splices a call-site value; $t is a macro-introduced fresh binder", () => {
+    expect(renderCondition(macroCondition("?s"))).toBe("?s");
+    expect(macroTerm("$t").text).toBe("$t");
+    expect(macroTerm("?a").text).toBe("?a");
+  });
+
+  test("a $ sigil is not a window parameter — the expander resolves only ?p there", () => {
+    expect(() => macroWindow("$w")).toThrow(/carries the "\?" sigil/);
+  });
+
+  test("a bare identifier is not a sigil", () => {
+    expect(() => macroCondition("s")).toThrow(/carries the "\?" sigil/);
+    expect(() => macroTerm("a")).toThrow(/carries a "\?" or "\$" sigil/);
+  });
+});
+
+describe("the default library", () => {
+  test("names exactly what upstream's default_macros.dw ships", () => {
+    expect([...DEFAULT_MACRO_NAMES]).toEqual([
+      "count_within",
+      "sum_within",
+      "count_distinct_within",
+      "bind",
+    ]);
+    expect(defaultMacroLibrary().map((d) => d.name)).toEqual([...DEFAULT_MACRO_NAMES]);
+  });
+
+  test("every definition is a temporal macro whose params all carry the sigil", () => {
+    for (const def of defaultMacroLibrary()) {
+      expect(def.kind).toBe("temporal");
+      for (const param of def.params) expect(param.startsWith("?")).toBe(true);
+    }
+  });
+
+  test("bind() is a call, so a policy using it depends on the callee's --macros", () => {
+    const node = bind("n", macroCondition("?A"), macroCondition("?B"));
+    expect(node.op).toBe("call");
+    expect(renderCondition(node)).toBe("bind(n, ?A, ?B)");
+  });
+
+  test("the library renders as a file a --macros flag can point at", () => {
+    const text = renderMacroLibrary(defaultMacroLibrary());
+    expect(text.endsWith("};\n")).toBe(true);
+    expect(text.split("\n\n")).toHaveLength(4);
+  });
+});

package/src/dogwood/macros.ts

@@ -0,0 +1,229 @@
+/**
+ * Macro authoring, and the default library as calls rather than operators.
+ *
+ * Upstream's policy grammar carries the macro system in the parser, not in the
+ * docs:
+ *
+ * ```
+ * def_decl = { kw_def ~ def_kind ~ ident ~ "(" ~ param_list? ~ ")" ~ "{" ~ block_inner ~ "}" ~ ";" }
+ * def_kind = { kw_def_cedar | kw_def_temporal }
+ * ```
+ *
+ * A `cedar` macro's body is a Cedar expression; a `temporal` macro's body is a
+ * temporal condition *or* a bare aggregation value (upstream's
+ * `temporal_macro_body_entry` tries `agg_expr` first, which is why
+ * `count_within` can expand into a `count …` that the call site compares).
+ *
+ * Two sigils, and they are not interchangeable. `?p` splices the call-site
+ * argument literally. `$t` is a fresh binder the macro introduces, gensym'd at
+ * every expansion. Both are legal *only* inside a macro body — upstream's
+ * well-formedness pass rejects them anywhere else — which is why they are
+ * validated here at definition time rather than at render time.
+ *
+ * The four wrappers at the bottom are the default library
+ * (`configuration/default_macros.dw`). They are calls, not operators. A caller
+ * who passes `--macros` replaces that library entirely, so a policy built on
+ * them is built on an assumption about the other end; {@link defaultMacroLibrary}
+ * exists so a project can emit the same definitions itself and stop assuming.
+ */
+
+import {
+  call,
+  interval,
+  renderCondition,
+  renderTerm,
+  sigilCondition,
+  varRef,
+  type CallNode,
+  type SigilCondition,
+  type TemporalCondition,
+  type TemporalTerm,
+  type TermText,
+} from "./temporal";
+import { windowParam, type WindowLike, type WindowParam } from "./window";
+
+/** `?w` — a value parameter, spliced from the call site. */
+const PARAM = /^\?[A-Za-z_][A-Za-z0-9_]*$/;
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Which sub-parser reads the body: Cedar's, or the temporal sub-language's. */
+export type MacroKind = "cedar" | "temporal";
+
+/** One `def <kind> <name>(<params>) { <body> };` declaration. */
+export interface MacroDefinition {
+  readonly kind: MacroKind;
+  readonly name: string;
+  /** Parameter names, each carrying the `?` sigil. */
+  readonly params: readonly string[];
+  /** Rendered body text. */
+  readonly body: string;
+  /** Emitted as `// …` lines above the definition. */
+  readonly comment?: string;
+}
+
+function assertMacroName(name: string): string {
+  if (!IDENT.test(name)) throw new Error(`dogwood: a macro name must be an identifier — got "${name}"`);
+  return name;
+}
+
+function assertParams(params: readonly string[]): readonly string[] {
+  for (const p of params) {
+    if (!PARAM.test(p)) {
+      throw new Error(`dogwood: a macro parameter carries the "?" sigil — got "${p}" (write "?${p.replace(/^\?/, "")}")`);
+    }
+  }
+  return params;
+}
+
+/**
+ * `def temporal name(?a, ?b) { … };`
+ *
+ * The body may be a condition or an aggregation term, matching upstream's
+ * `temporal_macro_body_entry`; `sum_within` is an aggregation-bodied macro and
+ * `once` is a condition-bodied one.
+ */
+export function defTemporalMacro(
+  name: string,
+  params: string[],
+  body: TemporalCondition | TemporalTerm,
+  comment?: string,
+): MacroDefinition {
+  return {
+    kind: "temporal",
+    name: assertMacroName(name),
+    params: assertParams(params),
+    body: isTermBody(body) ? renderTerm(body) : renderCondition(body),
+    comment,
+  };
+}
+
+function isTermBody(body: TemporalCondition | TemporalTerm): body is TemporalTerm {
+  return body.op === "term" || body.op === "array" || body.op === "count" || body.op === "sum";
+}
+
+/**
+ * `def cedar name(?a) { … };` — the body is Cedar expression text.
+ *
+ * Cedar's expression grammar is the policy language itself, so it stays a
+ * string here for the same reason `Cedar::Policy`'s `when` does.
+ */
+export function defCedarMacro(
+  name: string,
+  params: string[],
+  body: string,
+  comment?: string,
+): MacroDefinition {
+  return { kind: "cedar", name: assertMacroName(name), params: assertParams(params), body, comment };
+}
+
+// ── The sigils, in the three positions they appear ────────────────
+
+/**
+ * `within ?w` — the window a macro body defers to its call site.
+ *
+ * The call site supplies a bare interval (`once(1h, …)`), not a `within`
+ * clause: the keyword belongs to the operator, so it stays in the body.
+ */
+export function macroWindow(param: string): WindowParam {
+  return windowParam(param);
+}
+
+/** `?s` standing for an entire condition, spliced from the call site. */
+export function macroCondition(param: string): SigilCondition {
+  if (!PARAM.test(param)) throw new Error(`dogwood: a condition parameter carries the "?" sigil — got "${param}"`);
+  return sigilCondition(param);
+}
+
+/** `?a` / `$t` in term or binder position. */
+export function macroTerm(sigil: string): TermText {
+  if (!/^[?$][A-Za-z_][A-Za-z0-9_]*$/.test(sigil)) {
+    throw new Error(`dogwood: a macro term carries a "?" or "$" sigil — got "${sigil}"`);
+  }
+  return varRef(sigil);
+}
+
+/** One definition as `.dw` source. */
+export function renderMacroDefinition(def: MacroDefinition): string {
+  const lines: string[] = [];
+  if (def.comment) {
+    for (const line of def.comment.split("\n")) lines.push(`// ${line}`.trimEnd());
+  }
+  lines.push(`def ${def.kind} ${def.name}(${def.params.join(", ")}) {`);
+  lines.push(`    ${def.body}`);
+  lines.push("};");
+  return lines.join("\n");
+}
+
+/** A whole library — the file `--macros` points at, or a policy set's own prelude. */
+export function renderMacroLibrary(defs: readonly MacroDefinition[]): string {
+  return defs.map(renderMacroDefinition).join("\n\n") + "\n";
+}
+
+// ── The default library, as calls ─────────────────────────────────
+
+/** The macro names `configuration/default_macros.dw` ships at the pinned revision. */
+export const DEFAULT_MACRO_NAMES = ["count_within", "sum_within", "count_distinct_within", "bind"] as const;
+
+/**
+ * `count_within(?w, ?s)` — timepoints in the window at which `?s` held.
+ *
+ * A default-library call, not an operator. See this module's header.
+ */
+export function countWithin(w: WindowLike, condition: TemporalCondition): CallNode {
+  return call("count_within", [interval(w), condition]);
+}
+
+/** `sum_within(?a, ?w, ?body)` — `over` names the sum's bound variable. */
+export function sumWithin(over: string, w: WindowLike, body: TemporalCondition): CallNode {
+  return call("sum_within", [varRef(over), interval(w), body]);
+}
+
+/** `count_distinct_within(?k, ?w, ?s)` — distinct String keys `k` for which `s` held. */
+export function countDistinctWithin(key: string, w: WindowLike, condition: TemporalCondition): CallNode {
+  return call("count_distinct_within", [varRef(key), interval(w), condition]);
+}
+
+/** `bind(?n, ?A, ?B)` — names an aggregate result so it can be compared. */
+export function bind(name: string, aggregate: TemporalCondition, body: TemporalCondition): CallNode {
+  return call("bind", [varRef(name), aggregate, body]);
+}
+
+/**
+ * The default library's four definitions, verbatim from upstream's
+ * `dogwood-language/configuration/default_macros.dw` at the pinned revision.
+ *
+ * Emitting these into a project's own `macros.dw` turns an assumption about
+ * the callee's `--macros` into a file the project controls.
+ */
+export function defaultMacroLibrary(): MacroDefinition[] {
+  return [
+    {
+      kind: "temporal",
+      name: "count_within",
+      params: ["?w", "?s"],
+      body: "count for ($t: Timepoint). where (formerly within ?w (?s && tp($t)))",
+      comment: "Counts the timepoints within window `?w` at which condition `?s` held.",
+    },
+    {
+      kind: "temporal",
+      name: "sum_within",
+      params: ["?a", "?w", "?body"],
+      body: "sum ?a for (?a: Long), ($t: Timepoint). where (formerly within ?w (?body && tp($t)))",
+      comment: "Sums the numeric value `?a` over occurrences of `?body` within window `?w`.",
+    },
+    {
+      kind: "temporal",
+      name: "count_distinct_within",
+      params: ["?k", "?w", "?s"],
+      body: "count for (?k: String). where (formerly within ?w ?s)",
+      comment: "Counts the distinct key values `?k` for which `?s` held within window `?w`.",
+    },
+    {
+      kind: "temporal",
+      name: "bind",
+      params: ["?n", "?A", "?B"],
+      body: "exists (?n: Long). (?A == ?n && ?B)",
+      comment: 'A "let"-style binder: names an aggregate result `?n` and uses it in `?B`.',
+    },
+  ];
+}

package/src/dogwood/policy.test.ts

@@ -0,0 +1,94 @@
+/**
+ * The entity classes, driven the way a policy file drives them.
+ *
+ * The golden serializer test builds its entities by hand so the rendering is
+ * pinned independently of the runtime factory. This one closes the other half:
+ * that `new TemporalPolicy({ … })` produces a Declarable the cedar serializer
+ * recognises, with the props it was given.
+ */
+import { describe, test, expect } from "vitest";
+import type { Declarable } from "@intentius/chant/declarable";
+import { cedarSerializer } from "../serializer";
+import {
+  DOGWOOD_EVENT_SCHEMA_FILENAME,
+  DOGWOOD_EVENT_SCHEMA_TYPE,
+  DOGWOOD_LEXICON,
+  DOGWOOD_MACRO_FILENAME,
+  DOGWOOD_POLICY_FILENAME,
+  DOGWOOD_POLICY_TYPE,
+  TemporalEventSchema,
+  TemporalMacroLibrary,
+  TemporalPolicy,
+} from "./policy";
+import { ctx, formerly, predicate } from "./temporal";
+import { defaultEventSchema } from "./event-schema";
+import { defaultMacroLibrary } from "./macros";
+
+function files(entities: Map<string, Declarable>): Record<string, string> {
+  const out = cedarSerializer.serialize(entities);
+  return typeof out === "string" ? {} : (out.files ?? {});
+}
+
+describe("the dogwood entity classes", () => {
+  test("a TemporalPolicy is a cedar-lexicon Declarable of its own entity type", () => {
+    const policy = new TemporalPolicy({ whenTemporal: [] });
+    expect(policy.entityType).toBe(DOGWOOD_POLICY_TYPE);
+    expect(policy.lexicon).toBe(DOGWOOD_LEXICON);
+    expect(policy.kind).toBe("resource");
+  });
+
+  test("the dialect's entity types are namespaced apart from Cedar::Policy", () => {
+    expect(DOGWOOD_POLICY_TYPE).toBe("Dogwood::TemporalPolicy");
+    expect(DOGWOOD_EVENT_SCHEMA_TYPE).toBe("Dogwood::EventSchema");
+  });
+
+  test("a declared policy reaches the .dw output through the serializer", () => {
+    const entities = new Map<string, Declarable>([
+      [
+        "readAfterLogin",
+        new TemporalPolicy({
+          action: { eq: 'Drupe::Action::"Read"' },
+          principal: { is: "Drupe::OAuthUser" },
+          annotations: { owner: "platform" },
+          whenTemporal: [
+            formerly("1h", predicate('Drupe::Action::"Login"', "response", { "input.user": ctx("input.user") })),
+          ],
+        }),
+      ],
+    ]);
+
+    const text = files(entities)[DOGWOOD_POLICY_FILENAME];
+    expect(text).toContain('@id("read-after-login")');
+    expect(text).toContain('@owner("platform")');
+    expect(text).toContain("  principal is Drupe::OAuthUser,");
+    expect(text).toContain('  action == Drupe::Action::"Read",');
+    expect(text).toContain("formerly within 1h");
+  });
+
+  test("an event schema and a macro library each reach their own file", () => {
+    const entities = new Map<string, Declarable>([
+      ["events", new TemporalEventSchema({ schema: defaultEventSchema({ maxWindow: "12h" }) })],
+      ["macros", new TemporalMacroLibrary({ macros: defaultMacroLibrary() })],
+    ]);
+
+    const written = files(entities);
+    expect(written[DOGWOOD_EVENT_SCHEMA_FILENAME]).toContain("max_window = 12h");
+    expect(written[DOGWOOD_MACRO_FILENAME]).toContain("def temporal count_within(?w, ?s) {");
+  });
+
+  test("an inline macro library lands in the policy set, not a separate file", () => {
+    const entities = new Map<string, Declarable>([
+      ["macros", new TemporalMacroLibrary({ macros: defaultMacroLibrary(), inline: true })],
+      [
+        "p",
+        new TemporalPolicy({
+          whenTemporal: [formerly("1h", predicate('Ns::Action::"A"', "request"))],
+        }),
+      ],
+    ]);
+
+    const written = files(entities);
+    expect(written[DOGWOOD_MACRO_FILENAME]).toBeUndefined();
+    expect(written[DOGWOOD_POLICY_FILENAME]).toContain("def temporal count_within(?w, ?s) {");
+  });
+});