quario 0.0.1 → 0.2.0

package/lib/index.js

@@ -0,0 +1,290 @@
+/**
+ * quario — a tiny, CSP-safe report engine. A report is a JSON document; text
+ * cells are sjabloon templates and every other dynamic value is an xprsn
+ * expression, so definitions are data, never code. Nothing here turns text into
+ * runnable code, so a report renders under a strict Content Security Policy.
+ * (The safety suite greps every source file for the forbidden string-to-code
+ * constructs, so they must not appear even in a comment.)
+ *
+ * This module is the public surface of the markup-unaware core: the instance
+ * factory, the one compile behind it, and `events()`, whose stream is the seam
+ * every render target consumes. The schema traversal that compiles a report
+ * definition lives in `./plan.js`; what the two of them share lives in the
+ * siblings beside it, one seam each. See SCHEMA.md for the document shape.
+ */
+import { relocate as relocateQuery } from "padvinder";
+import { MARKING, verify } from "./license.js";
+import { err, locate } from "./locate.js";
+import { BLOCKED, NAME, record } from "./names.js";
+import { plan } from "./plan.js";
+import { aggregateValue, startRunners, withPage, withRow } from "./scope.js";
+import { opt } from "./stream.js";
+
+// The event stream's public seam, single-sourced in ./stream.js, and the
+// diagnostic predicate in ./locate.js. Re-exported here because a consumer
+// imports them from the package, not from a file inside it.
+export { breathe, display, isReportBand, text, typed, walk } from "./stream.js";
+export { isDiagnostic } from "./locate.js";
+
+/** @typedef {import("./scope.js").Scope} Scope */
+
+/** @type {(data: any) => any} */
+let inputOf = (data) => data ?? {};
+// Every aggregate is computed before any is injected, so results never depend
+// on declaration order; a sibling read inside an aggregate expression is always
+// the pre-injection null (see SCHEMA.md, deliberate asymmetries). Hence the two
+// passes: one to fold, one to write the values onto the report root.
+/** @type {(aggs: any, rows: any[], base: any, root: any) => Scope} */
+let foldAggs = (aggs, rows, base, root) => {
+  /** @type {Scope} */
+  let aggregates = {};
+  for (let [name, fold] of aggs) aggregates[name] = aggregateValue(fold, rows, base);
+  for (let [name] of aggs) root[name] = aggregates[name];
+  return aggregates;
+};
+/** @type {(band: any, perPage: (items: any) => any) => any} */
+let maybePage = (band, perPage) => band && perPage(band);
+/** @type {(pageHeader: any, pageFooter: any, perPage: (items: any) => any) => any} */
+let pageOf = (pageHeader, pageFooter, perPage) => {
+  if (!(pageHeader || pageFooter)) return null;
+  return opt(
+    {},
+    { header: maybePage(pageHeader, perPage), footer: maybePage(pageFooter, perPage) },
+  );
+};
+
+/** @type {(name: any) => void} */
+let checkTargetName = (name) => {
+  if (typeof name !== "string" || !NAME.test(name) || BLOCKED.has(name))
+    err("target.name: expected a plain identifier");
+};
+/** @type {(target: any) => void} */
+let checkTarget = (target) => {
+  // oxlint-disable-next-line no-unused-expressions
+  record(target) || err("target: expected a { name, compile } target");
+  checkTargetName(target.name);
+  // oxlint-disable-next-line no-unused-expressions
+  typeof target.compile === "function" || err("target.compile: expected a function");
+};
+/** @type {(compile: Function, stream: any, data: any) => any} */
+let runTarget = (compile, stream, data) => {
+  let render = compile(stream);
+  // oxlint-disable-next-line no-unused-expressions
+  typeof render === "function" ||
+    err("target.compile: expected compile(stream) to return a renderer");
+  return render(data);
+};
+
+/**
+ * Check a report definition without rendering it.
+ *
+ * @param {any} schema The report document.
+ * @param {Record<string, Function>} [funcs] Functions callable from expressions.
+ * @returns {string[]} All definition problems, in document order.
+ */
+export function validate(schema, funcs) {
+  return plan(schema, funcs).problems.map((problem) => problem.message);
+}
+
+// The structured problems, frozen for handing out: the traversal's own objects
+// go to exactly one caller, so freezing here cannot disturb a second reader.
+// The diagnostic stays an engine-minted error and is deliberately not frozen.
+/** @type {(problems: any[]) => readonly any[]} */
+let freezeProblems = (problems) => Object.freeze(problems.map((problem) => Object.freeze(problem)));
+
+// The per-node anchor sets, as frozen host data (CONTEXT.md, "Freeze"): which
+// anchors and group handles each compiled source reads, keyed by schema path.
+/** @type {(anchors: Map<string, Set<string>>) => any} */
+let freezeAnchors = (anchors) =>
+  Object.freeze(
+    Object.fromEntries(Array.from(anchors, ([path, set]) => [path, Object.freeze([...set])])),
+  );
+
+/**
+ * Compile a report once, stream structured render events against data many times.
+ *
+ * The render seam every target consumes — markup, spreadsheet, and document
+ * exporters all read the same stream. The instance owns the public API; this
+ * is where `report()` does its one compile. The returned stream, called with
+ * data, generates the banded walk; the data pre-pass runs eagerly per call
+ * and event emission is lazy. See SCHEMA.md ("Event stream").
+ *
+ * @param {any} schema The report document (see SCHEMA.md).
+ * @param {Record<string, Function> | undefined} funcs Functions callable from expressions.
+ * @param {{query?: {maxNodes?: number, maxDepth?: number, maxResults?: number}} | undefined}
+ *   options Host controls.
+ * @param {() => string | false} marking This render's unlicensed marking — its
+ *   wording, or false when the render is covered. A thunk, so what it answers
+ *   is this render's answer and not the compile's.
+ * @returns {{(data?: any): Generator<object, void, undefined>, names: string[],
+ *   functions: { name: string, arity: number, doc?: string }[],
+ *   paths: readonly any[]}} Event stream factory.
+ */
+function events(schema, funcs, options, marking) {
+  // The traversal collects every problem, so a thrown error is the first of the
+  // same list `validate()` would return.
+  let planned = plan(schema, funcs, options);
+  if (planned.problems.length)
+    throw planned.diagnostic() || SyntaxError(planned.problems[0].message);
+  return assemble(planned, schema, marking);
+}
+
+/**
+ * Build the event stream factory from a settled traversal — the half of the
+ * one compile that runs only when the plan carried no problems, shared by
+ * `report()`'s throwing path and the instance's `plan()`.
+ *
+ * @param {ReturnType<typeof plan>} planned The finished traversal.
+ * @param {any} schema The report document, for locating `data` faults.
+ * @param {() => string | false} marking This render's unlicensed marking.
+ * @returns {{(data?: any): Generator<object, void, undefined>, names: string[],
+ *   functions: { name: string, arity: number, doc?: string }[],
+ *   paths: readonly any[]}} Event stream factory.
+ */
+function assemble(planned, schema, marking) {
+  // Null only for a non-object schema, which is itself a collected problem.
+  // `select` and `params` come from the traversal too: it checked them, so
+  // nothing here compiles or clones a second time.
+  let {
+    select,
+    params,
+    where,
+    sort,
+    take,
+    aggs,
+    running,
+    style,
+    header,
+    empty,
+    columns,
+    footer,
+    band,
+    pageHeader,
+    pageFooter,
+  } = /** @type {NonNullable<typeof planned.compiled>} */ (planned.compiled);
+
+  // The runner's own faults are located per render: a budget is spent while
+  // traversing this document, not while compiling the path.
+  /** @type {(data: any) => any[]} */
+  let runSelect = (data) => {
+    try {
+      return select(data);
+    } catch (error) {
+      locate("data", schema.data, error, select.isDiagnostic(error) && relocateQuery);
+    }
+  };
+
+  /** @type {(data: any) => Generator<any>} */
+  let emit = (data) => {
+    let root = Object.create(null);
+    root.params = params;
+    root.input = inputOf(data);
+    let base = Object.create(null);
+    base["$"] = root;
+    // The eager pre-pass: select → filter → report sort → report take →
+    // aggregates (over the rows that remain). It cannot be lazy because the
+    // report header may interpolate report aggregates; only the banded walk
+    // itself streams.
+    let rows = runSelect(root.input);
+    if (where) rows = rows.filter((row) => where(withRow(base, row)));
+    if (sort) rows = sort(rows, base);
+    if (take != null) rows = rows.slice(0, take);
+    let aggregates = foldAggs(aggs, rows, base, root);
+    // The report's runners, started per render like everything else here.
+    let runners = startRunners(running);
+    // Per-render page band closures: a paginated target calls them once per
+    // page with `{ number, total }` (1-based) and receives resolved item
+    // events. Unpaginated targets ignore the field.
+    /** @type {(items: any) => (page: any) => any[]} */
+    let perPage = (items) => (page) => [...items(withPage(base, page))];
+    let page = pageOf(pageHeader, pageFooter, perPage);
+    // The banded walk itself, over everything the pre-pass settled above. The
+    // marking rides on the opening event — its wording, so that a target owns
+    // only where it goes. Read as the event is yielded, so a render drained
+    // before verification settles counts as unlicensed (SCHEMA.md, "License
+    // keys").
+    /** @type {() => Generator<object, void, undefined>} */
+    function* walked() {
+      yield opt(
+        { type: "report-start", params: root.params, aggregates },
+        { page, columns, style: style(base), marking: marking() },
+      );
+      yield* header(base);
+      if (!rows.length && empty) yield* empty(base);
+      else yield* band(rows, base, runners);
+      yield* footer(base);
+      yield { type: "report-end" };
+    }
+    return walked();
+  };
+  return Object.assign(emit, {
+    names: Array.from(planned.names),
+    // Already signature objects — plan() paired each called name with its
+    // registry metadata through xprsn's signatures().
+    functions: planned.functions,
+    paths: select.paths,
+  });
+}
+
+/** @typedef {import("./license.js").LicenseInfo} LicenseInfo */
+
+/**
+ * Create a configured quario instance: the host-level options — license key,
+ * query budgets. The key is verified once, here, and `license` settles with
+ * the result. `report()` compiles a definition once and every target renders
+ * from that one compiled stream through `render(target, data)`. See SCHEMA.md
+ * ("Instances and targets").
+ *
+ * @param {{query?: {maxNodes?: number, maxDepth?: number, maxResults?: number},
+ *   license?: string, trust?: {publicKey?: string, release?: string}}} [options]
+ *   Host configuration. `trust` is internal, not API — see ./license.js.
+ * @returns {{license: Promise<LicenseInfo>,
+ *   report: (schema: any, funcs?: Record<string, Function>) => any,
+ *   plan: (schema: any, funcs?: Record<string, Function>) => any}} The instance.
+ */
+export function quario(options) {
+  let { licensed, settled } = verify(options?.license, options?.trust);
+  // The wording is the instance's, where the key is; the stream is what
+  // states it, so nothing wraps a compiled stream to reach its first event.
+  /** @type {() => string | false} */
+  let marking = () => !licensed() && MARKING;
+  // The compiled report around a stream: what `report()` returns, and what
+  // `plan()` carries when the document had no problems.
+  /** @type {(stream: ReturnType<typeof events>) => any} */
+  let wrap = (stream) => ({
+    stream,
+    names: stream.names,
+    functions: stream.functions,
+    paths: stream.paths,
+    // Every render awaits verification before the target pulls its first
+    // event, so no render is marked merely for racing the check and no
+    // target carries that concern itself. Target shape problems throw
+    // synchronously — definition errors, like everything else — while a
+    // render is always a promise, even over a synchronous renderer.
+    render: (/** @type {any} */ target, /** @type {any} */ data) => {
+      checkTarget(target);
+      return settled.then(() => runTarget(target.compile, stream, data));
+    },
+  });
+  return {
+    license: settled,
+    /** @type {(schema: any, funcs?: Record<string, Function>) => any} */
+    report(schema, funcs) {
+      return wrap(events(schema, funcs, options, marking));
+    },
+    // The plan (CONTEXT.md): both readings of the one descent, kept.
+    // `report()` and `validate()` name what a caller wanted from it; this
+    // hands over the whole thing — the compiled report (null while the
+    // document has problems), every problem structurally, and the per-node
+    // anchor sets — so an editing host pays one traversal per edit, not two.
+    /** @type {(schema: any, funcs?: Record<string, Function>) => any} */
+    plan(schema, funcs) {
+      let planned = plan(schema, funcs, options);
+      return {
+        report: planned.problems.length ? null : wrap(assemble(planned, schema, marking)),
+        problems: freezeProblems(planned.problems),
+        anchors: freezeAnchors(planned.anchors),
+      };
+    },
+  };
+}

