@intentius/chant-lexicon-k3d 0.0.1

package/src/generated/index.d.ts

@@ -0,0 +1,189 @@
+// Code generated by chant k3d generate. DO NOT EDIT.
+
+// --- k3d Entity classes ---
+
+export declare class Cluster {
+  constructor(props: {
+    apiVersion: "k3d.io/v1alpha5";
+    kind: "Simple";
+    agents?: number;
+    env?: EnvVar[];
+    files?: File[];
+    /** Additional IP to multiple hostnames mappings */
+    hostAliases?: HostAlias[];
+    image?: string;
+    kubeAPI?: KubeAPI;
+    metadata?: Metadata;
+    network?: string;
+    options?: Options;
+    ports?: Port[];
+    registries?: Registries;
+    servers?: number;
+    subnet?: string;
+    token?: string;
+    volumes?: Volume[];
+  });
+}
+
+export declare class EnvVar {
+  constructor(props: {
+    envVar?: string;
+    nodeFilters?: string[];
+  });
+}
+
+export declare class File {
+  constructor(props: {
+    destination: string;
+    source: string;
+    description?: string;
+    nodeFilters?: string[];
+  });
+}
+
+export declare class HostAlias {
+  constructor(props: {
+    hostnames?: string[];
+    ip?: string;
+  });
+}
+
+export declare class K3dOptions {
+  constructor(props: {
+    disableImageVolume?: boolean;
+    disableLoadbalancer?: boolean;
+    disableRollback?: boolean;
+    loadbalancer?: LoadbalancerOptions;
+    timeout?: string;
+    wait?: boolean;
+  });
+}
+
+export declare class K3sExtraArg {
+  constructor(props: {
+    arg?: string;
+    nodeFilters?: string[];
+  });
+}
+
+export declare class K3sOptions {
+  constructor(props: {
+    extraArgs?: K3sExtraArg[];
+    nodeLabels?: NodeLabel[];
+  });
+}
+
+export declare class KubeAPI {
+  constructor(props: {
+    host?: string;
+    hostIP?: string;
+    hostPort?: string;
+  });
+}
+
+export declare class KubeconfigOptions {
+  constructor(props: {
+    switchCurrentContext?: boolean;
+    updateDefaultKubeconfig?: boolean;
+  });
+}
+
+export declare class LoadbalancerOptions {
+  constructor(props: {
+    configOverrides?: any[];
+  });
+}
+
+export declare class Metadata {
+  constructor(props: {
+    /** Name of the cluster (must be a valid hostname and will be prefixed with 'k3d-'). Example: 'mycluster'. */
+    name?: string;
+  });
+}
+
+export declare class NodeLabel {
+  constructor(props: {
+    label?: string;
+    nodeFilters?: string[];
+  });
+}
+
+export declare class Options {
+  constructor(props: {
+    k3d?: K3dOptions;
+    k3s?: K3sOptions;
+    kubeconfig?: KubeconfigOptions;
+    runtime?: RuntimeOptions;
+  });
+}
+
+export declare class Port {
+  constructor(props: {
+    nodeFilters?: string[];
+    port?: string;
+  });
+}
+
+export declare class Registries {
+  constructor(props: {
+    /** Reference a K3s registry configuration file or at it's contents here. */
+    config?: string;
+    /** Create a new container image registry alongside the cluster. */
+    create?: RegistryCreate;
+    /** Connect another container image registry to the cluster. */
+    use?: string[];
+  });
+}
+
+export declare class RegistryCreate {
+  constructor(props: {
+    enforcePortMatch?: boolean;
+    host?: string;
+    hostPort?: string;
+    image?: string;
+    name?: string;
+    proxy?: RegistryProxy;
+    volumes?: string[];
+  });
+}
+
+export declare class RegistryProxy {
+  constructor(props: {
+    password?: string;
+    remoteURL?: string;
+    username?: string;
+  });
+}
+
+export declare class RuntimeLabel {
+  constructor(props: {
+    label?: string;
+    nodeFilters?: string[];
+  });
+}
+
+export declare class RuntimeOptions {
+  constructor(props: {
+    agentsMemory?: string;
+    gpuRequest?: string;
+    hostPidMode?: boolean;
+    labels?: RuntimeLabel[];
+    serversMemory?: string;
+    ulimits?: Ulimit[];
+  });
+}
+
+export declare class Ulimit {
+  constructor(props: {
+    hard?: number;
+    name?: string;
+    soft?: number;
+  });
+}
+
+export declare class Volume {
+  constructor(props: {
+    nodeFilters?: string[];
+    volume?: string;
+  });
+}

