@pgpmjs/core 6.32.2 → 6.34.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/index.js

@@ -13,6 +13,7 @@ export * from './core/boilerplate-types';
 export * from './core/boilerplate-scanner';
 // Export package-files functionality (now integrated into core)
 export * from './files';
+export * from './refactor';
 export { cleanSql } from './migrate/clean';
 export { PgpmMigrate } from './migrate/client';
 export { PgpmInit } from './init/client';

package/esm/refactor/index.js

@@ -0,0 +1 @@
+export * from './rename';

package/esm/refactor/rename.js

@@ -0,0 +1,200 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, statSync, writeFileSync } from 'fs';
+import { dirname, join, relative, sep } from 'path';
+import { parsePlanFileSimple } from '../files/plan/parser';
+import { parsePgpmHeader, renameInHeader, writePgpmScript } from '../files/sql/header';
+const SCRIPT_DIRS = ['deploy', 'revert', 'verify'];
+function escapeRe(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function findSqlFiles(dir) {
+    const files = [];
+    if (!existsSync(dir))
+        return files;
+    const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...findSqlFiles(fullPath));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.sql')) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function removeEmptyDirs(dir, stopAt) {
+    let current = dir;
+    while (current !== stopAt && current.startsWith(stopAt)) {
+        if (!existsSync(current) || readdirSync(current).length > 0)
+            return;
+        rmdirSync(current);
+        current = dirname(current);
+    }
+}
+/**
+ * Validate a rename map against a module directory: every source change must
+ * exist in the plan, no target may collide with an existing change, and no
+ * two sources may map to the same target.
+ *
+ * @throws on any violation.
+ */
+export function validateRenames(moduleDir, renames) {
+    const planPath = join(moduleDir, 'pgpm.plan');
+    const plan = parsePlanFileSimple(planPath);
+    const changeNames = new Set(plan.changes.map(c => c.name));
+    const targets = new Set();
+    for (const [from, to] of renames) {
+        if (from === to) {
+            throw new Error(`Rename maps change to itself: ${from}`);
+        }
+        if (!changeNames.has(from)) {
+            throw new Error(`Cannot rename unknown change: ${from}`);
+        }
+        if (changeNames.has(to) && !renames.has(to)) {
+            throw new Error(`Rename target already exists in plan: ${to}`);
+        }
+        if (targets.has(to)) {
+            throw new Error(`Multiple changes rename to the same target: ${to}`);
+        }
+        targets.add(to);
+    }
+}
+/**
+ * Rewrite change names in a pgpm.plan's content according to a rename map.
+ * Textual and format-preserving: only the change-name token at the start of a
+ * change line, plain (same-package) dependency refs inside `[...]`, and tag
+ * lines' change field are rewritten; timestamps, planners, comments,
+ * cross-package refs, and tag refs are untouched.
+ */
+export function renameInPlanContent(content, renames) {
+    const froms = Array.from(renames.keys()).sort((a, b) => b.length - a.length);
+    return content
+        .split('\n')
+        .map(line => {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('%'))
+            return line;
+        let result = line;
+        for (const from of froms) {
+            const to = renames.get(from);
+            const re = new RegExp(`(^|[\\s\\[])${escapeRe(from)}(?=$|[\\s\\]@])`, 'g');
+            result = result.replace(re, `$1${to}`);
+        }
+        return result;
+    })
+        .join('\n');
+}
+/**
+ * Atomically rename/move changes within a pgpm module: the coupled 4-way
+ * rewrite of (1) deploy/revert/verify script files on disk, (2) the moved
+ * scripts' own header identity, (3) `-- requires:` headers in every script
+ * that references a renamed change, and (4) the pgpm.plan.
+ *
+ * SQL statement bodies are NOT touched: schema-name rewrites inside SQL are a
+ * separate AST-level concern for callers to compose (e.g. transform passes).
+ */
+export function renameChanges(moduleDir, renames, options = {}) {
+    const dryRun = options.dryRun ?? false;
+    const result = {
+        filesMoved: [],
+        headersRewritten: [],
+        planRewritten: false
+    };
+    if (dryRun)
+        result.dryRunReport = [];
+    if (renames.size === 0)
+        return result;
+    validateRenames(moduleDir, renames);
+    // 1. Move script files
+    for (const scriptDir of SCRIPT_DIRS) {
+        for (const [from, to] of renames) {
+            const oldPath = join(moduleDir, scriptDir, `${from}.sql`);
+            if (!existsSync(oldPath) || !statSync(oldPath).isFile())
+                continue;
+            const newPath = join(moduleDir, scriptDir, `${to}.sql`);
+            if (existsSync(newPath)) {
+                throw new Error(`Rename target file already exists: ${relative(moduleDir, newPath)}`);
+            }
+            if (dryRun) {
+                result.dryRunReport.push(`Would move: ${relative(moduleDir, oldPath)} -> ${relative(moduleDir, newPath)}`);
+            }
+            else {
+                mkdirSync(dirname(newPath), { recursive: true });
+                renameSync(oldPath, newPath);
+                removeEmptyDirs(dirname(oldPath), join(moduleDir, scriptDir));
+            }
+            result.filesMoved.push({
+                from: [scriptDir, `${from}.sql`].join(sep),
+                to: [scriptDir, `${to}.sql`].join(sep)
+            });
+        }
+    }
+    // 2 + 3. Rewrite headers in every script (identity of moved files,
+    // requires of dependents)
+    for (const scriptDir of SCRIPT_DIRS) {
+        const dir = join(moduleDir, scriptDir);
+        for (const file of findSqlFiles(dir)) {
+            const content = readFileSync(file, 'utf-8');
+            const script = parsePgpmHeader(content);
+            const count = renameInHeader(script, renames);
+            if (count === 0)
+                continue;
+            const rewritten = writePgpmScript(script);
+            if (rewritten === content)
+                continue;
+            if (dryRun) {
+                result.dryRunReport.push(`Would rewrite header: ${relative(moduleDir, file)}`);
+            }
+            else {
+                writeFileSync(file, rewritten);
+            }
+            result.headersRewritten.push(relative(moduleDir, file));
+        }
+    }
+    // In dry-run mode files were not moved, so dependents' headers are found at
+    // their original paths above; the moved files' own headers are still
+    // reported through the same scan.
+    // 4. Rewrite pgpm.plan
+    const planPath = join(moduleDir, 'pgpm.plan');
+    const planContent = readFileSync(planPath, 'utf-8');
+    const newPlanContent = renameInPlanContent(planContent, renames);
+    if (newPlanContent !== planContent) {
+        if (dryRun) {
+            result.dryRunReport.push('Would rewrite: pgpm.plan');
+        }
+        else {
+            writeFileSync(planPath, newPlanContent);
+        }
+        result.planRewritten = true;
+    }
+    return result;
+}
+/**
+ * Derive a change rename map from a schema mapping (old schema name -> new
+ * schema name) by rewriting the `schemas/<name>/` path segment of every plan
+ * change that lives under a renamed schema.
+ *
+ * This is the module-level counterpart of directory-based schema renames:
+ * `schemas/my-app/tables/users` with mapping `my-app -> my_app` yields
+ * `schemas/my_app/tables/users`.
+ */
+export function deriveRenamesFromSchemaMapping(moduleDir, schemaMapping) {
+    const renames = new Map();
+    const planPath = join(moduleDir, 'pgpm.plan');
+    const plan = parsePlanFileSimple(planPath);
+    const schemas = Array.from(schemaMapping.keys()).sort((a, b) => b.length - a.length);
+    for (const change of plan.changes) {
+        let renamed = change.name;
+        for (const schema of schemas) {
+            const to = schemaMapping.get(schema);
+            if (!to || to === schema)
+                continue;
+            const re = new RegExp(`(^|/)(schemas/)${escapeRe(schema)}(/|$)`, 'g');
+            renamed = renamed.replace(re, `$1$2${to}$3`);
+        }
+        if (renamed !== change.name) {
+            renames.set(change.name, renamed);
+        }
+    }
+    return renames;
+}

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;