@intentius/chant 0.13.1 → 0.15.1

package/src/codegen/rolling-upgrade.test.ts

@@ -0,0 +1,333 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  checkRollingUpgrade,
+  classifyDelta,
+  diffRollingSurface,
+  computeAzureApiVersionDelta,
+  extractAzureProvider,
+  diffAzureApiVersions,
+} from "./rolling-upgrade";
+import type { SurfaceSnapshot } from "./surface-snapshot";
+import type { RegenResult, RegenOptions } from "./lexicon-regen";
+import { diffSurface } from "./surface-snapshot";
+
+// ── Fixture snapshots ─────────────────────────────────────────────────
+
+function baselineAws(): SurfaceSnapshot {
+  return {
+    schemaVersion: 1,
+    generatedAt: "2026-01-01T00:00:00.000Z",
+    entries: {
+      Bucket: {
+        kind: "resource",
+        resourceType: "AWS::S3::Bucket",
+        attrs: ["Arn"],
+        props: ["BucketName:false", "Tags:false"],
+        taggable: true,
+      },
+      Bucket_Tag: { kind: "property", resourceType: "AWS::S3::Bucket.Tag" },
+    },
+  };
+}
+
+/** Adds a new resource → additive upgrade. */
+function freshAwsAdditive(): SurfaceSnapshot {
+  const s = baselineAws();
+  s.entries.Table = {
+    kind: "resource",
+    resourceType: "AWS::DynamoDB::Table",
+    attrs: ["Arn"],
+    props: ["TableName:false"],
+    taggable: true,
+  };
+  return s;
+}
+
+/** Removes a resource → breaking upgrade. */
+function freshAwsBreaking(): SurfaceSnapshot {
+  const s = baselineAws();
+  delete s.entries.Bucket_Tag;
+  return s;
+}
+
+function azureBaseline(): SurfaceSnapshot {
+  return {
+    schemaVersion: 1,
+    generatedAt: "2026-01-01T00:00:00.000Z",
+    entries: {
+      StorageAccount: {
+        kind: "resource",
+        resourceType: "Microsoft.Storage/storageAccounts",
+        props: ["name:true"],
+      },
+      VirtualMachine: {
+        kind: "resource",
+        resourceType: "Microsoft.Compute/virtualMachines",
+        props: ["name:true"],
+      },
+    },
+  };
+}
+
+/** Adds a resource from a brand-new provider. */
+function azureFreshNewProvider(): SurfaceSnapshot {
+  const s = azureBaseline();
+  s.entries.Vault = {
+    kind: "resource",
+    resourceType: "Microsoft.KeyVault/vaults",
+    props: ["name:true"],
+  };
+  return s;
+}
+
+// ── Mock regen ────────────────────────────────────────────────────────
+
+function makeRegen(
+  fresh: SurfaceSnapshot | null,
+  baseline: SurfaceSnapshot,
+  ok = true,
+): (opts: RegenOptions) => Promise<RegenResult> {
+  return async () => {
+    const delta = fresh
+      ? diffSurface(baseline, fresh)
+      : { added: [], changed: [], removed: [], severity: "none" as const };
+    const changed =
+      delta.added.length > 0 || delta.changed.length > 0 || delta.removed.length > 0;
+    return {
+      ok,
+      changed,
+      severity: delta.severity,
+      delta,
+      deltaText: changed ? "delta" : "",
+      failures: ok ? [] : [{ step: "generate", output: "boom" }],
+      freshSnapshot: fresh,
+    };
+  };
+}
+
+// ── Test dir helper ───────────────────────────────────────────────────
+
+/** Create a fake lexicon dir with a package.json and committed baseline snapshot. */
+function makeLexiconDir(name: string, baseline: SurfaceSnapshot): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-rolling-"));
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({ name: `@intentius/chant-lexicon-${name}` }),
+  );
+  writeFileSync(join(dir, "surface.snapshot.json"), JSON.stringify(baseline, null, 2));
+  mkdirSync(join(dir, "src", "generated"), { recursive: true });
+  return dir;
+}
+
+// ── classifyDelta (pure) ──────────────────────────────────────────────
+
+describe("classifyDelta", () => {
+  test("unchanged surface → no upgrade, none severity", () => {
+    const delta = diffRollingSurface(baselineAws(), baselineAws());
+    expect(classifyDelta(delta)).toEqual({ hasUpgrade: false, severity: "none" });
+  });
+
+  test("added resource → upgrade, additive severity", () => {
+    const delta = diffRollingSurface(baselineAws(), freshAwsAdditive());
+    expect(classifyDelta(delta)).toEqual({ hasUpgrade: true, severity: "additive" });
+  });
+
+  test("removed resource → upgrade, breaking severity", () => {
+    const delta = diffRollingSurface(baselineAws(), freshAwsBreaking());
+    const c = classifyDelta(delta);
+    expect(c.hasUpgrade).toBe(true);
+    expect(c.severity).toBe("breaking");
+  });
+});
+
+// ── checkRollingUpgrade (mocked regen) ────────────────────────────────
+
+describe("checkRollingUpgrade — surface changed vs unchanged", () => {
+  test("unchanged surface → hasUpgrade false", async () => {
+    const dir = makeLexiconDir("aws", baselineAws());
+    try {
+      const res = await checkRollingUpgrade({
+        lexiconDir: dir,
+        _regenFn: makeRegen(baselineAws(), baselineAws()),
+      });
+      expect(res.lexicon).toBe("aws");
+      expect(res.hasUpgrade).toBe(false);
+      expect(res.severity).toBe("none");
+      expect(res.validationOk).toBe(true);
+      expect(res.deltaText).toBe("");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("additive surface change → hasUpgrade true, additive", async () => {
+    const dir = makeLexiconDir("aws", baselineAws());
+    try {
+      const res = await checkRollingUpgrade({
+        lexiconDir: dir,
+        _regenFn: makeRegen(freshAwsAdditive(), baselineAws()),
+      });
+      expect(res.hasUpgrade).toBe(true);
+      expect(res.severity).toBe("additive");
+      expect(res.delta.added.map((a) => a.name)).toContain("Table");
+      expect(res.deltaText).not.toBe("");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("breaking surface change → hasUpgrade true, breaking", async () => {
+    const dir = makeLexiconDir("aws", baselineAws());
+    try {
+      const res = await checkRollingUpgrade({
+        lexiconDir: dir,
+        _regenFn: makeRegen(freshAwsBreaking(), baselineAws()),
+      });
+      expect(res.hasUpgrade).toBe(true);
+      expect(res.severity).toBe("breaking");
+      expect(res.delta.removed.map((r) => r.name)).toContain("Bucket_Tag");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("failed regen surfaces validationOk=false and failures", async () => {
+    const dir = makeLexiconDir("aws", baselineAws());
+    try {
+      const res = await checkRollingUpgrade({
+        lexiconDir: dir,
+        _regenFn: makeRegen(freshAwsAdditive(), baselineAws(), false),
+      });
+      expect(res.validationOk).toBe(false);
+      expect(res.failures.length).toBeGreaterThan(0);
+      // Still reports the delta so the failure carries the diff
+      expect(res.hasUpgrade).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ── azure lexicon detection + apiVersionDelta ─────────────────────────
+
+describe("checkRollingUpgrade — azure", () => {
+  test("detects azure lexicon by package name", async () => {
+    const dir = makeLexiconDir("azure", azureBaseline());
+    try {
+      const res = await checkRollingUpgrade({
+        lexiconDir: dir,
+        _regenFn: makeRegen(azureBaseline(), azureBaseline()),
+      });
+      expect(res.lexicon).toBe("azure");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("new provider shows up in apiVersionDelta", async () => {
+    const dir = makeLexiconDir("azure", azureBaseline());
+    try {
+      const res = await checkRollingUpgrade({
+        lexiconDir: dir,
+        _regenFn: makeRegen(azureFreshNewProvider(), azureBaseline()),
+      });
+      expect(res.hasUpgrade).toBe(true);
+      const kv = res.apiVersionDelta.find((c) => c.provider === "Microsoft.KeyVault");
+      expect(kv).toBeDefined();
+      expect(kv!.kind).toBe("added");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("aws has empty apiVersionDelta", async () => {
+    const dir = makeLexiconDir("aws", baselineAws());
+    try {
+      const res = await checkRollingUpgrade({
+        lexiconDir: dir,
+        _regenFn: makeRegen(freshAwsAdditive(), baselineAws()),
+      });
+      expect(res.apiVersionDelta).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ── extractAzureProvider (pure) ───────────────────────────────────────
+
+describe("extractAzureProvider", () => {
+  test("extracts provider from resourceType", () => {
+    expect(extractAzureProvider("Microsoft.Storage/storageAccounts")).toBe("Microsoft.Storage");
+    expect(extractAzureProvider("Microsoft.Compute/virtualMachines/extensions")).toBe(
+      "Microsoft.Compute",
+    );
+  });
+
+  test("returns null for non-ARM types", () => {
+    expect(extractAzureProvider("AWS::S3::Bucket")).toBeNull();
+    expect(extractAzureProvider("")).toBeNull();
+    expect(extractAzureProvider("Microsoft.Storage")).toBeNull();
+  });
+});
+
+// ── computeAzureApiVersionDelta (pure) ────────────────────────────────
+
+describe("computeAzureApiVersionDelta", () => {
+  test("reports added and removed providers", () => {
+    const delta = computeAzureApiVersionDelta(azureBaseline(), azureFreshNewProvider());
+    expect(delta).toHaveLength(1);
+    expect(delta[0]).toMatchObject({ provider: "Microsoft.KeyVault", kind: "added" });
+  });
+
+  test("no change when providers identical", () => {
+    expect(computeAzureApiVersionDelta(azureBaseline(), azureBaseline())).toEqual([]);
+  });
+
+  test("reports removed provider", () => {
+    const shrunk: SurfaceSnapshot = {
+      ...azureBaseline(),
+      entries: { StorageAccount: azureBaseline().entries.StorageAccount },
+    };
+    const delta = computeAzureApiVersionDelta(azureBaseline(), shrunk);
+    expect(delta).toEqual([
+      { provider: "Microsoft.Compute", before: "latest", after: null, kind: "removed" },
+    ]);
+  });
+});
+
+// ── diffAzureApiVersions (pure) ───────────────────────────────────────
+
+describe("diffAzureApiVersions", () => {
+  test("detects version bump as updated", () => {
+    const base = new Map([["Microsoft.Compute", "2022-03-01"]]);
+    const fresh = new Map([["Microsoft.Compute", "2023-07-01"]]);
+    const delta = diffAzureApiVersions(base, fresh);
+    expect(delta).toEqual([
+      {
+        provider: "Microsoft.Compute",
+        before: "2022-03-01",
+        after: "2023-07-01",
+        kind: "updated",
+      },
+    ]);
+  });
+
+  test("detects added and removed providers", () => {
+    const base = new Map([["Microsoft.Old", "2020-01-01"]]);
+    const fresh = new Map([["Microsoft.New", "2024-01-01"]]);
+    const delta = diffAzureApiVersions(base, fresh);
+    expect(delta).toEqual([
+      { provider: "Microsoft.New", before: null, after: "2024-01-01", kind: "added" },
+      { provider: "Microsoft.Old", before: "2020-01-01", after: null, kind: "removed" },
+    ]);
+  });
+
+  test("no change when versions identical", () => {
+    const m = new Map([["Microsoft.Storage", "2023-01-01"]]);
+    expect(diffAzureApiVersions(m, new Map(m))).toEqual([]);
+  });
+});

package/src/codegen/rolling-upgrade.ts

@@ -0,0 +1,320 @@
+/**
+ * Rolling-spec drift detection for aws, azure, and github lexicons.
+ *
+ * These lexicons have no pinned version constant — "latest" is fetched on every
+ * regen. An upgrade means regenerating from current-latest and diffing the
+ * produced API surface against the committed baseline (surface.snapshot.json).
+ * If the surface changed and validation passed, a PR can be opened with the
+ * delta as the review payload.
+ *
+ * This module contains only pure business logic (detecting drift, classifying
+ * it, formatting the report). It calls regenLexicon from #524 for the actual
+ * regen/validate work, and never runs a live regen itself.
+ *
+ * azure extra delta:
+ *   The Azure regen depends on `latestVersionPerProvider`, which picks one API
+ *   version per ARM provider. When new providers appear or existing ones get a
+ *   newer GA/preview version, that shows up in the surface diff. In addition,
+ *   this module computes an `apiVersionDelta` to surface those version changes
+ *   separately, so reviewers can see "Microsoft.Compute moved 2022-03-01 →
+ *   2023-07-01" without reading the raw surface diff.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import {
+  diffSurface,
+  formatDelta,
+  parseSnapshot,
+  type SurfaceDelta,
+  type ChangeSeverity,
+  type SurfaceSnapshot,
+} from "./surface-snapshot";
+import { regenLexicon, SNAPSHOT_FILENAME, type RegenOptions, type RegenResult } from "./lexicon-regen";
+
+// ── Public types ──────────────────────────────────────────────────────
+
+export type RollingLexicon = "aws" | "azure" | "github";
+
+/**
+ * An API-version change for one Azure ARM provider.
+ * Only populated for the azure lexicon.
+ */
+export interface AzureApiVersionChange {
+  provider: string;
+  before: string | null;
+  after: string | null;
+  /** "added" when provider is new; "updated" when version bumped; "removed" when gone. */
+  kind: "added" | "updated" | "removed";
+}
+
+/**
+ * The result of a rolling-upgrade check for one lexicon.
+ */
+export interface RollingUpgradeResult {
+  /** Lexicon identifier. */
+  lexicon: RollingLexicon;
+  /** True when the surface changed versus the committed baseline. */
+  hasUpgrade: boolean;
+  /** Severity of the surface delta. "none" when the surface is unchanged. */
+  severity: ChangeSeverity;
+  /** Structured surface delta. */
+  delta: SurfaceDelta;
+  /** Human-readable delta text. Empty when no changes. */
+  deltaText: string;
+  /** Whether regen+validation passed. False means the delta is unreliable. */
+  validationOk: boolean;
+  /** Failures captured during regen. */
+  failures: RegenResult["failures"];
+  /** azure-only: per-provider API version changes. Empty for aws/github. */
+  apiVersionDelta: AzureApiVersionChange[];
+  /** The fresh snapshot produced by the regen. Null when regen failed. */
+  freshSnapshot: SurfaceSnapshot | null;
+}
+
+/**
+ * Options for checkRollingUpgrade.
+ */
+export interface CheckRollingUpgradeOptions {
+  /** Root of the lexicon package (must contain package.json and surface.snapshot.json). */
+  lexiconDir: string;
+  /** Force re-fetch of the upstream spec (bypass cache). Default: false. */
+  force?: boolean;
+  /** Print subprocess output while running. Default: false. */
+  verbose?: boolean;
+  /**
+   * Override for the regen function — inject a mock in tests.
+   * Defaults to the production regenLexicon.
+   */
+  _regenFn?: (opts: RegenOptions) => Promise<RegenResult>;
+}
+
+// ── Main entry ────────────────────────────────────────────────────────
+
+/**
+ * Check whether the rolling spec has drifted since the committed baseline.
+ *
+ * Calls regenLexicon (from #524) to regenerate from current-latest, then diffs
+ * the resulting surface against the committed surface.snapshot.json. Returns
+ * hasUpgrade=true when the surface changed and validation passed.
+ *
+ * For azure, also computes an apiVersionDelta showing which ARM providers gained
+ * a new latest API version since the baseline was snapshotted.
+ *
+ * Never throws — all failures are captured in the result.
+ */
+export async function checkRollingUpgrade(
+  opts: CheckRollingUpgradeOptions,
+): Promise<RollingUpgradeResult> {
+  const {
+    lexiconDir,
+    force = false,
+    verbose = false,
+    _regenFn = regenLexicon,
+  } = opts;
+
+  const lexicon = detectLexicon(lexiconDir);
+
+  const regenResult = await _regenFn({
+    lexiconDir,
+    force,
+    verbose,
+    skipBundle: false,
+    skipBuild: false,
+    skipLint: false,
+    skipExamples: true,
+  });
+
+  const apiVersionDelta: AzureApiVersionChange[] = [];
+
+  if (lexicon === "azure" && regenResult.freshSnapshot) {
+    const baselinePath = join(lexiconDir, SNAPSHOT_FILENAME);
+    if (existsSync(baselinePath)) {
+      try {
+        const baselineJSON = readFileSync(baselinePath, "utf-8");
+        const baseline = parseSnapshot(baselineJSON);
+        apiVersionDelta.push(...computeAzureApiVersionDelta(baseline, regenResult.freshSnapshot));
+      } catch {
+        // Ignore — apiVersionDelta stays empty; the surface diff is still valid
+      }
+    }
+  }
+
+  return buildResult(lexicon, regenResult, apiVersionDelta);
+}
+
+// ── Lexicon detection ─────────────────────────────────────────────────
+
+/**
+ * Detect which rolling lexicon a directory belongs to by its package name.
+ * Falls back to directory-name matching.
+ */
+function detectLexicon(lexiconDir: string): RollingLexicon {
+  try {
+    const pkgPath = join(lexiconDir, "package.json");
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { name?: string };
+      const name = pkg.name ?? "";
+      if (name.includes("azure")) return "azure";
+      if (name.includes("github")) return "github";
+    }
+  } catch {
+    // Fall through to directory-based detection
+  }
+
+  const normalized = lexiconDir.replace(/\\/g, "/");
+  if (/\/azure(\/|$)/.test(normalized)) return "azure";
+  if (/\/github(\/|$)/.test(normalized)) return "github";
+  return "aws";
+}
+
+// ── Azure API-version delta ───────────────────────────────────────────
+
+/**
+ * Compute provider-level additions and removals between two azure snapshots.
+ *
+ * The snapshot resourceType values for azure look like
+ * "Microsoft.Storage/storageAccounts". This function extracts the provider
+ * name (the part before the first "/") and reports which providers appeared,
+ * disappeared, or (when version strings are supplied via diffAzureApiVersions)
+ * bumped their API version.
+ *
+ * Use diffAzureApiVersions when you have access to actual API version strings
+ * (e.g. from the lexicon's latestVersionPerProvider output in a CI run).
+ */
+export function computeAzureApiVersionDelta(
+  baseline: SurfaceSnapshot,
+  fresh: SurfaceSnapshot,
+): AzureApiVersionChange[] {
+  const baseProviders = new Set<string>();
+  const freshProviders = new Set<string>();
+
+  for (const entry of Object.values(baseline.entries)) {
+    const p = extractAzureProvider(entry.resourceType);
+    if (p) baseProviders.add(p);
+  }
+
+  for (const entry of Object.values(fresh.entries)) {
+    const p = extractAzureProvider(entry.resourceType);
+    if (p) freshProviders.add(p);
+  }
+
+  const changes: AzureApiVersionChange[] = [];
+
+  for (const p of freshProviders) {
+    if (!baseProviders.has(p)) {
+      changes.push({ provider: p, before: null, after: "latest", kind: "added" });
+    }
+  }
+
+  for (const p of baseProviders) {
+    if (!freshProviders.has(p)) {
+      changes.push({ provider: p, before: "latest", after: null, kind: "removed" });
+    }
+  }
+
+  return changes.sort((a, b) => a.provider.localeCompare(b.provider));
+}
+
+/**
+ * Extract the Azure ARM provider name from a resourceType string.
+ *
+ * Input:  "Microsoft.Storage/storageAccounts"
+ * Output: "Microsoft.Storage"
+ *
+ * Returns null for non-ARM resource types (e.g. empty string or non-Microsoft prefix).
+ */
+export function extractAzureProvider(resourceType: string): string | null {
+  if (!resourceType.startsWith("Microsoft.")) return null;
+  const slash = resourceType.indexOf("/");
+  if (slash === -1) return null;
+  return resourceType.slice(0, slash);
+}
+
+/**
+ * Diff actual API version strings per provider between two regen runs.
+ *
+ * Use this when the caller has access to the azure lexicon's
+ * latestVersionPerProvider output. Produces a richer delta that includes
+ * version bumps ("updated"), not just provider additions/removals.
+ *
+ * @param baseVersions  Map<provider, apiVersion> from the previous regen.
+ * @param freshVersions Map<provider, apiVersion> from the current regen.
+ */
+export function diffAzureApiVersions(
+  baseVersions: Map<string, string>,
+  freshVersions: Map<string, string>,
+): AzureApiVersionChange[] {
+  const changes: AzureApiVersionChange[] = [];
+
+  for (const [provider, freshVersion] of freshVersions) {
+    const baseVersion = baseVersions.get(provider) ?? null;
+    if (baseVersion === null) {
+      changes.push({ provider, before: null, after: freshVersion, kind: "added" });
+    } else if (baseVersion !== freshVersion) {
+      changes.push({ provider, before: baseVersion, after: freshVersion, kind: "updated" });
+    }
+  }
+
+  for (const [provider, baseVersion] of baseVersions) {
+    if (!freshVersions.has(provider)) {
+      changes.push({ provider, before: baseVersion, after: null, kind: "removed" });
+    }
+  }
+
+  return changes.sort((a, b) => a.provider.localeCompare(b.provider));
+}
+
+// ── Pure decision functions ───────────────────────────────────────────
+
+/**
+ * Diff two surface snapshots.
+ *
+ * Pure function re-exported for callers that import rolling-upgrade and want to
+ * compute the delta without importing surface-snapshot directly.
+ */
+export function diffRollingSurface(
+  baseline: SurfaceSnapshot,
+  fresh: SurfaceSnapshot,
+): SurfaceDelta {
+  return diffSurface(baseline, fresh);
+}
+
+/**
+ * Classify a delta as an upgrade and determine its severity.
+ *
+ * Pure function — no I/O. Unit-testable with fixture snapshots.
+ * Used by the CLI and the checkRollingUpgrade entry point.
+ */
+export function classifyDelta(delta: SurfaceDelta): {
+  hasUpgrade: boolean;
+  severity: ChangeSeverity;
+} {
+  const hasUpgrade =
+    delta.added.length > 0 || delta.changed.length > 0 || delta.removed.length > 0;
+  return { hasUpgrade, severity: hasUpgrade ? delta.severity : "none" };
+}
+
+// ── Result builder ────────────────────────────────────────────────────
+
+function buildResult(
+  lexicon: RollingLexicon,
+  regenResult: RegenResult,
+  apiVersionDelta: AzureApiVersionChange[],
+): RollingUpgradeResult {
+  const delta = regenResult.delta;
+  const { hasUpgrade, severity } = classifyDelta(delta);
+  const deltaText = hasUpgrade ? formatDelta(delta) : "";
+
+  return {
+    lexicon,
+    hasUpgrade,
+    severity,
+    delta,
+    deltaText,
+    validationOk: regenResult.ok,
+    failures: regenResult.failures,
+    apiVersionDelta,
+    freshSnapshot: regenResult.freshSnapshot,
+  };
+}