package/src/generated/index.ts

@@ -0,0 +1,27 @@
+// Code generated by chant generate. DO NOT EDIT.
+import { createResource, createProperty } from "./runtime";
+
+export const Cluster = createResource("K3d::Cluster", "k3d", {});
+
+export const EnvVar = createProperty("K3d::EnvVar", "k3d");
+export const File = createProperty("K3d::File", "k3d");
+export const HostAlias = createProperty("K3d::HostAlias", "k3d");
+export const K3dOptions = createProperty("K3d::K3dOptions", "k3d");
+export const K3sExtraArg = createProperty("K3d::K3sExtraArg", "k3d");
+export const K3sOptions = createProperty("K3d::K3sOptions", "k3d");
+export const KubeAPI = createProperty("K3d::KubeAPI", "k3d");
+export const KubeconfigOptions = createProperty("K3d::KubeconfigOptions", "k3d");
+export const LoadbalancerOptions = createProperty("K3d::LoadbalancerOptions", "k3d");
+export const Metadata = createProperty("K3d::Metadata", "k3d");
+export const NodeLabel = createProperty("K3d::NodeLabel", "k3d");
+export const Options = createProperty("K3d::Options", "k3d");
+export const Port = createProperty("K3d::Port", "k3d");
+export const Registries = createProperty("K3d::Registries", "k3d");
+export const RegistryCreate = createProperty("K3d::RegistryCreate", "k3d");
+export const RegistryProxy = createProperty("K3d::RegistryProxy", "k3d");
+export const RuntimeLabel = createProperty("K3d::RuntimeLabel", "k3d");
+export const RuntimeOptions = createProperty("K3d::RuntimeOptions", "k3d");
+export const Ulimit = createProperty("K3d::Ulimit", "k3d");
+export const Volume = createProperty("K3d::Volume", "k3d");
+
+// Re-exports for convenience

package/src/generated/lexicon-k3d.json

