@intentius/chant 0.124.13 → 0.124.14

package/dist/declarable.js

@@ -0,0 +1,114 @@
+/**
+ * Marker symbol for Declarable type identification
+ */
+export const DECLARABLE_MARKER = Symbol.for("chant.declarable");
+/**
+ * Type guard for `ResourceDeclarable` — replaces the ad-hoc `"props" in x`
+ * checks that were previously repeated (with an `as unknown as` cast) at every
+ * call site that reads `props`/`attributes` off a `Declarable`.
+ */
+export function isResourceDeclarable(value) {
+    return "props" in value;
+}
+/**
+ * The suffix a declarable marker's symbol description ends with.
+ *
+ * chant#2444 — what makes a marker mean "entity" rather than "some other kind
+ * of chant value". `Symbol.for("chant.declarable")` has it; so does the
+ * specification host's `Symbol.for("tsad.conformance.declarable")`.
+ */
+const DECLARABLE_MARKER_SUFFIX = ".declarable";
+/**
+ * Type guard to check if a value is a Declarable.
+ *
+ * chant#2444 — accepts an entity a HOST built, not only one chant built.
+ *
+ * `F-Host-Interface` item 1 says an entity carries a non-enumerable declarable
+ * marker, and a host supplies its own: the specification's conformance host
+ * marks with `Symbol.for("tsad.conformance.declarable")`. Testing identity
+ * against chant's symbol alone refused those for not being chant's rather than
+ * for being malformed, which is what chant#2442 hit inside composite member
+ * validation and what would otherwise keep biting in the entity tallies and the
+ * revival pass-through.
+ *
+ * ## Why NOT the reference implementation's reading
+ *
+ * The reference reads L6.1 as "any own symbol or non-enumerable own property",
+ * which is right in its domain and **unsafe in chant's**. Two measurements say
+ * so, and both were taken rather than assumed:
+ *
+ *   - A real chant entity's non-enumerable own NAMES are `lexicon`,
+ *     `entityType`, `kind`, `props`, `attributes`, `Ref`. "Any non-enumerable
+ *     own property" is therefore close to "any chant object at all".
+ *   - chant has SEVEN marker symbols, not one — `chant.intrinsic`,
+ *     `chant.composite`, `chant.stackOutput`, `chant.lexiconOutput`,
+ *     `chant.effect-receipt`, `chant.secret-declaration`, `chant.childProject`
+ *     — each a non-enumerable own symbol set to `true`. Under "any own symbol"
+ *     an Intrinsic and a StackOutput both classify as Declarable, which is a
+ *     worse bug than the one being fixed: they would enter the entity tallies.
+ *
+ * The reference can read any symbol because its domain has one. chant
+ * distinguishes seven kinds BY symbol identity, so it needs the marker's name.
+ * Hence the suffix: the marker must say `declarable`, whoever owns it.
+ *
+ * ## What the suffix cannot do
+ *
+ * It is a convention, not a registry. A host that marks with, say,
+ * `Symbol.for("acme.entity")` carries a perfectly good non-enumerable marker
+ * and is refused here, because nothing in this function knows that package is
+ * one the caller named. The context that would settle it —
+ * `FoldProjectOptions.lexiconPackages`, chant#2438 — lives in the fold path and
+ * does not reach a type guard called from a dozen places.
+ *
+ * That is a deliberate trade, not an oversight: a convention that refuses an
+ * unknown-but-valid marker costs a host one symbol name, while a rule loose
+ * enough to accept any marker miscounts chant's own seven kinds on every build.
+ * If a real host ever needs the other side of it, the fix is to thread the
+ * named packages through rather than to widen the test.
+ */
+export function isDeclarable(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    // chant's own, which is every entity a chant build makes.
+    if (value[DECLARABLE_MARKER] === true)
+        return true;
+    return carriesForeignDeclarableMarker(value);
+}
+/** A declarable marker some other implementation owns — see {@link isDeclarable}. */
+function carriesForeignDeclarableMarker(value) {
+    for (const marker of Object.getOwnPropertySymbols(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, marker);
+        // Non-enumerable and `true`, per F-Host-Interface item 1. An enumerable
+        // symbol would travel through a spread and reach an artifact, which a
+        // marker must not.
+        if (descriptor === undefined || descriptor.enumerable || descriptor.value !== true)
+            continue;
+        if (marker.description?.endsWith(DECLARABLE_MARKER_SUFFIX) === true)
+            return true;
+    }
+    return false;
+}
+/**
+ * Type guard to check if a Declarable is a property-level type
+ */
+export function isPropertyDeclarable(value) {
+    return value.kind === "property";
+}
+/**
+ * A declarable with a live counterpart of its own: what the live paths
+ * (`describeResources`, `observeResourcesDeep`, the snapshot, the diff and the
+ * change set) put in front of a lexicon's reader.
+ *
+ * Outputs, parameters and serializer directives carry no `props` and are
+ * already left out by {@link isResourceDeclarable}. A property-kind declarable
+ * (`createProperty`: Grafana's panels, an aws `SecurityGroup_Ingress`) does
+ * carry `props`, but it exists only inside the resource that holds it, and the
+ * deep diff already compares it as part of that resource's tree (#1314).
+ * Asking a reader about one on its own makes the answer either "absent", so
+ * `lifecycle plan` proposes a `create`, or "not observed", a hole for
+ * something read in full (#3001). This is the same test `graph-ir.ts` uses to
+ * keep property-kind declarables off the graph's nodes.
+ */
+export function isObservableDeclarable(value) {
+    return isResourceDeclarable(value) && !isPropertyDeclarable(value);
+}

