@shepherdjerred/helm-types 0.0.0-dev.706

package/src/code-generator.ts

@@ -0,0 +1,226 @@
+import type { TypeScriptInterface } from "./types.ts";
+import {
+  StringSchema,
+  ArraySchema,
+  RecordSchema,
+  ActualNumberSchema,
+  ActualBooleanSchema,
+} from "./schemas.ts";
+import { capitalizeFirst } from "./utils.ts";
+
+/**
+ * Generate TypeScript code from interface definition
+ */
+export function generateTypeScriptCode(
+  mainInterface: TypeScriptInterface,
+  chartName: string,
+): string {
+  const interfaces: TypeScriptInterface[] = [];
+
+  // Collect all nested interfaces
+  collectNestedInterfaces(mainInterface, interfaces);
+
+  let code = `// Generated TypeScript types for ${chartName} Helm chart\n\n`;
+
+  // Generate all interfaces
+  for (const iface of interfaces) {
+    code += generateInterfaceCode(iface);
+    code += "\n";
+  }
+
+  // Generate parameter type (flattened dot notation)
+  code += generateParameterType(mainInterface, chartName);
+
+  // Add header comment for generated files
+  if (code.includes(": any")) {
+    code = `// Generated TypeScript types for ${chartName} Helm chart
+
+${code.slice(Math.max(0, code.indexOf("\n\n") + 2))}`;
+  }
+
+  return code;
+}
+
+function collectNestedInterfaces(
+  iface: TypeScriptInterface,
+  collected: TypeScriptInterface[],
+): void {
+  for (const prop of Object.values(iface.properties)) {
+    if (prop.nested) {
+      collected.push(prop.nested);
+      collectNestedInterfaces(prop.nested, collected);
+    }
+  }
+
+  // Add main interface last so dependencies come first
+  if (!collected.some((i) => i.name === iface.name)) {
+    collected.push(iface);
+  }
+}
+
+function generateInterfaceCode(iface: TypeScriptInterface): string {
+  const hasProperties = Object.keys(iface.properties).length > 0;
+
+  if (!hasProperties) {
+    // Use 'object' for empty interfaces instead of '{}'
+    return `export type ${iface.name} = object;\n`;
+  }
+
+  let code = `export type ${iface.name} = {\n`;
+
+  for (const [key, prop] of Object.entries(iface.properties)) {
+    const optional = prop.optional ? "?" : "";
+
+    // Generate JSDoc comment if we have description or default
+    if (
+      (prop.description != null && prop.description !== "") ||
+      prop.default !== undefined
+    ) {
+      code += `  /**\n`;
+
+      if (prop.description != null && prop.description !== "") {
+        // Format multi-line descriptions properly with " * " prefix
+        // Escape */ sequences to prevent premature comment closure
+        const escapedDescription = prop.description.replaceAll(
+          "*/",
+          String.raw`*\/`,
+        );
+        const descLines = escapedDescription.split("\n");
+        for (const line of descLines) {
+          code += `   * ${line}\n`;
+        }
+      }
+
+      if (prop.default !== undefined) {
+        const defaultStr = formatDefaultValue(prop.default);
+        const hasDescription =
+          prop.description != null && prop.description !== "";
+        if (defaultStr != null && defaultStr !== "" && hasDescription) {
+          code += `   *\n`;
+        }
+        if (defaultStr != null && defaultStr !== "") {
+          code += `   * @default ${defaultStr}\n`;
+        }
+      }
+
+      code += `   */\n`;
+    }
+
+    code += `  ${key}${optional}: ${prop.type};\n`;
+  }
+
+  code += "};\n";
+  return code;
+}
+
+/**
+ * Format a default value for display in JSDoc
+ */
+function formatDefaultValue(value: unknown): string | null {
+  if (value === null) {
+    return "null";
+  }
+  if (value === undefined) {
+    return null;
+  }
+
+  // Handle arrays
+  const arrayCheck = ArraySchema.safeParse(value);
+  if (arrayCheck.success) {
+    if (arrayCheck.data.length === 0) {
+      return "[]";
+    }
+    if (arrayCheck.data.length <= 3) {
+      try {
+        return JSON.stringify(arrayCheck.data);
+      } catch {
+        return "[...]";
+      }
+    }
+    return `[...] (${String(arrayCheck.data.length)} items)`;
+  }
+
+  // Handle objects
+  const recordCheck = RecordSchema.safeParse(value);
+  if (recordCheck.success) {
+    const keys = Object.keys(recordCheck.data);
+    if (keys.length === 0) {
+      return "{}";
+    }
+    if (keys.length <= 3) {
+      try {
+        return JSON.stringify(recordCheck.data);
+      } catch {
+        return "{...}";
+      }
+    }
+    return `{...} (${String(keys.length)} keys)`;
+  }
+
+  // Primitives
+  const stringCheck = StringSchema.safeParse(value);
+  if (stringCheck.success) {
+    // Truncate long strings
+    if (stringCheck.data.length > 50) {
+      return `"${stringCheck.data.slice(0, 47)}..."`;
+    }
+    return `"${stringCheck.data}"`;
+  }
+
+  // Handle other primitives (numbers, booleans, etc.)
+  const numberCheck = ActualNumberSchema.safeParse(value);
+  if (numberCheck.success) {
+    return String(numberCheck.data);
+  }
+
+  const booleanCheck = ActualBooleanSchema.safeParse(value);
+  if (booleanCheck.success) {
+    return String(booleanCheck.data);
+  }
+
+  // Fallback for unknown types - try JSON.stringify
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "unknown";
+  }
+}
+
+function generateParameterType(
+  iface: TypeScriptInterface,
+  chartName: string,
+): string {
+  const parameterKeys = flattenInterfaceKeys(iface);
+
+  const normalizedChartName = capitalizeFirst(chartName).replaceAll("-", "");
+  let code = `export type ${normalizedChartName}HelmParameters = {\n`;
+
+  for (const key of parameterKeys) {
+    code += `  "${key}"?: string;\n`;
+  }
+
+  code += "};\n";
+
+  return code;
+}
+
+function flattenInterfaceKeys(
+  iface: TypeScriptInterface,
+  prefix = "",
+): string[] {
+  const keys: string[] = [];
+
+  for (const [key, prop] of Object.entries(iface.properties)) {
+    // Remove quotes from key for parameter names
+    const cleanKey = key.replaceAll('"', "");
+    const fullKey = prefix ? `${prefix}.${cleanKey}` : cleanKey;
+
+    if (prop.nested) {
+      keys.push(...flattenInterfaceKeys(prop.nested, fullKey));
+    } else {
+      keys.push(fullKey);
+    }
+  }
+
+  return keys;
+}

