@intentius/chant 0.124.12 → 0.124.14

package/dist/identity.js

@@ -0,0 +1,251 @@
+/**
+ * The identity contract (#1982) — which principal chant would act as in each
+ * substrate, reported before it acts.
+ *
+ * Every native observer already resolves this. `ObserverAdapter.bind()`
+ * (./observation.ts) reaches the provider on the applier's own transport, the
+ * k8s connector resolves a kubeconfig context and says which binding produced
+ * it, the aws read client resolves a region and an endpoint. All of it is
+ * discarded. The only way the answer has ever surfaced is as an `unobserved`
+ * entry with reason `no-credentials`, or — worse — as a successful read
+ * against the wrong account.
+ *
+ * A project spanning aws, k8s, gcp and github reaches four substrates with
+ * four credential sets, and nothing says which identity each one resolves to.
+ * `chant lifecycle whoami <env>` asks each configured lexicon that question
+ * and prints one row per lexicon.
+ *
+ * ## The tri-state
+ *
+ * The same discipline the observation contract draws between "absent" and
+ * "not observed" applies here, because the same mistake is available: an empty
+ * identity reads as "nobody", and "nobody" is not what "I could not find out"
+ * means.
+ *
+ *   - **REPORTED** — the lexicon asked the substrate and it answered. A
+ *     principal, a scope, and where the binding came from.
+ *   - **UNRESOLVED** — the lexicon tried and could not, carrying a total
+ *     {@link UnobservedReason}. `no-credentials` is "no identity is
+ *     configured"; `no-binding` and `read-failed` are "could not determine".
+ *     Those are different answers and the reason keeps them apart.
+ *   - **NOT REPORTED** — the lexicon implements no {@link
+ *     import("./lexicon.js").LexiconPlugin.describeIdentity}. It answers for
+ *     nothing, which is honest; it is never rendered as an empty identity.
+ *
+ * ## Read-only, and never a gate
+ *
+ * `whoami` mutates nothing and blocks nothing. It exits 0 whatever the rows
+ * say unless the caller asks for a non-zero exit on an unresolved row with
+ * `--strict`. A lexicon's implementation is held to the same rule: a self-query
+ * that reaches the substrate must be one the substrate treats as a read of the
+ * caller's own identity.
+ *
+ * ## No credential ever reaches the output
+ *
+ * An identity is a principal and a scope — an account id, a project, an org, a
+ * cluster context, a service-account name. It is never a token, a key, a
+ * password or a certificate. The rule is on the lexicon: report the fact, not
+ * the value, and where a substrate's only identity signal IS a secret, say so
+ * without it.
+ *
+ * {@link redactCredentialMaterial} is the backstop core applies to every field
+ * of every row regardless, not a license to be careless. It is deliberately
+ * structural rather than heuristic — it redacts what the process actually
+ * holds in a credential-shaped environment variable, plus the three literal
+ * shapes (PEM block, JWT, `Bearer …`) that no principal string can be — so an
+ * account id, an ARN and a `system:serviceaccount:…` subject survive it intact.
+ */
+/** True when a lexicon answered with a typed refusal rather than an identity. */
+export function isUnresolvedIdentity(value) {
+    return typeof value === "object" && value !== null && "unresolved" in value;
+}
+/** The marker a redacted field carries. Fixed text so a consumer can match it. */
+export const REDACTED = "[redacted]";
+/**
+ * Environment variables whose VALUE is credential material. Matched on the
+ * name, so a lexicon that echoes one of these into an identity string has the
+ * value removed before it is printed or serialized.
+ */
+export const CREDENTIAL_ENV_NAME = /(SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL|PRIVATE_KEY|APIKEY|API_KEY|ACCESS_KEY|SESSION_KEY|AUTH)/i;
+/** Shortest env value worth redacting. Below this a "secret" is a false positive. */
+const MIN_CREDENTIAL_LENGTH = 8;
+/**
+ * Literal credential shapes. Each is something a principal string cannot be,
+ * so matching one is proof rather than a guess.
+ */
+export const CREDENTIAL_SHAPES = [
+    // A PEM block of any key type.
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+    // A JWT: three base64url segments, the first starting with the `{"` header.
+    /\beyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]*/g,
+    // An `Authorization`-style scheme plus its value.
+    /\b(?:Bearer|Basic)\s+[A-Za-z0-9\-._~+/]{16,}={0,2}/g,
+];
+/**
+ * Provider-prefixed access tokens, by their issuer's own prefix (#2356).
+ *
+ * Separate from {@link CREDENTIAL_SHAPES} because these are a **denylist of
+ * known formats** rather than proof-by-shape. A prefix nobody has added here —
+ * a new provider, an internal issuer, a bare random string — passes every one
+ * of them, and any caller relying on this must say so rather than claim
+ * coverage. What it does buy is that the tokens people actually paste are
+ * caught wherever they appear, whatever the field is called.
+ *
+ * The suffix bound is deliberately short. The prefix is the signal; a truncated
+ * or example token is still somebody having written a credential down.
+ */
+export const CREDENTIAL_TOKEN_SHAPES = [
+    { name: "a GitHub token", re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{6,}\b/g },
+    { name: "a GitHub fine-grained token", re: /\bgithub_pat_[A-Za-z0-9_]{6,}\b/g },
+    { name: "a GitLab personal access token", re: /\bglpat-[A-Za-z0-9_-]{3,}\b/g },
+    { name: "an OpenAI-style secret key", re: /\bsk-(?:live-|proj-|test-)?[A-Za-z0-9]{6,}\b/g },
+    { name: "a Stripe key", re: /\b[rs]k_(?:live|test)_[A-Za-z0-9]{6,}\b/g },
+    { name: "a Slack token", re: /\bxox[abposr]-[A-Za-z0-9-]{6,}\b/g },
+    { name: "an AWS access key id", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+    { name: "a Google API key", re: /\bAIza[0-9A-Za-z_-]{20,}\b/g },
+    { name: "a Google OAuth token", re: /\bya29\.[0-9A-Za-z_-]{10,}/g },
+    { name: "an npm token", re: /\bnpm_[A-Za-z0-9]{10,}\b/g },
+];
+/**
+ * Strip credential material from one reported field.
+ *
+ * Two rules, both structural. Any value this process holds in a
+ * credential-named environment variable is replaced wherever it appears, which
+ * covers the realistic accident — a lexicon echoing `$GITHUB_TOKEN` or
+ * `$AWS_SECRET_ACCESS_KEY` into a `source`. And the three literal shapes above
+ * are replaced on sight.
+ *
+ * Nothing is entropy-scored, so an ARN, an account id, a service-account email
+ * and a cluster context name pass through unchanged — which matters, because a
+ * mangled principal is a wrong answer, not a safe one.
+ */
+export function redactCredentialMaterial(value, env = process.env) {
+    let out = value;
+    for (const [name, secret] of Object.entries(env)) {
+        if (!secret || secret.length < MIN_CREDENTIAL_LENGTH)
+            continue;
+        if (!CREDENTIAL_ENV_NAME.test(name))
+            continue;
+        if (!out.includes(secret))
+            continue;
+        out = out.split(secret).join(REDACTED);
+    }
+    for (const shape of CREDENTIAL_SHAPES)
+        out = out.replace(shape, REDACTED);
+    // Provider-prefixed tokens too (#2356): these are the ones people paste, and
+    // the three shapes above match none of them.
+    for (const { re } of CREDENTIAL_TOKEN_SHAPES)
+        out = out.replace(re, REDACTED);
+    return out;
+}
+/** Apply {@link redactCredentialMaterial} to every free-text field of a row. */
+export function redactIdentityRow(row, env = process.env) {
+    const clean = (v) => v === undefined ? undefined : redactCredentialMaterial(v, env);
+    return {
+        ...row,
+        ...(row.identity !== undefined ? { identity: clean(row.identity) } : {}),
+        ...(row.scope !== undefined ? { scope: clean(row.scope) } : {}),
+        ...(row.source !== undefined ? { source: clean(row.source) } : {}),
+        ...(row.endpoint !== undefined ? { endpoint: clean(row.endpoint) } : {}),
+        ...(row.detail !== undefined ? { detail: clean(row.detail) } : {}),
+    };
+}
+/**
+ * Normalize one lexicon's answer into a row.
+ *
+ * Every degradation lands somewhere honest. No method at all is NOT REPORTED.
+ * A throw is UNRESOLVED with `read-failed` — the lexicon reached for the
+ * substrate and something broke, which is a different claim from having no
+ * credentials. An answer that carries no identity string is UNRESOLVED too: a
+ * lexicon cannot report an empty principal, because an empty principal renders
+ * as "acting as nobody", and nobody is a claim.
+ */
+export function identityRowFor(lexicon, result, env = process.env) {
+    if (result === undefined)
+        return { lexicon, status: "not-reported" };
+    if (isUnresolvedIdentity(result)) {
+        return redactIdentityRow({
+            lexicon,
+            status: "unresolved",
+            reason: result.unresolved.reason,
+            ...(result.unresolved.detail ? { detail: result.unresolved.detail } : {}),
+        }, env);
+    }
+    if (!result.identity || result.identity.trim() === "") {
+        return {
+            lexicon,
+            status: "unresolved",
+            reason: "read-failed",
+            detail: "the lexicon reported an identity with no principal in it",
+        };
+    }
+    return redactIdentityRow({
+        lexicon,
+        status: "reported",
+        identity: result.identity,
+        scope: result.scope,
+        source: result.source,
+        ...(result.endpoint ? { endpoint: result.endpoint } : {}),
+    }, env);
+}
+/**
+ * Ask every plugin who it would act as. One call per lexicon, concurrently,
+ * in the order the plugins were configured so the report is stable.
+ *
+ * A plugin that throws never fails the run: the throw becomes that lexicon's
+ * UNRESOLVED row. Reporting is the whole point, and a report that aborts on
+ * the first broken substrate is exactly the report nobody can use.
+ */
+export async function describeIdentities(plugins, options, env = process.env) {
+    return Promise.all(plugins.map(async (plugin) => {
+        if (!plugin.describeIdentity)
+            return { lexicon: plugin.name, status: "not-reported" };
+        try {
+            return identityRowFor(plugin.name, await plugin.describeIdentity(options), env);
+        }
+        catch (err) {
+            return identityRowFor(plugin.name, {
+                unresolved: {
+                    reason: "read-failed",
+                    detail: err instanceof Error ? err.message : String(err),
+                },
+            }, env);
+        }
+    }));
+}
+/**
+ * A row's verdict as one short cell, for the IDENTITY column. Deliberately
+ * without the `detail`, which is a sentence and belongs under the table rather
+ * than inside a column every other row has to be padded to.
+ */
+export function identityStatusText(row) {
+    switch (row.status) {
+        case "reported":
+            return row.identity ?? "";
+        case "unresolved":
+            return `could not determine — ${unresolvedReasonText(row.reason)}`;
+        case "not-reported":
+            return "not reported — this lexicon does not answer for an identity";
+    }
+}
+/**
+ * Why an identity did not resolve, in words. Deliberately distinct from
+ * `unobservedReasonText`: `no-credentials` here means "no identity is
+ * configured for this substrate", which is an answer, not a failure to look.
+ */
+export function unresolvedReasonText(reason) {
+    switch (reason) {
+        case "no-credentials":
+            return "no identity is configured for this substrate";
+        case "no-binding":
+            return "this environment resolves to no target";
+        case "read-failed":
+            return "the substrate was reached and the self-query failed";
+        case "unsupported-kind":
+            return "the substrate exposes no self-query";
+        case "filtered":
+            return "withheld";
+        default:
+            return "no reason given";
+    }
+}

package/dist/import/base-parser.js

@@ -0,0 +1,34 @@
+/**
+ * Base class for template value parsers.
+ *
+ * Implements the generic recursive walk: null → array → single-key
+ * intrinsic dispatch → plain object → primitive. Subclasses provide
+ * format-specific intrinsic dispatch.
+ */
+export class BaseValueParser {
+    /**
+     * Parse a value recursively: null → array → single-key intrinsic → object → primitive.
+     */
+    parseValue(value) {
+        if (value === null || value === undefined)
+            return value;
+        if (Array.isArray(value)) {
+            return value.map((v) => this.parseValue(v));
+        }
+        if (typeof value === "object") {
+            const obj = value;
+            const keys = Object.keys(obj);
+            if (keys.length === 1) {
+                const result = this.dispatchIntrinsic(keys[0], obj[keys[0]], obj);
+                if (result !== null)
+                    return result;
+            }
+            const parsed = {};
+            for (const [k, v] of Object.entries(obj)) {
+                parsed[k] = this.parseValue(v);
+            }
+            return parsed;
+        }
+        return value;
+    }
+}

package/dist/import/embedded.js

@@ -0,0 +1,255 @@
+/**
+ * Content embedded in another lexicon's resources, imported by the lexicon
+ * that owns it (#2962).
+ *
+ * A Kubernetes ConfigMap holding a collector's `config.yaml`, a
+ * `PrometheusRule` whose `spec.groups` are Prometheus rule groups, and a
+ * ConfigMap holding Grafana dashboard JSON all carry another lexicon's
+ * source inside a k8s resource. The host lexicon's parser (k8s) finds such
+ * content and offers it here; the lexicon that can import it (otel,
+ * prometheus, grafana) declares so with `LexiconPlugin.embeddedImporters()`.
+ * Core matches the two at run time, so the host needs no dependency on the
+ * owner: when the owner is not installed the content stays as written, with
+ * a warning.
+ *
+ * The flow, driven by `chant import`:
+ *
+ * 1. The host's `TemplateParser.parse(content, context)` calls
+ *    `context.embedded.resolve(site)` for each place content can be
+ *    embedded, and puts the `EmbeddedReference` it gets back into its IR in
+ *    place of the raw value. `undefined` means keep the raw value.
+ * 2. The owner's `EmbeddedContentImporter.import(site)` returns the modules
+ *    declaring the content and how the host's value is built from them
+ *    (`collectorYaml([...])`, a list of rule groups, `dashboardJson(...)`).
+ * 3. Core writes those modules in a directory of their own beside the
+ *    host's files, and the host's generator renders the reference with
+ *    `renderEmbeddedReference`, which also writes the imports it needs.
+ */
+import { posix } from "path";
+import { parseYAMLDocument, splitYAMLDocuments } from "../yaml.js";
+export function isEmbeddedReference(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const e = value.$embedded;
+    return (typeof e === "object" &&
+        e !== null &&
+        Array.isArray(e.value?.bindings));
+}
+// ── the registry ─────────────────────────────────────────────────────
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** The document a text holds: JSON, or a single YAML document. Undefined for anything else. */
+export function embeddedDocument(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Not JSON: try YAML.
+    }
+    const docs = splitYAMLDocuments(text);
+    if (docs.length !== 1)
+        return undefined;
+    let doc;
+    try {
+        doc = parseYAMLDocument(docs[0]);
+    }
+    catch {
+        return undefined;
+    }
+    // Text that is not YAML (`just text`, `KEY=value` lines) makes core's YAML
+    // reader throw, caught above (#2991); an empty or comment-only text reads
+    // as an empty mapping. Neither is a document.
+    if (typeof doc === "object" && doc !== null && Object.keys(doc).length === 0)
+        return undefined;
+    return doc;
+}
+/** A directory name: lower-case letters, digits and `-`. */
+function slug(text) {
+    const s = text
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return s === "" ? "embedded" : s;
+}
+/**
+ * Resolves embedded content against the importers registered for one
+ * import, and collects what the imports produce: the files to write beside
+ * the host's and the warnings to print. `offered` lists every piece of
+ * content the host offered, claimed or not.
+ */
+export class EmbeddedImports {
+    /**
+     * @param importers what the installed lexicons registered, in the order they are asked
+     * @param options.quiet collect `offered` only, with no warnings (a probe before the importers are known)
+     */
+    constructor(importers = [], options = {}) {
+        this.importers = importers;
+        this.options = options;
+        this.offered = [];
+        this.files = [];
+        this.warnings = [];
+        this.directories = new Set();
+    }
+    resolve(offered) {
+        const content = offered.document === undefined && typeof offered.text === "string"
+            ? { ...offered, document: embeddedDocument(offered.text) }
+            : offered;
+        this.offered.push(content);
+        const matching = this.importers.filter(({ importer }) => {
+            try {
+                return importer.matches(content);
+            }
+            catch {
+                return false;
+            }
+        });
+        const [chosen, ...others] = matching;
+        if (!chosen) {
+            const owner = content.expectedOwner;
+            if (owner && !this.options.quiet) {
+                this.warnings.push(`${content.location} looks like ${owner.what}, and no installed lexicon imports it, so it is kept as written. ` +
+                    `Install @intentius/chant-lexicon-${owner.lexicon} (or a version that imports embedded content) to import it as typed declarations.`);
+            }
+            return undefined;
+        }
+        if (others.length > 0) {
+            this.warnings.push(`${content.location} is also importable by ${others.map((o) => o.lexicon).join(", ")}; imported with ${chosen.lexicon}.`);
+        }
+        const kept = chosen.importer.keepsAsWritten?.(content);
+        if (kept !== undefined) {
+            this.warnings.push(`${content.location} is ${chosen.importer.what}, kept as written: ${kept}`);
+            return undefined;
+        }
+        let result;
+        try {
+            result = chosen.importer.import(content);
+        }
+        catch (err) {
+            this.warnings.push(`${content.location} looks like ${chosen.importer.what}, but the ${chosen.lexicon} import failed, so it is kept as written: ` +
+                (err instanceof Error ? err.message : String(err)));
+            return undefined;
+        }
+        const dir = this.claimDirectory(content.directory);
+        const local = new Set(result.files.map((f) => f.path));
+        const rebase = (from) => (local.has(from) ? `${dir}/${from}` : from);
+        for (const f of result.files)
+            this.files.push({ path: `${dir}/${f.path}`, content: f.content });
+        for (const w of result.warnings ?? [])
+            this.warnings.push(`${content.location}: ${w}`);
+        const v = result.value;
+        const value = {
+            bindings: v.bindings.map((b) => ({ ...b, from: rebase(b.from) })),
+            shape: v.shape,
+            ...(v.through ? { through: { ...v.through, from: rebase(v.through.from) } } : {}),
+        };
+        return {
+            $embedded: { lexicon: chosen.lexicon, what: chosen.importer.what, location: content.location, value },
+        };
+    }
+    claimDirectory(name) {
+        const base = slug(name);
+        let dir = base;
+        for (let n = 2; this.directories.has(dir); n++)
+            dir = `${base}-${n}`;
+        this.directories.add(dir);
+        return dir;
+    }
+}
+// ── rendering ────────────────────────────────────────────────────────
+const RESERVED = new Set(("break case catch class const continue debugger default delete do else enum export extends false finally for " +
+    "function if import in instanceof new null return super switch this throw true try typeof var void while with " +
+    "yield let static implements interface package private protected public await arguments eval undefined").split(" "));
+/**
+ * The imports one generated module needs for the references it renders.
+ * Names are made unique against the module's own declarations: a second
+ * `otlp` from another collector's directory is imported as `otlp2`.
+ */
+export class EmbeddedImportScope {
+    /**
+     * @param fromDir the directory of the module being generated, relative to the output directory (`""` for its top)
+     * @param taken names the module already declares or imports
+     */
+    constructor(fromDir, taken = []) {
+        this.fromDir = fromDir;
+        /** specifier -> exported name -> local name */
+        this.bySpecifier = new Map();
+        this.taken = new Set(taken);
+    }
+    /** The local name `name`, exported by `from` (a package or an output-relative path), is used under. */
+    bind(from, name) {
+        const spec = this.specifier(from);
+        let names = this.bySpecifier.get(spec);
+        if (!names) {
+            names = new Map();
+            this.bySpecifier.set(spec, names);
+        }
+        const existing = names.get(name);
+        if (existing)
+            return existing;
+        let local = name;
+        for (let n = 2; this.taken.has(local) || RESERVED.has(local); n++)
+            local = `${name}${n}`;
+        this.taken.add(local);
+        names.set(name, local);
+        return local;
+    }
+    /** The import statements, packages first, then local modules, each sorted. */
+    lines() {
+        const specs = [...this.bySpecifier.keys()].sort((a, b) => {
+            const la = a.startsWith("."), lb = b.startsWith(".");
+            return la === lb ? a.localeCompare(b) : la ? 1 : -1;
+        });
+        return specs.map((spec) => {
+            const entries = [...this.bySpecifier.get(spec)].sort(([a], [b]) => a.localeCompare(b));
+            const list = entries.map(([name, local]) => (name === local ? name : `${name} as ${local}`));
+            const one = `import { ${list.join(", ")} } from "${spec}";`;
+            return one.length <= 100 ? one : `import {\n${list.map((n) => `  ${n},`).join("\n")}\n} from "${spec}";`;
+        });
+    }
+    specifier(from) {
+        if (!from.endsWith(".ts"))
+            return from;
+        let rel = posix.relative(this.fromDir || ".", from.replace(/\.ts$/, ""));
+        if (!rel.startsWith("."))
+            rel = `./${rel}`;
+        return rel;
+    }
+}
+/**
+ * The TypeScript expression for a reference, binding its names in `scope`.
+ * A list longer than one line is broken one binding per line, indented from
+ * `indent` spaces.
+ */
+export function renderEmbeddedReference(ref, scope, indent = 0) {
+    const { value } = ref.$embedded;
+    const items = value.bindings.map((b) => `${scope.bind(b.from, b.name)}${b.member ? `.${b.member}` : ""}`);
+    let inner;
+    if (value.shape === "single") {
+        if (items.length !== 1)
+            throw new Error(`${ref.$embedded.location}: a single embedded value needs exactly one binding`);
+        inner = items[0];
+    }
+    else {
+        const one = `[${items.join(", ")}]`;
+        const pad = " ".repeat(indent);
+        inner = one.length <= 80 ? one : `[\n${items.map((i) => `${pad}  ${i},`).join("\n")}\n${pad}]`;
+    }
+    return value.through ? `${scope.bind(value.through.from, value.through.name)}(${inner})` : inner;
+}
+/**
+ * The names a generated module exports in its `export { … }` list, for an
+ * importer whose generator writes one per module (COR004).
+ */
+export function exportedNames(content) {
+    const names = [];
+    for (const m of content.matchAll(/^export\s*\{([^}]*)\};?\s*$/gm)) {
+        for (const part of m[1].split(",")) {
+            const name = part.trim().split(/\s+as\s+/).pop().trim();
+            if (name !== "" && !name.startsWith("type "))
+                names.push(name);
+        }
+    }
+    return names;
+}

