@octalmesh/seagull-core 0.0.2

package/src/config/schema.ts

@@ -0,0 +1,270 @@
+import { z } from "zod";
+
+/**
+ * The seagull config *schema* version - not the npm package's own version.
+ * Bumped only when the shape of `seagull.yaml` changes in a breaking way, so
+ * older configs fail with a clear "this config targets schema vN, seagull
+ * expects vM" error instead of a confusing validation failure on some
+ * unrelated field once the schema moves on.
+ */
+export const CONFIG_SCHEMA_VERSION = 1;
+
+/**
+ * A free-form tree of leaf values, used for the `vars:` block in the CLI config.
+ * Nest however deep is useful - every leaf becomes addressable as
+ * `{vars.<dot.path>}` in templated fields.
+ */
+export interface VarsTree {
+  [key: string]: string | number | boolean | VarsTree;
+}
+
+export const varsTreeSchema: z.ZodType<VarsTree> = z.lazy(() =>
+  z.record(
+    z.string(),
+    z.union([z.string(), z.number(), z.boolean(), varsTreeSchema]),
+  ),
+);
+
+export const githubSchema = z.object({
+  owner: z.string().min(1),
+  repo: z.string().min(1),
+});
+
+export const pathsSchema = z.object({
+  dist: z.string().min(1).default("dist"),
+  specs: z.string().min(1).optional(),
+  docs: z.string().min(1).optional(),
+  sdk: z.string().min(1).optional(),
+});
+
+export const docsSchema = z.object({
+  server: z.object({
+    host: z.string().min(1),
+    port: z.number().int().positive(),
+  }),
+  metadata: z.object({
+    title: z.string().min(1),
+    description: z.string().min(1),
+    favicon: z.string().min(1),
+    baseServerUrl: z.string().min(1),
+  }),
+});
+
+export const sdkToolSchema = z.enum([
+  "openapi-generator",
+  "openapi-typescript",
+]);
+export const sdkLangSchema = z.enum(["typescript", "go", "java"]);
+export const sdkKindSchema = z.enum(["client", "server"]);
+
+/**
+ * `-g`/`--additional-properties` values: openapi-generator accepts strings,
+ * numbers and booleans, all rendered as `key=value` on the CLI.
+ */
+export const additionalPropertiesSchema = z
+  .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+  .default({});
+
+export const mavenCoordsSchema = z.object({
+  groupId: z.string().min(1),
+  artifactId: z.string().min(1),
+});
+
+/**
+ * Publishing conventions - git branch/tag naming, and where registry-backed
+ * artifacts (npm, Maven) get pushed. Every field is a template supporting the
+ * usual `{...}` placeholders (`{service}`, `{id}`, `{github.*}`, `{vars.*}`,
+ * and for `tag` only, also `{version}`).
+ *
+ * Required at the root level - seagull has no built-in opinion on branch/tag
+ * naming or which registry to use, so this has to come from the config, not
+ * from a hardcoded convention baked into the tool. Per-generator
+ * (`generators.<id>.publishing`) and per-contract-artifact
+ * (`artifacts[].overrides.publishing`) blocks only need to override the
+ * fields that differ for that generator/artifact - see
+ * {@link publishingOverrideSchema}.
+ */
+export const publishingSchema = z.object({
+  /**
+   * Git branch artifacts publish to. Resolved once, at config-load time -
+   * no `{version}` available here, e.g. `"sdk/svc-{service}/{id}"`.
+   */
+  branch: z.string().min(1),
+  /**
+   * Git tag artifacts are tagged with on publish. Resolved at publish time,
+   * once the version is known, e.g. `"svc-{service}-{id}-v{version}"`.
+   */
+  tag: z.string().min(1),
+  /**
+   * Template for the `repository.url` field written into generated
+   * `package.json` (and shown in default README templates), e.g.
+   * `"https://github.com/{github.owner}/{github.repo}"`.
+   */
+  repositoryUrl: z.string().min(1),
+  npm: z.object({
+    registry: z.string().min(1),
+    access: z.enum(["public", "restricted"]),
+  }),
+  maven: z.object({
+    repositoryId: z.string().min(1),
+    repositoryUrl: z.string().min(1),
+  }),
+});
+
+export type PublishingInput = z.infer<typeof publishingSchema>;
+
+/**
+ * The generator-level / per-artifact-override form of {@link publishingSchema} -
+ * every field optional, since it only needs to override whichever fields
+ * differ from the root-level `publishing:` (which is guaranteed complete).
+ */
+export const publishingOverrideSchema = z.object({
+  branch: z.string().min(1).optional(),
+  tag: z.string().min(1).optional(),
+  repositoryUrl: z.string().min(1).optional(),
+  npm: z
+    .object({
+      registry: z.string().min(1).optional(),
+      access: z.enum(["public", "restricted"]).optional(),
+    })
+    .optional(),
+  maven: z
+    .object({
+      repositoryId: z.string().min(1).optional(),
+      repositoryUrl: z.string().min(1).optional(),
+    })
+    .optional(),
+});
+
+export type PublishingOverrideInput = z.infer<typeof publishingOverrideSchema>;
+
+/**
+ * The shape of a generator "recipe", without the cross-field checks below -
+ * kept separate so {@link artifactRefSchema}'s `overrides:` can `.partial()`
+ * it (zod rejects `.partial()` on a schema with `.check()` refinements
+ * attached).
+ */
+const generatorDefBaseSchema = z.object({
+  tool: sdkToolSchema,
+  lang: sdkLangSchema,
+  kind: sdkKindSchema,
+  /**
+   * `openapi-generator -g <generator>` value. Required when `tool` is
+   * `openapi-generator`.
+   */
+  generator: z.string().min(1).optional(),
+  /** npm package name template, e.g. `"@{vars.org}/{service}-client"`. */
+  package: z.string().min(1).optional(),
+  goModule: z.string().min(1).optional(),
+  goPackageName: z.string().min(1).optional(),
+  maven: mavenCoordsSchema.optional(),
+  additionalProperties: additionalPropertiesSchema,
+  /**
+   * Optional path (relative to the config file's directory) to a custom README
+   * template for this artifact - supports the same `{...}` placeholders as
+   * naming templates, plus `{version}`, `{title}`, and `{artifact.*}`. If
+   * omitted, a built-in default template for the artifact's language/kind is
+   * used instead.
+   */
+  readme: z.string().min(1).optional(),
+  /**
+   * Publishing conventions (branch/tag naming, registry URLs) for this
+   * generator specifically - overrides whichever fields differ from the
+   * root-level `publishing:` (required, see {@link publishingSchema}).
+   */
+  publishing: publishingOverrideSchema.optional(),
+});
+
+/**
+ * A single generator "recipe": which tool to invoke and how. Referenced by id
+ * from one or more contracts' `artifacts:` list.
+ */
+export const generatorDefSchema = generatorDefBaseSchema.check((ctx) => {
+  const value = ctx.value;
+
+  if (value.tool === "openapi-generator" && !value.generator) {
+    ctx.issues.push({
+      code: "custom",
+      message: '"generator" is required when tool is "openapi-generator"',
+      input: value,
+    });
+  }
+
+  if (value.lang === "go" && !value.goModule) {
+    ctx.issues.push({
+      code: "custom",
+      message: '"goModule" is required for lang "go"',
+      input: value,
+    });
+  }
+
+  if (value.lang === "java" && !value.maven) {
+    ctx.issues.push({
+      code: "custom",
+      message: '"maven" ({ groupId, artifactId }) is required for lang "java"',
+      input: value,
+    });
+  }
+
+  if (value.lang === "typescript" && !value.package) {
+    ctx.issues.push({
+      code: "custom",
+      message: '"package" is required for lang "typescript"',
+      input: value,
+    });
+  }
+});
+
+export type GeneratorDefInput = z.infer<typeof generatorDefSchema>;
+
+export const generatorsSchema = z.record(z.string(), generatorDefSchema);
+
+/**
+ * A contract's reference to a generator by id. The plain-string form just runs
+ * that generator as-is; the object form lets one contract tweak a shared
+ * generator (extra/overridden `additionalProperties`, a different
+ * `maven`/`package`/`readme`/... value) without duplicating the whole recipe
+ * under a new id, and `as` renames the artifact's own id (output
+ * folder / branch / tag segment) if a contract needs two variants of the same
+ * base generator.
+ */
+export const artifactRefSchema = z.union([
+  z.string().min(1),
+  z.object({
+    generator: z.string().min(1),
+    as: z.string().min(1).optional(),
+    overrides: generatorDefBaseSchema.partial().optional(),
+  }),
+]);
+
+export const contractSchema = z.object({
+  name: z.string().min(1),
+  title: z.string().min(1),
+  entrypoint: z.string().min(1),
+  artifacts: z.array(artifactRefSchema).min(1),
+});
+
+export const rootConfigSchema = z.object({
+  /**
+   * The config schema version this file targets. Currently must be `1`
+   * (the only version that exists) - see {@link CONFIG_SCHEMA_VERSION}.
+   */
+  configVersion: z.literal(CONFIG_SCHEMA_VERSION),
+  github: githubSchema,
+  vars: varsTreeSchema.default({}),
+  paths: pathsSchema.default({ dist: "dist" }),
+  docs: docsSchema,
+  /**
+   * Publishing conventions (branch/tag naming, registry URLs), applied to
+   * every artifact unless overridden per-generator or
+   * per-contract-artifact. Required - seagull has no built-in default here,
+   * see {@link publishingSchema}.
+   */
+  publishing: publishingSchema,
+  generators: generatorsSchema,
+  contracts: z.array(contractSchema).min(1),
+});
+
+export type RootConfigInput = z.infer<typeof rootConfigSchema>;
+export type ArtifactRefInput = z.infer<typeof artifactRefSchema>;
+export type ContractInput = z.infer<typeof contractSchema>;

