typekro 0.5.0 → 0.8.0

package/dist/core/serialization/kro-post-processing.js

@@ -0,0 +1,103 @@
+/**
+ * KRO YAML Post-Processing Utilities
+ *
+ * Shared helpers for applying ternary conditionals to resource data before
+ * YAML serialization. Used by both the toResourceGraph pipeline (core.ts)
+ * and the KRO factory deployment path (kro-factory.ts).
+ *
+ * Extracted to avoid circular dependencies between core.ts and kro-factory.ts.
+ *
+ * Note: KRO 0.9+ omit() wrapping for optional fields is NOT in this module —
+ * it's applied inline during ref-to-CEL conversion via
+ * `SerializationContext.omitFields` in `cel-references.ts`. That keeps
+ * `has() ? ... : omit()` generation as a structured operation on
+ * KubernetesRef objects instead of a post-hoc regex rewrite of the
+ * serialized YAML string.
+ */
+/**
+ * Apply ternary conditionals to resource data by replacing raw marker sections
+ * with CEL conditional expressions. This runs BEFORE processResourceReferences
+ * so that the markers within the truthy branch get converted to mixed-template
+ * CEL format by the normal pipeline.
+ *
+ * For `spec.redisUrl ? \`redis:\n  url: ${spec.redisUrl}\` : ''`, the raw
+ * settings.yml string contains the redis section with a __KUBERNETES_REF__
+ * marker. This function replaces that section with a CEL conditional that
+ * processResourceReferences will then convert to the final mixed-template form.
+ *
+ * FRAGILE: operates on raw string values inside resource data by substring
+ * matching. The `proxySection` must be byte-identical to what was extracted
+ * by `extractTernaryConditionals` in schema.ts — meaning the composition's
+ * string construction (typically a template literal) and the re-execution
+ * pass both need to produce the same newline/indentation layout. If a
+ * composition author post-processes the settings string, interpolates it
+ * through another templating layer, or if the extraction heuristic in
+ * schema.ts is updated to include/exclude different surrounding context,
+ * the match will fail silently and the ternary will not be applied.
+ *
+ * Tracked for replacement with AST-based detection in
+ * https://github.com/yehudacohen/typekro/issues/57
+ */
+export function applyTernaryConditionalsToResources(resources, conditionals) {
+    for (const { proxySection, conditionField } of conditionals) {
+        replaceInResources(resources, proxySection, (matchedSection) => {
+            // Split the matched section on markers so we can separately handle
+            // LITERAL text (needs CEL string-literal escaping) and CEL REFERENCES
+            // (must NOT be escaped — they're emitted as `string(ref)` concatenation).
+            const markerRe = /__KUBERNETES_REF_(__schema__|[^_]+)_([a-zA-Z0-9.$]+)__/g;
+            let celTruthy = '';
+            let lastIndex = 0;
+            let m = markerRe.exec(matchedSection);
+            while (m !== null) {
+                if (m.index > lastIndex) {
+                    celTruthy += escapeCelStringLiteral(matchedSection.slice(lastIndex, m.index));
+                }
+                const resourceId = m[1];
+                const fieldPath = m[2];
+                const celPath = resourceId === '__schema__' ? `schema.${fieldPath}` : `${resourceId}.${fieldPath}`;
+                celTruthy += `" + string(${celPath}) + "`;
+                lastIndex = m.index + m[0].length;
+                m = markerRe.exec(matchedSection);
+            }
+            if (lastIndex < matchedSection.length) {
+                celTruthy += escapeCelStringLiteral(matchedSection.slice(lastIndex));
+            }
+            return `\${has(schema.spec.${conditionField}) ? "${celTruthy}" : ""}`;
+        });
+    }
+}
+/**
+ * Escape a literal text chunk for inclusion inside a CEL double-quoted
+ * string. Must handle backslash, double quote, newline, carriage return,
+ * and tab — in that order, so that the backslash escape doesn't re-escape
+ * the backslashes introduced by later substitutions.
+ *
+ * Previous implementation only escaped newlines, which left literal `"` and
+ * `\` characters unescaped. That was a latent bug: any composition that
+ * emitted quoted YAML values or Windows-style paths inside a ternary branch
+ * would produce malformed CEL and the KRO reconciler would reject the RGD.
+ */
+function escapeCelStringLiteral(literal) {
+    return literal
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+}
+/** Recursively find and replace string sections in resource data. */
+function replaceInResources(obj, section, replacer) {
+    if (!obj || typeof obj !== 'object')
+        return;
+    const record = obj;
+    for (const key of Object.keys(record)) {
+        const val = record[key];
+        if (typeof val === 'string' && val.includes(section)) {
+            record[key] = val.replaceAll(section, replacer(section));
+        }
+        else if (typeof val === 'object' && val !== null) {
+            replaceInResources(val, section, replacer);
+        }
+    }
+}
+//# sourceMappingURL=kro-post-processing.js.map

package/dist/core/serialization/kro-post-processing.js.map

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

package/dist/core/serialization/schema.d.ts

@@ -6,8 +6,66 @@
  * from resource maps.
  */
 import type { Type } from 'arktype';
-import type { SchemaDefinition } from '../types/serialization.js';
+import type { KroSimpleSchemaWithMetadata, SchemaDefinition } from '../types/serialization.js';
 import type { KroCompatibleType, KroSimpleSchema, KubernetesResource } from '../types.js';