package/dist/import/generator.js

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

package/dist/import/ir-utils.js

@@ -0,0 +1,85 @@
+/**
+ * IR intrinsic scanning utilities.
+ *
+ * Generic recursive walkers that scan the import IR value trees for
+ * intrinsic markers and dependency references.
+ */
+/**
+ * Check if a value tree contains an intrinsic with the given name.
+ * Looks for `{ __intrinsic: name }` objects recursively.
+ */
+export function hasIntrinsicInValue(value, name) {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return value.some((item) => hasIntrinsicInValue(item, name));
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        if (obj.__intrinsic === name) {
+            return true;
+        }
+        return Object.values(obj).some((v) => hasIntrinsicInValue(v, name));
+    }
+    return false;
+}
+/**
+ * Check if any resource, condition, or output in the IR uses a given intrinsic.
+ */
+export function irUsesIntrinsic(ir, name) {
+    for (const resource of ir.resources) {
+        if (hasIntrinsicInValue(resource.properties, name) ||
+            hasIntrinsicInValue(resource.metadata, name) ||
+            hasIntrinsicInValue(resource.attributes, name)) {
+            return true;
+        }
+    }
+    if (hasIntrinsicInValue(ir.metadata, name))
+        return true;
+    for (const condition of ir.conditions ?? []) {
+        if (hasIntrinsicInValue(condition.expression, name)) {
+            return true;
+        }
+    }
+    for (const output of ir.outputs ?? []) {
+        if (hasIntrinsicInValue(output.value, name) || hasIntrinsicInValue(output.exportName, name)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Collect dependency references from a value tree.
+ *
+ * @param value - The value tree to scan
+ * @param isDependency - Given an object, returns a logical ID if it represents
+ *   a dependency, or null otherwise. Each lexicon provides its own predicate.
+ */
+export function collectDependencies(value, isDependency) {
+    const deps = new Set();
+    collectDepsRecursive(value, isDependency, deps);
+    return deps;
+}
+function collectDepsRecursive(value, isDependency, deps) {
+    if (value === null || value === undefined)
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectDepsRecursive(item, isDependency, deps);
+        }
+        return;
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const dep = isDependency(obj);
+        if (dep !== null) {
+            deps.add(dep);
+        }
+        else {
+            for (const v of Object.values(obj)) {
+                collectDepsRecursive(v, isDependency, deps);
+            }
+        }
+    }
+}

package/dist/import/parser-options.js

@@ -0,0 +1,45 @@
+/**
+ * Check `--parser-option` entries (`key` or `key=value`) against what the
+ * lexicon declares in `parserOptions()` and convert each value to its declared
+ * type (#2994). Returns the options, or an error message naming what is wrong
+ * and what the lexicon accepts. An empty list is always valid.
+ */
+export function resolveParserOptions(plugin, entries) {
+    const options = {};
+    if (!entries || entries.length === 0)
+        return { options };
+    const specs = plugin.parserOptions?.() ?? [];
+    const accepted = specs.length === 0
+        ? `lexicon "${plugin.name}" declares no parser options`
+        : `${plugin.name} accepts: ${specs.map((s) => `${s.name} (${s.type}): ${s.description}`).join("; ")}`;
+    for (const entry of entries) {
+        const eq = entry.indexOf("=");
+        const name = eq === -1 ? entry : entry.slice(0, eq);
+        const raw = eq === -1 ? undefined : entry.slice(eq + 1);
+        const spec = specs.find((s) => s.name === name);
+        if (!spec) {
+            return { error: `Unknown parser option "${name}" for lexicon "${plugin.name}"; ${accepted}.` };
+        }
+        if (spec.type === "boolean") {
+            if (raw === undefined || raw === "true")
+                options[name] = true;
+            else if (raw === "false")
+                options[name] = false;
+            else
+                return { error: `Parser option "${name}" is a boolean: use ${name}, ${name}=true or ${name}=false, got "${raw}".` };
+        }
+        else if (raw === undefined) {
+            return { error: `Parser option "${name}" needs a value: --parser-option ${name}=<${spec.type}>.` };
+        }
+        else if (spec.type === "number") {
+            const n = Number(raw);
+            if (raw.trim() === "" || !Number.isFinite(n))
+                return { error: `Parser option "${name}" is a number, got "${raw}".` };
+            options[name] = n;
+        }
+        else {
+            options[name] = raw;
+        }
+    }
+    return { options };
+}

package/dist/import/parser.js

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