typekro 0.33.9 → 0.34.0

package/dist/core/validation/literal-status.js

@@ -0,0 +1,346 @@
+/**
+ * Dropped status-leaf validation for KRO mode.
+ *
+ * THE RULE: a KRO status field must reference at least one RESOURCE in the
+ * graph. KRO's own instance builder enforces exactly that — `instance status
+ * field must refer to a resource` (KRO `builder.go`, quoted in
+ * `kro-instance-safety.ts`) — and its status CEL environment has no `schema`
+ * identifier at all. A status expression with no resource in it therefore has
+ * nothing to project from and is left unset on the instance. The declared
+ * status schema then promises a field the custom resource never carries, and
+ * every consumer that reads the CR directly (kubectl, another controller, an
+ * `externalRef` from a second composition) sees `undefined`.
+ *
+ * Two shapes have no resource in them, and KRO drops BOTH the same way:
+ *
+ *  - a bare LITERAL — a string, number, boolean, literal array/object, or a
+ *    reference-free CEL expression such as `Cel.expr`'running'``;
+ *  - a bare SCHEMA REFERENCE — `schema.spec.foo` standing alone in a status
+ *    leaf. It looks resolvable (the CR does hold that value in its own spec),
+ *    but a status leaf is a PROJECTION, and there is no resource here to
+ *    project from. TypeKro's own serializer already agrees: it classifies a
+ *    schema-only status field as "static" and excludes it from the emitted
+ *    status block — see invariant I1/I2 in
+ *    `test/unit/nested-composition-kro-serialization.test.ts` ("KRO status CEL
+ *    does NOT support `schema.spec.*`"), the same conclusion in
+ *    `src/core/proxy/create-resource.ts` ("classifies the resulting status
+ *    field as schema-derived and drops it from the live KRO CR's status
+ *    entirely"), and `assertNoHoistWeakenedStatusFields`, which already THROWS
+ *    for precisely this shape when a hoisted Namespace leaves a field
+ *    schema-only. This module simply makes the general case agree with that
+ *    special one.
+ *
+ * What stays valid is any expression ANCHORED on a resource. A mixed template
+ * such as `` `http://${schema.spec.name}-svc:${svc.spec.ports[0].port}` `` is
+ * fine: the resource reference gives KRO the dependency it requires, and
+ * `schema.spec.*` resolves against the instance's own spec from there. The
+ * serializer deliberately preserves those (`cel-references.ts`: "Plain CR spec
+ * fields must remain `schema.spec.*`"), and
+ * `nested-composition-kro-serialization.test.ts` pins the emitted shape. So the
+ * test is not "does this mention `schema`" but "does this reference a
+ * resource".
+ *
+ * TypeKro classified both dropped shapes as "static" and hydrated them
+ * client-side in `getStatus()`, which hides the gap from the composition's own
+ * author while leaving it wide open for everybody else. This module finds those
+ * leaves at serialization time so the author is told before the RGD ships.
+ *
+ * Direct mode is unaffected — there is no KRO reconciler in that path and the
+ * status object is assembled locally, so literals and schema refs are perfectly
+ * fine there. The check therefore runs only from the KRO schema emitter.
+ *
+ * See issue #188.
+ */
+import { KUBERNETES_REF_MARKER_SOURCE, KUBERNETES_REF_SCHEMA_MARKER_SOURCE, } from '../../shared/brands.js';
+import { celRootReferences, kubernetesMarkerReferences, } from '../../utils/cel-resource-identifiers.js';
+import { isCelExpression, isKubernetesRef } from '../../utils/type-guards.js';
+import { lookupNestedExpression } from '../serialization/cel-references.js';
+/** Longest rendered literal included in a diagnostic before truncation. */
+const MAX_RENDERED_LITERAL_LENGTH = 60;
+/**
+ * CEL roots that are NOT a resource: the instance's own spec, in both the
+ * pre-rewrite (`__schema__`) and emitted (`schema`) spellings.
+ */
+const SCHEMA_REFERENCE_ROOTS = new Set(['schema', '__schema__']);
+const REF_MARKER_PATTERN = new RegExp(KUBERNETES_REF_MARKER_SOURCE, 'g');
+const SCHEMA_REF_MARKER_PATTERN = new RegExp(KUBERNETES_REF_SCHEMA_MARKER_SOURCE);
+/**
+ * Blank every TypeKro ref marker out of an expression before CEL analysis.
+ *
+ * Markers are read by {@link kubernetesMarkerReferences}, never by the CEL
+ * parser: a marker's own text (`__KUBERNETES_REF___schema___spec_name__`) is a
+ * legal CEL identifier, so leaving it in place would make a SCHEMA marker parse
+ * as a root named `__KUBERNETES_REF___schema___spec` — i.e. read as a resource.
+ * Replacing each with an empty string literal keeps the surrounding expression
+ * parseable while contributing no references of its own.
+ */
+function stripRefMarkers(expression) {
+    return expression.replace(REF_MARKER_PATTERN, '""');
+}
+/**
+ * Does this CEL expression reference at least one RESOURCE?
+ *
+ * Handles every expression shape the status analyzer produces: ref markers,
+ * KRO mixed templates (`http://${svc.status.clusterIP}`), and plain CEL
+ * (`deploy.status.readyReplicas > 0`).
+ *
+ * `kubernetesMarkerReferences` already drops the `__schema__` root, so a marker
+ * hit is by construction a resource. For the parsed form, a root of `schema` /
+ * `__schema__` is the instance's own spec rather than a resource, so it does
+ * not anchor the leaf.
+ *
+ * A reference-free expression — `'"web"'`, `'41.5'`, `'true'` — is a literal in
+ * CEL clothing and gets dropped exactly like a bare literal would.
+ *
+ * CEL string literals never surface as identifier nodes and macro-bound lambda
+ * variables are excluded, so `['a','b'].map(x, x)` does not read as a
+ * reference to `x`.
+ */
+function expressionReferencesResource(expression) {
+    if (kubernetesMarkerReferences(expression).length > 0)
+        return true;
+    return celRootReferences(stripRefMarkers(expression)).some((reference) => !SCHEMA_REFERENCE_ROOTS.has(reference.root));
+}
+/** Does this CEL expression mention the instance's own spec? */
+function expressionReferencesSchema(expression) {
+    if (SCHEMA_REF_MARKER_PATTERN.test(expression))
+        return true;
+    return celRootReferences(stripRefMarkers(expression)).some((reference) => SCHEMA_REFERENCE_ROOTS.has(reference.root));
+}
+/**
+ * Is this plain status string safe to hand to the CEL analyzer at all?
+ *
+ * A plain string is ordinary data, not CEL, so it must never be analyzed
+ * wholesale: `'http://static.example.test'` would parse as the identifiers
+ * `http`, `static`, `example` and `test` and read as four references to
+ * resources that do not exist. Only two shapes are expressions:
+ *
+ *  - a TypeKro ref marker, resource (`__KUBERNETES_REF_<id>_<path>__`) or
+ *    schema (`__KUBERNETES_REF___schema___spec.name__`);
+ *  - a `${...}` interpolation, which the status analyzer emits for a mixed
+ *    template or an already-converted CEL expression. Those DO get analyzed,
+ *    so a hand-written `${"idle"}` is still caught.
+ */
+function stringIsExpression(value) {
+    return value.includes('__KUBERNETES_REF_') || value.includes('${');
+}
+/** Does this plain status string reference at least one resource? */
+function stringReferencesResource(value) {
+    return stringIsExpression(value) && expressionReferencesResource(value);
+}
+/** Does this plain status string reference the instance's own spec? */
+function stringReferencesSchema(value) {
+    return stringIsExpression(value) && expressionReferencesSchema(value);
+}
+function renderLiteral(value) {
+    const rendered = value === undefined
+        ? 'undefined'
+        : typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+            ? JSON.stringify(value)
+            : (JSON.stringify(value) ?? String(value));
+    return rendered.length > MAX_RENDERED_LITERAL_LENGTH
+        ? `${rendered.slice(0, MAX_RENDERED_LITERAL_LENGTH)}…`
+        : rendered;
+}
+function isPlainStatusObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !isKubernetesRef(value) &&
+        !isCelExpression(value));
+}
+/** Is this ref the instance's own spec rather than a graph resource? */
+function isSchemaRef(value) {
+    return SCHEMA_REFERENCE_ROOTS.has(value.resourceId);
+}
+/**
+ * Put ref markers back into the form the author would recognise:
+ * `__KUBERNETES_REF___schema___spec.name__` reads as `${schema.spec.name}`.
+ *
+ * Markers are an internal encoding of template-literal analysis. Printing one
+ * raw makes the diagnostic look like a TypeKro bug rather than a description of
+ * the author's own status field.
+ */
+function humanizeRefMarkers(expression) {
+    return expression.replace(REF_MARKER_PATTERN, (_match, root, fieldPath) => {
+        const readableRoot = root === '__schema__' ? 'schema' : root;
+        return `\${${readableRoot}.${fieldPath}}`;
+    });
+}
+/**
+ * Render an expression as itself, unquoted — `schema.spec.foo`, not
+ * `"schema.spec.foo"`. Quoting a reference would read as a string literal and
+ * misdescribe what the author actually wrote.
+ */
+function renderExpression(expression) {
+    const readable = humanizeRefMarkers(expression);
+    return readable.length > MAX_RENDERED_LITERAL_LENGTH
+        ? `${readable.slice(0, MAX_RENDERED_LITERAL_LENGTH)}…`
+        : readable;
+}
+/** Render a bare schema ref the way the author wrote it: `schema.spec.foo`. */
+function renderSchemaRef(fieldPath) {
+    return renderExpression(`schema.${fieldPath.replace(/^schema\./, '')}`);
+}
+/**
+ * Classify an expression that has already been found to reference no resource.
+ */
+function droppedExpressionLeaf(path, expression) {
+    return expressionReferencesSchema(expression)
+        ? { path, literal: renderExpression(expression), kind: 'schema-reference' }
+        : { path, literal: renderLiteral(expression), kind: 'literal' };
+}
+/**
+ * Walk one status value, appending every leaf KRO would drop from beneath it.
+ */
+function collectLeaves(value, path, nestedStatusCel, found) {
+    if (isKubernetesRef(value)) {
+        const nestedRef = value.__nestedComposition === true;
+        if (!nestedRef) {
+            // A projection of a graph resource anchors the leaf and is exactly what
+            // KRO wants. A bare `schema.spec.*` does not: it is the instance's own
+            // spec, not a resource, so KRO has nothing to project and leaves the
+            // field unset — the same outcome as a literal, by the same mechanism.
+            if (isSchemaRef(value) && typeof value.fieldPath === 'string') {
+                found.push({
+                    path,
+                    literal: renderSchemaRef(value.fieldPath),
+                    kind: 'schema-reference',
+                });
+            }
+            return;
+        }
+        if (!nestedStatusCel || typeof value.fieldPath !== 'string')
+            return;
+        // A nested composition's status field is only as projectable as the
+        // expression the inner composition put behind it: `outer.ready` is a
+        // dropped leaf when the inner `ready` was `true`, and equally when it was a
+        // `schema.spec` passthrough — flattening does not give either one a
+        // resource to project from. Resolve one level and classify what is actually
+        // there. An unresolvable reference is left alone —
+        // `validateStatusCelExpressions` reports those structurally.
+        const innerExpression = lookupNestedExpression(value.resourceId, value.fieldPath.replace(/^status\./, ''), nestedStatusCel);
+        if (innerExpression !== undefined && !expressionReferencesResource(innerExpression)) {
+            found.push(droppedExpressionLeaf(path, innerExpression));
+        }
+        return;
+    }
+    if (isCelExpression(value)) {
+        if (!expressionReferencesResource(value.expression)) {
+            found.push(droppedExpressionLeaf(path, value.expression));
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        // An empty array is itself the dropped value — there are no elements to
+        // blame, so report the field.
+        if (value.length === 0) {
+            found.push({ path, literal: '[]', kind: 'literal' });
+            return;
+        }
+        value.forEach((item, index) => {
+            collectLeaves(item, `${path}[${index}]`, nestedStatusCel, found);
+        });
+        return;
+    }
+    if (isPlainStatusObject(value)) {
+        const entries = Object.entries(value).filter(([key]) => !key.startsWith('__'));
+        if (entries.length === 0) {
+            found.push({ path, literal: '{}', kind: 'literal' });
+            return;
+        }
+        for (const [key, nested] of entries) {
+            if (nested === undefined)
+                continue;
+            collectLeaves(nested, `${path}.${key}`, nestedStatusCel, found);
+        }
+        return;
+    }
+    // Template-literal analysis leaves ref markers and `${...}` interpolations in
+    // plain strings; only those are expressions, and only a resource inside one
+    // anchors the leaf. Everything else here is bare data.
+    if (typeof value === 'string') {
+        if (!stringReferencesResource(value)) {
+            found.push(stringReferencesSchema(value)
+                ? { path, literal: renderExpression(value), kind: 'schema-reference' }
+                : { path, literal: renderLiteral(value), kind: 'literal' });
+        }
+        return;
+    }
+    if (value === undefined)
+        return;
+    found.push({ path, literal: renderLiteral(value), kind: 'literal' });
+}
+/**
+ * Find every status leaf that KRO would leave unset.
+ *
+ * `statusMappings` is the analyzed status mapping (post-CEL-conversion,
+ * pre-static/dynamic split) — the split is exactly what hides the problem, so
+ * the walk has to happen before it.
+ */
+export function findLiteralStatusLeaves(statusMappings, nestedStatusCel) {
+    if (!statusMappings || typeof statusMappings !== 'object')
+        return [];
+    const found = [];
+    for (const [fieldName, fieldValue] of Object.entries(statusMappings)) {
+        // Internal serialization metadata, not user-facing status.
+        if (fieldName.startsWith('__') || fieldValue === undefined)
+            continue;
+        collectLeaves(fieldValue, `status.${fieldName}`, nestedStatusCel, found);
+    }
+    return found;
+}
+/**
+ * Human-readable diagnostic for a set of dropped status leaves.
+ */
+export function formatLiteralStatusLeaves(leaves) {
+    const paths = leaves
+        .map((leaf) => `  - ${leaf.path} = ${leaf.literal}` +
+        (leaf.kind === 'schema-reference' ? ' (schema reference — no resource to project from)' : ''))
+        .join('\n');
+    const schemaNote = leaves.some((leaf) => leaf.kind === 'schema-reference')
+        ? ' A bare `schema.spec.*` is dropped for the same reason a literal is: KRO requires every ' +
+            'status field to refer to a resource, and its status CEL has no `schema` identifier. It ' +
+            'stays valid INSIDE an expression that also references a resource — a template ' +
+            'interpolating both `myService.metadata.name` and `schema.spec.namespace` is anchored by ' +
+            'the resource, and the spec value resolves from there. To surface a spec value on its ' +
+            'own, project it through a resource this graph owns: echo it into a ConfigMap (or an ' +
+            'annotation) you create and read it back.'
+        : '';
+    return ("KRO fills a status field only from the graph's own resources, so it leaves these fields " +
+        'unset and the declared status schema would promise ' +
+        `${leaves.length === 1 ? 'a field' : 'fields'} the instance never carries:\n${paths}\n` +
+        'Project each leaf from a resource this graph owns (for example, put the value in a ' +
+        'ConfigMap you create and reference `myConfigMap.data.<key>`), or remove the field from ' +
+        `the status schema.${schemaNote} Set \`allowLiteralStatus: true\` to log these paths instead ` +
+        'of failing while migrating.');
+}
+/**
+ * Default for `allowLiteralStatus` — i.e. whether a literal status leaf warns
+ * rather than throwing.
+ *
+ * `true` (warn) for now. The check is correct and the diagnostic is actionable,
+ * but literal status leaves are not a rare mistake in existing code: turning
+ * this on as a hard error against the repository's own suite rejected 377
+ * serializations across 69 test files and every bootstrap composition listed in
+ * `test/unit/literal-status-repo-scan.test.ts`. Shipping that as a patch-level
+ * error would break every downstream composition using the same shape, with no
+ * migration window.
+ *
+ * So: warn by default, and let a composition (or a CI job, via the factory
+ * option) opt into the error with `allowLiteralStatus: false` today. Flip this
+ * constant to `false` in the next major once the bundled compositions are
+ * projections — that single edit is the whole migration.
+ */
+export const DEFAULT_ALLOW_LITERAL_STATUS = true;
+/**
+ * Resolve the effective `allowLiteralStatus` setting.
+ *
+ * A factory-level setting wins over the composition's own, so a CI job can run
+ * `graph.factory('kro', { allowLiteralStatus: false }).toYaml()` to enforce
+ * projection across compositions it does not own.
+ */
+export function resolveAllowLiteralStatus(factoryOption, compositionOption) {
+    return factoryOption ?? compositionOption ?? DEFAULT_ALLOW_LITERAL_STATUS;
+}
+//# sourceMappingURL=literal-status.js.map

package/dist/core/validation/literal-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"literal-status.js","sourceRoot":"","sources":["../../../src/core/validation/literal-status.ts"],"names":[],"mappings":"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"}