package/dist/deep-observation.js

@@ -0,0 +1,437 @@
+/**
+ * The deep observation contract (#1014) — what a lexicon's
+ * `observeResourcesDeep()` is allowed to mean, and how a live property tree is
+ * normalized before anything diffs it.
+ *
+ * `describeResources()` (./observation.ts) answers *whether* a declared entity
+ * exists and carries a handful of scrubbed outputs. That is thin by design, and
+ * it is why `lifecycle diff --live` only fires on a changed status, a replaced
+ * physical id, or a changed stack output. The drift people actually care about
+ * — a hand-edited security-group rule, an inline policy added in the console, a
+ * flipped bucket setting — lives one level down, in properties nobody was
+ * reading.
+ *
+ * This module adds the second, optional read: a normalized live property tree
+ * per declared entity. It composes with the tri-state contract rather than
+ * replacing it — {@link DeepObservationResult} carries the same
+ * {@link UnobservedEntity} map, so a deep read that fails for one entity is
+ * NOT-OBSERVED with a reason. A thin deep result is never allowed to pass for a
+ * clean one.
+ *
+ * ## The hard half is noise, not reading
+ *
+ * A raw live model is mostly fields nobody declared and nobody changed: arns,
+ * timestamps, generation counters, status subtrees, values the API filled in,
+ * fields a controller owns, and orderings that carry no meaning (tag order,
+ * policy statement order). Diffing that raw is all noise. So the contract is
+ * three parts, and a lexicon implements the last two:
+ *
+ *   1. **The normalization pass** (here, shared) — canonical key order,
+ *      hook-driven array order, secret masking, non-JSON values collapsed to
+ *      {@link UNRESOLVED}.
+ *   2. **The pruning hook** ({@link DeepNormalizationHooks.prune}) — the
+ *      lexicon names its own read-only / server-populated / controller-managed /
+ *      provider-defaulted fields.
+ *   3. **The ordering hook** ({@link DeepNormalizationHooks.orderKey}) — the
+ *      lexicon names which arrays are sets, and by what key they canonicalize.
+ *
+ * Both hooks are applied to the *declared* tree and the *live* tree with the
+ * same rules, so the two sides are compared in the same shape. A hook sees
+ * which side it is normalizing ({@link DeepNode.side}) and whether the same path
+ * exists on the other side ({@link DeepNode.counterpart}) — that second flag is
+ * what makes default subtraction expressible: a provider default is only noise
+ * when nobody declared the property.
+ */
+import { isHeldElsewhere, isNormalizedHeldElsewhere, normalizeHeldElsewhere } from "./held-elsewhere.js";
+/** True when `value` is the versioned {@link DeepObservationResult} envelope. */
+export function isDeepObservationResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.deepObservation === "v1");
+}
+/** Build a {@link DeepObservationResult}. Lexicons use this rather than writing the discriminant by hand. */
+export function deepObservation(resources, unobserved, pending) {
+    return {
+        deepObservation: "v1",
+        resources,
+        ...(unobserved && Object.keys(unobserved).length > 0 ? { unobserved } : {}),
+        ...(pending && pending.length > 0 ? { pending } : {}),
+    };
+}
+/**
+ * Normalize a deep result. `undefined` (a lexicon that returned nothing at all)
+ * normalizes to two empty maps — which reads as "every declared entity's
+ * properties were read and there were none", so a reader that means "I could
+ * not look" must say so with `unobservedAll()` rather than returning nothing.
+ */
+export function normalizeDeepObservation(value) {
+    if (!value)
+        return { resources: {}, unobserved: {} };
+    return {
+        resources: value.resources ?? {},
+        unobserved: value.unobserved ?? {},
+        ...(value.pending && value.pending.length > 0 ? { pending: value.pending } : {}),
+    };
+}
+// ── Normalization pass ──────────────────────────────────────────────────────
+/**
+ * The placeholder a value takes when it is not JSON data — a class instance
+ * (an unevaluated intrinsic like `Sub`/`Ref` in a declared tree), a function, a
+ * symbol. The diff skips any path whose *declared* value is this: chant cannot
+ * know what `Fn::Sub` resolves to without deploying, and guessing would report
+ * every interpolated property as permanent drift.
+ */
+export const UNRESOLVED = "<chant:unresolved>";
+/** Value a masked (secret-bearing) property takes. Matches the thin path's convention. */
+export const MASKED = "[REDACTED]";
+/**
+ * Property-name patterns that mark a value secret-bearing. Deliberately narrow
+ * and key-name based: broadening this to e.g. `/key/i` would mask an AWS tag's
+ * `Key` field and every `*KeyName` reference, which is how masking turns into
+ * its own drift signal.
+ *
+ * Shared with the thin snapshot path (`./lifecycle/snapshot.ts`), which warns
+ * on the same names — one list, so the two paths cannot disagree about what
+ * counts as a secret.
+ */
+export const SENSITIVE_KEY_PATTERNS = [
+    /password/i,
+    /secret/i,
+    /token/i,
+    /private.?key/i,
+    /credential/i,
+    /connection.?string/i,
+];
+/** True when a property name looks secret-bearing (see {@link SENSITIVE_KEY_PATTERNS}). */
+export function isSensitiveKey(key) {
+    return SENSITIVE_KEY_PATTERNS.some((p) => p.test(key));
+}
+/** True for a value the pass will walk into rather than treat as a leaf. */
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** True for a value that can be compared and serialized as-is. */
+function isJsonPrimitive(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean");
+}
+function joinPath(parent, key) {
+    return parent ? `${parent}.${key}` : key;
+}
+function joinIndex(parent, index) {
+    return `${parent}[${index}]`;
+}
+function joinPattern(parent) {
+    return `${parent}[]`;
+}
+/**
+ * Every path in a raw tree — both the exact form (`Tags[0].Value`) and the
+ * index-erased pattern (`Tags[].Value`) — for {@link
+ * NormalizeDeepOptions.counterpartPaths}. The two forms never collide (`[]` vs
+ * `[0]`), so one set answers both questions.
+ *
+ * Computed on the *raw* tree, before pruning: whether a property was declared
+ * cannot depend on whether the pruning rules kept it.
+ */
+export function deepPathSet(tree) {
+    const out = new Set();
+    const walk = (value, path, pattern) => {
+        if (path) {
+            out.add(path);
+            out.add(pattern);
+        }
+        // A held marker (#2162) is one declared value, not a `{ by, reason }`
+        // object to walk into — same leaf treatment `normalizeDeepProperties`
+        // gives it, so this path set agrees with what the normalized tree
+        // actually looks like a path down.
+        if (isHeldElsewhere(value))
+            return;
+        // A property-kind declarable is walked as its props, exactly as
+        // `normalizeDeepProperties` inlines it (#1314). Stopping at it left every
+        // path under a typed nested property out of the set, so the other tree's
+        // nodes there read `counterpart: "absent"` and default subtraction fired
+        // on properties the author did declare.
+        if (isPropertyDeclarableValue(value)) {
+            walk(value.props ?? {}, path, pattern);
+            return;
+        }
+        if (Array.isArray(value)) {
+            value.forEach((el, i) => walk(el, joinIndex(path, i), joinPattern(pattern)));
+            return;
+        }
+        if (isPlainObject(value)) {
+            for (const [k, v] of Object.entries(value))
+                walk(v, joinPath(path, k), joinPath(pattern, k));
+        }
+    };
+    walk(tree, "", "");
+    return out;
+}
+/**
+ * Normalize one property tree: prune by hook, mask secret-bearing leaves,
+ * canonicalize key order, canonicalize array order where the hook knows how,
+ * and collapse anything that isn't JSON data to {@link UNRESOLVED}.
+ *
+ * Pure and total. Key order is canonicalized unconditionally because JSON
+ * object order is not semantic and a provider is free to return it differently
+ * on every read; array order is canonicalized only where the lexicon says the
+ * array is a set, because list order often *is* semantic.
+ */
+/**
+ * A container whose every member the rules pruned.
+ *
+ * The distinction it carries is between a value that was empty in the source
+ * and one this pass emptied: `{}` a lexicon actually declared is a fact worth
+ * diffing, while `{}` left behind after both of a rule's fields were subtracted
+ * as provider defaults is a husk. Reporting the husk turns a suppressed default
+ * into `SecurityGroupEgress[#{}]: <undeclared> → {}` — noise wearing the shape
+ * of drift, which is the one thing the noise rules exist to prevent.
+ *
+ * Module-private: it never leaves this function's recursion.
+ */
+const EMPTIED = Symbol("emptied-by-pruning");
+/**
+ * A property-kind Declarable — a nested property authored through a lexicon's
+ * generated constructor rather than as a plain object (#1314).
+ *
+ * Duck-typed on the same three facts `declarable.ts` defines it by
+ * (`entityType`, `kind === "property"`, `props`) rather than imported, keeping
+ * this module free of a dependency on the authoring types it only ever
+ * inspects. A resource-kind Declarable deliberately does not match.
+ */
+function isPropertyDeclarableValue(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return typeof v.entityType === "string" && v.kind === "property" && typeof v.props === "object" && v.props !== null;
+}
+export function normalizeDeepProperties(tree, options) {
+    const { entityType, side, hooks, counterpartPaths } = options;
+    const nodeOf = (path, pattern, key, value) => ({
+        entityType,
+        path,
+        pattern,
+        key,
+        value,
+        side,
+        counterpart: !counterpartPaths
+            ? "unknown"
+            : counterpartPaths.has(path) || counterpartPaths.has(pattern)
+                ? "present"
+                : "absent",
+    });
+    const prune = (path, pattern, key, value) => {
+        if (!hooks?.prune)
+            return false;
+        return hooks.prune(nodeOf(path, pattern, key, value));
+    };
+    const normalizeValue = (value, path, pattern, key) => {
+        // A `heldElsewhere()` marker (#2162) — declared on purpose, not
+        // unresolved and not a plain object to walk into. Checked ahead of even
+        // the secret-masking rules below: the marker carries no value at all,
+        // only who holds the field and why, so there is nothing for masking to
+        // protect and masking it would destroy the one thing worth reporting —
+        // a `heldElsewhere()` on a `password`-shaped key ("an operator rotates
+        // this out of band") must still say so, not collapse to `[REDACTED]`.
+        // Normalized to a JSON-safe tagged leaf so its identity survives this
+        // pass and a `--json` round-trip; `deep-diff.ts` reads the tag to
+        // report a live difference here as held rather than as drift, on
+        // either side (a lexicon's own reader never produces this shape, so
+        // the check is safe on the live tree too, though only the declared
+        // side ever carries one in practice). Checked ahead of the
+        // array/object branches too, same reason a property-Declarable is: it
+        // would otherwise be walked as a two-key plain object and lose the
+        // very identity that makes it a marker rather than authored data.
+        if (isHeldElsewhere(value))
+            return normalizeHeldElsewhere(value);
+        if (isSensitiveKey(key))
+            return MASKED;
+        // The lexicon's structural mask — same collapse, path-shaped rather than
+        // key-named (a k8s Secret's `data.*` no matter what the key is called).
+        if (hooks?.mask?.(nodeOf(path, pattern, key, value)))
+            return MASKED;
+        // A value the lexicon says cannot be known without deploying — an
+        // expression-string reference — collapses exactly like a class-instance
+        // intrinsic does below.
+        if (hooks?.unresolved?.(nodeOf(path, pattern, key, value)))
+            return UNRESOLVED;
+        if (isJsonPrimitive(value))
+            return value;
+        // A PROPERTY-kind Declarable is authored data wearing a class, not an
+        // opaque instance (#1314). The generated property constructors —
+        // `SecurityGroup_Ingress`, `Role_Policy`, `MicrovmImage_Logging` — are the
+        // typed way to write a nested property, and the serializer inlines their
+        // `.props` (serializer-walker.ts `visitor.propertyDeclarable`). The
+        // declared tree has to do the same, or the two sides disagree about a
+        // property the author did write: without this the declared side held
+        // UNRESOLVED while the live side held the real rule, so every one of its
+        // fields reported `<undeclared> → <value>` on a clean apply, and the noise
+        // scaled with how strictly a project typed its properties.
+        //
+        // Checked ahead of the array/object branches rather than in the non-JSON
+        // fallback below, so it holds whether the declarable arrives as a class
+        // instance (what a lexicon constructs) or as an equivalent plain object.
+        //
+        // Deliberately property-kind only. A RESOURCE-kind Declarable in another
+        // resource's props is a reference, which has no source-side value to
+        // compare against a live one, so UNRESOLVED stays correct for it — and a
+        // resource-kind instance falls through to that fallback unchanged.
+        if (isPropertyDeclarableValue(value)) {
+            return normalizeValue(value.props ?? {}, path, pattern, key);
+        }
+        if (Array.isArray(value)) {
+            const elements = [];
+            for (let i = 0; i < value.length; i++) {
+                const elPath = joinIndex(path, i);
+                const elPattern = joinPattern(pattern);
+                if (prune(elPath, elPattern, String(i), value[i]))
+                    continue;
+                const element = normalizeValue(value[i], elPath, elPattern, String(i));
+                if (element === EMPTIED)
+                    continue;
+                elements.push(element);
+            }
+            // An array that had elements and has none left was emptied by pruning,
+            // not declared empty. Reporting `[]` for it is reporting the husk of a
+            // value the rules just decided was noise.
+            if (elements.length === 0 && value.length > 0)
+                return EMPTIED;
+            return orderElements(elements, path, pattern);
+        }
+        if (isPlainObject(value)) {
+            const out = {};
+            let had = 0;
+            for (const childKey of Object.keys(value).sort()) {
+                const childPath = joinPath(path, childKey);
+                const childPattern = joinPath(pattern, childKey);
+                const childValue = value[childKey];
+                if (childValue === undefined)
+                    continue;
+                had += 1;
+                if (prune(childPath, childPattern, childKey, childValue))
+                    continue;
+                const child = normalizeValue(childValue, childPath, childPattern, childKey);
+                if (child === EMPTIED)
+                    continue;
+                out[childKey] = child;
+            }
+            if (Object.keys(out).length === 0 && had > 0)
+                return EMPTIED;
+            return out;
+        }
+        // A class instance (an unevaluated intrinsic), a function, a symbol, a
+        // bigint — not JSON data, and not something the diff may guess at.
+        return UNRESOLVED;
+    };
+    const orderElements = (elements, path, pattern) => {
+        if (!hooks?.orderKey || elements.length < 2)
+            return elements;
+        const keyed = [];
+        for (let i = 0; i < elements.length; i++) {
+            const key = hooks.orderKey({
+                entityType,
+                path,
+                pattern,
+                element: elements[i],
+                index: i,
+                side,
+            });
+            // A partial answer is not an answer — leave the order alone.
+            if (key === undefined)
+                return elements;
+            keyed.push({ key, element: elements[i] });
+        }
+        keyed.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+        return keyed.map((k) => k.element);
+    };
+    const root = normalizeValue(tree, "", "", "");
+    return isPlainObject(root) ? root : {};
+}
+/** Longest order key that may appear inside a path segment before it stops being readable. */
+const MAX_KEYED_SEGMENT = 60;
+/**
+ * Flatten a normalized tree to `path → leaf value`. Leaves are JSON primitives,
+ * {@link UNRESOLVED}, and empty containers (an empty object/array is itself a
+ * value — `Tags: []` differs from no `Tags` at all).
+ *
+ * Arrays the ordering hook can key are addressed **by that key**
+ * (`Tags[#env].Value`) rather than by position. Positional paths would make the
+ * diff shift-sensitive: one tag added in the console renames every tag after
+ * it, so a single new tag reports as a change to every other tag and a
+ * baseline entry stops matching the moment the set changes. Keying holds a
+ * property's identity still while the set around it moves.
+ *
+ * Positional paths remain for arrays the hook cannot key, arrays whose keys
+ * collide, and keys too long to read.
+ */
+export function flattenDeepProperties(tree, options) {
+    const out = new Map();
+    const indexSegments = (elements, path, pattern) => {
+        const positional = elements.map((_, i) => joinIndex(path, i));
+        if (!options?.hooks?.orderKey)
+            return positional;
+        const keys = [];
+        for (let i = 0; i < elements.length; i++) {
+            const key = options.hooks.orderKey({
+                entityType: options.entityType,
+                path,
+                pattern,
+                element: elements[i],
+                index: i,
+                side: options.side,
+            });
+            if (key === undefined || key.length > MAX_KEYED_SEGMENT)
+                return positional;
+            keys.push(key);
+        }
+        if (new Set(keys).size !== keys.length)
+            return positional;
+        return keys.map((k) => `${path}[#${k}]`);
+    };
+    const walk = (value, path, pattern) => {
+        // A normalized held marker (#2162) is one value, not a two-key object to
+        // descend into — same reason UNRESOLVED and a JSON primitive are leaves.
+        if (isNormalizedHeldElsewhere(value)) {
+            out.set(path, value);
+            return;
+        }
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                out.set(path, []);
+                return;
+            }
+            const segments = indexSegments(value, path, pattern);
+            value.forEach((el, i) => walk(el, segments[i], joinPattern(pattern)));
+            return;
+        }
+        if (isPlainObject(value)) {
+            const keys = Object.keys(value);
+            if (keys.length === 0) {
+                out.set(path, {});
+                return;
+            }
+            for (const k of keys)
+                walk(value[k], joinPath(path, k), joinPath(pattern, k));
+            return;
+        }
+        out.set(path, value);
+    };
+    for (const [k, v] of Object.entries(tree))
+        walk(v, k, k);
+    return out;
+}
+/** Structural equality over JSON-shaped values, order-sensitive (post-canonicalization). */
+export function deepValueEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || a === undefined || b === undefined)
+        return false;
+    if (typeof a !== "object" || typeof b !== "object")
+        return false;
+    return JSON.stringify(a) === JSON.stringify(b);
+}

