@kustodian/generator 1.0.0

package/src/validation/graph.ts

@@ -0,0 +1,125 @@
+import type { TemplateType } from '@kustodian/schema';
+
+import {
+  create_node_id,
+  is_parse_error,
+  parse_dependency_ref,
+  resolve_dependency_ref,
+} from './reference.js';
+import type { BuildGraphResultType, GraphNodeType, GraphValidationErrorType } from './types.js';
+
+/**
+ * Builds a dependency graph from templates.
+ *
+ * Uses a two-pass algorithm:
+ * 1. First pass: Create nodes for all kustomizations
+ * 2. Second pass: Resolve dependencies and validate references
+ *
+ * @param templates - Array of templates to build graph from
+ * @returns Graph nodes and any errors encountered during building
+ */
+export function build_dependency_graph(templates: TemplateType[]): BuildGraphResultType {
+  const nodes = new Map<string, GraphNodeType>();
+  const errors: GraphValidationErrorType[] = [];
+
+  // First pass: Create all nodes
+  for (const template of templates) {
+    const template_name = template.metadata.name;
+
+    for (const kustomization of template.spec.kustomizations) {
+      const node_id = create_node_id(template_name, kustomization.name);
+
+      nodes.set(node_id, {
+        id: node_id,
+        template: template_name,
+        kustomization: kustomization.name,
+        dependencies: [],
+      });
+    }
+  }
+
+  // Second pass: Resolve dependencies
+  for (const template of templates) {
+    const template_name = template.metadata.name;
+
+    for (const kustomization of template.spec.kustomizations) {
+      const node_id = create_node_id(template_name, kustomization.name);
+      const resolved_dependencies: string[] = [];
+
+      for (const dep of kustomization.depends_on ?? []) {
+        // Parse the dependency reference
+        const parse_result = parse_dependency_ref(dep);
+
+        if (is_parse_error(parse_result)) {
+          // Add source to the error
+          errors.push({
+            ...parse_result,
+            source: node_id,
+          });
+          continue;
+        }
+
+        // Resolve to full node ID
+        const target_id = resolve_dependency_ref(parse_result, template_name);
+
+        // Check for self-reference
+        if (target_id === node_id) {
+          errors.push({
+            type: 'self_reference',
+            node: node_id,
+            message: `Kustomization '${node_id}' cannot depend on itself`,
+          });
+          continue;
+        }
+
+        // Check if target exists
+        if (!nodes.has(target_id)) {
+          errors.push({
+            type: 'missing_reference',
+            source: node_id,
+            target: target_id,
+            message: `Kustomization '${node_id}' depends on '${target_id}' which does not exist`,
+          });
+          continue;
+        }
+
+        resolved_dependencies.push(target_id);
+      }
+
+      // Update node with resolved dependencies
+      // We need to create a new node since GraphNodeType has readonly properties
+      if (resolved_dependencies.length > 0) {
+        const existing_node = nodes.get(node_id);
+        if (existing_node) {
+          nodes.set(node_id, {
+            ...existing_node,
+            dependencies: resolved_dependencies,
+          });
+        }
+      }
+    }
+  }
+
+  return { nodes, errors };
+}
+
+/**
+ * Gets all nodes from the graph as an array.
+ *
+ * @param nodes - Map of graph nodes
+ * @returns Array of all nodes
+ */
+export function get_all_nodes(nodes: Map<string, GraphNodeType>): GraphNodeType[] {
+  return Array.from(nodes.values());
+}
+
+/**
+ * Gets a node by its ID.
+ *
+ * @param nodes - Map of graph nodes
+ * @param id - Node ID to look up
+ * @returns The node or undefined if not found
+ */
+export function get_node(nodes: Map<string, GraphNodeType>, id: string): GraphNodeType | undefined {
+  return nodes.get(id);
+}

package/src/validation/index.ts

