@ultimat3/manifest 3.0.0 → 4.0.0

package/src/diff-registries.ts

@@ -0,0 +1,116 @@
+// The two declaration registries: `policies` (a permission, where it is enforced) and
+// `errorCodes` (a code, the package that owns it). Both are keyed by a string a consumer matches
+// on — a permission it grants, a code it branches on — so losing an entry is breaking and the
+// metadata beside it is internal.
+
+import type { ManifestChange } from './diff-change';
+import { diffScalar, index } from './diff-change';
+import type { ErrorCodeFact, PolicyFact } from './schema';
+
+export function diffPolicies(
+  before: readonly PolicyFact[],
+  after: readonly PolicyFact[],
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const afterByName = index(after, (p) => p.permission);
+  const beforeByName = index(before, (p) => p.permission);
+
+  for (const policy of before) {
+    const next = afterByName.get(policy.permission);
+    const path = `policies.${policy.permission}`;
+    if (next === undefined) {
+      // The rule this permission names is enforced nowhere now; an actor holding the grant is
+      // the only thing left that still believes in it.
+      changes.push({ kind: 'breaking', path, detail: 'policy removed' });
+      continue;
+    }
+    changes.push(
+      ...diffScalar(
+        'internal',
+        `${path}.description`,
+        policy.description,
+        next.description,
+        (from, to) => `description "${from}" -> "${to}"`,
+      ),
+    );
+    // Same direction as an operation's permissions: a NEW enforcement site refuses callers that
+    // reached that surface yesterday; one dropped widens access and is reported, never fatal.
+    changes.push(...diffEnforcedIn(path, policy.enforcedIn, next.enforcedIn));
+  }
+  for (const policy of after) {
+    if (!beforeByName.has(policy.permission)) {
+      changes.push({
+        kind: 'additive',
+        path: `policies.${policy.permission}`,
+        detail: 'policy added',
+      });
+    }
+  }
+  return changes;
+}
+
+function diffEnforcedIn(
+  path: string,
+  before: readonly string[],
+  after: readonly string[],
+): readonly ManifestChange[] {
+  const beforeSet = new Set(before);
+  const afterSet = new Set(after);
+  return [
+    ...after
+      .filter((site) => !beforeSet.has(site))
+      .map((site) => ({
+        kind: 'breaking' as const,
+        path: `${path}.enforcedIn.${site}`,
+        detail: 'now enforced here; callers that reached this surface are refused',
+      })),
+    ...before
+      .filter((site) => !afterSet.has(site))
+      .map((site) => ({
+        kind: 'additive' as const,
+        path: `${path}.enforcedIn.${site}`,
+        detail: 'no longer enforced here; access widened',
+      })),
+  ];
+}
+
+export function diffErrorCodes(
+  before: readonly ErrorCodeFact[],
+  after: readonly ErrorCodeFact[],
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const afterByCode = index(after, (e) => e.code);
+  const beforeByCode = index(before, (e) => e.code);
+
+  for (const fact of before) {
+    const next = afterByCode.get(fact.code);
+    const path = `errorCodes.${fact.code}`;
+    if (next === undefined) {
+      // A code is stable forever once shipped — every `catch` matching on it, every runbook and
+      // every `x errors explain` argument stops resolving the moment it leaves the file.
+      changes.push({ kind: 'breaking', path, detail: 'error code removed' });
+      continue;
+    }
+    // Which package declares it is a fact about the framework, not about the caller: the code
+    // string is what anyone matches on, and it did not move.
+    changes.push(
+      ...diffScalar(
+        'internal',
+        `${path}.package`,
+        fact.package,
+        next.package,
+        (from, to) => `owner ${from} -> ${to}`,
+      ),
+    );
+  }
+  for (const fact of after) {
+    if (!beforeByCode.has(fact.code)) {
+      changes.push({
+        kind: 'additive',
+        path: `errorCodes.${fact.code}`,
+        detail: 'error code added',
+      });
+    }
+  }
+  return changes;
+}

package/src/diff-routes.ts

