@intentius/chant-lexicon-helm 0.0.16

package/dist/rules/whm407.ts

@@ -0,0 +1,83 @@
+/**
+ * WHM407: `kind: Secret` with inline `data:` values and no ExternalSecret/SealedSecret.
+ *
+ * Warns when secrets contain inline data values (not `.Values` refs) and the chart
+ * does not use ExternalSecret or SealedSecret resources.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getChartFiles } from "./helm-helpers";
+
+export const whm407: PostSynthCheck = {
+  id: "WHM407",
+  description: "Secrets with inline data should use ExternalSecret or SealedSecret",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const files = getChartFiles(output);
+
+      // Check if chart uses ExternalSecret or SealedSecret anywhere
+      const allContent = Object.values(files).join("\n");
+      const hasExternalSecret = allContent.includes("ExternalSecret") || allContent.includes("SealedSecret");
+
+      for (const [filename, content] of Object.entries(files)) {
+        if (!filename.startsWith("templates/") || filename.endsWith("_helpers.tpl") || filename.endsWith("NOTES.txt")) continue;
+        if (filename.includes("tests/")) continue;
+
+        if (!content.includes("kind: Secret")) continue;
+
+        // Scan for inline data values in data: or stringData: sections
+        const lines = content.split("\n");
+        let inData = false;
+        let dataIndent = -1;
+        let hasLiteralValues = false;
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed || trimmed.startsWith("#")) continue;
+
+          const indent = line.length - line.trimStart().length;
+
+          if (trimmed === "data:" || trimmed === "stringData:") {
+            inData = true;
+            dataIndent = indent;
+            continue;
+          }
+
+          if (inData) {
+            // If we've returned to the same or lower indent level, exit data section
+            if (indent <= dataIndent && trimmed) {
+              inData = false;
+              dataIndent = -1;
+              continue;
+            }
+            // Check if value is a literal (not a template expression)
+            if (!trimmed.includes("{{") && !trimmed.includes(".Values")) {
+              const colonIdx = trimmed.indexOf(":");
+              if (colonIdx > 0 && trimmed.length > colonIdx + 1 && trimmed[colonIdx + 1] === " ") {
+                const val = trimmed.slice(colonIdx + 1).trim();
+                if (val) {
+                  hasLiteralValues = true;
+                }
+              }
+            }
+          }
+        }
+
+        if (hasLiteralValues && !hasExternalSecret) {
+          diagnostics.push({
+            checkId: "WHM407",
+            severity: "warning",
+            message: `${filename}: Secret with inline data values — consider using ExternalSecret or SealedSecret for secret management`,
+            entity: filename,
+            lexicon: "helm",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/whm501.ts

@@ -0,0 +1,103 @@
+/**
+ * WHM501: Unused values keys.
+ *
+ * Parses values.yaml key paths and scans all template files for
+ * `.Values.` references. Keys defined but never referenced produce
+ * an info diagnostic.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getChartFiles } from "./helm-helpers";
+
+/** Keys that are always implicitly used (e.g. in _helpers.tpl). */
+const IMPLICIT_KEYS = new Set(["nameOverride", "fullnameOverride"]);
+
+/**
+ * Extract all top-level and nested key paths from values.yaml content.
+ * Uses indentation to track nesting (2-space indent per level).
+ */
+function extractValuePaths(content: string): string[] {
+  const paths: string[] = [];
+  const stack: string[] = [];
+  let prevIndent = -1;
+
+  for (const line of content.split("\n")) {
+    const trimmed = line.trimStart();
+    if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("-")) continue;
+
+    const indent = line.length - trimmed.length;
+    const match = trimmed.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:/);
+    if (!match) continue;
+
+    const key = match[1];
+
+    // Adjust stack based on indentation
+    while (stack.length > 0 && indent <= prevIndent) {
+      stack.pop();
+      prevIndent -= 2;
+    }
+
+    stack.push(key);
+    paths.push(stack.join("."));
+    prevIndent = indent;
+  }
+
+  return paths;
+}
+
+export const whm501: PostSynthCheck = {
+  id: "WHM501",
+  description: "Detect values keys that are defined but never referenced in templates",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const files = getChartFiles(output);
+      const valuesContent = files["values.yaml"];
+      if (!valuesContent || valuesContent.trim() === "{}" || valuesContent.trim() === "") continue;
+
+      const definedPaths = extractValuePaths(valuesContent);
+      if (definedPaths.length === 0) continue;
+
+      // Collect all .Values references from templates
+      const referencedPaths = new Set<string>();
+      const valuesRegex = /\.Values\.([a-zA-Z0-9_.]+)/g;
+
+      for (const [filename, content] of Object.entries(files)) {
+        if (!filename.startsWith("templates/")) continue;
+        let match;
+        while ((match = valuesRegex.exec(content)) !== null) {
+          referencedPaths.add(match[1]);
+        }
+      }
+
+      for (const path of definedPaths) {
+        if (IMPLICIT_KEYS.has(path)) continue;
+
+        // Check if this path or any child is referenced
+        const isReferenced = referencedPaths.has(path) ||
+          [...referencedPaths].some((ref) => ref.startsWith(path + "."));
+
+        // Check if any parent of this path is referenced (parent consumed entirely)
+        const parts = path.split(".");
+        const parentReferenced = parts.some((_, i) => {
+          if (i === parts.length - 1) return false;
+          return referencedPaths.has(parts.slice(0, i + 1).join("."));
+        });
+
+        if (!isReferenced && !parentReferenced) {
+          diagnostics.push({
+            checkId: "WHM501",
+            severity: "info",
+            message: `values.yaml defines "${path}" but it is never referenced in templates`,
+            entity: "values.yaml",
+            lexicon: "helm",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/whm502.ts

@@ -0,0 +1,94 @@
+/**
+ * WHM502: K8s API version/kind validation.
+ *
+ * Checks for deprecated or invalid Kubernetes API versions in templates
+ * and suggests replacements.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getChartFiles } from "./helm-helpers";
+
+/**
+ * Deprecated API versions with their replacements.
+ */
+const DEPRECATED_APIS: Record<string, { replacement: string; kinds: string[] }> = {
+  "extensions/v1beta1": {
+    replacement: "networking.k8s.io/v1",
+    kinds: ["Ingress"],
+  },
+  "networking.k8s.io/v1beta1": {
+    replacement: "networking.k8s.io/v1",
+    kinds: ["Ingress", "IngressClass"],
+  },
+  "apps/v1beta1": {
+    replacement: "apps/v1",
+    kinds: ["Deployment", "StatefulSet"],
+  },
+  "apps/v1beta2": {
+    replacement: "apps/v1",
+    kinds: ["Deployment", "StatefulSet", "DaemonSet", "ReplicaSet"],
+  },
+  "rbac.authorization.k8s.io/v1beta1": {
+    replacement: "rbac.authorization.k8s.io/v1",
+    kinds: ["ClusterRole", "ClusterRoleBinding", "Role", "RoleBinding"],
+  },
+  "admissionregistration.k8s.io/v1beta1": {
+    replacement: "admissionregistration.k8s.io/v1",
+    kinds: ["MutatingWebhookConfiguration", "ValidatingWebhookConfiguration"],
+  },
+  "batch/v1beta1": {
+    replacement: "batch/v1",
+    kinds: ["CronJob"],
+  },
+  "policy/v1beta1": {
+    replacement: "policy/v1",
+    kinds: ["PodDisruptionBudget", "PodSecurityPolicy"],
+  },
+  "autoscaling/v2beta1": {
+    replacement: "autoscaling/v2",
+    kinds: ["HorizontalPodAutoscaler"],
+  },
+  "autoscaling/v2beta2": {
+    replacement: "autoscaling/v2",
+    kinds: ["HorizontalPodAutoscaler"],
+  },
+};
+
+export const whm502: PostSynthCheck = {
+  id: "WHM502",
+  description: "Detect deprecated or invalid Kubernetes API versions",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const files = getChartFiles(output);
+
+      for (const [filename, content] of Object.entries(files)) {
+        if (!filename.startsWith("templates/") || filename.endsWith("_helpers.tpl") || filename.endsWith("NOTES.txt")) continue;
+
+        // Extract apiVersion from template
+        const apiVersionMatch = content.match(/apiVersion:\s*(.+)/);
+        if (!apiVersionMatch) continue;
+
+        const apiVersion = apiVersionMatch[1].trim();
+
+        // Skip template expressions
+        if (apiVersion.includes("{{")) continue;
+
+        const deprecation = DEPRECATED_APIS[apiVersion];
+        if (deprecation) {
+          diagnostics.push({
+            checkId: "WHM502",
+            severity: "warning",
+            message: `${filename}: apiVersion "${apiVersion}" is deprecated — use "${deprecation.replacement}" instead`,
+            entity: filename,
+            lexicon: "helm",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/skills/chant-helm-chart-patterns.md

@@ -0,0 +1,229 @@
+---
+skill: chant-helm-patterns
+description: Common Helm chart patterns and best practices using chant
+user-invocable: true
+---
+
+# Common Helm Chart Patterns
+
+## Standard Chart Layout
+
+A chant Helm project compiles TypeScript into the standard Helm directory structure:
+
+```
+my-chart/
+  Chart.yaml          ← chart metadata (name, version, apiVersion: v2)
+  values.yaml         ← default configuration values
+  templates/
+    deployment.yaml
+    service.yaml
+    ingress.yaml
+    _helpers.tpl      ← named templates (fullname, labels, etc.)
+    NOTES.txt         ← post-install instructions
+  charts/             ← subcharts (dependencies)
+```
+
+The source of truth is `src/`. Never edit generated files in `templates/` by hand.
+
+## Parameterization via Values Proxy
+
+The `values` proxy turns property access into `{{ .Values.x }}` template directives:
+
+```typescript
+import { values } from "@intentius/chant-lexicon-helm";
+
+// Simple access
+values.replicaCount          // → {{ .Values.replicaCount }}
+
+// Nested access
+values.image.repository      // → {{ .Values.image.repository }}
+values.image.tag             // → {{ .Values.image.tag }}
+
+// Use in resource definitions
+export const deployment = new Deployment({
+  spec: {
+    replicas: values.replicaCount,
+    template: {
+      spec: {
+        containers: [{
+          name: "app",
+          image: printf("%s:%s", values.image.repository, values.image.tag),
+        }],
+      },
+    },
+  },
+});
+```
+
+Default values are set in the `Values` resource, which becomes `values.yaml`.
+
+## Conditional Resources with If()
+
+Wrap resources in `If()` to gate them on a values flag:
+
+```typescript
+import { If, values } from "@intentius/chant-lexicon-helm";
+import { Ingress } from "@intentius/chant-lexicon-k8s";
+
+// Only rendered when .Values.ingress.enabled is true
+export const ingress = If(values.ingress.enabled, new Ingress({
+  metadata: { name: include("my-app.fullname") },
+  spec: {
+    rules: [{ host: values.ingress.hostname }],
+  },
+}));
+```
+
+`If()` wraps the entire template output in `{{- if .Values.ingress.enabled }}...{{- end }}`.
+
+## Helper Templates with include()
+
+Reference named templates from `_helpers.tpl`:
+
+```typescript
+import { include } from "@intentius/chant-lexicon-helm";
+
+export const deployment = new Deployment({
+  metadata: {
+    name: include("my-app.fullname"),
+    labels: include("my-app.labels"),
+  },
+  spec: {
+    selector: {
+      matchLabels: include("my-app.selectorLabels"),
+    },
+  },
+});
+```
+
+The composites (`HelmWebApp`, `HelmMicroservice`, etc.) generate `_helpers.tpl` automatically with standard named templates for fullname, labels, and selector labels.
+
+## Dependency Management with HelmDependency
+
+Declare subchart dependencies that go into `Chart.yaml`:
+
+```typescript
+import { HelmDependency } from "@intentius/chant-lexicon-helm";
+
+export const redisDep = HelmDependency({
+  name: "redis",
+  version: "17.x",
+  repository: "https://charts.bitnami.com/bitnami",
+  condition: "redis.enabled",
+});
+
+export const postgresqlDep = HelmDependency({
+  name: "postgresql",
+  version: "12.x",
+  repository: "https://charts.bitnami.com/bitnami",
+  condition: "postgresql.enabled",
+});
+```
+
+After building, run `helm dependency update` to fetch the subcharts.
+
+## Multi-Environment Configuration
+
+Use separate values files per environment and compose them at deploy time:
+
+```typescript
+// src/infra.ts — base chart with parameterized defaults
+export const app = HelmWebApp({
+  name: "my-app",
+  port: 3000,
+  replicas: 1,              // default for dev
+  imageTag: "latest",       // overridden per env
+});
+```
+
+```bash
+# Deploy with environment-specific overrides
+helm install my-app . -f values.yaml -f values-staging.yaml
+helm install my-app . -f values.yaml -f values-production.yaml
+```
+
+Structure values files as overlays: `values.yaml` (defaults) -> `values-staging.yaml` (overrides) -> `values-production.yaml` (overrides). Later files win.
+
+## Library Charts with HelmLibrary
+
+Create reusable chart libraries that other charts can import:
+
+```typescript
+import { HelmLibrary } from "@intentius/chant-lexicon-helm";
+
+export const library = HelmLibrary({
+  name: "common-templates",
+  version: "1.0.0",
+  templates: {
+    "common.labels": labelsTemplate,
+    "common.annotations": annotationsTemplate,
+    "common.fullname": fullnameTemplate,
+  },
+});
+```
+
+Library charts produce no templates of their own. They are included as dependencies by application charts, which use `include()` to reference the shared named templates.
+
+## Testing Patterns with HelmTest
+
+Add Helm test pods that run on `helm test`:
+
+```typescript
+import { HelmTest } from "@intentius/chant-lexicon-helm";
+
+export const connectivityTest = HelmTest({
+  name: "test-connection",
+  image: "busybox:1.36",
+  command: ["wget", "--spider", "http://my-app:3000/healthz"],
+});
+```
+
+This generates a pod in `templates/tests/` with the `helm.sh/hook: test` annotation. Run tests after install:
+
+```bash
+helm install my-app .
+helm test my-app
+```
+
+**Lint rule WHM301** fires when an application chart has no test resources.
+
+## Composites Quick Reference
+
+| Composite           | Resources created                                           |
+|---------------------|-------------------------------------------------------------|
+| `HelmWebApp`        | Chart, Values, Deployment, Service, Ingress?, HPA?, SA?     |
+| `HelmMicroservice`  | Chart, Values, Deployment, Service, SA, ConfigMap?, PDB?, HPA?, Ingress? |
+| `HelmWorker`        | Chart, Values, Deployment, SA, HPA?, PDB?                   |
+| `HelmCronJob`       | Chart, Values, CronJob                                      |
+| `HelmStatefulSet`   | Chart, Values, StatefulSet, Service                          |
+| `HelmDaemonSet`     | Chart, Values, DaemonSet, SA?                                |
+| `HelmLibrary`       | Chart (type: library), named templates                       |
+
+All composites accept optional `podSecurityContext`, `securityContext`, `nodeSelector`, `tolerations`, `affinity`, and `strategy` fields.
+
+## Built-in Objects
+
+Access Helm's built-in objects in templates:
+
+```typescript
+import { Release, ChartRef, Capabilities } from "@intentius/chant-lexicon-helm";
+
+Release.Name          // {{ .Release.Name }}
+Release.Namespace     // {{ .Release.Namespace }}
+Release.IsUpgrade     // {{ .Release.IsUpgrade }}
+ChartRef.Name         // {{ .Chart.Name }}
+ChartRef.Version      // {{ .Chart.Version }}
+```
+
+## Template Functions
+
+```typescript
+import { include, printf, toYaml, quote, required, helmDefault } from "@intentius/chant-lexicon-helm";
+
+include("my-app.fullname")                    // {{ include "my-app.fullname" . }}
+printf("%s-%s", Release.Name, "worker")       // {{ printf "%s-%s" .Release.Name "worker" }}
+toYaml(values.resources, 12)                  // {{ toYaml .Values.resources | nindent 12 }}
+quote(values.annotations)                     // {{ quote .Values.annotations }}
+required("image.tag is required", values.image.tag)  // {{ required "..." .Values.image.tag }}
+helmDefault(values.replicas, 1)               // {{ default 1 .Values.replicas }}
+```

package/dist/skills/chant-helm-chart-security-patterns.md

@@ -0,0 +1,192 @@
+---
+skill: chant-helm-security
+description: Security best practices for Helm charts built with chant
+user-invocable: true
+---
+
+# Helm Chart Security Patterns
+
+## Pod Security Context
+
+Always set pod-level security constraints. The `podSecurityContext` field applies to all containers in the pod.
+
+```typescript
+import { HelmWebApp } from "@intentius/chant-lexicon-helm";
+
+const app = HelmWebApp({
+  name: "secure-app",
+  port: 3000,
+  podSecurityContext: {
+    runAsNonRoot: true,
+    runAsUser: 1000,
+    runAsGroup: 1000,
+    fsGroup: 1000,
+    seccompProfile: { type: "RuntimeDefault" },
+  },
+});
+```
+
+**Lint rule WHM402** fires when `runAsNonRoot` is not set on any pod spec.
+
+## Container Security Context
+
+Set per-container restrictions to minimize attack surface:
+
+```typescript
+const app = HelmWebApp({
+  name: "hardened-app",
+  port: 8080,
+  securityContext: {
+    readOnlyRootFilesystem: true,
+    allowPrivilegeEscalation: false,
+    capabilities: { drop: ["ALL"] },
+    runAsUser: 1000,
+  },
+});
+```
+
+- **WHM403**: `readOnlyRootFilesystem` not set
+- **WHM404**: `privileged: true` detected
+
+If the application needs to write temporary files, mount a writable `emptyDir` volume at the specific path rather than disabling `readOnlyRootFilesystem`.
+
+## Image Tagging
+
+Never use `:latest` or omit the tag entirely. Use semver tags or digests.
+
+```typescript
+// Bad — WHM401 fires
+HelmWebApp({ name: "app", imageTag: "latest", port: 3000 });
+
+// Good — pinned semver
+HelmWebApp({ name: "app", imageTag: "v2.4.1", port: 3000 });
+
+// Best — pinned digest
+HelmWebApp({ name: "app", imageTag: "sha256:abc123...", port: 3000 });
+```
+
+**Lint rule WHM401** fires when the image uses `:latest` or has no tag at all.
+
+## Secret Management
+
+Never inline secrets in `values.yaml`. Use External Secrets Operator or Sealed Secrets.
+
+```typescript
+import { HelmExternalSecret } from "@intentius/chant-lexicon-helm";
+
+// External Secrets Operator — fetches secrets from a remote store at runtime
+const secrets = HelmExternalSecret({
+  name: "app-secrets",
+  secretStoreName: "aws-secretsmanager",
+  data: {
+    DB_PASSWORD: "prod/db-password",
+    API_KEY: "prod/api-key",
+  },
+});
+```
+
+**Lint rule WHM407** fires when a Secret resource contains inline `data` or `stringData` values. The fix is always to use an external secret provider.
+
+### What NOT to do
+
+```typescript
+// Bad — WHM407 fires, secret value is in source control
+new Secret({
+  metadata: { name: "db-creds" },
+  stringData: { password: "hunter2" },
+});
+```
+
+## RBAC and ServiceAccount
+
+Every workload should run under a dedicated ServiceAccount with minimal RBAC:
+
+```typescript
+const app = HelmMicroservice({
+  name: "payment-api",
+  port: 8080,
+  serviceAccount: true, // creates a dedicated SA
+});
+```
+
+When the workload needs API access, bind only the required verbs and resources:
+
+```typescript
+import { Role, RoleBinding } from "@intentius/chant-lexicon-k8s";
+
+export const role = new Role({
+  metadata: { name: include("payment-api.fullname") },
+  rules: [{
+    apiGroups: [""],
+    resources: ["configmaps"],
+    verbs: ["get", "watch"],
+  }],
+});
+```
+
+Avoid `ClusterRole` with wildcard resources or verbs. Prefer namespace-scoped `Role` bindings.
+
+## Network Policies
+
+Restrict pod-to-pod traffic to only what is required:
+
+```typescript
+import { NetworkPolicy } from "@intentius/chant-lexicon-k8s";
+
+export const netpol = new NetworkPolicy({
+  metadata: { name: "allow-frontend-to-api" },
+  spec: {
+    podSelector: { matchLabels: { app: "payment-api" } },
+    policyTypes: ["Ingress"],
+    ingress: [{
+      from: [{ podSelector: { matchLabels: { app: "frontend" } } }],
+      ports: [{ protocol: "TCP", port: 8080 }],
+    }],
+  },
+});
+```
+
+Start with a default-deny policy per namespace, then add allow rules for known traffic patterns.
+
+## Resource Limits and Requests
+
+Always set both requests and limits. Without them, a single pod can starve others.
+
+```typescript
+const app = HelmMicroservice({
+  name: "api",
+  port: 8080,
+  // HelmMicroservice sets sensible defaults:
+  //   requests: { cpu: "250m", memory: "128Mi" }
+  //   limits:   { cpu: "500m", memory: "256Mi" }
+});
+```
+
+**Lint rule WHM405** fires when a container spec is missing `cpu` or `memory` in resources. **WHM302** fires when resource limits are not set at all.
+
+## Security Lint Rules Reference
+
+| Rule   | What it checks                              | Severity |
+|--------|---------------------------------------------|----------|
+| WHM401 | Image uses `:latest` tag or no tag          | Warning  |
+| WHM402 | `runAsNonRoot` not set on pod               | Warning  |
+| WHM403 | `readOnlyRootFilesystem` not set            | Warning  |
+| WHM404 | `privileged: true` on a container           | Error    |
+| WHM405 | Missing cpu/memory in resource spec         | Warning  |
+| WHM406 | CRD lifecycle limitation (no auto-upgrade)  | Info     |
+| WHM407 | Secret with inline data in source           | Error    |
+
+## Checklist
+
+When reviewing or building a Helm chart, verify:
+
+1. Pod runs as non-root with a numeric UID (`runAsNonRoot: true`, `runAsUser: 1000`)
+2. Containers drop all capabilities (`capabilities: { drop: ["ALL"] }`)
+3. Root filesystem is read-only (`readOnlyRootFilesystem: true`)
+4. Privilege escalation is blocked (`allowPrivilegeEscalation: false`)
+5. Images use pinned semver or digest tags, never `:latest`
+6. Secrets come from an external provider, never inline
+7. Each workload has a dedicated ServiceAccount
+8. RBAC is namespace-scoped with minimal verbs
+9. Network policies restrict ingress/egress to known peers
+10. CPU and memory requests and limits are set on every container