package/src/config/template.ts

@@ -0,0 +1,113 @@
+const PLACEHOLDER = /\{([a-zA-Z0-9_.]+)}/g;
+
+export type TemplateScope = Record<string, unknown>;
+export type TemplateContext = Readonly<Record<string, string>>;
+
+/**
+ * Replaces every `{dot.path}` placeholder in `template` with its value from
+ * `context`, throwing a descriptive error if a placeholder has no match -
+ * a typo'd `{vars.org}` should fail loudly at config-load time, not silently
+ * produce a package named literally `@{vars.org}/...`.
+ *
+ * @param template - The template string, e.g. `"@{vars.org}/{service}-client"`.
+ * @param context  - The flattened context to resolve placeholders against.
+ * @returns The interpolated string.
+ */
+export function interpolate(
+  template: string,
+  context: TemplateContext,
+): string {
+  return template.replace(PLACEHOLDER, (_match, key: string) => {
+    const value = context[key];
+
+    if (value === undefined) {
+      const available = Object.keys(context).sort().join(", ");
+
+      throw new Error(
+        `Unknown template placeholder "{${key}}" in "${template}" (available: ${available})`,
+      );
+    }
+
+    return value;
+  });
+}
+
+/**
+ * Recursively interpolates every string value in `value` (walking through plain
+ * objects), leaving non-string leaves untouched. Used to resolve
+ * `additionalProperties` maps, which may mix templated strings with plain
+ * booleans/numbers.
+ *
+ * @param value   - The value (string, object, or primitive) to interpolate.
+ * @param context - The flattened context to resolve placeholders against.
+ * @returns A deep copy of `value` with every string interpolated.
+ */
+export function interpolateDeep<T>(value: T, context: TemplateContext): T {
+  // Every `as T` below asserts a value back into the exact shape it was
+  // destructured from - `T` is unconstrained here (it's whatever shape the
+  // caller's config value happens to be), which is the shape-preserving
+  // contract this function promises, not an actual type hole in practice.
+  /* eslint-disable @typescript-eslint/no-unsafe-return */
+  if (typeof value === "string") {
+    const interpolated: string = interpolate(value, context);
+
+    return interpolated as T;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => interpolateDeep(item, context)) as T;
+  }
+
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([key, child]) => [
+        key,
+        interpolateDeep(child, context),
+      ]),
+    ) as T;
+  }
+
+  /* eslint-enable @typescript-eslint/no-unsafe-return */
+  return value;
+}
+
+/**
+ * Flattens a nested scope object (e.g. `{ service: "auth", vars: { org: "x" } }`)
+ * into dot-path lookup keys (`{ service: "auth", "vars.org": "x" }`) for use
+ * with {@link interpolate}.
+ *
+ * @param scope - The nested scope to flatten.
+ * @returns A flat dot-path -> string map.
+ */
+export function buildTemplateContext(scope: TemplateScope): TemplateContext {
+  const out: Record<string, string> = {};
+
+  flatten(scope, "", out);
+
+  return out;
+}
+
+function flatten(
+  value: unknown,
+  prefix: string,
+  out: Record<string, string>,
+): void {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    for (const [key, child] of Object.entries(
+      value as Record<string, unknown>,
+    )) {
+      flatten(child, prefix ? `${prefix}.${key}` : key, out);
+    }
+
+    return;
+  }
+
+  if (value === undefined) {
+    return;
+  }
+
+  // Leaf values from parsed YAML/JSON config are always string/number/boolean
+  // (VarsTree's own type guarantees this) - String() is safe here.
+  /* eslint-disable-next-line @typescript-eslint/no-base-to-string */
+  out[prefix] = String(value);
+}

