@shepherdjerred/helm-types 1.1.0

package/src/comment-parser.ts

@@ -0,0 +1,156 @@
+/**
+ * Clean up YAML comment text for use in JSDoc
+ */
+export function cleanYAMLComment(comment: string): string {
+  const lines = comment.split("\n").map((line) => {
+    // Remove leading # symbols
+    line = line.replace(/^#+\s*/, "");
+    // Remove common Helm chart comment markers
+    line = line.replace(/^--\s*/, "");
+    line = line.replace(/^##\s*/, "");
+    return line.trim();
+  });
+
+  // Filter and clean lines
+  const cleaned: string[] = [];
+  let inCodeBlock = false;
+
+  for (const line of lines) {
+    const currentLine = line;
+
+    // Skip empty lines
+    if (currentLine.length === 0) {
+      if (inCodeBlock) inCodeBlock = false;
+      continue;
+    }
+
+    // Skip @default lines (we'll generate our own)
+    if (currentLine.startsWith("@default")) continue;
+
+    // Detect various patterns that indicate this is an example/code block, not documentation
+    const isExample =
+      /^-{3,}/.test(currentLine) ||
+      /^BEGIN .*(KEY|CERTIFICATE)/.test(currentLine) ||
+      /^END .*(KEY|CERTIFICATE)/.test(currentLine) ||
+      (currentLine.startsWith("-") && (currentLine.includes(":") || /^-\s+\|/.test(currentLine))) ||
+      /^\w+:$/.test(currentLine) ||
+      /^[\w-]+:\s*$/.test(currentLine) ||
+      /^[\w.-]+:\s*\|/.test(currentLine) || // YAML multiline indicator (e.g., "policy.csv: |")
+      currentLine.startsWith("|") ||
+      currentLine.includes("$ARGOCD_") ||
+      currentLine.includes("$KUBE_") ||
+      /^\s{2,}/.test(currentLine) ||
+      /^echo\s+/.test(currentLine) ||
+      /^[pg],\s*/.test(currentLine); // Policy rules like "p, role:..." or "g, subject, ..."
+
+    if (isExample) {
+      inCodeBlock = true;
+      continue;
+    }
+
+    // If we're in a code block, skip until we hit normal prose
+    if (inCodeBlock) {
+      // Check if this line looks like normal prose (sentence case, punctuation)
+      const looksLikeProse =
+        /^[A-Z][\w\s]+[.!?]$/.test(currentLine) ||
+        /^[A-Z][\w\s,'"-]+:?\s*$/.test(currentLine) ||
+        currentLine.startsWith("Ref:") ||
+        currentLine.startsWith("See:") ||
+        currentLine.startsWith("http://") ||
+        currentLine.startsWith("https://");
+
+      if (looksLikeProse) {
+        inCodeBlock = false;
+      } else {
+        continue;
+      }
+    }
+
+    // Keep the line
+    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.substring(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*)([a-zA-Z0-9_-]+)\s*:/.exec(currentLine);
+    if (keyMatch) {
+      const indent = keyMatch[1]?.length ?? 0;
+      const key = keyMatch[2];
+      if (!key) continue;
+
+      // Update indent stack
+      const lastIndent = indentStack[indentStack.length - 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*(.+)$/.exec(currentLine);
+      if (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,140 @@
+/**
+ * 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) {
+    const commentLower = yamlComment.toLowerCase();
+    if (
+      /\b(arbitrary|custom|additional|extra|any)\s+(keys?|properties?|fields?|values?)\b/i.exec(commentLower) ||
+      /\bkey[\s-]?value\s+pairs?\b/i.exec(commentLower)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/helm-types.ts

@@ -0,0 +1,46 @@
+// Main entry point for Helm type generation
+// This file re-exports all functionality from the modular components
+
+// Core types
+export type { ChartInfo, JSONSchemaProperty, TypeScriptInterface, TypeProperty } from "./types.js";
+
+// Schemas
+export type { HelmValue } from "./schemas.js";
+export {
+  StringSchema,
+  ActualNumberSchema,
+  ActualBooleanSchema,
+  NullSchema,
+  UndefinedSchema,
+  ArraySchema,
+  RecordSchema,
+  ErrorSchema,
+  StringBooleanSchema,
+  HelmValueSchema,
+} from "./schemas.js";
+
+// Configuration
+export { EXTENSIBLE_TYPE_PATTERNS, shouldAllowArbitraryProps } from "./config.js";
+
+// Chart info parsing
+export { parseChartInfoFromVersions } from "./chart-info-parser.js";
+
+// YAML comments
+export { cleanYAMLComment, parseYAMLComments } from "./yaml-comments.js";
+
+// Chart fetching
+export { fetchHelmChart } from "./chart-fetcher.js";
+
+// Type conversion
+export {
+  jsonSchemaToTypeScript,
+  inferTypeFromValue,
+  typesAreCompatible,
+  convertToTypeScriptInterface,
+} from "./type-converter.js";
+
+// Code generation
+export { generateTypeScriptCode } from "./interface-generator.js";
+
+// Utilities
+export { sanitizePropertyName, sanitizeTypeName, capitalizeFirst } from "./utils.js";

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @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.
+ */
+export * from "./helm-types.ts";

package/src/interface-generator.ts

@@ -0,0 +1,203 @@
+import type { TypeScriptInterface } from "./types.js";
+import { ArraySchema, RecordSchema, StringSchema, ActualNumberSchema, ActualBooleanSchema } from "./schemas.js";
+
+/**
+ * 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);
+
+  // Check if any 'any' types were generated and add ESLint disable if needed
+  if (code.includes(": any")) {
+    code = `// Generated TypeScript types for ${chartName} Helm chart
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+${code.substring(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 && !iface.allowArbitraryProps) {
+    // Use 'object' for empty interfaces instead of '{}'
+    return `export type ${iface.name} = object;\n`;
+  }
+
+  let code = `export type ${iface.name} = {\n`;
+
+  // Add index signature if this type allows arbitrary properties
+  if (iface.allowArbitraryProps) {
+    code += `  /**\n`;
+    code += `   * This type allows arbitrary additional properties beyond those defined below.\n`;
+    code += `   * This is common for config maps, custom settings, and extensible configurations.\n`;
+    code += `   */\n`;
+    code += `  [key: string]: unknown;\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 || prop.default !== undefined) {
+      code += `  /**\n`;
+
+      if (prop.description) {
+        // Format multi-line descriptions properly with " * " prefix
+        // Escape */ sequences to prevent premature comment closure
+        const escapedDescription = prop.description.replace(/\*\//g, "*\\/");
+        const descLines = escapedDescription.split("\n");
+        for (const line of descLines) {
+          code += `   * ${line}\n`;
+        }
+      }
+
+      if (prop.default !== undefined) {
+        const defaultStr = formatDefaultValue(prop.default);
+        if (defaultStr) {
+          if (prop.description) code += `   *\n`;
+          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.substring(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).replace(/-/g, "");
+  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.replace(/"/g, "");
+    const fullKey = prefix ? `${prefix}.${cleanKey}` : cleanKey;
+
+    if (prop.nested) {
+      keys.push(...flattenInterfaceKeys(prop.nested, fullKey));
+    } else {
+      keys.push(fullKey);
+    }
+  }
+
+  return keys;
+}
+
+function capitalizeFirst(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/src/reset.d.ts

@@ -0,0 +1 @@
+import "@total-typescript/ts-reset";

package/src/schemas.ts

@@ -0,0 +1,37 @@
+// Zod schemas for runtime validation
+import { z } from "zod";
+
+// Individual Zod schemas for type detection
+export const StringSchema = z.string();
+export const ActualNumberSchema = z.number(); // Runtime number
+export const ActualBooleanSchema = z.boolean(); // Runtime boolean
+export const NullSchema = z.null();
+export const UndefinedSchema = z.undefined();
+export const ArraySchema = z.array(z.unknown());
+export const RecordSchema = z.record(z.string(), z.unknown());
+export const ErrorSchema = z.instanceof(Error);
+
+// Custom boolean string parser - only matches actual boolean-like strings
+export const StringBooleanSchema = z.string().refine((val) => {
+  const lower = val.toLowerCase();
+  return lower === "true" || lower === "false" || lower === "yes" || lower === "no";
+}, "Not a boolean string");
+
+// Zod schema for validating YAML values - recursive definition with more flexibility
+export const HelmValueSchema: z.ZodType<Record<string, unknown>> = z.lazy(() =>
+  z.record(
+    z.string(),
+    z.union([
+      z.string(),
+      z.number(),
+      z.boolean(),
+      z.null(),
+      z.undefined(),
+      z.array(z.unknown()), // Allow arrays of any type
+      HelmValueSchema,
+      z.unknown(), // Allow any other values as fallback
+    ]),
+  ),
+);
+
+export type HelmValue = z.infer<typeof HelmValueSchema>;