@octalmesh/seagull-core 0.0.2 → 0.1.1

package/src/config/schema.ts

@@ -25,16 +25,23 @@ export const varsTreeSchema: z.ZodType<VarsTree> = z.lazy(() =>
   ),
 );
 
-export const githubSchema = z.object({
-  owner: z.string().min(1),
-  repo: z.string().min(1),
-});
+export const specFormatSchema = z.enum(["json", "yaml"]);
+export type SpecFormat = z.infer<typeof specFormatSchema>;
+
+export const specFormatListSchema = z
+  .union([specFormatSchema, z.array(specFormatSchema).min(1)])
+  .default("json")
+  .transform((value) => (Array.isArray(value) ? value : [value]))
+  .refine((formats) => new Set(formats).size === formats.length, {
+    message: "paths.specFormat entries must be unique",
+  });
 
 export const pathsSchema = z.object({
   dist: z.string().min(1).default("dist"),
   specs: z.string().min(1).optional(),
   docs: z.string().min(1).optional(),
   sdk: z.string().min(1).optional(),
+  specFormat: specFormatListSchema,
 });
 
 export const docsSchema = z.object({
@@ -73,8 +80,8 @@ export const mavenCoordsSchema = z.object({
 /**
  * Publishing conventions - git branch/tag naming, and where registry-backed
  * artifacts (npm, Maven) get pushed. Every field is a template supporting the
- * usual `{...}` placeholders (`{service}`, `{id}`, `{github.*}`, `{vars.*}`,
- * and for `tag` only, also `{version}`).
+ * usual `{...}` placeholders (`{service}`, `{id}`, `{vars.*}`, and for `tag`
+ * only, also `{version}`).
  *
  * Required at the root level - seagull has no built-in opinion on branch/tag
  * naming or which registry to use, so this has to come from the config, not
@@ -98,7 +105,7 @@ export const publishingSchema = z.object({
   /**
    * Template for the `repository.url` field written into generated
    * `package.json` (and shown in default README templates), e.g.
-   * `"https://github.com/{github.owner}/{github.repo}"`.
+   * `"https://github.com/{vars.repository.owner}/{vars.repository.repo}"`.
    */
   repositoryUrl: z.string().min(1),
   npm: z.object({
@@ -246,13 +253,12 @@ export const contractSchema = z.object({
 
 export const rootConfigSchema = z.object({
   /**
-   * The config schema version this file targets. Currently must be `1`
+   * The config schema version this file targets. Currently, must be `1`
    * (the only version that exists) - see {@link CONFIG_SCHEMA_VERSION}.
    */
   configVersion: z.literal(CONFIG_SCHEMA_VERSION),
-  github: githubSchema,
   vars: varsTreeSchema.default({}),
-  paths: pathsSchema.default({ dist: "dist" }),
+  paths: pathsSchema.default({ dist: "dist", specFormat: ["json"] }),
   docs: docsSchema,
   /**
    * Publishing conventions (branch/tag naming, registry URLs), applied to

package/src/config/spec-format.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+
+import { parseBundledSpec, specFilename } from "./spec-format";
+
+describe("specFilename", () => {
+  it("joins the contract name and format with a dot", () => {
+    expect(specFilename("auth", "json")).toBe("auth.json");
+    expect(specFilename("auth", "yaml")).toBe("auth.yaml");
+  });
+});
+
+describe("parseBundledSpec", () => {
+  it("parses 'json' as strict JSON", () => {
+    const result = parseBundledSpec(
+      '{"openapi":"3.1.0","info":{"version":"1.0.0"}}',
+      "json",
+    );
+
+    expect(result).toEqual({
+      openapi: "3.1.0",
+      info: { version: "1.0.0" },
+    });
+  });
+
+  it("rejects invalid JSON when format is 'json', even if it happens to be valid YAML", () => {
+    // A bare, unquoted top-level scalar - valid YAML, not valid JSON. Proves
+    // parseBundledSpec doesn't quietly fall back to a lenient parser.
+    expect(() => parseBundledSpec("not json", "json")).toThrow();
+  });
+
+  it("parses 'yaml' as YAML", () => {
+    const result = parseBundledSpec(
+      'openapi: "3.1.0"\ninfo:\n  version: "1.0.0"\n',
+      "yaml",
+    );
+
+    expect(result).toEqual({
+      openapi: "3.1.0",
+      info: { version: "1.0.0" },
+    });
+  });
+
+  it("accepts plain JSON text when format is 'yaml' (JSON is valid YAML)", () => {
+    const result = parseBundledSpec(
+      '{"openapi":"3.1.0","info":{"version":"1.0.0"}}',
+      "yaml",
+    );
+
+    expect(result).toEqual({
+      openapi: "3.1.0",
+      info: { version: "1.0.0" },
+    });
+  });
+});

package/src/config/spec-format.ts

@@ -0,0 +1,48 @@
+import { parse as parseYaml } from "yaml";
+
+import type { SpecFormat } from "./schema";
+
+export type { SpecFormat } from "./schema";
+
+/**
+ * The "primary" format among a `paths.specFormat` list - the one SDK generation,
+ * version/hash resolution, and the docs site actually read from when more than
+ * one format is configured. By convention, that's whichever format was listed
+ * first.
+ *
+ * @param formats - `config.paths.specFormat` (always non-empty).
+ * @returns The primary format.
+ */
+export function primarySpecFormat(formats: SpecFormat[]): SpecFormat {
+  return formats[0]!;
+}
+
+/**
+ * The filename a contract's bundled spec is written to/read from, e.g.
+ * `auth.json` or `auth.yaml` - one place computing this so `bundle`, `generate`,
+ * and `docs generate` can't disagree about the extension.
+ *
+ * @param contractName - The contract's `name`.
+ * @param format       - `config.paths.specFormat`.
+ * @returns The filename (no directory), e.g. `"auth.yaml"`.
+ */
+export function specFilename(contractName: string, format: SpecFormat): string {
+  return `${contractName}.${format}`;
+}
+
+/**
+ * Parses a bundled spec's raw file contents according to its configured format.
+ * JSON and YAML are both valid inputs to Redocly/openapi-generator/
+ * openapi-typescript, so seagull's own parsing has to match: `JSON.parse`
+ * rejects trailing commas and comments that valid YAML permits, and would
+ * silently misparse a YAML document that happens to look JSON-ish.
+ *
+ * @param raw    - The raw bundled spec file contents.
+ * @param format - `config.paths.specFormat`.
+ * @returns The parsed document.
+ */
+export function parseBundledSpec(raw: string, format: SpecFormat): unknown {
+  return format === "json"
+    ? (JSON.parse(raw) as unknown)
+    : parseYaml(raw, { merge: true });
+}

package/src/config/template.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+
+import { buildTemplateContext, interpolate, interpolateDeep } from "./template";
+
+describe("interpolate", () => {
+  it("replaces a single placeholder", () => {
+    expect(interpolate("hello {name}", { name: "world" })).toBe("hello world");
+  });
+
+  it("replaces multiple placeholders, including repeats", () => {
+    expect(interpolate("{a}-{b}-{a}", { a: "x", b: "y" })).toBe("x-y-x");
+  });
+
+  it("supports dotted placeholder keys", () => {
+    expect(
+      interpolate("@{vars.org}/{service}-client", {
+        "vars.org": "octalmesh",
+        service: "auth",
+      }),
+    ).toBe("@octalmesh/auth-client");
+  });
+
+  it("returns the template unchanged when it has no placeholders", () => {
+    expect(interpolate("no placeholders here", {})).toBe(
+      "no placeholders here",
+    );
+  });
+
+  it("leaves non-placeholder braces-free text alone alongside real placeholders", () => {
+    expect(interpolate("v{version}!!", { version: "1.0.0" })).toBe("v1.0.0!!");
+  });
+
+  it("throws a descriptive error for an unknown placeholder", () => {
+    expect(() => interpolate("{missing}", { known: "x" })).toThrow(
+      /Unknown template placeholder "\{missing\}" in "\{missing\}" \(available: known\)/,
+    );
+  });
+
+  it("lists available keys sorted in the error message", () => {
+    expect(() => interpolate("{missing}", { zeta: "1", alpha: "2" })).toThrow(
+      /available: alpha, zeta/,
+    );
+  });
+
+  it("throws on an empty context when a placeholder is present", () => {
+    expect(() => interpolate("{x}", {})).toThrow(/available: /);
+  });
+
+  it("does not treat a placeholder-shaped key with invalid characters as one", () => {
+    expect(interpolate("{not a placeholder}", {})).toBe("{not a placeholder}");
+  });
+
+  it("resolves a value that itself contains no braces even if empty string", () => {
+    expect(interpolate("[{x}]", { x: "" })).toBe("[]");
+  });
+});
+
+describe("interpolateDeep", () => {
+  it("interpolates a bare string", () => {
+    expect(interpolateDeep("{a}", { a: "1" })).toBe("1");
+  });
+
+  it("leaves non-string primitives untouched", () => {
+    expect(interpolateDeep(42, {})).toBe(42);
+    expect(interpolateDeep(true, {})).toBe(true);
+    expect(interpolateDeep(null, {})).toBe(null);
+    expect(interpolateDeep(undefined, {})).toBe(undefined);
+  });
+
+  it("recurses into arrays", () => {
+    expect(interpolateDeep(["{a}", "{b}", 3], { a: "1", b: "2" })).toEqual([
+      "1",
+      "2",
+      3,
+    ]);
+  });
+
+  it("recurses into plain objects, preserving shape", () => {
+    const result = interpolateDeep(
+      { npmName: "{pkg}", withGoMod: true, count: 3 },
+      { pkg: "@org/pkg" },
+    );
+
+    expect(result).toEqual({
+      npmName: "@org/pkg",
+      withGoMod: true,
+      count: 3,
+    });
+  });
+
+  it("recurses into nested structures (object of arrays of objects)", () => {
+    const result = interpolateDeep(
+      { list: [{ id: "{id}" }, { id: "static" }] },
+      { id: "42" },
+    );
+
+    expect(result).toEqual({ list: [{ id: "42" }, { id: "static" }] });
+  });
+
+  it("produces a deep copy rather than mutating the input", () => {
+    const input = { a: { b: "{x}" } };
+    const result = interpolateDeep(input, { x: "y" });
+
+    expect(result).not.toBe(input);
+    expect(result.a).not.toBe(input.a);
+    expect(input.a.b).toBe("{x}");
+  });
+});
+
+describe("buildTemplateContext", () => {
+  it("flattens a nested scope into dot-path keys", () => {
+    expect(
+      buildTemplateContext({
+        service: "auth",
+        repository: { owner: "OctalMesh", repo: "ows-contracts" },
+        vars: { org: "octalmesh", nested: { deep: "value" } },
+      }),
+    ).toEqual({
+      service: "auth",
+      "repository.owner": "OctalMesh",
+      "repository.repo": "ows-contracts",
+      "vars.org": "octalmesh",
+      "vars.nested.deep": "value",
+    });
+  });
+
+  it("stringifies numbers and booleans at leaf positions", () => {
+    expect(
+      buildTemplateContext({ vars: { port: 8080, enabled: true } }),
+    ).toEqual({ "vars.port": "8080", "vars.enabled": "true" });
+  });
+
+  it("skips undefined leaves entirely", () => {
+    expect(buildTemplateContext({ a: "x", b: undefined })).toEqual({ a: "x" });
+  });
+
+  it("does not descend into arrays as if they were nested scopes", () => {
+    const result = buildTemplateContext({ list: ["a", "b"] as never });
+
+    expect(result).toEqual({ list: "a,b" });
+  });
+
+  it("returns an empty object for an empty scope", () => {
+    expect(buildTemplateContext({})).toEqual({});
+  });
+
+  it("round-trips with interpolate for a realistic artifact context", () => {
+    const context = buildTemplateContext({
+      service: "auth",
+      id: "ts-client",
+      repository: { owner: "OctalMesh", repo: "ows-contracts" },
+      vars: { org: "octalmesh" },
+    });
+
+    expect(interpolate("sdk/svc-{service}/{id}", context)).toBe(
+      "sdk/svc-auth/ts-client",
+    );
+    expect(interpolate("@{vars.org}/{service}-client", context)).toBe(
+      "@octalmesh/auth-client",
+    );
+    expect(
+      interpolate(
+        "https://github.com/{repository.owner}/{repository.repo}",
+        context,
+      ),
+    ).toBe("https://github.com/OctalMesh/ows-contracts");
+  });
+});

package/src/config/types.ts

@@ -1,6 +1,6 @@
-import type { VarsTree } from "./schema";
+import type { SpecFormat, VarsTree } from "./schema";
 
-export type { VarsTree } from "./schema";
+export type { SpecFormat, VarsTree } from "./schema";
 export type SdkTool = "openapi-generator" | "openapi-typescript";
 export type SdkLang = "typescript" | "go" | "java";
 export type SdkKind = "client" | "server";
@@ -114,9 +114,9 @@ export interface ResolvedConfig {
     specs: string;
     docs: string;
     sdk: string;
+    specFormat: SpecFormat[];
   };
 
-  github: { owner: string; repo: string };
   vars: VarsTree;
 
   docs: {

package/src/generator/generator.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { SdkTool } from "../config/types";
+import { Generator } from "./generator";
+import type { GenerateContext, PrepareContext } from "./types";
+
+class StubGenerator extends Generator {
+  readonly tool: SdkTool = "openapi-typescript";
+  readonly generateSpy = vi.fn((_ctx: GenerateContext) => Promise.resolve());
+
+  async generate(ctx: GenerateContext): Promise<void> {
+    await this.generateSpy(ctx);
+  }
+}
+
+describe("Generator", () => {
+  it("does not require 'prepare' to be implemented", () => {
+    const generator = new StubGenerator();
+
+    expect(typeof generator.prepare).toBe("undefined");
+  });
+
+  it("subclasses can implement 'prepare' as an optional hook", async () => {
+    const prepareSpy = vi.fn((_ctx: PrepareContext) => Promise.resolve());
+
+    class WithPrepare extends Generator {
+      readonly tool: SdkTool = "openapi-generator";
+
+      override async prepare(ctx: PrepareContext): Promise<void> {
+        await prepareSpy(ctx);
+      }
+
+      generate(): Promise<void> {
+        return Promise.resolve();
+      }
+    }
+
+    const generator = new WithPrepare();
+
+    await generator.prepare?.({ rootDir: "/tmp", entries: [] });
+
+    expect(prepareSpy).toHaveBeenCalledOnce();
+  });
+
+  it("exposes 'tool' as a readonly discriminator", () => {
+    const generator = new StubGenerator();
+
+    expect(generator.tool).toBe("openapi-typescript");
+  });
+
+  it("requires 'generate' to be implemented and calls through to it", async () => {
+    const generator = new StubGenerator();
+    const ctx = {} as GenerateContext;
+
+    await generator.generate(ctx);
+
+    expect(generator.generateSpy).toHaveBeenCalledWith(ctx);
+  });
+});

package/src/generator/registry.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+
+import type { SdkTool } from "../config/types";
+import { Generator } from "./generator";
+import { GeneratorRegistry } from "./registry";
+import type { GenerateContext } from "./types";
+
+class FakeGenerator extends Generator {
+  readonly tool: SdkTool;
+
+  constructor(tool: SdkTool) {
+    super();
+    this.tool = tool;
+  }
+
+  generate(_ctx: GenerateContext): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+describe("GeneratorRegistry", () => {
+  it("resolves a generator by its registered tool", () => {
+    const registry = new GeneratorRegistry();
+    const generator = new FakeGenerator("openapi-generator");
+
+    registry.register(generator);
+
+    expect(registry.resolve("openapi-generator")).toBe(generator);
+  });
+
+  it("returns 'this' from register(), enabling chaining", () => {
+    const registry = new GeneratorRegistry();
+    const result = registry
+      .register(new FakeGenerator("openapi-generator"))
+      .register(new FakeGenerator("openapi-typescript"));
+
+    expect(result).toBe(registry);
+  });
+
+  it("throws a descriptive error for an unregistered tool", () => {
+    const registry = new GeneratorRegistry();
+
+    registry.register(new FakeGenerator("openapi-typescript"));
+
+    expect(() => registry.resolve("openapi-generator")).toThrow(
+      /No generator implementation registered for tool "openapi-generator" \(available: openapi-typescript\)/,
+    );
+  });
+
+  it("throws with an empty available-list when nothing is registered", () => {
+    const registry = new GeneratorRegistry();
+
+    expect(() => registry.resolve("openapi-generator")).toThrow(
+      /\(available: \)/,
+    );
+  });
+
+  it("re-registering the same tool replaces the previous generator", () => {
+    const registry = new GeneratorRegistry();
+    const first = new FakeGenerator("openapi-generator");
+    const second = new FakeGenerator("openapi-generator");
+
+    registry.register(first).register(second);
+
+    expect(registry.resolve("openapi-generator")).toBe(second);
+  });
+
+  it("tools() lists every distinct registered tool", () => {
+    const registry = new GeneratorRegistry();
+
+    registry
+      .register(new FakeGenerator("openapi-generator"))
+      .register(new FakeGenerator("openapi-typescript"));
+
+    expect(registry.tools().sort()).toEqual([
+      "openapi-generator",
+      "openapi-typescript",
+    ]);
+  });
+
+  it("tools() returns an empty array for a fresh registry", () => {
+    expect(new GeneratorRegistry().tools()).toEqual([]);
+  });
+});

package/src/generator/types.ts

@@ -2,18 +2,12 @@ import type {
   ResolvedArtifact,
   ResolvedArtifactEntry,
   ResolvedContract,
-  SdkTool,
 } from "../config/types";
 
-export type {
-  ResolvedArtifact,
-  ResolvedArtifactEntry,
-  ResolvedContract,
-  SdkTool,
-};
-
-/** Passed once per tool to {@link Generator.prepare}, before any of that
- * tool's {@link Generator.generate} calls run. */
+/**
+ * Passed once per tool to {@link Generator.prepare}, before any of that
+ * tool's {@link Generator.generate} calls run.
+ */
 export interface PrepareContext {
   rootDir: string;
   /**
@@ -23,16 +17,17 @@ export interface PrepareContext {
   entries: ResolvedArtifactEntry[];
 }
 
-/** Passed once per artifact to {@link Generator.generate}. */
+/**
+ * Passed once per artifact to {@link Generator.generate}.
+ */
 export interface GenerateContext {
   rootDir: string;
   contract: ResolvedContract;
   artifact: ResolvedArtifact;
   version: string;
-  github: { owner: string; repo: string };
   /**
-   * Absolute path to the contract's bundled JSON spec
-   * (`<specsDir>/<contract>.json`).
+   * Absolute path to the contract's bundled spec
+   * (`<specsDir>/<contract>.<paths.specFormat>` - `json` or `yaml`).
    */
   specInputPath: string;
 }