@kustodian/generator 1.0.0

package/src/namespace.ts

@@ -0,0 +1,121 @@
+import type { KustomizationType, TemplateType } from '@kustodian/schema';
+
+import type { ResolvedTemplateType } from './types.js';
+
+/**
+ * System namespaces that should not be generated.
+ */
+export const SYSTEM_NAMESPACES = new Set([
+  'default',
+  'flux-system',
+  'kube-system',
+  'kube-public',
+  'kube-node-lease',
+]);
+
+/**
+ * Namespace resource type.
+ */
+export interface NamespaceResourceType {
+  apiVersion: 'v1';
+  kind: 'Namespace';
+  metadata: {
+    name: string;
+    labels?: Record<string, string>;
+  };
+}
+
+/**
+ * Extracts the namespace from a kustomization.
+ * Returns undefined if no namespace is configured.
+ */
+export function get_kustomization_namespace(kustomization: KustomizationType): string | undefined {
+  return kustomization.namespace?.default;
+}
+
+/**
+ * Extracts all namespaces from a template.
+ */
+export function get_template_namespaces(template: TemplateType): string[] {
+  const namespaces = new Set<string>();
+
+  for (const kustomization of template.spec.kustomizations) {
+    const namespace = get_kustomization_namespace(kustomization);
+    if (namespace) {
+      namespaces.add(namespace);
+    }
+  }
+
+  return Array.from(namespaces);
+}
+
+/**
+ * Extracts all namespaces from resolved templates.
+ * Filters out disabled templates.
+ */
+export function collect_namespaces(templates: ResolvedTemplateType[]): string[] {
+  const namespaces = new Set<string>();
+
+  for (const resolved of templates) {
+    if (!resolved.enabled) {
+      continue;
+    }
+
+    for (const namespace of get_template_namespaces(resolved.template)) {
+      namespaces.add(namespace);
+    }
+  }
+
+  return Array.from(namespaces).sort();
+}
+
+/**
+ * Filters out system namespaces from a list.
+ */
+export function filter_system_namespaces(namespaces: string[]): string[] {
+  return namespaces.filter((ns) => !is_system_namespace(ns));
+}
+
+/**
+ * Checks if a namespace is a system namespace.
+ */
+export function is_system_namespace(namespace: string): boolean {
+  if (SYSTEM_NAMESPACES.has(namespace)) {
+    return true;
+  }
+
+  // Also filter kube-* namespaces
+  return namespace.startsWith('kube-');
+}
+
+/**
+ * Creates a namespace resource.
+ */
+export function create_namespace_resource(
+  name: string,
+  labels?: Record<string, string>,
+): NamespaceResourceType {
+  const metadata: NamespaceResourceType['metadata'] = { name };
+  if (labels !== undefined) {
+    metadata.labels = labels;
+  }
+  return {
+    apiVersion: 'v1',
+    kind: 'Namespace',
+    metadata,
+  };
+}
+
+/**
+ * Generates namespace resources for all namespaces in templates.
+ * Filters out system namespaces.
+ */
+export function generate_namespace_resources(
+  templates: ResolvedTemplateType[],
+  labels?: Record<string, string>,
+): NamespaceResourceType[] {
+  const namespaces = collect_namespaces(templates);
+  const filtered = filter_system_namespaces(namespaces);
+
+  return filtered.map((name) => create_namespace_resource(name, labels));
+}

package/src/output.ts

