@octalmesh/seagull-core 0.0.2 → 0.1.1

package/src/process/resolve-bin.test.ts

@@ -0,0 +1,43 @@
+import { existsSync } from "node:fs";
+
+import { describe, expect, it } from "vitest";
+
+import { resolveBinPath } from "./resolve-bin";
+
+describe("resolveBinPath", () => {
+  it("resolves an installed package's default bin entry to an existing file", () => {
+    const bin = resolveBinPath("@redocly/cli", "redocly");
+
+    expect(existsSync(bin)).toBe(true);
+    expect(bin).toMatch(/cli\.js$/);
+  });
+
+  it("resolves a string-form 'bin' field (not just the object form)", () => {
+    const bin = resolveBinPath("prettier", "prettier");
+
+    expect(existsSync(bin)).toBe(true);
+    expect(bin).toMatch(/prettier\.cjs$/);
+  });
+
+  it("resolves a non-default bin entry when the package exposes multiple", () => {
+    const bin = resolveBinPath("@redocly/cli", "openapi");
+
+    expect(existsSync(bin)).toBe(true);
+  });
+
+  it("defaults 'binName' to the package's own unscoped name when omitted", () => {
+    expect(() => resolveBinPath("@redocly/cli")).toThrow(
+      /Could not resolve a "cli" bin entry for package "@redocly\/cli"/,
+    );
+  });
+
+  it("throws a descriptive error for a package with no matching bin entry", () => {
+    expect(() => resolveBinPath("@redocly/cli", "does-not-exist")).toThrow(
+      /Could not resolve a "does-not-exist" bin entry for package "@redocly\/cli" - is it installed, and does it expose that bin\?/,
+    );
+  });
+
+  it("throws when the package itself cannot be resolved", () => {
+    expect(() => resolveBinPath("@octalmesh/does-not-exist")).toThrow();
+  });
+});

