typekro 0.4.0 → 0.5.0

package/dist/core/serialization/cel-references.js

@@ -0,0 +1,183 @@
+/**
+ * CEL Reference Serialization
+ *
+ * Functions for converting KubernetesRef objects, CelExpression objects,
+ * and __KUBERNETES_REF__ marker strings into CEL expression strings
+ * suitable for Kro ResourceGraphDefinition YAML output.
+ *
+ * This module is the **single authority** for KubernetesRef → CEL string
+ * conversion.  No other module should duplicate this logic.
+ */
+import { isCelExpression, isKubernetesRef } from '../../utils/type-guards.js';
+import { copyResourceMetadata } from '../metadata/index.js';
+// ---------------------------------------------------------------------------
+// Primitive helpers
+// ---------------------------------------------------------------------------
+/**
+ * Compute the inner CEL path for a {@link KubernetesRef}.
+ *
+ * The special sentinel `__schema__` is normalised to `schema` so that
+ * the resulting path is valid Kro CEL (e.g. `schema.spec.name`).
+ *
+ * @remarks
+ * This is the authoritative implementation.
+ */
+export function getInnerCelPath(ref) {
+    const resourceId = ref.resourceId === '__schema__' ? 'schema' : ref.resourceId;
+    return `${resourceId}.${ref.fieldPath}`;
+}
+// ---------------------------------------------------------------------------
+// Single-ref → CEL
+// ---------------------------------------------------------------------------
+/**
+ * Wrap a {@link KubernetesRef} in `${…}` for Kro YAML output.
+ */
+function generateCelExpression(ref, _context) {
+    const expression = getInnerCelPath(ref);
+    return `\${${expression}}`;
+}
+// ---------------------------------------------------------------------------
+// __KUBERNETES_REF__ marker conversion
+// ---------------------------------------------------------------------------
+/**
+ * Convert `__KUBERNETES_REF__` markers embedded in a string to CEL
+ * expressions.
+ *
+ * These markers are created when schema proxy values are used in
+ * template literals, e.g.:
+ *
+ * - `__KUBERNETES_REF___schema___spec.name__-policy`
+ *   → `${schema.spec.name + "-policy"}`
+ *
+ * Pattern: `__KUBERNETES_REF_{resourceId}_{fieldPath}__`
+ * For schema: `__KUBERNETES_REF___schema___{fieldPath}__`
+ */
+function convertKubernetesRefMarkersTocel(str) {
+    // Pattern handles both regular resource IDs and __schema__ (which has underscores)
+    // The field path is matched with [a-zA-Z0-9.$]+ which captures dot-separated identifiers
+    // like "spec.name", "status.readyReplicas", or "spec.workers.$item.name"
+    const refPattern = /__KUBERNETES_REF_(__schema__|[^_]+)_([a-zA-Z0-9.$]+)__/g;
+    // Fast-path: entire string is a single reference
+    const singleRefMatch = str.match(/^__KUBERNETES_REF_(__schema__|[^_]+)_([a-zA-Z0-9.$]+)__$/);
+    if (singleRefMatch) {
+        const [, resourceId, fieldPath] = singleRefMatch;
+        const celPath = resourceId === '__schema__' ? `schema.${fieldPath}` : `${resourceId}.${fieldPath}`;
+        return `\${${celPath}}`;
+    }
+    // Mixed content → CEL concatenation
+    const parts = [];
+    let lastIndex = 0;
+    let match;
+    refPattern.lastIndex = 0;
+    match = refPattern.exec(str);
+    while (match !== null) {
+        if (match.index > lastIndex) {
+            const textBefore = str.slice(lastIndex, match.index);
+            parts.push(`"${textBefore}"`);
+        }
+        const [, resourceId, fieldPath] = match;
+        const celPath = resourceId === '__schema__' ? `schema.${fieldPath}` : `${resourceId}.${fieldPath}`;
+        parts.push(celPath);
+        lastIndex = match.index + match[0].length;
+        match = refPattern.exec(str);
+    }
+    if (lastIndex < str.length) {
+        const textAfter = str.slice(lastIndex);
+        parts.push(`"${textAfter}"`);
+    }
+    if (parts.length === 1) {
+        return `\${${parts[0]}}`;
+    }
+    return `\${${parts.join(' + ')}}`;
+}
+// ---------------------------------------------------------------------------
+// Recursive resource reference processing
+// ---------------------------------------------------------------------------
+/**
+ * Recursively replace all {@link KubernetesRef} objects with CEL expressions
+ * for Kro YAML output.
+ *
+ * This is the **only** function that should perform this transformation.
+ */
+export function processResourceReferences(obj, context) {
+    if (isKubernetesRef(obj)) {
+        return generateCelExpression(obj, context);
+    }
+    if (isCelExpression(obj)) {
+        if (obj.__isTemplate) {
+            // Template expressions from Cel.template() are already in Kro's mixed-template
+            // format (e.g. "http://${schema.spec.name}.${service.metadata.namespace}").
+            // Pass them through as-is — do NOT convert to CEL concat or re-wrap.
+            return obj.expression;
+        }
+        return `\${${obj.expression}}`;
+    }
+    // Strings containing __KUBERNETES_REF__ markers from template literals
+    if (typeof obj === 'string' && obj.includes('__KUBERNETES_REF_')) {
+        return convertKubernetesRefMarkersTocel(obj);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => processResourceReferences(item, context));
+    }
+    if (obj && typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            // Exclude hidden resourceId property and id field from the final template
+            if (key === '__resourceId' || key === 'id')
+                continue;
+            result[key] = processResourceReferences(value, context);
+        }
+        // Preserve resource metadata (resourceId, readinessEvaluator, etc.) via WeakMap
+        // Also migrates legacy non-enumerable properties from source
+        copyResourceMetadata(obj, result);
+        return result;
+    }
+    return obj;
+}
+// ---------------------------------------------------------------------------
+// Status-mapping serialization
+// ---------------------------------------------------------------------------
+/**
+ * Serialize user-defined status mappings to CEL expressions for Kro schema.
+ *
+ * Only processes dynamic fields that require Kro resolution.
+ */
+export function serializeStatusMappingsToCel(statusMappings) {
+    const celExpressions = {};
+    function serializeValue(value) {
+        if (isKubernetesRef(value)) {
+            return `\${${value.resourceId}.${value.fieldPath}}`;
+        }
+        if (isCelExpression(value)) {
+            if (value.__isTemplate) {
+                // Template expressions from Cel.template() are already in Kro's mixed-template
+                // format (e.g. "http://${schema.spec.name}.${service.metadata.namespace}").
+                // Pass them through as-is — do NOT convert to CEL concat or re-wrap.
+                return value.expression;
+            }
+            return `\${${value.expression}}`;
+        }
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            const nestedExpressions = {};
+            for (const [key, nestedValue] of Object.entries(value)) {
+                nestedExpressions[key] = serializeValue(nestedValue);
+            }
+            return nestedExpressions;
+        }
+        if (typeof value === 'string') {
+            return `\${"${value}"}`;
+        }
+        if (typeof value === 'number') {
+            return `\${${value}}`;
+        }
+        if (typeof value === 'boolean') {
+            return `\${${value}}`;
+        }
+        return `\${""}`;
+    }
+    for (const [fieldName, fieldValue] of Object.entries(statusMappings)) {
+        celExpressions[fieldName] = serializeValue(fieldValue);
+    }
+    return celExpressions;
+}
+//# sourceMappingURL=cel-references.js.map

