@octalmesh/seagull-cli 0.0.2 → 0.1.1

package/src/commands/clean.test.ts

@@ -0,0 +1,67 @@
+import { mkdir, mkdtemp, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { MockInstance } from "vitest";
+
+import { makeConfig } from "../test-support/fixtures";
+import { cleanCommand } from "./clean";
+
+describe("cleanCommand", () => {
+  let dir: string;
+  let logSpy: MockInstance;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), "seagull-clean-"));
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+    logSpy.mockRestore();
+  });
+
+  it("removes the dist directory recursively", async () => {
+    const config = makeConfig(dir);
+
+    await mkdir(path.join(config.paths.dist, "sdk", "auth"), {
+      recursive: true,
+    });
+    await writeFile(
+      path.join(config.paths.dist, "sdk", "auth", "file.txt"),
+      "hi",
+    );
+
+    await cleanCommand(config);
+
+    await expect(stat(config.paths.dist)).rejects.toThrow();
+  });
+
+  it("does not throw when dist doesn't exist (force: true)", async () => {
+    await expect(cleanCommand(makeConfig(dir))).resolves.toBeUndefined();
+  });
+
+  it("logs the cleaned path", async () => {
+    const config = makeConfig(dir);
+
+    await mkdir(config.paths.dist, { recursive: true });
+
+    await cleanCommand(config);
+
+    expect(logSpy).toHaveBeenCalledWith(`Cleaned ${config.paths.dist}`);
+  });
+
+  it("only removes 'dist', leaving sibling files in rootDir untouched", async () => {
+    const config = makeConfig(dir);
+
+    await mkdir(config.paths.dist, { recursive: true });
+    await writeFile(path.join(dir, "seagull.yaml"), "configVersion: 1");
+
+    await cleanCommand(config);
+
+    await expect(stat(path.join(dir, "seagull.yaml"))).resolves.toMatchObject(
+      {},
+    );
+  });
+});

package/src/commands/generate-docs.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { makeConfig } from "../test-support/fixtures";
+
+const generateDocsSiteMock = vi.fn((..._args: unknown[]) => Promise.resolve());
+
+vi.mock("@octalmesh/seagull-docs", () => ({
+  generateDocsSite: (...a: unknown[]) => generateDocsSiteMock(...a),
+}));
+
+const { generateDocsCommand } = await import("./generate-docs");
+
+describe("generateDocsCommand", () => {
+  it("delegates straight to generateDocsSite with the resolved config", async () => {
+    const config = makeConfig("/repo");
+
+    await generateDocsCommand(config);
+
+    expect(generateDocsSiteMock).toHaveBeenCalledTimes(1);
+    expect(generateDocsSiteMock).toHaveBeenCalledWith(config);
+  });
+
+  it("propagates errors from generateDocsSite", async () => {
+    generateDocsSiteMock.mockRejectedValueOnce(new Error("boom"));
+
+    await expect(generateDocsCommand(makeConfig("/repo"))).rejects.toThrow(
+      "boom",
+    );
+  });
+});

package/src/commands/generate-sdk.test.ts

