@distilled.cloud/core 1.0.0-rc.8 → 1.0.0-rc.9

package/src/codegen/spec-path.ts

@@ -0,0 +1,115 @@
+/**
+ * Spec path resolution — the seam between a production spec mirror and a
+ * local working copy of one (dev-time only).
+ *
+ * Every SDK package reads its specs from `packages/<pkg>/specs/`. In
+ * production that directory holds a submodule of the package's mirror
+ * repository, `distilled-mirror/spec-mirror-<pkg>`, whose layout is fixed:
+ *
+ *   packages/<pkg>/specs/spec-mirror-<pkg>/
+ *   ├── .meta/          fetch-specs.ts + its package.json
+ *   └── specs/          what the generator reads
+ *
+ * A contributor adding a provider cannot create that repository — it lives in
+ * an org they have no write access to, and it is only created once the
+ * `distilled-submodules` stack deploys on merge to main. So `pnpm specs:local
+ * <pkg>` runs the same `fetch-specs.ts` into a gitignored directory shaped
+ * exactly like the mirror:
+ *
+ *   packages/<pkg>/specs/.local/
+ *   ├── .meta/
+ *   └── specs/
+ *
+ * Setting {@link LOCAL_ENV} then re-roots every spec read into it. Nothing in
+ * the package's source changes — the `specPath` a `convert.ts` declares stays
+ * the production one — so there is no `.local` reference that could be
+ * committed by accident, and the switch is impossible to leave on: it lives
+ * in the environment of one command, never in a file.
+ *
+ * The opt-in is deliberate rather than a fallback-when-missing. A silent
+ * fallback would regenerate an SDK from a stale `.local` copy the moment a
+ * submodule failed to check out, and the result — committed, formatted,
+ * plausible — would be indistinguishable from a real regeneration.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** Set to a non-empty value to read specs from `specs/.local` instead. */
+export const LOCAL_ENV = "DISTILLED_SPECS_LOCAL";
+
+/** The local working copy of a mirror, relative to a package root. */
+export const LOCAL_DIR = path.join("specs", ".local");
+
+/** Repository name of the mirror feeding `packages/<pkg>`. */
+export const mirrorRepositoryName = (pkg: string) => `spec-mirror-${pkg}`;
+
+/** Whether this process reads specs from `specs/.local`. */
+export const isLocalSpecs = (): boolean =>
+  (process.env[LOCAL_ENV] ?? "").trim() !== "";
+
+let announced = false;
+
+/**
+ * The path within a mirror's `specs/` directory that `specPath` names.
+ *
+ * Spec paths take one of two shapes — `specs/<mirror>/specs/<tail>` for a
+ * submodule and `specs/<tail>` for a committed file — and in both the tail is
+ * everything after the LAST `specs` segment. That one rule covers the
+ * submodule form, the committed form, the nested forms
+ * (`specs/<mirror>/specs/models/<service>/...`) and the directory form
+ * (`specs/<mirror>/specs`, whose tail is empty — the mirror's `specs/`
+ * directory itself) without needing to know which it was handed.
+ *
+ * `undefined` means there is no `specs` segment at all, which local mode
+ * cannot interpret.
+ */
+const tailWithinSpecs = (specPath: string): string | undefined => {
+  const segments = specPath.split(/[/\\]/).filter((s) => s !== "" && s !== ".");
+  const last = segments.lastIndexOf("specs");
+  if (last === -1) return undefined;
+  return segments.slice(last + 1).join(path.sep);
+};
+
+/**
+ * Resolve a package-relative spec path to an absolute one.
+ *
+ * @param root      absolute package root (`path.resolve(import.meta.dir, "..")`)
+ * @param specPath  the production path, relative to `root` (or absolute)
+ */
+export const resolveSpecPath = (root: string, specPath: string): string => {
+  const production = path.resolve(root, specPath);
+  if (!isLocalSpecs() || path.isAbsolute(specPath)) return production;
+
+  const tail = tailWithinSpecs(specPath);
+  if (tail === undefined) {
+    throw new Error(
+      `${LOCAL_ENV} is set, but "${specPath}" has no \`specs/\` segment to ` +
+        `re-root. Local mode only understands paths under the package's ` +
+        `specs/ directory.`,
+    );
+  }
+
+  if (!announced) {
+    announced = true;
+    // stderr, not stdout: generate-all captures stdout per package and only
+    // prints it on failure, and this is exactly the line you need to see on
+    // a run that succeeded against the wrong specs.
+    console.error(
+      `⚠  ${LOCAL_ENV} — reading specs from ${LOCAL_DIR}, not the mirror submodule.`,
+    );
+  }
+
+  const local = path.join(root, LOCAL_DIR, "specs", tail);
+  if (!fs.existsSync(local)) {
+    // A missing local spec is a setup mistake, not a generator bug, and the
+    // ENOENT the caller would otherwise raise names a path nobody recognises.
+    throw new Error(
+      `${local} does not exist. Materialise this package's mirror first:\n` +
+        `  pnpm specs:local ${path.basename(root)}\n` +
+        `If that succeeds and this path is still missing, the package's ` +
+        `declared spec path (${specPath}) is not mirror-shaped yet — it must ` +
+        `read \`specs/<mirror>/specs/<file>\` for local mode to find it.`,
+    );
+  }
+  return local;
+};

