@pgpmjs/core 7.1.0 → 7.2.1

package/files/plan/validators.d.ts

@@ -1,52 +0,0 @@
-/**
- * Validators for Sqitch change and tag names according to the spec:
- * https://sqitch.org/docs/manual/sqitchchanges/
- */
-/**
- * Validate a change name according to Sqitch rules:
- * - ≥1 character
- * - Cannot contain whitespace
- * - First and last characters must not be punctuation (except _)
- * - Must not end in ~, ^, /, = or % followed by digits
- * - Disallowed characters anywhere: :, @, #, \
- */
-export declare function isValidChangeName(name: string): boolean;
-/**
- * Validate a tag name according to Sqitch rules:
- * - Same as change name rules
- * - Additionally, must not contain /
- */
-export declare function isValidTagName(name: string): boolean;
-/**
- * Parse a reference that might include project qualifier and/or tag
- * Examples:
- * - "users_table"
- * - "@v1.0"
- * - "users_table@v1.0"
- * - "otherproj:users_table"
- * - "otherproj:@v1.2"
- * - "otherproj:users_table@v1.2"
- * - "40763784148fa190d75bad036730ef44d1c2eac6"
- * - "project:40763784148fa190d75bad036730ef44d1c2eac6"
- */
-export interface ParsedReference {
-    package?: string;
-    change?: string;
-    tag?: string;
-    sha1?: string;
-    symbolic?: 'HEAD' | 'ROOT';
-    relative?: {
-        base: string;
-        direction: '^' | '~';
-        count: number;
-    };
-}
-/**
- * Parse a reference string into its components
- */
-export declare function parseReference(ref: string): ParsedReference | null;
-/**
- * Validate a dependency reference
- * Dependencies can be any valid reference format
- */
-export declare function isValidDependency(dep: string): boolean;

package/files/plan/validators.js

