@homeflare/alchemy 0.8.0 → 0.10.1

package/src/verify/verify.test.ts

@@ -0,0 +1,146 @@
+/**
+ * The verifier against Alchemy's own planner (fake-engine.ts): what it reports for each kind of row,
+ * and that it never writes while the engine it watches would.
+ *
+ * ★ THE FIRST TEST IS THE MEASUREMENT THE TOOL EXISTS FOR. alchemy beta.79 prints `adopted` for a
+ *   matching object and for a drifting one alike, and the deploy reconciles both. Pinned here so an
+ *   Alchemy upgrade that stops forcing the update — or starts logging the diff — fails loudly and
+ *   this tool can be re-thought rather than silently duplicated.
+ */
+import { describe, expect, test } from 'bun:test';
+import { renamedFrom } from 'alchemy';
+import * as Effect from 'effect/Effect';
+import {
+  Blind,
+  type Body,
+  type Cloud,
+  Thing,
+  cloudOf,
+  fakeEngine,
+  writesOf,
+} from './fake-engine.ts';
+import { exitCodeOf } from './report.ts';
+
+const one = (name: string, comment?: string) =>
+  Thing(name, comment === undefined ? { name } : { comment, name });
+
+const rowsBy = async (cloud: Cloud, body: Body, all = false) => {
+  const report = await fakeEngine(cloud).verify(body, { all });
+  return { byFqn: Object.fromEntries(report.rows.map((row) => [row.fqn, row])), report };
+};
+
+describe('what alchemy beta.79 does with an adoption', () => {
+  test('prints adopted for a match and for a drift alike, and reconciles both', async () => {
+    const cloud = cloudOf({ same: 'x', drifted: 'old' });
+    const planned = await fakeEngine(cloud).deploy(
+      Effect.all([one('same', 'x'), one('drifted', 'new')]),
+    );
+    expect(planned).toEqual({ drifted: 'adopted', same: 'adopted' });
+    expect(writesOf(cloud).sort()).toEqual(['reconcile drifted', 'reconcile same']);
+  });
+});
+
+describe('verifySession', () => {
+  test('a matching adoption is a no-op, and verifying it writes nothing', async () => {
+    const cloud = cloudOf({ same: 'x' });
+    const { byFqn, report } = await rowsBy(cloud, one('same', 'x'));
+    expect(byFqn['same']).toMatchObject({
+      changed: [],
+      diff: 'noop',
+      ok: true,
+      planned: 'adopted',
+      read: 'found',
+      stateRow: false,
+      type: 'Test.Thing',
+    });
+    expect(exitCodeOf(report)).toBe(0);
+    expect(writesOf(cloud)).toEqual([]);
+    expect(cloud.calls).toEqual(['read same', 'diff same']);
+  });
+
+  test('a drifting adoption says update and names the field, though the engine says adopted', async () => {
+    const cloud = cloudOf({ drifted: 'old' });
+    const { byFqn, report } = await rowsBy(cloud, one('drifted', 'new'));
+    expect(byFqn['drifted']).toMatchObject({
+      changed: ['comment'],
+      diff: 'update',
+      ok: false,
+      planned: 'adopted',
+    });
+    expect(byFqn['drifted']?.why).toContain('the deploy writes');
+    expect(exitCodeOf(report)).toBe(1);
+    expect(writesOf(cloud)).toEqual([]);
+  });
+
+  test('an object the read cannot find is a create, not an adoption', async () => {
+    const cloud = cloudOf();
+    const { byFqn } = await rowsBy(cloud, one('fresh'));
+    expect(byFqn['fresh']).toMatchObject({ diff: 'not-run', ok: false, planned: 'create' });
+    expect(byFqn['fresh']?.read).toBe('absent');
+    expect(byFqn['fresh']?.why).toContain('CREATES');
+  });
+
+  test('an unowned match is a no-op with a note that the deploy needs --adopt', async () => {
+    const cloud = cloudOf({ theirs: 'x' });
+    cloud.unowned.add('theirs');
+    const { byFqn } = await rowsBy(cloud, one('theirs', 'x'));
+    expect(byFqn['theirs']).toMatchObject({ diff: 'noop', ok: true, read: 'unowned' });
+    expect(byFqn['theirs']?.why).toContain('--adopt');
+  });
+
+  test('a provider with no diff cannot prove an adoption', async () => {
+    const cloud = cloudOf({ blind: 'x' });
+    const { byFqn } = await rowsBy(cloud, Blind('blind', { comment: 'x', name: 'blind' }));
+    expect(byFqn['blind']).toMatchObject({ diff: 'none', ok: false, planned: 'adopted' });
+  });
+
+  test('rows with state are left out by default and read afresh with all', async () => {
+    const cloud = cloudOf();
+    const engine = fakeEngine(cloud);
+    await engine.deploy(one('kept', 'x'));
+    cloud.live.set('new', 'y');
+    cloud.calls.length = 0;
+    const body = Effect.all([one('kept', 'x'), one('new', 'y')]);
+
+    const scoped = await engine.verify(body);
+    expect(scoped.rows.map((row) => row.fqn)).toEqual(['new']);
+    expect(scoped.declared).toBe(2);
+
+    const all = await engine.verify(body, { all: true });
+    const kept = all.rows.find((row) => row.fqn === 'kept');
+    expect(kept).toMatchObject({ diff: 'noop', ok: true, planned: 'noop', read: 'found' });
+    expect(kept?.stateRow).toBe(true);
+    expect(writesOf(cloud)).toEqual([]);
+  });
+
+  /**
+   * ⚠️ A RENAME MAY HAND ITS OLD ID TO A NEW RESOURCE IN THE SAME DEPLOY (alchemy Rename.ts). The
+   *   store still holds the renamer's row at that id, so judging state by FQN alone hid the new
+   *   resource's `create` from the default report. Both rows are without state of their own.
+   */
+  test('a rename that hands its old id to a new resource shows both, the create included', async () => {
+    const cloud = cloudOf();
+    const engine = fakeEngine(cloud);
+    await engine.deploy(one('old', 'x'));
+    const body = Effect.all([
+      Thing('moved', { comment: 'x', name: 'old' }).pipe(renamedFrom('old')),
+      Thing('old', { name: 'fresh' }),
+    ]);
+    const report = await engine.verify(body);
+    const byFqn = Object.fromEntries(report.rows.map((row) => [row.fqn, row]));
+    expect(Object.keys(byFqn).sort()).toEqual(['moved', 'old']);
+    expect(byFqn['old']).toMatchObject({ ok: false, planned: 'create', stateRow: false });
+    expect(byFqn['moved']).toMatchObject({ ok: false, stateRow: false });
+    expect(writesOf(cloud)).toEqual(['reconcile old']);
+  });
+
+  test('with all, a row no longer declared is a pending delete', async () => {
+    const cloud = cloudOf();
+    const engine = fakeEngine(cloud);
+    await engine.deploy(one('gone', 'x'));
+    const report = await engine.verify(Effect.void, { all: true });
+    expect(report.rows).toEqual([expect.objectContaining({ fqn: 'gone', ok: false })]);
+    expect(report.rows[0]?.planned).toBe('delete');
+    expect(cloud.live.get('gone')).toBe('x');
+  });
+});