@@ -0,0 +1,208 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import { Errors, type ResultType, failure, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+import YAML from 'yaml';
+
+import type { FluxKustomizationType, GenerationResultType } from './types.js';
+
+/**
+ * Output format options.
+ */
+export type OutputFormatType = 'yaml' | 'json';
+
+/**
+ * Options for writing output.
+ */
+export interface WriteOptionsType {
+  format?: OutputFormatType;
+  create_dirs?: boolean;
+}
+
+/**
+ * Serializes a resource to YAML or JSON.
+ */
+export function serialize_resource<T>(resource: T, format: OutputFormatType = 'yaml'): string {
+  if (format === 'json') {
+    return JSON.stringify(resource, null, 2);
+  }
+
+  return YAML.stringify(resource, {
+    indent: 2,
+    lineWidth: 0,
+    singleQuote: false,
+  });
+}
+
+/**
+ * Serializes multiple resources to a single YAML document with separators.
+ */
+export function serialize_resources<T>(resources: T[], format: OutputFormatType = 'yaml'): string {
+  if (format === 'json') {
+    return JSON.stringify(resources, null, 2);
+  }
+
+  return resources.map((r) => serialize_resource(r, format)).join('---\n');
+}
+
+/**
+ * Ensures a directory exists, creating it if necessary.
+ */
+export async function ensure_directory(
+  dir_path: string,
+): Promise<ResultType<void, KustodianErrorType>> {
+  try {
+    await fs.mkdir(dir_path, { recursive: true });
+    return success(undefined);
+  } catch (error) {
+    return failure(Errors.file_write_error(dir_path, error));
+  }
+}
+
+/**
+ * Writes content to a file.
+ */
+export async function write_file(
+  file_path: string,
+  content: string,
+  options: WriteOptionsType = {},
+): Promise<ResultType<void, KustodianErrorType>> {
+  const { create_dirs = true } = options;
+
+  if (create_dirs) {
+    const dir = path.dirname(file_path);
+    const dir_result = await ensure_directory(dir);
+    if (!dir_result.success) {
+      return dir_result;
+    }
+  }
+
+  try {
+    await fs.writeFile(file_path, content, 'utf-8');
+    return success(undefined);
+  } catch (error) {
+    return failure(Errors.file_write_error(file_path, error));
+  }
+}
+
+/**
+ * Writes a Flux Kustomization resource to a file.
+ */
+export async function write_flux_kustomization(
+  kustomization: FluxKustomizationType,
+  output_dir: string,
+  options: WriteOptionsType = {},
+): Promise<ResultType<string, KustodianErrorType>> {
+  const format = options.format ?? 'yaml';
+  const ext = format === 'json' ? 'json' : 'yaml';
+  const file_path = path.join(output_dir, `${kustomization.metadata.name}.${ext}`);
+
+  const content = serialize_resource(kustomization, format);
+  const result = await write_file(file_path, content, options);
+
+  if (!result.success) {
+    return result;
+  }
+
+  return success(file_path);
+}
+
+/**
+ * Writes all generated kustomizations to a structured output directory.
+ *
+ * Output structure:
+ * ```
+ * {output_dir}/
+ * ├── flux-system/
+ * │   ├── kustomization.yaml    # Root kustomization referencing all templates
+ * │   └── oci-repository.yaml   # OCI source (if configured)
+ * └── templates/
+ *     ├── {template-name}/
+ *     │   └── {kustomization-name}.yaml
+ *     └── ...
+ * ```
+ */
+export async function write_generation_result(
+  result: GenerationResultType,
+  options: WriteOptionsType = {},
+): Promise<ResultType<string[], KustodianErrorType>> {
+  const format = options.format ?? 'yaml';
+  const ext = format === 'json' ? 'json' : 'yaml';
+  const written_files: string[] = [];
+
+  const flux_system_dir = path.join(result.output_dir, 'flux-system');
+  const templates_dir = path.join(result.output_dir, 'templates');
+
+  // Write OCIRepository to flux-system directory if present
+  if (result.oci_repository) {
+    const oci_path = path.join(flux_system_dir, `oci-repository.${ext}`);
+    const oci_content = serialize_resource(result.oci_repository, format);
+    const oci_result = await write_file(oci_path, oci_content, options);
+
+    if (!oci_result.success) {
+      return oci_result;
+    }
+
+    written_files.push(oci_path);
+  }
+
+  // Write each kustomization to templates/{template-name}/{kustomization-name}.yaml
+  for (const generated of result.kustomizations) {
+    const template_dir = path.join(templates_dir, generated.template);
+    const file_path = path.join(template_dir, `${generated.flux_kustomization.metadata.name}.${ext}`);
+
+    const content = serialize_resource(generated.flux_kustomization, format);
+    const file_result = await write_file(file_path, content, options);
+
+    if (!file_result.success) {
+      return file_result;
+    }
+
+    written_files.push(file_path);
+  }
+
+  // Write root kustomization.yaml in flux-system directory
+  const kustomization_path = path.join(flux_system_dir, 'kustomization.yaml');
+  const resources: string[] = [];
+
+  // Add OCI repository reference if present
+  if (result.oci_repository) {
+    resources.push(`oci-repository.${ext}`);
+  }
+
+  // Add references to all template kustomizations with relative paths
+  resources.push(
+    ...result.kustomizations.map((k) => {
+      return `../templates/${k.template}/${k.flux_kustomization.metadata.name}.${ext}`;
+    }),
+  );
+
+  // Sort resources for deterministic output
+  resources.sort();
+
+  const kustomization_content = serialize_resource(
+    {
+      apiVersion: 'kustomize.config.k8s.io/v1beta1',
+      kind: 'Kustomization',
+      resources,
+    },
+    'yaml',
+  );
+
+  const kustomization_result = await write_file(kustomization_path, kustomization_content, options);
+  if (!kustomization_result.success) {
+    return kustomization_result;
+  }
+
+  written_files.push(kustomization_path);
+
+  return success(written_files);
+}
+
+/**
+ * Gets the file extension for a format.
+ */
+export function get_extension(format: OutputFormatType): string {
+  return format === 'json' ? 'json' : 'yaml';
+}

package/src/substitution.ts

@@ -0,0 +1,140 @@
+import type { KustomizationType } from '@kustodian/schema';
+
+/**
+ * Pattern for matching substitution variables: ${variable_name}
+ */
+export const SUBSTITUTION_PATTERN = /\$\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
+
+/**
+ * Result of validating substitution values.
+ */
+export interface SubstitutionValidationResultType {
+  valid: boolean;
+  missing: string[];
+  unused: string[];
+}
+
+/**
+ * Extracts variable names from a string containing ${var} patterns.
+ */
+export function extract_variables(text: string): string[] {
+  const matches = text.matchAll(SUBSTITUTION_PATTERN);
+  const variables = new Set<string>();
+  for (const match of matches) {
+    const variable_name = match[1];
+    if (variable_name !== undefined) {
+      variables.add(variable_name);
+    }
+  }
+  return Array.from(variables);
+}
+
+/**
+ * Applies substitution values to a string containing ${var} patterns.
+ */
+export function substitute_string(text: string, values: Record<string, string>): string {
+  return text.replace(SUBSTITUTION_PATTERN, (match, variable_name) => {
+    return values[variable_name] ?? match;
+  });
+}
+
+/**
+ * Applies substitution values to an object recursively.
+ * Only processes string values within the object.
+ */
+export function substitute_object<T>(obj: T, values: Record<string, string>): T {
+  if (typeof obj === 'string') {
+    return substitute_string(obj, values) as T;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => substitute_object(item, values)) as T;
+  }
+
+  if (obj !== null && typeof obj === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = substitute_object(value, values);
+    }
+    return result as T;
+  }
+
+  return obj;
+}
+
+/**
+ * Collects substitution values from a kustomization definition and cluster values.
+ * Returns a record of variable name to value.
+ */
+export function collect_substitution_values(
+  kustomization: KustomizationType,
+  cluster_values: Record<string, string> = {},
+): Record<string, string> {
+  const values: Record<string, string> = {};
+
+  for (const sub of kustomization.substitutions ?? []) {
+    // Cluster value takes precedence over default
+    const value = cluster_values[sub.name] ?? sub.default;
+    if (value !== undefined) {
+      values[sub.name] = value;
+    }
+  }
+
+  return values;
+}
+
+/**
+ * Gets all defined substitution names from a kustomization.
+ */
+export function get_defined_substitutions(kustomization: KustomizationType): string[] {
+  return (kustomization.substitutions ?? []).map((sub) => sub.name);
+}
+
+/**
+ * Gets all required substitution names (those without defaults) from a kustomization.
+ */
+export function get_required_substitutions(kustomization: KustomizationType): string[] {
+  return (kustomization.substitutions ?? [])
+    .filter((sub) => sub.default === undefined)
+    .map((sub) => sub.name);
+}
+
+/**
+ * Validates that all required substitutions have values.
+ */
+export function validate_substitutions(
+  kustomization: KustomizationType,
+  cluster_values: Record<string, string> = {},
+): SubstitutionValidationResultType {
+  const required = get_required_substitutions(kustomization);
+  const defined = get_defined_substitutions(kustomization);
+  const provided = Object.keys(cluster_values);
+
+  // Find missing required values
+  const missing = required.filter((name) => cluster_values[name] === undefined);
+
+  // Find unused provided values
+  const unused = provided.filter((name) => !defined.includes(name));
+
+  return {
+    valid: missing.length === 0,
+    missing,
+    unused,
+  };
+}
+
+/**
+ * Generates the postBuild.substitute object for a Flux Kustomization.
+ * Only includes values that have actual values (not undefined).
+ */
+export function generate_flux_substitutions(
+  values: Record<string, string>,
+): Record<string, string> | undefined {
+  const entries = Object.entries(values).filter(([, value]) => value !== undefined);
+
+  if (entries.length === 0) {
+    return undefined;
+  }
+
+  return Object.fromEntries(entries);
+}

