@distilled.cloud/core 0.30.3 → 1.0.0-rc.10

package/src/codegen/members.ts

@@ -0,0 +1,71 @@
+/**
+ * Structure-member analysis for the SDK generators (dev-time only).
+ *
+ * The TS-facing name policy is the provider's (cloudflare camelCases wire
+ * names, AWS keeps them) — supplied as `nameFn`. Wire-name resolution from
+ * the smithy HTTP binding traits is generic smithy semantics.
+ */
+import { oneLine } from "./naming.ts";
+
+export interface MemberBase {
+  /** Original smithy member name. */
+  readonly name: string;
+  /** TS-facing name (per `nameFn`, deduplicated within the structure). */
+  readonly tsName: string;
+  readonly target: string;
+  readonly required: boolean;
+  readonly doc: string | undefined;
+  readonly traits: Record<string, any>;
+}
+
+/**
+ * Base analysis of a structure's members: TS naming (with collision
+ * dedup — a clashing name falls back to the original, then a numeric
+ * suffix), required-ness, and one-line docs. Binding classification and
+ * anything provider-specific layer on top via `traits`.
+ */
+export const memberBases = (
+  def: any,
+  nameFn: (memberName: string) => string = (n) => n,
+): MemberBase[] => {
+  const used = new Set<string>();
+  return Object.entries(def.members ?? {}).map(([mn, m]: [string, any]) => {
+    const traits = m.traits ?? {};
+    let tsName = nameFn(mn);
+    if (used.has(tsName)) tsName = mn;
+    let k = 2;
+    while (used.has(tsName)) tsName = `${nameFn(mn)}${k++}`;
+    used.add(tsName);
+    return {
+      name: mn,
+      tsName,
+      target: m.target,
+      required: "smithy.api#required" in traits,
+      doc: oneLine(traits["smithy.api#documentation"]),
+      traits,
+    };
+  });
+};
+
+/**
+ * The wire name a bound member serializes under, per the smithy HTTP
+ * binding traits: labels use the member name (URI placeholders), query and
+ * header use the trait value when it's a non-empty string, everything else
+ * uses `jsonName` when present.
+ */
+export const smithyWireName = (
+  traits: Record<string, any>,
+  memberName: string,
+  binding: "label" | "query" | "header" | "other",
+): string => {
+  if (binding === "label") return memberName;
+  if (binding === "query") {
+    const v = traits["smithy.api#httpQuery"];
+    return typeof v === "string" && v ? v : memberName;
+  }
+  if (binding === "header") {
+    const v = traits["smithy.api#httpHeader"];
+    return typeof v === "string" && v ? v : memberName;
+  }
+  return traits["smithy.api#jsonName"] ?? memberName;
+};