package/dist/core/validation/structural-spec-dependence.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Structural spec-dependence diagnostics.
+ *
+ * ## The rule
+ *
+ * A `ResourceGraphDefinition` is fixed at build time. `schema.spec.*` values
+ * are *runtime* references: KRO substitutes them per instance, long after the
+ * composition function has run. So a spec value may decide what a field
+ * **contains** (a value position), but it may never decide what the graph
+ * **looks like** — which resources exist, how many list entries there are, or
+ * what an object's keys are called (a structural position).
+ *
+ * When a composition puts a spec value in a structural position, the
+ * composition function still runs: the schema proxy hands the author a
+ * `KubernetesRef` and JavaScript does something plausible-but-wrong with it.
+ * An `if` takes the truthy branch because a proxy object is truthy. A `.map()`
+ * runs exactly once against a sentinel element. `Object.keys()` yields one
+ * fabricated key. The RGD that comes out is well-formed and silently encodes
+ * the build-time guess for every instance.
+ *
+ * This module turns that silence into a KRO-mode serialization error.
+ *
+ * ## What is detected
+ *
+ * Two independent detectors, deliberately narrow so that legitimate
+ * value-position uses (`replicas: spec.replicas`, `` url: `http://${spec.host}` ``,
+ * CEL ternaries in status) stay silent:
+ *
+ * 1. {@link scanRgdResourcesForStructuralSpecArtifacts} — reads the RGD that is
+ *    about to be emitted and reports build-time residue that can only come from
+ *    a structural use. This is evidence-based: every finding is a concrete
+ *    artifact in the output, so there are no false positives by construction.
+ *      - `spec-derived-key`: an object key (or resource id) that is a schema
+ *        reference marker — `{ [spec.key]: v }`, or `Object.fromEntries(...)`
+ *        over a spec collection.
+ *      - `runtime-map-enumerated`: the `__typekroSchemaKey` sentinel, which the
+ *        schema proxy hands out when a composition enumerates a
+ *        `Record<string, V>` spec field (`Object.keys(spec.settings)`,
+ *        `{ ...spec.settings }`) whose keys are not knowable until runtime.
+ *      - `collection-length-collapsed`: a `$item` element sentinel surviving in
+ *        a resource that carries no `forEach` dimension — a `.map()` / `for-of`
+ *        over a spec collection that was flattened to a single element instead
+ *        of being compiled to KRO's `forEach`. A backstop: the serializer
+ *        normally rewrites `$item` either into a `forEach` loop variable or
+ *        into a whole-array reference (`ports: ${schema.spec.ports}`), both of
+ *        which are correct, so this catches only what those miss.
+ *
+ * 2. {@link detectStructuralSpecPredicates} — parses the composition source and
+ *    reports branch predicates that are spec-derived in a form the control-flow
+ *    analyzer cannot compile to `includeWhen`, so the branch was decided at
+ *    build time:
+ *      - `uncompiled-predicate`: the `if` / ternary test reaches the spec only
+ *        through a local binding (`const enabled = spec.enabled; if (enabled)`,
+ *        `const { enabled } = spec;`), so the analyzer's lexical `spec` check
+ *        misses it and no `includeWhen` is attached.
+ *      - `switch-discriminator`: a `switch` on a spec-derived discriminant.
+ *        There is no `switch` lowering at all; the proxy matches no `case`, so
+ *        `default` wins for every instance.
+ *      - `collection-length-read`: `.length` on a spec-derived collection or
+ *        string. The proxy always answers `1`, so the value is a build-time
+ *        constant no matter what the instance holds.
+ *
+ *    A branch only counts when it BUILDS something. That question is settled
+ *    by an allowlist, not by the callee's name: nothing in the source says
+ *    whether an imported binding is a factory, and casing least of all — most
+ *    of this repo's factories are camelCase (`helmRelease`, `serviceAccount`,
+ *    `persistentVolumeClaim`, `observedResource`, `singleton`). So any call in
+ *    the branch counts as building structure unless it is a pure JavaScript
+ *    builtin (`String(…)`, `JSON.stringify(…)`, `Math.max(…)`, `items.map(…)`)
+ *    or a `Cel.*` runtime expression. See {@link isPureHelperCall}.
+ *
+ * ## What is NOT detected
+ *
+ * Static analysis of arbitrary JavaScript cannot be complete, and this check
+ * does not pretend otherwise. Known blind spots:
+ *
+ *   - A predicate laundered through a **helper function** or a module-level
+ *     constant: `if (isEnabled(spec))`. The alias resolver only walks
+ *     top-level `const`/`let` bindings in the composition body.
+ *   - A predicate on a value read back **out of a resource** rather than off
+ *     the spec proxy.
+ *   - Structure decided by a spec value that is **consumed by a factory** and
+ *     collapsed inside it, if the collapse leaves no marker, sentinel or
+ *     `$item` residue in the emitted RGD.
+ *   - A branch whose only call is a **method named like a builtin**
+ *     (`registry.push(…)`, `catalog.map(…)`): the pure-helper allowlist matches
+ *     on the method name without resolving the receiver, so such a call is
+ *     assumed pure. No factory in `src/factories/**` carries one of those
+ *     names, and a new one must not.
+ *   - Anything reached through `eval`, dynamic imports, or a composition whose
+ *     source cannot be parsed (the AST detector degrades to silence, never to
+ *     a false positive).
+ *
+ * Detector 1 is the backstop for most of these: however the structure was
+ * decided, if the decision left residue in the RGD it is reported.
+ */
+import { TypeKroError } from '../errors.js';
+import type { KroResourceTemplate } from '../types/serialization.js';
+/** How a runtime spec value ended up deciding build-time structure. */
+export type StructuralSpecDependenceKind = 'spec-derived-key' | 'runtime-map-enumerated' | 'collection-length-collapsed' | 'uncompiled-predicate' | 'switch-discriminator' | 'collection-length-read';
+/** One place where graph structure was decided by a runtime spec value. */
+export interface StructuralSpecDependenceFinding {
+    readonly kind: StructuralSpecDependenceKind;
+    /**
+     * Where the dependence surfaced: a resource id, or `resource.<id>` plus the
+     * dotted path inside its template, or a source excerpt for AST findings.
+     */
+    readonly location: string;
+    /** Spec paths involved, as `spec.<path>` (may be empty when unresolvable). */
+    readonly specPaths: readonly string[];
+    /** One sentence naming what the emitted RGD actually encodes. */
+    readonly detail: string;
+}
+/**
+ * A place where the composition read the keys of a spec field at build time.
+ * A candidate for a `runtime-map-enumerated` finding, not a finding itself.
+ */
+export interface MapEnumerationSite {
+    /** Source excerpt, e.g. `Object.keys(spec.settings)` or `...spec.app.env`. */
+    readonly location: string;
+    /** The `spec.<path>` whose keys were read. */
+    readonly specPath: string;
+}
+/** Thrown when a KRO-mode RGD would silently encode a build-time guess. */
+export declare class StructuralSpecDependenceError extends TypeKroError {
+    readonly graphName: string;
+    readonly findings: readonly StructuralSpecDependenceFinding[];
+    constructor(message: string, graphName: string, findings: readonly StructuralSpecDependenceFinding[]);
+}
+/**
+ * Report build-time residue in the RGD that is about to be emitted.
+ *
+ * Operates on the serialized manifest rather than on live composition state,
+ * so every finding is backed by a concrete artifact in the output.
+ */
+export declare function scanRgdResourcesForStructuralSpecArtifacts(resources: readonly KroResourceTemplate[]): StructuralSpecDependenceFinding[];
+/**
+ * Branch predicates and `.length` reads the control-flow analyzer does not
+ * compile. See {@link analyzeCompositionSource}.
+ */
+export declare function detectStructuralSpecPredicates(compositionSource: string | undefined): StructuralSpecDependenceFinding[];
+/**
+ * Sites where the composition reads the keys of a spec field at build time.
+ *
+ * These are CANDIDATES, never findings. Enumerating an *object-typed* spec
+ * field is legitimate — the schema proxy is shape-aware and yields the real
+ * declared names — and the AST cannot tell that apart from a map-typed field,
+ * whose keys exist only per instance. Only the emitted RGD can, by leaving the
+ * `__typekroSchemaKey` sentinel behind; but that sentinel carries no path when
+ * it was consumed as a plain string. Reporting these alongside such a finding
+ * lets the message point at the lines worth reading without claiming any one
+ * of them is the culprit.
+ */
+export declare function detectMapEnumerationSites(compositionSource: string | undefined): readonly MapEnumerationSite[];
+/** Render the diagnostic text shared by the error and the escape-hatch warning. */
+export declare function formatStructuralSpecDependence(graphName: string, findings: readonly StructuralSpecDependenceFinding[], mapEnumerationSites?: readonly MapEnumerationSite[]): string;
+/**
+ * Whether the structural spec-dependence check ignores per-composition escape
+ * hatches.
+ *
+ * `TYPEKRO_STRUCTURAL_SPEC=strict` makes every structural use an error even
+ * when the composition sets `allowStructuralSpecDependence`, so a repository
+ * can audit what its shipped graphs still depend on without editing them.
+ * Resolved in ONE place, matching `isStrictCelDiagnosticsEnabled`.
+ */
+export declare function isStructuralSpecDependenceStrict(): boolean;
+/**
+ * Gate KRO-mode serialization on structural spec-dependence.
+ *
+ * Throws {@link StructuralSpecDependenceError} unless `allow` is set, in which
+ * case the same report is logged as a warning naming every path.
+ */
+export declare function assertNoStructuralSpecDependence(input: {
+    graphName: string;
+    resources: readonly KroResourceTemplate[];
+    compositionSource?: string | undefined;
+    allow?: boolean | undefined;
+}): void;
+//# sourceMappingURL=structural-spec-dependence.d.ts.map

