@pgpmjs/ast 0.1.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

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

package/esm/files/sql/writer.js

@@ -0,0 +1,107 @@
+import { getEnvOptions } from '@pgpmjs/env';
+import fs from 'fs';
+import path from 'path';
+/**
+ * Write SQL files for PGPM migrations (deploy, revert, verify)
+ */
+export const writePgpmFiles = (rows, opts) => {
+    rows.forEach((row) => writeVerify(row, opts));
+    rows.forEach((row) => writeRevert(row, opts));
+    rows.forEach((row) => writeDeploy(row, opts));
+};
+/**
+ * Sort dependencies in a consistent order
+ */
+const ordered = (arr) => {
+    if (!arr)
+        return [];
+    return arr.sort((a, b) => a.length - b.length || a.localeCompare(b));
+};
+/**
+ * Write a deploy SQL file for a PGPM change
+ */
+const writeDeploy = (row, opts) => {
+    const globalOpts = getEnvOptions({
+        migrations: {
+            codegen: {
+                useTx: opts.useTx
+            }
+        }
+    });
+    const useTx = globalOpts.migrations.codegen.useTx;
+    const deploy = opts.replacer(row.deploy);
+    const dir = path.dirname(deploy);
+    const prefix = path.join(opts.outdir, opts.name, 'deploy');
+    const actualDir = path.resolve(prefix, dir);
+    const actualFile = path.resolve(prefix, `${deploy}.sql`);
+    fs.mkdirSync(actualDir, { recursive: true });
+    const sqlContent = opts.replacer(row.content);
+    const content = `-- Deploy: ${deploy}
+-- made with <3 @ constructive.io
+
+${opts.replacer(ordered(row?.deps)
+        .map((dep) => `-- requires: ${dep}`)
+        .join('\n') || '')}
+
+${useTx ? 'BEGIN;' : ''}
+${sqlContent}
+${useTx ? 'COMMIT;' : ''}
+`;
+    fs.writeFileSync(actualFile, content);
+};
+/**
+ * Write a verify SQL file for a PGPM change
+ */
+const writeVerify = (row, opts) => {
+    const globalOpts = getEnvOptions({
+        migrations: {
+            codegen: {
+                useTx: opts.useTx
+            }
+        }
+    });
+    const useTx = globalOpts.migrations.codegen.useTx;
+    const deploy = opts.replacer(row.deploy);
+    const dir = path.dirname(deploy);
+    const prefix = path.join(opts.outdir, opts.name, 'verify');
+    const actualDir = path.resolve(prefix, dir);
+    const actualFile = path.resolve(prefix, `${deploy}.sql`);
+    fs.mkdirSync(actualDir, { recursive: true });
+    const sqlContent = opts.replacer(row.verify);
+    const content = opts.replacer(`-- Verify: ${deploy}
+
+${useTx ? 'BEGIN;' : ''}
+${sqlContent}
+${useTx ? 'COMMIT;' : ''}
+
+`);
+    fs.writeFileSync(actualFile, content);
+};
+/**
+ * Write a revert SQL file for a PGPM change
+ */
+const writeRevert = (row, opts) => {
+    const globalOpts = getEnvOptions({
+        migrations: {
+            codegen: {
+                useTx: opts.useTx
+            }
+        }
+    });
+    const useTx = globalOpts.migrations.codegen.useTx;
+    const deploy = opts.replacer(row.deploy);
+    const dir = path.dirname(deploy);
+    const prefix = path.join(opts.outdir, opts.name, 'revert');
+    const actualDir = path.resolve(prefix, dir);
+    const actualFile = path.resolve(prefix, `${deploy}.sql`);
+    fs.mkdirSync(actualDir, { recursive: true });
+    const sqlContent = opts.replacer(row.revert);
+    const content = `-- Revert: ${deploy}
+
+${useTx ? 'BEGIN;' : ''}
+${sqlContent}
+${useTx ? 'COMMIT;' : ''}
+
+`;
+    fs.writeFileSync(actualFile, content);
+};

package/esm/files/sql-scripts/index.js

@@ -0,0 +1,2 @@
+// Re-export all sql-scripts functionality
+export * from './reader';

package/esm/files/sql-scripts/reader.js

@@ -0,0 +1,19 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+/**
+ * Read a SQL script file, return empty string if not found
+ */
+export function readScript(basePath, scriptType, changeName) {
+    const scriptPath = join(basePath, scriptType, `${changeName}.sql`);
+    if (!existsSync(scriptPath)) {
+        return '';
+    }
+    return readFileSync(scriptPath, 'utf-8');
+}
+/**
+ * Check if a script file exists
+ */
+export function scriptExists(basePath, scriptType, changeName) {
+    const scriptPath = join(basePath, scriptType, `${changeName}.sql`);
+    return existsSync(scriptPath);
+}

package/esm/files/types/index.js

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

package/esm/files/types/package.js

@@ -0,0 +1 @@
+export {};