@@ -0,0 +1,184 @@
+{
+  "Cluster": {
+    "resourceType": "K3d::Cluster",
+    "kind": "resource",
+    "lexicon": "k3d",
+    "constraints": {
+      "apiVersion": {
+        "default": "k3d.io/v1alpha5",
+        "enum": [
+          "k3d.io/v1alpha5"
+        ]
+      },
+      "kind": {
+        "default": "Simple",
+        "enum": [
+          "Simple"
+        ]
+      },
+      "servers": {
+        "minimum": 1
+      },
+      "agents": {
+        "minimum": 0
+      },
+      "subnet": {
+        "default": "auto"
+      }
+    }
+  },
+  "EnvVar": {
+    "resourceType": "K3d::EnvVar",
+    "kind": "property",
+    "lexicon": "k3d"
+  },
+  "File": {
+    "resourceType": "K3d::File",
+    "kind": "property",
+    "lexicon": "k3d"
+  },
+  "HostAlias": {
+    "resourceType": "K3d::HostAlias",
+    "kind": "property",
+    "lexicon": "k3d"
+  },
+  "K3dOptions": {
+    "resourceType": "K3d::K3dOptions",
+    "kind": "property",
+    "lexicon": "k3d",
+    "constraints": {
+      "wait": {
+        "default": true
+      },
+      "disableLoadbalancer": {
+        "default": false
+      },
+      "disableImageVolume": {
+        "default": false
+      },
+      "disableRollback": {
+        "default": false
+      }
+    }
+  },
+  "K3sExtraArg": {
+    "resourceType": "K3d::K3sExtraArg",
+    "kind": "property",
+    "lexicon": "k3d"
+  },
+  "K3sOptions": {
+    "resourceType": "K3d::K3sOptions",
+    "kind": "property",
+    "lexicon": "k3d"
+  },
+  "KubeAPI": {
+    "resourceType": "K3d::KubeAPI",
+    "kind": "property",
+    "lexicon": "k3d",
+    "constraints": {
+      "host": {
+        "format": "hostname"
+      },
+      "hostIP": {
+        "format": "ipv4"
+      }
+    }
+  },
+  "KubeconfigOptions": {
+    "resourceType": "K3d::KubeconfigOptions",
+    "kind": "property",
+    "lexicon": "k3d",
+    "constraints": {
+      "updateDefaultKubeconfig": {
+        "default": true
+      },
+      "switchCurrentContext": {
+        "default": true
+      }
+    }
+  },
+  "LoadbalancerOptions": {
+    "resourceType": "K3d::LoadbalancerOptions",
+    "kind": "property",
+    "lexicon": "k3d"
+  },
+  "Metadata": {
+    "resourceType": "K3d::Metadata",
+    "kind": "property",
+    "lexicon": "k3d",
+    "constraints": {
+      "name": {
+        "format": "hostname"
+      }
+    }
+  },
+  "NodeLabel": {
+    "resourceType": "K3d::NodeLabel",
+    "kind": "property",
+    "lexicon": "k3d"
+  },
+  "Options": {
+    "resourceType": "K3d::Options",
+    "kind": "property",
+    "lexicon": "k3d"
+  },
+  "Port": {
+    "resourceType": "K3d::Port",
+    "kind": "property",
+    "lexicon": "k3d"
+  },
+  "Registries": {
+    "resourceType": "K3d::Registries",
+    "kind": "property",
+    "lexicon": "k3d"
+  },
+  "RegistryCreate": {
+    "resourceType": "K3d::RegistryCreate",
+    "kind": "property",
+    "lexicon": "k3d",
+    "constraints": {
+      "host": {
+        "default": "0.0.0.0"
+      },
+      "hostPort": {
+        "default": "random"
+      },
+      "image": {
+        "default": "docker.io/library/registry:2"
+      },
+      "enforcePortMatch": {
+        "default": false
+      }
+    }
+  },
+  "RegistryProxy": {
+    "resourceType": "K3d::RegistryProxy",
+    "kind": "property",
+    "lexicon": "k3d"
+  },
+  "RuntimeLabel": {
+    "resourceType": "K3d::RuntimeLabel",
+    "kind": "property",
+    "lexicon": "k3d"
+  },
+  "RuntimeOptions": {
+    "resourceType": "K3d::RuntimeOptions",
+    "kind": "property",
+    "lexicon": "k3d",
+    "constraints": {
+      "hostPidMode": {
+        "default": false
+      }
+    }
+  },
+  "Ulimit": {
+    "resourceType": "K3d::Ulimit",
+    "kind": "property",
+    "lexicon": "k3d"
+  },
+  "Volume": {
+    "resourceType": "K3d::Volume",
+    "kind": "property",
+    "lexicon": "k3d"
+  }
+}

package/src/generated/runtime.ts

@@ -0,0 +1,4 @@
+/**
+ * Runtime factory constructors — re-exported from core.
+ */
+export { createResource, createProperty } from "@intentius/chant/runtime";

package/src/index.ts

@@ -0,0 +1,8 @@
+// Plugin
+export { k3dPlugin } from "./plugin";
+
+// Serializer
+export { k3dSerializer } from "./serializer";
+
+// Generated resources — export everything from generated index
+export * from "./generated/index";

package/src/lint/audit-catalog.ts

@@ -0,0 +1,26 @@
+/**
+ * The k3d lexicon's chant audit catalog — metadata for its post-synth
+ * checks, contributed via k3dPlugin.auditCatalog() (#687, #1346). Every
+ * post-synth check has an entry, or the check contributes nothing to
+ * `chant audit`, silently.
+ */
+import { auditRule, type RuleMeta } from "@intentius/chant/audit/catalog";
+
+export const k3dAuditCatalog: Record<string, RuleMeta> = {
+  K3D101: auditRule(
+    "K3D101",
+    "merge-worthy",
+    "guidance",
+    "nodeFilter matches no node",
+    'Use a real k3d selector: "all", "loadbalancer", or "server"/"agent" with ":<index>" or ":*".',
+    { category: "correctness" },
+  ),
+  K3D102: auditRule(
+    "K3D102",
+    "merge-worthy",
+    "guidance",
+    "Registry proxy password in the emitted cluster config",
+    "Remove the credential from the declaration; connect the registry via registries.use or configure the proxy outside chant.",
+    { category: "security" },
+  ),
+};

