@octalmesh/seagull-core 0.0.2 → 0.1.1

package/src/config/publishing.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+
+import { renderArtifactTag } from "./publishing";
+import type { ResolvedArtifact } from "./types";
+
+function makeArtifact(
+  overrides: Partial<ResolvedArtifact> = {},
+): ResolvedArtifact {
+  return {
+    id: "ts-client",
+    tool: "openapi-generator",
+    lang: "typescript",
+    kind: "client",
+    outputDir: "/tmp/out",
+    branch: "sdk/svc-auth/ts-client",
+    publishing: {
+      branch: "sdk/svc-auth/ts-client",
+      tagTemplate: "svc-{service}-{id}-v{version}",
+      repositoryUrl: "https://github.com/OctalMesh/ows-contracts",
+      npmRegistry: "https://npm.pkg.github.com",
+      npmAccess: "public",
+      mavenRepositoryId: "github",
+      mavenRepositoryUrl:
+        "https://maven.pkg.github.com/OctalMesh/ows-contracts",
+    },
+    additionalProperties: {},
+    ...overrides,
+  };
+}
+
+describe("renderArtifactTag", () => {
+  it("renders {service}, {id}, and {version} into the tag template", () => {
+    const tag = renderArtifactTag(makeArtifact(), "auth", "1.2.3", {});
+
+    expect(tag).toBe("svc-auth-ts-client-v1.2.3");
+  });
+
+  it("supports {vars.*} placeholders in the tag template, including nested trees", () => {
+    const artifact = makeArtifact({
+      publishing: {
+        ...makeArtifact().publishing,
+        tagTemplate:
+          "{vars.org}-{vars.repository.repo}-{service}-{id}-v{version}",
+      },
+    });
+
+    const tag = renderArtifactTag(artifact, "catalog", "0.4.0", {
+      org: "octalmesh",
+      repository: { owner: "OctalMesh", repo: "ows-contracts" },
+    });
+
+    expect(tag).toBe("octalmesh-ows-contracts-catalog-ts-client-v0.4.0");
+  });
+
+  it("throws when the tag template references an unresolvable placeholder", () => {
+    const artifact = makeArtifact({
+      publishing: {
+        ...makeArtifact().publishing,
+        tagTemplate: "{vars.missing}-v{version}",
+      },
+    });
+
+    expect(() => renderArtifactTag(artifact, "auth", "1.0.0", {})).toThrow(
+      /Unknown template placeholder/,
+    );
+  });
+
+  it("throws a descriptive error when the resolved tag would start with '-'", () => {
+    const artifact = makeArtifact({
+      publishing: {
+        ...makeArtifact().publishing,
+        tagTemplate: "-{vars.opt}",
+      },
+    });
+
+    expect(() =>
+      renderArtifactTag(artifact, "auth", "1.0.0", {
+        opt: "upload-pack=evil.sh",
+      }),
+    ).toThrow(
+      /Invalid git publishing\.tag for artifact "auth\/ts-client" "-upload-pack=evil\.sh": must not start with "-"/,
+    );
+  });
+
+  it("uses the artifact's own id, not its branch, for {id}", () => {
+    const artifact = makeArtifact({ id: "go-client" });
+
+    const tag = renderArtifactTag(artifact, "auth", "1.0.0", {});
+
+    expect(tag).toBe("svc-auth-go-client-v1.0.0");
+  });
+});

package/src/config/publishing.ts

@@ -1,3 +1,4 @@
+import { assertSafeRefName } from "../git/git";
 import { buildTemplateContext, interpolate } from "./template";
 import type { ResolvedArtifact, VarsTree } from "./types";
 
@@ -13,8 +14,6 @@ import type { ResolvedArtifact, VarsTree } from "./types";
  *                       `{service}`.
  * @param version      - The resolved SDK version, exposed to the template as
  *                       `{version}`.
- * @param github       - `{ owner, repo }`, exposed as `{github.owner}`/
- *                       `{github.repo}`.
  * @param vars         - The config's `vars:` tree, exposed as `{vars.*}`.
  * @returns The rendered tag name.
  */
@@ -22,16 +21,21 @@ export function renderArtifactTag(
   artifact: ResolvedArtifact,
   contractName: string,
   version: string,
-  github: { owner: string; repo: string },
   vars: VarsTree,
 ): string {
   const context = buildTemplateContext({
     service: contractName,
     id: artifact.id,
     version,
-    github,
     vars,
   });
 
-  return interpolate(artifact.publishing.tagTemplate, context);
+  const tag = interpolate(artifact.publishing.tagTemplate, context);
+
+  assertSafeRefName(
+    tag,
+    `publishing.tag for artifact "${contractName}/${artifact.id}"`,
+  );
+
+  return tag;
 }