@@ -0,0 +1,382 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import type { GenerateContext } from "@octalmesh/seagull-core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { MockInstance } from "vitest";
+
+import {
+  makeArtifact,
+  makeConfig,
+  makeContract,
+} from "../test-support/fixtures";
+
+const syncRedoclyConfigMock = vi.fn((..._args: unknown[]) => Promise.resolve());
+const resolveVersionMock = vi.fn((..._args: unknown[]) => "1.0.0");
+const hashSpecMock = vi.fn((..._args: unknown[]) => "some-hash");
+const renderReadmeMock = vi.fn((..._args: unknown[]) =>
+  Promise.resolve("# readme\n"),
+);
+
+const openApiGeneratorPrepare = vi.fn((..._args: unknown[]) =>
+  Promise.resolve(),
+);
+const openApiGeneratorGenerate = vi.fn(async (ctx: GenerateContext) => {
+  await mkdir(ctx.artifact.outputDir, { recursive: true });
+});
+const openApiTypescriptPrepare = vi.fn((..._args: unknown[]) =>
+  Promise.resolve(),
+);
+const openApiTypescriptGenerate = vi.fn(async (ctx: GenerateContext) => {
+  await mkdir(ctx.artifact.outputDir, { recursive: true });
+});
+
+vi.mock("@octalmesh/seagull-core", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("@octalmesh/seagull-core")>();
+
+  class FakeOpenApiGeneratorCli {
+    readonly tool = "openapi-generator";
+    prepare = openApiGeneratorPrepare;
+    generate = openApiGeneratorGenerate;
+  }
+
+  class FakeOpenApiTypescriptGenerator {
+    readonly tool = "openapi-typescript";
+    prepare = openApiTypescriptPrepare;
+    generate = openApiTypescriptGenerate;
+  }
+
+  return {
+    ...actual,
+    syncRedoclyConfig: (...a: unknown[]) => syncRedoclyConfigMock(...a),
+    resolveVersion: (...a: unknown[]) => resolveVersionMock(...a),
+    hashSpec: (...a: unknown[]) => hashSpecMock(...a),
+    renderReadme: (...a: unknown[]) => renderReadmeMock(...a),
+    OpenApiGeneratorCli: FakeOpenApiGeneratorCli,
+    OpenApiTypescriptGenerator: FakeOpenApiTypescriptGenerator,
+  };
+});
+
+const { generateSdkCommand } = await import("./generate-sdk");
+
+describe("generateSdkCommand", () => {
+  let dir: string;
+  let logSpy: MockInstance;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), "seagull-gensdk-"));
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    syncRedoclyConfigMock.mockClear();
+    resolveVersionMock.mockClear().mockReturnValue("1.0.0");
+    hashSpecMock.mockClear().mockReturnValue("some-hash");
+    renderReadmeMock.mockClear().mockResolvedValue("# readme\n");
+    openApiGeneratorPrepare.mockClear();
+    openApiGeneratorGenerate.mockClear();
+    openApiTypescriptPrepare.mockClear();
+    openApiTypescriptGenerate.mockClear();
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+    logSpy.mockRestore();
+  });
+
+  async function writeSpec(
+    specsDir: string,
+    name: string,
+    raw = '{"info":{"version":"1.0.0"}}',
+  ): Promise<void> {
+    await mkdir(specsDir, { recursive: true });
+    await writeFile(path.join(specsDir, `${name}.json`), raw);
+  }
+
+  it("syncs redocly.yaml before generating", async () => {
+    const config = makeConfig(dir, { contracts: [] });
+
+    await writeSpec(config.paths.specs, "auth");
+
+    await generateSdkCommand(config);
+
+    expect(syncRedoclyConfigMock).toHaveBeenCalledOnce();
+  });
+
+  it("recreates the sdk output directory", async () => {
+    const config = makeConfig(dir, { contracts: [] });
+
+    await mkdir(config.paths.sdk, { recursive: true });
+    await writeFile(path.join(config.paths.sdk, "stale.txt"), "x");
+
+    await generateSdkCommand(config);
+
+    await expect(
+      readFile(path.join(config.paths.sdk, "stale.txt"), "utf8"),
+    ).rejects.toThrow();
+  });
+
+  it("calls prepare() once per distinct tool present among the artifacts, with only its own entries", async () => {
+    const config = makeConfig(dir, {
+      contracts: [
+        makeContract({
+          name: "auth",
+          artifacts: [
+            makeArtifact({
+              id: "ts-client",
+              tool: "openapi-generator",
+              outputDir: path.join(dir, "dist", "sdk", "auth", "ts-client"),
+            }),
+            makeArtifact({
+              id: "ts-server",
+              tool: "openapi-typescript",
+              outputDir: path.join(dir, "dist", "sdk", "auth", "ts-server"),
+            }),
+          ],
+        }),
+      ],
+    });
+
+    await writeSpec(config.paths.specs, "auth");
+
+    await generateSdkCommand(config);
+
+    expect(openApiGeneratorPrepare).toHaveBeenCalledOnce();
+    expect(openApiGeneratorPrepare.mock.calls[0]![0]).toMatchObject({
+      rootDir: config.rootDir,
+      entries: [{ artifact: { id: "ts-client" } }],
+    });
+
+    expect(openApiTypescriptPrepare).toHaveBeenCalledOnce();
+    expect(openApiTypescriptPrepare.mock.calls[0]![0]).toMatchObject({
+      rootDir: config.rootDir,
+      entries: [{ artifact: { id: "ts-server" } }],
+    });
+  });
+
+  it("calls generate() once per artifact, with the right generator dispatched by tool", async () => {
+    const config = makeConfig(dir, {
+      contracts: [
+        makeContract({
+          name: "auth",
+          artifacts: [
+            makeArtifact({
+              id: "ts-client",
+              tool: "openapi-generator",
+              outputDir: path.join(dir, "dist", "sdk", "auth", "ts-client"),
+            }),
+          ],
+        }),
+      ],
+    });
+
+    await writeSpec(config.paths.specs, "auth");
+    await mkdir(path.dirname(config.contracts[0]!.artifacts[0]!.outputDir), {
+      recursive: true,
+    });
+    await mkdir(config.contracts[0]!.artifacts[0]!.outputDir, {
+      recursive: true,
+    });
+
+    await generateSdkCommand(config);
+
+    expect(openApiGeneratorGenerate).toHaveBeenCalledOnce();
+    expect(openApiTypescriptGenerate).not.toHaveBeenCalled();
+
+    const ctx = openApiGeneratorGenerate.mock.calls[0]![0];
+
+    expect(ctx).toMatchObject({
+      rootDir: config.rootDir,
+      version: "1.0.0",
+      specInputPath: path.join(config.paths.specs, "auth.json"),
+    });
+  });
+
+  it("resolves version/hash from the bundled spec once per contract, caching across its artifacts", async () => {
+    const config = makeConfig(dir, {
+      contracts: [
+        makeContract({
+          name: "auth",
+          artifacts: [
+            makeArtifact({
+              id: "ts-client",
+              tool: "openapi-generator",
+              outputDir: path.join(dir, "dist", "sdk", "auth", "ts-client"),
+            }),
+            makeArtifact({
+              id: "ts-server",
+              tool: "openapi-typescript",
+              outputDir: path.join(dir, "dist", "sdk", "auth", "ts-server"),
+            }),
+          ],
+        }),
+      ],
+    });
+
+    await writeSpec(config.paths.specs, "auth", '{"info":{"version":"2.0.0"}}');
+    for (const artifact of config.allArtifacts) {
+      await mkdir(artifact.artifact.outputDir, { recursive: true });
+    }
+
+    await generateSdkCommand(config);
+
+    expect(resolveVersionMock).toHaveBeenCalledTimes(1);
+    expect(hashSpecMock).toHaveBeenCalledTimes(1);
+    expect(resolveVersionMock).toHaveBeenCalledWith(
+      { info: { version: "2.0.0" } },
+      "auth",
+    );
+  });
+
+  it("writes VERSION, SPEC_HASH, and README.md into each artifact's outputDir", async () => {
+    const outputDir = path.join(dir, "dist", "sdk", "auth", "ts-client");
+    const config = makeConfig(dir, {
+      contracts: [
+        makeContract({
+          name: "auth",
+          artifacts: [makeArtifact({ id: "ts-client", outputDir })],
+        }),
+      ],
+    });
+
+    resolveVersionMock.mockReturnValue("3.4.5");
+    hashSpecMock.mockReturnValue("abc123");
+    renderReadmeMock.mockResolvedValue("# Hello\n");
+
+    await writeSpec(config.paths.specs, "auth");
+    await mkdir(outputDir, { recursive: true });
+
+    await generateSdkCommand(config);
+
+    await expect(
+      readFile(path.join(outputDir, "VERSION"), "utf8"),
+    ).resolves.toBe("3.4.5\n");
+    await expect(
+      readFile(path.join(outputDir, "SPEC_HASH"), "utf8"),
+    ).resolves.toBe("abc123\n");
+    await expect(
+      readFile(path.join(outputDir, "README.md"), "utf8"),
+    ).resolves.toBe("# Hello\n");
+  });
+
+  it("passes contract/artifact/version/vars through to renderReadme", async () => {
+    const outputDir = path.join(dir, "dist", "sdk", "auth", "ts-client");
+    const config = makeConfig(dir, {
+      vars: { org: "octalmesh" },
+      contracts: [
+        makeContract({
+          name: "auth",
+          artifacts: [makeArtifact({ id: "ts-client", outputDir })],
+        }),
+      ],
+    });
+
+    await writeSpec(config.paths.specs, "auth");
+    await mkdir(outputDir, { recursive: true });
+
+    await generateSdkCommand(config);
+
+    expect(renderReadmeMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        version: "1.0.0",
+        vars: { org: "octalmesh" },
+      }),
+    );
+  });
+
+  it("logs a summary listing each contract's resolved version", async () => {
+    const outputDir = path.join(dir, "dist", "sdk", "auth", "ts-client");
+    const config = makeConfig(dir, {
+      contracts: [
+        makeContract({
+          name: "auth",
+          artifacts: [makeArtifact({ id: "ts-client", outputDir })],
+        }),
+      ],
+    });
+
+    resolveVersionMock.mockReturnValue("9.9.9");
+
+    await writeSpec(config.paths.specs, "auth");
+    await mkdir(outputDir, { recursive: true });
+
+    await generateSdkCommand(config);
+
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("auth@9.9.9"));
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("Generated 1"));
+  });
+
+  it("reads <specs>/<name>.yaml and parses it as YAML when paths.specFormat is 'yaml'", async () => {
+    const outputDir = path.join(dir, "dist", "sdk", "auth", "ts-client");
+    const config = makeConfig(dir, {
+      contracts: [
+        makeContract({
+          name: "auth",
+          artifacts: [makeArtifact({ id: "ts-client", outputDir })],
+        }),
+      ],
+    });
+
+    config.paths.specFormat = ["yaml"];
+
+    await mkdir(config.paths.specs, { recursive: true });
+    await writeFile(
+      path.join(config.paths.specs, "auth.yaml"),
+      'info:\n  version: "7.0.0"\n',
+    );
+    await mkdir(outputDir, { recursive: true });
+
+    await generateSdkCommand(config);
+
+    expect(resolveVersionMock).toHaveBeenCalledWith(
+      { info: { version: "7.0.0" } },
+      "auth",
+    );
+
+    const ctx = openApiGeneratorGenerate.mock.calls[0]![0];
+
+    expect(ctx).toMatchObject({
+      specInputPath: path.join(config.paths.specs, "auth.yaml"),
+    });
+  });
+
+  it("uses the first entry in paths.specFormat as the primary format when several are configured", async () => {
+    const outputDir = path.join(dir, "dist", "sdk", "auth", "ts-client");
+    const config = makeConfig(dir, {
+      contracts: [
+        makeContract({
+          name: "auth",
+          artifacts: [makeArtifact({ id: "ts-client", outputDir })],
+        }),
+      ],
+    });
+
+    config.paths.specFormat = ["yaml", "json"];
+
+    await mkdir(config.paths.specs, { recursive: true });
+    // Both bundled formats exist on disk (as a real `bundle` run would leave
+    // them) - only the primary (first) one, "yaml", should actually get read.
+    await writeFile(
+      path.join(config.paths.specs, "auth.yaml"),
+      'info:\n  version: "1.2.3"\n',
+    );
+    await writeFile(
+      path.join(config.paths.specs, "auth.json"),
+      '{"info":{"version":"9.9.9"}}',
+    );
+    await mkdir(outputDir, { recursive: true });
+
+    await generateSdkCommand(config);
+
+    expect(resolveVersionMock).toHaveBeenCalledWith(
+      { info: { version: "1.2.3" } },
+      "auth",
+    );
+
+    const ctx = openApiGeneratorGenerate.mock.calls[0]![0];
+
+    expect(ctx).toMatchObject({
+      specInputPath: path.join(config.paths.specs, "auth.yaml"),
+    });
+  });
+});