package/src/lint/post-synth/index.ts

@@ -0,0 +1,9 @@
+// Code generated by chant generate. DO NOT EDIT.
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import { k3d101 } from "./k3d101";
+import { k3d102 } from "./k3d102";
+
+export const postSynthChecks: PostSynthCheck[] = [
+  k3d101,
+  k3d102,
+];

package/src/lint/post-synth/k3d101.ts

@@ -0,0 +1,87 @@
+/**
+ * K3D101: malformed nodeFilters.
+ *
+ * `nodeFilters` are k3d's own selector syntax and the schema types them as
+ * bare strings, so a typo validates, applies to nothing, and reports
+ * nothing — the port mapping or volume silently lands nowhere. This is the
+ * silent-at-create failure worth an error.
+ *
+ * Valid forms (k3d v5): `all`, `loadbalancer`, or `server`/`agent` with an
+ * optional `:<index>` / `:*`, and for port mappings an optional trailing
+ * `:direct` / `:proxy`.
+ */
+
+import { load, loadAll } from "js-yaml";
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import type { SerializerResult } from "@intentius/chant/serializer";
+
+const VALID_FILTER = /^(all|loadbalancer|server|agent)(:(\d+|\*))?(:(direct|proxy))?$/;
+
+export function k3dDocuments(ctx: PostSynthContext): Array<{ source: string; doc: unknown }> {
+  const docs: Array<{ source: string; doc: unknown }> = [];
+  for (const [outputName, output] of ctx.outputs) {
+    const texts: Array<[string, string]> =
+      typeof output === "string"
+        ? [[outputName, output]]
+        : [
+            [outputName, (output as SerializerResult).primary],
+            ...Object.entries((output as SerializerResult).files ?? {}),
+          ];
+    for (const [source, text] of texts) {
+      if (!text || !text.includes("k3d.io/")) continue;
+      try {
+        for (const doc of loadAll(text)) docs.push({ source, doc });
+      } catch {
+        try {
+          docs.push({ source, doc: load(text) });
+        } catch {
+          // not YAML — someone else's output
+        }
+      }
+    }
+  }
+  return docs;
+}
+
+function collectFilters(value: unknown, path: string, out: Array<{ path: string; filter: string }>): void {
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => collectFilters(v, `${path}[${i}]`, out));
+    return;
+  }
+  if (typeof value !== "object" || value === null) return;
+  for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+    if (key === "nodeFilters" && Array.isArray(v)) {
+      v.forEach((f, i) => {
+        if (typeof f === "string") out.push({ path: `${path}.nodeFilters[${i}]`, filter: f });
+      });
+      continue;
+    }
+    collectFilters(v, path ? `${path}.${key}` : key, out);
+  }
+}
+
+export const k3d101: PostSynthCheck = {
+  id: "K3D101",
+  description: "A nodeFilter that matches no node applies to nothing, silently",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const { source, doc } of k3dDocuments(ctx)) {
+      const filters: Array<{ path: string; filter: string }> = [];
+      collectFilters(doc, "", filters);
+      for (const { path, filter } of filters) {
+        if (VALID_FILTER.test(filter)) continue;
+        diagnostics.push({
+          checkId: "K3D101",
+          severity: "error",
+          message:
+            `${source}: nodeFilter "${filter}" at ${path} is not a k3d selector — valid forms are ` +
+            `"all", "loadbalancer", "server"/"agent" with optional ":<index>" or ":*", plus ` +
+            `":direct"/":proxy" on port mappings. k3d applies an unmatched filter to nothing and says nothing.`,
+          lexicon: "k3d",
+        });
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/k3d102.ts

@@ -0,0 +1,40 @@
+/**
+ * K3D102: registry proxy credential in the emitted config.
+ *
+ * The other half of K3D001: the lint rule sees literals in source, this
+ * sees what actually landed in the artifact — a value that arrived through
+ * a variable, a helper, or anything else the AST rule cannot follow. The
+ * emitted config is the file people commit, attach to issues and copy to
+ * other machines, which is exactly where a registry credential must not be.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { k3dDocuments } from "./k3d101";
+
+export const k3d102: PostSynthCheck = {
+  id: "K3D102",
+  description: "The emitted cluster config carries a registry proxy password",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const { source, doc } of k3dDocuments(ctx)) {
+      if (typeof doc !== "object" || doc === null) continue;
+      const registries = (doc as Record<string, unknown>).registries as Record<string, unknown> | undefined;
+      const create = registries?.create as Record<string, unknown> | undefined;
+      const proxy = create?.proxy as Record<string, unknown> | undefined;
+      const password = proxy?.password;
+      if (typeof password === "string" && password.length > 0) {
+        diagnostics.push({
+          checkId: "K3D102",
+          severity: "error",
+          message:
+            `${source}: registries.create.proxy.password is present in the emitted config — ` +
+            `this file is the walk-away artifact and a credential inside it is a credential in source. ` +
+            `Connect a pre-existing registry via registries.use, or supply the proxy credential outside chant.`,
+          lexicon: "k3d",
+        });
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/post-synth.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { k3d101 } from "./k3d101";
+import { k3d102 } from "./k3d102";
+
+function ctx(yaml: string): PostSynthContext {
+  const outputs = new Map<string, string>([["k3d", yaml]]);
+  return {
+    outputs,
+    entities: new Map(),
+    buildResult: { outputs, entities: new Map(), warnings: [] },
+  } as unknown as PostSynthContext;
+}
+
+const HEADER = "apiVersion: k3d.io/v1alpha5\nkind: Simple\n";
+
+describe("K3D101: malformed nodeFilters", () => {
+  test("accepts every documented form", () => {
+    const yaml =
+      HEADER +
+      `ports:
+  - port: "8080:80"
+    nodeFilters: ["loadbalancer", "server:0", "server:*", "agent:1", "all", "loadbalancer:proxy", "server:0:direct"]
+`;
+    expect(k3d101.check(ctx(yaml))).toHaveLength(0);
+  });
+
+  test("flags a typo'd role", () => {
+    const yaml = HEADER + `volumes:\n  - volume: /tmp/x:/x\n    nodeFilters: ["sevrer:0"]\n`;
+    const diags = k3d101.check(ctx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("K3D101");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("sevrer:0");
+  });
+
+  test("flags a malformed index", () => {
+    const diags = k3d101.check(ctx(HEADER + `ports:\n  - port: "1:1"\n    nodeFilters: ["server:one"]\n`));
+    expect(diags).toHaveLength(1);
+  });
+
+  test("ignores output that is not a k3d config", () => {
+    const outputs = new Map<string, string>([["k8s", "kind: Deployment\nmetadata:\n  name: x\n"]]);
+    const context = {
+      outputs,
+      entities: new Map(),
+      buildResult: { outputs, entities: new Map(), warnings: [] },
+    } as unknown as PostSynthContext;
+    expect(k3d101.check(context)).toHaveLength(0);
+  });
+});
+
+describe("K3D102: proxy password in the emitted config", () => {
+  test("flags a password that landed in the artifact", () => {
+    const yaml =
+      HEADER +
+      `registries:
+  create:
+    name: myregistry
+    proxy:
+      remoteURL: https://registry-1.docker.io
+      password: hunter2
+`;
+    const diags = k3d102.check(ctx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("K3D102");
+    expect(diags[0].severity).toBe("error");
+  });
+
+  test("silent when there is no proxy or no password", () => {
+    expect(k3d102.check(ctx(HEADER + "servers: 1\n"))).toHaveLength(0);
+    const noPass =
+      HEADER + `registries:\n  create:\n    name: r\n    proxy:\n      remoteURL: https://x\n`;
+    expect(k3d102.check(ctx(noPass))).toHaveLength(0);
+  });
+});

package/src/lint/rules/index.ts

@@ -0,0 +1,7 @@
+import type { LintRule } from "@intentius/chant/lint/rule";
+import { registryProxyPasswordRule } from "./registry-proxy-password";
+
+export { registryProxyPasswordRule } from "./registry-proxy-password";
+
+/** All lint rules provided by this lexicon (imported by plugin.ts's lintRules()). */
+export const rules: LintRule[] = [registryProxyPasswordRule];