package/src/config/types.ts

@@ -0,0 +1,139 @@
+import type { VarsTree } from "./schema";
+
+export type { VarsTree } from "./schema";
+export type SdkTool = "openapi-generator" | "openapi-typescript";
+export type SdkLang = "typescript" | "go" | "java";
+export type SdkKind = "client" | "server";
+
+/**
+ * Fully resolved publishing conventions for one artifact.
+ */
+export interface ResolvedPublishing {
+  /** Fully resolved git branch name (no runtime-only placeholders left). */
+  branch: string;
+  /**
+   * Raw tag template - still contains `{version}`, resolved at publish
+   * time via `renderArtifactTag()` in `config/publishing.ts`.
+   */
+  tagTemplate: string;
+  /** Resolved `repository.url` for generated package.json / README examples. */
+  repositoryUrl: string;
+  npmRegistry: string;
+  npmAccess: "public" | "restricted";
+  mavenRepositoryId: string;
+  mavenRepositoryUrl: string;
+}
+
+/**
+ * A single artifact a contract generates: a generator recipe from the CLI
+ * config, fully resolved (templates interpolated, overrides merged, paths made
+ * absolute) for one specific contract.
+ */
+export interface ResolvedArtifact {
+  /**
+   * The id this artifact is known by for this contract - the key under
+   * `generators:` it was resolved from, or its `as` override. Used as the
+   * output folder segment, and to derive the publish branch/tag.
+   */
+  id: string;
+
+  tool: SdkTool;
+  lang: SdkLang;
+  kind: SdkKind;
+
+  /** `openapi-generator -g` value. Set only when `tool` is `openapi-generator`. */
+  generator?: string;
+
+  /** Absolute output directory: `<sdkDir>/<contract>/<id>`. */
+  outputDir: string;
+
+  /**
+   * Fully resolved git branch name - convenience alias for
+   * `publishing.branch`.
+   */
+  branch: string;
+
+  /**
+   * Publishing conventions (branch/tag/registry) for this artifact - see
+   * {@link ResolvedPublishing}.
+   */
+  publishing: ResolvedPublishing;
+
+  additionalProperties: Record<string, string | number | boolean>;
+
+  package?: string;
+  goModule?: string;
+  goPackageName?: string;
+  maven?: { groupId: string; artifactId: string };
+
+  /**
+   * Absolute path to a custom README template, if `readme:` was set for this
+   * generator/artifact. Falls back to a built-in default template when unset -
+   * see `core/readme/readme-renderer.ts`.
+   */
+  readmeTemplate?: string;
+}
+
+export interface ResolvedContract {
+  name: string;
+  title: string;
+  /** Absolute path to the source `openapi.yaml`. */
+  entrypoint: string;
+  /**
+   * Path to the source `openapi.yaml`, relative to `rootDir` - what
+   * `redocly.yaml`'s `apis:` section wants.
+   */
+  entrypointRelative: string;
+  artifacts: ResolvedArtifact[];
+}
+
+/**
+ * One (contract, artifact) pair - the flattened unit of work most commands
+ * actually iterate over.
+ */
+export interface ResolvedArtifactEntry {
+  contract: ResolvedContract;
+  artifact: ResolvedArtifact;
+}
+
+export interface ResolvedConfig {
+  /**
+   * The config schema version this file targets - see `CONFIG_SCHEMA_VERSION`
+   * in `config/schema.ts`.
+   */
+  configVersion: number;
+
+  /**
+   * Directory containing the config file - every relative path in the config
+   * (entrypoints, `paths.*`, `readme` templates, ...) resolves against this.
+   */
+  rootDir: string;
+
+  paths: {
+    dist: string;
+    specs: string;
+    docs: string;
+    sdk: string;
+  };
+
+  github: { owner: string; repo: string };
+  vars: VarsTree;
+
+  docs: {
+    server: { host: string; port: number };
+    metadata: {
+      title: string;
+      description: string;
+      favicon: string;
+      baseServerUrl: string;
+    };
+  };
+
+  contracts: ResolvedContract[];
+
+  /**
+   * Every (contract, artifact) pair across every contract, in config order -
+   * the flat list most commands iterate over.
+   */
+  allArtifacts: ResolvedArtifactEntry[];
+}

