@octalmesh/seagull-core 0.0.2

package/src/generators/openapi-generator-cli/openapi-generator-cli.generator.ts

@@ -0,0 +1,122 @@
+import { mkdir } from "node:fs/promises";
+
+import type { ResolvedArtifact, SdkTool } from "../../config/types";
+import { Generator } from "../../generator/generator";
+import type { GenerateContext } from "../../generator/types";
+import { run } from "../../process/exec";
+import { resolveBinPath } from "../../process/resolve-bin";
+import { GoModulePatcher } from "./patchers/go-module.patcher";
+import { MavenPomPatcher } from "./patchers/maven.patcher";
+import { NpmPackagePatcher } from "./patchers/npm.patcher";
+import type { Patcher } from "./patchers/patcher";
+
+/**
+ * Additional-properties that are fully derivable from an artifact's own
+ * `package`/`goPackageName`/`maven` fields - conventional openapi-generator
+ * knobs (`npmName`, `groupId`, ...) that would otherwise have to be duplicated
+ * by hand in every generator's `additionalProperties:` block, in lockstep with
+ * those same fields. Tool-specific tuning that isn't derivable this way
+ * (`library=restclient`, `withGoMod`, ...) still lives in
+ * `additionalProperties:` and is layered on top of these.
+ *
+ * @param artifact - The resolved artifact to derive properties for.
+ * @returns The derived additional-properties, before the artifact's own
+ *          `additionalProperties` are layered on top.
+ */
+function deriveAdditionalProperties(
+  artifact: ResolvedArtifact,
+): Record<string, string> {
+  if (artifact.lang === "typescript" && artifact.package) {
+    return { npmName: artifact.package };
+  }
+
+  if (artifact.lang === "go" && artifact.goPackageName) {
+    return { packageName: artifact.goPackageName };
+  }
+
+  if (artifact.lang === "java" && artifact.maven) {
+    const invokerPackage = `${artifact.maven.groupId}.${artifact.kind}`;
+
+    return {
+      groupId: artifact.maven.groupId,
+      artifactId: artifact.maven.artifactId,
+      invokerPackage,
+      apiPackage: `${invokerPackage}.api`,
+      modelPackage: `${invokerPackage}.model`,
+    };
+  }
+
+  return {};
+}
+
+/**
+ * Renders an artifact's additional-properties (derived + explicit, explicit
+ * wins on conflicts) as the `key=value,key=value` string
+ * `openapi-generator-cli --additional-properties` expects.
+ *
+ * @param artifact - The resolved artifact.
+ * @returns The rendered `--additional-properties` value.
+ */
+function buildAdditionalPropertiesArg(artifact: ResolvedArtifact): string {
+  const merged = {
+    ...deriveAdditionalProperties(artifact),
+    ...artifact.additionalProperties,
+  };
+
+  return Object.entries(merged)
+    .map(([key, value]) => `${key}=${String(value)}`)
+    .join(",");
+}
+
+/**
+ * Wraps `openapi-generator-cli` - the single tool implementation behind every
+ * `-g` template (`typescript-fetch`, `go`, `go-server`, `java`, `spring`, ...),
+ * regardless of language. Language-specific output patching is delegated to a
+ * {@link Patcher}, selected by `artifact.lang`.
+ */
+export class OpenApiGeneratorCli extends Generator {
+  readonly tool: SdkTool = "openapi-generator";
+
+  private readonly patchers: Partial<
+    Record<ResolvedArtifact["lang"], Patcher>
+  > = {
+    go: new GoModulePatcher(),
+    typescript: new NpmPackagePatcher(),
+    java: new MavenPomPatcher(),
+  };
+
+  async generate(ctx: GenerateContext): Promise<void> {
+    const { artifact, rootDir, specInputPath } = ctx;
+
+    if (!artifact.generator) {
+      throw new Error(
+        `Artifact "${artifact.id}" uses tool "openapi-generator" but has no "generator" value`,
+      );
+    }
+
+    await mkdir(artifact.outputDir, { recursive: true });
+
+    const bin = resolveBinPath(
+      "@openapitools/openapi-generator-cli",
+      "openapi-generator-cli",
+    );
+
+    await run(
+      "node",
+      [
+        bin,
+        "generate",
+        "-i",
+        specInputPath,
+        "-g",
+        artifact.generator,
+        "-o",
+        artifact.outputDir,
+        `--additional-properties=${buildAdditionalPropertiesArg(artifact)}`,
+      ],
+      rootDir,
+    );
+
+    await this.patchers[artifact.lang]?.patch(ctx);
+  }
+}

