@intentius/chant-lexicon-k3s 0.44.3

package/src/codegen/generate.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, test } from "vitest";
+import { extractFlagLiterals, extractFlagList, parseSpecFiles } from "./parse";
+
+const SERVER_GO = `package cmds
+
+import "github.com/urfave/cli/v2"
+
+var ServerFlags = []cli.Flag{
+	ConfigFlag,
+	DebugFlag,
+	&cli.IntFlag{
+		Name:        "https-listen-port",
+		Usage:       "(listener) HTTPS listen port",
+		Value:       6443,
+		Destination: &ServerConfig.HTTPSPort,
+	},
+	&cli.StringFlag{
+		Name:        "token",
+		Aliases:     []string{"t"},
+		Usage:       "(cluster) Shared secret used to join a server or agent to a cluster",
+		EnvVars:     []string{"K3S_TOKEN"},
+	},
+	&cli.StringFlag{
+		Name:  "token-file",
+		Usage: "(cluster) File containing the token",
+	},
+	&cli.StringSliceFlag{
+		Name:  "tls-san",
+		Usage: "(listener) Add additional hostnames or IPv4/IPv6 addresses as Subject Alternative Names on the server TLS cert",
+	},
+	&cli.BoolFlag{
+		Name:   "secret-thing",
+		Usage:  "internal",
+		Hidden: true,
+	},
+	&cli.StringFlag{
+		Name:  "old-thing",
+		Usage: "(deprecated) do not use",
+	},
+	UnknownSharedFlag,
+}
+`;
+
+const AGENT_GO = `package cmds
+
+import "github.com/urfave/cli/v2"
+
+var (
+	NodeNameFlag = &cli.StringFlag{
+		Name:        "node-name",
+		Usage:       "(agent/node) Node name",
+		EnvVars:     []string{"K3S_NODE_NAME"},
+	}
+)
+
+func NewAgentCommand() *cli.Command {
+	return &cli.Command{
+		Name: "agent",
+		Flags: []cli.Flag{
+			ConfigFlag,
+			NodeNameFlag,
+			&cli.StringFlag{
+				Name:  "server",
+				Usage: "(cluster) Server to connect to",
+			},
+		},
+	}
+}
+`;
+
+const CONFIG_GO = `package cmds
+
+var (
+	ConfigFlag = &cli.StringFlag{
+		Name:  "config",
+		Usage: "(config) Load configuration from FILE",
+		Value: "/etc/rancher/k3s/config.yaml",
+	}
+	DebugFlag = &cli.BoolFlag{
+		Name:  "debug",
+		Usage: "(logging) Turn on debug logs",
+	}
+)
+`;
+
+function envelope(): string {
+  return JSON.stringify({ "server.go": SERVER_GO, "agent.go": AGENT_GO, "config.go": CONFIG_GO });
+}
+
+describe("k3s flag parser", () => {
+  test("extracts named flag vars with type, usage and default", () => {
+    const { byVar } = extractFlagLiterals(CONFIG_GO);
+    const debug = byVar.get("DebugFlag");
+    expect(debug?.flagType).toBe("Bool");
+    expect(debug?.name).toBe("debug");
+    expect(debug?.usage).toContain("debug logs");
+  });
+
+  test("extracts a flag list mixing references and inline literals in order", () => {
+    const items = extractFlagList(SERVER_GO, "var ServerFlags = []cli.Flag{");
+    expect(items[0]).toBe("ConfigFlag");
+    expect(items[1]).toBe("DebugFlag");
+    expect(typeof items[2]).toBe("object");
+  });
+
+  test("parses the envelope into Server, Agent and the registries entities", () => {
+    const results = parseSpecFiles(envelope());
+    const names = results.map((r) => r.resource.typeName);
+    expect(names).toEqual([
+      "K3s::Server",
+      "K3s::Agent",
+      "K3s::Registries",
+      "K3s::Mirror",
+      "K3s::RegistryConfig",
+      "K3s::RegistryAuth",
+      "K3s::RegistryTLS",
+    ]);
+  });
+
+  test("drops secrets, hidden, deprecated and the config flag itself; keeps the rest", () => {
+    const server = parseSpecFiles(envelope())[0].resource;
+    const names = server.properties.map((p) => p.name);
+    expect(names).not.toContain("token");
+    expect(names).not.toContain("config");
+    expect(names).not.toContain("secret-thing");
+    expect(names).not.toContain("old-thing");
+    expect(names).toContain("token-file");
+    expect(names).toContain("debug");
+  });
+
+  test("maps flag types to TS types, slices accepting single-or-list", () => {
+    const server = parseSpecFiles(envelope())[0].resource;
+    const byName = new Map(server.properties.map((p) => [p.name, p]));
+    expect(byName.get("https-listen-port")?.tsType).toBe("number");
+    expect(byName.get("tls-san")?.tsType).toBe("string | string[]");
+    expect(byName.get("debug")?.tsType).toBe("boolean");
+  });
+
+  test("carries the default into the description", () => {
+    const server = parseSpecFiles(envelope())[0].resource;
+    const port = server.properties.find((p) => p.name === "https-listen-port");
+    expect(port?.description).toContain("(default: 6443)");
+  });
+
+  test("requires server on the agent, and only there", () => {
+    const results = parseSpecFiles(envelope());
+    const agent = results[1].resource;
+    expect(agent.properties.find((p) => p.name === "server")?.required).toBe(true);
+    const server = results[0].resource;
+    expect(server.properties.every((p) => !p.required)).toBe(true);
+  });
+
+  test("surfaces unresolved references as warnings instead of dropping them silently", () => {
+    const results = parseSpecFiles(envelope());
+    expect(results[0].warnings).toEqual(["ServerFlags: unresolved flag reference UnknownSharedFlag"]);
+  });
+});

