@pgpmjs/core 3.0.0

package/files/plan/parser.js

@@ -0,0 +1,303 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePlanFile = parsePlanFile;
+exports.resolveReference = resolveReference;
+exports.parsePlanFileSimple = parsePlanFileSimple;
+exports.getChanges = getChanges;
+exports.getLatestChange = getLatestChange;
+const fs_1 = require("fs");
+const validators_1 = require("./validators");
+const types_1 = require("@pgpmjs/types");
+/**
+ * Parse a Sqitch plan file with full validation
+ * Supports both changes and tags
+ */
+function parsePlanFile(planPath) {
+    const content = (0, fs_1.readFileSync)(planPath, 'utf-8');
+    const lines = content.split('\n');
+    let project = '';
+    let uri = '';
+    const changes = [];
+    const tags = [];
+    const errors = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNum = i + 1;
+        const trimmed = line.trim();
+        // Skip empty lines
+        if (!trimmed)
+            continue;
+        // Skip comments
+        if (trimmed.startsWith('#'))
+            continue;
+        // Parse package metadata
+        if (trimmed.startsWith('%project=')) {
+            project = trimmed.substring('%project='.length);
+            continue;
+        }
+        if (trimmed.startsWith('%uri=')) {
+            uri = trimmed.substring('%uri='.length);
+            continue;
+        }
+        // Skip other metadata lines
+        if (trimmed.startsWith('%')) {
+            continue;
+        }
+        // Parse tag lines
+        if (trimmed.startsWith('@')) {
+            const lastChangeName = changes.length > 0 ? changes[changes.length - 1].name : null;
+            const tag = parseTagLine(trimmed, lastChangeName);
+            if (tag) {
+                if ((0, validators_1.isValidTagName)(tag.name)) {
+                    tags.push(tag);
+                }
+                else {
+                    errors.push({
+                        line: lineNum,
+                        message: `Invalid tag name: ${tag.name}`
+                    });
+                }
+            }
+            else {
+                errors.push({
+                    line: lineNum,
+                    message: 'Invalid tag line format'
+                });
+            }
+            continue;
+        }
+        // Parse change lines
+        const change = parseChangeLine(trimmed);
+        if (change) {
+            // Validate change name
+            if (!(0, validators_1.isValidChangeName)(change.name)) {
+                errors.push({
+                    line: lineNum,
+                    message: `Invalid change name: ${change.name}`
+                });
+                continue;
+            }
+            // Validate dependencies
+            for (const dep of change.dependencies) {
+                if (!(0, validators_1.isValidDependency)(dep)) {
+                    errors.push({
+                        line: lineNum,
+                        message: `Invalid dependency reference: ${dep}`
+                    });
+                }
+            }
+            changes.push(change);
+        }
+        else if (trimmed) {
+            // Non-empty line that couldn't be parsed
+            errors.push({
+                line: lineNum,
+                message: 'Invalid line format'
+            });
+        }
+    }
+    if (errors.length > 0) {
+        return { errors };
+    }
+    return {
+        data: { package: project, uri, changes, tags },
+        errors: []
+    };
+}
+/**
+ * Parse a single change line from a plan file
+ * Format: change_name [deps] timestamp planner <email> # comment
+ */
+function parseChangeLine(line) {
+    // More flexible regex that handles various formats, including planner names with spaces
+    // Format: change_name [deps] timestamp planner <email> # comment
+    // The timestamp is required if planner/email/comment are present
+    const regex = /^(\S+)(?:\s+\[([^\]]*)\])?(?:\s+(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z)(?:\s+([^<]+?))?(?:\s+<([^>]+)>)?(?:\s+#\s+(.*))?)?$/;
+    const match = line.match(regex);
+    if (!match) {
+        return null;
+    }
+    const [, name, depsStr, timestamp, planner, email, comment] = match;
+    // Parse dependencies
+    const dependencies = depsStr
+        ? depsStr.split(/\s+/).filter(dep => dep.length > 0)
+        : [];
+    return {
+        name,
+        dependencies,
+        timestamp,
+        planner,
+        email,
+        comment
+    };
+}
+/**
+ * Parse a tag line from a plan file
+ * Format: @tag_name change_name timestamp planner <email> # comment
+ */
+function parseTagLine(line, lastChangeName) {
+    // Tag lines start with @
+    if (!line.startsWith('@')) {
+        return null;
+    }
+    // Remove the @ and parse
+    const tagContent = line.substring(1);
+    // Two possible formats:
+    // 1. tagname timestamp planner <email> # comment (tag for last change)
+    // 2. tagname changename timestamp planner <email> # comment (tag for specific change)
+    // First try to match with change name (format 2)
+    const regexWithChange = /^(\S+)\s+(\S+)\s+(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z)\s+(.+?)\s+<([^>]+)>(?:\s+#\s+(.*))?$/;
+    let match = tagContent.match(regexWithChange);
+    if (match) {
+        const [, name, secondToken, timestamp, planner, email, comment] = match;
+        // Check if the second token is a timestamp (format 1) or change name (format 2)
+        if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(secondToken)) {
+            // Format 1: no change name specified
+            return {
+                name,
+                change: lastChangeName || '', // Tag is associated with the last change
+                timestamp: secondToken,
+                planner: timestamp, // What we thought was timestamp is actually planner
+                email: planner, // Shift everything
+                comment: email || comment
+            };
+        }
+        else {
+            // Format 2: explicit change name
+            return {
+                name,
+                change: secondToken,
+                timestamp,
+                planner,
+                email,
+                comment
+            };
+        }
+    }
+    // Try simple format without change name
+    const regexSimple = /^(\S+)\s+(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z)\s+(.+?)\s+<([^>]+)>(?:\s+#\s+(.*))?$/;
+    match = tagContent.match(regexSimple);
+    if (!match) {
+        return null;
+    }
+    const [, name, timestamp, planner, email, comment] = match;
+    return {
+        name,
+        change: lastChangeName || '', // Tag is associated with the last change
+        timestamp,
+        planner,
+        email,
+        comment
+    };
+}
+/**
+ * Resolve a reference within a plan file context
+ * Handles symbolic references (HEAD, ROOT) and relative references
+ */
+function resolveReference(ref, plan, currentPackage) {
+    const parsed = (0, validators_1.parseReference)(ref);
+    if (!parsed) {
+        return { error: `Invalid reference: ${ref}` };
+    }
+    // Handle package qualifier
+    const planPackage = currentPackage || plan.package;
+    if (parsed.package && parsed.package !== planPackage) {
+        // Cross-package reference - return as-is
+        return { change: ref };
+    }
+    // Handle SHA1 references
+    if (parsed.sha1) {
+        // Would need to look up in database
+        return { change: ref };
+    }
+    // Handle symbolic references
+    if (parsed.symbolic === 'HEAD' && plan.changes.length > 0) {
+        return { change: plan.changes[plan.changes.length - 1].name };
+    }
+    if (parsed.symbolic === 'ROOT' && plan.changes.length > 0) {
+        return { change: plan.changes[0].name };
+    }
+    // Handle relative references
+    if (parsed.relative) {
+        const baseResolved = resolveReference(parsed.relative.base, plan, currentPackage);
+        if (baseResolved.error) {
+            return baseResolved;
+        }
+        // Get the change name from the resolved reference
+        const baseChange = baseResolved.change;
+        if (!baseChange) {
+            return { error: `Cannot resolve base reference: ${parsed.relative.base}` };
+        }
+        const changeIndex = plan.changes.findIndex(c => c.name === baseChange);
+        if (changeIndex === -1) {
+            return { error: `Change not found: ${baseChange}` };
+        }
+        let targetIndex;
+        if (parsed.relative.direction === '^') {
+            // Go backwards
+            targetIndex = changeIndex - parsed.relative.count;
+        }
+        else {
+            // Go forwards
+            targetIndex = changeIndex + parsed.relative.count;
+        }
+        if (targetIndex < 0 || targetIndex >= plan.changes.length) {
+            return { error: `Relative reference out of bounds: ${ref}` };
+        }
+        return { change: plan.changes[targetIndex].name };
+    }
+    // Handle tag references
+    if (parsed.tag) {
+        const tag = plan.tags.find(t => t.name === parsed.tag);
+        if (!tag) {
+            return { error: `Tag not found: ${parsed.tag}` };
+        }
+        return { tag: parsed.tag, change: tag.change };
+    }
+    // Handle change@tag format
+    if (parsed.change && parsed.tag) {
+        return { change: parsed.change, tag: parsed.tag };
+    }
+    // Plain change reference
+    if (parsed.change) {
+        // Validate that the change exists in the plan
+        const changeExists = plan.changes.some(c => c.name === parsed.change);
+        if (!changeExists) {
+            return { error: `Change not found: ${parsed.change}` };
+        }
+        return { change: parsed.change };
+    }
+    return { error: `Cannot resolve reference: ${ref}` };
+}
+/**
+ * Simple plan file parser without validation (for backwards compatibility)
+ */
+function parsePlanFileSimple(planPath) {
+    const result = parsePlanFile(planPath);
+    if (result.data) {
+        // Return without tags for simple format
+        const { tags, ...planWithoutTags } = result.data;
+        return planWithoutTags;
+    }
+    // If there are errors, throw with details
+    if (result.errors && result.errors.length > 0) {
+        const errorMessages = result.errors.map(e => `Line ${e.line}: ${e.message}`).join('\n');
+        throw types_1.errors.PLAN_PARSE_ERROR({ planPath, errors: errorMessages });
+    }
+    // Return empty plan if no data and no errors
+    return { package: '', uri: '', changes: [] };
+}
+/**
+ * Get all change names from a plan file
+ */
+function getChanges(planPath) {
+    const plan = parsePlanFileSimple(planPath);
+    return plan.changes.map(change => change.name);
+}
+/**
+ * Get the latest (last) change from a plan file
+ */
+function getLatestChange(planPath) {
+    const changes = getChanges(planPath);
+    return changes[changes.length - 1] || '';
+}

package/files/plan/validators.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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

@@ -0,0 +1,187 @@
+"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

@@ -0,0 +1,27 @@
+import { Change, SqitchRow, Tag, ExtendedPlanFile } from '../types';
+export interface PlanWriteOptions {
+    outdir: string;
+    name: string;
+    replacer: (str: string) => string;
+    author?: string;
+}
+/**
+ * Write a Sqitch plan file based on the provided rows
+ */
+export declare function writeSqitchPlan(rows: SqitchRow[], 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): string;
+/**
+ * Generate a line for a tag in a plan file
+ */
+export declare function generateTagLineContent(tag: Tag): string;

package/files/plan/writer.js

@@ -0,0 +1,124 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeSqitchPlan = writeSqitchPlan;
+exports.writePlanFile = writePlanFile;
+exports.generatePlanFileContent = generatePlanFileContent;
+exports.generateChangeLineContent = generateChangeLineContent;
+exports.generateTagLineContent = generateTagLineContent;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Write a Sqitch plan file based on the provided rows
+ */
+function writeSqitchPlan(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 author = opts.author || 'launchql';
+    const email = `${author}@5b0c196eeb62`;
+    const duplicates = {};
+    const plan = opts.replacer(`%syntax-version=1.0.0
+%project=launchql-extension-name
+%uri=launchql-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} [${row.deps.join(' ')}] ${date()} ${author} <${email}> # add ${row.name}`;
+        }
+        return `${row.deploy} ${date()} ${author} <${email}> # 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`;
+    // Add changes and their associated tags
+    for (const change of changes) {
+        content += generateChangeLineContent(change);
+        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) {
+    const { name, dependencies, timestamp, planner, email, comment } = change;
+    let line = name;
+    // Add dependencies if present
+    if (dependencies && dependencies.length > 0) {
+        line += ` [${dependencies.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/index.d.ts

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