@pgpmjs/core 6.32.1 → 6.33.0

package/esm/files/sql/header.js

@@ -0,0 +1,259 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { parsePlanFile } from '../plan/parser';
+import { parseReference } from '../plan/validators';
+const HEADER_LINE = /^--\s*(Deploy|Revert|Verify)\b(:)?\s*(.*?)\s*$/;
+const REQUIRES_LINE = /^--\s*requires:\s*(.*?)\s*$/;
+const COMMENT_LINE = /^\s*--/;
+const TO_PG_SUFFIX = /\s+to\s+pg\s*$/;
+/**
+ * Parse the header block of a pgpm SQL script into a structured model.
+ *
+ * Recognizes both header formats:
+ *   `-- Deploy <project>:<change> to pg` (legacy sqitch-compatible)
+ *   `-- Deploy <change>` / `-- Deploy: <change>` (new)
+ * along with `-- requires: <ref>` lines where `<ref>` may be a plain change
+ * name, `{package}:{change}`, `@tag`, or `{package}:@tag`.
+ *
+ * The parse is lossless: `header.lines` plus `body` reassemble the original
+ * content byte-exactly (see {@link writePgpmScript}).
+ */
+export function parsePgpmHeader(content) {
+    const header = {
+        verb: null,
+        project: null,
+        change: null,
+        toPg: false,
+        requires: [],
+        lines: []
+    };
+    const lines = content.split('\n');
+    let lastHeaderIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === '') {
+            continue;
+        }
+        if (!COMMENT_LINE.test(line)) {
+            break;
+        }
+        const headerMatch = line.match(HEADER_LINE);
+        if (headerMatch && header.verb === null) {
+            header.verb = headerMatch[1];
+            let target = headerMatch[3];
+            if (TO_PG_SUFFIX.test(target)) {
+                header.toPg = true;
+                target = target.replace(TO_PG_SUFFIX, '');
+            }
+            const colonIndex = target.indexOf(':');
+            if (colonIndex > 0 && /^[a-zA-Z0-9_-]+$/.test(target.substring(0, colonIndex))) {
+                header.project = target.substring(0, colonIndex);
+                header.change = target.substring(colonIndex + 1).trim();
+            }
+            else {
+                header.change = target.trim() || null;
+            }
+            lastHeaderIdx = i;
+            continue;
+        }
+        const requiresMatch = line.match(REQUIRES_LINE);
+        if (requiresMatch) {
+            const raw = requiresMatch[1];
+            header.requires.push({ raw, ref: parseReference(raw) });
+            lastHeaderIdx = i;
+            continue;
+        }
+        // Other comment lines (e.g. attribution) before/between header lines are
+        // tolerated but only absorbed into the header when a later header line
+        // follows; trailing comments belong to the body.
+    }
+    header.lines = lines.slice(0, lastHeaderIdx + 1);
+    return {
+        header,
+        body: lines.slice(lastHeaderIdx + 1).join('\n')
+    };
+}
+/**
+ * Serialize a header back to its raw lines. When the structured fields have
+ * been modified via {@link renameInHeader}, the raw lines already reflect the
+ * change; this simply joins header and body losslessly.
+ */
+export function writePgpmScript(script) {
+    if (script.header.lines.length === 0)
+        return script.body;
+    return script.header.lines.join('\n') + '\n' + script.body;
+}
+/**
+ * Rewrite change names in a script header according to a rename map
+ * (old change name -> new change name). Rewrites both the `-- Deploy` line's
+ * change identity and any `-- requires:` lines referencing renamed changes,
+ * preserving format (project qualifier, ` to pg` suffix, tag refs untouched).
+ *
+ * Returns the number of substitutions applied; mutates `script` in place.
+ */
+export function renameInHeader(script, renames) {
+    const { header } = script;
+    let count = 0;
+    const renameRef = (raw) => {
+        const ref = parseReference(raw);
+        if (!ref) {
+            const to = renames.get(raw);
+            return to ?? null;
+        }
+        if (ref.tag || ref.symbolic || ref.relative)
+            return null;
+        const change = ref.change;
+        if (!change)
+            return null;
+        const to = renames.get(change);
+        if (!to)
+            return null;
+        return ref.package ? `${ref.package}:${to}` : to;
+    };
+    header.lines = header.lines.map(line => {
+        const headerMatch = line.match(HEADER_LINE);
+        if (headerMatch && header.change && renames.has(header.change)) {
+            const to = renames.get(header.change);
+            const oldTarget = header.project ? `${header.project}:${header.change}` : header.change;
+            const newTarget = header.project ? `${header.project}:${to}` : to;
+            const rewritten = line.replace(oldTarget, newTarget);
+            if (rewritten !== line) {
+                header.change = to;
+                count++;
+                return rewritten;
+            }
+            return line;
+        }
+        const requiresMatch = line.match(REQUIRES_LINE);
+        if (requiresMatch) {
+            const raw = requiresMatch[1];
+            const renamed = renameRef(raw);
+            if (renamed !== null) {
+                count++;
+                return line.replace(raw, renamed);
+            }
+        }
+        return line;
+    });
+    header.requires = header.requires.map(req => {
+        const renamed = renameRef(req.raw);
+        if (renamed === null)
+            return req;
+        return { raw: renamed, ref: parseReference(renamed) };
+    });
+    return count;
+}
+/**
+ * Scan a deploy script the way dependency resolution historically has:
+ * line-by-line over the whole file, collecting `-- requires: <ref>` lines
+ * verbatim and validating any `-- Deploy <project>:<change>[ to pg]` line
+ * against the script's path identity and project name.
+ *
+ * Kept strictly line-regex-compatible with the original resolver behavior
+ * (requires lines are honored anywhere in the file, and the legacy
+ * `-- Deploy: <change>` colon form is not identity-validated).
+ *
+ * @throws when the Deploy line's project or change identity mismatches.
+ */
+export function scanDeployScript(content, options) {
+    const { key, extname, makeKey } = options;
+    const requires = [];
+    for (const line of content.split('\n')) {
+        const requiresMatch = line.match(/^-- requires: (.*)/);
+        if (requiresMatch) {
+            requires.push(requiresMatch[1].trim());
+            continue;
+        }
+        if (/:/.test(line)) {
+            const m2 = line.match(/^-- Deploy ([^:]*):([\w\/]+)(?:\s+to\s+pg)?/);
+            if (m2) {
+                const actualProject = m2[1];
+                const keyToTest = m2[2];
+                if (extname !== actualProject) {
+                    throw new Error(`Mismatched project name in deploy file:
+          Expected project: ${extname}
+          Found in line   : ${actualProject}
+          Line            : ${line}`);
+                }
+                const expectedKey = makeKey(keyToTest);
+                if (key !== expectedKey) {
+                    throw new Error(`Deployment script path or internal name mismatch:
+          Expected key    : ${key}
+          Found in line   : ${expectedKey}
+          Line            : ${line}`);
+                }
+            }
+        }
+        else {
+            const m2 = line.match(/^-- Deploy (.*?)(?:\s+to\s+pg)?\s*$/);
+            if (m2) {
+                const keyToTest = m2[1].trim();
+                if (key !== makeKey(keyToTest)) {
+                    throw new Error('deployment script in wrong place or is named wrong internally\n' + line);
+                }
+            }
+        }
+    }
+    return { requires };
+}
+/**
+ * Verify that every change in a module's pgpm.plan has a deploy script whose
+ * header identity matches its path, and report dependency drift between the
+ * plan's dep lists and the scripts' `-- requires:` lines.
+ *
+ * Read-only diagnostic; returns issues rather than throwing.
+ */
+export function verifyPlanMatchesHeaders(moduleDir) {
+    const issues = [];
+    const planPath = join(moduleDir, 'pgpm.plan');
+    const parsed = parsePlanFile(planPath);
+    if (!parsed.data) {
+        throw new Error(`Failed to parse plan file: ${planPath}`);
+    }
+    for (const planChange of parsed.data.changes) {
+        const change = planChange.name;
+        const file = join(moduleDir, 'deploy', `${change}.sql`);
+        let content;
+        try {
+            content = readFileSync(file, 'utf-8');
+        }
+        catch {
+            issues.push({
+                change,
+                file,
+                kind: 'missing-file',
+                message: `deploy script not found for plan change "${change}"`
+            });
+            continue;
+        }
+        const { header } = parsePgpmHeader(content);
+        if (header.change && header.change !== change) {
+            issues.push({
+                change,
+                file,
+                kind: 'identity-mismatch',
+                message: `header declares "${header.change}" but path identity is "${change}"`
+            });
+        }
+        const planDeps = new Set(planChange.dependencies || []);
+        const headerDeps = new Set(header.requires.map(r => r.raw));
+        const missingInHeader = [...planDeps].filter(d => !headerDeps.has(d));
+        const missingInPlan = [...headerDeps].filter(d => !planDeps.has(d));
+        if (missingInHeader.length > 0 || missingInPlan.length > 0) {
+            const parts = [];
+            if (missingInHeader.length > 0) {
+                parts.push(`in plan but not in header requires: ${missingInHeader.join(', ')}`);
+            }
+            if (missingInPlan.length > 0) {
+                parts.push(`in header requires but not in plan: ${missingInPlan.join(', ')}`);
+            }
+            issues.push({
+                change,
+                file,
+                kind: 'requires-drift',
+                message: parts.join('; ')
+            });
+        }
+    }
+    return issues;
+}