package/dist/core/validation/structural-spec-dependence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-spec-dependence.d.ts","sourceRoot":"","sources":["../../../src/core/validation/structural-spec-dependence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+FG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AA0BrE,uEAAuE;AACvE,MAAM,MAAM,4BAA4B,GACpC,kBAAkB,GAClB,wBAAwB,GACxB,6BAA6B,GAC7B,sBAAsB,GACtB,sBAAsB,GACtB,wBAAwB,CAAC;AAE7B,2EAA2E;AAC3E,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAOD,2EAA2E;AAC3E,qBAAa,6BAA8B,SAAQ,YAAY;aAG3C,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,SAAS,+BAA+B,EAAE;gBAFpE,OAAO,EAAE,MAAM,EACC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,+BAA+B,EAAE;CAKvE;AA4DD;;;;;GAKG;AACH,wBAAgB,0CAA0C,CACxD,SAAS,EAAE,SAAS,mBAAmB,EAAE,GACxC,+BAA+B,EAAE,CAoFnC;AAmjBD;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,iBAAiB,EAAE,MAAM,GAAG,SAAS,GACpC,+BAA+B,EAAE,CAEnC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,iBAAiB,EAAE,MAAM,GAAG,SAAS,GACpC,SAAS,kBAAkB,EAAE,CAE/B;AAuCD,mFAAmF;AACnF,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,+BAA+B,EAAE,EACpD,mBAAmB,GAAE,SAAS,kBAAkB,EAAO,GACtD,MAAM,CAkCR;AAED;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,IAAI,OAAO,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC1C,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC7B,GAAG,IAAI,CA2BP"}