@intentius/chant 0.124.13 → 0.124.15

package/dist/toml.js

@@ -0,0 +1,428 @@
+/**
+ * Lightweight TOML parser (#446).
+ *
+ * Written for the audit engine's spike: is there a pure, dependency-free way
+ * to parse a config format the engine can't read today? TOML fits — it is a
+ * fully-specified, static (no macros/interpolation/imports) grammar, so a
+ * hand-rolled tokenizer + recursive-descent parser covers it without any
+ * runtime surface a Workers sandbox would reject (no `eval`, no native
+ * modules, no filesystem/network).
+ *
+ * Covers the subset of TOML v1.0 that real-world deploy configs
+ * (`wrangler.toml`, `Cargo.toml`, `pyproject.toml`, `netlify.toml`) actually
+ * use: basic/literal strings (single-line), integers, floats, booleans,
+ * arrays (including multi-line), inline tables, dotted keys, standard tables
+ * (`[a.b]`), and arrays of tables (`[[a.b]]`).
+ *
+ * Deliberately NOT a full spec implementation:
+ *  - Multi-line strings (`"""..."""`, `'''...'''`) are read as a single
+ *    opaque string body (no line-ending backslash trimming); good enough to
+ *    not crash, not spec-perfect for continuation whitespace.
+ *  - Dates/times are returned as their raw source text (a string), not a
+ *    `Date` — none of the checks built on this parser need calendar math.
+ *  - A dotted-key path element must be a bare word or a plain quoted string;
+ *    mixing exotic key shapes mid-path is not supported.
+ * These gaps only matter for exotic TOML; they don't affect the shapes the
+ * audit checks read (`[vars]`, `[[kv_namespaces]]`, `[env.NAME]`, …).
+ */
+export class TomlParseError extends Error {
+}
+const STOP_CHARS = new Set([" ", "\t", "\r", "\n", "[", "]", "{", "}", "=", ",", ".", "#", '"', "'"]);
+/** Same stop set, minus `.` — used for numeric-looking tokens so `3.14` lexes whole. */
+const NUM_STOP_CHARS = new Set([...STOP_CHARS].filter((ch) => ch !== "."));
+/** Read a quoted string (basic `"..."`/`'...'` or multi-line `"""..."""`/`'''...'''`) starting at `i` (the opening quote). */
+function readString(s, i) {
+    const q = s[i];
+    const literal = q === "'";
+    const triple = s[i + 1] === q && s[i + 2] === q;
+    const quoteLen = triple ? 3 : 1;
+    let j = i + quoteLen;
+    // A newline immediately after an opening multi-line delimiter is trimmed (TOML spec).
+    if (triple && s[j] === "\r")
+        j++;
+    if (triple && s[j] === "\n")
+        j++;
+    let out = "";
+    while (true) {
+        if (j >= s.length)
+            throw new TomlParseError(`Unterminated string starting at offset ${i}`);
+        if (s.startsWith(q.repeat(quoteLen), j)) {
+            return { value: out, next: j + quoteLen };
+        }
+        const c = s[j];
+        if (!triple && (c === "\n" || c === "\r")) {
+            throw new TomlParseError(`Unterminated single-line string starting at offset ${i}`);
+        }
+        if (literal) {
+            out += c;
+            j++;
+            continue;
+        }
+        if (c === "\\") {
+            const esc = s[j + 1];
+            if (triple && (esc === "\n" || esc === "\r" || esc === " " || esc === "\t")) {
+                // Line-ending backslash: consume the backslash, trailing whitespace, the
+                // newline, and all leading whitespace on the next line (folds away).
+                let k = j + 1;
+                while (s[k] === " " || s[k] === "\t")
+                    k++;
+                if (s[k] === "\r")
+                    k++;
+                if (s[k] === "\n")
+                    k++;
+                while (s[k] === " " || s[k] === "\t" || s[k] === "\n" || s[k] === "\r")
+                    k++;
+                j = k;
+                continue;
+            }
+            const simple = { n: "\n", t: "\t", r: "\r", b: "\b", f: "\f", '"': '"', "\\": "\\" };
+            if (esc !== undefined && esc in simple) {
+                out += simple[esc];
+                j += 2;
+                continue;
+            }
+            if (esc === "u" || esc === "U") {
+                const width = esc === "u" ? 4 : 8;
+                const hex = s.slice(j + 2, j + 2 + width);
+                if (hex.length < width || !/^[0-9a-fA-F]+$/.test(hex)) {
+                    throw new TomlParseError(`Invalid unicode escape at offset ${j}`);
+                }
+                out += String.fromCodePoint(parseInt(hex, 16));
+                j += 2 + width;
+                continue;
+            }
+            throw new TomlParseError(`Invalid escape \\${esc} at offset ${j}`);
+        }
+        out += c;
+        j++;
+    }
+}
+function lex(input) {
+    const s = input.replace(/\r\n/g, "\n");
+    const tokens = [];
+    let i = 0;
+    let atLineStart = true;
+    const n = s.length;
+    while (i < n) {
+        const c = s[i];
+        if (c === "\n") {
+            tokens.push({ t: "nl" });
+            i++;
+            atLineStart = true;
+            continue;
+        }
+        if (c === " " || c === "\t") {
+            i++;
+            continue;
+        }
+        if (c === "#") {
+            while (i < n && s[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (c === "[") {
+            if (atLineStart && s[i + 1] === "[") {
+                tokens.push({ t: "[[" });
+                i += 2;
+            }
+            else {
+                tokens.push({ t: "[" });
+                i += 1;
+            }
+            atLineStart = false;
+            continue;
+        }
+        if (c === "]") {
+            if (s[i + 1] === "]" && tokens.length > 0 && hasUnmatchedArrayTableOpen(tokens)) {
+                tokens.push({ t: "]]" });
+                i += 2;
+            }
+            else {
+                tokens.push({ t: "]" });
+                i += 1;
+            }
+            atLineStart = false;
+            continue;
+        }
+        if (c === "{") {
+            tokens.push({ t: "{" });
+            i++;
+            atLineStart = false;
+            continue;
+        }
+        if (c === "}") {
+            tokens.push({ t: "}" });
+            i++;
+            atLineStart = false;
+            continue;
+        }
+        if (c === "=") {
+            tokens.push({ t: "=" });
+            i++;
+            atLineStart = false;
+            continue;
+        }
+        if (c === ",") {
+            tokens.push({ t: "," });
+            i++;
+            atLineStart = false;
+            continue;
+        }
+        if (c === ".") {
+            tokens.push({ t: "." });
+            i++;
+            atLineStart = false;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            const { value, next } = readString(s, i);
+            tokens.push({ t: "str", v: value });
+            i = next;
+            atLineStart = false;
+            continue;
+        }
+        // A dotted key (`a.b`) uses `.` as a segment separator, so a plain
+        // bareword stops there. A value that looks numeric (starts with a digit,
+        // or +/- followed by one) needs `.` to stay IN the token so floats
+        // (`3.14`) and dates (`2024-01-01`, already dash-based) lex as one piece.
+        const numericStart = /[0-9]/.test(c) || ((c === "+" || c === "-") && /[0-9]/.test(s[i + 1] ?? ""));
+        const stopSet = numericStart ? NUM_STOP_CHARS : STOP_CHARS;
+        let j = i;
+        while (j < n && !stopSet.has(s[j]))
+            j++;
+        if (j === i)
+            throw new TomlParseError(`Unexpected character ${JSON.stringify(c)} at offset ${i}`);
+        tokens.push({ t: "bare", v: s.slice(i, j) });
+        i = j;
+        atLineStart = false;
+    }
+    tokens.push({ t: "eof" });
+    return tokens;
+}
+/** Is the most recent unmatched `[[` in `tokens` still open (no `]]` seen since)? Used only to decide whether a trailing `]]` closes an array-of-tables header vs. two array closes. */
+function hasUnmatchedArrayTableOpen(tokens) {
+    let depth = 0;
+    for (const tok of tokens) {
+        if (tok.t === "[[")
+            depth++;
+        else if (tok.t === "]]")
+            depth--;
+    }
+    return depth > 0;
+}
+class Cursor {
+    constructor(tokens, pos = 0) {
+        this.tokens = tokens;
+        this.pos = pos;
+    }
+    peek() { return this.tokens[this.pos]; }
+    next() { return this.tokens[this.pos++]; }
+    skipNl() { while (this.peek().t === "nl")
+        this.pos++; }
+    expect(t) {
+        const tok = this.next();
+        if (tok.t !== t)
+            throw new TomlParseError(`Expected ${t}, got ${tok.t}`);
+        return tok;
+    }
+}
+/** Read a dotted key path (`a.b.c`) — bare words or quoted strings joined by `.`. */
+function readPath(c) {
+    const parts = [];
+    while (true) {
+        const tok = c.next();
+        if (tok.t === "bare")
+            parts.push(tok.v);
+        else if (tok.t === "str")
+            parts.push(tok.v);
+        else
+            throw new TomlParseError(`Expected a key segment, got ${tok.t}`);
+        if (c.peek().t === ".") {
+            c.next();
+            continue;
+        }
+        break;
+    }
+    return parts;
+}
+const INT_RE = /^[+-]?(0|[1-9](_?\d)*)$/;
+const HEX_RE = /^0x[0-9A-Fa-f](_?[0-9A-Fa-f])*$/;
+const OCT_RE = /^0o[0-7](_?[0-7])*$/;
+const BIN_RE = /^0b[01](_?[01])*$/;
+const FLOAT_RE = /^[+-]?(\d(_?\d)*)(\.\d(_?\d)*)?([eE][+-]?\d(_?\d)*)?$/;
+/** Coerce a bare value token to boolean / number / raw string (dates fall through as strings). */
+function coerceBare(raw) {
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    if (raw === "nan" || raw === "+nan" || raw === "-nan")
+        return NaN;
+    if (raw === "inf" || raw === "+inf")
+        return Infinity;
+    if (raw === "-inf")
+        return -Infinity;
+    if (HEX_RE.test(raw))
+        return parseInt(raw.replace(/_/g, ""), 16);
+    if (OCT_RE.test(raw))
+        return parseInt(raw.replace(/_/g, "").slice(2), 8);
+    if (BIN_RE.test(raw))
+        return parseInt(raw.replace(/_/g, "").slice(2), 2);
+    if (INT_RE.test(raw))
+        return parseInt(raw.replace(/_/g, ""), 10);
+    if (FLOAT_RE.test(raw) && /[.eE]/.test(raw))
+        return parseFloat(raw.replace(/_/g, ""));
+    // Not a recognized scalar shape — likely a date/time or something exotic.
+    // Kept as its raw source text rather than failing the whole document.
+    return raw;
+}
+function parseValue(c) {
+    const tok = c.peek();
+    if (tok.t === "str") {
+        c.next();
+        return tok.v;
+    }
+    if (tok.t === "bare") {
+        c.next();
+        return coerceBare(tok.v);
+    }
+    if (tok.t === "[")
+        return parseArray(c);
+    if (tok.t === "{")
+        return parseInlineTable(c);
+    throw new TomlParseError(`Unexpected token ${tok.t} where a value was expected`);
+}
+function parseArray(c) {
+    c.expect("[");
+    const out = [];
+    c.skipNl();
+    while (c.peek().t !== "]") {
+        out.push(parseValue(c));
+        c.skipNl();
+        if (c.peek().t === ",") {
+            c.next();
+            c.skipNl();
+            continue;
+        }
+        break;
+    }
+    c.skipNl();
+    c.expect("]");
+    return out;
+}
+function assignDotted(target, path, value) {
+    let cur = target;
+    for (let i = 0; i < path.length - 1; i++) {
+        const seg = path[i];
+        const existing = cur[seg];
+        if (existing && typeof existing === "object" && !Array.isArray(existing)) {
+            cur = existing;
+        }
+        else {
+            const created = {};
+            cur[seg] = created;
+            cur = created;
+        }
+    }
+    cur[path[path.length - 1]] = value;
+}
+function parseInlineTable(c) {
+    c.expect("{");
+    const out = {};
+    // Inline tables are single-line per spec, but stray newlines are tolerated
+    // here rather than rejected — the audit must never crash on odd input.
+    c.skipNl();
+    while (c.peek().t !== "}") {
+        const path = readPath(c);
+        c.expect("=");
+        const value = parseValue(c);
+        assignDotted(out, path, value);
+        c.skipNl();
+        if (c.peek().t === ",") {
+            c.next();
+            c.skipNl();
+            continue;
+        }
+        break;
+    }
+    c.skipNl();
+    c.expect("}");
+    return out;
+}
+/** Navigate/create a nested table (or the last element of a nested array-of-tables) at `path`, per TOML header semantics. */
+function navigateTable(root, path) {
+    let cur = root;
+    for (const seg of path) {
+        const existing = cur[seg];
+        if (existing === undefined) {
+            const created = {};
+            cur[seg] = created;
+            cur = created;
+        }
+        else if (Array.isArray(existing)) {
+            const last = existing[existing.length - 1];
+            if (!last || typeof last !== "object")
+                throw new TomlParseError(`Cannot navigate into array segment "${seg}"`);
+            cur = last;
+        }
+        else if (typeof existing === "object") {
+            cur = existing;
+        }
+        else {
+            throw new TomlParseError(`Key "${seg}" is already a scalar value`);
+        }
+    }
+    return cur;
+}
+function navigateArrayTable(root, path) {
+    const parent = navigateTable(root, path.slice(0, -1));
+    const last = path[path.length - 1];
+    const existing = parent[last];
+    const arr = Array.isArray(existing) ? existing : [];
+    if (!Array.isArray(existing))
+        parent[last] = arr;
+    const entry = {};
+    arr.push(entry);
+    return entry;
+}
+/**
+ * Parse a TOML document into a plain nested object. Throws {@link TomlParseError}
+ * on malformed input — callers that scan arbitrary repo files should wrap the
+ * call in a try/catch (matching the rest of the audit engine's tolerance for
+ * unparseable content).
+ */
+export function parseTOML(input) {
+    const tokens = lex(input);
+    const c = new Cursor(tokens);
+    const root = {};
+    let current = root;
+    c.skipNl();
+    while (c.peek().t !== "eof") {
+        const tok = c.peek();
+        if (tok.t === "[") {
+            c.next();
+            const path = readPath(c);
+            c.expect("]");
+            current = navigateTable(root, path);
+        }
+        else if (tok.t === "[[") {
+            c.next();
+            const path = readPath(c);
+            c.expect("]]");
+            current = navigateArrayTable(root, path);
+        }
+        else {
+            const path = readPath(c);
+            c.expect("=");
+            const value = parseValue(c);
+            assignDotted(current, path, value);
+        }
+        const end = c.next();
+        if (end.t === "eof")
+            break;
+        if (end.t !== "nl")
+            throw new TomlParseError(`Expected end of line, got ${end.t}`);
+        c.skipNl();
+    }
+    return root;
+}

package/dist/ts-loader.d.ts

@@ -0,0 +1,46 @@
+/**
+ * #3878 — TypeScript loading for the compiled CLI.
+ *
+ * An installed chant runs `dist/cli/main.js` with plain `node`, so chant's own
+ * modules need no loader. Everything else chant imports at run time still can
+ * be TypeScript: a project's `chant.config.ts` and source files, `*.op.ts`,
+ * policies and lint rules, and the lexicon packages, which ship `src/*.ts`.
+ * {@link ensureTypeScriptLoader} registers tsx for those, the first time one of
+ * them is about to be imported, so a command that imports none (`--version`,
+ * `run wave` on a project with no `chant.config.ts`) never loads tsx at all.
+ *
+ * {@link installCompiledCli} also points every resolution of chant's own
+ * source at the compiled file next to it. A lexicon or project file imports
+ * `@intentius/chant`, and the package exports resolve that to `src/*.ts`;
+ * without the redirect that import would load a second copy of core,
+ * transpiled, beside the one the CLI runs, with its own registries and
+ * classes.
+ *
+ * Run from source (the repository's `bin/chant` through tsx, vitest), this
+ * module is itself TypeScript, the TypeScript loader is already there, and
+ * both functions do nothing.
+ */
+/**
+ * Called once by the CLI's `main()`. Compiled, it records that TypeScript
+ * loads lazily and installs the `src/*.ts` to `dist/*.js` redirect; from
+ * source it does nothing.
+ */
+export declare function installCompiledCli(): void;
+/**
+ * Register tsx for the ESM and CommonJS loaders, once, before importing
+ * anything that may be TypeScript. A no-op from source, where tsx (or vitest)
+ * is already loading chant itself. Returns whether the compiled CLI's tsx
+ * registration covers this process, so a caller that registers its own
+ * CommonJS hook from source knows not to add a second one.
+ */
+export declare function ensureTypeScriptLoader(): boolean;
+/**
+ * The source directory for a module of chant's own: `dirname` of `moduleUrl`
+ * from source, and the matching directory under `<package>/src` when the
+ * module runs from `<package>/dist`. The sandbox drivers hand chant's own
+ * modules to esbuild by path, and must name the TypeScript source the
+ * project's own `@intentius/chant/*` imports resolve to. String arithmetic
+ * only: no filesystem access, so it is safe inside a sandboxed child.
+ */
+export declare function chantSourceDir(moduleUrl: string): string;
+//# sourceMappingURL=ts-loader.d.ts.map

package/dist/ts-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ts-loader.d.ts","sourceRoot":"","sources":["../src/ts-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAoCH;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAwBzC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAShD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOxD"}

package/dist/ts-loader.js

@@ -0,0 +1,103 @@
+/**
+ * #3878 — TypeScript loading for the compiled CLI.
+ *
+ * An installed chant runs `dist/cli/main.js` with plain `node`, so chant's own
+ * modules need no loader. Everything else chant imports at run time still can
+ * be TypeScript: a project's `chant.config.ts` and source files, `*.op.ts`,
+ * policies and lint rules, and the lexicon packages, which ship `src/*.ts`.
+ * {@link ensureTypeScriptLoader} registers tsx for those, the first time one of
+ * them is about to be imported, so a command that imports none (`--version`,
+ * `run wave` on a project with no `chant.config.ts`) never loads tsx at all.
+ *
+ * {@link installCompiledCli} also points every resolution of chant's own
+ * source at the compiled file next to it. A lexicon or project file imports
+ * `@intentius/chant`, and the package exports resolve that to `src/*.ts`;
+ * without the redirect that import would load a second copy of core,
+ * transpiled, beside the one the CLI runs, with its own registries and
+ * classes.
+ *
+ * Run from source (the repository's `bin/chant` through tsx, vitest), this
+ * module is itself TypeScript, the TypeScript loader is already there, and
+ * both functions do nothing.
+ */
+import { existsSync } from "node:fs";
+import * as nodeModule from "node:module";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const { createRequire, registerHooks } = nodeModule;
+const STATE = Symbol.for("chant.compiledCli");
+function compiledState() {
+    return globalThis[STATE];
+}
+/** True when this module runs as compiled JavaScript, from `<package>/dist`. */
+function runsCompiled() {
+    return import.meta.url.endsWith(".js");
+}
+/**
+ * Called once by the CLI's `main()`. Compiled, it records that TypeScript
+ * loads lazily and installs the `src/*.ts` to `dist/*.js` redirect; from
+ * source it does nothing.
+ */
+export function installCompiledCli() {
+    if (!runsCompiled() || compiledState())
+        return;
+    globalThis[STATE] = { tsx: false };
+    const distDir = dirname(fileURLToPath(import.meta.url));
+    const srcUrl = pathToFileURL(join(dirname(distDir), "src") + sep).href;
+    const distUrl = pathToFileURL(distDir + sep).href;
+    const compiled = new Map();
+    registerHooks({
+        resolve(specifier, context, nextResolve) {
+            const result = nextResolve(specifier, context);
+            if (!result.url.startsWith(srcUrl))
+                return result;
+            const path = result.url.slice(srcUrl.length).replace(/[?#].*$/, "");
+            if (!path.endsWith(".ts") || path.endsWith(".d.ts"))
+                return result;
+            let target = compiled.get(path);
+            if (target === undefined) {
+                const js = distUrl + path.slice(0, -3) + ".js";
+                target = existsSync(fileURLToPath(js)) ? js : null;
+                compiled.set(path, target);
+            }
+            return target === null ? result : { ...result, url: target, format: "module" };
+        },
+    });
+}
+/**
+ * Register tsx for the ESM and CommonJS loaders, once, before importing
+ * anything that may be TypeScript. A no-op from source, where tsx (or vitest)
+ * is already loading chant itself. Returns whether the compiled CLI's tsx
+ * registration covers this process, so a caller that registers its own
+ * CommonJS hook from source knows not to add a second one.
+ */
+export function ensureTypeScriptLoader() {
+    const state = compiledState();
+    if (!state)
+        return false;
+    if (state.tsx)
+        return true;
+    state.tsx = true;
+    const require = createRequire(import.meta.url);
+    require("tsx/cjs/api").register();
+    require("tsx/esm/api").register();
+    return true;
+}
+/**
+ * The source directory for a module of chant's own: `dirname` of `moduleUrl`
+ * from source, and the matching directory under `<package>/src` when the
+ * module runs from `<package>/dist`. The sandbox drivers hand chant's own
+ * modules to esbuild by path, and must name the TypeScript source the
+ * project's own `@intentius/chant/*` imports resolve to. String arithmetic
+ * only: no filesystem access, so it is safe inside a sandboxed child.
+ */
+export function chantSourceDir(moduleUrl) {
+    const dir = dirname(fileURLToPath(moduleUrl));
+    if (!moduleUrl.endsWith(".js"))
+        return dir;
+    const marker = `${sep}dist${sep}`;
+    const at = (dir + sep).lastIndexOf(marker);
+    if (at < 0)
+        return dir;
+    return dir.slice(0, at) + `${sep}src` + dir.slice(at + marker.length - 1);
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.js

@@ -0,0 +1,61 @@
+import { AttrRef } from "./attrref.js";
+/**
+ * Symbol for storing logical names on Declarable entities
+ */
+export const LOGICAL_NAME_SYMBOL = Symbol.for("chant.logicalName");
+/**
+ * Duck-type check for AttrRef that survives the dual-package hazard.
+ * When npm installs separate copies of @intentius/chant (one for the CLI,
+ * one for the lexicon), `instanceof AttrRef` fails across package boundaries.
+ */
+export function isAttrRefLike(value) {
+    if (value instanceof AttrRef)
+        return true;
+    return (typeof value === "object" &&
+        value !== null &&
+        "parent" in value &&
+        "attribute" in value &&
+        "_setLogicalName" in value &&
+        typeof value.parent === "object" &&
+        typeof value.attribute === "string");
+}
+/**
+ * JSON.stringify replacer that sorts object keys for deterministic output.
+ */
+export function sortedJsonReplacer(_key, value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
+    }
+    return value;
+}
+/**
+ * Get all property names that have AttrRef values
+ * @param entity - The declarable entity to inspect
+ * @returns Array of property names with AttrRef values
+ */
+export function getAttributes(entity) {
+    const attributes = [];
+    const obj = entity;
+    for (const key in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            const value = obj[key];
+            if (isAttrRefLike(value)) {
+                attributes.push(key);
+            }
+        }
+    }
+    return attributes;
+}
+/**
+ * Get the logical name stored on a Declarable entity
+ * @param entity - The declarable entity
+ * @returns The logical name
+ * @throws {Error} If logical name is not set
+ */
+export function getLogicalName(entity) {
+    const logicalName = entity[LOGICAL_NAME_SYMBOL];
+    if (typeof logicalName !== "string") {
+        throw new Error(`Logical name not set on entity of type "${entity.entityType}"`);
+    }
+    return logicalName;
+}

package/dist/validation.js

@@ -0,0 +1,20 @@
+/**
+ * Validation system for declarable entities
+ *
+ * Provides opt-in, non-blocking validation hooks that can be used
+ * to validate entities during build or discovery phases.
+ */
+/**
+ * Validate an entity against a set of validation rules
+ *
+ * This function is opt-in and non-blocking - it returns results
+ * but does not throw errors. Callers can decide how to handle
+ * validation failures.
+ *
+ * @param entity - The declarable entity to validate
+ * @param rules - Array of validation rules to apply
+ * @returns Array of validation results, one per rule
+ */
+export function validate(entity, rules) {
+    return rules.map((rule) => rule.validate(entity));
+}