package/src/config/resolve-config-file.test.ts

@@ -0,0 +1,60 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { CONFIG_FILENAMES, resolveConfigPath } from "./resolve-config-file";
+
+describe("resolveConfigPath", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), "seagull-resolve-config-"));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it("throws with the full candidate list when no config file exists", () => {
+    expect(() => resolveConfigPath(dir)).toThrow(
+      new RegExp(
+        `No CLI config found in ${dir.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+      ),
+    );
+
+    for (const filename of CONFIG_FILENAMES) {
+      expect(() => resolveConfigPath(dir)).toThrow(
+        new RegExp(filename.replace(".", "\\.")),
+      );
+    }
+  });
+
+  it("finds 'seagull.yaml' when present", async () => {
+    await writeFile(path.join(dir, "seagull.yaml"), "configVersion: 1");
+
+    expect(resolveConfigPath(dir)).toBe(path.join(dir, "seagull.yaml"));
+  });
+
+  it("prefers earlier filenames in CONFIG_FILENAMES order over later ones", async () => {
+    await writeFile(path.join(dir, ".seagull"), "configVersion: 1");
+    await writeFile(path.join(dir, "seagull.yaml"), "configVersion: 1");
+
+    expect(resolveConfigPath(dir)).toBe(path.join(dir, ".seagull"));
+  });
+
+  it("falls through to a later candidate when earlier ones are absent", async () => {
+    await writeFile(path.join(dir, "seagull.yml"), "configVersion: 1");
+
+    expect(resolveConfigPath(dir)).toBe(path.join(dir, "seagull.yml"));
+  });
+
+  it("returns an absolute path", async () => {
+    await writeFile(path.join(dir, ".seagull.yaml"), "configVersion: 1");
+
+    const resolved = resolveConfigPath(dir);
+
+    expect(path.isAbsolute(resolved)).toBe(true);
+  });
+});

package/src/config/schema.test.ts

@@ -0,0 +1,466 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  CONFIG_SCHEMA_VERSION,
+  artifactRefSchema,
+  contractSchema,
+  generatorDefSchema,
+  publishingSchema,
+  rootConfigSchema,
+  varsTreeSchema,
+} from "./schema";
+
+const validPublishing = {
+  branch: "sdk/svc-{service}/{id}",
+  tag: "svc-{service}-{id}-v{version}",
+  repositoryUrl:
+    "https://github.com/{vars.repository.owner}/{vars.repository.repo}",
+  npm: { registry: "https://npm.pkg.github.com", access: "public" as const },
+  maven: {
+    repositoryId: "github",
+    repositoryUrl:
+      "https://maven.pkg.github.com/{vars.repository.owner}/{vars.repository.repo}",
+  },
+};
+
+const minimalRootConfig = {
+  configVersion: 1,
+  docs: {
+    server: { host: "localhost", port: 8080 },
+    metadata: {
+      title: "t",
+      description: "d",
+      favicon: "f",
+      baseServerUrl: "https://example.com",
+    },
+  },
+  publishing: validPublishing,
+  generators: {
+    "ts-server": {
+      tool: "openapi-typescript",
+      lang: "typescript",
+      kind: "server",
+      package: "@org/{service}-server",
+      additionalProperties: {},
+    },
+  },
+  contracts: [
+    {
+      name: "auth",
+      title: "Auth Service API",
+      entrypoint: "specs/auth/openapi.yaml",
+      artifacts: ["ts-server"],
+    },
+  ],
+};
+
+describe("varsTreeSchema", () => {
+  it("accepts a free-form nested tree of string/number/boolean leaves", () => {
+    const result = varsTreeSchema.safeParse({
+      org: "octalmesh",
+      port: 8080,
+      enabled: true,
+      nested: { deep: { deeper: "value" } },
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects a leaf of an unsupported type", () => {
+    const result = varsTreeSchema.safeParse({ bad: null });
+
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts an empty tree", () => {
+    expect(varsTreeSchema.safeParse({}).success).toBe(true);
+  });
+});
+
+describe("generatorDefSchema", () => {
+  const base = {
+    tool: "openapi-generator" as const,
+    lang: "typescript" as const,
+    kind: "client" as const,
+    generator: "typescript-fetch",
+    package: "@org/pkg",
+    additionalProperties: {},
+  };
+
+  it("accepts a minimal valid typescript openapi-generator recipe", () => {
+    expect(generatorDefSchema.safeParse(base).success).toBe(true);
+  });
+
+  it("requires 'generator' when tool is 'openapi-generator'", () => {
+    const rest: Record<string, unknown> = { ...base };
+
+    delete rest.generator;
+    const result = generatorDefSchema.safeParse(rest);
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues[0]?.message).toMatch(
+        /"generator" is required when tool is "openapi-generator"/,
+      );
+    }
+  });
+
+  it("does not require 'generator' when tool is 'openapi-typescript'", () => {
+    const result = generatorDefSchema.safeParse({
+      tool: "openapi-typescript",
+      lang: "typescript",
+      kind: "server",
+      package: "@org/pkg",
+      additionalProperties: {},
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("requires 'goModule' for lang 'go'", () => {
+    const result = generatorDefSchema.safeParse({
+      ...base,
+      lang: "go",
+      generator: "go",
+      goPackageName: "authclient",
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(
+        result.error.issues.some((issue) =>
+          issue.message.includes('"goModule" is required for lang "go"'),
+        ),
+      ).toBe(true);
+    }
+  });
+
+  it("accepts lang 'go' when goModule is present", () => {
+    const result = generatorDefSchema.safeParse({
+      ...base,
+      lang: "go",
+      generator: "go",
+      package: undefined,
+      goModule: "github.com/org/repo",
+      goPackageName: "authclient",
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("requires 'maven' ({groupId, artifactId}) for lang 'java'", () => {
+    const result = generatorDefSchema.safeParse({
+      ...base,
+      lang: "java",
+      generator: "java",
+      package: undefined,
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(
+        result.error.issues.some((issue) => issue.message.includes('"maven"')),
+      ).toBe(true);
+    }
+  });
+
+  it("accepts lang 'java' when maven coordinates are present", () => {
+    const result = generatorDefSchema.safeParse({
+      ...base,
+      lang: "java",
+      generator: "java",
+      package: undefined,
+      maven: { groupId: "com.org.svc", artifactId: "svc-client" },
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("requires 'package' for lang 'typescript'", () => {
+    const result = generatorDefSchema.safeParse({
+      ...base,
+      package: undefined,
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(
+        result.error.issues.some((issue) =>
+          issue.message.includes('"package" is required for lang "typescript"'),
+        ),
+      ).toBe(true);
+    }
+  });
+
+  it("can report multiple independent cross-field issues at once", () => {
+    const result = generatorDefSchema.safeParse({
+      tool: "openapi-generator",
+      lang: "go",
+      kind: "client",
+      additionalProperties: {},
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues.length).toBeGreaterThanOrEqual(2);
+    }
+  });
+
+  it("defaults additionalProperties to an empty object when omitted", () => {
+    const result = generatorDefSchema.safeParse({
+      tool: "openapi-typescript",
+      lang: "typescript",
+      kind: "server",
+      package: "@org/pkg",
+    });
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.additionalProperties).toEqual({});
+    }
+  });
+
+  it("rejects an empty-string 'generator' as if absent", () => {
+    const result = generatorDefSchema.safeParse({ ...base, generator: "" });
+
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("artifactRefSchema", () => {
+  it("accepts a plain string id", () => {
+    expect(artifactRefSchema.safeParse("ts-client").success).toBe(true);
+  });
+
+  it("rejects an empty string id", () => {
+    expect(artifactRefSchema.safeParse("").success).toBe(false);
+  });
+
+  it("accepts the object form with generator/as/overrides", () => {
+    const result = artifactRefSchema.safeParse({
+      generator: "ts-client",
+      as: "ts-client-legacy",
+      overrides: { package: "@org/legacy-{service}" },
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts the object form with only 'generator' set", () => {
+    expect(
+      artifactRefSchema.safeParse({ generator: "ts-client" }).success,
+    ).toBe(true);
+  });
+
+  it("rejects an object form missing 'generator'", () => {
+    expect(artifactRefSchema.safeParse({ as: "x" }).success).toBe(false);
+  });
+
+  it("allows overrides to be a partial generator def missing required fields", () => {
+    const result = artifactRefSchema.safeParse({
+      generator: "java-client",
+      overrides: { additionalProperties: { library: "restclient" } },
+    });
+
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("contractSchema", () => {
+  it("requires at least one artifact", () => {
+    const result = contractSchema.safeParse({
+      name: "auth",
+      title: "Auth",
+      entrypoint: "specs/auth/openapi.yaml",
+      artifacts: [],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts a contract with mixed string and object artifact refs", () => {
+    const result = contractSchema.safeParse({
+      name: "auth",
+      title: "Auth",
+      entrypoint: "specs/auth/openapi.yaml",
+      artifacts: ["ts-client", { generator: "java-client", as: "java-v2" }],
+    });
+
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("publishingSchema", () => {
+  it("accepts a fully specified publishing block", () => {
+    expect(publishingSchema.safeParse(validPublishing).success).toBe(true);
+  });
+
+  it("rejects a publishing block missing 'maven'", () => {
+    const rest: Record<string, unknown> = { ...validPublishing };
+
+    delete rest.maven;
+
+    expect(publishingSchema.safeParse(rest).success).toBe(false);
+  });
+
+  it("rejects an npm.access value outside the enum", () => {
+    const result = publishingSchema.safeParse({
+      ...validPublishing,
+      npm: { ...validPublishing.npm, access: "private" },
+    });
+
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("rootConfigSchema", () => {
+  it("accepts a minimal valid config", () => {
+    const result = rootConfigSchema.safeParse(minimalRootConfig);
+
+    expect(result.success).toBe(true);
+  });
+
+  it("defaults 'vars' to an empty object", () => {
+    const result = rootConfigSchema.safeParse(minimalRootConfig);
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.vars).toEqual({});
+    }
+  });
+
+  it("defaults 'paths' to { dist: 'dist', specFormat: ['json'] }", () => {
+    const result = rootConfigSchema.safeParse(minimalRootConfig);
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.paths).toEqual({
+        dist: "dist",
+        specFormat: ["json"],
+      });
+    }
+  });
+
+  it("only accepts configVersion === CONFIG_SCHEMA_VERSION", () => {
+    expect(CONFIG_SCHEMA_VERSION).toBe(1);
+
+    const result = rootConfigSchema.safeParse({
+      ...minimalRootConfig,
+      configVersion: 2,
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it("requires at least one contract", () => {
+    const result = rootConfigSchema.safeParse({
+      ...minimalRootConfig,
+      contracts: [],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it("requires the root 'publishing' block", () => {
+    const rest: Record<string, unknown> = { ...minimalRootConfig };
+
+    delete rest.publishing;
+    const result = rootConfigSchema.safeParse(rest);
+
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects a contract referencing artifacts by any shape but keeps generators as a free map", () => {
+    const result = rootConfigSchema.safeParse({
+      ...minimalRootConfig,
+      generators: {
+        ...minimalRootConfig.generators,
+        "another-one": {
+          tool: "openapi-typescript",
+          lang: "typescript",
+          kind: "server",
+          package: "@org/other-{service}",
+          additionalProperties: {},
+        },
+      },
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts explicit paths overrides", () => {
+    const result = rootConfigSchema.safeParse({
+      ...minimalRootConfig,
+      paths: { dist: "build", specs: "specs-out", docs: "docs-out" },
+    });
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.paths).toEqual({
+        dist: "build",
+        specs: "specs-out",
+        docs: "docs-out",
+        specFormat: ["json"],
+      });
+    }
+  });
+
+  it("accepts paths.specFormat as a single value, normalizing it to a one-element array", () => {
+    const result = rootConfigSchema.safeParse({
+      ...minimalRootConfig,
+      paths: { dist: "dist", specFormat: "yaml" },
+    });
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.paths.specFormat).toEqual(["yaml"]);
+    }
+  });
+
+  it("accepts paths.specFormat as a list, bundling into more than one format", () => {
+    const result = rootConfigSchema.safeParse({
+      ...minimalRootConfig,
+      paths: { dist: "dist", specFormat: ["json", "yaml"] },
+    });
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.paths.specFormat).toEqual(["json", "yaml"]);
+    }
+  });
+
+  it("rejects a paths.specFormat outside 'json' | 'yaml'", () => {
+    const result = rootConfigSchema.safeParse({
+      ...minimalRootConfig,
+      paths: { dist: "dist", specFormat: "yml" },
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects an empty paths.specFormat list", () => {
+    const result = rootConfigSchema.safeParse({
+      ...minimalRootConfig,
+      paths: { dist: "dist", specFormat: [] },
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects duplicate entries in paths.specFormat", () => {
+    const result = rootConfigSchema.safeParse({
+      ...minimalRootConfig,
+      paths: { dist: "dist", specFormat: ["json", "json"] },
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects a config missing docs metadata", () => {
+    const rest: Record<string, unknown> = { ...minimalRootConfig };
+
+    delete rest.docs;
+
+    expect(rootConfigSchema.safeParse(rest).success).toBe(false);
+  });
+});