@@ -0,0 +1,92 @@
+import { type ResultType, failure, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+import type { TemplateType } from '@kustodian/schema';
+
+import { detect_cycles } from './cycle-detection.js';
+import { build_dependency_graph } from './graph.js';
+import type { GraphValidationResultType } from './types.js';
+
+// Re-export types
+export type {
+  BuildGraphResultType,
+  CycleDetectionResultType,
+  CycleErrorType,
+  DependencyRefType,
+  GraphNodeType,
+  GraphValidationErrorType,
+  GraphValidationResultType,
+  InvalidReferenceErrorType,
+  MissingReferenceErrorType,
+  SelfReferenceErrorType,
+} from './types.js';
+
+// Re-export functions
+export { build_dependency_graph, get_all_nodes, get_node } from './graph.js';
+export { detect_cycles, has_cycles } from './cycle-detection.js';
+export {
+  create_node_id,
+  is_parse_error,
+  parse_dependency_ref,
+  parse_node_id,
+  resolve_dependency_ref,
+} from './reference.js';
+
+/**
+ * Validates the dependency graph for a set of templates.
+ *
+ * Performs the following validations:
+ * 1. Reference validation: Ensures all `depends_on` references point to existing kustomizations
+ * 2. Self-reference detection: Detects kustomizations that depend on themselves
+ * 3. Cycle detection: Detects circular dependencies using DFS
+ * 4. Topological sorting: Computes deployment order if the graph is valid
+ *
+ * @param templates - Array of templates to validate
+ * @returns Detailed validation result including errors and deployment order
+ */
+export function validate_dependency_graph(templates: TemplateType[]): GraphValidationResultType {
+  // Build the dependency graph (validates references)
+  const { nodes, errors } = build_dependency_graph(templates);
+
+  // Detect cycles in the graph
+  const { cycles, topological_order } = detect_cycles(nodes);
+
+  // Combine all errors
+  const all_errors = [...errors, ...cycles];
+
+  const result: GraphValidationResultType = {
+    valid: all_errors.length === 0,
+    errors: all_errors,
+  };
+
+  if (topological_order !== null) {
+    return { ...result, topological_order };
+  }
+
+  return result;
+}
+
+/**
+ * Validates the dependency graph and returns a Result type.
+ *
+ * This is the main integration point for the generator pipeline.
+ * Returns a success with the topological order, or a failure with
+ * detailed error information.
+ *
+ * @param templates - Array of templates to validate
+ * @returns Result with topological order on success, or error on failure
+ */
+export function validate_dependencies(
+  templates: TemplateType[],
+): ResultType<string[], KustodianErrorType> {
+  const result = validate_dependency_graph(templates);
+
+  if (!result.valid) {
+    const error_messages = result.errors.map((e) => e.message);
+    return failure({
+      code: 'DEPENDENCY_VALIDATION_ERROR',
+      message: `Dependency validation failed:\n${error_messages.map((m) => `  - ${m}`).join('\n')}`,
+    });
+  }
+
+  return success(result.topological_order ?? []);
+}

package/src/validation/reference.ts

@@ -0,0 +1,126 @@
+import type { DependencyRefType, InvalidReferenceErrorType } from './types.js';
+
+/**
+ * Parses a dependency reference string.
+ *
+ * Supports two formats:
+ * - Within-template: `kustomization-name` (e.g., `operator`)
+ * - Cross-template: `template-name/kustomization-name` (e.g., `001-secrets/doppler`)
+ *
+ * @param ref - The raw dependency reference string
+ * @returns Parsed dependency reference or error
+ */
+export function parse_dependency_ref(ref: string): DependencyRefType | InvalidReferenceErrorType {
+  const trimmed = ref.trim();
+
+  if (trimmed.length === 0) {
+    return {
+      type: 'invalid_reference',
+      source: '',
+      reference: ref,
+      message: 'Empty dependency reference',
+    };
+  }
+
+  const parts = trimmed.split('/');
+
+  if (parts.length === 1) {
+    // Within-template reference: `kustomization-name`
+    const kustomization = parts[0];
+    if (kustomization === undefined) {
+      return {
+        type: 'invalid_reference',
+        source: '',
+        reference: ref,
+        message: `Invalid dependency reference: '${ref}'`,
+      };
+    }
+    return {
+      kustomization,
+      raw: ref,
+    };
+  }
+
+  if (parts.length === 2) {
+    // Cross-template reference: `template-name/kustomization-name`
+    const template = parts[0];
+    const kustomization = parts[1];
+
+    if (
+      template === undefined ||
+      kustomization === undefined ||
+      template.length === 0 ||
+      kustomization.length === 0
+    ) {
+      return {
+        type: 'invalid_reference',
+        source: '',
+        reference: ref,
+        message: `Invalid dependency reference format: '${ref}' - both template and kustomization names must be non-empty`,
+      };
+    }
+
+    return {
+      template,
+      kustomization,
+      raw: ref,
+    };
+  }
+
+  // More than one slash is invalid
+  return {
+    type: 'invalid_reference',
+    source: '',
+    reference: ref,
+    message: `Invalid dependency reference format: '${ref}' - expected 'kustomization' or 'template/kustomization'`,
+  };
+}
+
+/**
+ * Type guard to check if parse result is an error.
+ */
+export function is_parse_error(
+  result: DependencyRefType | InvalidReferenceErrorType,
+): result is InvalidReferenceErrorType {
+  return 'type' in result && result.type === 'invalid_reference';
+}
+
+/**
+ * Resolves a dependency reference to a full node ID.
+ *
+ * @param ref - Parsed dependency reference
+ * @param current_template - The template containing the reference
+ * @returns Full node ID in format `template/kustomization`
+ */
+export function resolve_dependency_ref(ref: DependencyRefType, current_template: string): string {
+  const template = ref.template ?? current_template;
+  return `${template}/${ref.kustomization}`;
+}
+
+/**
+ * Creates a node ID from template and kustomization names.
+ *
+ * @param template - Template name
+ * @param kustomization - Kustomization name
+ * @returns Node ID in format `template/kustomization`
+ */
+export function create_node_id(template: string, kustomization: string): string {
+  return `${template}/${kustomization}`;
+}
+
+/**
+ * Parses a node ID into its components.
+ *
+ * @param node_id - Node ID in format `template/kustomization`
+ * @returns Object with template and kustomization names
+ */
+export function parse_node_id(node_id: string): { template: string; kustomization: string } {
+  const slash_index = node_id.indexOf('/');
+  if (slash_index === -1) {
+    return { template: '', kustomization: node_id };
+  }
+  return {
+    template: node_id.slice(0, slash_index),
+    kustomization: node_id.slice(slash_index + 1),
+  };
+}

package/src/validation/types.ts

@@ -0,0 +1,107 @@
+/**
+ * Node in the dependency graph.
+ */
+export interface GraphNodeType {
+  /** Unique identifier: `${template}/${kustomization}` */
+  readonly id: string;
+  /** Template name */
+  readonly template: string;
+  /** Kustomization name */
+  readonly kustomization: string;
+  /** Resolved dependency IDs */
+  readonly dependencies: string[];
+}
+
+/**
+ * Parsed dependency reference.
+ */
+export interface DependencyRefType {
+  /** Template name (undefined for within-template refs) */
+  readonly template?: string;
+  /** Kustomization name */
+  readonly kustomization: string;
+  /** Original reference string */
+  readonly raw: string;
+}
+
+/**
+ * Cycle error - circular dependency detected.
+ */
+export interface CycleErrorType {
+  readonly type: 'cycle';
+  /** Array of node IDs forming the cycle */
+  readonly cycle: string[];
+  readonly message: string;
+}
+
+/**
+ * Missing reference error - dependency target doesn't exist.
+ */
+export interface MissingReferenceErrorType {
+  readonly type: 'missing_reference';
+  /** Node ID that has the reference */
+  readonly source: string;
+  /** Missing target reference */
+  readonly target: string;
+  readonly message: string;
+}
+
+/**
+ * Self-reference error - kustomization depends on itself.
+ */
+export interface SelfReferenceErrorType {
+  readonly type: 'self_reference';
+  readonly node: string;
+  readonly message: string;
+}
+
+/**
+ * Invalid reference format error.
+ */
+export interface InvalidReferenceErrorType {
+  readonly type: 'invalid_reference';
+  readonly source: string;
+  readonly reference: string;
+  readonly message: string;
+}
+
+/**
+ * Union of all graph validation error types.
+ */
+export type GraphValidationErrorType =
+  | CycleErrorType
+  | MissingReferenceErrorType
+  | SelfReferenceErrorType
+  | InvalidReferenceErrorType;
+
+/**
+ * Result of graph validation.
+ */
+export interface GraphValidationResultType {
+  /** Whether the graph is valid (no errors) */
+  readonly valid: boolean;
+  /** All validation errors found */
+  readonly errors: GraphValidationErrorType[];
+  /** Deployment order if valid (topologically sorted) */
+  readonly topological_order?: string[];
+}
+
+/**
+ * Result of building the dependency graph.
+ */
+export interface BuildGraphResultType {
+  /** All nodes in the graph */
+  readonly nodes: Map<string, GraphNodeType>;
+  /** Errors encountered during graph building */
+  readonly errors: GraphValidationErrorType[];
+}
+
+/**
+ * Result of cycle detection.
+ */
+export interface CycleDetectionResultType {
+  /** All cycles found */
+  readonly cycles: CycleErrorType[];
+  /** Topological order if no cycles found, null otherwise */
+  readonly topological_order: string[] | null;
+}