package/src/codegen/generate.ts

@@ -0,0 +1,116 @@
+/**
+ * k3s generation pipeline — uses core generatePipeline with k3s-specific
+ * fetch, parse, naming, and generation callbacks.
+ */
+
+import {
+  generatePipeline,
+  writeGeneratedArtifacts,
+  type GenerateOptions,
+  type GenerateResult,
+  type GeneratePipelineConfig,
+} from "@intentius/chant/codegen/generate";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { fetchSchemas } from "../spec/fetch";
+import { parseSpecFiles, type K3sParseResult } from "./parse";
+import { NamingStrategy } from "./naming";
+import { generateLexiconJSON } from "./generate-lexicon";
+import { generateTypeScriptDeclarations } from "./generate-typescript";
+import {
+  generateRuntimeIndex as coreGenerateRuntimeIndex,
+  type RuntimeIndexEntry,
+  type RuntimeIndexPropertyEntry,
+} from "@intentius/chant/codegen/generate-runtime-index";
+
+export type { GenerateResult };
+
+/**
+ * Run the full k3s generation pipeline.
+ */
+export async function generate(opts: GenerateOptions = {}): Promise<GenerateResult> {
+  let pendingResults: K3sParseResult[] = [];
+
+  const config: GeneratePipelineConfig<K3sParseResult> = {
+    fetchSchemas: async (fetchOpts) => {
+      return fetchSchemas(fetchOpts.force);
+    },
+
+    parseSchema: (_typeName, data) => {
+      const results = parseSpecFiles(data);
+      if (results.length === 0) return null;
+      pendingResults = results.slice(1);
+      return results[0];
+    },
+
+    createNaming: (results) => new NamingStrategy(results),
+
+    augmentResults: (results, _opts, log) => {
+      if (pendingResults.length > 0) {
+        results.push(...pendingResults);
+        log(`Added ${pendingResults.length} additional entities from single spec`);
+        pendingResults = [];
+      }
+      for (const r of results) {
+        for (const w of r.warnings ?? []) log(`warning: ${w}`);
+      }
+      const props = results.map((r) => `${r.resource.typeName}(${r.resource.properties.length})`);
+      log(`Total: ${results.length} k3s entities — ${props.join(", ")}`);
+      return { results };
+    },
+
+    generateRegistry: (results, naming) => {
+      return generateLexiconJSON(results, naming as NamingStrategy);
+    },
+
+    generateTypes: (results, naming) => {
+      return generateTypeScriptDeclarations(results, naming as NamingStrategy);
+    },
+
+    generateRuntimeIndex: (results, naming) => {
+      return generateRuntimeIndex(results, naming as NamingStrategy);
+    },
+  };
+
+  return generatePipeline(config, opts);
+}
+
+/**
+ * Write generated artifacts to disk.
+ */
+export function writeGeneratedFiles(result: GenerateResult, pkgDir?: string): void {
+  const baseDir = pkgDir ?? dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+  writeGeneratedArtifacts({
+    baseDir,
+    files: {
+      "lexicon-k3s.json": result.lexiconJSON,
+      "index.d.ts": result.typesDTS,
+      "index.ts": result.indexTS,
+      "runtime.ts": `/**\n * Runtime factory constructors — re-exported from core.\n */\nexport { createResource, createProperty } from "@intentius/chant/runtime";\n`,
+    },
+  });
+}
+
+/**
+ * Generate the runtime index.ts with factory constructor exports.
+ */
+function generateRuntimeIndex(results: K3sParseResult[], naming: NamingStrategy): string {
+  const resourceEntries: RuntimeIndexEntry[] = [];
+  const propertyEntries: RuntimeIndexPropertyEntry[] = [];
+
+  for (const r of results) {
+    const typeName = r.resource.typeName;
+    const tsName = naming.resolve(typeName);
+    if (!tsName) continue;
+
+    if (r.isProperty) {
+      propertyEntries.push({ tsName, resourceType: typeName });
+    } else {
+      resourceEntries.push({ tsName, resourceType: typeName, attrs: {} });
+    }
+  }
+
+  return coreGenerateRuntimeIndex(resourceEntries, propertyEntries, {
+    lexiconName: "k3s",
+  });
+}