package/src/json-patch.ts

@@ -1,10 +1,11 @@
 /**
  * JSON Patch (RFC 6902) Implementation
  *
- * Provides a unified spec patching system for all SDKs. Patches are applied to
- * generated intermediary specs (Smithy models, OpenAPI docs, …) before code
- * generation to add typed error shapes, rename operations, mark nullable
- * fields, etc. Ported from the distilled repo's `core/json-patch`.
+ * Provides a unified spec patching system for all SDKs. Patches apply in
+ * `convert` so `.generated-specs` is the patched Smithy model. generate does
+ * not patch. Prefer `operationNaming: "verbNoun"` for operationId renames —
+ * JSON pointers at `/paths/~1foo/operationId` go stale when upstream prefixes
+ * paths.
  *
  * Pure functions only — callers load patch files themselves (the generators
  * use Effect's FileSystem) and hand the parsed operations to `applyPatch`.
@@ -45,19 +46,44 @@ export function parseJsonPointer(pointer: string): string[] {
 }
 
 /** Get a value at a JSON Pointer path. */
+/**
+ * The target location of a patch operation is absent from the document —
+ * spec drift (renamed/removed upstream), not a malformed patch.
+ */
+export class StaleTargetError extends Error {
+  override readonly name = "StaleTargetError";
+}
+
 export function getValueAtPath(obj: unknown, pointer: string): unknown {
   const segments = parseJsonPointer(pointer);
   let current: unknown = obj;
 
   for (const segment of segments) {
-    if (current === null || typeof current !== "object") {
-      throw new Error(`Cannot traverse path ${pointer}: not an object`);
+    if (
+      current === null ||
+      current === undefined ||
+      typeof current !== "object"
+    ) {
+      throw new StaleTargetError(
+        `JSON pointer ${pointer} missing (at '${segment}'): not an object`,
+      );
     }
     if (Array.isArray(current)) {
       const index = segment === "-" ? current.length : parseInt(segment, 10);
+      if (index < 0 || index >= current.length) {
+        throw new StaleTargetError(
+          `JSON pointer ${pointer} missing index '${segment}'`,
+        );
+      }
       current = current[index];
     } else {
-      current = (current as Record<string, unknown>)[segment];
+      const record = current as Record<string, unknown>;
+      if (!Object.prototype.hasOwnProperty.call(record, segment)) {
+        throw new StaleTargetError(
+          `JSON pointer ${pointer} missing key '${segment}'`,
+        );
+      }
+      current = record[segment];
     }
   }
 
@@ -80,7 +106,9 @@ export function setValueAtPath(
   for (let i = 0; i < segments.length - 1; i++) {
     const segment = segments[i]!;
     if (current === null || typeof current !== "object") {
-      throw new Error(`Cannot traverse path ${pointer}: not an object`);
+      throw new StaleTargetError(
+        `Cannot traverse path ${pointer}: not an object`,
+      );
     }
     if (Array.isArray(current)) {
       current = current[parseInt(segment, 10)];
@@ -91,7 +119,7 @@ export function setValueAtPath(
 
   const lastSegment = segments[segments.length - 1]!;
   if (current === null || typeof current !== "object") {
-    throw new Error(
+    throw new StaleTargetError(
       `Cannot set value at path ${pointer}: parent is not an object`,
     );
   }
@@ -119,7 +147,9 @@ export function removeValueAtPath(obj: unknown, pointer: string): void {
   for (let i = 0; i < segments.length - 1; i++) {
     const segment = segments[i]!;
     if (current === null || typeof current !== "object") {
-      throw new Error(`Cannot traverse path ${pointer}: not an object`);
+      throw new StaleTargetError(
+        `Cannot traverse path ${pointer}: not an object`,
+      );
     }
     if (Array.isArray(current)) {
       current = current[parseInt(segment, 10)];
@@ -130,15 +160,28 @@ export function removeValueAtPath(obj: unknown, pointer: string): void {
 
   const lastSegment = segments[segments.length - 1]!;
   if (current === null || typeof current !== "object") {
-    throw new Error(
+    throw new StaleTargetError(
       `Cannot remove at path ${pointer}: parent is not an object`,
     );
   }
 
+  // RFC 6902 §4.2: the target location MUST exist.
   if (Array.isArray(current)) {
-    current.splice(parseInt(lastSegment, 10), 1);
+    const index = parseInt(lastSegment, 10);
+    if (Number.isNaN(index) || index < 0 || index >= current.length) {
+      throw new StaleTargetError(
+        `JSON pointer ${pointer} missing index '${lastSegment}'`,
+      );
+    }
+    current.splice(index, 1);
   } else {
-    delete (current as Record<string, unknown>)[lastSegment];
+    const record = current as Record<string, unknown>;
+    if (!Object.prototype.hasOwnProperty.call(record, lastSegment)) {
+      throw new StaleTargetError(
+        `JSON pointer ${pointer} missing key '${lastSegment}'`,
+      );
+    }
+    delete record[lastSegment];
   }
 }
 
@@ -158,16 +201,21 @@ export function applyOperation(
     case "remove":
       removeValueAtPath(obj, operation.path);
       break;
-    case "replace":
-      // For replace, the path must exist
-      getValueAtPath(obj, operation.path); // throws if doesn't exist
+    case "replace": {
+      const existing = getValueAtPath(obj, operation.path);
+      if (existing === undefined) {
+        throw new StaleTargetError(
+          `JSON pointer ${operation.path} does not exist`,
+        );
+      }
       setValueAtPath(obj, operation.path, operation.value);
       break;
+    }
     case "move": {
       if (!operation.from) throw new Error("move operation requires 'from'");
       const moveValue = getValueAtPath(obj, operation.from);
       if (moveValue === undefined) {
-        throw new Error(
+        throw new StaleTargetError(
           `Cannot move from path ${operation.from}: not an object`,
         );
       }
@@ -207,16 +255,25 @@ export function applyPatch(obj: unknown, patch: JsonPatch): void {
 }
 
 /**
- * Whether a per-operation failure is caused by the target location being
- * absent from the spec (i.e. spec drift — the operation/shape the patch
- * targets was renamed or removed upstream) as opposed to a malformed patch.
- * Stale targets should be skipped with a warning rather than aborting the
- * whole generate; a patch that only adds an error to an operation that no
- * longer exists is harmless to drop.
+ * Whether a per-operation failure is a {@link StaleTargetError} (the
+ * operation/shape the patch targets was renamed or removed upstream) as
+ * opposed to a malformed patch. Accepts the thrown value or its message.
+ * Convert fails the run on these by default (`onStalePatch: "fail"`);
+ * `"warn"` restores skip-and-continue.
  */
-export function isStaleTargetError(message: string): boolean {
+export function isStaleTargetError(error: unknown): boolean {
+  if (error instanceof StaleTargetError) return true;
+  const message =
+    typeof error === "string"
+      ? error
+      : error instanceof Error
+        ? error.message
+        : "";
   return (
     message.includes("not an object") ||
-    message.includes("parent is not an object")
+    message.includes("parent is not an object") ||
+    message.includes("missing key") ||
+    message.includes("missing index") ||
+    message.includes("does not exist")
   );
 }