package/src/readme/default-templates.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, it } from "vitest";
+
+import { makeArtifact, makeContract } from "../test-support/fixtures";
+import { renderDefaultReadme } from "./default-templates";
+
+describe("renderDefaultReadme", () => {
+  it("renders a common header with title, source, version, and branch", () => {
+    const contract = makeContract();
+    const artifact = makeArtifact();
+
+    const readme = renderDefaultReadme({
+      contract,
+      artifact,
+      version: "1.2.3",
+      vars: {},
+    });
+
+    expect(readme).toContain("# Auth Service API - TypeScript Client SDK");
+    expect(readme).toContain(
+      "> Generated from `specs/auth/openapi.yaml` in https://github.com/OctalMesh/ows-contracts.",
+    );
+    expect(readme).toContain("Version: `1.2.3`");
+    expect(readme).toContain("Source branch: `sdk/svc-auth/ts-client`");
+  });
+
+  it.each([
+    ["typescript", "client", "TypeScript Client SDK"],
+    ["typescript", "server", "TypeScript Server Types"],
+    ["go", "client", "Go Client SDK"],
+    ["go", "server", "Go Server Stubs"],
+    ["java", "client", "Java Client SDK"],
+    ["java", "server", "Java Server Stubs"],
+  ] as const)("labels %s/%s as '%s'", (lang, kind, label) => {
+    const artifact = makeArtifact({
+      lang,
+      kind,
+      package: lang === "typescript" ? "@org/pkg" : undefined,
+      goModule: lang === "go" ? "github.com/org/repo" : undefined,
+      goPackageName: lang === "go" ? "authclient" : undefined,
+      maven:
+        lang === "java"
+          ? { groupId: "com.org.auth", artifactId: "auth-client" }
+          : undefined,
+    });
+
+    const readme = renderDefaultReadme({
+      contract: makeContract(),
+      artifact,
+      version: "1.0.0",
+      vars: {},
+    });
+
+    expect(readme).toContain(`- ${label}`);
+  });
+
+  it("typescript-client body includes npm install/usage instructions", () => {
+    const readme = renderDefaultReadme({
+      contract: makeContract(),
+      artifact: makeArtifact({
+        lang: "typescript",
+        kind: "client",
+        package: "@octalmesh/auth-client",
+      }),
+      version: "1.0.0",
+      vars: {},
+    });
+
+    expect(readme).toContain("npm install @octalmesh/auth-client@1.0.0");
+    expect(readme).toContain(
+      'import { Configuration, DefaultApi } from "@octalmesh/auth-client";',
+    );
+  });
+
+  it("typescript-server body includes types-only usage, not a client import", () => {
+    const readme = renderDefaultReadme({
+      contract: makeContract(),
+      artifact: makeArtifact({
+        lang: "typescript",
+        kind: "server",
+        package: "@octalmesh/auth-server",
+      }),
+      version: "1.0.0",
+      vars: {},
+    });
+
+    expect(readme).toContain(
+      'import type { components, operations } from "@octalmesh/auth-server";',
+    );
+    expect(readme).not.toContain("Configuration, DefaultApi");
+  });
+
+  it("go-client body renders an example tag using the artifact's own tag template", () => {
+    const readme = renderDefaultReadme({
+      contract: makeContract(),
+      artifact: makeArtifact({
+        id: "go-client",
+        lang: "go",
+        kind: "client",
+        package: undefined,
+        goModule: "github.com/octalmesh/ows-contracts",
+        goPackageName: "authclient",
+        branch: "sdk/svc-auth/go-client",
+        publishing: {
+          branch: "sdk/svc-auth/go-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",
+        },
+      }),
+      version: "1.0.0",
+      vars: {},
+    });
+
+    expect(readme).toContain(
+      "go get github.com/octalmesh/ows-contracts@sdk/svc-auth/go-client",
+    );
+    expect(readme).toContain(
+      "go get github.com/octalmesh/ows-contracts@svc-auth-go-client-v<version>",
+    );
+  });
+
+  it("go-server body has no install-by-tag example, just go get + router wiring", () => {
+    const readme = renderDefaultReadme({
+      contract: makeContract(),
+      artifact: makeArtifact({
+        lang: "go",
+        kind: "server",
+        package: undefined,
+        goModule: "github.com/octalmesh/ows-contracts",
+        goPackageName: "authserver",
+      }),
+      version: "1.0.0",
+      vars: {},
+    });
+
+    expect(readme).toContain("authserver.NewRouter(");
+  });
+
+  it("java-client body renders Maven coordinates and a RestClient usage example", () => {
+    const readme = renderDefaultReadme({
+      contract: makeContract(),
+      artifact: makeArtifact({
+        lang: "java",
+        kind: "client",
+        package: undefined,
+        maven: { groupId: "com.octalmesh.auth", artifactId: "auth-client" },
+      }),
+      version: "2.0.0",
+      vars: {},
+    });
+
+    expect(readme).toContain("<groupId>com.octalmesh.auth</groupId>");
+    expect(readme).toContain("<artifactId>auth-client</artifactId>");
+    expect(readme).toContain("<version>2.0.0</version>");
+    expect(readme).toContain("<id>github</id>");
+    expect(readme).toContain("RestClient");
+  });
+
+  it("java-server body notes interfaceOnly generation, not a usable client", () => {
+    const readme = renderDefaultReadme({
+      contract: makeContract(),
+      artifact: makeArtifact({
+        lang: "java",
+        kind: "server",
+        package: undefined,
+        maven: { groupId: "com.octalmesh.auth", artifactId: "auth-server" },
+      }),
+      version: "1.0.0",
+      vars: {},
+    });
+
+    expect(readme).toContain("interfaceOnly=true");
+    expect(readme).toContain("implements SomeApi");
+  });
+});

package/src/readme/default-templates.ts

@@ -9,7 +9,6 @@ export interface DefaultReadmeArgs {
   contract: ResolvedContract;
   artifact: ResolvedArtifact;
   version: string;
-  github: { owner: string; repo: string };
   vars: VarsTree;
 }
 