package/src/generator/generator.ts

@@ -0,0 +1,33 @@
+import type { SdkTool } from "../config/types";
+import type { GenerateContext, PrepareContext } from "./types";
+
+/**
+ * The root primitive every concrete SDK generator implements.
+ *
+ * One instance per underlying tool (`openapi-generator-cli`,
+ * `openapi-typescript`, ...) - not one per language, since a single tool
+ * invocation (e.g. `openapi-generator-cli -g java`/`-g go`) already covers
+ * every language it supports. Language-specific behaviour (patching `go.mod`,
+ * `package.json`, `pom.xml`, ...) is composed in via patchers rather than
+ * living in per-language subclasses.
+ */
+export abstract class Generator {
+  abstract readonly tool: SdkTool;
+
+  /**
+   * Optional one-time setup step, run once per tool before any of that tool's
+   * {@link generate} calls - for tools like `openapi-typescript` that generate
+   * every contract's output in a single global invocation instead of one call
+   * per artifact.
+   *
+   * @param ctx - Every (contract, artifact) pair using this generator's tool.
+   */
+  prepare?(ctx: PrepareContext): Promise<void>;
+
+  /**
+   * Generates a single artifact.
+   *
+   * @param ctx - The contract, artifact, and resolved version to generate for.
+   */
+  abstract generate(ctx: GenerateContext): Promise<void>;
+}

