@shepherdjerred/helm-types 1.7.0 → 2.0.0

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/code-generator.ts

@@ -1,226 +0,0 @@
-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 !== "" && 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;
-}

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