package/src/generators/openapi-generator-cli/patchers/go-module.patcher.ts

@@ -0,0 +1,31 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { GenerateContext } from "../../../generator/types";
+import type { Patcher } from "./patcher";
+
+/**
+ * Patches the `go.mod` file in a generated Go SDK package to set the correct
+ * module path (`openapi-generator-cli` has no way to be told this up front for
+ * every template).
+ */
+export class GoModulePatcher implements Patcher {
+  async patch({ artifact }: GenerateContext): Promise<void> {
+    if (!artifact.goModule) {
+      return;
+    }
+
+    const moduleFile = path.join(artifact.outputDir, "go.mod");
+
+    try {
+      const contents = await readFile(moduleFile, "utf8");
+
+      await writeFile(
+        moduleFile,
+        contents.replace(/^module .*$/m, `module ${artifact.goModule}`),
+      );
+    } catch {
+      // go-server templates don't always emit go.mod
+    }
+  }
+}

package/src/generators/openapi-generator-cli/patchers/maven.patcher.ts

@@ -0,0 +1,44 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { GenerateContext } from "../../../generator/types";
+import type { Patcher } from "./patcher";
+
+/**
+ * Patches the `pom.xml` file in a generated Java SDK package to set the correct
+ * version and distribution management information for publishing, using the
+ * artifact's resolved `publishing:` config rather than a hardcoded registry.
+ */
+export class MavenPomPatcher implements Patcher {
+  async patch({ artifact, version }: GenerateContext): Promise<void> {
+    const pomFile = path.join(artifact.outputDir, "pom.xml");
+
+    try {
+      let pom = await readFile(pomFile, "utf8");
+
+      pom = pom.replace(
+        /<version>[^<]*<\/version>/,
+        `<version>${version}</version>`,
+      );
+
+      if (!pom.includes("<distributionManagement>")) {
+        pom = pom.replace(
+          "</project>",
+          [
+            "  <distributionManagement>",
+            "    <repository>",
+            `      <id>${artifact.publishing.mavenRepositoryId}</id>`,
+            `      <url>${artifact.publishing.mavenRepositoryUrl}</url>`,
+            "    </repository>",
+            "  </distributionManagement>",
+            "</project>",
+          ].join("\n"),
+        );
+      }
+
+      await writeFile(pomFile, pom);
+    } catch {
+      // pom.xml absent (e.g. Gradle build selected)
+    }
+  }
+}

package/src/generators/openapi-generator-cli/patchers/npm.patcher.ts

@@ -0,0 +1,32 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { GenerateContext } from "../../../generator/types";
+import type { Patcher } from "./patcher";
+
+/**
+ * Patches the `package.json` file in a generated TypeScript SDK package (the
+ * client target - `openapi-generator-cli` produces its own `package.json`, this
+ * just fills in the version and publishing metadata) to set the correct version
+ * and repository information, using the artifact's resolved `publishing:`
+ * config rather than a hardcoded registry.
+ */
+export class NpmPackagePatcher implements Patcher {
+  async patch({ artifact, version }: GenerateContext): Promise<void> {
+    const pkgFile = path.join(artifact.outputDir, "package.json");
+    const pkgData = await readFile(pkgFile, "utf8");
+    const pkg = JSON.parse(pkgData) as Record<string, unknown>;
+
+    pkg.version = version;
+    pkg.repository = {
+      type: "git",
+      url: `git+${artifact.publishing.repositoryUrl}.git`,
+    };
+    pkg.publishConfig = {
+      registry: artifact.publishing.npmRegistry,
+      access: artifact.publishing.npmAccess,
+    };
+
+    await writeFile(pkgFile, JSON.stringify(pkg, null, 2));
+  }
+}