package/src/codegen/naming.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared naming utilities for the SDK generators (dev-time only — imported by
+ * `packages/<sdk>/scripts/generate.ts`, never by runtime code).
+ */
+
+/** JSON-string-quote a value for emission into generated source. */
+export const q = (s: string): string => JSON.stringify(s);
+
+/** Smithy shape id → local name (`ns#Shape` → `Shape`). */
+export const local = (id: string): string => id.split("#")[1] ?? id;
+
+/** Whether a shape id is a smithy prelude shape (`smithy.api#…`). */
+export const isPrelude = (id: string): boolean => id.startsWith("smithy.api#");
+
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/** Emit a TS object key: bare when a valid identifier, quoted otherwise. */
+export const tsKey = (s: string): string => (IDENT.test(s) ? s : q(s));
+
+/** snake_case / kebab-case wire name → camelCase TS-facing name. */
+export const camel = (s: string): string =>
+  s.replace(/[_-]+([A-Za-z0-9])/g, (_, c: string) => c.toUpperCase());
+
+/** Reserved words that can't be `const` names. */
+export const RESERVED = new Set([
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "enum",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "import",
+  "in",
+  "instanceof",
+  "let",
+  "new",
+  "null",
+  "package",
+  "return",
+  "static",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "yield",
+]);
+
+/**
+ * Lower-case the first character for an exported operation name — unless the
+ * result is a reserved word, in which case the original casing is kept.
+ */
+export const lowerFirst = (s: string): string => {
+  const lowered = s.charAt(0).toLowerCase() + s.slice(1);
+  return RESERVED.has(lowered) ? s : lowered;
+};
+
+/** Upper-case the first character. */
+export const upperFirst = (s: string): string =>
+  s.charAt(0).toUpperCase() + s.slice(1);
+
+/**
+ * Collapse a smithy documentation string to a single safe line for a
+ * `/** … *​/` comment.
+ */
+export const oneLine = (s: string | undefined): string | undefined =>
+  s ? s.replace(/\s+/g, " ").replace(/\*\//g, "*\\/").trim() : undefined;

package/src/codegen/openapi-cli.ts

@@ -0,0 +1,182 @@
+/**
+ * OpenAPI → Smithy pipeline helper (dev-time only, provider-agnostic).
+ *
+ * Owns the spec-side pipeline every OpenAPI-sourced provider shares: read the
+ * spec file, apply OpenAPI RFC-6902 ops to the document, convert with
+ * {@link convertOpenApiToSmithy} (which owns verbNoun naming), apply Smithy
+ * RFC-6902 ops (`/shapes`, `/metadata`) to the model, and write
+ * `.generated-specs/<name>.json`. Stale targets fail unless
+ * `onStalePatch: "warn"`.
+ *
+ * A provider's `scripts/convert.ts` is: a `runOpenApiConvert` call.
+ * `scripts/generate.ts` compiles the already-patched models and does not
+ * apply patches.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import {
+  convertOpenApiToSmithy,
+  type OpenApiConvertOptions,
+} from "./openapi.ts";
+import {
+  applyRfc6902Files,
+  finalizeConvert,
+  isSmithyPatchPath,
+  listRfc6902PatchFiles,
+} from "./patches.ts";
+import { resolveSpecPath } from "./spec-path.ts";
+
+export interface OpenApiSpecEntry {
+  /** Output model name — written to `<outDir>/<name>.json`. */
+  readonly name: string;
+  /** Spec file path, relative to `root` (or absolute). */
+  readonly specPath: string;
+  /**
+   * Hook between patching and conversion (e.g. path prefixing, server
+   * rewrites). May mutate the spec in place or return a replacement.
+   */
+  readonly preprocess?: (spec: any) => unknown | void | Promise<unknown | void>;
+  /** Per-spec converter option overrides (merged over the shared options). */
+  readonly options?: Partial<OpenApiConvertOptions>;
+}
+
+export interface RunOpenApiConvertOptions {
+  /** Absolute package root (usually `path.resolve(import.meta.dir, "..")`). */
+  readonly root: string;
+  readonly specs: readonly OpenApiSpecEntry[];
+  /**
+   * RFC-6902 patch chain root, relative to `root`. Default `"patches"`;
+   * `false` disables. Layout: `<patchesDir>/<name>/*.json` when the
+   * per-spec directory exists; for single-spec providers a flat
+   * `<patchesDir>/*.json` also works. Ops under `/shapes` or `/metadata`
+   * apply to the Smithy model after conversion; the rest apply to OpenAPI.
+   */
+  readonly patchesDir?: string | false;
+  /** Output directory, relative to `root`. Default `".generated-specs"`. */
+  readonly outDir?: string;
+  /**
+   * Spec text parser. Default `JSON.parse` — the seam for YAML specs
+   * (`parse: (text) => YAML.parse(text)`).
+   */
+  readonly parse?: (text: string, specPath: string) => unknown;
+  /** Shared converter options (per-spec `options` merge over these). */
+  readonly options: OpenApiConvertOptions;
+  /**
+   * What to do when a patch JSON pointer does not resolve. Default `"fail"`:
+   * silent skip is how a whole patch chain can vanish after an upstream path
+   * prefix change. `"warn"` restores the old skip-and-continue behaviour.
+   */
+  readonly onStalePatch?: "fail" | "warn";
+  /**
+   * Run {@link finalizeConvert} on the written models (reference check +
+   * finalized marker; naming already happened in the converter). Default
+   * true. Pass false when the caller finalizes once after several convert
+   * steps (Fly machines + sprites + addons).
+   */
+  readonly finalize?: boolean;
+}
+
+const exists = async (p: string): Promise<boolean> => {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Run the OpenAPI→Smithy conversion pipeline (plain async — call from a script). */
+export const runOpenApiConvert = async (
+  o: RunOpenApiConvertOptions,
+): Promise<void> => {
+  const outDir = path.resolve(o.root, o.outDir ?? ".generated-specs");
+  const patchRoot =
+    o.patchesDir === false
+      ? undefined
+      : path.resolve(o.root, o.patchesDir ?? "patches");
+  const parse = o.parse ?? ((text: string) => JSON.parse(text));
+  const onStalePatch = o.onStalePatch ?? "fail";
+
+  await fs.mkdir(outDir, { recursive: true });
+
+  console.log("🛠️  openapi → smithy");
+  console.log(`   Output: ${outDir}`);
+
+  for (const entry of o.specs) {
+    // Production path by default; `specs/.local` under DISTILLED_SPECS_LOCAL.
+    const specPath = resolveSpecPath(o.root, entry.specPath);
+    let spec: any = parse(await fs.readFile(specPath, "utf8"), specPath);
+
+    // ---- RFC-6902: OpenAPI ops before convert, Smithy ops after ----
+    let patchDir: string | undefined;
+    if (patchRoot && (await exists(patchRoot))) {
+      const perSpec = path.join(patchRoot, entry.name);
+      if (await exists(perSpec)) {
+        patchDir = perSpec;
+      } else if (o.specs.length === 1) {
+        patchDir = patchRoot;
+      }
+    }
+    const patchFiles = patchDir ? await listRfc6902PatchFiles(patchDir) : [];
+    const patchLabel = (file: string) => `${entry.name}/${path.basename(file)}`;
+    const openapiPatches = await applyRfc6902Files(spec, patchFiles, {
+      onStalePatch,
+      include: (op) => !isSmithyPatchPath(op.path),
+      label: patchLabel,
+    });
+    if (openapiPatches.errors.length) {
+      for (const b of openapiPatches.errors)
+        console.error(`❌ bad patch: ${b}`);
+      throw new Error(
+        `${openapiPatches.errors.length} patch operation(s) failed — fix the pointers or delete the patch`,
+      );
+    }
+
+    // ---- Preprocess hook ----
+    if (entry.preprocess) {
+      const replaced = await entry.preprocess(spec);
+      if (replaced !== undefined) spec = replaced;
+    }
+
+    // ---- Convert, Smithy patches, write ----
+    const model = convertOpenApiToSmithy(spec, {
+      ...o.options,
+      ...entry.options,
+    });
+    const smithyPatches = await applyRfc6902Files(model, patchFiles, {
+      onStalePatch,
+      include: (op) => isSmithyPatchPath(op.path),
+      label: patchLabel,
+    });
+    if (smithyPatches.errors.length) {
+      for (const b of smithyPatches.errors) console.error(`❌ bad patch: ${b}`);
+      throw new Error(
+        `${smithyPatches.errors.length} Smithy patch operation(s) failed — fix the pointers or delete the patch`,
+      );
+    }
+    const opCount = Object.values(model.shapes).filter(
+      (s: any) => s.type === "operation",
+    ).length;
+    const outPath = path.join(outDir, `${entry.name}.json`);
+    await fs.writeFile(outPath, JSON.stringify(model, null, 2) + "\n");
+    const staleOps = openapiPatches.stale + smithyPatches.stale;
+    console.log(
+      `   ✅ ${entry.name}: ${opCount} operations, ${Object.keys(model.shapes).length} shapes` +
+        (patchFiles.length
+          ? ` (${patchFiles.length} patch file(s) applied${staleOps ? `, ${staleOps} stale op(s) skipped` : ""})`
+          : ""),
+    );
+  }
+
+  if (o.finalize !== false) {
+    const written = new Set(o.specs.map((s) => s.name));
+    await finalizeConvert({
+      root: o.root,
+      outDir,
+      // Patches and naming already ran above.
+      patchesDir: false,
+      operationNaming: "as-is",
+      include: (resource) => written.has(resource),
+    });
+  }
+};