package/src/commands/generate-sdk.ts

@@ -8,8 +8,11 @@ import {
   OpenApiTypescriptGenerator,
   type ResolvedConfig,
   hashSpec,
+  parseBundledSpec,
+  primarySpecFormat,
   renderReadme,
   resolveVersion,
+  specFilename,
   syncRedoclyConfig,
 } from "@octalmesh/seagull-core";
 
@@ -48,6 +51,7 @@ export async function generateSdkCommand(
   }
 
   const versionCache = new Map<string, VersionInfo>();
+  const specFormat = primarySpecFormat(config.paths.specFormat);
 
   async function getVersionInfo(contractName: string): Promise<VersionInfo> {
     const cached = versionCache.get(contractName);
@@ -56,9 +60,12 @@ export async function generateSdkCommand(
       return cached;
     }
 
-    const specPath = path.join(config.paths.specs, `${contractName}.json`);
+    const specPath = path.join(
+      config.paths.specs,
+      specFilename(contractName, specFormat),
+    );
     const raw = await readFile(specPath, "utf8");
-    const spec = JSON.parse(raw) as BundledSpec;
+    const spec = parseBundledSpec(raw, specFormat) as BundledSpec;
 
     const info: VersionInfo = {
       version: resolveVersion(spec, contractName),
@@ -79,8 +86,10 @@ export async function generateSdkCommand(
       contract,
       artifact,
       version,
-      github: config.github,
-      specInputPath: path.join(config.paths.specs, `${contract.name}.json`),
+      specInputPath: path.join(
+        config.paths.specs,
+        specFilename(contract.name, specFormat),
+      ),
     });
 
     await writeFile(path.join(artifact.outputDir, "VERSION"), `${version}\n`);
@@ -91,7 +100,6 @@ export async function generateSdkCommand(
         contract,
         artifact,
         version,
-        github: config.github,
         vars: config.vars,
       }),
     );