package/src/generators/openapi-generator-cli/patchers/patcher.ts

@@ -0,0 +1,17 @@
+import type { GenerateContext } from "../../../generator/types";
+
+/**
+ * A strategy that post-processes an `openapi-generator-cli` output directory
+ * after generation - patching in the version, repository metadata, and
+ * publishing config that the generator itself doesn't know about. One
+ * implementation per language (`npm`, `go-module`, `maven`), selected by
+ * openapi-generator-cli based on `artifact.lang`, so the base generator class
+ * stays language-agnostic.
+ */
+export interface Patcher {
+  /**
+   * @param ctx - The generate context (contract, artifact, version, ...) for
+   *              the artifact that was just generated.
+   */
+  patch(ctx: GenerateContext): Promise<void>;
+}

package/src/generators/openapi-typescript/index.ts

@@ -0,0 +1 @@
+export { OpenApiTypescriptGenerator } from "./openapi-typescript.generator";

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

@@ -0,0 +1,62 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { SdkTool } from "../../config/types";
+import { Generator } from "../../generator/generator";
+import type { GenerateContext, PrepareContext } from "../../generator/types";
+import { run } from "../../process/exec";
+import { resolveBinPath } from "../../process/resolve-bin";
+
+/**
+ * Wraps `openapi-typescript`. Unlike `openapi-generator-cli`, it isn't invoked
+ * once per artifact - it reads `redocly.yaml`'s `apis:` map (kept in sync with
+ * the CLI config by `core/redocly/redocly-sync.ts`) and writes every contract's
+ * `index.d.ts` to its configured `x-openapi-ts.output` path in a single run,
+ * so that single global invocation happens once in {@link prepare}.
+ * {@link generate} then only has to write each artifact's package.json` -
+ * `openapi-typescript` emits `index.d.ts` alone, with no package manifest of
+ * its own to patch.
+ */
+export class OpenApiTypescriptGenerator extends Generator {
+  readonly tool: SdkTool = "openapi-typescript";
+
+  override async prepare({ rootDir, entries }: PrepareContext): Promise<void> {
+    await Promise.all(
+      entries.map((entry) =>
+        mkdir(entry.artifact.outputDir, { recursive: true }),
+      ),
+    );
+
+    const bin = resolveBinPath("openapi-typescript", "openapi-typescript");
+
+    await run("node", [bin], rootDir);
+  }
+
+  async generate({
+    contract,
+    artifact,
+    version,
+  }: GenerateContext): Promise<void> {
+    const pkg = {
+      name: artifact.package,
+      version,
+      description: `Types-only OpenAPI contract for the ${contract.name} service.`,
+      types: "./index.d.ts",
+      files: ["index.d.ts"],
+      license: "MIT",
+      repository: {
+        type: "git",
+        url: `git+${artifact.publishing.repositoryUrl}.git`,
+      },
+      publishConfig: {
+        registry: artifact.publishing.npmRegistry,
+        access: artifact.publishing.npmAccess,
+      },
+    };
+
+    await writeFile(
+      path.join(artifact.outputDir, "package.json"),
+      JSON.stringify(pkg, null, 2),
+    );
+  }
+}

package/src/git/git.ts