package/dist/core/serialization/cel-references.js.map

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

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

@@ -4,12 +4,177 @@
  * This module provides the main serialization functions to convert
  * TypeScript resource definitions to Kro ResourceGraphDefinition YAML manifests.
  */
+import { type ASTAnalysisResult } from '../expressions/composition/composition-analyzer.js';
+import { getComponentLogger } from '../logging/index.js';
 import type { DeploymentClosure, TypedResourceGraph } from '../types/deployment.js';
 import type { MagicAssignableShape, ResourceGraphDefinition, SchemaProxy, SerializationOptions } from '../types/serialization.js';
-import type { Enhanced, KroCompatibleType } from '../types.js';
+import type { Enhanced, KroCompatibleType, KubernetesResource } from '../types.js';
 /**
- * Create a new typed resource graph with factory pattern support
- * This is the new API with definition-first parameter and separate builder functions
+ * Separate Enhanced<> resources from deployment closures in the builder result
  */
-export declare function toResourceGraph<TSpec extends KroCompatibleType, TStatus extends KroCompatibleType, TResources extends Record<string, Enhanced<any, any> | DeploymentClosure>>(definition: ResourceGraphDefinition<TSpec, TStatus>, resourceBuilder: (schema: SchemaProxy<TSpec, TStatus>) => TResources, statusBuilder: (schema: SchemaProxy<TSpec, TStatus>, resources: TResources) => TStatus | MagicAssignableShape<TStatus>, options?: SerializationOptions): TypedResourceGraph<TSpec, TStatus>;
+declare function separateResourcesAndClosures<T extends Record<string, Enhanced<any, any> | DeploymentClosure>>(builderResult: T): {
+    resources: Record<string, Enhanced<any, any>>;
+    closures: Record<string, DeploymentClosure>;
+};
+/**
+ * Create a minimal stub resource object for factory calls that were detected
+ * by AST analysis but didn't execute at runtime.
+ *
+ * This happens when a factory call is inside an if-branch that wasn't taken
+ * because the schema proxy's `Symbol.toPrimitive` value didn't match the comparison.
+ * The stub contains just enough info for YAML serialization to produce a valid
+ * resource entry with includeWhen/forEach directives.
+ */
+declare function createStubResource(factoryName: string, resourceId: string): Record<string, unknown> | null;
+import { analyzeStatusMappingTypes, analyzeValueType, detectAndPreserveCelExpressions, isLikelyStaticObject, mergePreservedCelExpressions } from './status-analysis-helpers.js';
+/** @internal Exported for testing only */
+export { separateResourcesAndClosures, createStubResource, detectAndPreserveCelExpressions, mergePreservedCelExpressions, analyzeStatusMappingTypes, analyzeValueType, isLikelyStaticObject, validateResourceGraphName, findResourceByKey, analyzeAndConvertStatusMappings, processCompositionBodyAnalysis, reanalyzeStatusForDirectFactory, wrapWithResourceGraphProxy, };
+export type { StatusAnalysisResult, CompositionBodyAnalysisResult };
+/**
+ * Validate a resource graph name and return the Kubernetes-compatible form.
+ *
+ * @throws {ValidationError} if the name is empty, whitespace-only, not DNS-compliant,
+ *   or exceeds the 253-character Kubernetes limit.
+ * @returns The validated, lowercase-hyphenated Kubernetes name.
+ *
+ * @internal Exported for testing only
+ */
+declare function validateResourceGraphName(name: string | undefined | null): string;
+/**
+ * Find a resource by key name in a resources map.
+ *
+ * Implements multiple matching strategies for cross-composition magic proxy
+ * access (e.g. `composition.database`):
+ * 1. Direct match by generated resource ID (exact)
+ * 2. Smart pattern matching — name parts + kind-based (fuzzy, logged)
+ * 3. Case-insensitive match on resource ID (fuzzy, logged)
+ * 4. Partial matching — key parts contained in resource ID (fuzzy, logged)
+ *
+ * Strategies 2-4 emit a debug-level warning so users can diagnose unexpected
+ * cross-composition references. Strategy 1 is the only silent/exact match.
+ *
+ * @internal Exported for testing only
+ */
+declare function findResourceByKey(key: string | symbol, resourcesWithKeys: Record<string, Enhanced<any, any>>, logger?: ReturnType<ReturnType<typeof getComponentLogger>['child']>): KubernetesResource | undefined;
+/**
+ * Result of analyzing and converting status builder output.
+ *
+ * @internal Exported for testing only
+ */
+interface StatusAnalysisResult {
+    /** The status mapping values returned by the builder (raw, before conversion). */
+    statusMappings: MagicAssignableShape<KroCompatibleType>;
+    /** The final analyzed/converted status mappings (CEL expressions resolved). */
+    analyzedStatusMappings: Record<string, unknown>;
+    /** Field-level analysis of the status mappings. */
+    mappingAnalysis: ReturnType<typeof analyzeStatusMappingTypes>;
+    /** Whether imperative analysis succeeded and provided CEL expressions. */
+    imperativeAnalysisSucceeded: boolean;
+}
+/**
+ * Analyze a status builder function and convert JavaScript expressions to CEL.
+ *
+ * This encapsulates the full pipeline:
+ * 1. Execute the status builder in a context that returns KubernetesRef objects
+ * 2. If imperative, try status builder analysis or fall back to imperative analysis
+ * 3. If declarative, analyze directly
+ * 4. Detect and preserve existing CEL expressions
+ * 5. Convert KubernetesRef objects to CEL via CelConversionEngine
+ * 6. Log migration opportunities
+ *
+ * @internal Exported for testing only
+ */
+declare function analyzeAndConvertStatusMappings<TSpec extends KroCompatibleType, TStatus extends KroCompatibleType, TResources extends Record<string, Enhanced<any, any> | DeploymentClosure>>(definition: ResourceGraphDefinition<TSpec, TStatus>, statusBuilder: (schema: SchemaProxy<TSpec, TStatus>, resources: TResources) => MagicAssignableShape<TStatus>, schema: SchemaProxy<TSpec, TStatus>, resourcesWithKeys: Record<string, Enhanced<any, any>>, serializationLogger: ReturnType<ReturnType<typeof getComponentLogger>['child']>): StatusAnalysisResult;
+/**
+ * Result of analyzing the composition function body for control flow patterns.
+ *
+ * @internal Exported for testing only
+ */
+interface CompositionBodyAnalysisResult {
+    /** The analysis result from the composition body analyzer, or null if unavailable. */
+    compositionAnalysis: ASTAnalysisResult | null;
+    /**
+     * Mutable flag tracking whether `applyAnalysisToResources` has been called.
+     * Wrapped in an object so Biome doesn't hoist it to `const`.
+     */
+    analysisState: {
+        appliedToResources: boolean;
+    };
+}
+/**
+ * Analyze the composition function body for control flow patterns
+ * (if-statements -> includeWhen, for-of loops -> forEach, ternary -> template overrides,
+ * collection aggregates -> status overrides).
+ *
+ * This MUST run before validation because:
+ * 1. Stub resources need to exist before resource ID validation
+ * 2. Status overrides (e.g. .map().join()) need to replace raw marker strings
+ *    before CEL expression validation
+ *
+ * @internal Exported for testing only
+ */
+declare function processCompositionBodyAnalysis(statusMappings: Record<string, unknown> | MagicAssignableShape<KroCompatibleType>, resourcesWithKeys: Record<string, Enhanced<any, any>>, analyzedStatusMappings: Record<string, unknown>, serializationLogger: ReturnType<ReturnType<typeof getComponentLogger>['child']>): CompositionBodyAnalysisResult;
+/**
+ * Re-analyze status mappings specifically for the direct factory pattern.
+ *
+ * When the factory mode is `'direct'`, the status mappings may need different
+ * treatment than the Kro pattern (which is the default analysis target).
+ *
+ * @internal Exported for testing only
+ */
+declare function reanalyzeStatusForDirectFactory<TSpec extends KroCompatibleType, TStatus extends KroCompatibleType>(analysisResults: {
+    hasKubernetesRefs: boolean;
+    statusMappings: MagicAssignableShape<KroCompatibleType>;
+}, analyzedStatusMappings: Record<string, unknown>, resourcesWithKeys: Record<string, Enhanced<any, any>>, schema: SchemaProxy<TSpec, TStatus>, serializationLogger: ReturnType<ReturnType<typeof getComponentLogger>['child']>): Record<string, unknown>;
+/**
+ * Wrap a base resource graph object with a Proxy that enables cross-composition
+ * resource access (e.g. `composition.database`).
+ *
+ * The Proxy intercepts property access for unknown keys and delegates to
+ * `findResourceByKey` to locate matching resources, then creates an external
+ * ref for them.
+ *
+ * @internal Exported for testing only
+ */
+declare function wrapWithResourceGraphProxy<TSpec extends KroCompatibleType, TStatus extends KroCompatibleType>(baseResourceGraph: TypedResourceGraph<TSpec, TStatus>, resourcesWithKeys: Record<string, Enhanced<any, any>>, logger?: ReturnType<ReturnType<typeof getComponentLogger>['child']>): TypedResourceGraph<TSpec, TStatus>;
+/**
+ * Create a typed ResourceGraphDefinition (RGD) from a declarative definition,
+ * a resource builder, and a status builder.
+ *
+ * This is the primary API for defining Kubernetes compositions in TypeKro.
+ * The returned object contains the serialized YAML for the RGD and can be
+ * deployed via `deploy()` in both Direct and Kro modes.
+ *
+ * @typeParam TSpec - The arktype schema for the custom resource's spec
+ * @typeParam TStatus - The arktype schema for the custom resource's status
+ * @typeParam TResources - The shape of resources returned by the resource builder
+ *
+ * @param definition - The RGD metadata: name, apiVersion, kind, spec schema, status schema
+ * @param resourceBuilder - Function receiving a schema proxy, returns Kubernetes resources
+ * @param statusBuilder - Function receiving schema proxy + resources, returns status shape
+ * @param options - Optional serialization options (e.g., custom CEL prefix)
+ * @returns A `TypedResourceGraph` containing the serialized RGD and deploy/toYaml methods
+ *
+ * @example
+ * ```typescript
+ * const webapp = toResourceGraph(
+ *   {
+ *     name: 'webapp',
+ *     apiVersion: 'apps.example.com/v1alpha1',
+ *     kind: 'WebApp',
+ *     spec: type({ name: 'string', replicas: 'number' }),
+ *     status: type({ ready: 'boolean', url: 'string' }),
+ *   },
+ *   (schema) => ({
+ *     deploy: Deployment({ name: schema.spec.name, replicas: schema.spec.replicas }),
+ *     svc: Service({ name: schema.spec.name }),
+ *   }),
+ *   (schema, resources) => ({
+ *     ready: Cel.expr<boolean>(resources.deploy.status.readyReplicas, ' > 0'),
+ *     url: Cel.template('https://%s', schema.spec.name),
+ *   }),
+ * );
+ * ```
+ */
+export declare function toResourceGraph<TSpec extends KroCompatibleType, TStatus extends KroCompatibleType, TResources extends Record<string, Enhanced<any, any> | DeploymentClosure>>(definition: ResourceGraphDefinition<TSpec, TStatus>, resourceBuilder: (schema: SchemaProxy<TSpec, TStatus>) => TResources, statusBuilder: (schema: SchemaProxy<TSpec, TStatus>, resources: TResources) => MagicAssignableShape<TStatus>, options?: SerializationOptions): TypedResourceGraph<TSpec, TStatus>;
 //# sourceMappingURL=core.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/core/serialization/core.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH,OAAO,KAAK,EACV,iBAAiB,EAKjB,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACV,oBAAoB,EACpB,uBAAuB,EAEvB,WAAW,EACX,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAEV,QAAQ,EACR,iBAAiB,EAElB,MAAM,aAAa,CAAC;AA8ZrB;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,SAAS,iBAAiB,EAC/B,OAAO,SAAS,iBAAiB,EAEjC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,iBAAiB,CAAC,EAEzE,UAAU,EAAE,uBAAuB,CAAC,KAAK,EAAE,OAAO,CAAC,EAEnD,eAAe,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,UAAU,EAEpE,aAAa,EAAE,CACb,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,EACnC,SAAS,EAAE,UAAU,KAClB,OAAO,GAAG,oBAAoB,CAAC,OAAO,CAAC,EAC5C,OAAO,CAAC,EAAE,oBAAoB,GAC7B,kBAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,CAGpC"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/core/serialization/core.ts"],"names":[],"mappings":"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"}