@shepherdjerred/helm-types 1.7.0-dev.14406 → 1.7.0-dev.14474

package/src/cli.ts

@@ -1,217 +0,0 @@
-#!/usr/bin/env bun
-/**
- * CLI for @homelab/helm-types
- *
- * Generate TypeScript types from Helm charts
- */
-import { z } from "zod";
-import { fetchHelmChart } from "./chart-fetcher.ts";
-import { convertToTypeScriptInterface } from "./type-converter.ts";
-import { generateTypeScriptCode } from "./interface-generator.ts";
-import type { ChartInfo } from "./types.ts";
-
-const ErrorSchema = z.object({
-  message: z.string(),
-});
-
-const HELP_TEXT = String.raw`
-helm-types - Generate TypeScript types from Helm charts
-
-USAGE:
-  bunx @homelab/helm-types [options]
-
-OPTIONS:
-  --name, -n          Unique identifier for the chart (required)
-  --chart, -c         Chart name in the repository (defaults to --name)
-  --repo, -r          Helm repository URL (required)
-  --version, -v       Chart version (required)
-  --output, -o        Output file path (defaults to stdout)
-  --interface, -i     Interface name (auto-generated from chart name if not provided)
-  --help, -h          Show this help message
-
-EXAMPLES:
-  # Generate types for ArgoCD and print to stdout
-  bunx @homelab/helm-types \
-    --name argo-cd \
-    --repo https://argoproj.github.io/argo-helm \
-    --version 8.3.1
-
-  # Generate types with custom output file
-  bunx @homelab/helm-types \
-    --name argo-cd \
-    --repo https://argoproj.github.io/argo-helm \
-    --version 8.3.1 \
-    --output argo-cd.types.ts
-
-  # Generate types with custom chart name and interface name
-  bunx @homelab/helm-types \
-    --name argocd \
-    --chart argo-cd \
-    --repo https://argoproj.github.io/argo-helm \
-    --version 8.3.1 \
-    --interface ArgocdHelmValues \
-    --output argocd.types.ts
-`;
-
-type CliArgs = {
-  name?: string;
-  chart?: string;
-  repo?: string;
-  version?: string;
-  output?: string;
-  interface?: string;
-  help?: boolean;
-};
-
-/** String-valued flag names (excludes boolean 'help') */
-type StringCliArgsKey = Exclude<keyof CliArgs, "help">;
-
-/** Map from flag name to CliArgs key */
-const FLAG_MAP: Record<string, StringCliArgsKey> = {
-  "--name": "name",
-  "-n": "name",
-  "--chart": "chart",
-  "-c": "chart",
-  "--repo": "repo",
-  "-r": "repo",
-  "--version": "version",
-  "-v": "version",
-  "--output": "output",
-  "-o": "output",
-  "--interface": "interface",
-  "-i": "interface",
-};
-
-const HELP_FLAGS = new Set(["--help", "-h"]);
-
-/**
- * Simple argument parser for Bun CLI
- */
-function parseCliArgs(args: string[]): CliArgs {
-  const result: CliArgs = {};
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "" || arg == null) {
-      continue;
-    }
-
-    if (HELP_FLAGS.has(arg)) {
-      result.help = true;
-      continue;
-    }
-
-    const key = FLAG_MAP[arg];
-    if (key != null) {
-      const value = args[i + 1];
-      if (value !== "" && value != null) {
-        result[key] = value;
-        i += 1;
-      }
-      continue;
-    }
-
-    if (arg.startsWith("-")) {
-      throw new Error(`Unknown argument: ${arg}`);
-    }
-  }
-
-  return result;
-}
-
-async function main() {
-  try {
-    const args = parseCliArgs(Bun.argv.slice(2));
-
-    // Show help
-    if (args.help === true) {
-      console.log(HELP_TEXT);
-      process.exit(0);
-    }
-
-    // Validate required arguments
-    if (
-      args.name == null ||
-      args.name === "" ||
-      args.repo == null ||
-      args.repo === "" ||
-      args.version == null ||
-      args.version === ""
-    ) {
-      console.error("Error: Missing required arguments");
-      console.error("Required: --name, --repo, --version");
-      console.error("\nRun with --help for usage information");
-      process.exit(1);
-    }
-
-    // Build chart info
-    const chartInfo: ChartInfo = {
-      name: args.name,
-      chartName: args.chart ?? args.name,
-      repoUrl: args.repo,
-      version: args.version,
-    };
-
-    // Generate interface name from chart name if not provided
-    const interfaceName =
-      args.interface ?? `${toPascalCase(args.name)}HelmValues`;
-
-    console.error(
-      `Fetching chart: ${chartInfo.chartName}@${chartInfo.version}`,
-    );
-    console.error(`Repository: ${chartInfo.repoUrl}`);
-    console.error("");
-
-    // Fetch chart
-    const { values, schema, yamlComments } = await fetchHelmChart(chartInfo);
-
-    console.error("");
-    console.error(`Converting to TypeScript interface: ${interfaceName}`);
-
-    // Convert to TypeScript interface
-    const tsInterface = convertToTypeScriptInterface({
-      values,
-      interfaceName,
-      schema,
-      yamlComments,
-      chartName: args.name,
-    });
-
-    // Generate TypeScript code
-    const code = generateTypeScriptCode(tsInterface, args.name);
-
-    // Write to file or stdout
-    if (args.output != null && args.output !== "") {
-      await Bun.write(args.output, code);
-      console.error("");
-      console.error(`✅ Types written to: ${args.output}`);
-    } else {
-      // Write to stdout (so it can be piped)
-      console.log(code);
-    }
-
-    process.exit(0);
-  } catch (error) {
-    const parseResult = ErrorSchema.safeParse(error);
-    if (parseResult.success) {
-      console.error(`Error: ${parseResult.data.message}`);
-    } else {
-      console.error(`Error: ${String(error)}`);
-    }
-    process.exit(1);
-  }
-}
-
-/**
- * Convert a string to PascalCase
- */
-export function toPascalCase(str: string): string {
-  return str
-    .split(/[-_\s]+/)
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
-    .join("");
-}
-
-if (import.meta.main) {
-  void main();
-}