package/src/verify/verify.ts

@@ -0,0 +1,185 @@
+/**
+ * Prove a deploy's adoptions are no-ops — with Alchemy's own planner, before anything is written.
+ *
+ * ★ THE ENGINE PLANS, THIS ONLY WATCHES. `verifySession` runs `Plan.make` — the same call
+ *   `alchemy plan` makes (Alchemist routes/stack.ts) — over the session's context with every
+ *   provider swapped for a watched copy (spy.ts). Output resolution, the state lookup, rename
+ *   migrations, the adoption probe and `adopt(…)` all stay the engine's; nothing here re-derives
+ *   them. What it adds is the provider's own `diff` answer, which Plan.ts overwrites for every
+ *   adopted row (`forceUpdateAfterAdoption`), and the state-row check that says which rows ARE
+ *   adoptions.
+ *
+ * ⛔ READ-ONLY BY CONSTRUCTION. The planner calls `read` and `diff`; spy.ts replaces `reconcile`,
+ *   `delete` and `precreate` with refusals; nothing here calls `apply`. `--all` adds one `read` per
+ *   row with state, and recheck.ts one more `diff` for an adopted `noop` whose read differs from
+ *   the declaration — both still reads by Alchemy's provider contract.
+ * ⚠️ READS ARE NOT FREE FOR EVERY FAMILY. A kit PVE/PBS read mints a lease through OpenBao, which
+ *   creates a short-lived API token on the cluster, exactly as `alchemy plan` does.
+ */
+import * as Alchemist from 'alchemy/Alchemist';
+import * as Plan from 'alchemy/Plan';
+import type { ProviderService } from 'alchemy/Provider';
+import type { CompiledStack } from 'alchemy/Stack';
+import { State, isActionState } from 'alchemy/State';
+import type * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import { inPlanScope } from './plan-scope.ts';
+import { recheck } from './recheck.ts';
+import { type AdoptRow, type PlanView, rowsOf } from './rows.ts';
+import { type Observations, spyContext } from './spy.ts';
+
+export interface VerifyOptions {
+  /** Report every declared row and every pending deletion, not only rows without state. */
+  readonly all?: boolean;
+}
+
+export interface AdoptReport {
+  readonly stack: string;
+  readonly stage: string;
+  /** Resources the stack declares. */
+  readonly declared: number;
+  readonly rows: readonly AdoptRow[];
+}
+
+/** An imported stack and the context it plans under — what `Alchemist.open` returns. */
+export interface VerifySession {
+  readonly stack: CompiledStack<unknown, unknown>;
+  readonly context: Context.Context<unknown>;
+}
+
+/** The plan-node fields `--all` needs to read a row that has state, and the recheck to replay a diff. */
+type StatefulNode = {
+  readonly action: string;
+  readonly provider?: ProviderService;
+  readonly resource: { readonly LogicalId: string };
+  readonly state?: {
+    readonly instanceId: string;
+    readonly props: object;
+    readonly attr: object | undefined;
+  };
+};
+
+/** ⚠️ In the scope Plan.ts gives its own reads (plan-scope.ts). */
+const readWithState = (fqn: string, node: StatefulNode) =>
+  Effect.gen(function* () {
+    const read = node.provider?.read;
+    if (read === undefined || node.state === undefined) return;
+    yield* read({
+      fqn,
+      id: node.resource.LogicalId,
+      instanceId: node.state.instanceId,
+      olds: node.state.props,
+      output: node.state.attr,
+    }).pipe(inPlanScope(fqn, node.state.instanceId));
+  });
+
+/**
+ * Which planned rows plan FROM a resource row the stage's state store holds for them.
+ *
+ * ⚠️ THE ROW MUST BE THE ONE THE NODE PLANS FROM, NOT MERELY A ROW AT THE SAME FQN. Alchemy lets a
+ *   rename hand its old id to a new resource in the same deploy (Rename.ts: `Bucket("Assets")
+ *   .pipe(renamedFrom("Bucket"))` beside a fresh `Bucket("Bucket")`). The store still holds the
+ *   renamer's row at `Bucket`, so a check by FQN alone called the reuser stateful and the default
+ *   report hid its `create`. Matching the node's `state.instanceId` also sees the renamer, whose
+ *   row still sits at its FORMER FQN, as a row without state.
+ */
+const withState = (
+  stack: CompiledStack<unknown, unknown>,
+  nodes: Readonly<Record<string, StatefulNode>>,
+) =>
+  Effect.gen(function* () {
+    const store = yield* yield* State;
+    const found = yield* Effect.all(
+      Object.entries(nodes).map(([fqn, node]) =>
+        store
+          .get({ fqn, stack: stack.name, stage: stack.stage })
+          .pipe(
+            Effect.map((row) =>
+              row === undefined ||
+              isActionState(row) ||
+              (row as { readonly instanceId?: unknown }).instanceId !== node.state?.instanceId
+                ? []
+                : [fqn],
+            ),
+          ),
+      ),
+      { concurrency: 8 },
+    );
+    return new Set(found.flat());
+  });
+
+/**
+ * Plan `session.stack` with watched providers and report each row without state (or, with
+ * `all`, every row). Never writes.
+ */
+export const verifySession = (
+  session: VerifySession,
+  options: VerifyOptions = {},
+): Effect.Effect<AdoptReport, unknown> => {
+  const seen: Observations = new Map();
+  const all = options.all === true;
+  // ⚠️ THE CAST IS AT THE ENGINE'S TYPED BOUNDARY. `Plan.make` declares only `State` and hides the
+  //   rest behind a ts-expect-error; the session context carries all of it, as in routes/stack.ts.
+  const plan = Plan.make(session.stack) as unknown as Effect.Effect<
+    PlanView & { readonly resources: Readonly<Record<string, StatefulNode>> },
+    unknown
+  >;
+  return Effect.gen(function* () {
+    const planned = yield* plan;
+    const stateRows = yield* withState(session.stack, planned.resources);
+    // ★ Before the rows are judged: an adopted `noop` beside a differing read is asked again.
+    yield* Effect.all(
+      Object.entries(planned.resources).map(([fqn, node]) => recheck(fqn, node, seen)),
+      { concurrency: 8 },
+    );
+    if (all) {
+      const stateful = Object.entries(planned.resources).filter(([fqn]) => stateRows.has(fqn));
+      yield* Effect.all(
+        stateful.map(([fqn, node]) =>
+          readWithState(fqn, node).pipe(
+            Effect.catchCause(() =>
+              Effect.sync(() => {
+                const entry = seen.get(fqn) ?? {};
+                entry.read = { answer: 'failed', attributes: undefined };
+                seen.set(fqn, entry);
+              }),
+            ),
+          ),
+        ),
+        { concurrency: 8 },
+      );
+    }
+    return {
+      declared: Object.keys(planned.resources).length,
+      rows: rowsOf(planned, stateRows, seen, all),
+      stack: session.stack.name,
+      stage: session.stack.stage,
+    } satisfies AdoptReport;
+  }).pipe(Effect.provide(spyContext(session.context, seen)), Effect.scoped);
+};
+
+/** Where the stack lives — the fields `alchemy plan` takes as flags. */
+export interface VerifyTarget {
+  /** The stack entrypoint, e.g. `alchemy.run.ts`. */
+  readonly entrypoint: string;
+  readonly stage: string;
+  readonly profile?: string;
+  readonly envFile?: string;
+}
+
+/**
+ * Import the stack the way the Alchemy CLI does and verify it.
+ *
+ * ★ `adopt: true`, ALWAYS, AND IT CANNOT WRITE. Planning is side-effect free (Plan.ts keeps the
+ *   adopted state in memory, alchemy#793), so the flag only lets an `Unowned` row reach its
+ *   `diff` instead of failing the plan — the report marks it, because the real deploy then needs
+ *   `--adopt`. A resource declared `.pipe(adopt(false))` still fails the plan, as it would deploy.
+ */
+export const verifyStack = (
+  target: VerifyTarget,
+  options: VerifyOptions = {},
+): Effect.Effect<AdoptReport, unknown> =>
+  Effect.gen(function* () {
+    const session = yield* Alchemist.open(target, { adopt: true });
+    return yield* verifySession(session, options);
+  }).pipe(Effect.scoped, Effect.provide(Alchemist.layer()));