package/src/comment-parser.ts

@@ -0,0 +1,180 @@
+/**
+ * Check if a line looks like an example/code block rather than documentation
+ */
+function isExampleLine(line: string): boolean {
+  return (
+    /^-{3,}/.test(line) ||
+    /^BEGIN .*(?:KEY|CERTIFICATE)/.test(line) ||
+    /^END .*(?:KEY|CERTIFICATE)/.test(line) ||
+    (line.startsWith("-") && (line.includes(":") || /^-\s+\|/.test(line))) ||
+    /^\w+:$/.test(line) ||
+    /^[\w-]+:\s*$/.test(line) ||
+    /^[\w.-]+:\s*\|/.test(line) || // YAML multiline indicator (e.g., "policy.csv: |")
+    line.startsWith("|") ||
+    line.includes("$ARGOCD_") ||
+    line.includes("$KUBE_") ||
+    /^\s{2,}/.test(line) ||
+    /^echo\s+/.test(line) ||
+    /^[pg],\s*/.test(line) // Policy rules like "p, role:..." or "g, subject, ..."
+  );
+}
+
+/**
+ * Check if a line looks like normal prose (sentence case, punctuation)
+ */
+function looksLikeProse(line: string): boolean {
+  return (
+    /^[A-Z][\w\s]+[.!?]$/.test(line) ||
+    /^[A-Z][\w\s,'"-]+(?::\s*)?$/.test(line) ||
+    line.startsWith("Ref:") ||
+    line.startsWith("See:") ||
+    line.startsWith("http://") ||
+    line.startsWith("https://")
+  );
+}
+
+/**
+ * Strip YAML comment markers from a single line
+ */
+function stripCommentMarkers(line: string): string {
+  let result = line.replace(/^#+\s*/, "");
+  result = result.replace(/^--\s*/, "");
+  result = result.replace(/^##\s*/, "");
+  return result.trim();
+}
+
+/**
+ * Clean up YAML comment text for use in JSDoc
+ */
+export function cleanYAMLComment(comment: string): string {
+  const lines = comment.split("\n").map((line) => stripCommentMarkers(line));
+
+  // Filter and clean lines
+  const cleaned: string[] = [];
+  let inCodeBlock = false;
+
+  for (const currentLine of lines) {
+    if (currentLine.length === 0) {
+      if (inCodeBlock) {
+        inCodeBlock = false;
+      }
+      continue;
+    }
+
+    if (currentLine.startsWith("@default")) {
+      continue;
+    }
+
+    if (isExampleLine(currentLine)) {
+      inCodeBlock = true;
+      continue;
+    }
+
+    if (inCodeBlock) {
+      if (looksLikeProse(currentLine)) {
+        inCodeBlock = false;
+      } else {
+        continue;
+      }
+    }
+
+    cleaned.push(currentLine);
+  }
+
+  return cleaned.join("\n").trim();
+}
+
+/**
+ * Parse YAML comments and associate them with keys
+ * Exported for testing purposes
+ */
+export function parseYAMLComments(yamlContent: string): Map<string, string> {
+  const lines = yamlContent.split("\n");
+  const comments = new Map<string, string>();
+  let pendingComments: { text: string; indent: number }[] = [];
+  const indentStack: { indent: number; key: string }[] = [];
+
+  for (const line of lines) {
+    const currentLine = line;
+    const trimmed = currentLine.trim();
+
+    // Skip empty lines
+    if (!trimmed) {
+      // Empty lines break comment association only if we already have comments
+      // This allows comments separated by blank lines to still be associated
+      continue;
+    }
+
+    // Check if line is a comment
+    if (trimmed.startsWith("#")) {
+      const comment = trimmed.slice(1).trim();
+      if (comment) {
+        // Track the indentation level of the comment
+        const commentIndent = currentLine.search(/\S/);
+        pendingComments.push({ text: comment, indent: commentIndent });
+      }
+      continue;
+    }
+
+    // Check if line has a key
+    const keyMatch = /^(\s*)([\w-]+)\s*:/.exec(currentLine);
+    if (keyMatch) {
+      const indent = keyMatch[1]?.length ?? 0;
+      const key = keyMatch[2];
+      if (key == null || key === "") {
+        continue;
+      }
+
+      // Update indent stack
+      const lastIndent = indentStack.at(-1);
+      while (
+        indentStack.length > 0 &&
+        lastIndent &&
+        lastIndent.indent >= indent
+      ) {
+        indentStack.pop();
+      }
+
+      // Build full key path
+      const keyPath =
+        indentStack.length > 0
+          ? `${indentStack.map((s) => s.key).join(".")}.${key}`
+          : key;
+
+      // Check for inline comment
+      const inlineCommentMatch = /#\s*(\S.*)$/.exec(currentLine);
+      if (inlineCommentMatch?.[1] != null && inlineCommentMatch[1] !== "") {
+        pendingComments.push({ text: inlineCommentMatch[1].trim(), indent });
+      }
+
+      // Filter pending comments to only those at the same or shallower indent level as this key
+      // This prevents comments from deeper nested properties being associated with a shallower property
+      const relevantComments = pendingComments.filter(
+        (c) => c.indent <= indent,
+      );
+
+      // Associate relevant comments with this key
+      if (relevantComments.length > 0) {
+        // Join and clean comments
+        const commentText = cleanYAMLComment(
+          relevantComments.map((c) => c.text).join("\n"),
+        );
+        if (commentText) {
+          comments.set(keyPath, commentText);
+        }
+      }
+
+      // Clear pending comments after processing
+      pendingComments = [];
+
+      // Add to indent stack
+      indentStack.push({ indent, key });
+    } else {
+      // If we encounter a non-comment, non-key line, clear pending comments
+      // This handles list items and other YAML structures
+      pendingComments = [];
+    }
+  }
+
+  return comments;
+}

package/src/config.ts

@@ -0,0 +1,147 @@
+/**
+ * Well-known Kubernetes resource patterns.
+ * When a property matches these patterns, we augment the type with standard K8s fields.
+ */
+export const K8S_RESOURCE_SPEC_PATTERN = {
+  /**
+   * Property names that indicate a Kubernetes resource spec (requests/limits pattern)
+   */
+  resourceSpecNames: ["resources"],
+  /**
+   * Required sibling properties for a valid resource spec
+   */
+  resourceSpecFields: ["requests", "limits"] as const,
+};
+
+/**
+ * Check if a property name indicates a Kubernetes resource spec.
+ */
+export function isK8sResourceSpec(propertyName: string): boolean {
+  return K8S_RESOURCE_SPEC_PATTERN.resourceSpecNames.includes(
+    propertyName.toLowerCase(),
+  );
+}
+
+/**
+ * Configuration for types that should allow arbitrary additional properties.
+ * Maps chart names to array of key paths that should be extensible.
+ *
+ * These are typically config maps, RBAC policies, or other key-value stores
+ * where the schema doesn't enumerate all possible keys.
+ */
+export const EXTENSIBLE_TYPE_PATTERNS: Record<string, string[]> = {
+  "argo-cd": [
+    "configs.cm", // Allows accounts.*, and other custom config
+    "configs.rbac", // Allows policy.*, custom RBAC rules
+  ],
+  "kube-prometheus-stack": [
+    "grafana", // Allows "grafana.ini" and other quoted config keys
+    "grafana.deploymentStrategy", // Allows Kubernetes Deployment strategy objects with flexible fields
+    "alertmanager.config.receivers", // Allows various *_configs (pagerduty_configs, etc.) on array elements
+    "prometheus-node-exporter", // Allows extraHostVolumeMounts and other node exporter specific configs
+    "prometheusNodeExporter", // Also support camelCase variant
+  ],
+  loki: [
+    "loki.limits_config", // Allows retention_period and other limit configs (note: underscore, not camelCase)
+    "loki.limitsConfig", // Also support camelCase variant
+    "compactor", // Allows various compactor settings
+    "minio.persistence", // Storage configs
+  ],
+  minecraft: [
+    "persistence", // Storage class and other persistence options
+  ],
+  openebs: [
+    "zfs-localpv", // ZFS-specific configs
+  ],
+  "postgres-operator": [
+    "configGeneral", // General config allows various settings
+  ],
+  chartmuseum: [
+    "persistence", // Storage options
+  ],
+  "intel-device-plugins-operator": [
+    // Root level for device-specific settings
+    "",
+  ],
+  "prometheus-adapter": [
+    "rules", // Allows resource, custom, external and other rule configurations
+  ],
+  velero: [
+    "kubectl.image", // Allows image configuration
+  ],
+  seaweedfs: [
+    "volume.dataDirs", // dataDirs elements support size, storageClass when type is persistentVolumeClaim
+  ],
+};
+
+/**
+ * Pattern-based detection for extensible types.
+ * Returns true if the property should allow arbitrary keys.
+ */
+export function shouldAllowArbitraryProps(
+  keyPath: string,
+  chartName: string,
+  propertyName: string,
+  yamlComment?: string,
+): boolean {
+  // Check configured patterns for this chart
+  const patterns = EXTENSIBLE_TYPE_PATTERNS[chartName];
+  if (patterns) {
+    for (const pattern of patterns) {
+      if (
+        pattern === keyPath ||
+        (pattern === "" && keyPath.split(".").length === 1)
+      ) {
+        return true;
+      }
+      // Also match if keyPath starts with pattern
+      if (pattern && keyPath.startsWith(`${pattern}.`)) {
+        return true;
+      }
+    }
+  }
+
+  // Pattern-based detection from property names
+  const lowerProp = propertyName.toLowerCase();
+  const lowerPath = keyPath.toLowerCase();
+
+  // Common names that suggest extensibility
+  const extensibleNames = [
+    "cm", // ConfigMap data
+    "data",
+    "config",
+    "configs",
+    "settings",
+    "parameters",
+    "options",
+    "extraenv",
+    "annotations",
+    "labels",
+    "nodeaffinity",
+    "toleration",
+  ];
+
+  if (extensibleNames.includes(lowerProp)) {
+    return true;
+  }
+
+  // Check for persistence/storage which often has provider-specific fields
+  if (lowerPath.includes("persistence") || lowerPath.includes("storage")) {
+    return true;
+  }
+
+  // Check YAML comments for hints
+  if (yamlComment != null && yamlComment !== "") {
+    const commentLower = yamlComment.toLowerCase();
+    if (
+      /\b(?:arbitrary|custom|additional|extra|any)\s+(?:keys?|properties?|fields?|values?)\b/i.test(
+        commentLower,
+      ) ||
+      /\bkey[\s-]?value\s+pairs?\b/i.test(commentLower)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/helm-types.ts

@@ -0,0 +1,16 @@
+/**
+ * This file previously served as a barrel/re-export module.
+ * Import directly from submodules instead:
+ * - ./types.ts - Core types
+ * - ./schemas.ts - Zod schemas
+ * - ./config.ts - Configuration
+ * - ./chart-info-parser.ts - Chart info parsing
+ * - ./yaml-comments.ts - YAML comments
+ * - ./chart-fetcher.ts - Chart fetching
+ * - ./type-converter.ts - Type conversion
+ * - ./interface-generator.ts - Code generation
+ * - ./utils.ts - Utilities
+ */
+
+/** Version marker for the helm-types module. */
+export const HELM_TYPES_VERSION = "1.1.0";

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @homelab/helm-types
+ *
+ * A library for generating TypeScript types from Helm chart values.
+ *
+ * Core functionality:
+ * - Fetch Helm charts from repositories
+ * - Parse values.yaml and values.schema.json
+ * - Generate TypeScript interfaces with JSDoc comments
+ * - Support for nested objects, arrays, and unions
+ *
+ * This is a general-purpose library that can be used with any Helm chart.
+ * Application-specific logic should be kept in your application code.
+ *
+ * Import directly from submodules:
+ * - ./types.ts - Core types (ChartInfo, JSONSchemaProperty, TypeScriptInterface, TypeProperty)
+ * - ./schemas.ts - Zod schemas (HelmValueSchema, StringSchema, etc.)
+ * - ./config.ts - Configuration (EXTENSIBLE_TYPE_PATTERNS, shouldAllowArbitraryProps)
+ * - ./chart-info-parser.ts - Chart info parsing (parseChartInfoFromVersions)
+ * - ./yaml-comments.ts - YAML comments (cleanYAMLComment, parseYAMLComments)
+ * - ./chart-fetcher.ts - Chart fetching (fetchHelmChart)
+ * - ./type-converter.ts - Type conversion (jsonSchemaToTypeScript, inferTypeFromValue, etc.)
+ * - ./interface-generator.ts - Code generation (generateTypeScriptCode)
+ * - ./utils.ts - Utilities (sanitizePropertyName, sanitizeTypeName, capitalizeFirst)
+ */
+
+/** Version marker for the helm-types package. */
+export const HELM_TYPES_PACKAGE_VERSION = "1.1.0";