package/esm/files/sql/index.js

@@ -1 +1,2 @@
+export * from './header';
 export * from './writer';

package/esm/resolution/deps.js

@@ -3,6 +3,7 @@ import { sync as glob } from 'glob';
 import { join, relative } from 'path';
 import { PgpmPackage } from '../core/class/pgpm';
 import { parsePlanFile } from '../files/plan/parser';
+import { scanDeployScript } from '../files/sql/header';
 import { errors } from '@pgpmjs/types';
 /**
  * Core dependency resolution algorithm that handles circular dependency detection
@@ -333,84 +334,46 @@ export const resolveDependencies = (packageDir, extname, options = {}) => {
     const files = glob(`${packageDir}/deploy/**/*.sql`).sort((a, b) => a.localeCompare(b));
     for (const file of files) {
         const data = readFileSync(file, 'utf-8');
-        const lines = data.split('\n');
         const key = '/' + relative(packageDir, file);
         deps[key] = [];
-        for (const line of lines) {
-            // Handle requires statements
-            const requiresMatch = line.match(/^-- requires: (.*)/);
-            if (requiresMatch) {
-                const dep = requiresMatch[1].trim();
-                // For 'preserve' mode, just add the dependency as-is (like original getDeps)
-                if (tagResolution === 'preserve') {
-                    deps[key].push(dep);
-                    continue;
-                }
-                // For other modes, handle tag resolution
-                if (dep.includes('@')) {
-                    const match = dep.match(/^([^:]+):@(.+)$/);
-                    if (match) {
-                        const [, projectName, tagName] = match;
-                        const taggedChange = resolveTagToChange(projectName, tagName);
-                        if (taggedChange) {
-                            if (tagResolution === 'resolve') {
-                                // Full resolution: replace tag with actual change
-                                const resolvedDep = `${projectName}:${taggedChange}`;
-                                deps[key].push(resolvedDep);
-                            }
-                            else if (tagResolution === 'internal') {
-                                // Internal resolution: keep tag in deps but track mapping
-                                tagMappings[dep] = `${projectName}:${taggedChange}`;
-                                deps[key].push(dep);
-                            }
+        const { requires } = scanDeployScript(data, { key, extname, makeKey });
+        for (const dep of requires) {
+            // For 'preserve' mode, just add the dependency as-is (like original getDeps)
+            if (tagResolution === 'preserve') {
+                deps[key].push(dep);
+                continue;
+            }
+            // For other modes, handle tag resolution
+            if (dep.includes('@')) {
+                const match = dep.match(/^([^:]+):@(.+)$/);
+                if (match) {
+                    const [, projectName, tagName] = match;
+                    const taggedChange = resolveTagToChange(projectName, tagName);
+                    if (taggedChange) {
+                        if (tagResolution === 'resolve') {
+                            // Full resolution: replace tag with actual change
+                            const resolvedDep = `${projectName}:${taggedChange}`;
+                            deps[key].push(resolvedDep);
                         }
-                        else {
-                            // Could not resolve tag, keep it as is
+                        else if (tagResolution === 'internal') {
+                            // Internal resolution: keep tag in deps but track mapping
+                            tagMappings[dep] = `${projectName}:${taggedChange}`;
                             deps[key].push(dep);
                         }
                     }
                     else {
-                        // Invalid tag format, keep as is
+                        // Could not resolve tag, keep it as is
                         deps[key].push(dep);
                     }
                 }
                 else {
-                    // Not a tag, keep as is
+                    // Invalid tag format, keep as is
                     deps[key].push(dep);
                 }
-                continue;
-            }
-            // Handle deploy statements - exactly as in original
-            let m2;
-            let keyToTest;
-            if (/:/.test(line)) {
-                m2 = line.match(/^-- Deploy ([^:]*):([\w\/]+)(?:\s+to\s+pg)?/);
-                if (m2) {
-                    const actualProject = m2[1];
-                    keyToTest = m2[2];
-                    if (extname !== actualProject) {
-                        throw new Error(`Mismatched project name in deploy file:
-          Expected project: ${extname}
-          Found in line   : ${actualProject}
-          Line            : ${line}`);
-                    }
-                    const expectedKey = makeKey(keyToTest);
-                    if (key !== expectedKey) {
-                        throw new Error(`Deployment script path or internal name mismatch:
-          Expected key    : ${key}
-          Found in line   : ${expectedKey}
-          Line            : ${line}`);
-                    }
-                }
             }
             else {
-                m2 = line.match(/^-- Deploy (.*?)(?:\s+to\s+pg)?\s*$/);
-                if (m2) {
-                    keyToTest = m2[1].trim();
-                    if (key !== makeKey(keyToTest)) {
-                        throw new Error('deployment script in wrong place or is named wrong internally\n' + line);
-                    }
-                }
+                // Not a tag, keep as is
+                deps[key].push(dep);
             }
         }
     }

package/esm/slice/slice.js

@@ -340,7 +340,9 @@ export function generateControlContent(pkgName, deps) {
 /**
  * Generate a single package output
  */
-export function generateSinglePackage(pkgName, changes, graph, changeToPackage, pkgDeps, useTagsForCrossPackageDeps = false) {
+export function generateSinglePackage(pkgName, changes, graph, changeToPackage, pkgDeps, crossPackageDeps = 'change') {
+    // Back-compat: earlier signature took useTagsForCrossPackageDeps: boolean
+    const crossPackageDepMode = crossPackageDeps === true ? 'tag' : crossPackageDeps === false ? 'change' : crossPackageDeps;
     // Sort changes in topological order within package
     const sortedChanges = topologicalSortWithinPackage(changes, graph);
     // Build plan entries with updated dependencies
@@ -361,7 +363,13 @@ export function generateSinglePackage(pkgName, changes, graph, changeToPackage,
             }
             else {
                 // Cross-package dependency
-                if (useTagsForCrossPackageDeps) {
+                if (crossPackageDepMode === 'control-only') {
+                    // Dropped from the plan line; carried by the control file's
+                    // `requires` (extension install ordering deploys the whole
+                    // dependency package first)
+                    continue;
+                }
+                if (crossPackageDepMode === 'tag') {
                     // Find latest tag in the dependency package
                     const depPkgChanges = [...graph.nodes.keys()]
                         .filter(c => changeToPackage.get(c) === depPkg);
@@ -461,7 +469,7 @@ export function slicePlan(config) {
         const changes = assignments.get(pkgName);
         if (!changes || changes.size === 0)
             continue;
-        const pkgOutput = generateSinglePackage(pkgName, changes, graph, changeToPackage, packageDeps.get(pkgName) || new Set(), config.useTagsForCrossPackageDeps || false);
+        const pkgOutput = generateSinglePackage(pkgName, changes, graph, changeToPackage, packageDeps.get(pkgName) || new Set(), config.crossPackageDepMode ?? (config.useTagsForCrossPackageDeps ? 'tag' : 'change'));
         packages.push(pkgOutput);
         // Check for heavy cross-package dependencies
         let crossDeps = 0;

package/files/sql/header.d.ts

@@ -0,0 +1,114 @@
+import { ParsedReference } from '../plan/validators';
+/**
+ * A parsed `-- requires:` line from a pgpm SQL script header.
+ */
+export interface PgpmHeaderRequire {
+    /** The dependency reference exactly as written (e.g. `schema`, `pkg:tables/users`, `pkg:@v1`). */
+    raw: string;
+    /** Structured breakdown of the reference (package/change/tag), when parseable. */
+    ref: ParsedReference | null;
+}
+/**
+ * The parsed header block of a pgpm SQL script (deploy/revert/verify).
+ *
+ * The header is everything from the top of the file through the last
+ * header-relevant comment line (`-- Deploy|Revert|Verify ...`,
+ * `-- requires: ...`, and any interleaved comment/blank lines), with the
+ * remainder of the file preserved as `body`.
+ */
+export interface PgpmHeader {
+    /** Header verb: Deploy, Revert or Verify. Null when no header line was found. */
+    verb: 'Deploy' | 'Revert' | 'Verify' | null;
+    /** The project (extension) name from `-- Deploy <project>:<change>`, if present. */
+    project: string | null;
+    /**
+     * The change name from the header line. By convention this must equal the
+     * script's path identity: `deploy/<change>.sql`.
+     */
+    change: string | null;
+    /** Whether the header line carried the legacy ` to pg` suffix. */
+    toPg: boolean;
+    /** Parsed `-- requires:` dependencies, in file order. */
+    requires: PgpmHeaderRequire[];
+    /** The raw header lines, byte-exact, in file order. */
+    lines: string[];
+}
+/**
+ * Result of splitting a SQL script into header and body.
+ */
+export interface ParsedPgpmScript {
+    header: PgpmHeader;
+    /** Everything after the header block, byte-exact. */
+    body: string;
+}
+/**
+ * Parse the header block of a pgpm SQL script into a structured model.
+ *
+ * Recognizes both header formats:
+ *   `-- Deploy <project>:<change> to pg` (legacy sqitch-compatible)
+ *   `-- Deploy <change>` / `-- Deploy: <change>` (new)
+ * along with `-- requires: <ref>` lines where `<ref>` may be a plain change
+ * name, `{package}:{change}`, `@tag`, or `{package}:@tag`.
+ *
+ * The parse is lossless: `header.lines` plus `body` reassemble the original
+ * content byte-exactly (see {@link writePgpmScript}).
+ */
+export declare function parsePgpmHeader(content: string): ParsedPgpmScript;
+/**
+ * Serialize a header back to its raw lines. When the structured fields have
+ * been modified via {@link renameInHeader}, the raw lines already reflect the
+ * change; this simply joins header and body losslessly.
+ */
+export declare function writePgpmScript(script: ParsedPgpmScript): string;
+/**
+ * Rewrite change names in a script header according to a rename map
+ * (old change name -> new change name). Rewrites both the `-- Deploy` line's
+ * change identity and any `-- requires:` lines referencing renamed changes,
+ * preserving format (project qualifier, ` to pg` suffix, tag refs untouched).
+ *
+ * Returns the number of substitutions applied; mutates `script` in place.
+ */
+export declare function renameInHeader(script: ParsedPgpmScript, renames: Map<string, string>): number;
+/**
+ * Options for {@link scanDeployScript}.
+ */
+export interface ScanDeployScriptOptions {
+    /** The script's path identity key (e.g. `/deploy/tables/users.sql`). */
+    key: string;
+    /** The current extension (project) name. */
+    extname: string;
+    /** Maps a change name to its path identity key. */
+    makeKey: (change: string) => string;
+}
+/**
+ * Scan a deploy script the way dependency resolution historically has:
+ * line-by-line over the whole file, collecting `-- requires: <ref>` lines
+ * verbatim and validating any `-- Deploy <project>:<change>[ to pg]` line
+ * against the script's path identity and project name.
+ *
+ * Kept strictly line-regex-compatible with the original resolver behavior
+ * (requires lines are honored anywhere in the file, and the legacy
+ * `-- Deploy: <change>` colon form is not identity-validated).
+ *
+ * @throws when the Deploy line's project or change identity mismatches.
+ */
+export declare function scanDeployScript(content: string, options: ScanDeployScriptOptions): {
+    requires: string[];
+};
+/**
+ * A single plan-vs-header discrepancy found by {@link verifyPlanMatchesHeaders}.
+ */
+export interface HeaderDriftIssue {
+    change: string;
+    file: string;
+    kind: 'missing-file' | 'identity-mismatch' | 'requires-drift';
+    message: string;
+}
+/**
+ * Verify that every change in a module's pgpm.plan has a deploy script whose
+ * header identity matches its path, and report dependency drift between the
+ * plan's dep lists and the scripts' `-- requires:` lines.
+ *
+ * Read-only diagnostic; returns issues rather than throwing.
+ */
+export declare function verifyPlanMatchesHeaders(moduleDir: string): HeaderDriftIssue[];

package/files/sql/header.js

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePgpmHeader = parsePgpmHeader;
+exports.writePgpmScript = writePgpmScript;
+exports.renameInHeader = renameInHeader;
+exports.scanDeployScript = scanDeployScript;
+exports.verifyPlanMatchesHeaders = verifyPlanMatchesHeaders;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const parser_1 = require("../plan/parser");
+const validators_1 = require("../plan/validators");
+const HEADER_LINE = /^--\s*(Deploy|Revert|Verify)\b(:)?\s*(.*?)\s*$/;
+const REQUIRES_LINE = /^--\s*requires:\s*(.*?)\s*$/;
+const COMMENT_LINE = /^\s*--/;
+const TO_PG_SUFFIX = /\s+to\s+pg\s*$/;
+/**
+ * Parse the header block of a pgpm SQL script into a structured model.
+ *
+ * Recognizes both header formats:
+ *   `-- Deploy <project>:<change> to pg` (legacy sqitch-compatible)
+ *   `-- Deploy <change>` / `-- Deploy: <change>` (new)
+ * along with `-- requires: <ref>` lines where `<ref>` may be a plain change
+ * name, `{package}:{change}`, `@tag`, or `{package}:@tag`.
+ *
+ * The parse is lossless: `header.lines` plus `body` reassemble the original
+ * content byte-exactly (see {@link writePgpmScript}).
+ */
+function parsePgpmHeader(content) {
+    const header = {
+        verb: null,
+        project: null,
+        change: null,
+        toPg: false,
+        requires: [],
+        lines: []
+    };
+    const lines = content.split('\n');
+    let lastHeaderIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === '') {
+            continue;
+        }
+        if (!COMMENT_LINE.test(line)) {
+            break;
+        }
+        const headerMatch = line.match(HEADER_LINE);
+        if (headerMatch && header.verb === null) {
+            header.verb = headerMatch[1];
+            let target = headerMatch[3];
+            if (TO_PG_SUFFIX.test(target)) {
+                header.toPg = true;
+                target = target.replace(TO_PG_SUFFIX, '');
+            }
+            const colonIndex = target.indexOf(':');
+            if (colonIndex > 0 && /^[a-zA-Z0-9_-]+$/.test(target.substring(0, colonIndex))) {
+                header.project = target.substring(0, colonIndex);
+                header.change = target.substring(colonIndex + 1).trim();
+            }
+            else {
+                header.change = target.trim() || null;
+            }
+            lastHeaderIdx = i;
+            continue;
+        }
+        const requiresMatch = line.match(REQUIRES_LINE);
+        if (requiresMatch) {
+            const raw = requiresMatch[1];
+            header.requires.push({ raw, ref: (0, validators_1.parseReference)(raw) });
+            lastHeaderIdx = i;
+            continue;
+        }
+        // Other comment lines (e.g. attribution) before/between header lines are
+        // tolerated but only absorbed into the header when a later header line
+        // follows; trailing comments belong to the body.
+    }
+    header.lines = lines.slice(0, lastHeaderIdx + 1);
+    return {
+        header,
+        body: lines.slice(lastHeaderIdx + 1).join('\n')
+    };
+}
+/**
+ * Serialize a header back to its raw lines. When the structured fields have
+ * been modified via {@link renameInHeader}, the raw lines already reflect the
+ * change; this simply joins header and body losslessly.
+ */
+function writePgpmScript(script) {
+    if (script.header.lines.length === 0)
+        return script.body;
+    return script.header.lines.join('\n') + '\n' + script.body;
+}
+/**
+ * Rewrite change names in a script header according to a rename map
+ * (old change name -> new change name). Rewrites both the `-- Deploy` line's
+ * change identity and any `-- requires:` lines referencing renamed changes,
+ * preserving format (project qualifier, ` to pg` suffix, tag refs untouched).
+ *
+ * Returns the number of substitutions applied; mutates `script` in place.
+ */
+function renameInHeader(script, renames) {
+    const { header } = script;
+    let count = 0;
+    const renameRef = (raw) => {
+        const ref = (0, validators_1.parseReference)(raw);
+        if (!ref) {
+            const to = renames.get(raw);
+            return to ?? null;
+        }
+        if (ref.tag || ref.symbolic || ref.relative)
+            return null;
+        const change = ref.change;
+        if (!change)
+            return null;
+        const to = renames.get(change);
+        if (!to)
+            return null;
+        return ref.package ? `${ref.package}:${to}` : to;
+    };
+    header.lines = header.lines.map(line => {
+        const headerMatch = line.match(HEADER_LINE);
+        if (headerMatch && header.change && renames.has(header.change)) {
+            const to = renames.get(header.change);
+            const oldTarget = header.project ? `${header.project}:${header.change}` : header.change;
+            const newTarget = header.project ? `${header.project}:${to}` : to;
+            const rewritten = line.replace(oldTarget, newTarget);
+            if (rewritten !== line) {
+                header.change = to;
+                count++;
+                return rewritten;
+            }
+            return line;
+        }
+        const requiresMatch = line.match(REQUIRES_LINE);
+        if (requiresMatch) {
+            const raw = requiresMatch[1];
+            const renamed = renameRef(raw);
+            if (renamed !== null) {
+                count++;
+                return line.replace(raw, renamed);
+            }
+        }
+        return line;
+    });
+    header.requires = header.requires.map(req => {
+        const renamed = renameRef(req.raw);
+        if (renamed === null)
+            return req;
+        return { raw: renamed, ref: (0, validators_1.parseReference)(renamed) };
+    });
+    return count;
+}
+/**
+ * Scan a deploy script the way dependency resolution historically has:
+ * line-by-line over the whole file, collecting `-- requires: <ref>` lines
+ * verbatim and validating any `-- Deploy <project>:<change>[ to pg]` line
+ * against the script's path identity and project name.
+ *
+ * Kept strictly line-regex-compatible with the original resolver behavior
+ * (requires lines are honored anywhere in the file, and the legacy
+ * `-- Deploy: <change>` colon form is not identity-validated).
+ *
+ * @throws when the Deploy line's project or change identity mismatches.
+ */
+function scanDeployScript(content, options) {
+    const { key, extname, makeKey } = options;
+    const requires = [];
+    for (const line of content.split('\n')) {
+        const requiresMatch = line.match(/^-- requires: (.*)/);
+        if (requiresMatch) {
+            requires.push(requiresMatch[1].trim());
+            continue;
+        }
+        if (/:/.test(line)) {
+            const m2 = line.match(/^-- Deploy ([^:]*):([\w\/]+)(?:\s+to\s+pg)?/);
+            if (m2) {
+                const actualProject = m2[1];
+                const keyToTest = m2[2];
+                if (extname !== actualProject) {
+                    throw new Error(`Mismatched project name in deploy file:
+          Expected project: ${extname}
+          Found in line   : ${actualProject}
+          Line            : ${line}`);
+                }
+                const expectedKey = makeKey(keyToTest);
+                if (key !== expectedKey) {
+                    throw new Error(`Deployment script path or internal name mismatch:
+          Expected key    : ${key}
+          Found in line   : ${expectedKey}
+          Line            : ${line}`);
+                }
+            }
+        }
+        else {
+            const m2 = line.match(/^-- Deploy (.*?)(?:\s+to\s+pg)?\s*$/);
+            if (m2) {
+                const keyToTest = m2[1].trim();
+                if (key !== makeKey(keyToTest)) {
+                    throw new Error('deployment script in wrong place or is named wrong internally\n' + line);
+                }
+            }
+        }
+    }
+    return { requires };
+}
+/**
+ * Verify that every change in a module's pgpm.plan has a deploy script whose
+ * header identity matches its path, and report dependency drift between the
+ * plan's dep lists and the scripts' `-- requires:` lines.
+ *
+ * Read-only diagnostic; returns issues rather than throwing.
+ */
+function verifyPlanMatchesHeaders(moduleDir) {
+    const issues = [];
+    const planPath = (0, path_1.join)(moduleDir, 'pgpm.plan');
+    const parsed = (0, parser_1.parsePlanFile)(planPath);
+    if (!parsed.data) {
+        throw new Error(`Failed to parse plan file: ${planPath}`);
+    }
+    for (const planChange of parsed.data.changes) {
+        const change = planChange.name;
+        const file = (0, path_1.join)(moduleDir, 'deploy', `${change}.sql`);
+        let content;
+        try {
+            content = (0, fs_1.readFileSync)(file, 'utf-8');
+        }
+        catch {
+            issues.push({
+                change,
+                file,
+                kind: 'missing-file',
+                message: `deploy script not found for plan change "${change}"`
+            });
+            continue;
+        }
+        const { header } = parsePgpmHeader(content);
+        if (header.change && header.change !== change) {
+            issues.push({
+                change,
+                file,
+                kind: 'identity-mismatch',
+                message: `header declares "${header.change}" but path identity is "${change}"`
+            });
+        }
+        const planDeps = new Set(planChange.dependencies || []);
+        const headerDeps = new Set(header.requires.map(r => r.raw));
+        const missingInHeader = [...planDeps].filter(d => !headerDeps.has(d));
+        const missingInPlan = [...headerDeps].filter(d => !planDeps.has(d));
+        if (missingInHeader.length > 0 || missingInPlan.length > 0) {
+            const parts = [];
+            if (missingInHeader.length > 0) {
+                parts.push(`in plan but not in header requires: ${missingInHeader.join(', ')}`);
+            }
+            if (missingInPlan.length > 0) {
+                parts.push(`in header requires but not in plan: ${missingInPlan.join(', ')}`);
+            }
+            issues.push({
+                change,
+                file,
+                kind: 'requires-drift',
+                message: parts.join('; ')
+            });
+        }
+    }
+    return issues;
+}

package/files/sql/index.d.ts

@@ -1 +1,2 @@
+export * from './header';
 export * from './writer';

package/files/sql/index.js

@@ -14,4 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./header"), exports);
 __exportStar(require("./writer"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpmjs/core",
-  "version": "6.32.1",
+  "version": "6.33.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "PGPM Package and Migration Tools",
   "main": "index.js",
@@ -52,7 +52,7 @@
     "@pgpmjs/logger": "^2.14.0",
     "@pgpmjs/server-utils": "^3.15.3",
     "@pgpmjs/types": "^2.35.1",
-    "csv-to-pg": "^3.21.0",
+    "csv-to-pg": "^3.21.1",
     "genomic": "^5.6.2",
     "glob": "^13.0.6",
     "minimatch": "^10.2.5",
@@ -60,9 +60,9 @@
     "pg": "^8.21.0",
     "pg-cache": "^3.15.2",
     "pg-env": "^1.18.1",
-    "pgsql-deparser": "^17.18.3",
-    "pgsql-parser": "^17.9.15",
+    "pgsql-deparser": "^17.18.5",
+    "pgsql-parser": "^17.9.17",
     "yanse": "^0.2.1"
   },
-  "gitHead": "e53a570a4a70987e82dc074bd73501971fd82828"
+  "gitHead": "6a1d3e65a4a786e602efe5ec3835238eb1648734"
 }

package/resolution/deps.js

@@ -6,6 +6,7 @@ const glob_1 = require("glob");
 const path_1 = require("path");
 const pgpm_1 = require("../core/class/pgpm");
 const parser_1 = require("../files/plan/parser");
+const header_1 = require("../files/sql/header");
 const types_1 = require("@pgpmjs/types");
 /**
  * Core dependency resolution algorithm that handles circular dependency detection
@@ -337,84 +338,46 @@ const resolveDependencies = (packageDir, extname, options = {}) => {
     const files = (0, glob_1.sync)(`${packageDir}/deploy/**/*.sql`).sort((a, b) => a.localeCompare(b));
     for (const file of files) {
         const data = (0, fs_1.readFileSync)(file, 'utf-8');
-        const lines = data.split('\n');
         const key = '/' + (0, path_1.relative)(packageDir, file);
         deps[key] = [];
-        for (const line of lines) {
-            // Handle requires statements
-            const requiresMatch = line.match(/^-- requires: (.*)/);
-            if (requiresMatch) {
-                const dep = requiresMatch[1].trim();
-                // For 'preserve' mode, just add the dependency as-is (like original getDeps)
-                if (tagResolution === 'preserve') {
-                    deps[key].push(dep);
-                    continue;
-                }
-                // For other modes, handle tag resolution
-                if (dep.includes('@')) {
-                    const match = dep.match(/^([^:]+):@(.+)$/);
-                    if (match) {
-                        const [, projectName, tagName] = match;
-                        const taggedChange = resolveTagToChange(projectName, tagName);
-                        if (taggedChange) {
-                            if (tagResolution === 'resolve') {
-                                // Full resolution: replace tag with actual change
-                                const resolvedDep = `${projectName}:${taggedChange}`;
-                                deps[key].push(resolvedDep);
-                            }
-                            else if (tagResolution === 'internal') {
-                                // Internal resolution: keep tag in deps but track mapping
-                                tagMappings[dep] = `${projectName}:${taggedChange}`;
-                                deps[key].push(dep);
-                            }
+        const { requires } = (0, header_1.scanDeployScript)(data, { key, extname, makeKey });
+        for (const dep of requires) {
+            // For 'preserve' mode, just add the dependency as-is (like original getDeps)
+            if (tagResolution === 'preserve') {
+                deps[key].push(dep);
+                continue;
+            }
+            // For other modes, handle tag resolution
+            if (dep.includes('@')) {
+                const match = dep.match(/^([^:]+):@(.+)$/);
+                if (match) {
+                    const [, projectName, tagName] = match;
+                    const taggedChange = resolveTagToChange(projectName, tagName);
+                    if (taggedChange) {
+                        if (tagResolution === 'resolve') {
+                            // Full resolution: replace tag with actual change
+                            const resolvedDep = `${projectName}:${taggedChange}`;
+                            deps[key].push(resolvedDep);
                         }
-                        else {
-                            // Could not resolve tag, keep it as is
+                        else if (tagResolution === 'internal') {
+                            // Internal resolution: keep tag in deps but track mapping
+                            tagMappings[dep] = `${projectName}:${taggedChange}`;
                             deps[key].push(dep);
                         }
                     }
                     else {
-                        // Invalid tag format, keep as is
+                        // Could not resolve tag, keep it as is
                         deps[key].push(dep);
                     }
                 }
                 else {
-                    // Not a tag, keep as is
+                    // Invalid tag format, keep as is
                     deps[key].push(dep);
                 }
-                continue;
-            }
-            // Handle deploy statements - exactly as in original
-            let m2;
-            let keyToTest;
-            if (/:/.test(line)) {
-                m2 = line.match(/^-- Deploy ([^:]*):([\w\/]+)(?:\s+to\s+pg)?/);
-                if (m2) {
-                    const actualProject = m2[1];
-                    keyToTest = m2[2];
-                    if (extname !== actualProject) {
-                        throw new Error(`Mismatched project name in deploy file:
-          Expected project: ${extname}
-          Found in line   : ${actualProject}
-          Line            : ${line}`);
-                    }
-                    const expectedKey = makeKey(keyToTest);
-                    if (key !== expectedKey) {
-                        throw new Error(`Deployment script path or internal name mismatch:
-          Expected key    : ${key}
-          Found in line   : ${expectedKey}
-          Line            : ${line}`);
-                    }
-                }
             }
             else {
-                m2 = line.match(/^-- Deploy (.*?)(?:\s+to\s+pg)?\s*$/);
-                if (m2) {
-                    keyToTest = m2[1].trim();
-                    if (key !== makeKey(keyToTest)) {
-                        throw new Error('deployment script in wrong place or is named wrong internally\n' + line);
-                    }
-                }
+                // Not a tag, keep as is
+                deps[key].push(dep);
             }
         }
     }

package/slice/slice.d.ts

@@ -1,5 +1,5 @@
 import { Change, Tag, ExtendedPlanFile } from '../files/types';
-import { SliceConfig, SliceResult, DependencyGraph, PackageOutput, GroupingStrategy, PatternStrategy } from './types';
+import { SliceConfig, SliceResult, DependencyGraph, PackageOutput, GroupingStrategy, PatternStrategy, CrossPackageDepMode } from './types';
 /**
  * Build a dependency graph from a parsed plan file
  */
@@ -52,7 +52,7 @@ export declare function generateControlContent(pkgName: string, deps: Set<string
 /**
  * Generate a single package output
  */
-export declare function generateSinglePackage(pkgName: string, changes: Set<string>, graph: DependencyGraph, changeToPackage: Map<string, string>, pkgDeps: Set<string>, useTagsForCrossPackageDeps?: boolean): PackageOutput;
+export declare function generateSinglePackage(pkgName: string, changes: Set<string>, graph: DependencyGraph, changeToPackage: Map<string, string>, pkgDeps: Set<string>, crossPackageDeps?: boolean | CrossPackageDepMode): PackageOutput;
 /**
  * Main slicing function
  */

package/slice/slice.js

@@ -356,7 +356,9 @@ function generateControlContent(pkgName, deps) {
 /**
  * Generate a single package output
  */
-function generateSinglePackage(pkgName, changes, graph, changeToPackage, pkgDeps, useTagsForCrossPackageDeps = false) {
+function generateSinglePackage(pkgName, changes, graph, changeToPackage, pkgDeps, crossPackageDeps = 'change') {
+    // Back-compat: earlier signature took useTagsForCrossPackageDeps: boolean
+    const crossPackageDepMode = crossPackageDeps === true ? 'tag' : crossPackageDeps === false ? 'change' : crossPackageDeps;
     // Sort changes in topological order within package
     const sortedChanges = topologicalSortWithinPackage(changes, graph);
     // Build plan entries with updated dependencies
@@ -377,7 +379,13 @@ function generateSinglePackage(pkgName, changes, graph, changeToPackage, pkgDeps
             }
             else {
                 // Cross-package dependency
-                if (useTagsForCrossPackageDeps) {
+                if (crossPackageDepMode === 'control-only') {
+                    // Dropped from the plan line; carried by the control file's
+                    // `requires` (extension install ordering deploys the whole
+                    // dependency package first)
+                    continue;
+                }
+                if (crossPackageDepMode === 'tag') {
                     // Find latest tag in the dependency package
                     const depPkgChanges = [...graph.nodes.keys()]
                         .filter(c => changeToPackage.get(c) === depPkg);
@@ -477,7 +485,7 @@ function slicePlan(config) {
         const changes = assignments.get(pkgName);
         if (!changes || changes.size === 0)
             continue;
-        const pkgOutput = generateSinglePackage(pkgName, changes, graph, changeToPackage, packageDeps.get(pkgName) || new Set(), config.useTagsForCrossPackageDeps || false);
+        const pkgOutput = generateSinglePackage(pkgName, changes, graph, changeToPackage, packageDeps.get(pkgName) || new Set(), config.crossPackageDepMode ?? (config.useTagsForCrossPackageDeps ? 'tag' : 'change'));
         packages.push(pkgOutput);
         // Check for heavy cross-package dependencies
         let crossDeps = 0;

package/slice/types.d.ts

@@ -13,11 +13,26 @@ export interface SliceConfig {
     defaultPackage?: string;
     /** Whether to use tags for cross-package deps */
     useTagsForCrossPackageDeps?: boolean;
+    /**
+     * How cross-package dependencies are recorded in sliced plans:
+     * - 'change' (default): per-change refs (`{package}:{change}`)
+     * - 'tag': per-change tag refs (`{package}:@tag`) when available
+     *   (equivalent to `useTagsForCrossPackageDeps: true`)
+     * - 'control-only': drop per-change cross-package refs from plan lines
+     *   entirely; the dependency is carried only by the control file's
+     *   `requires` (extension install ordering deploys the whole dependency
+     *   package first, which subsumes any per-change ordering constraint)
+     */
+    crossPackageDepMode?: CrossPackageDepMode;
     /** Minimum changes per package (merge smaller groups) */
     minChangesPerPackage?: number;
     /** Author for generated plan files */
     author?: string;
 }
+/**
+ * How cross-package dependencies are represented in sliced plan files
+ */
+export type CrossPackageDepMode = 'change' | 'tag' | 'control-only';
 /**
  * Grouping strategy for slicing
  */