Merge pull request #1559 from constructive-io/feat/pgpm-package-check

feat(pgpm): `pgpm package --check` — verify committed bundle artifacts are in sync with deploy/

Author: pyramation

pgpm/cli/src/commands/package.ts

@@ -1,6 +1,9 @@
-import { PgpmPackage, writePackage } from '@pgpmjs/core';
+import { checkPackages, PgpmPackage, writePackage } from '@pgpmjs/core';
+import { Logger } from '@pgpmjs/logger';
 import { CLIOptions, Inquirerer, Question } from 'inquirerer';
 
+const log = new Logger('package');
+
 const packageUsageText = `
 Package Command:
 
@@ -17,11 +20,23 @@ Options:
   --bundle                        Also emit sql/<name>--<version>.bundle.tar.gz (default: true)
   --cwd <directory>               Working directory (default: current directory)
 
+Check mode (no writes — verify committed artifacts are in sync with deploy/):
+  --check                         Verify committed sql/<name>--<version>.bundle.tar.gz
+                                  matches deploy/ for changed modules; exit 1 on drift
+  --since <ref>                   Git branch/ref/tag to diff HEAD against for change
+                                  detection (default: PR base in CI, else working tree)
+  --all                           Check every workspace module (skip change detection)
+  --dependents                    Also re-check modules that require a changed module
+  --no-fail-fast                  Report all drifted modules instead of stopping at the first
+
 Examples:
   pgpm package                     Package with defaults
   pgpm package --no-plan           Package without plan
   pgpm package --outputDiff        Package and export AST diff files if mismatch detected
   pgpm package --no-bundle         Package without emitting the bundle artifact
+  pgpm package --check             Verify changed modules' bundles are in sync
+  pgpm package --check --since origin/main   Verify modules changed vs origin/main
+  pgpm package --check --all       Verify every module in the workspace
 `;
 
 export default async (
@@ -34,6 +49,46 @@ export default async (
     console.log(packageUsageText);
     process.exit(0);
   }
+
+  // Check mode: verify committed artifacts, never write.
+  if (argv.check) {
+    const result = await checkPackages({
+      cwd: argv.cwd,
+      since: typeof argv.since === 'string' ? argv.since : undefined,
+      all: argv.all === true,
+      dependents: argv.dependents === true,
+      failFast: argv.failFast !== false,
+    });
+
+    if (argv.all) {
+      log.info(`Checking all ${result.targeted.length} workspace module(s)`);
+    } else {
+      log.info(
+        `Change detection${result.base ? ` vs ${result.base}` : ' (working tree)'}: ` +
+          `${result.changedModules.length} changed module(s)` +
+          (result.targeted.length !== result.changedModules.length
+            ? ` (${result.targeted.length} incl. dependents)`
+            : '')
+      );
+    }
+
+    if (result.drifted.length) {
+      for (const drift of result.drifted) {
+        log.error(`✖ ${drift.name}: ${drift.detail}`);
+      }
+      log.error(
+        `${result.drifted.length} module(s) out of sync. Run \`pgpm package\` in each and commit the artifacts.`
+      );
+      process.exit(1);
+    }
+
+    if (result.checked.length === 0) {
+      log.success('No changed modules to check.');
+    } else {
+      log.success(`${result.checked.length} module(s) in sync.`);
+    }
+    return argv;
+  }
   const questions: Question[] = [
     {
       type: 'confirm',

pgpm/core/__tests__/packaging/check.test.ts

@@ -0,0 +1,129 @@
+import { readFileSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+import {
+  addDependents,
+  checkModuleArtifact,
+  checkPackages,
+  enumerateModules,
+  mapFilesToModules,
+} from '../../src/packaging/check';
+import { resolveBundleArtifactPath, writeBundleArtifact } from '../../src/bundle/artifact';
+import { PgpmPackage } from '../../src/core/class/pgpm';
+import { TestFixture } from '../../test-utils';
+
+const MODULES = ['my-first', 'my-second', 'my-third'] as const;
+
+/**
+ * `pgpm package --check`: verify a committed bundle artifact still matches its
+ * `deploy/`. Read + sha256 only — no DDL, no database — so these are pure,
+ * DB-free unit tests over the fixture workspace.
+ */
+describe('package check (artifact drift verification)', () => {
+  let fixture: TestFixture;
+  let root: string;
+
+  const moduleDir = (name: string): string => fixture.fixturePath('packages', name);
+
+  const emitAll = async (): Promise<void> => {
+    for (const name of MODULES) {
+      const dir = moduleDir(name);
+      const version = require(join(dir, 'package.json')).version as string;
+      await writeBundleArtifact(dir, version);
+    }
+  };
+
+  beforeEach(() => {
+    fixture = new TestFixture('sqitch', 'simple-w-tags');
+    root = fixture.fixturePath();
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('reports no drift for a freshly packaged module', async () => {
+    await emitAll();
+    expect(checkModuleArtifact(moduleDir('my-first'), 'my-first')).toBeNull();
+  });
+
+  it('flags a missing artifact', () => {
+    const drift = checkModuleArtifact(moduleDir('my-first'), 'my-first');
+    expect(drift?.reason).toBe('missing-artifact');
+  });
+
+  it('flags an artifact whose deploy/ has changed (out of sync)', async () => {
+    await emitAll();
+    const dir = moduleDir('my-first');
+    const deployFile = join(dir, 'deploy', 'schema_myfirstapp.sql');
+    writeFileSync(deployFile, `${readFileSync(deployFile, 'utf-8')}\n-- drift\n`);
+
+    const drift = checkModuleArtifact(dir, 'my-first');
+    expect(drift?.reason).toBe('out-of-sync');
+  });
+
+  it('flags a corrupt artifact archive', async () => {
+    await emitAll();
+    writeFileSync(resolveBundleArtifactPath(moduleDir('my-second'))!, 'not-an-archive');
+    const drift = checkModuleArtifact(moduleDir('my-second'), 'my-second');
+    expect(drift?.reason).toBe('unreadable-artifact');
+  });
+
+  it('checkPackages --all verifies every module and passes when in sync', async () => {
+    await emitAll();
+    const result = await checkPackages({ cwd: root, all: true });
+    expect(new Set(result.checked)).toEqual(new Set(MODULES));
+    expect(result.drifted).toHaveLength(0);
+  });
+
+  it('checkPackages --all fails fast on the first drift by default', async () => {
+    await emitAll();
+    // Break two modules; fail-fast should report exactly one.
+    rmSync(resolveBundleArtifactPath(moduleDir('my-first'))!);
+    rmSync(resolveBundleArtifactPath(moduleDir('my-second'))!);
+    const result = await checkPackages({ cwd: root, all: true });
+    expect(result.drifted).toHaveLength(1);
+  });
+
+  it('checkPackages --all --no-fail-fast reports every drifted module', async () => {
+    await emitAll();
+    rmSync(resolveBundleArtifactPath(moduleDir('my-first'))!);
+    rmSync(resolveBundleArtifactPath(moduleDir('my-second'))!);
+    const result = await checkPackages({ cwd: root, all: true, failFast: false });
+    expect(new Set(result.drifted.map((d) => d.name))).toEqual(
+      new Set(['my-first', 'my-second'])
+    );
+  });
+});
+
+describe('package check (workspace mapping helpers)', () => {
+  let fixture: TestFixture;
+  let pkg: PgpmPackage;
+
+  beforeEach(() => {
+    fixture = new TestFixture('sqitch', 'simple-w-tags');
+    pkg = new PgpmPackage(fixture.fixturePath());
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('maps a changed deploy file to its owning module', () => {
+    const modules = enumerateModules(pkg);
+    const changed = [fixture.fixturePath('packages', 'my-second', 'deploy', 'anything.sql')];
+    expect(mapFilesToModules(changed, modules)).toEqual(['my-second']);
+  });
+
+  it('ignores files outside any module', () => {
+    const modules = enumerateModules(pkg);
+    expect(mapFilesToModules([fixture.fixturePath('README.md')], modules)).toEqual([]);
+  });
+
+  it('expands to transitive dependents', () => {
+    // my-third requires my-second requires my-first.
+    const names = new Set(['my-first']);
+    addDependents(names, pkg);
+    expect(names).toEqual(new Set(['my-first', 'my-second', 'my-third']));
+  });
+});

pgpm/core/src/index.ts

@@ -2,6 +2,7 @@ export * from './core/class/pgpm';
 export * from './rebundle';
 export * from './extensions';
 export * from './modules/modules';
+export * from './packaging/check';
 export * from './packaging/package';
 export * from './packaging/sync-versions';
 export * from './packaging/transform';