@intentius/chant-lexicon-fly 0.16.0

package/src/generated/lexicon-fly.json

@@ -0,0 +1,285 @@
+{
+  "App": {
+    "resourceType": "Fly::Machines::App",
+    "kind": "resource",
+    "lexicon": "fly"
+  },
+  "Certificate": {
+    "resourceType": "Fly::Machines::Certificate",
+    "kind": "resource",
+    "lexicon": "fly"
+  },
+  "ContainerConfig": {
+    "resourceType": "Fly::Machines::ContainerConfig",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "ContainerDependency": {
+    "resourceType": "Fly::Machines::ContainerDependency",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "ContainerHealthcheck": {
+    "resourceType": "Fly::Machines::ContainerHealthcheck",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "DNSConfig": {
+    "resourceType": "Fly::Machines::DNSConfig",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "DnsForwardRule": {
+    "resourceType": "Fly::Machines::DnsForwardRule",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "DnsOption": {
+    "resourceType": "Fly::Machines::DnsOption",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "EnvFrom": {
+    "resourceType": "Fly::Machines::EnvFrom",
+    "kind": "property",
+    "lexicon": "fly",
+    "constraints": {
+      "field_ref": {
+        "enum": [
+          "id",
+          "version",
+          "app_name",
+          "private_ip",
+          "region",
+          "image"
+        ]
+      }
+    }
+  },
+  "ExecHealthcheck": {
+    "resourceType": "Fly::Machines::ExecHealthcheck",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "File": {
+    "resourceType": "Fly::Machines::File",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "HTTPHealthcheck": {
+    "resourceType": "Fly::Machines::HTTPHealthcheck",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "HTTPOptions": {
+    "resourceType": "Fly::Machines::HTTPOptions",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "HTTPResponseOptions": {
+    "resourceType": "Fly::Machines::HTTPResponseOptions",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "IPAddress": {
+    "resourceType": "Fly::Machines::IPAddress",
+    "kind": "resource",
+    "lexicon": "fly"
+  },
+  "Machine": {
+    "resourceType": "Fly::Machines::Machine",
+    "kind": "resource",
+    "lexicon": "fly"
+  },
+  "MachineCacheDrive": {
+    "resourceType": "Fly::Machines::MachineCacheDrive",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "MachineCheck": {
+    "resourceType": "Fly::Machines::MachineCheck",
+    "kind": "property",
+    "lexicon": "fly",
+    "constraints": {
+      "kind": {
+        "enum": [
+          "informational",
+          "readiness"
+        ]
+      }
+    }
+  },
+  "MachineConfig": {
+    "resourceType": "Fly::Machines::MachineConfig",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "MachineGuest": {
+    "resourceType": "Fly::Machines::MachineGuest",
+    "kind": "property",
+    "lexicon": "fly",
+    "constraints": {
+      "persist_rootfs": {
+        "enum": [
+          "never",
+          "always",
+          "restart"
+        ]
+      }
+    }
+  },
+  "MachineHTTPHeader": {
+    "resourceType": "Fly::Machines::MachineHTTPHeader",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "MachineInit": {
+    "resourceType": "Fly::Machines::MachineInit",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "MachineMetrics": {
+    "resourceType": "Fly::Machines::MachineMetrics",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "MachineMount": {
+    "resourceType": "Fly::Machines::MachineMount",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "MachinePort": {
+    "resourceType": "Fly::Machines::MachinePort",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "MachineProcess": {
+    "resourceType": "Fly::Machines::MachineProcess",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "MachineRestart": {
+    "resourceType": "Fly::Machines::MachineRestart",
+    "kind": "property",
+    "lexicon": "fly",
+    "constraints": {
+      "policy": {
+        "enum": [
+          "no",
+          "always",
+          "on-failure",
+          "spot-price"
+        ]
+      }
+    }
+  },
+  "MachineRootfs": {
+    "resourceType": "Fly::Machines::MachineRootfs",
+    "kind": "property",
+    "lexicon": "fly",
+    "constraints": {
+      "persist": {
+        "enum": [
+          "never",
+          "always",
+          "restart"
+        ]
+      }
+    }
+  },
+  "MachineSecret": {
+    "resourceType": "Fly::Machines::MachineSecret",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "MachineService": {
+    "resourceType": "Fly::Machines::MachineService",
+    "kind": "property",
+    "lexicon": "fly",
+    "constraints": {
+      "autostop": {
+        "enum": [
+          "off",
+          "stop",
+          "suspend"
+        ]
+      }
+    }
+  },
+  "MachineServiceCheck": {
+    "resourceType": "Fly::Machines::MachineServiceCheck",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "MachineServiceConcurrency": {
+    "resourceType": "Fly::Machines::MachineServiceConcurrency",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "MachineSpot": {
+    "resourceType": "Fly::Machines::MachineSpot",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "ProxyProtoOptions": {
+    "resourceType": "Fly::Machines::ProxyProtoOptions",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "ReplayCache": {
+    "resourceType": "Fly::Machines::ReplayCache",
+    "kind": "property",
+    "lexicon": "fly",
+    "constraints": {
+      "type": {
+        "enum": [
+          "cookie",
+          "header"
+        ]
+      }
+    }
+  },
+  "Secret": {
+    "resourceType": "Fly::Machines::Secret",
+    "kind": "resource",
+    "lexicon": "fly"
+  },
+  "Static": {
+    "resourceType": "Fly::Machines::Static",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "StopConfig": {
+    "resourceType": "Fly::Machines::StopConfig",
+    "kind": "property",
+    "lexicon": "fly",
+    "constraints": {
+      "signal": {
+        "enum": [
+          "SIGHUP",
+          "SIGINT",
+          "SIGQUIT",
+          "SIGKILL",
+          "SIGUSR1",
+          "SIGUSR2",
+          "SIGTERM"
+        ]
+      }
+    }
+  },
+  "TCPHealthcheck": {
+    "resourceType": "Fly::Machines::TCPHealthcheck",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "TLSOptions": {
+    "resourceType": "Fly::Machines::TLSOptions",
+    "kind": "property",
+    "lexicon": "fly"
+  },
+  "Volume": {
+    "resourceType": "Fly::Machines::Volume",
+    "kind": "resource",
+    "lexicon": "fly"
+  }
+}

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/import/generator.test.ts

@@ -0,0 +1,123 @@
+import { describe, test, expect } from "vitest";
+import { FlyGenerator } from "./generator";
+
+const generator = new FlyGenerator();
+
+function makeIR(resources: any[]) {
+  return { resources, parameters: [] };
+}
+
+function content(ir: ReturnType<typeof makeIR>): string {
+  return generator.generate(ir)[0].content;
+}
+
+describe("FlyGenerator", () => {
+  test("generates chant TypeScript from IR", () => {
+    const ir = makeIR([
+      { logicalId: "my-app", type: "Fly::Machines::App", properties: { name: "my-app", org_slug: "personal" } },
+    ]);
+    const result = content(ir);
+    expect(result).toContain('import { App } from "@intentius/chant-lexicon-fly";');
+    expect(result).toContain("export const myApp = new App({");
+    expect(result).toContain('name: "my-app"');
+  });
+
+  test("import source is @intentius/chant-lexicon-fly", () => {
+    const ir = makeIR([
+      { logicalId: "web", type: "Fly::Machines::Machine", properties: { name: "web" } },
+    ]);
+    expect(content(ir)).toContain('from "@intentius/chant-lexicon-fly"');
+  });
+
+  test("App and Machine produce two exports", () => {
+    const ir = makeIR([
+      { logicalId: "my-app", type: "Fly::Machines::App", properties: { name: "my-app" } },
+      { logicalId: "web", type: "Fly::Machines::Machine", properties: { name: "web", region: "iad" } },
+    ]);
+    const result = content(ir);
+    expect(result).toContain("export const myApp = new App(");
+    expect(result).toContain("export const web = new Machine(");
+  });
+
+  test("camelCase variable names from kebab-case logical names", () => {
+    const ir = makeIR([
+      { logicalId: "my-web-app", type: "Fly::Machines::App", properties: { name: "my-web-app" } },
+    ]);
+    expect(content(ir)).toContain("export const myWebApp");
+  });
+
+  test("config is wrapped in new MachineConfig(...) so it typechecks", () => {
+    const ir = makeIR([
+      {
+        logicalId: "web",
+        type: "Fly::Machines::Machine",
+        properties: { name: "web", config: { image: "nginx:1" } },
+      },
+    ]);
+    const result = content(ir);
+    expect(result).toContain("config: new MachineConfig({");
+    expect(result).toContain("MachineConfig");
+    // MachineConfig is imported alongside the resource classes.
+    expect(result).toMatch(/import \{[^}]*MachineConfig[^}]*\}/);
+  });
+
+  test("nested declarables (guest, services, ports) get their own constructors", () => {
+    const ir = makeIR([
+      {
+        logicalId: "web",
+        type: "Fly::Machines::Machine",
+        properties: {
+          name: "web",
+          config: {
+            image: "nginx:1",
+            guest: { cpu_kind: "shared", cpus: 1 },
+            services: [
+              { protocol: "tcp", internal_port: 8080, ports: [{ port: 443, handlers: ["tls"] }] },
+            ],
+          },
+        },
+      },
+    ]);
+    const result = content(ir);
+    expect(result).toContain("guest: new MachineGuest({");
+    expect(result).toContain("new MachineService({");
+    expect(result).toContain("new MachinePort({");
+    // Every wrapped class appears in the import.
+    const importLine = result.split("\n").find((l) => l.startsWith("import"))!;
+    for (const cls of ["App", "Machine", "MachineConfig", "MachineGuest", "MachineService", "MachinePort"]) {
+      // App is not used here; only imports for classes actually emitted.
+      if (cls === "App") continue;
+      expect(importLine).toContain(cls);
+    }
+  });
+
+  test("scalar maps (metadata, env) stay plain object literals", () => {
+    const ir = makeIR([
+      {
+        logicalId: "web",
+        type: "Fly::Machines::Machine",
+        properties: { name: "web", config: { metadata: { "managed-by": "chant" }, env: { PORT: "8080" } } },
+      },
+    ]);
+    const result = content(ir);
+    expect(result).toContain("metadata: {");
+    expect(result).toContain('"managed-by": "chant"');
+    expect(result).toContain("env: {");
+    expect(result).toContain("PORT: ");
+  });
+
+  test("imports are sorted alphabetically", () => {
+    const ir = makeIR([
+      { logicalId: "web", type: "Fly::Machines::Machine", properties: { name: "web", config: { image: "x" } } },
+      { logicalId: "my-app", type: "Fly::Machines::App", properties: { name: "my-app" } },
+    ]);
+    const importLine = content(ir).split("\n").find((l) => l.startsWith("import"))!;
+    expect(importLine.indexOf("App")).toBeLessThan(importLine.indexOf("Machine"));
+  });
+
+  test("empty IR still produces a single file", () => {
+    const files = generator.generate(makeIR([]));
+    expect(files).toHaveLength(1);
+    expect(typeof files[0].content).toBe("string");
+  });
+});

package/src/import/generator.ts

@@ -0,0 +1,242 @@
+/**
+ * flaps TypeScript generator.
+ *
+ * Converts import IR from {@link FlyParser} into typed chant TypeScript:
+ * `import { App, Machine, ... } from "@intentius/chant-lexicon-fly";` followed by
+ * `export const <var> = new <Class>({ ... });`.
+ *
+ * fly's nested config types (`MachineConfig`, `MachineGuest`, `MachineService`,
+ * ...) are property declarables — classes with an empty instance shape — so a
+ * bare object literal would trip TypeScript's excess-property check against the
+ * declared parameter type. Wherever a field's declared type is one of those
+ * classes, the value is wrapped in `new <Class>({ ... })` (recursively), which is
+ * the same authoring surface `chant init` scaffolds and the serializer walks back
+ * to the identical flaps body.
+ */
+
+import type { TypeScriptGenerator, GeneratedFile } from "@intentius/chant/import/generator";
+import type { TemplateIR } from "@intentius/chant/import/parser";
+
+/**
+ * How a nested field is wrapped: `single` → `new Cls({...})`, `array` → each
+ * element wrapped, `record` → each value wrapped.
+ */
+type Nested = { kind: "single" | "array" | "record"; cls: string };
+
+/**
+ * `<OwnerClass> → { <field>: { kind, cls } }` for every field whose declared
+ * type is a fly property declarable (a class, an array of one, or a
+ * `Record<string, one>`). Mirrors the constructor parameter types in the
+ * generated resource classes (src/generated). Regenerate this map if the pinned
+ * flaps spec changes the config surface.
+ */
+const NESTED_DECLARABLES: Record<string, Record<string, Nested>> = {
+  Machine: {
+    config: { kind: "single", cls: "MachineConfig" },
+  },
+  Volume: {
+    compute: { kind: "single", cls: "MachineGuest" },
+  },
+  ContainerConfig: {
+    depends_on: { kind: "array", cls: "ContainerDependency" },
+    env_from: { kind: "array", cls: "EnvFrom" },
+    files: { kind: "array", cls: "File" },
+    healthchecks: { kind: "array", cls: "ContainerHealthcheck" },
+    restart: { kind: "single", cls: "MachineRestart" },
+    secrets: { kind: "array", cls: "MachineSecret" },
+    stop: { kind: "single", cls: "StopConfig" },
+  },
+  ContainerHealthcheck: {
+    exec: { kind: "single", cls: "ExecHealthcheck" },
+    http: { kind: "single", cls: "HTTPHealthcheck" },
+    tcp: { kind: "single", cls: "TCPHealthcheck" },
+  },
+  DNSConfig: {
+    dns_forward_rules: { kind: "array", cls: "DnsForwardRule" },
+    options: { kind: "array", cls: "DnsOption" },
+  },
+  HTTPHealthcheck: {
+    headers: { kind: "array", cls: "MachineHTTPHeader" },
+  },
+  HTTPOptions: {
+    replay_cache: { kind: "array", cls: "ReplayCache" },
+    response: { kind: "single", cls: "HTTPResponseOptions" },
+  },
+  MachineCheck: {
+    headers: { kind: "array", cls: "MachineHTTPHeader" },
+  },
+  MachineConfig: {
+    cache_drive: { kind: "single", cls: "MachineCacheDrive" },
+    checks: { kind: "record", cls: "MachineCheck" },
+    containers: { kind: "array", cls: "ContainerConfig" },
+    dns: { kind: "single", cls: "DNSConfig" },
+    files: { kind: "array", cls: "File" },
+    guest: { kind: "single", cls: "MachineGuest" },
+    init: { kind: "single", cls: "MachineInit" },
+    metrics: { kind: "single", cls: "MachineMetrics" },
+    mounts: { kind: "array", cls: "MachineMount" },
+    processes: { kind: "array", cls: "MachineProcess" },
+    restart: { kind: "single", cls: "MachineRestart" },
+    rootfs: { kind: "single", cls: "MachineRootfs" },
+    services: { kind: "array", cls: "MachineService" },
+    spot: { kind: "single", cls: "MachineSpot" },
+    statics: { kind: "array", cls: "Static" },
+    stop_config: { kind: "single", cls: "StopConfig" },
+  },
+  MachinePort: {
+    http_options: { kind: "single", cls: "HTTPOptions" },
+    proxy_proto_options: { kind: "single", cls: "ProxyProtoOptions" },
+    tls_options: { kind: "single", cls: "TLSOptions" },
+  },
+  MachineProcess: {
+    env_from: { kind: "array", cls: "EnvFrom" },
+    secrets: { kind: "array", cls: "MachineSecret" },
+  },
+  MachineService: {
+    checks: { kind: "array", cls: "MachineServiceCheck" },
+    concurrency: { kind: "single", cls: "MachineServiceConcurrency" },
+    ports: { kind: "array", cls: "MachinePort" },
+  },
+  MachineServiceCheck: {
+    headers: { kind: "array", cls: "MachineHTTPHeader" },
+  },
+};
+
+export class FlyGenerator implements TypeScriptGenerator {
+  generate(ir: TemplateIR): GeneratedFile[] {
+    const imports = new Set<string>();
+    const bodyLines: string[] = [];
+
+    for (const resource of ir.resources) {
+      const parts = resource.type.split("::");
+      const className = parts.length >= 3 ? parts[2] : resource.type;
+      imports.add(className);
+      const varName = camelCase(resource.logicalId);
+      const props = formatProps(resource.properties, 0, className, imports);
+      bodyLines.push(`export const ${varName} = new ${className}(${props});`);
+      bodyLines.push("");
+    }
+
+    const lines: string[] = [];
+    if (imports.size > 0) {
+      lines.push(
+        `import { ${[...imports].sort().join(", ")} } from "@intentius/chant-lexicon-fly";`,
+      );
+      lines.push("");
+    }
+    lines.push(...bodyLines);
+
+    return [{ path: "main.ts", content: lines.join("\n") + "\n" }];
+  }
+}
+
+function camelCase(str: string): string {
+  return str
+    .replace(/[-_.](.)/g, (_, c) => c.toUpperCase())
+    .replace(/^(.)/, (_, c) => c.toLowerCase());
+}
+
+/**
+ * Format an object literal for the props of `ownerClass`. Fields whose declared
+ * type is a nested declarable are wrapped in their constructor; everything else
+ * is emitted as a plain literal.
+ */
+function formatProps(
+  props: Record<string, unknown>,
+  indent: number,
+  ownerClass: string,
+  imports: Set<string>,
+): string {
+  const entries = Object.entries(props);
+  if (entries.length === 0) return "{}";
+
+  const pad = "  ".repeat(indent + 1);
+  const closePad = "  ".repeat(indent);
+  const nested = NESTED_DECLARABLES[ownerClass];
+
+  const lines = entries.map(([key, value]) => {
+    const spec = nested?.[key];
+    const rendered =
+      spec !== undefined
+        ? formatNested(value, indent + 1, spec, imports)
+        : formatValue(value, indent + 1);
+    return `${pad}${key}: ${rendered},`;
+  });
+
+  return `{\n${lines.join("\n")}\n${closePad}}`;
+}
+
+/** Wrap a nested-declarable value in its constructor per the field's kind. */
+function formatNested(
+  value: unknown,
+  indent: number,
+  spec: Nested,
+  imports: Set<string>,
+): string {
+  const construct = (obj: unknown, at: number): string => {
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+      return formatValue(obj, at);
+    }
+    imports.add(spec.cls);
+    return `new ${spec.cls}(${formatProps(obj as Record<string, unknown>, at, spec.cls, imports)})`;
+  };
+
+  if (spec.kind === "single") {
+    return construct(value, indent);
+  }
+
+  if (spec.kind === "array") {
+    if (!Array.isArray(value) || value.length === 0) return "[]";
+    const pad = "  ".repeat(indent + 1);
+    const closePad = "  ".repeat(indent);
+    const items = value.map((v) => `${pad}${construct(v, indent + 1)},`);
+    return `[\n${items.join("\n")}\n${closePad}]`;
+  }
+
+  // record: a plain object whose values are wrapped in the constructor.
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return formatValue(value, indent);
+  }
+  const record = value as Record<string, unknown>;
+  const recKeys = Object.entries(record);
+  if (recKeys.length === 0) return "{}";
+  const pad = "  ".repeat(indent + 1);
+  const closePad = "  ".repeat(indent);
+  const items = recKeys.map(([k, v]) => `${pad}${JSON.stringify(k)}: ${construct(v, indent + 1)},`);
+  return `{\n${items.join("\n")}\n${closePad}}`;
+}
+
+function formatValue(value: unknown, indent: number): string {
+  if (value === null || value === undefined) return "undefined";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    const pad = "  ".repeat(indent + 1);
+    const closePad = "  ".repeat(indent);
+    const items = value.map((v) => `${pad}${formatValue(v, indent + 1)},`);
+    return `[\n${items.join("\n")}\n${closePad}]`;
+  }
+
+  if (typeof value === "object") {
+    return formatPlainObject(value as Record<string, unknown>, indent);
+  }
+
+  return String(value);
+}
+
+/** A plain object literal (no constructor wrapping) — for scalar-valued maps like env/metadata. */
+function formatPlainObject(obj: Record<string, unknown>, indent: number): string {
+  const entries = Object.entries(obj);
+  if (entries.length === 0) return "{}";
+  const pad = "  ".repeat(indent + 1);
+  const closePad = "  ".repeat(indent);
+  const lines = entries.map(([key, value]) => `${pad}${objectKey(key)}: ${formatValue(value, indent + 1)},`);
+  return `{\n${lines.join("\n")}\n${closePad}}`;
+}
+
+/** Emit a bare identifier key when it is a valid one, else a quoted key. */
+function objectKey(key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+}