package/src/types.ts

@@ -0,0 +1,120 @@
+import type { ClusterType, KustomizationType, TemplateType } from '@kustodian/schema';
+
+/**
+ * Options for the generation process.
+ */
+export interface GenerateOptionsType {
+  dry_run?: boolean;
+  output_dir?: string;
+  skip_validation?: boolean;
+}
+
+/**
+ * A resolved template with its values.
+ */
+export interface ResolvedTemplateType {
+  template: TemplateType;
+  values: Record<string, string>;
+  enabled: boolean;
+}
+
+/**
+ * A resolved kustomization with substitution values applied.
+ */
+export interface ResolvedKustomizationType {
+  template: TemplateType;
+  kustomization: KustomizationType;
+  values: Record<string, string>;
+  namespace: string;
+}
+
+/**
+ * Generation context for a cluster.
+ */
+export interface GenerationContextType {
+  cluster: ClusterType;
+  templates: ResolvedTemplateType[];
+  output_dir: string;
+}
+
+/**
+ * Result of a single kustomization generation.
+ */
+export interface GeneratedKustomizationType {
+  name: string;
+  template: string;
+  path: string;
+  flux_kustomization: FluxKustomizationType;
+}
+
+/**
+ * Result of the full generation process.
+ */
+export interface GenerationResultType {
+  cluster: string;
+  output_dir: string;
+  kustomizations: GeneratedKustomizationType[];
+  oci_repository?: FluxOCIRepositoryType;
+}
+
+/**
+ * Flux OCIRepository resource type.
+ */
+export interface FluxOCIRepositoryType {
+  apiVersion: 'source.toolkit.fluxcd.io/v1';
+  kind: 'OCIRepository';
+  metadata: {
+    name: string;
+    namespace: string;
+  };
+  spec: {
+    interval: string;
+    url: string;
+    ref: {
+      tag?: string;
+      digest?: string;
+      semver?: string;
+    };
+    provider?: 'aws' | 'azure' | 'gcp' | 'generic';
+    secretRef?: {
+      name: string;
+    };
+    insecure?: boolean;
+    timeout?: string;
+  };
+}
+
+/**
+ * Flux Kustomization resource type.
+ */
+export interface FluxKustomizationType {
+  apiVersion: 'kustomize.toolkit.fluxcd.io/v1';
+  kind: 'Kustomization';
+  metadata: {
+    name: string;
+    namespace: string;
+  };
+  spec: {
+    interval: string;
+    targetNamespace?: string;
+    path: string;
+    prune: boolean;
+    wait: boolean;
+    timeout?: string;
+    retryInterval?: string;
+    sourceRef: {
+      kind: 'GitRepository' | 'OCIRepository';
+      name: string;
+    };
+    dependsOn?: Array<{ name: string }>;
+    postBuild?: {
+      substitute?: Record<string, string>;
+    };
+    healthChecks?: Array<{
+      apiVersion: string;
+      kind: string;
+      name: string;
+      namespace: string;
+    }>;
+  };
+}