package/lib/license.js

@@ -0,0 +1,141 @@
+// License keys (LICENSE section 6): offline verification, scoped to one
+// instance, and the wording of the marking an unlicensed render carries.
+// `quario()` calls `verify` once and closes over the result: no mutable state
+// lives at module scope, so nothing one instance does can reach another.
+// Verification is entirely offline, and asynchronous only because WebCrypto
+// is.
+
+// Release date of this version, written into the version commit by
+// release-please (`x-release-please-date`). Both constants keep the `let`
+// spelling that `scripts/license/keygen.mjs` matches on, though nothing
+// reassigns them. A key is valid for every version released inside its window
+// (LICENSE section 7), so validity compares ISO date strings and never reads
+// a clock — accepted output stays accepted.
+let RELEASE = "2026-09-01"; // x-release-please-date
+// The verifying half of the signing pair: the 65-byte uncompressed P-256
+// point, base64url. The private half never enters the repo;
+// scripts/license/sign.mjs mints keys against it.
+let PUBKEY =
+  "BEyXC0sH4pDoL-gGxLTqHguWi38WK2v7OrAfNvK8_4Ou8yLhcKgX5dzCoj1ojj6ez0B1cwMDPfejthqEQ4wZGjM";
+
+// The marking wording, stated once for the whole engine and carried to every
+// target on `report-start` (SCHEMA.md, "License keys"): the targets own where
+// it goes, never what it says. Keep it encodable by WinAnsi — the PDF target
+// draws it through a base-14 face, and the em dash is the one character here
+// that had to be checked. The assertion that would catch a bad one lives in
+// that target's suite (`packages/pdf/test/pdf.test.js`), not this package's.
+export let MARKING = "Unlicensed evaluation — getquario.com";
+
+let ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+let DECODER = new TextDecoder();
+
+/** @type {(text: string) => Uint8Array<ArrayBuffer>} */
+let unb64 = (text) => {
+  let bin = atob(text.replace(/-/g, "+").replace(/_/g, "/"));
+  let bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bytes.length; i++) bytes[i] = bin.charCodeAt(i);
+  return bytes;
+};
+
+/** @type {(obj: any, name: string, fallback: string) => string} */
+let field = (obj, name, fallback) => (obj && obj[name]) || fallback;
+
+/** @type {(key: string) => [string, Uint8Array<ArrayBuffer>]} */
+let parseKey = (key) => {
+  if (!key.startsWith("quario_")) throw Error("not a quario_ key");
+  let [body, signature, extra] = key.slice(7).split(".");
+  if (!signature || extra !== undefined) throw Error("expected <payload>.<signature>");
+  return [signature, unb64(body)];
+};
+
+/** @type {(value: any) => boolean} */
+let isStr = (value) => typeof value === "string";
+
+/** @type {(payload: any) => void} */
+let checkPayload = (payload) => {
+  if (!payload || !isStr(payload.id) || !isStr(payload.name))
+    throw Error("payload is missing id/name");
+};
+
+/** @type {(payload: any) => void} */
+let checkWindow = (payload) => {
+  if (!payload.id.startsWith("1-")) throw Error("unsupported key format version");
+  if (!ISO_DATE.test(payload.from) || !ISO_DATE.test(payload.to))
+    throw Error("payload window is not a pair of ISO dates");
+};
+
+/** @type {() => Crypto["subtle"]} */
+let cryptoSubtle = () => {
+  let subtle = globalThis.crypto && globalThis.crypto.subtle;
+  if (!subtle) throw Error("crypto.subtle is unavailable (secure contexts only)");
+  return subtle;
+};
+
+/** @type {(subtle: Crypto["subtle"], pubkey: string, signature: string, bytes: BufferSource) => Promise<void>} */
+let importAndVerify = async (subtle, pubkey, signature, bytes) => {
+  let curve = { name: "ECDSA", namedCurve: "P-256" };
+  let pub = await subtle.importKey("raw", unb64(pubkey), curve, false, ["verify"]);
+  let hash = { name: "ECDSA", hash: "SHA-256" };
+  if (!(await subtle.verify(hash, pub, unb64(signature), bytes)))
+    throw Error("signature does not match");
+};
+
+/** @type {(payload: any, release: string) => void} */
+let checkCover = (payload, release) => {
+  if (!(payload.from <= release && release <= payload.to))
+    throw Error("window does not cover the " + release + " release");
+};
+
+/** @type {(error: unknown) => string} */
+let failMsg = (error) => (error instanceof Error ? error.message : String(error));
+
+/** @typedef {{ licensed: boolean, licensee?: string, id?: string }} LicenseInfo */
+
+/**
+ * Verify one instance's license key.
+ *
+ * `settled` is the instance's public `license` promise and the gate every
+ * render awaits; `licensed()` is the same answer readable synchronously, for
+ * the marking on the opening event. A render drained before settlement reads
+ * `false` and is marked — the shipped targets await settlement first. Every
+ * failure (including a missing `crypto.subtle` outside secure contexts)
+ * soft-fails to marked output and warns once; the feature set never gates
+ * (LICENSE section 6).
+ *
+ * @param {string | undefined} key The instance's `license` option.
+ * @param {{publicKey?: string, release?: string}} [trust] What this instance
+ *   verifies against, defaulting to the shipped key and release date. Internal
+ *   — a test seam, not API: the production private key never enters the repo,
+ *   so suites verify against freshly generated pairs.
+ * @returns {{licensed: () => boolean, settled: Promise<LicenseInfo>}}
+ */
+export let verify = (key, trust) => {
+  let pubkey = field(trust, "publicKey", PUBKEY);
+  let release = field(trust, "release", RELEASE);
+  let valid = false;
+  let settled = (async () => {
+    if (!key) return { licensed: false };
+    // Every throw below is caught here and turned into marked output, so none
+    // of them is a definition error — the engine's thrower means the opposite.
+    try {
+      let [signature, bytes] = parseKey(key);
+      let payload = JSON.parse(DECODER.decode(bytes));
+      checkPayload(payload);
+      checkWindow(payload);
+      await importAndVerify(cryptoSubtle(), pubkey, signature, bytes);
+      checkCover(payload, release);
+      // Set before this promise resolves: `render` awaits `settled`, so a
+      // verified instance must never still read as unlicensed afterwards.
+      valid = true;
+      return { licensed: true, licensee: payload.name, id: payload.id };
+    } catch (error) {
+      console.warn(
+        "quario: license key rejected (" +
+          failMsg(error) +
+          ") - output will be marked, see LICENSE section 6",
+      );
+      return { licensed: false };
+    }
+  })();
+  return { licensed: () => valid, settled };
+};