package/esm/hash.js

@@ -0,0 +1,9 @@
+import { createHash } from 'crypto';
+/**
+ * Generate a SHA256 hash (hex) of a string. Pure content-addressing primitive
+ * shared by the bundle layer and core; kept here so the artifact layer has a
+ * dependency-free hash without reaching into core.
+ */
+export function hashString(content) {
+    return createHash('sha256').update(content).digest('hex');
+}

package/esm/index.js

@@ -0,0 +1,18 @@
+/**
+ * @pgpmjs/ast — the pgpm module AST layer.
+ *
+ * Two things live here:
+ *   - `files/*` — the low-level file parsers/writers (plan, control, SQL header,
+ *     scripts) and their types. These are the primitives everything else composes.
+ *   - `module/*` — the unified {@link PgpmModuleAst}: `readModule`/`writeModule`
+ *     (parse/deparse a whole pgpm module) built by composing the `files/*` parsers,
+ *     lossless round-trip.
+ *
+ * This package is a pure leaf (no DB, no deploy engine); `@pgpmjs/core` and the
+ * bundle/artifact layer build on top of it.
+ */
+export * from './files';
+export * from './hash';
+export * from './module';
+export * from './plan-rename';
+export { parseAuthor } from './utils/author';

package/esm/module/index.js

@@ -0,0 +1,12 @@
+/**
+ * pgpm-ast: the unified in-memory AST for pgpm modules ("AST for the migrations").
+ *
+ * Composes the existing file-level parsers (plan, control, SQL header) into a
+ * single typed {@link PgpmModuleAst} object that operators transform, then writes
+ * it back losslessly.
+ */
+export * from './parse';
+export * from './reader';
+export * from './roundtrip';
+export * from './types';
+export * from './writer';

package/esm/module/parse.js

@@ -0,0 +1,27 @@
+import { readModule } from './reader';
+import { writeModule } from './writer';
+/**
+ * Parse a pgpm module directory into a {@link PgpmModuleAst}.
+ *
+ * The module-level analog of `pgsql-parser`'s `parse()`: where that turns SQL
+ * text into a PostgreSQL AST, this turns an on-disk pgpm module (plan + control
+ * + deploy/revert/verify scripts) into a single typed tree. Alias of
+ * {@link readModule}; the inverse of {@link deparseModule}.
+ */
+export function parseModule(dir) {
+    return readModule(dir);
+}
+/**
+ * Deparse a {@link PgpmModuleAst} back to an on-disk pgpm module.
+ *
+ * The module-level analog of `pgsql-deparser`'s `deparse()`. With the default
+ * `fromRaw: true` it is lossless (byte-exact round-trip of {@link parseModule});
+ * with `fromRaw: false` it re-serializes the structured model, for operators
+ * that mutate the AST first. Alias of {@link writeModule}.
+ *
+ * For in-memory deparse-to-string of individual parts, use `serializePlan` /
+ * `serializeScript`.
+ */
+export function deparseModule(module, options = {}) {
+    writeModule(module, options);
+}

package/esm/module/reader.js

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { parseControlFile } from '../files/extension/reader';
+import { parsePlanFile } from '../files/plan/parser';
+import { parsePgpmHeader } from '../files/sql/header';
+import { readScript, scriptExists } from '../files/sql-scripts/reader';
+function readScriptAst(dir, kind, change) {
+    if (!scriptExists(dir, kind, change))
+        return null;
+    const raw = readScript(dir, kind, change);
+    const { header, body } = parsePgpmHeader(raw);
+    return { kind, header, body, raw };
+}
+/**
+ * Read a pgpm module directory into the unified {@link PgpmModuleAst}.
+ *
+ * Composes the existing plan parser, control reader, and SQL header parser — it
+ * does not re-implement any parsing. The module is addressed by plan order: the
+ * `changes` array follows `pgpm.plan`, and each change eagerly parses its
+ * deploy/revert/verify scripts (missing ones are `null`). Every leaf retains its
+ * byte-exact source so {@link writeModule} can reproduce the module losslessly.
+ *
+ * @throws when `dir` has no `pgpm.plan`, or the plan fails to parse.
+ */
+export function readModule(dir) {
+    const planPath = join(dir, 'pgpm.plan');
+    if (!existsSync(planPath)) {
+        throw new Error(`No pgpm.plan found in module directory: ${dir}`);
+    }
+    const planRaw = readFileSync(planPath, 'utf-8');
+    const parsed = parsePlanFile(planPath);
+    if (!parsed.data) {
+        const detail = parsed.errors
+            .map(e => `line ${e.line}: ${e.message}`)
+            .join('; ');
+        throw new Error(`Failed to parse plan file ${planPath}: ${detail}`);
+    }
+    const plan = parsed.data;
+    const name = plan.package;
+    let control = null;
+    if (name) {
+        const fileName = `${name}.control`;
+        const controlPath = join(dir, fileName);
+        if (existsSync(controlPath)) {
+            const raw = readFileSync(controlPath, 'utf-8');
+            const info = parseControlFile(controlPath, dir);
+            control = {
+                fileName,
+                name,
+                requires: info.requires,
+                version: info.version,
+                raw
+            };
+        }
+    }
+    const changes = plan.changes.map(planChange => ({
+        name: planChange.name,
+        plan: planChange,
+        deploy: readScriptAst(dir, 'deploy', planChange.name),
+        revert: readScriptAst(dir, 'revert', planChange.name),
+        verify: readScriptAst(dir, 'verify', planChange.name)
+    }));
+    return { dir, name, plan, planRaw, control, changes };
+}

