@shepherdjerred/helm-types 1.1.0

package/README.md

@@ -0,0 +1,200 @@
+# @shepherdjerred/helm-types
+
+Generate TypeScript types from Helm chart values.
+
+## What it does
+
+This tool fetches Helm charts and generates strongly-typed TypeScript interfaces from their
+`values.yaml` and `values.schema.json` files. Use it to get type-safe Helm configurations in your
+TypeScript projects.
+
+**Features:**
+
+- Fetch charts from any Helm repository
+- Generate nested interfaces with proper types
+- Parse YAML comments for JSDoc documentation
+- Support for arrays, unions, enums, and optional properties
+- Handle reserved keywords and special characters
+
+## Installation
+
+```bash
+npm install @shepherdjerred/helm-types
+# or
+bun add @shepherdjerred/helm-types
+```
+
+## Requirements
+
+- **Node.js 18+** or **Bun**
+- **Helm CLI** installed and available in PATH
+
+## CLI Usage
+
+Generate types directly with npx/bunx:
+
+```bash
+# Generate types for ArgoCD
+npx @shepherdjerred/helm-types \
+  --name argo-cd \
+  --repo https://argoproj.github.io/argo-helm \
+  --version 8.3.1 \
+  --output argo-cd.types.ts
+
+# Short flags
+npx @shepherdjerred/helm-types \
+  -n argo-cd \
+  -r https://argoproj.github.io/argo-helm \
+  -v 8.3.1 \
+  -o argo-cd.types.ts
+
+# Print to stdout
+npx @shepherdjerred/helm-types \
+  -n argo-cd \
+  -r https://argoproj.github.io/argo-helm \
+  -v 8.3.1
+
+# Custom interface name
+npx @shepherdjerred/helm-types \
+  -n argo-cd \
+  -r https://argoproj.github.io/argo-helm \
+  -v 8.3.1 \
+  -i CustomArgocdValues \
+  -o argo-cd.types.ts
+```
+
+**Options:**
+
+| Flag              | Description                                     |
+| ----------------- | ----------------------------------------------- |
+| `--name, -n`      | Unique identifier for the chart (required)      |
+| `--chart, -c`     | Chart name in 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 if not provided) |
+| `--help, -h`      | Show help message                               |
+
+## Programmatic API
+
+```typescript
+import { fetchHelmChart, convertToTypeScriptInterface, generateTypeScriptCode } from "@shepherdjerred/helm-types";
+
+// 1. Define your chart
+const chart = {
+  name: "argo-cd",
+  chartName: "argo-cd",
+  repoUrl: "https://argoproj.github.io/argo-helm",
+  version: "8.3.1",
+};
+
+// 2. Fetch and generate types
+const { values, schema, yamlComments } = await fetchHelmChart(chart);
+const tsInterface = convertToTypeScriptInterface(values, "ArgocdHelmValues", schema, yamlComments);
+const code = generateTypeScriptCode(tsInterface, chart.name);
+
+// 3. Write output
+await fs.writeFile("argo-cd.types.ts", code);
+```
+
+## Generated Output
+
+### Values Interface
+
+```typescript
+export type ArgocdHelmValues = {
+  /**
+   * Number of replicas
+   * @default 1
+   */
+  replicaCount?: number;
+
+  image?: ArgocdHelmValuesImage;
+  service?: ArgocdHelmValuesService;
+};
+```
+
+### Nested Types
+
+```typescript
+export type ArgocdHelmValuesImage = {
+  repository?: string;
+  tag?: string;
+  pullPolicy?: "Always" | "IfNotPresent" | "Never";
+};
+```
+
+### Parameters Type (Flattened)
+
+A flattened type using dot notation for Helm's `--set` parameter syntax:
+
+```typescript
+export type ArgocdHelmParameters = {
+  replicaCount?: string;
+  "image.repository"?: string;
+  "image.tag"?: string;
+  "service.type"?: string;
+};
+```
+
+## Type Inference
+
+The library intelligently infers types from values:
+
+| Value               | Inferred Type    |
+| ------------------- | ---------------- |
+| `true`, `false`     | `boolean`        |
+| `"true"`, `"false"` | `boolean`        |
+| `123`, `3.14`       | `number`         |
+| `"123"`             | `number`         |
+| `"hello"`           | `string`         |
+| `[]`                | `unknown[]`      |
+| `[1, 2]`            | `number[]`       |
+| `{}`                | nested interface |
+
+JSON schema takes precedence when available.
+
+## API Reference
+
+### `fetchHelmChart(chart: ChartInfo)`
+
+Fetches a Helm chart and extracts configuration.
+
+```typescript
+type ChartInfo = {
+  name: string; // Unique identifier
+  chartName: string; // Chart name in repo
+  repoUrl: string; // Helm repository URL
+  version: string; // Chart version
+};
+
+// Returns
+{
+  values: Record<string, unknown>;
+  schema: JSONSchemaProperty | null;
+  yamlComments: Map<string, string>;
+}
+```
+
+### `convertToTypeScriptInterface(values, name, schema?, comments?, prefix?)`
+
+Converts Helm values to TypeScript interface definition.
+
+- `values` - Chart values object
+- `name` - Interface name
+- `schema?` - Optional JSON schema for type hints
+- `comments?` - Optional YAML comments for JSDoc
+- `prefix?` - Optional key prefix for nested types
+
+### `generateTypeScriptCode(interface, chartName)`
+
+Generates TypeScript code from interface definition. Returns a string containing the main values
+interface, nested type definitions, and flattened parameters type.
+
+### `parseYAMLComments(yamlContent)`
+
+Extracts YAML comments and associates them with keys.
+
+## License
+
+GPL-3.0