@@ -0,0 +1,93 @@
+// Routes: the URL and what it serves. `surface` is the contract — a URL that answered HTML and
+// now answers JSON breaks every link to it — while the delivery facts (`render`, `offline`,
+// `hydrate`, `budget`, `revalidateTags`) are internal and reported.
+
+import { canonical } from './build';
+import type { ManifestChange } from './diff-change';
+import { diffScalar, index } from './diff-change';
+import type { RouteFact } from './schema';
+
+export function diffRoutes(
+  before: readonly RouteFact[],
+  after: readonly RouteFact[],
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const afterByUrl = index(after, (r) => r.url);
+  const beforeByUrl = index(before, (r) => r.url);
+
+  for (const route of before) {
+    const next = afterByUrl.get(route.url);
+    const path = `routes.${route.url}`;
+    if (next === undefined) {
+      // A removed URL is a 404 for anyone holding a link to it.
+      changes.push({ kind: 'breaking', path, detail: 'route removed' });
+      continue;
+    }
+    // `site`, `app` and `api` are three different promises about one URL: a page becoming an API
+    // route stops rendering HTML for every crawler and bookmark pointing at it.
+    changes.push(
+      ...diffScalar(
+        'breaking',
+        `${path}.surface`,
+        route.surface,
+        next.surface,
+        (from, to) => `surface ${from} -> ${to}`,
+      ),
+    );
+    // The delivery facts, each with its own path so a reviewer sees WHICH one moved. Every one is
+    // optional in the file, and `diffScalar` skips a side that carries nothing: a manifest written
+    // before a field existed must not report every route as changed the first time it is diffed.
+    changes.push(
+      ...diffScalar(
+        'internal',
+        `${path}.render`,
+        route.render,
+        next.render,
+        (from, to) => `render ${from} -> ${to}`,
+      ),
+      ...diffScalar(
+        'internal',
+        `${path}.offline`,
+        route.offline,
+        next.offline,
+        (from, to) => `offline ${from} -> ${to}`,
+      ),
+      ...diffScalar(
+        'internal',
+        `${path}.hydrate`,
+        route.hydrate,
+        next.hydrate,
+        (from, to) => `hydrate ${from} -> ${to}`,
+      ),
+    );
+    changes.push(...diffJson('internal', `${path}.budget`, route.budget, next.budget, 'changed'));
+    changes.push(
+      ...diffJson(
+        'internal',
+        `${path}.revalidateTags`,
+        route.revalidateTags,
+        next.revalidateTags,
+        'revalidate tags changed',
+      ),
+    );
+  }
+  for (const route of after) {
+    if (!beforeByUrl.has(route.url)) {
+      changes.push({ kind: 'additive', path: `routes.${route.url}`, detail: 'route added' });
+    }
+  }
+  return changes;
+}
+
+/** The structural sibling of `diffScalar`: absent on either side is still no evidence. */
+function diffJson(
+  kind: ManifestChange['kind'],
+  path: string,
+  before: unknown,
+  after: unknown,
+  detail: string,
+): readonly ManifestChange[] {
+  if (before === undefined || after === undefined) return [];
+  if (canonical(before) === canonical(after)) return [];
+  return [{ kind, path, detail }];
+}

package/src/diff-work.ts