package/esm/module/roundtrip.js

@@ -0,0 +1,65 @@
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { readModule } from './reader';
+import { serializePlan, serializeScript, writeModule } from './writer';
+/**
+ * Read-only invariant check for the module AST: proves a module survives a
+ * read → serialize → re-read cycle without drifting.
+ *
+ * Guarantees checked:
+ *   - every script serializes byte-identically to its source (the SQL header
+ *     parser is lossless), and
+ *   - the plan serialization is idempotent and the structured change set is
+ *     stable across a serialize → re-read round trip.
+ *
+ * Returns the issues found rather than throwing.
+ */
+export function verifyModuleRoundTrip(dir) {
+    const issues = [];
+    const module = readModule(dir);
+    for (const change of module.changes) {
+        for (const script of [change.deploy, change.revert, change.verify]) {
+            if (!script)
+                continue;
+            if (serializeScript(script) !== script.raw) {
+                issues.push({
+                    kind: 'script-drift',
+                    change: change.name,
+                    script: script.kind,
+                    message: 'header serialize is not byte-identical to source'
+                });
+            }
+        }
+    }
+    const planOnce = serializePlan(module);
+    const tmp = mkdtempSync(join(tmpdir(), 'pgpm-ast-rt-'));
+    try {
+        writeModule(module, { outDir: tmp, fromRaw: false });
+        const reread = readModule(tmp);
+        if (serializePlan(reread) !== planOnce) {
+            issues.push({ kind: 'plan-drift', message: 'plan serialization is not idempotent' });
+        }
+        if (reread.changes.length !== module.changes.length) {
+            issues.push({
+                kind: 'change-count',
+                message: `change count drifted: ${module.changes.length} -> ${reread.changes.length}`
+            });
+        }
+        else {
+            for (let i = 0; i < module.changes.length; i++) {
+                if (reread.changes[i].name !== module.changes[i].name) {
+                    issues.push({
+                        kind: 'change-identity',
+                        change: module.changes[i].name,
+                        message: `change at index ${i} drifted to "${reread.changes[i].name}"`
+                    });
+                }
+            }
+        }
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+    return issues;
+}

package/esm/module/types.js

@@ -0,0 +1 @@
+export {};

package/esm/module/writer.js

@@ -0,0 +1,45 @@
+import { mkdirSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { generatePlanFileContent } from '../files/plan/writer';
+import { writePgpmScript } from '../files/sql/header';
+/**
+ * Serialize a script AST back to SQL text from its structured header + body.
+ * Byte-identical to the source for scripts read via {@link readModule} (the SQL
+ * header parser is lossless), and reflects any structural header edits.
+ */
+export function serializeScript(script) {
+    return writePgpmScript({ header: script.header, body: script.body });
+}
+/**
+ * Serialize a module's plan back to `pgpm.plan` text from its structured model.
+ */
+export function serializePlan(module) {
+    return generatePlanFileContent(module.plan);
+}
+/**
+ * Materialize a {@link PgpmModuleAst} back to disk: `pgpm.plan`, the `.control`
+ * file (when present), and every change's deploy/revert/verify script.
+ *
+ * With the default `fromRaw: true` this is a lossless copy of what
+ * {@link readModule} loaded; with `fromRaw: false` it emits the structured
+ * serialization (used by operators that mutate the AST before writing).
+ */
+export function writeModule(module, options = {}) {
+    const outDir = options.outDir ?? module.dir;
+    const fromRaw = options.fromRaw ?? true;
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(join(outDir, 'pgpm.plan'), fromRaw ? module.planRaw : serializePlan(module));
+    if (module.control) {
+        writeFileSync(join(outDir, module.control.fileName), module.control.raw);
+    }
+    for (const change of module.changes) {
+        const scripts = [change.deploy, change.revert, change.verify];
+        for (const script of scripts) {
+            if (!script)
+                continue;
+            const file = join(outDir, script.kind, `${change.name}.sql`);
+            mkdirSync(dirname(file), { recursive: true });
+            writeFileSync(file, fromRaw ? script.raw : serializeScript(script));
+        }
+    }
+}

package/esm/plan-rename.js

@@ -0,0 +1,28 @@
+function escapeRe(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * 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');
+}