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

@@ -12,6 +12,7 @@ export * from './core/template-scaffold';
 export * from './core/boilerplate-types';
 export * from './core/boilerplate-scanner';
 export * from './files';
+export * from './refactor';
 export { cleanSql } from './migrate/clean';
 export { PgpmMigrate } from './migrate/client';
 export { PgpmInit } from './init/client';

package/index.js

@@ -30,6 +30,7 @@ __exportStar(require("./core/boilerplate-types"), exports);
 __exportStar(require("./core/boilerplate-scanner"), exports);
 // Export package-files functionality (now integrated into core)
 __exportStar(require("./files"), exports);
+__exportStar(require("./refactor"), exports);
 var clean_1 = require("./migrate/clean");
 Object.defineProperty(exports, "cleanSql", { enumerable: true, get: function () { return clean_1.cleanSql; } });
 var client_1 = require("./migrate/client");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpmjs/core",
-  "version": "6.32.2",
+  "version": "6.34.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "PGPM Package and Migration Tools",
   "main": "index.js",
@@ -64,5 +64,5 @@
     "pgsql-parser": "^17.9.17",
     "yanse": "^0.2.1"
   },
-  "gitHead": "dbec64be89f2d62d3c77f0026a95c2d477de052a"
+  "gitHead": "08b12923f099191b2d1592b9c897f9f04b4950aa"
 }

package/refactor/index.d.ts

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

package/refactor/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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("./rename"), exports);

package/refactor/rename.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Options for {@link renameChanges}.
+ */
+export interface RenameChangesOptions {
+    /** Report planned operations without touching the filesystem. Default: false */
+    dryRun?: boolean;
+}
+/**
+ * Result of a {@link renameChanges} run.
+ */
+export interface RenameChangesResult {
+    /** deploy/revert/verify script files moved (old path -> new path, module-relative). */
+    filesMoved: Array<{
+        from: string;
+        to: string;
+    }>;
+    /** Script files whose headers were rewritten (identity and/or requires). */
+    headersRewritten: string[];
+    /** Whether pgpm.plan was rewritten. */
+    planRewritten: boolean;
+    /** Dry-run report lines (only populated when dryRun). */
+    dryRunReport?: string[];
+}
+/**
+ * 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 declare function validateRenames(moduleDir: string, renames: Map<string, string>): void;
+/**
+ * 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 declare function renameInPlanContent(content: string, renames: Map<string, string>): string;
+/**
+ * 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 declare function renameChanges(moduleDir: string, renames: Map<string, string>, options?: RenameChangesOptions): RenameChangesResult;
+/**
+ * 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 declare function deriveRenamesFromSchemaMapping(moduleDir: string, schemaMapping: Map<string, string>): Map<string, string>;