typekro 0.33.10 → 0.35.0

package/dist/core/validation/cel-dialect.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Dual-dialect compatibility check for emitted status CEL.
+ *
+ * TypeKro emits one CEL expression per dynamic status field and then runs it
+ * through **two different engines**: `cel-js` evaluates it locally in direct
+ * mode, and `cel-go` (inside the KRO controller, with KRO's type environment)
+ * evaluates it in Kro mode. The two disagree in ways that only surface when the
+ * expression meets real data on a live cluster — one engine returns a value and
+ * the other rejects the expression or blows up on a missing field.
+ *
+ * This module runs every emitted status expression through cel-js's own parser
+ * **and** a curated denylist of the divergences we have confirmed, so an
+ * expression that only one engine accepts fails at serialization time with the
+ * expression, the status leaf it came from, and the dialect that rejects it.
+ *
+ * ## cel-js's parser is not the CEL grammar
+ *
+ * cel-js 0.8.2 parses a proper subset of CEL, so a `parse()` failure is a fact
+ * about **direct mode only**. Its `atomicExpression` rule takes a postfix
+ * `.`/`[` after an identifier (and after a map literal, and one index after a
+ * list literal) and nowhere else, while the spec's `Member` production takes a
+ * postfix on any `Member` and `Primary` includes both `LITERAL` and
+ * `"(" Expr ")"` — so `"x".size()`, `[1,2].size()`, `(a).b` and `size(a).b` are
+ * all valid CEL that cel-js rejects, and its lexer has neither the exponent
+ * `FLOAT_LIT` form nor the `r`/`b`/triple-quoted `STRING_LIT` forms. Inferring
+ * "cel-go would reject this too" from a cel-js parse failure is therefore
+ * unsound, and the parse half does not do it: it sorts a failure into
+ * `not-valid-cel` (a form the *spec's* grammar has no token or production for),
+ * `cel-js-rejects-spec-cel` (a positively identified cel-js shortfall — a real
+ * divergence) or `cel-js-parse-failure` (no verdict beyond direct mode).
+ *
+ * Identifying a shortfall *somewhere* in a rejected expression is not by itself
+ * a divergence, because the parse may have failed for an unrelated reason: the
+ * shortfall in `"x".size() +` is real and the expression is still unfinished,
+ * and cel-go refuses it exactly as cel-js does. So the divergence bucket is
+ * earned rather than assumed — every identified shortfall is rewritten into a
+ * spelling of the same spec production that cel-js does have (`"x".size()` into
+ * `__typekro_recv0.size()`, `1e3` into `0.0`), the rest of the text is left
+ * untouched, and cel-js is asked again. Only a rewrite that parses proves the
+ * shortfall was the whole reason; anything else falls to `cel-js-parse-failure`.
+ *
+ * ## Why a denylist rather than a real cel-go
+ *
+ * cel-go is a Go library; there is no in-process cel-go for a TypeScript
+ * serializer to consult, and shelling out to one would make `toYaml()` depend
+ * on a Go toolchain. The denylist is therefore a deliberately *curated*,
+ * documented set of confirmed divergences rather than a general type checker.
+ * It is meant to grow: each rule below records what was observed and on which
+ * engine, so a new entry can be justified the same way.
+ *
+ * ## What may fail strict mode
+ *
+ * A rule may fail strict mode only when the two engines genuinely **diverge** on
+ * the form: there is data for which one engine yields a value and the other does
+ * not. That bar rules out two tempting kinds of rule, and both are deliberately
+ * excluded rather than merely unwritten.
+ *
+ * - **Anything that needs a CEL *type* to be a divergence.** Syntax does not
+ *   establish a type. `x[0]` is a list index against one schema and a map lookup
+ *   against another; `"k" in e` is fine when `e` is a map and rejected when
+ *   cel-go's type env has typed `e` as a message. The real types live in the
+ *   referenced resources' Kubernetes schemas, and nothing at this call site has
+ *   them: the check receives the serialized status map — expression text naming
+ *   graph resources by id — and TypeKro's `Enhanced<>` types are erased before
+ *   serialization runs. A rule that guesses a type from bracket shape fails
+ *   strict mode on valid CEL, so such rules are reported as notes instead.
+ * - **Forms both engines treat the same.** Indexing a required list inside a
+ *   logical chain is the worked example: `size(l) > 0 && l[0].f != ""` returns
+ *   `false` on an empty `l` in both engines (cel-js short-circuits, cel-go
+ *   absorbs the error under a deciding `false`), and an out-of-range index
+ *   errors on both. Nothing diverges, so nothing is reported.
+ *
+ * What the bar does **not** license is a claim about what KRO ultimately does
+ * with the field. Every rule here reasons about the grammar and about published
+ * engine behaviour; none of them models cel-go's *type checker*, which runs
+ * after the parse with KRO's type environment and function set and rejects
+ * plenty of grammatical CEL — `1.string()` parses on any conformant grammar and
+ * the checker still refuses it, `string` being a global conversion function
+ * rather than a member, and an unknown member function goes the same way. So a
+ * finding says "direct mode can never evaluate this field" where that is proven,
+ * and leaves KRO's verdict open. A rule stays a `divergence` on the strength of
+ * the disagreement it does establish: the engines differ on the *form*, at a
+ * stage that needs no type environment, which makes the emitted CEL defective
+ * for one of the two targets TypeKro serializes for whatever the other decides.
+ *
+ * Findings that do not clear the bar are still worth surfacing, so each rule
+ * declares a {@link CelDialectFindingKind}: `divergence` findings abort
+ * serialization in strict mode, `note` findings never do and are logged in both
+ * modes. Strictness otherwise follows the shared CEL diagnostics convention
+ * (`strictCelDiagnostics` factory option, `TYPEKRO_STRICT_CEL=1`).
+ */
+/**
+ * The CEL engine that rejects — or diverges on — an expression.
+ *
+ * `'both'` marks a form neither engine accepts, which is a defect but not a
+ * divergence. `'unchecked'` is not an engine at all: it marks a finding where no
+ * verdict was reached, because the expression was past the analysis budget.
+ */
+export type CelDialect = 'cel-js' | 'cel-go' | 'both' | 'unchecked';
+/**
+ * Whether a finding may fail strict mode.
+ *
+ * - `divergence` — the two engines demonstrably disagree on this form, with no
+ *   appeal to a type the checker cannot see. Fails strict mode.
+ * - `note` — worth reporting, but not a proven divergence: either both engines
+ *   reject the form (a defect, but the same defect on each), or the divergence
+ *   is conditional on a type the checker has no way to establish, or no verdict
+ *   was reached at all. Never fails strict mode, in either strictness setting.
+ */
+export type CelDialectFindingKind = 'divergence' | 'note';
+/** Identifier for a curated dual-dialect rule. */
+export type CelDialectRuleId = 'not-valid-cel' | 'cel-js-rejects-spec-cel' | 'cel-js-parse-failure' | 'has-index-argument' | 'in-on-list-entry' | 'guard-after-use-in-logical-chain' | 'heterogeneous-map-literal' | 'expression-too-large';
+/**
+ * Largest expression this module will analyze, in characters.
+ *
+ * Both halves of the check cost roughly a microsecond per character — cel-js's
+ * parser dominates — so the cost is linear in the length of the expression and
+ * the only way it can run away is for the expression itself to run away.
+ *
+ * The budget is set from what TypeKro actually emits. Across the unit suite the
+ * median status expression is under 100 characters, the 99th percentile is
+ * ~1.6k, and the largest authored one is ~3.3k. 16 KiB leaves roughly five
+ * times the headroom over the largest real expression while capping the check
+ * at ~16ms for any single leaf.
+ *
+ * Anything past this is not an authored status field. The known source is a
+ * nested composition whose inlined status re-expands into itself, doubling per
+ * level until the depth limit stops it — which yields a multi-megabyte
+ * expression that no engine can use: cel-js needs seconds to parse it on every
+ * direct-mode reconcile, and a ResourceGraphDefinition carrying it is past the
+ * Kubernetes object size limit, so the API server refuses it outright.
+ */
+export declare const CEL_DIALECT_MAX_EXPRESSION_LENGTH = 16384;
+/** A single dual-dialect incompatibility found in an emitted expression. */
+export interface CelDialectFinding {
+    /** Which curated rule matched. */
+    readonly rule: CelDialectRuleId;
+    /** Whether this finding may fail strict mode. */
+    readonly kind: CelDialectFindingKind;
+    /** The engine that rejects or diverges on this expression. */
+    readonly dialect: CelDialect;
+    /** The status leaf path the expression was emitted for. */
+    readonly field: string;
+    /** The emitted CEL expression. */
+    readonly expression: string;
+    /** The offending fragment, when the rule can isolate one. */
+    readonly fragment?: string;
+    /** What the engine does with it. */
+    readonly message: string;
+    /** How to write it so both engines accept it. */
+    readonly suggestion: string;
+}
+/**
+ * The curated denylist.
+ *
+ * Every entry names the engine that rejects the form, whether the entry counts
+ * as a divergence, and the observation behind it. Keep this table and
+ * {@link checkCelDialectCompatibility} in step.
+ */
+export declare const CEL_DIALECT_RULES: readonly {
+    readonly id: CelDialectRuleId;
+    readonly kind: CelDialectFindingKind;
+    readonly dialect: CelDialect;
+    readonly summary: string;
+    readonly observed: string;
+}[];
+/** True when any finding in the set may fail strict mode. */
+export declare function hasCelDialectDivergence(findings: readonly CelDialectFinding[]): boolean;
+/**
+ * What the last run (or runs) of the check cost, in units that do not depend on
+ * the machine it ran on.
+ *
+ * Wall-clock is the wrong instrument for the property that actually matters
+ * here — that the work is linear in the length of the expression rather than
+ * quadratic in its nesting — because a slow CI box and a quadratic regression
+ * look alike. These counters do not: `indexedCharacters` is the total text
+ * scanned to build bracket indexes and `lookups` the total number of "where
+ * does this close?" questions asked, so doubling the input must roughly double
+ * both.
+ */
+export interface CelDialectWorkStats {
+    /** How many bracket indexes were built. */
+    readonly indexBuilds: number;
+    /** Total characters scanned across those builds. */
+    readonly indexedCharacters: number;
+    /** Total bracket-match questions answered out of an index. */
+    readonly lookups: number;
+}
+/** Read the work counters. */
+export declare function celDialectWorkStats(): CelDialectWorkStats;
+/** Zero the work counters, so one check can be measured on its own. */
+export declare function resetCelDialectWorkStats(): void;
+/**
+ * Offset of the first character of `expression` no CEL token can carry, or `-1`
+ * when the spec's lexical grammar covers the text end to end.
+ *
+ * Exported for the same reason {@link celDialectParseProof} is: the coverage
+ * scan is half of what "cel-js parsed it" means here, so it has to be checkable
+ * from outside rather than taken on trust. `-1` is the precondition for every
+ * verdict this module draws from a cel-js parse — see
+ * {@link firstUnlexableOffset} for why `parse()` alone is not enough.
+ */
+export declare function celDialectLexicalGap(expression: string): number;
+/**
+ * The rewritten expression a `cel-js-rejects-spec-cel` divergence stands on, or
+ * `undefined` when there is none.
+ *
+ * Exported so the proof can be reproduced rather than taken on trust: the
+ * returned text differs from `expression` only where a confirmed cel-js
+ * shortfall was replaced by a same-production spelling cel-js has, cel-js's
+ * lexer carries every character of it and cel-js parses it. An expression with
+ * no identified shortfall, one whose own text is not lexically CEL, or one where
+ * taking the shortfalls away still leaves text cel-js refuses, yields
+ * `undefined` — and that is exactly the case the check refuses to call a
+ * divergence.
+ */
+export declare function celDialectParseProof(expression: string): string | undefined;
+/**
+ * Check one emitted status CEL expression against both dialects.
+ *
+ * @param expression The emitted CEL, without any `${...}` wrapper.
+ * @param field The status leaf path the expression belongs to.
+ */
+export declare function checkCelDialectCompatibility(expression: string, field: string): CelDialectFinding[];
+/**
+ * Check every emitted status CEL expression in a serialized status map.
+ *
+ * Accepts the nested shape `serializeStatusMappingsToCel` produces: leaves are
+ * `${...}`-wrapped CEL strings, and objects/arrays nest arbitrarily. Values
+ * that carry no CEL are skipped, so plain literal status fields cost nothing.
+ */
+export declare function collectStatusCelDialectFindings(statusCel: Readonly<Record<string, unknown>>): CelDialectFinding[];
+/**
+ * Longest expression or fragment a report will quote, in characters.
+ *
+ * The analysis budget already keeps `checkCelDialectCompatibility` from
+ * returning an oversized `expression`, but the formatter is exported and takes
+ * findings from wherever the caller got them — so it bounds what it quotes on
+ * its own rather than trusting its input. A report is read by a human; past a
+ * couple of lines per finding the excerpt stops helping and starts being the
+ * thing that fills the log.
+ */
+export declare const CEL_DIALECT_MAX_EXCERPT_LENGTH = 400;
+/** Render findings as a multi-line report naming the leaf, dialect and expression. */
+export declare function formatCelDialectFindings(findings: readonly CelDialectFinding[]): string;
+//# sourceMappingURL=cel-dialect.d.ts.map

package/dist/core/validation/cel-dialect.d.ts.map

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