package/src/generator/registry.ts

@@ -0,0 +1,51 @@
+import type { SdkTool } from "../config/types";
+import type { Generator } from "./generator";
+
+/**
+ * Looks up the concrete {@link Generator} implementation for a given tool name.
+ */
+export class GeneratorRegistry {
+  private readonly generators = new Map<SdkTool, Generator>();
+
+  /**
+   * Registers a generator implementation under its own {@link Generator.tool}.
+   *
+   * @param generator - The generator instance to register.
+   * @returns `this`, for chaining.
+   */
+  register(generator: Generator): this {
+    this.generators.set(generator.tool, generator);
+
+    return this;
+  }
+
+  /**
+   * Resolves the generator implementation for a given tool name.
+   *
+   * @param tool - The tool name, e.g. `"openapi-generator"`.
+   * @returns The registered generator.
+   * @throws Error if no generator is registered for that tool.
+   */
+  resolve(tool: SdkTool): Generator {
+    const generator = this.generators.get(tool);
+
+    if (!generator) {
+      const available = [...this.generators.keys()].join(", ");
+
+      throw new Error(
+        `No generator implementation registered for tool "${tool}" (available: ${available})`,
+      );
+    }
+
+    return generator;
+  }
+
+  /**
+   * All distinct tools currently registered.
+   *
+   * @returns The registered tool names.
+   */
+  tools(): SdkTool[] {
+    return [...this.generators.keys()];
+  }
+}

package/src/generator/types.ts

@@ -0,0 +1,38 @@
+import type {
+  ResolvedArtifact,
+  ResolvedArtifactEntry,
+  ResolvedContract,
+  SdkTool,
+} from "../config/types";
+
+export type {
+  ResolvedArtifact,
+  ResolvedArtifactEntry,
+  ResolvedContract,
+  SdkTool,
+};
+
+/** Passed once per tool to {@link Generator.prepare}, before any of that
+ * tool's {@link Generator.generate} calls run. */
+export interface PrepareContext {
+  rootDir: string;
+  /**
+   * Every (contract, artifact) pair that uses this generator's `tool`, across
+   * all contracts.
+   */
+  entries: ResolvedArtifactEntry[];
+}
+
+/** Passed once per artifact to {@link Generator.generate}. */
+export interface GenerateContext {
+  rootDir: string;
+  contract: ResolvedContract;
+  artifact: ResolvedArtifact;
+  version: string;
+  github: { owner: string; repo: string };
+  /**
+   * Absolute path to the contract's bundled JSON spec
+   * (`<specsDir>/<contract>.json`).
+   */
+  specInputPath: string;
+}

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

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