package/src/validation/cycle-detection.ts

@@ -0,0 +1,111 @@
+import type { CycleDetectionResultType, CycleErrorType, GraphNodeType } from './types.js';
+
+/**
+ * Visit state for DFS traversal.
+ */
+enum VisitState {
+  /** Node has not been visited yet */
+  Unvisited = 0,
+  /** Node is currently being visited (in the DFS stack) */
+  Visiting = 1,
+  /** Node has been fully processed */
+  Visited = 2,
+}
+
+/**
+ * Formats a cycle into a human-readable message.
+ *
+ * @param cycle - Array of node IDs forming the cycle
+ * @returns Formatted cycle message
+ */
+function format_cycle_message(cycle: string[]): string {
+  const cycle_str = cycle.join(' → ');
+  return `Dependency cycle detected: ${cycle_str}`;
+}
+
+/**
+ * Detects cycles in the dependency graph using depth-first search (DFS).
+ *
+ * Uses a three-color algorithm:
+ * - Unvisited (white): Node hasn't been processed
+ * - Visiting (gray): Node is currently in the DFS stack
+ * - Visited (black): Node and all its descendants have been processed
+ *
+ * If we encounter a Visiting node during DFS, we've found a cycle.
+ *
+ * Also performs topological sorting if no cycles are found.
+ *
+ * @param nodes - Map of graph nodes
+ * @returns Cycles found and topological order (if no cycles)
+ */
+export function detect_cycles(nodes: Map<string, GraphNodeType>): CycleDetectionResultType {
+  const state = new Map<string, VisitState>();
+  const cycles: CycleErrorType[] = [];
+  const topological_order: string[] = [];
+
+  // Initialize all nodes as unvisited
+  for (const id of nodes.keys()) {
+    state.set(id, VisitState.Unvisited);
+  }
+
+  /**
+   * DFS traversal function.
+   *
+   * @param node_id - Current node being visited
+   * @param path - Current path from DFS root to this node
+   */
+  function dfs(node_id: string, path: string[]): void {
+    state.set(node_id, VisitState.Visiting);
+    path.push(node_id);
+
+    const node = nodes.get(node_id);
+    if (node) {
+      for (const dep_id of node.dependencies) {
+        const dep_state = state.get(dep_id);
+
+        if (dep_state === VisitState.Visiting) {
+          // Found a cycle - extract it from the path
+          const cycle_start_index = path.indexOf(dep_id);
+          const cycle = [...path.slice(cycle_start_index), dep_id];
+          cycles.push({
+            type: 'cycle',
+            cycle,
+            message: format_cycle_message(cycle),
+          });
+        } else if (dep_state === VisitState.Unvisited) {
+          dfs(dep_id, path);
+        }
+        // If Visited, skip - already fully processed
+      }
+    }
+
+    state.set(node_id, VisitState.Visited);
+    path.pop();
+
+    // Add to end for post-order (dependencies come before dependents)
+    topological_order.push(node_id);
+  }
+
+  // Visit all nodes (handles disconnected components)
+  for (const node_id of nodes.keys()) {
+    if (state.get(node_id) === VisitState.Unvisited) {
+      dfs(node_id, []);
+    }
+  }
+
+  return {
+    cycles,
+    topological_order: cycles.length === 0 ? topological_order : null,
+  };
+}
+
+/**
+ * Checks if a graph has cycles.
+ *
+ * @param nodes - Map of graph nodes
+ * @returns True if the graph has at least one cycle
+ */
+export function has_cycles(nodes: Map<string, GraphNodeType>): boolean {
+  const result = detect_cycles(nodes);
+  return result.cycles.length > 0;
+}