@@ -1,187 +0,0 @@
-"use strict";
-/**
- * Validators for Sqitch change and tag names according to the spec:
- * https://sqitch.org/docs/manual/sqitchchanges/
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isValidChangeName = isValidChangeName;
-exports.isValidTagName = isValidTagName;
-exports.parseReference = parseReference;
-exports.isValidDependency = isValidDependency;
-/**
- * Check if a character is punctuation (excluding underscore)
- */
-function isPunctuation(char) {
-    // Common punctuation marks, excluding underscore
-    const punctuation = /[!"#$%&'()*+,\-./:;<=>?@[\\\]^`{|}~]/;
-    return punctuation.test(char);
-}
-/**
- * Validate a change name according to Sqitch rules:
- * - ≥1 character
- * - Cannot contain whitespace
- * - First and last characters must not be punctuation (except _)
- * - Must not end in ~, ^, /, = or % followed by digits
- * - Disallowed characters anywhere: :, @, #, \
- */
-function isValidChangeName(name) {
-    if (!name || name.length === 0) {
-        return false;
-    }
-    // Check for whitespace
-    if (/\s/.test(name)) {
-        return false;
-    }
-    // Check for disallowed characters anywhere
-    if (/[:@#\\]/.test(name)) {
-        return false;
-    }
-    // Check first character - must not be punctuation except underscore
-    const firstChar = name[0];
-    if (firstChar !== '_' && isPunctuation(firstChar)) {
-        return false;
-    }
-    // Check last character - must not be punctuation except underscore
-    const lastChar = name[name.length - 1];
-    if (lastChar !== '_' && isPunctuation(lastChar)) {
-        return false;
-    }
-    // Check for endings like ~N, ^N, /N, =N, %N where N is digits
-    if (/[~^/=%]\d+$/.test(name)) {
-        return false;
-    }
-    return true;
-}
-/**
- * Validate a tag name according to Sqitch rules:
- * - Same as change name rules
- * - Additionally, must not contain /
- */
-function isValidTagName(name) {
-    if (!isValidChangeName(name)) {
-        return false;
-    }
-    // Tags must not contain /
-    if (name.includes('/')) {
-        return false;
-    }
-    return true;
-}
-/**
- * Check if a string is a valid SHA1 hash (40 hex characters)
- */
-function isSHA1(str) {
-    return /^[0-9a-f]{40}$/i.test(str);
-}
-/**
- * Parse a reference string into its components
- */
-function parseReference(ref) {
-    if (!ref) {
-        return null;
-    }
-    const result = {};
-    // Check for package qualifier
-    let workingRef = ref;
-    const colonIndex = ref.indexOf(':');
-    if (colonIndex > 0) {
-        const projectPart = ref.substring(0, colonIndex);
-        const remainingPart = ref.substring(colonIndex + 1);
-        // Check if this is actually a package qualifier or just a colon in the name
-        // Package names should be valid identifiers (alphanumeric, dash, underscore)
-        // Also check that the remaining part doesn't have more colons
-        if (/^[a-zA-Z0-9_-]+$/.test(projectPart) &&
-            remainingPart.length > 0 &&
-            remainingPart.indexOf(':') === -1) {
-            result.package = projectPart;
-            workingRef = remainingPart;
-        }
-        else {
-            // Not a valid package qualifier, treat the whole thing as a reference
-            workingRef = ref;
-        }
-    }
-    // Check for symbolic references
-    if (workingRef === 'HEAD' || workingRef === '@HEAD') {
-        result.symbolic = 'HEAD';
-        return result;
-    }
-    if (workingRef === 'ROOT' || workingRef === '@ROOT') {
-        result.symbolic = 'ROOT';
-        return result;
-    }
-    // Check for relative references (e.g., HEAD^, @beta~2, HEAD^^)
-    // Handle multiple ^ characters
-    const multiCaretMatch = workingRef.match(/^(.+?)(\^+)$/);
-    if (multiCaretMatch) {
-        const [, base, carets] = multiCaretMatch;
-        result.relative = {
-            base: base, // Keep the original base including @ prefix
-            direction: '^',
-            count: carets.length
-        };
-        return result;
-    }
-    // Handle ^N or ~N format
-    const relativeMatch = workingRef.match(/^(.+?)([~^])(\d+)$/);
-    if (relativeMatch) {
-        const [, base, direction, countStr] = relativeMatch;
-        const count = parseInt(countStr, 10);
-        result.relative = {
-            base: base, // Keep the original base including @ prefix
-            direction: direction,
-            count
-        };
-        return result;
-    }
-    // Handle single ^ or ~ without number
-    const singleRelativeMatch = workingRef.match(/^(.+?)([~^])$/);
-    if (singleRelativeMatch) {
-        const [, base, direction] = singleRelativeMatch;
-        result.relative = {
-            base: base, // Keep the original base including @ prefix
-            direction: direction,
-            count: 1
-        };
-        return result;
-    }
-    // Check if it's a SHA1
-    if (isSHA1(workingRef)) {
-        result.sha1 = workingRef;
-        return result;
-    }
-    // Check for tag reference (starts with @)
-    if (workingRef.startsWith('@')) {
-        const tagName = workingRef.substring(1);
-        if (isValidTagName(tagName)) {
-            result.tag = tagName;
-            return result;
-        }
-        return null; // Invalid tag name
-    }
-    // Check for change@tag format
-    const atIndex = workingRef.indexOf('@');
-    if (atIndex > 0) {
-        const changeName = workingRef.substring(0, atIndex);
-        const tagName = workingRef.substring(atIndex + 1);
-        if (isValidChangeName(changeName) && isValidTagName(tagName)) {
-            result.change = changeName;
-            result.tag = tagName;
-            return result;
-        }
-        return null; // Invalid change or tag name
-    }
-    // Must be a plain change name
-    if (isValidChangeName(workingRef)) {
-        result.change = workingRef;
-        return result;
-    }
-    return null; // Invalid reference
-}
-/**
- * Validate a dependency reference
- * Dependencies can be any valid reference format
- */
-function isValidDependency(dep) {
-    return parseReference(dep) !== null;
-}

package/files/plan/writer.d.ts

@@ -1,27 +0,0 @@
-import { Change, ExtendedPlanFile, PgpmRow, Tag } from '../types';
-export interface PlanWriteOptions {
-    outdir: string;
-    name: string;
-    replacer: (str: string) => string;
-    author?: string;
-}
-/**
- * Write a PGPM plan file based on the provided rows
- */
-export declare function writePgpmPlan(rows: PgpmRow[], opts: PlanWriteOptions): void;
-/**
- * Write a plan file with the provided content
- */
-export declare function writePlanFile(planPath: string, plan: ExtendedPlanFile): void;
-/**
- * Generate content for a plan file
- */
-export declare function generatePlanFileContent(plan: ExtendedPlanFile): string;
-/**
- * Generate a line for a change in a plan file
- */
-export declare function generateChangeLineContent(change: Change, changeOrder?: Map<string, number>): string;
-/**
- * Generate a line for a tag in a plan file
- */
-export declare function generateTagLineContent(tag: Tag): string;

package/files/plan/writer.js

@@ -1,152 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.writePgpmPlan = writePgpmPlan;
-exports.writePlanFile = writePlanFile;
-exports.generatePlanFileContent = generatePlanFileContent;
-exports.generateChangeLineContent = generateChangeLineContent;
-exports.generateTagLineContent = generateTagLineContent;
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-const author_1 = require("../../utils/author");
-/**
- * Sort dependencies by their order in the supplied plan, so prerequisites
- * (parent migrations) appear before their dependents in the bracket.
- * Internal dependencies are sorted by their plan index, and external
- * dependencies (not in the plan) preserve their original order.
- */
-const sortDependencies = (deps, order) => {
-    const originalOrder = new Map(deps.map((dep, index) => [dep, index]));
-    return [...deps].sort((a, b) => {
-        const aIndex = order.get(a);
-        const bIndex = order.get(b);
-        const aOriginal = originalOrder.get(a);
-        const bOriginal = originalOrder.get(b);
-        if (aIndex !== undefined && bIndex !== undefined)
-            return aIndex - bIndex || aOriginal - bOriginal;
-        if (aIndex !== undefined)
-            return -1;
-        if (bIndex !== undefined)
-            return 1;
-        return aOriginal - bOriginal;
-    });
-};
-/**
- * Write a PGPM plan file based on the provided rows
- */
-function writePgpmPlan(rows, opts) {
-    const dir = path_1.default.resolve(path_1.default.join(opts.outdir, opts.name));
-    fs_1.default.mkdirSync(dir, { recursive: true });
-    const date = () => '2017-08-11T08:11:51Z'; // stubbed timestamp
-    const { fullName, email } = (0, author_1.parseAuthor)(opts.author || 'constructive');
-    const authorName = fullName;
-    const authorEmail = email || `${fullName}@5b0c196eeb62`;
-    const duplicates = {};
-    // Build an order map from the row list so brackets can be sorted by plan order
-    const rowOrder = new Map(rows.map((row, index) => [row.deploy, index]));
-    const plan = opts.replacer(`%syntax-version=1.0.0
-%project=constructive-extension-name
-%uri=constructive-extension-name
-
-${rows
-        .map((row) => {
-        if (duplicates[row.deploy]) {
-            console.log('DUPLICATE ' + row.deploy);
-            return '';
-        }
-        duplicates[row.deploy] = true;
-        if (row.deps?.length) {
-            return `${row.deploy} [${sortDependencies(row.deps, rowOrder).join(' ')}] ${date()} ${authorName} <${authorEmail}> # add ${row.name}`;
-        }
-        return `${row.deploy} ${date()} ${authorName} <${authorEmail}> # add ${row.name}`;
-    })
-        .join('\n')}
-`);
-    fs_1.default.writeFileSync(path_1.default.join(dir, 'pgpm.plan'), plan);
-}
-/**
- * Write a plan file with the provided content
- */
-function writePlanFile(planPath, plan) {
-    const content = generatePlanFileContent(plan);
-    fs_1.default.writeFileSync(planPath, content);
-}
-/**
- * Generate content for a plan file
- */
-function generatePlanFileContent(plan) {
-    const { package: packageName, uri, changes, tags } = plan;
-    let content = `%syntax-version=1.0.0\n`;
-    content += `%project=${packageName}\n`;
-    if (uri) {
-        content += `%uri=${uri}\n`;
-    }
-    content += `\n`;
-    // Build an order map from the change list so brackets can be sorted by plan order
-    const changeOrder = new Map(changes.map((change, index) => [change.name, index]));
-    // Add changes and their associated tags
-    for (const change of changes) {
-        content += generateChangeLineContent(change, changeOrder);
-        content += `\n`;
-        const associatedTags = tags.filter(tag => tag.change === change.name);
-        for (const tag of associatedTags) {
-            content += generateTagLineContent(tag);
-            content += `\n`;
-        }
-    }
-    return content;
-}
-/**
- * Generate a line for a change in a plan file
- */
-function generateChangeLineContent(change, changeOrder) {
-    const { name, dependencies, timestamp, planner, email, comment } = change;
-    let line = name;
-    // Add dependencies if present, sorted by plan order
-    if (dependencies && dependencies.length > 0) {
-        line += ` [${sortDependencies(dependencies, changeOrder || new Map()).join(' ')}]`;
-    }
-    // Add timestamp if present
-    if (timestamp) {
-        line += ` ${timestamp}`;
-        // Add planner if present
-        if (planner) {
-            line += ` ${planner}`;
-            // Add email if present
-            if (email) {
-                line += ` <${email}>`;
-            }
-        }
-    }
-    // Add comment if present
-    if (comment) {
-        line += ` # ${comment}`;
-    }
-    return line;
-}
-/**
- * Generate a line for a tag in a plan file
- */
-function generateTagLineContent(tag) {
-    const { name, timestamp, planner, email, comment } = tag;
-    let line = `@${name}`;
-    // Add timestamp if present
-    if (timestamp) {
-        line += ` ${timestamp}`;
-        // Add planner if present
-        if (planner) {
-            line += ` ${planner}`;
-            // Add email if present
-            if (email) {
-                line += ` <${email}>`;
-            }
-        }
-    }
-    // Add comment if present
-    if (comment) {
-        line += ` # ${comment}`;
-    }
-    return line;
-}

package/files/sql/header.d.ts

@@ -1,114 +0,0 @@
-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[];