@homeflare/alchemy 0.58.0 → 0.60.0

package/src/scope/patch-check.ts

@@ -0,0 +1,118 @@
+/**
+ * A consuming stack's own `check` calls `checkAlchemyPatch` to assert it actually carries the
+ * duplicate-resource-id fix — not just that SOME version of `alchemy` is installed, but that
+ * THIS install carries the patch, for the alchemy version it was cut against.
+ *
+ * ★ WHY A BUMP CAN OTHERWISE DROP IT SILENTLY. `patchedDependencies` keys a patch to an EXACT
+ *   version string (`alchemy@2.0.0-beta.81`). `bun add alchemy@2.0.0-beta.82` leaves that key
+ *   pointing at a version nothing installs anymore — `bun install` neither errors nor warns,
+ *   it just stops applying the patch, and the stack is back to the original silent collision
+ *   with every other gate still green. This check is what turns that bump into a failing
+ *   `check`, the same way `tests/dist.test.ts` turns a build regression into a failing test
+ *   instead of a surprise three repos downstream (this package's own AGENTS.md, "the smoke
+ *   test is not optional").
+ * ★ A STATIC CHECK, mirroring `@homeflare/config/check`'s `checkCopy`/`checkOxfmt` — not a
+ *   functional probe that spins up a `Stack`/`Resource`/`Effect` harness on every `check` run.
+ *   The functional proof that the patch's LOGIC works lives in this package's own
+ *   `duplicate-id.test.ts`, against the exact pinned version; a consumer's `check` only needs
+ *   to know whether ITS install carries that same patch, applied — three file reads, no
+ *   `effect` runtime pulled into every repo's check step.
+ * ⛔ IT REPORTS, IT DOES NOT REPAIR, same as `checkProject` in `@homeflare/config/check` — this
+ *   never edits `package.json` or re-runs `bun install` for the caller.
+ */
+import { PATCHED_ALCHEMY_VERSION } from './duplicate-id.ts';
+
+/** One thing wrong with a consuming stack's alchemy patch, in the imperative. */
+export type PatchProblem = string;
+
+const patchKey = (version: string) => `alchemy@${version}`;
+
+/** Where THIS package's own shipped copy of the patch lives, however it was installed. */
+const shippedPatchPath = (version: string): string =>
+  new URL(`../../patches/${patchKey(version)}.patch`, import.meta.url).pathname;
+
+type PackageJson = {
+  readonly patchedDependencies?: Readonly<Record<string, string>>;
+};
+
+/**
+ * @param projectDir The consuming stack's OWN repo root (where its `package.json` and
+ *   `patches/` directory live) — never this kit's own.
+ * @param alchemyVersion The version to check for — defaults to the version this package's
+ *   own shipped patch targets ({@link PATCHED_ALCHEMY_VERSION}); a caller only overrides it to
+ *   test a different pin.
+ */
+export const checkAlchemyPatch = async (
+  projectDir: string,
+  alchemyVersion: string = PATCHED_ALCHEMY_VERSION,
+): Promise<readonly PatchProblem[]> => {
+  const problems: PatchProblem[] = [];
+  const key = patchKey(alchemyVersion);
+
+  const installedPkg = Bun.file(`${projectDir}/node_modules/alchemy/package.json`);
+  if (!(await installedPkg.exists())) {
+    problems.push('node_modules/alchemy: not installed — nothing to check the patch against');
+    return problems;
+  }
+  const installedVersion = ((await installedPkg.json()) as { version?: string }).version;
+  if (installedVersion !== alchemyVersion) {
+    problems.push(
+      `node_modules/alchemy is ${installedVersion ?? 'unknown'}, but the duplicate-resource-id ` +
+        `patch targets ${alchemyVersion} — bump the patch (@homeflare/alchemy's own ` +
+        'patches/) before bumping alchemy, or this install has no protection at all',
+    );
+    return problems;
+  }
+
+  const pkgFile = Bun.file(`${projectDir}/package.json`);
+  if (!(await pkgFile.exists())) {
+    problems.push('package.json: missing');
+    return problems;
+  }
+  const pkg = (await pkgFile.json()) as PackageJson;
+  const declaredPath = pkg.patchedDependencies?.[key];
+  if (declaredPath === undefined) {
+    problems.push(
+      `package.json: patchedDependencies has no entry for "${key}" — this stack has no ` +
+        'duplicate-resource-id protection at all; see @homeflare/alchemy/docs/duplicate-resource-id.md',
+    );
+    return problems;
+  }
+
+  const theirs = Bun.file(`${projectDir}/${declaredPath}`);
+  if (!(await theirs.exists())) {
+    problems.push(`package.json declares "${key}" at ${declaredPath}, but that file is missing`);
+    return problems;
+  }
+  const ours = Bun.file(shippedPatchPath(alchemyVersion));
+  if (!(await ours.exists())) {
+    // The kit's own tarball is missing its patch — a packaging bug, not the consumer's.
+    problems.push(`@homeflare/alchemy ships no patches/${key}.patch to compare against`);
+    return problems;
+  }
+  if ((await theirs.text()) !== (await ours.text())) {
+    problems.push(
+      `${declaredPath}: differs from @homeflare/alchemy's shipped patch — re-copy it, ` +
+        'or say why it differs',
+    );
+  }
+
+  // Declared and byte-identical is not yet APPLIED: a hand-edited patchedDependencies entry,
+  // or an install under a package manager that does not support bun's patch format, leaves
+  // node_modules unpatched with nothing above noticing. One cheap textual proof it landed.
+  const resourceSrc = Bun.file(`${projectDir}/node_modules/alchemy/src/Resource.ts`);
+  const resourceLib = Bun.file(`${projectDir}/node_modules/alchemy/lib/Resource.js`);
+  const marker = 'DuplicateResourceIdError';
+  const [srcText, libText] = await Promise.all([
+    resourceSrc.exists().then((ok) => (ok ? resourceSrc.text() : '')),
+    resourceLib.exists().then((ok) => (ok ? resourceLib.text() : '')),
+  ]);
+  if (!srcText.includes(marker) && !libText.includes(marker)) {
+    problems.push(
+      'node_modules/alchemy/{src/Resource.ts,lib/Resource.js}: neither contains the patch — ' +
+        'declared in package.json but not applied; re-run `bun install`',
+    );
+  }
+
+  return problems;
+};