package/src/comment-parser.ts

@@ -1,180 +0,0 @@
-/**
- * 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 === "" || key == null) {
-        continue;
-      }
-
-      // Update indent stack
-      const lastIndent = indentStack.at(-1);
-      while (
-        lastIndent &&
-        indentStack.length > 0 &&
-        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

@@ -1,195 +0,0 @@
-/**
- * Well-known Kubernetes fields whose shape is defined by the Kubernetes API,
- * not by whatever subset a chart's values.yaml happens to set as defaults.
- *
- * Inferring these from defaults produces types that are too narrow — e.g. a
- * chart defaulting `resources: {requests: {cpu: 0.2}}` would otherwise forbid
- * setting a memory request at all. When a property matches one of these names
- * AND its default value has a compatible shape, the canonical permissive type
- * is emitted instead of a defaults-derived interface.
- */
-const K8S_WELL_KNOWN_FIELDS: Record<
-  string,
-  { type: string; allowedShapes: ("object" | "array")[]; description: string }
-> = {
-  resources: {
-    type: "{ requests?: Record<string, string | number>; limits?: Record<string, string | number> }",
-    // RBAC rules also use a key named `resources`, but as an array of strings —
-    // the object guard keeps those out.
-    allowedShapes: ["object"],
-    description:
-      "Kubernetes container resources (standard ResourceRequirements: arbitrary resource names, string or numeric quantities)",
-  },
-  nodeselector: {
-    type: "Record<string, string>",
-    allowedShapes: ["object"],
-    description: "Kubernetes nodeSelector (arbitrary label key/value pairs)",
-  },
-  tolerations: {
-    type: "unknown[]",
-    allowedShapes: ["array"],
-    description: "Kubernetes tolerations (standard Toleration objects)",
-  },
-  affinity: {
-    type: "Record<string, unknown>",
-    allowedShapes: ["object"],
-    description: "Kubernetes affinity (standard Affinity object)",
-  },
-};
-
-/**
- * Return the canonical type for a well-known Kubernetes field, or undefined if
- * the property name doesn't match or the default value's shape is incompatible
- * (e.g. an RBAC `resources: ["secrets"]` array, which must NOT become
- * ResourceRequirements).
- */
-export function getWellKnownK8sFieldType(
-  propertyName: string,
-  value: unknown,
-): { type: string; description: string } | undefined {
-  const field = K8S_WELL_KNOWN_FIELDS[propertyName.toLowerCase()];
-  if (!field) {
-    return undefined;
-  }
-  // A null/undefined default carries no shape signal — trust the name.
-  if (value != null) {
-    const shape: "object" | "array" | "primitive" = Array.isArray(value)
-      ? "array"
-      : typeof value === "object"
-        ? "object"
-        : "primitive";
-    if (shape === "primitive" || !field.allowedShapes.includes(shape)) {
-      return undefined;
-    }
-  }
-  return { type: field.type, description: field.description };
-}
-
-/**
- * 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 receiver-specific config blocks 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
-  ],
-  // OCI charts that document config keys only as commented-out examples in
-  // values.yaml, so inference from active defaults misses valid keys.
-  "agent-stack-k8s": [
-    "config", // config.queue / max-in-flight / empty-job-grace-period / default-checkout-params are valid but not defaulted
-  ],
-};
-
-/**
- * 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 !== "" && yamlComment != null) {
-    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/index.ts

@@ -1,28 +0,0 @@
-/**
- * @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";