package/dist/detectLexicon.js

@@ -0,0 +1,54 @@
+import { readFile } from "node:fs/promises";
+/**
+ * The message {@link detectLexicons} throws when a scan of the project's
+ * source files turns up no `@intentius/chant-lexicon-*` import at all.
+ *
+ * Named (chant #2222) because one caller has to tell this failure apart from
+ * every other one: `chant lint` reports a lexicon it cannot resolve as an
+ * error diagnostic, but "this directory declares no lexicon and imports none"
+ * is not that. It is a project that lints under the core rules alone, and it
+ * has always been allowed to. See {@link isNoLexiconDetected}.
+ */
+export const NO_LEXICON_DETECTED_MESSAGE = "No lexicon detected in infrastructure files";
+/** Whether `error` is the {@link NO_LEXICON_DETECTED_MESSAGE} failure. */
+export function isNoLexiconDetected(error) {
+    return error instanceof Error && error.message === NO_LEXICON_DETECTED_MESSAGE;
+}
+/**
+ * Detects which lexicons are being used by analyzing import statements
+ * in the provided infrastructure files. Matches any `@intentius/chant-lexicon-*` package,
+ * imported by its root or by a subpath (`@intentius/chant-lexicon-sql/postgres`).
+ *
+ * @param files - Array of file paths to analyze
+ * @returns Array of detected lexicon names
+ * @throws Error if no lexicon is detected
+ */
+export async function detectLexicons(files) {
+    const detectedLexicons = new Set();
+    for (const file of files) {
+        let content;
+        try {
+            content = await readFile(file, "utf-8");
+        }
+        catch (error) {
+            // Skip files that can't be read
+            continue;
+        }
+        // Match @intentius/chant-lexicon-<name> in import/export statements.
+        // Uses [\s\S] instead of . to handle multiline imports like:
+        //   import { Foo, Bar } from "@intentius/chant-lexicon-k8s";
+        // chant #3648: a subpath import names the same lexicon, so
+        // "@intentius/chant-lexicon-sql/clickhouse" detects "sql". A project that
+        // imports a lexicon only through its subpaths (every sql project) has no
+        // other import for this scan to find.
+        const regex = /(?:import|export)\s+[\s\S]*?\s+from\s+['"]@intentius\/chant-lexicon-([a-z][\w-]*)(?:\/[^'"\s]*)?['"]/g;
+        for (const match of content.matchAll(regex)) {
+            detectedLexicons.add(match[1]);
+        }
+    }
+    // Validate results
+    if (detectedLexicons.size === 0) {
+        throw new Error(NO_LEXICON_DETECTED_MESSAGE);
+    }
+    return Array.from(detectedLexicons);
+}