@@ -0,0 +1,131 @@
+// Background work: `jobs` (enqueued) and `tasks` (scheduled). Both fail the same silent way —
+// nothing throws, the work simply stops happening — which is why a removal on either side is
+// breaking rather than a note in the diff.
+
+import { canonical } from './build';
+import type { ManifestChange } from './diff-change';
+import { diffScalar, index } from './diff-change';
+import type { JobFact, TaskFact } from './schema';
+
+export function diffJobs(
+  before: readonly JobFact[],
+  after: readonly JobFact[],
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const afterByName = index(after, (j) => j.name);
+  const beforeByName = index(before, (j) => j.name);
+
+  for (const job of before) {
+    const next = afterByName.get(job.name);
+    const path = `jobs.${job.name}`;
+    if (next === undefined) {
+      // Enqueued-but-undeliverable work is silent data loss, so a removal is breaking.
+      changes.push({ kind: 'breaking', path, detail: 'job removed' });
+      continue;
+    }
+    if (canonical(job.input) !== canonical(next.input)) {
+      changes.push({
+        kind: 'breaking',
+        path: `${path}.input`,
+        detail: 'input schema changed; in-flight payloads will not parse',
+      });
+    }
+    // The same failure as a removal, from the worker's side: a fleet subscribed to the old queue
+    // keeps running and stops receiving this job, and the rows pile up where nobody drains them.
+    changes.push(
+      ...diffScalar(
+        'breaking',
+        `${path}.queue`,
+        job.queue,
+        next.queue,
+        (from, to) => `queue ${from} -> ${to}; workers bound to ${from} stop receiving it`,
+      ),
+    );
+    changes.push(...diffRetry(path, job, next));
+    if (canonical(job.steps) !== canonical(next.steps)) {
+      changes.push({
+        kind: 'internal',
+        path: `${path}.steps`,
+        detail: 'steps changed; resumed runs may replay differently',
+      });
+    }
+  }
+  for (const job of after) {
+    if (!beforeByName.has(job.name)) {
+      changes.push({ kind: 'additive', path: `jobs.${job.name}`, detail: 'job added' });
+    }
+  }
+  return changes;
+}
+
+/**
+ * Attempts are a durability promise: work that survived a provider blip at 5 attempts
+ * dead-letters at 1, and nothing else in the manifest moves when that number does. Backoff only
+ * changes the spacing between the same attempts, so it is internal.
+ */
+function diffRetry(path: string, before: JobFact, after: JobFact): readonly ManifestChange[] {
+  const declared: unknown = before.retry;
+  const next: unknown = after.retry;
+  if (typeof declared !== 'object' || declared === null) return [];
+  if (typeof next !== 'object' || next === null) return [];
+  const from = (declared as Record<string, unknown>)['attempts'];
+  const to = (next as Record<string, unknown>)['attempts'];
+  const changes: ManifestChange[] = [];
+
+  if (typeof from === 'number' && typeof to === 'number' && from !== to) {
+    changes.push({
+      kind: to < from ? 'breaking' : 'additive',
+      path: `${path}.retry.attempts`,
+      detail:
+        to < from
+          ? `attempts ${from} -> ${to}; a transient failure this survived now dead-letters`
+          : `attempts ${from} -> ${to}`,
+    });
+  }
+  changes.push(
+    ...diffScalar(
+      'internal',
+      `${path}.retry.backoff`,
+      (declared as Record<string, unknown>)['backoff'],
+      (next as Record<string, unknown>)['backoff'],
+      (a, b) => `backoff ${a} -> ${b}`,
+    ),
+  );
+  return changes;
+}
+
+export function diffTasks(
+  before: readonly TaskFact[],
+  after: readonly TaskFact[],
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const afterByName = index(after, (t) => t.name);
+  const beforeByName = index(before, (t) => t.name);
+
+  for (const task of before) {
+    const next = afterByName.get(task.name);
+    const path = `tasks.${task.name}`;
+    if (next === undefined) {
+      // Nothing throws when a schedule disappears — the work simply never runs again.
+      changes.push({ kind: 'breaking', path, detail: 'task removed' });
+      continue;
+    }
+    // WHEN it runs is not a caller's contract, but it is the fact an operator reads this file
+    // for, and a zone change moves every fire time without touching the expression beside it.
+    changes.push(
+      ...diffScalar('internal', `${path}.cron`, task.cron, next.cron, (a, b) => `${a} -> ${b}`),
+    );
+    changes.push(
+      ...diffScalar('internal', `${path}.tz`, task.tz, next.tz, (a, b) => `${a} -> ${b}`),
+    );
+    if (canonical(task.enqueues) !== canonical(next.enqueues)) {
+      changes.push({ kind: 'internal', path: `${path}.enqueues`, detail: 'enqueued jobs changed' });
+    }
+  }
+  for (const task of after) {
+    if (!beforeByName.has(task.name)) {
+      changes.push({ kind: 'additive', path: `tasks.${task.name}`, detail: 'task added' });
+    }
+  }
+  return changes;
+}