+/**
+ * Extract literal default values from `spec.field ?? literalValue` patterns
+ * in a composition function's source code.
+ *
+ * **FAST PATH — NOT AUTHORITATIVE.** This regex-based extraction runs first
+ * to catch the common case where a composition uses `spec.X ?? 'literal'`
+ * with a literal right-hand side. It is intentionally conservative:
+ *
+ * - Both `??` and the literal must be on the same source line.
+ * - The literal must be a string, number, boolean, or minified !0/!1 form.
+ * - The right-hand side cannot be a constant, variable, template literal,
+ *   function call, or expression involving other spec fields.
+ *
+ * Anything this regex misses is caught by {@link resolveDefaultsByReExecution}
+ * (Phase 2), which actually executes the composition function with optional
+ * fields set to `undefined` and observes the concrete resolved values. Phase 2
+ * is the authoritative source; this function only exists to short-circuit
+ * the common case so the heavy re-execution doesn't need to compare every
+ * field for every composition.
+ *
+ * In KRO mode, `??` doesn't trigger for proxy objects (they're truthy).
+ * Instead, we detect these patterns via fn.toString() and add
+ * `| default=<value>` annotations to the KRO SimpleSchema so that KRO
+ * uses the intended default when the field isn't provided in the CR.
+ *
+ * NOTE: `.orValue()` is NOT supported in KRO resource templates (only in
+ * status CEL). Schema `| default=` is the correct mechanism for resource
+ * template defaults.
+ *
+ * Handles:
+ * - `spec.field ?? 'string'` or `spec.field ?? "string"`
+ * - `spec.field ?? 123` (numbers)
+ * - `spec.field ?? true/false` (booleans, including minified !0/!1)
+ * - `spec.parent?.child ?? value` (optional chaining)
+ */
+export declare function extractNullishDefaults(fnSource: string): Record<string, string | number | boolean>;
+/**
+ * Placeholder value passed in place of required spec fields during the
+ * defaults-extraction re-execution. Any captured leaf value that IS this
+ * string, CONTAINS this string as a substring (from template-literal
+ * interpolation), or is NaN (from arithmetic coercion of the string) is
+ * filtered out by the sentinel-detection logic in `extractDefaultsByComparison`
+ * so it never gets recorded as a real schema default.
+ *
+ * The choice of a string (rather than a Symbol or object) is deliberate:
+ *   - String concatenation preserves the token so template-literal usage
+ *     produces a clearly-identifiable captured value (e.g. `"__typekro_default__-cfg"`).
+ *   - Truthiness matches the real proxy behavior (proxies are truthy), so
+ *     `if (spec.requiredField)` takes the same branch in both runs.
+ *   - Numeric contexts coerce to NaN in both runs (proxies also coerce to
+ *     NaN because functions have no numeric value), so arithmetic-derived
+ *     NaN values are symmetric across runs and don't produce spurious defaults.
+ *
+ * If the propagation ever drifts out of this sentinel's shape (e.g. someone
+ * introduces a Symbol-based sentinel), update `isSentinelDerivedValue` below
+ * to match.
+ */
+export declare const REQUIRED_FIELD_SENTINEL = "__typekro_default__";
 /**
  * Convert an Arktype schema to a Kro-compatible schema definition.
  *
@@ -22,7 +80,7 @@ export declare function arktypeToKroSchema(name: string, schemaDefinition: {
     kind: string;
     spec: Type;
     status: Type;
-}, _resources?: Record<string, KubernetesResource>, statusMappings?: Record<string, unknown>): KroSimpleSchema;
+}, resources?: Record<string, KubernetesResource>, statusMappings?: Record<string, unknown>, nestedStatusCel?: Record<string, string>): KroSimpleSchemaWithMetadata;
 /**
  * Generate a minimal Kro schema from a resource map (no Arktype).
  *
@@ -41,5 +99,5 @@ export declare function generateKroSchema(name: string, _resources: Record<strin
  * @see {@link arktypeToKroSchema} for the low-level variant.
  * @see {@link generateKroSchema} for a simple variant without Arktype.
  */
-export declare function generateKroSchemaFromArktype<TSpec extends KroCompatibleType, TStatus extends KroCompatibleType>(name: string, schemaDefinition: SchemaDefinition<TSpec, TStatus>, resources?: Record<string, KubernetesResource>, statusMappings?: Record<string, unknown>): KroSimpleSchema;
+export declare function generateKroSchemaFromArktype<TSpec extends KroCompatibleType, TStatus extends KroCompatibleType>(name: string, schemaDefinition: SchemaDefinition<TSpec, TStatus>, resources?: Record<string, KubernetesResource>, statusMappings?: Record<string, unknown>, nestedStatusCel?: Record<string, string>): KroSimpleSchemaWithMetadata;
 //# sourceMappingURL=schema.d.ts.map

package/dist/core/serialization/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/core/serialization/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAEpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA0G1F;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,IAAI,CAAC;CACd,EACD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAC/C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvC,eAAe,CA6BjB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAC7C,eAAe,CAajB;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,SAAS,iBAAiB,EAC/B,OAAO,SAAS,iBAAiB,EAEjC,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,EAClD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAC9C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvC,eAAe,CAEjB"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/core/serialization/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAIpC,OAAO,KAAK,EACV,2BAA2B,EAC3B,gBAAgB,EAEjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA4G1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CA0BlG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AA8a7D;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,IAAI,CAAC;CACd,EACD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAC9C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACvC,2BAA2B,CA0G7B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAC7C,eAAe,CAajB;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,SAAS,iBAAiB,EAC/B,OAAO,SAAS,iBAAiB,EAEjC,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,EAClD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAC9C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACvC,2BAA2B,CAE7B"}