package/dist/discovery/cache.js

@@ -0,0 +1,70 @@
+import { statSync } from "fs";
+/**
+ * Discovery cache for incremental rebuilds.
+ *
+ * Tracks file mtimes and file→entity mappings so that only changed files
+ * need to be re-imported during watch-mode rebuilds.
+ */
+export class DiscoveryCache {
+    constructor() {
+        this.files = new Map();
+    }
+    /**
+     * Check if a file has changed since it was last tracked.
+     * Returns true if the file is new or its mtime has changed.
+     */
+    hasFileChanged(filePath) {
+        const entry = this.files.get(filePath);
+        if (!entry)
+            return true;
+        try {
+            const stat = statSync(filePath);
+            return stat.mtimeMs !== entry.mtime;
+        }
+        catch {
+            // File may have been deleted
+            return true;
+        }
+    }
+    /**
+     * Record a successful import, storing the file's mtime and entity names.
+     */
+    trackFileImport(filePath, mtime, entityNames) {
+        this.files.set(filePath, { mtime, entityNames });
+    }
+    /**
+     * Invalidate cache entries for the given files.
+     * Returns the set of entity names that were invalidated.
+     */
+    invalidate(changedFiles) {
+        const invalidatedEntities = new Set();
+        for (const file of changedFiles) {
+            const entry = this.files.get(file);
+            if (entry) {
+                for (const name of entry.entityNames) {
+                    invalidatedEntities.add(name);
+                }
+                this.files.delete(file);
+            }
+        }
+        return invalidatedEntities;
+    }
+    /**
+     * Get all tracked file paths.
+     */
+    trackedFiles() {
+        return [...this.files.keys()];
+    }
+    /**
+     * Get entity names for a tracked file.
+     */
+    getFileEntities(filePath) {
+        return this.files.get(filePath)?.entityNames;
+    }
+    /**
+     * Clear all cached data.
+     */
+    clear() {
+        this.files.clear();
+    }
+}