@@ -22,27 +21,26 @@ export interface DefaultReadmeArgs {
  * come from the artifact's resolved `publishing:` config, so a repo that
  * overrides its registry sees that reflected here automatically.
  *
- * @param args - The contract, artifact, version, and github/vars coordinates
- *               to render for.
+ * @param args - The contract, artifact, version, and vars coordinates to render
+ *               for.
  * @returns The rendered README content.
  */
 export function renderDefaultReadme({
   contract,
   artifact,
   version,
-  github,
   vars,
 }: DefaultReadmeArgs): string {
   const header = `# ${contract.title} - ${label(artifact)}
 
-> Generated from \`${contract.entrypointRelative}\` in [${github.owner}/${github.repo}](https://github.com/${github.owner}/${github.repo}).
+> Generated from \`${contract.entrypointRelative}\` in ${artifact.publishing.repositoryUrl}.
 > Do not edit by hand - this package is regenerated and republished on every release.
 
 Version: \`${version}\`
 Source branch: \`${artifact.branch}\`
 `;
 
-  return `${header}\n${body(contract, artifact, version, github, vars)}\n`;
+  return `${header}\n${body(contract, artifact, version, vars)}\n`;
 }
 
 //<editor-fold desc="README Template Helpers" defaultstate="collapsed">
@@ -65,7 +63,6 @@ function body(
   contract: ResolvedContract,
   artifact: ResolvedArtifact,
   version: string,
-  github: { owner: string; repo: string },
   vars: VarsTree,
 ): string {
   switch (`${artifact.lang}-${artifact.kind}`) {
@@ -74,7 +71,7 @@ function body(
     case "typescript-server":
       return tsServer(artifact, version);
     case "go-client":
-      return goClient(contract, artifact, github, vars);
+      return goClient(contract, artifact, vars);
     case "go-server":
       return goServer(artifact);
     case "java-client":
@@ -146,7 +143,6 @@ app.post("/login", (req, res) => {
 function goClient(
   contract: ResolvedContract,
   artifact: ResolvedArtifact,
-  github: { owner: string; repo: string },
   vars: VarsTree,
 ): string {
   // Illustrative only - renders the tag template with a literal "<version>"
@@ -156,7 +152,6 @@ function goClient(
     artifact,
     contract.name,
     "<version>",
-    github,
     vars,
   );
 

package/src/readme/readme-renderer.test.ts

@@ -0,0 +1,121 @@
+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 { makeArtifact, makeContract } from "../test-support/fixtures";
+import { renderReadme } from "./readme-renderer";
+
+describe("renderReadme", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), "seagull-readme-"));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it("falls back to the built-in default template when no readmeTemplate is set", async () => {
+    const readme = await renderReadme({
+      contract: makeContract(),
+      artifact: makeArtifact({ readmeTemplate: undefined }),
+      version: "1.0.0",
+      vars: {},
+    });
+
+    expect(readme).toContain("# Auth Service API - TypeScript Client SDK");
+  });
+
+  it("reads and interpolates a custom readmeTemplate file when set", async () => {
+    const templatePath = path.join(dir, "custom-readme.md");
+
+    await writeFile(
+      templatePath,
+      [
+        "# {title} - custom",
+        "",
+        "Install `{artifact.package}@{version}` from {artifact.npmRegistry}.",
+        "Branch: {artifact.branch}, tag: {artifact.tag}.",
+        "Org: {vars.org}, repo: {vars.repository.owner}/{vars.repository.repo}.",
+      ].join("\n"),
+    );
+
+    const readme = await renderReadme({
+      contract: makeContract({ title: "Auth Service API" }),
+      artifact: makeArtifact({ readmeTemplate: templatePath }),
+      version: "1.2.3",
+      vars: {
+        org: "octalmesh",
+        repository: { owner: "OctalMesh", repo: "ows-contracts" },
+      },
+    });
+
+    expect(readme).toBe(
+      [
+        "# Auth Service API - custom",
+        "",
+        "Install `@octalmesh/auth-client@1.2.3` from https://npm.pkg.github.com.",
+        "Branch: sdk/svc-auth/ts-client, tag: svc-auth-ts-client-v1.2.3.",
+        "Org: octalmesh, repo: OctalMesh/ows-contracts.",
+      ].join("\n"),
+    );
+  });
+
+  it("exposes artifact.id/lang/kind and maven coordinates to the custom template", async () => {
+    const templatePath = path.join(dir, "java-readme.md");
+
+    await writeFile(
+      templatePath,
+      "{artifact.id} / {artifact.lang} / {artifact.kind} - {artifact.maven.groupId}:{artifact.maven.artifactId}",
+    );
+
+    const readme = await renderReadme({
+      contract: makeContract(),
+      artifact: makeArtifact({
+        id: "java-client",
+        lang: "java",
+        kind: "client",
+        package: undefined,
+        maven: { groupId: "com.octalmesh.auth", artifactId: "auth-client" },
+        readmeTemplate: templatePath,
+      }),
+      version: "1.0.0",
+      vars: {},
+    });
+
+    expect(readme).toBe(
+      "java-client / java / client - com.octalmesh.auth:auth-client",
+    );
+  });
+
+  it("throws when the custom template references an unknown placeholder", async () => {
+    const templatePath = path.join(dir, "broken.md");
+
+    await writeFile(templatePath, "{artifact.doesNotExist}");
+
+    await expect(
+      renderReadme({
+        contract: makeContract(),
+        artifact: makeArtifact({ readmeTemplate: templatePath }),
+        version: "1.0.0",
+        vars: {},
+      }),
+    ).rejects.toThrow(/Unknown template placeholder/);
+  });
+
+  it("rejects when the custom template file doesn't exist", async () => {
+    await expect(
+      renderReadme({
+        contract: makeContract(),
+        artifact: makeArtifact({
+          readmeTemplate: path.join(dir, "missing.md"),
+        }),
+        version: "1.0.0",
+        vars: {},
+      }),
+    ).rejects.toThrow();
+  });
+});

package/src/readme/readme-renderer.ts

@@ -13,7 +13,6 @@ export interface RenderReadmeArgs {
   contract: ResolvedContract;
   artifact: ResolvedArtifact;
   version: string;
-  github: { owner: string; repo: string };
   vars: VarsTree;
 }
 
@@ -23,13 +22,12 @@ export interface RenderReadmeArgs {
  * If the artifact has a `readme:` path configured (resolved at config-load time
  * to `artifact.readmeTemplate`), that file is read and interpolated with the
  * same `{...}` placeholder engine naming templates use - `{service}`,
- * `{title}`, `{version}`, `{vars.*}`, `{github.owner}`, `{github.repo}`, plus
- * `{artifact.*}` (id/lang/kind/package/goModule/goPackageName/maven.groupId/
+ * `{title}`, `{version}`, `{vars.*}`, plus `{artifact.*}`
+ * (id/lang/kind/package/goModule/goPackageName/maven.groupId/
  * maven.artifactId/branch/tag/npmRegistry/mavenRepositoryUrl). Otherwise,
  * falls back to a built-in default template for the artifact's language/kind.
  *
- * @param args - The contract, artifact, version, and github/vars context to
- *               render for.
+ * @param args - The contract, artifact, version, and vars context to render for.
  * @returns The rendered README content.
  */
 export async function renderReadme(args: RenderReadmeArgs): Promise<string> {
@@ -42,7 +40,6 @@ export async function renderReadme(args: RenderReadmeArgs): Promise<string> {
     service: args.contract.name,
     title: args.contract.title,
     version: args.version,
-    github: args.github,
     vars: args.vars,
     artifact: {
       id: args.artifact.id,
@@ -57,7 +54,6 @@ export async function renderReadme(args: RenderReadmeArgs): Promise<string> {
         args.artifact,
         args.contract.name,
         args.version,
-        args.github,
         args.vars,
       ),
       npmRegistry: args.artifact.publishing.npmRegistry,

package/src/redocly/redocly-sync.test.ts

@@ -0,0 +1,190 @@
+import { mkdtemp, readFile, 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 { parse as parseYaml } from "yaml";
+
+import type { ResolvedConfig } from "../config/types";
+import { makeArtifact, makeContract } from "../test-support/fixtures";
+import { syncRedoclyConfig } from "./redocly-sync";
+
+function makeConfig(overrides: Partial<ResolvedConfig> = {}): ResolvedConfig {
+  return {
+    configVersion: 1,
+    rootDir: "/repo",
+    paths: {
+      dist: "/repo/dist",
+      specs: "/repo/dist/specs",
+      docs: "/repo/dist/docs",
+      sdk: "/repo/dist/sdk",
+      specFormat: ["json"],
+    },
+    vars: {},
+    docs: {
+      server: { host: "localhost", port: 8080 },
+      metadata: {
+        title: "t",
+        description: "d",
+        favicon: "f",
+        baseServerUrl: "https://example.com",
+      },
+    },
+    contracts: [makeContract()],
+    allArtifacts: [],
+    ...overrides,
+  };
+}
+
+describe("syncRedoclyConfig", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), "seagull-redocly-"));
+    await writeFile(
+      path.join(dir, "redocly.base.yaml"),
+      [
+        "extends:",
+        '  - "recommended"',
+        "rules:",
+        '  operation-operationId: "error"',
+      ].join("\n"),
+    );
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it("writes redocly.yaml merging the base extends/rules with generated apis", async () => {
+    const config = makeConfig({ rootDir: dir });
+
+    await syncRedoclyConfig(config);
+
+    const written = await readFile(path.join(dir, "redocly.yaml"), "utf8");
+    const parsed = parseYaml(written) as {
+      extends: string[];
+      rules: Record<string, string>;
+      apis: Record<string, unknown>;
+    };
+
+    expect(parsed.extends).toEqual(["recommended"]);
+    expect(parsed.rules).toEqual({ "operation-operationId": "error" });
+    expect(parsed.apis).toHaveProperty("auth@v1");
+  });
+
+  it("prefixes the generated file with the auto-generated header comment", async () => {
+    const config = makeConfig({ rootDir: dir });
+
+    await syncRedoclyConfig(config);
+
+    const written = await readFile(path.join(dir, "redocly.yaml"), "utf8");
+
+    expect(written).toMatch(/^# AUTO-GENERATED by Seagull/);
+    expect(written).toMatch(/Do not edit directly/);
+  });
+
+  it("sets each api's 'root' to the contract's entrypoint relative to rootDir", async () => {
+    const config = makeConfig({ rootDir: dir });
+
+    await syncRedoclyConfig(config);
+
+    const parsed = parseYaml(
+      await readFile(path.join(dir, "redocly.yaml"), "utf8"),
+    ) as { apis: Record<string, { root: string }> };
+
+    expect(parsed.apis["auth@v1"]!.root).toBe("specs/auth/openapi.yaml");
+  });
+
+  it("adds x-openapi-ts.output only for contracts with an openapi-typescript artifact", async () => {
+    const withTypes = makeContract({
+      name: "auth",
+      artifacts: [
+        makeArtifact({
+          tool: "openapi-typescript",
+          id: "ts-server",
+          outputDir: path.join(dir, "dist", "sdk", "auth", "ts-server"),
+        }),
+      ],
+    });
+    const withoutTypes = makeContract({
+      name: "catalog",
+      entrypoint: "/repo/specs/catalog/openapi.yaml",
+      entrypointRelative: path.join("specs", "catalog", "openapi.yaml"),
+      artifacts: [
+        makeArtifact({
+          tool: "openapi-generator",
+          id: "java-client",
+        }),
+      ],
+    });
+
+    const config = makeConfig({
+      rootDir: dir,
+      contracts: [withTypes, withoutTypes],
+    });
+
+    await syncRedoclyConfig(config);
+
+    const parsed = parseYaml(
+      await readFile(path.join(dir, "redocly.yaml"), "utf8"),
+    ) as {
+      apis: Record<string, { "x-openapi-ts"?: { output: string } }>;
+    };
+
+    expect(parsed.apis["auth@v1"]!["x-openapi-ts"]).toEqual({
+      output: path.join("dist", "sdk", "auth", "ts-server", "index.d.ts"),
+    });
+    expect(parsed.apis["catalog@v1"]!["x-openapi-ts"]).toBeUndefined();
+  });
+
+  it("includes every contract as its own '<name>@v1' api entry", async () => {
+    const config = makeConfig({
+      rootDir: dir,
+      contracts: [
+        makeContract({ name: "auth" }),
+        makeContract({
+          name: "catalog",
+          entrypoint: "/repo/specs/catalog/openapi.yaml",
+          entrypointRelative: path.join("specs", "catalog", "openapi.yaml"),
+        }),
+      ],
+    });
+
+    await syncRedoclyConfig(config);
+
+    const parsed = parseYaml(
+      await readFile(path.join(dir, "redocly.yaml"), "utf8"),
+    ) as { apis: Record<string, unknown> };
+
+    expect(Object.keys(parsed.apis).sort()).toEqual(["auth@v1", "catalog@v1"]);
+  });
+
+  it("rejects when redocly.base.yaml is missing", async () => {
+    const emptyDir = await mkdtemp(
+      path.join(tmpdir(), "seagull-redocly-empty-"),
+    );
+
+    try {
+      await expect(
+        syncRedoclyConfig(makeConfig({ rootDir: emptyDir })),
+      ).rejects.toThrow();
+    } finally {
+      await rm(emptyDir, { recursive: true, force: true });
+    }
+  });
+
+  it("overwrites a pre-existing redocly.yaml", async () => {
+    await writeFile(
+      path.join(dir, "redocly.yaml"),
+      "# stale content\napis: {}\n",
+    );
+
+    await syncRedoclyConfig(makeConfig({ rootDir: dir }));
+
+    const written = await readFile(path.join(dir, "redocly.yaml"), "utf8");
+
+    expect(written).not.toContain("stale content");
+    expect(written).toContain("auth@v1");
+  });
+});

package/src/redocly/redocly-sync.ts

@@ -31,7 +31,9 @@ interface RedoclyBase {
  */
 export async function syncRedoclyConfig(config: ResolvedConfig): Promise<void> {
   const basePath = path.join(config.rootDir, "redocly.base.yaml");
-  const base = parseYaml(await readFile(basePath, "utf8")) as RedoclyBase;
+  const base = parseYaml(await readFile(basePath, "utf8"), {
+    merge: true,
+  }) as RedoclyBase;
 
   const apis = Object.fromEntries(
     config.contracts.map((contract) => {