@shepherdjerred/helm-types 1.7.0 → 2.0.0

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";

package/src/interface-generator.ts

@@ -1,238 +0,0 @@
-import type { TypeScriptInterface } from "./types.ts";
-import {
-  ArraySchema,
-  RecordSchema,
-  StringSchema,
-  ActualNumberSchema,
-  ActualBooleanSchema,
-} from "./schemas.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 && iface.allowArbitraryProps !== true) {
-    // 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 === true) {
-    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 != 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 !== "" && hasDescription && defaultStr != null) {
-          code += `   *\n`;
-        }
-        if (defaultStr !== "" && defaultStr != null) {
-          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;
-}
-
-function capitalizeFirst(str: string): string {
-  return str.charAt(0).toUpperCase() + str.slice(1);
-}

package/src/reset.d.ts

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

package/src/type-converter-helpers.ts

@@ -1,108 +0,0 @@
-import type { JSONSchemaProperty, TypeProperty } from "./types.ts";
-import {
-  StringSchema,
-  ActualNumberSchema,
-  ActualBooleanSchema,
-  StringBooleanSchema,
-} from "./schemas.ts";
-
-export type PropertyConversionContext = {
-  value: unknown;
-  nestedTypeName: string;
-  schema?: JSONSchemaProperty;
-  propertyName?: string;
-  yamlComment?: string;
-  yamlComments?: Map<string, string>;
-  fullKey?: string;
-  chartName?: string;
-};
-
-/**
- * Merge description from schema and YAML comments
- */
-export function mergeDescriptions(
-  schemaDescription: string | undefined,
-  yamlComment: string | undefined,
-): string | undefined {
-  if (yamlComment === "" || yamlComment == null) {
-    return schemaDescription;
-  }
-  return schemaDescription !== "" && schemaDescription != null
-    ? `${yamlComment}\n\n${schemaDescription}`
-    : yamlComment;
-}
-
-/**
- * Infer a primitive TypeProperty from a runtime value (no schema)
- */
-export function inferPrimitiveType(
-  value: unknown,
-  yamlComment?: string,
-): TypeProperty {
-  if (ActualBooleanSchema.safeParse(value).success) {
-    return {
-      type: "boolean",
-      optional: true,
-      description: yamlComment,
-      default: value,
-    };
-  }
-
-  if (ActualNumberSchema.safeParse(value).success) {
-    return {
-      type: "number",
-      optional: true,
-      description: yamlComment,
-      default: value,
-    };
-  }
-
-  if (StringBooleanSchema.safeParse(value).success) {
-    return {
-      type: "boolean",
-      optional: true,
-      description: yamlComment,
-      default: value,
-    };
-  }
-
-  const stringCheckForNumber = StringSchema.safeParse(value);
-  if (stringCheckForNumber.success) {
-    const trimmed = stringCheckForNumber.data.trim();
-    if (
-      trimmed !== "" &&
-      !Number.isNaN(Number(trimmed)) &&
-      Number.isFinite(Number(trimmed))
-    ) {
-      return {
-        type: "number",
-        optional: true,
-        description: yamlComment,
-        default: value,
-      };
-    }
-  }
-
-  const stringCheckForPlain = StringSchema.safeParse(value);
-  if (stringCheckForPlain.success) {
-    if (stringCheckForPlain.data === "default") {
-      return {
-        type: "string | number | boolean",
-        optional: true,
-        description: yamlComment,
-        default: value,
-      };
-    }
-    return {
-      type: "string",
-      optional: true,
-      description: yamlComment,
-      default: value,
-    };
-  }
-
-  console.warn(
-    `Unrecognized value type for: ${String(value)}, using 'unknown'`,
-  );
-  return { type: "unknown", optional: true, description: yamlComment };
-}