@shepherdjerred/helm-types 1.1.0 → 1.2.0-dev.893

package/src/comment-parser.ts

@@ -1,72 +1,83 @@
+/**
+ * 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) => {
-    // Remove leading # symbols
-    line = line.replace(/^#+\s*/, "");
-    // Remove common Helm chart comment markers
-    line = line.replace(/^--\s*/, "");
-    line = line.replace(/^##\s*/, "");
-    return line.trim();
-  });
+  const lines = comment.split("\n").map((line) => stripCommentMarkers(line));
 
   // Filter and clean lines
   const cleaned: string[] = [];
   let inCodeBlock = false;
 
-  for (const line of lines) {
-    const currentLine = line;
-
-    // Skip empty lines
+  for (const currentLine of lines) {
     if (currentLine.length === 0) {
-      if (inCodeBlock) inCodeBlock = false;
+      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) {
+    if (currentLine.startsWith("@default")) {
+      continue;
+    }
+
+    if (isExampleLine(currentLine)) {
       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) {
+      if (looksLikeProse(currentLine)) {
         inCodeBlock = false;
       } else {
         continue;
       }
     }
 
-    // Keep the line
     cleaned.push(currentLine);
   }
 
@@ -96,7 +107,7 @@ export function parseYAMLComments(yamlContent: string): Map<string, string> {
 
     // Check if line is a comment
     if (trimmed.startsWith("#")) {
-      const comment = trimmed.substring(1).trim();
+      const comment = trimmed.slice(1).trim();
       if (comment) {
         // Track the indentation level of the comment
         const commentIndent = currentLine.search(/\S/);
@@ -106,35 +117,48 @@ export function parseYAMLComments(yamlContent: string): Map<string, string> {
     }
 
     // Check if line has a key
-    const keyMatch = /^(\s*)([a-zA-Z0-9_-]+)\s*:/.exec(currentLine);
+    const keyMatch = /^(\s*)([\w-]+)\s*:/.exec(currentLine);
     if (keyMatch) {
       const indent = keyMatch[1]?.length ?? 0;
       const key = keyMatch[2];
-      if (!key) continue;
+      if (key == null || key === "") {
+        continue;
+      }
 
       // Update indent stack
-      const lastIndent = indentStack[indentStack.length - 1];
-      while (indentStack.length > 0 && lastIndent && lastIndent.indent >= indent) {
+      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;
+      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]) {
+      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);
+      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"));
+        const commentText = cleanYAMLComment(
+          relevantComments.map((c) => c.text).join("\n"),
+        );
         if (commentText) {
           comments.set(keyPath, commentText);
         }

package/src/config.ts

@@ -17,7 +17,9 @@ export const K8S_RESOURCE_SPEC_PATTERN = {
  * 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());
+  return K8S_RESOURCE_SPEC_PATTERN.resourceSpecNames.includes(
+    propertyName.toLowerCase(),
+  );
 }
 
 /**
@@ -86,7 +88,10 @@ export function shouldAllowArbitraryProps(
   const patterns = EXTENSIBLE_TYPE_PATTERNS[chartName];
   if (patterns) {
     for (const pattern of patterns) {
-      if (pattern === keyPath || (pattern === "" && keyPath.split(".").length === 1)) {
+      if (
+        pattern === keyPath ||
+        (pattern === "" && keyPath.split(".").length === 1)
+      ) {
         return true;
       }
       // Also match if keyPath starts with pattern
@@ -126,11 +131,13 @@ export function shouldAllowArbitraryProps(
   }
 
   // Check YAML comments for hints
-  if (yamlComment) {
+  if (yamlComment != null && 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)
+      /\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;
     }

package/src/helm-types.ts

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

@@ -11,5 +11,18 @@
  *
  * 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)
  */
-export * from "./helm-types.ts";
+
+/** Version marker for the helm-types package. */
+export const HELM_TYPES_PACKAGE_VERSION = "1.1.0";

package/src/interface-generator.ts

@@ -1,10 +1,19 @@
-import type { TypeScriptInterface } from "./types.js";
-import { ArraySchema, RecordSchema, StringSchema, ActualNumberSchema, ActualBooleanSchema } from "./schemas.js";
+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 {
+export function generateTypeScriptCode(
+  mainInterface: TypeScriptInterface,
+  chartName: string,
+): string {
   const interfaces: TypeScriptInterface[] = [];
 
   // Collect all nested interfaces
@@ -21,18 +30,20 @@ export function generateTypeScriptCode(mainInterface: TypeScriptInterface, chart
   // Generate parameter type (flattened dot notation)
   code += generateParameterType(mainInterface, chartName);
 
-  // Check if any 'any' types were generated and add ESLint disable if needed
+  // Add header comment for generated files
   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)}`;
+${code.slice(Math.max(0, code.indexOf("\n\n") + 2))}`;
   }
 
   return code;
 }
 
-function collectNestedInterfaces(iface: TypeScriptInterface, collected: TypeScriptInterface[]): void {
+function collectNestedInterfaces(
+  iface: TypeScriptInterface,
+  collected: TypeScriptInterface[],
+): void {
   for (const prop of Object.values(iface.properties)) {
     if (prop.nested) {
       collected.push(prop.nested);
@@ -49,7 +60,7 @@ function collectNestedInterfaces(iface: TypeScriptInterface, collected: TypeScri
 function generateInterfaceCode(iface: TypeScriptInterface): string {
   const hasProperties = Object.keys(iface.properties).length > 0;
 
-  if (!hasProperties && !iface.allowArbitraryProps) {
+  if (!hasProperties && iface.allowArbitraryProps !== true) {
     // Use 'object' for empty interfaces instead of '{}'
     return `export type ${iface.name} = object;\n`;
   }
@@ -57,7 +68,7 @@ function generateInterfaceCode(iface: TypeScriptInterface): string {
   let code = `export type ${iface.name} = {\n`;
 
   // Add index signature if this type allows arbitrary properties
-  if (iface.allowArbitraryProps) {
+  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`;
@@ -69,13 +80,19 @@ function generateInterfaceCode(iface: TypeScriptInterface): string {
     const optional = prop.optional ? "?" : "";
 
     // Generate JSDoc comment if we have description or default
-    if (prop.description || prop.default !== undefined) {
+    if (
+      (prop.description != null && prop.description !== "") ||
+      prop.default !== undefined
+    ) {
       code += `  /**\n`;
 
-      if (prop.description) {
+      if (prop.description != null && prop.description !== "") {
         // Format multi-line descriptions properly with " * " prefix
         // Escape */ sequences to prevent premature comment closure
-        const escapedDescription = prop.description.replace(/\*\//g, "*\\/");
+        const escapedDescription = prop.description.replaceAll(
+          "*/",
+          String.raw`*\/`,
+        );
         const descLines = escapedDescription.split("\n");
         for (const line of descLines) {
           code += `   * ${line}\n`;
@@ -84,8 +101,12 @@ function generateInterfaceCode(iface: TypeScriptInterface): string {
 
       if (prop.default !== undefined) {
         const defaultStr = formatDefaultValue(prop.default);
-        if (defaultStr) {
-          if (prop.description) code += `   *\n`;
+        const hasDescription =
+          prop.description != null && prop.description !== "";
+        if (defaultStr != null && defaultStr !== "" && hasDescription) {
+          code += `   *\n`;
+        }
+        if (defaultStr != null && defaultStr !== "") {
           code += `   * @default ${defaultStr}\n`;
         }
       }
@@ -104,13 +125,19 @@ function generateInterfaceCode(iface: TypeScriptInterface): string {
  * Format a default value for display in JSDoc
  */
 function formatDefaultValue(value: unknown): string | null {
-  if (value === null) return "null";
-  if (value === undefined) return 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 === 0) {
+      return "[]";
+    }
     if (arrayCheck.data.length <= 3) {
       try {
         return JSON.stringify(arrayCheck.data);
@@ -125,7 +152,9 @@ function formatDefaultValue(value: unknown): string | null {
   const recordCheck = RecordSchema.safeParse(value);
   if (recordCheck.success) {
     const keys = Object.keys(recordCheck.data);
-    if (keys.length === 0) return "{}";
+    if (keys.length === 0) {
+      return "{}";
+    }
     if (keys.length <= 3) {
       try {
         return JSON.stringify(recordCheck.data);
@@ -141,7 +170,7 @@ function formatDefaultValue(value: unknown): string | null {
   if (stringCheck.success) {
     // Truncate long strings
     if (stringCheck.data.length > 50) {
-      return `"${stringCheck.data.substring(0, 47)}..."`;
+      return `"${stringCheck.data.slice(0, 47)}..."`;
     }
     return `"${stringCheck.data}"`;
   }
@@ -165,10 +194,13 @@ function formatDefaultValue(value: unknown): string | null {
   }
 }
 
-function generateParameterType(iface: TypeScriptInterface, chartName: string): string {
+function generateParameterType(
+  iface: TypeScriptInterface,
+  chartName: string,
+): string {
   const parameterKeys = flattenInterfaceKeys(iface);
 
-  const normalizedChartName = capitalizeFirst(chartName).replace(/-/g, "");
+  const normalizedChartName = capitalizeFirst(chartName).replaceAll("-", "");
   let code = `export type ${normalizedChartName}HelmParameters = {\n`;
 
   for (const key of parameterKeys) {
@@ -180,12 +212,15 @@ function generateParameterType(iface: TypeScriptInterface, chartName: string): s
   return code;
 }
 
-function flattenInterfaceKeys(iface: TypeScriptInterface, prefix = ""): string[] {
+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 cleanKey = key.replaceAll('"', "");
     const fullKey = prefix ? `${prefix}.${cleanKey}` : cleanKey;
 
     if (prop.nested) {

package/src/schemas.ts

@@ -14,7 +14,9 @@ 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";
+  return (
+    lower === "true" || lower === "false" || lower === "yes" || lower === "no"
+  );
 }, "Not a boolean string");
 
 // Zod schema for validating YAML values - recursive definition with more flexibility