package/lib/locate.js

@@ -0,0 +1,67 @@
+/**
+ * Located diagnostics: where quario re-throws an engine's error with the
+ * band/item path and offending source attached.
+ */
+import { isDiagnostic as isQueryDiagnostic } from "padvinder";
+import { isDiagnostic as isXprsnDiagnostic } from "xprsn";
+import { isDiagnostic as isTemplateDiagnostic } from "sjabloon";
+
+/**
+ * True when an error is one of the stack's authenticated diagnostics — thrown
+ * by an engine (xprsn, sjabloon, or padvinder) directly, or re-thrown by
+ * quario through that engine's `relocate` — i.e. it safely carries the
+ * optional `code`/`start`/`end`/`limit`/`actual`/`blocks` metadata.
+ * Authentication is by identity: an error merely shaped like a diagnostic does
+ * not pass, and a located copy passes because the engine that minted the
+ * original made the copy.
+ *
+ * @param {unknown} error The caught value.
+ * @returns {boolean} Whether `error` is a located diagnostic.
+ */
+export function isDiagnostic(error) {
+  return isXprsnDiagnostic(error) || isTemplateDiagnostic(error) || isQueryDiagnostic(error);
+}
+
+/** @type {(msg: string) => never} */
+export let err = (msg) => {
+  throw Error(msg);
+};
+
+// How a located error remembers where it happened as data: the traversal reads
+// this to build a structured problem, so nothing parses a message back apart.
+// A symbol, so the located copy's public shape stays exactly the engine's.
+export let LOCATION = Symbol("quario.location");
+
+/** @type {(path: string, msg: string) => never} */
+export let fault = (path, msg) => {
+  throw Object.assign(Error(path + ": " + msg), { [LOCATION]: { path } });
+};
+
+/**
+ * Re-throw `error` located at `path`, with `src` — the offending author
+ * source — in the message.
+ *
+ * A diagnostic is relocated by the engine that authenticated it, so the copy
+ * carries every field that engine puts on it and passes that engine's own
+ * guard (ADR 0024). `relocate` is that engine's relocation — and a verdict as
+ * much as a callback: the call site holds the guard, because two of them are
+ * scoped to one evaluator rather than to the module, and `false` is its way of
+ * saying the guard rejected this error. Anything else — a host function's
+ * throw, quario's own verdict on image bytes — is wrapped as a plain error
+ * with no metadata at all.
+ *
+ * @type {(path: string, src: any, error: any, relocate?: false | ((e: any, o: { prefix: string, offset: number }) => any), offset?: number) => never}
+ */
+export let locate = (path, src, error, relocate, offset = 0) => {
+  let prefix = (src === undefined ? path : path + " [" + String(src) + "]") + ": ";
+  let where = { [LOCATION]: { path, source: src } };
+  if (relocate) throw Object.assign(relocate(error, { prefix, offset }), where);
+  // A host throw keeps its own class — the located error is the same kind of
+  // failure, named where it happened — and gains no diagnostic metadata.
+  throw Object.assign(
+    error instanceof Error
+      ? new /** @type {any} */ (error.constructor)(prefix + error.message)
+      : Error(prefix + String(error)),
+    where,
+  );
+};

package/lib/names.js

@@ -0,0 +1,19 @@
+/**
+ * The engine's closed name vocabulary: what counts as an object worth
+ * descending into, what an author may name, and the anchors the engine binds
+ * for itself. The traversal checks a report definition against it, and the
+ * instance checks a target's `{ name, compile }` shape against the same rules —
+ * one spelling of "a plain identifier", wherever a name is offered.
+ */
+/** @type {(value: any) => boolean} */
+export let record = (value) => value && typeof value === "object" && !Array.isArray(value);
+export let NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// The anchors quario actually binds at evaluation time.
+export let ANCHORS = ["@", "$", "run", "loop", "page"];
+// Refused as group handle names: the anchors above plus the namespace held for
+// future ones. Engine-provided values arrive on a new anchor rather than as new
+// fields on `$` or a group handle (SCHEMA.md, "Stability"), so protecting the
+// anchor namespace is the whole of what the authoring surface has to reserve --
+// aggregate and run names stay the author's, `count` and `index` included.
+export let RESERVED = new Set([...ANCHORS, "report", "table", "data", "meta"]);
+export let BLOCKED = new Set(["__proto__", "constructor", "prototype"]);