@@ -0,0 +1,118 @@
+import { spawnSync } from "node:child_process";
+
+/**
+ * The result of executing a git command.
+ *
+ * @see {@link git} - The function that executes the git command.
+ */
+export interface GitResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Execute a git command in a given working directory and return the result.
+ *
+ * @param args - The command-line arguments to pass to the git command.
+ * @param cwd  - The working directory in which to execute the git command.
+ * @returns The result of the git command.
+ *
+ * @see {@link GitResult} - The result of executing the git command.
+ */
+export function git(args: string[], cwd: string): GitResult {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+
+  return {
+    status: result.status ?? 1,
+    stdout: (result.stdout ?? "").trim(),
+    stderr: (result.stderr ?? "").trim(),
+  };
+}
+
+/**
+ * Check if a remote branch exists in the given repository.
+ *
+ * @param repoRoot - The root directory of the repository.
+ * @param branch   - The name of the branch to check.
+ * @returns Whether the remote branch exists (true) or not (false).
+ */
+export function remoteBranchExists(repoRoot: string, branch: string): boolean {
+  return (
+    git(["ls-remote", "--exit-code", "--heads", "origin", branch], repoRoot)
+      .status === 0
+  );
+}
+
+/**
+ * Check if a remote tag exists in the given repository.
+ *
+ * @param repoRoot - The root directory of the repository.
+ * @param tag      - The name of the tag to check.
+ * @returns Whether the remote tag exists (true) or not (false).
+ */
+export function tagExists(repoRoot: string, tag: string): boolean {
+  return (
+    git(["ls-remote", "--exit-code", "--tags", "origin", tag], repoRoot)
+      .status === 0
+  );
+}
+
+/**
+ * Fetch a single tag's object from origin into the local repo, without
+ * fetching the rest of history/tags.
+ *
+ * @param repoRoot - The root directory of the repository.
+ * @param tag      - The name of the tag to fetch.
+ * @returns The result of the underlying `git fetch` command.
+ */
+function fetchTag(repoRoot: string, tag: string): GitResult {
+  return git(
+    ["fetch", "origin", `refs/tags/${tag}:refs/tags/${tag}`, "--force"],
+    repoRoot,
+  );
+}
+
+/**
+ * Read a single file's content as it existed at a given git tag, without
+ * checking out a worktree.
+ *
+ * Returns `null` (rather than throwing) both when the tag can't be fetched and
+ * when the tag exists but doesn't contain the requested file - the latter is
+ * expected for tags published before that file was introduced, and callers
+ * should treat "unknown" the same as "no mismatch to report".
+ *
+ * @param repoRoot - The root directory of the repository.
+ * @param tag      - The tag to read the file from.
+ * @param filePath - The path of the file within that tag's tree.
+ * @returns The file's content, or `null` if it couldn't be read.
+ */
+export function readFileAtTag(
+  repoRoot: string,
+  tag: string,
+  filePath: string,
+): string | null {
+  const fetch = fetchTag(repoRoot, tag);
+
+  if (fetch.status !== 0) {
+    return null;
+  }
+
+  const show = git(["show", `${tag}:${filePath}`], repoRoot);
+
+  return show.status === 0 ? show.stdout.trim() : null;
+}
+
+/**
+ * Require that a git command succeeded, throwing an error with the given
+ * message if it did not.
+ *
+ * @param result  - The result of the git command to check.
+ * @param message - The error message to throw if the command failed.
+ * @throws Error if the git command failed (non-zero exit code).
+ */
+export function requireOk(result: GitResult, message: string): void {
+  if (result.status !== 0) {
+    throw new Error(`${message}: ${result.stderr || result.stdout}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+export { CONFIG_SCHEMA_VERSION } from "./config/schema";
+export { loadConfig } from "./config/loader";
+export { renderArtifactTag } from "./config/publishing";
+export {
+  CONFIG_FILENAMES,
+  resolveConfigPath,
+} from "./config/resolve-config-file";
+export type {
+  ResolvedArtifact,
+  ResolvedArtifactEntry,
+  ResolvedConfig,
+  ResolvedContract,
+  ResolvedPublishing,
+  SdkKind,
+  SdkLang,
+  SdkTool,
+  VarsTree,
+} from "./config/types";
+
+export { Generator } from "./generator/generator";
+export { GeneratorRegistry } from "./generator/registry";
+export type { GenerateContext, PrepareContext } from "./generator/types";
+
+export { run, runSync } from "./process/exec";
+export { resolveBinPath } from "./process/resolve-bin";
+
+export {
+  git,
+  readFileAtTag,
+  remoteBranchExists,
+  requireOk,
+  tagExists,
+} from "./git/git";
+export type { GitResult } from "./git/git";
+
+export { hashSpec, resolveVersion } from "./version/version";
+export type { BundledSpec } from "./version/version";
+
+export { renderReadme } from "./readme/readme-renderer";
+export type { RenderReadmeArgs } from "./readme/readme-renderer";
+
+export { syncRedoclyConfig } from "./redocly/redocly-sync";
+
+export { OpenApiGeneratorCli } from "./generators/openapi-generator-cli";
+export { OpenApiTypescriptGenerator } from "./generators/openapi-typescript";

package/src/process/exec.ts

@@ -0,0 +1,53 @@
+import { spawn, spawnSync } from "node:child_process";
+
+/**
+ * Runs a command to completion, streaming its stdio straight through
+ * (`inherit`), and rejects if it exits non-zero.
+ *
+ * This is the async counterpart used for the "one long-running tool" commands
+ * (`redocly`, `openapi-generator-cli`, `openapi-typescript`); for short
+ * synchronous calls (git plumbing, `npm publish`/`mvn deploy`), see
+ * {@link runSync}.
+ *
+ * @param command - The executable to run.
+ * @param args    - Arguments to pass to it.
+ * @param cwd     - The working directory to run it in.
+ * @returns A promise that resolves on exit code 0, and rejects otherwise.
+ */
+export function run(
+  command: string,
+  args: string[],
+  cwd: string,
+): Promise<void> {
+  return new Promise<void>((resolvePromise, reject) => {
+    const child = spawn(command, args, { cwd, stdio: "inherit", shell: true });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolvePromise();
+        return;
+      }
+
+      reject(new Error(`${command} ${args.join(" ")} exited with ${code}`));
+    });
+  });
+}
+
+/**
+ * Runs a command to completion synchronously, streaming its stdio straight
+ * through (`inherit`).
+ *
+ * @param command - The executable to run.
+ * @param args    - Arguments to pass to it.
+ * @param cwd     - The working directory to run it in.
+ * @returns The exit status (0 on success).
+ */
+export function runSync(command: string, args: string[], cwd: string): number {
+  const result = spawnSync(command, args, {
+    cwd,
+    stdio: "inherit",
+    shell: true,
+  });
+
+  return result.status ?? 1;
+}

package/src/process/resolve-bin.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Resolves the absolute path to an installed npm package's own CLI entrypoint
+ * script, using Node's standard module resolution algorithm - so it works the
+ * same way regardless of which package manager (npm/pnpm/yarn) installed CLI
+ * and its dependencies, or how deeply they get hoisted. Shelling out to
+ * `pnpm exec`/`npx` instead would assume a specific package manager and a
+ * particular install layout, which doesn't hold once CLI is just another
+ * dependency in someone else's project.
+ *
+ * @param pkgName - The npm package name, e.g. `"@org/cli"`.
+ * @param binName - Which entry to resolve from that package's `bin` field.
+ *                  Defaults to the package's own unscoped name.
+ * @returns The absolute path to the resolved bin script.
+ * @throws Error if the package or the requested bin entry can't be found.
+ */
+export function resolveBinPath(pkgName: string, binName?: string): string {
+  const pkgJsonPath = require.resolve(`${pkgName}/package.json`);
+  const pkgDir = path.dirname(pkgJsonPath);
+  const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as {
+    name: string;
+    bin?: string | Record<string, string>;
+  };
+
+  const key = binName ?? pkg.name.split("/").pop()!;
+  const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.[key];
+
+  if (!bin) {
+    throw new Error(
+      `Could not resolve a "${key}" bin entry for package "${pkgName}" - ` +
+        `is it installed, and does it expose that bin?`,
+    );
+  }
+
+  return path.join(pkgDir, bin);
+}