package/src/commands/lint.test.ts

@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { MockInstance } from "vitest";
+
+import { makeConfig, makeContract } from "../test-support/fixtures";
+
+const runSyncMock = vi.fn((..._args: unknown[]) => 0);
+const resolveBinPathMock = vi.fn(
+  (..._args: unknown[]) => "/fake/bin/redocly.js",
+);
+const syncRedoclyConfigMock = vi.fn((..._args: unknown[]) => Promise.resolve());
+
+vi.mock("@octalmesh/seagull-core", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("@octalmesh/seagull-core")>();
+
+  return {
+    ...actual,
+    runSync: (...a: unknown[]) => runSyncMock(...a),
+    resolveBinPath: (...a: unknown[]) => resolveBinPathMock(...a),
+    syncRedoclyConfig: (...a: unknown[]) => syncRedoclyConfigMock(...a),
+  };
+});
+
+const { lintCommand } = await import("./lint");
+
+describe("lintCommand", () => {
+  let logSpy: MockInstance;
+  const originalExitCode = process.exitCode;
+
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    runSyncMock.mockClear().mockReturnValue(0);
+    resolveBinPathMock.mockClear();
+    syncRedoclyConfigMock.mockClear();
+    process.exitCode = undefined;
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+    process.exitCode = originalExitCode;
+  });
+
+  it("syncs redocly.yaml before linting", async () => {
+    await lintCommand(makeConfig("/repo", { contracts: [] }));
+
+    expect(syncRedoclyConfigMock).toHaveBeenCalledOnce();
+  });
+
+  it("runs 'redocly lint <entrypoint>' once per contract via runSync", async () => {
+    const config = makeConfig("/repo", {
+      contracts: [
+        makeContract({
+          name: "auth",
+          entrypoint: "/repo/specs/auth/openapi.yaml",
+        }),
+        makeContract({
+          name: "catalog",
+          entrypoint: "/repo/specs/catalog/openapi.yaml",
+        }),
+      ],
+    });
+
+    await lintCommand(config);
+
+    expect(runSyncMock).toHaveBeenCalledTimes(2);
+    expect(runSyncMock).toHaveBeenNthCalledWith(
+      1,
+      "node",
+      ["/fake/bin/redocly.js", "lint", "/repo/specs/auth/openapi.yaml"],
+      config.rootDir,
+    );
+    expect(runSyncMock).toHaveBeenNthCalledWith(
+      2,
+      "node",
+      ["/fake/bin/redocly.js", "lint", "/repo/specs/catalog/openapi.yaml"],
+      config.rootDir,
+    );
+  });
+
+  it("leaves process.exitCode unset when every contract lints cleanly", async () => {
+    runSyncMock.mockReturnValue(0);
+
+    await lintCommand(
+      makeConfig("/repo", {
+        contracts: [
+          makeContract({ name: "auth" }),
+          makeContract({ name: "catalog" }),
+        ],
+      }),
+    );
+
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it("sets process.exitCode = 1 if any single contract fails", async () => {
+    runSyncMock.mockReturnValueOnce(0).mockReturnValueOnce(1);
+
+    await lintCommand(
+      makeConfig("/repo", {
+        contracts: [
+          makeContract({ name: "auth" }),
+          makeContract({ name: "catalog" }),
+        ],
+      }),
+    );
+
+    expect(process.exitCode).toBe(1);
+  });
+
+  it("keeps checking every contract even after an earlier one fails", async () => {
+    runSyncMock.mockReturnValueOnce(1).mockReturnValueOnce(0);
+
+    await lintCommand(
+      makeConfig("/repo", {
+        contracts: [
+          makeContract({ name: "auth" }),
+          makeContract({ name: "catalog" }),
+        ],
+      }),
+    );
+
+    expect(runSyncMock).toHaveBeenCalledTimes(2);
+    expect(process.exitCode).toBe(1);
+  });
+});