package/src/codegen/naming.ts

@@ -0,0 +1,42 @@
+/**
+ * k3s naming strategy — flat namespace, one short name per entity.
+ */
+
+import {
+  NamingStrategy as CoreNamingStrategy,
+  type NamingConfig,
+  type NamingInput,
+} from "@intentius/chant/codegen/naming";
+import { k3sShortName, k3sServiceName, type K3sParseResult } from "./parse";
+
+export { propertyTypeName, extractDefName } from "@intentius/chant/codegen/naming";
+
+const k3sNamingConfig: NamingConfig = {
+  priorityNames: {
+    "K3s::Server": "Server",
+    "K3s::Agent": "Agent",
+    "K3s::Registries": "Registries",
+    "K3s::Mirror": "Mirror",
+    "K3s::RegistryConfig": "RegistryConfig",
+    "K3s::RegistryAuth": "RegistryAuth",
+    "K3s::RegistryTLS": "RegistryTLS",
+  },
+  priorityAliases: {},
+  priorityPropertyAliases: {},
+  serviceAbbreviations: {},
+  shortName: k3sShortName,
+  serviceName: k3sServiceName,
+};
+
+/**
+ * k3s naming strategy.
+ */
+export class NamingStrategy extends CoreNamingStrategy {
+  constructor(results: K3sParseResult[]) {
+    const inputs: NamingInput[] = results.map((r) => ({
+      typeName: r.resource.typeName,
+      propertyTypes: r.propertyTypes,
+    }));
+    super(inputs, k3sNamingConfig);
+  }
+}

package/src/codegen/package.ts

@@ -0,0 +1,28 @@
+import { packagePipeline, collectSkills } from "@intentius/chant/codegen/package";
+import type { PackagePipelineConfig } from "@intentius/chant/codegen/package";
+import { k3sPlugin } from "../plugin";
+import { generate } from "./generate";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * Package the k3s lexicon for distribution.
+ */
+export async function packageLexicon(options?: { verbose?: boolean; force?: boolean }) {
+  const srcDir = dirname(fileURLToPath(import.meta.url));
+
+  const { spec, stats } = await packagePipeline({
+    generate: (opts) => generate({ verbose: opts?.verbose, force: opts?.force }),
+    buildManifest: () => ({
+      name: "k3s",
+      version: "0.0.1",
+      chantVersion: ">=0.1.0",
+      namespace: "K3s",
+    }),
+    srcDir,
+    collectSkills: () => collectSkills(k3sPlugin.skills?.() ?? []),
+  });
+
+  console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules`);
+  return { spec, stats };
+}