@postxl/generator 1.6.3 → 1.7.0

package/dist/utils/custom-blocks.d.ts

@@ -93,6 +93,18 @@ export type CustomBlockError = {
  * @returns ExtractResult containing blocks, non-custom lines, and any errors
  */
 export declare function extractCustomBlocks(content: string): ExtractResult;
+/**
+ * Finds the line range of a class member (method/property with a body) in the
+ * given lines, identified by its name. Returns the half-open range
+ * `[start, end)` covering the member's signature through its closing brace, or
+ * `null` if the member is not found or has no brace-delimited body.
+ *
+ * Exported for reuse by the three-way merge's `@custom-override` handling.
+ */
+export declare function findMemberRange(targetLines: string[], memberName: string): {
+    start: number;
+    end: number;
+} | null;
 /**
  * Finds the best position to insert a custom block in the target content
  * based on anchor context matching.
@@ -117,6 +129,26 @@ export declare function insertCustomBlocks(blocks: CustomBlock[], targetContent:
  * Checks if a string contains any custom block markers
  */
 export declare function hasCustomBlockMarkers(content: string): boolean;
+/**
+ * Parses a `@custom-override:<member>` marker line **without a regular
+ * expression** (plain string scanning — avoids a flagged slow-regex hotspot and
+ * is easy to follow). Accepts both the line-comment form (`// @custom-override:member`)
+ * and the single-line block-comment form (slash-star ... star-slash), each with
+ * an optional leading `@`.
+ *
+ * Returns the member name, or `undefined` when the line is not an override marker.
+ */
+export declare function parseOverrideMarkerMemberName(line: string): string | undefined;
+/**
+ * Extracts the member names declared by `// @custom-override:<member>` markers,
+ * in document order and de-duplicated. Used by the three-way merge to keep the
+ * developer's version of the named generated members.
+ */
+export declare function extractOverrideMemberNames(content: string): string[];
+/**
+ * Checks if a string contains any `@custom-override` markers.
+ */
+export declare function hasCustomOverrideMarkers(content: string): boolean;
 /**
  * Reconstructs content from non-custom lines, used when comparing
  * the "real" content differences (excluding custom blocks)

package/dist/utils/custom-blocks.js

@@ -37,9 +37,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.customBlockMarkers = void 0;
 exports.extractCustomBlocks = extractCustomBlocks;
+exports.findMemberRange = findMemberRange;
 exports.findInsertionPosition = findInsertionPosition;
 exports.insertCustomBlocks = insertCustomBlocks;
 exports.hasCustomBlockMarkers = hasCustomBlockMarkers;
+exports.parseOverrideMarkerMemberName = parseOverrideMarkerMemberName;
+exports.extractOverrideMemberNames = extractOverrideMemberNames;
+exports.hasCustomOverrideMarkers = hasCustomOverrideMarkers;
 exports.reconstructNonCustomContent = reconstructNonCustomContent;
 /**
  * Marker patterns for custom blocks
@@ -340,41 +344,65 @@ function countChar(line, char) {
     }
     return count;
 }
-function findMemberRange(targetLines, memberName) {
-    for (let i = 0; i < targetLines.length; i++) {
-        const line = targetLines[i];
+/**
+ * True if the member signature at `start` opens a `{` body before any `;`. A
+ * `;` reached first means a bodyless declaration (overload/abstract), which has
+ * no range.
+ */
+function memberHasBody(targetLines, start) {
+    if (targetLines[start]?.includes('{')) {
+        return true;
+    }
+    for (let j = start + 1; j < targetLines.length; j++) {
+        const line = targetLines[j];
+        if (line?.includes('{')) {
+            return true;
+        }
+        if (line?.trim().endsWith(';')) {
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * Given a member signature at `start` known to open a body, returns the index
+ * just past its balanced closing brace, or `null` if braces never balance.
+ */
+function findMemberBodyEnd(targetLines, start) {
+    let braceDepth = 0;
+    for (let k = start; k < targetLines.length; k++) {
+        const line = targetLines[k];
         if (line === undefined) {
             continue;
         }
-        if (findMemberNameInLine(line) !== memberName) {
-            continue;
+        braceDepth += countChar(line, '{');
+        braceDepth -= countChar(line, '}');
+        if (braceDepth === 0 && k > start) {
+            return k + 1;
         }
-        let j = i;
-        let foundOpeningBrace = line.includes('{');
-        while (!foundOpeningBrace && j + 1 < targetLines.length) {
-            j++;
-            const continuationLine = targetLines[j];
-            if (continuationLine?.includes('{')) {
-                foundOpeningBrace = true;
-            }
-            if (continuationLine?.trim().endsWith(';')) {
-                break;
-            }
+    }
+    return null;
+}
+/**
+ * Finds the line range of a class member (method/property with a body) in the
+ * given lines, identified by its name. Returns the half-open range
+ * `[start, end)` covering the member's signature through its closing brace, or
+ * `null` if the member is not found or has no brace-delimited body.
+ *
+ * Exported for reuse by the three-way merge's `@custom-override` handling.
+ */
+function findMemberRange(targetLines, memberName) {
+    for (let i = 0; i < targetLines.length; i++) {
+        const line = targetLines[i];
+        if (line === undefined || findMemberNameInLine(line) !== memberName) {
+            continue;
         }
-        if (!foundOpeningBrace) {
+        if (!memberHasBody(targetLines, i)) {
             continue;
         }
-        let braceDepth = 0;
-        for (let k = i; k < targetLines.length; k++) {
-            const memberLine = targetLines[k];
-            if (memberLine === undefined) {
-                continue;
-            }
-            braceDepth += countChar(memberLine, '{');
-            braceDepth -= countChar(memberLine, '}');
-            if (braceDepth === 0 && k > i) {
-                return { start: i, end: k + 1 };
-            }
+        const end = findMemberBodyEnd(targetLines, i);
+        if (end !== null) {
+            return { start: i, end };
         }
     }
     return null;
@@ -592,6 +620,78 @@ function hasCustomBlockMarkers(content) {
     const lines = content.split('\n');
     return lines.some((line) => exports.customBlockMarkers.startPattern.test(line) || exports.customBlockMarkers.endPattern.test(line));
 }
+/**
+ * Parses a `@custom-override:<member>` marker line **without a regular
+ * expression** (plain string scanning — avoids a flagged slow-regex hotspot and
+ * is easy to follow). Accepts both the line-comment form (`// @custom-override:member`)
+ * and the single-line block-comment form (slash-star ... star-slash), each with
+ * an optional leading `@`.
+ *
+ * Returns the member name, or `undefined` when the line is not an override marker.
+ */
+function parseOverrideMarkerMemberName(line) {
+    let text = line.trim();
+    if (text.startsWith('//')) {
+        text = text.slice(2).trim();
+    }
+    else if (text.startsWith('/*')) {
+        text = text.slice(2).trim();
+        if (text.endsWith('*/')) {
+            text = text.slice(0, -2).trim();
+        }
+    }
+    else {
+        return undefined;
+    }
+    if (text.startsWith('@')) {
+        text = text.slice(1);
+    }
+    const prefix = 'custom-override:';
+    if (!text.startsWith(prefix)) {
+        return undefined;
+    }
+    const member = text.slice(prefix.length).trim();
+    return isValidMemberName(member) ? member : undefined;
+}
+/** True for a non-empty JS identifier (`[A-Za-z_$][A-Za-z0-9_$]*`), checked char-by-char. */
+function isValidMemberName(name) {
+    if (name.length === 0) {
+        return false;
+    }
+    for (let i = 0; i < name.length; i++) {
+        const ch = name[i];
+        const isLetter = (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z');
+        const isSpecial = ch === '_' || ch === '$';
+        const isDigit = ch >= '0' && ch <= '9';
+        if (i === 0 ? !(isLetter || isSpecial) : !(isLetter || isSpecial || isDigit)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Extracts the member names declared by `// @custom-override:<member>` markers,
+ * in document order and de-duplicated. Used by the three-way merge to keep the
+ * developer's version of the named generated members.
+ */
+function extractOverrideMemberNames(content) {
+    const names = [];
+    const seen = new Set();
+    for (const line of content.split('\n')) {
+        const memberName = parseOverrideMarkerMemberName(line);
+        if (memberName && !seen.has(memberName)) {
+            seen.add(memberName);
+            names.push(memberName);
+        }
+    }
+    return names;
+}
+/**
+ * Checks if a string contains any `@custom-override` markers.
+ */
+function hasCustomOverrideMarkers(content) {
+    return content.split('\n').some((line) => parseOverrideMarkerMemberName(line) !== undefined);
+}
 /**
  * Reconstructs content from non-custom lines, used when comparing
  * the "real" content differences (excluding custom blocks)

package/dist/utils/diff3.d.ts

@@ -0,0 +1,20 @@
+/** A merged region: either resolved lines, or an unresolved 3-way conflict. */
+export type Diff3Chunk = {
+    type: 'stable';
+    lines: string[];
+} | {
+    type: 'conflict';
+    local: string[];
+    base: string[];
+    incoming: string[];
+};
+/**
+ * Performs a three-way line merge and returns the resolved/conflicting chunks.
+ *
+ * @param local - The developer's current version (on disk).
+ * @param base - The common ancestor (previous generation).
+ * @param incoming - The freshly generated version.
+ */
+export declare function diff3Merge(local: string[], base: string[], incoming: string[]): Diff3Chunk[];
+/** Returns true if any chunk is an unresolved conflict. */
+export declare function hasConflictChunk(chunks: Diff3Chunk[]): boolean;

package/dist/utils/diff3.js

@@ -0,0 +1,258 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diff3Merge = diff3Merge;
+exports.hasConflictChunk = hasConflictChunk;
+/**
+ * Self-contained three-way (diff3) line merge.
+ *
+ * Given a common ancestor (`base`), the developer's on-disk version (`local`),
+ * and the freshly generated version (`incoming`), this module reproduces the
+ * classic diff3 chunk merge:
+ *
+ * - Regions changed by only ONE side relative to `base` are auto-applied.
+ * - Regions where both sides made the SAME change collapse to that change.
+ * - Regions where one side is unchanged from `base` take the other side.
+ * - Only regions where both sides diverge from `base` AND from each other are
+ *   reported as conflicts for a human/agent to arbitrate.
+ *
+ * Unlike a 2-way diff (disk vs. fresh output), this can attribute a divergence
+ * to "the developer changed this" vs. "the generator changed this", so a model
+ * change in one region and a developer edit in a different region merge cleanly
+ * with no conflict.
+ *
+ * The matching is computed with jsdiff's `diffArrays` (line arrays), which we
+ * already depend on. Regions are grouped on the `base` axis: two changes only
+ * collide when their `base` ranges genuinely overlap, so directly-adjacent but
+ * disjoint edits from the two sides do not manufacture a false conflict.
+ */
+const Diff = __importStar(require("diff"));
+/**
+ * Consumes the maximal run of added/removed parts starting at `start`, summing
+ * how many base lines it removes and how many side lines it adds. Returns the
+ * index of the first non-change part after the run.
+ */
+function consumeChangeRun(parts, start) {
+    let baseLength = 0;
+    let otherLength = 0;
+    let i = start;
+    while (i < parts.length) {
+        const change = parts[i];
+        if (change === undefined || (!change.added && !change.removed)) {
+            break;
+        }
+        if (change.removed) {
+            baseLength += change.value.length;
+        }
+        else {
+            otherLength += change.value.length;
+        }
+        i++;
+    }
+    return { baseLength, otherLength, next: i };
+}
+/**
+ * Computes the differing hunks between `base` and `other`, anchored on `base`.
+ * Common (matching) regions advance both cursors and are not part of any hunk.
+ */
+function diffIndices(base, other) {
+    const parts = Diff.diffArrays(base, other);
+    const hunks = [];
+    let baseOffset = 0;
+    let otherOffset = 0;
+    let i = 0;
+    while (i < parts.length) {
+        const part = parts[i];
+        if (part === undefined) {
+            i++;
+            continue;
+        }
+        if (!part.added && !part.removed) {
+            baseOffset += part.value.length;
+            otherOffset += part.value.length;
+            i++;
+            continue;
+        }
+        // Start of a change region: consume the maximal run of added/removed parts.
+        const baseStart = baseOffset;
+        const otherStart = otherOffset;
+        const run = consumeChangeRun(parts, i);
+        i = run.next;
+        baseOffset += run.baseLength;
+        otherOffset += run.otherLength;
+        hunks.push({
+            baseOffset: baseStart,
+            baseLength: run.baseLength,
+            sideOffset: otherStart,
+            sideLength: run.otherLength,
+        });
+    }
+    return hunks;
+}
+/**
+ * Maps the base range [regionStart, regionEnd) into one side's line coordinates,
+ * using that side's hunks. Base lines inside the region but outside a hunk are
+ * unchanged on this side and map 1:1.
+ *
+ * `lo` (where the region starts on the side) is anchored on the FIRST hunk and
+ * `hi` (where it ends) on the LAST — not min/max across all hunks. With a single
+ * hunk these are equivalent, but when one region groups several same-side hunks
+ * whose net length differs from base (deletions/insertions, not pure
+ * substitutions), a per-hunk min/max over-extrapolates each hunk to the full
+ * region independently and unions the results, pulling in unchanged context lines
+ * outside [regionStart, regionEnd). That duplicated context then appears both as a
+ * stable chunk and inside the conflict body. `sideHunks` arrive sorted ascending
+ * by `baseOffset` (and base hunks never overlap), so the first/last elements carry
+ * the region's true start/end deltas.
+ */
+function sliceSide(sideHunks, sideArr, regionStart, regionEnd) {
+    const first = sideHunks[0];
+    const last = sideHunks.at(-1);
+    if (first === undefined || last === undefined) {
+        return [];
+    }
+    const lo = first.sideOffset - (first.baseOffset - regionStart);
+    const hi = last.sideOffset + last.sideLength + (regionEnd - (last.baseOffset + last.baseLength));
+    return sideArr.slice(lo, hi);
+}
+function arraysEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Starting from `first` at index `start`, groups every later hunk that genuinely
+ * overlaps the region on the base axis. Adjacent-but-disjoint edits
+ * (`next.baseOffset === regionEnd`) stay separate, so independent single-line
+ * edits from the two sides do not collide. Returns the region span, its hunks,
+ * and the index of the first hunk past it.
+ */
+function collectRegion(first, hunks, start) {
+    const regionStart = first.baseOffset;
+    let regionEnd = first.baseOffset + first.baseLength;
+    const regionHunks = [first];
+    let i = start + 1;
+    while (i < hunks.length) {
+        const next = hunks[i];
+        if (next === undefined || next.baseOffset >= regionEnd) {
+            break;
+        }
+        regionEnd = Math.max(regionEnd, next.baseOffset + next.baseLength);
+        regionHunks.push(next);
+        i++;
+    }
+    return { regionStart, regionEnd, regionHunks, next: i };
+}
+/**
+ * Resolves a single grouped region into one merged chunk, or `null` when a
+ * one-sided region contributes no lines (e.g. a pure deletion). A region with
+ * changes from both sides is a conflict unless one side is unchanged from base
+ * (take the other) or both sides agree (take either).
+ */
+function resolveRegion(region, local, base, incoming) {
+    const { regionStart, regionEnd, regionHunks } = region;
+    const localHunks = regionHunks.filter((hunk) => hunk.side === 'local');
+    const incomingHunks = regionHunks.filter((hunk) => hunk.side === 'incoming');
+    // Only one side touched this region — apply its content verbatim.
+    if (localHunks.length === 0 || incomingHunks.length === 0) {
+        const oneSided = localHunks.length > 0 ? localHunks : incomingHunks;
+        const sideArr = localHunks.length > 0 ? local : incoming;
+        const lines = sliceSide(oneSided, sideArr, regionStart, regionEnd);
+        return lines.length > 0 ? { type: 'stable', lines } : null;
+    }
+    const localLines = sliceSide(localHunks, local, regionStart, regionEnd);
+    const incomingLines = sliceSide(incomingHunks, incoming, regionStart, regionEnd);
+    const baseLines = base.slice(regionStart, regionEnd);
+    // Both agree, or incoming never moved from base -> take local.
+    if (arraysEqual(localLines, incomingLines) || arraysEqual(incomingLines, baseLines)) {
+        return { type: 'stable', lines: localLines };
+    }
+    // Local never moved from base -> take the generator's version.
+    if (arraysEqual(localLines, baseLines)) {
+        return { type: 'stable', lines: incomingLines };
+    }
+    return { type: 'conflict', local: localLines, base: baseLines, incoming: incomingLines };
+}
+/**
+ * Performs a three-way line merge and returns the resolved/conflicting chunks.
+ *
+ * @param local - The developer's current version (on disk).
+ * @param base - The common ancestor (previous generation).
+ * @param incoming - The freshly generated version.
+ */
+function diff3Merge(local, base, incoming) {
+    const hunks = [
+        ...diffIndices(base, local).map((hunk) => ({ ...hunk, side: 'local' })),
+        ...diffIndices(base, incoming).map((hunk) => ({ ...hunk, side: 'incoming' })),
+    ];
+    // Order by base position; ties resolve local-before-incoming for stable output.
+    hunks.sort((a, b) => a.baseOffset - b.baseOffset || (a.side === b.side ? 0 : a.side === 'local' ? -1 : 1));
+    const chunks = [];
+    let cursor = 0;
+    const emitBase = (end) => {
+        if (end > cursor) {
+            chunks.push({ type: 'stable', lines: base.slice(cursor, end) });
+            cursor = end;
+        }
+    };
+    let i = 0;
+    while (i < hunks.length) {
+        const first = hunks[i];
+        if (first === undefined) {
+            i++;
+            continue;
+        }
+        const region = collectRegion(first, hunks, i);
+        i = region.next;
+        emitBase(region.regionStart);
+        const chunk = resolveRegion(region, local, base, incoming);
+        if (chunk !== null) {
+            chunks.push(chunk);
+        }
+        cursor = region.regionEnd;
+    }
+    emitBase(base.length);
+    return chunks;
+}
+/** Returns true if any chunk is an unresolved conflict. */
+function hasConflictChunk(chunks) {
+    return chunks.some((chunk) => chunk.type === 'conflict');
+}

package/dist/utils/merge-conflict.d.ts

@@ -35,12 +35,38 @@ export declare function hasMergeConflictMarkers(content: FileContent): boolean;
  * // your custom code here
  * // @custom-end:myFeature
  */
-export declare function generateMergeConflict({ contentSource, contentIncoming, labelSource, labelIncoming, }: {
+export declare function generateMergeConflict({ contentSource, contentIncoming, contentBase, labelSource, labelIncoming, onWarning, }: {
     contentSource: FileContent;
     contentIncoming: FileContent;
+    /**
+     * The common ancestor (previous generation, `G(model_old)`). When provided as
+     * a string, a true three-way (diff3) merge is performed: developer edits and
+     * model-driven changes in disjoint regions merge cleanly, and conflict markers
+     * are emitted only where they genuinely overlap. When omitted (legacy projects,
+     * first run after upgrade), the function falls back to the 2-way path below.
+     */
+    contentBase?: FileContent;
     labelSource?: string;
     labelIncoming?: string;
+    /** Sink for `@custom-override` advisories. Defaults to a yellow `console.warn`. */
+    onWarning?: (message: string) => void;
 }): FileContent;
+/**
+ * Applies `@custom-override:<member>` regions: for each overridden member, the
+ * developer's version (from `local`) replaces the generator's version inside
+ * `incoming`, so diff3 sees both sides agree and auto-resolves to the developer's
+ * code. When the generator would itself have changed that member (its body
+ * differs between `base` and `incoming`), an advisory is emitted so the developer
+ * can deliberately re-sync rather than silently shadow a model-driven change.
+ */
+export declare function applyCustomOverrides({ base, local, incoming, onWarning, }: {
+    base: string;
+    local: string;
+    incoming: string;
+    onWarning: (message: string) => void;
+}): {
+    incoming: string;
+};
 /**
  * Generates a summary of the differences between two files: For each conflict,
  * it will show the first 3 lines of each conflict with line counters, i.e.:

package/dist/utils/merge-conflict.js

@@ -36,10 +36,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.mergeConflictMarkers = void 0;
 exports.hasMergeConflictMarkers = hasMergeConflictMarkers;
 exports.generateMergeConflict = generateMergeConflict;
+exports.applyCustomOverrides = applyCustomOverrides;
 exports.generateDiffSummary = generateDiffSummary;
 const Diff = __importStar(require("diff"));
 const utils_1 = require("@postxl/utils");
 const custom_blocks_1 = require("./custom-blocks");
+const diff3_1 = require("./diff3");
 /**
  * Standard merge conflict markers used by git and our generator
  */
@@ -136,7 +138,7 @@ function isWhitespaceOnlyDifference(sourceLines, incomingLines) {
  * // your custom code here
  * // @custom-end:myFeature
  */
-function generateMergeConflict({ contentSource, contentIncoming, labelSource = 'Manual', labelIncoming = 'Generated', }) {
+function generateMergeConflict({ contentSource, contentIncoming, contentBase, labelSource = 'Manual', labelIncoming = 'Generated', onWarning = (message) => console.warn((0, utils_1.yellow)(message)), }) {
     // In case the content is binary, we just return the incoming content
     if (typeof contentSource !== 'string' || typeof contentIncoming !== 'string') {
         return contentIncoming;
@@ -148,6 +150,17 @@ function generateMergeConflict({ contentSource, contentIncoming, labelSource = '
     if (sourceNormalized === incomingNormalized) {
         return contentIncoming;
     }
+    // True three-way merge when a base (previous generation) is available.
+    if (typeof contentBase === 'string') {
+        return generateThreeWayMerge({
+            contentBase,
+            contentSource,
+            contentIncoming,
+            labelSource,
+            labelIncoming,
+            onWarning,
+        });
+    }
     // Handle custom blocks: extract from source, insert into incoming
     if ((0, custom_blocks_1.hasCustomBlockMarkers)(contentSource)) {
         return generateMergeConflictWithCustomBlocks({
@@ -165,6 +178,122 @@ function generateMergeConflict({ contentSource, contentIncoming, labelSource = '
         labelIncoming,
     });
 }
+/**
+ * Generates a true three-way merge between the previous generation (`base`),
+ * the developer's on-disk file (`source`/local), and the freshly generated file
+ * (`incoming`).
+ *
+ * Steps:
+ * 1. Apply any `@custom-override:<member>` regions by substituting the developer's
+ *    version of those members into the incoming content (so they auto-resolve),
+ *    emitting an advisory when the generator itself would have changed the member.
+ * 2. Run diff3 over the line arrays.
+ * 3. Suppress whitespace-only conflicts (reformatting must not manufacture them).
+ * 4. Emit conflict markers only for genuinely overlapping changes.
+ */
+function generateThreeWayMerge({ contentBase, contentSource, contentIncoming, labelSource, labelIncoming, onWarning, }) {
+    const { incoming: effectiveIncoming } = applyCustomOverrides({
+        base: contentBase,
+        local: contentSource,
+        incoming: contentIncoming,
+        onWarning,
+    });
+    // Preserve `@custom-start`/`@custom-end` blocks the same way the 2-way path
+    // does: extract them from the developer's file, run diff3 on the remaining
+    // content, then re-insert the blocks. Without this, a model change in the same
+    // base region as a custom block would drag the block into conflict markers
+    // (a regression vs. the 2-way behavior). Removing the blocks before diff3
+    // guarantees they never appear inside markers; they are re-anchored afterwards.
+    if ((0, custom_blocks_1.hasCustomBlockMarkers)(contentSource)) {
+        const extractResult = (0, custom_blocks_1.extractCustomBlocks)(contentSource);
+        if (extractResult.blocks.length > 0) {
+            const sourceWithoutBlocks = (0, custom_blocks_1.reconstructNonCustomContent)(extractResult);
+            const chunks = (0, diff3_1.diff3Merge)(splitLines(sourceWithoutBlocks), splitLines(contentBase), splitLines(effectiveIncoming));
+            const merged = formatDiff3Chunks(chunks, labelSource, labelIncoming);
+            const { content, unplacedBlocks } = (0, custom_blocks_1.insertCustomBlocks)(extractResult.blocks, merged);
+            return handleUnplacedBlocks(content, unplacedBlocks);
+        }
+    }
+    const chunks = (0, diff3_1.diff3Merge)(splitLines(contentSource), splitLines(contentBase), splitLines(effectiveIncoming));
+    return formatDiff3Chunks(chunks, labelSource, labelIncoming);
+}
+/**
+ * Splits content into lines on normalized (Unix) line endings. A trailing
+ * newline yields a trailing empty line, which round-trips back to a trailing
+ * newline on join — preserving the file's exact terminal newline.
+ */
+function splitLines(content) {
+    return content.replaceAll('\r\n', '\n').replaceAll('\r', '\n').split('\n');
+}
+/**
+ * Renders diff3 chunks into a string, emitting conflict markers for unresolved
+ * regions. Whitespace-only conflicts are resolved in favor of the incoming
+ * (generated) side so reformatting churn never surfaces as a conflict.
+ */
+function formatDiff3Chunks(chunks, labelSource, labelIncoming) {
+    const out = [];
+    for (const chunk of chunks) {
+        if (chunk.type === 'stable') {
+            out.push(...chunk.lines);
+            continue;
+        }
+        if (isWhitespaceOnlyDifference(chunk.local, chunk.incoming)) {
+            out.push(...chunk.incoming);
+            continue;
+        }
+        out.push(`${exports.mergeConflictMarkers.start} ${labelSource}`, ...chunk.local, exports.mergeConflictMarkers.separator, ...chunk.incoming, `${exports.mergeConflictMarkers.end} ${labelIncoming}`);
+    }
+    return out.join('\n');
+}
+/**
+ * Applies `@custom-override:<member>` regions: for each overridden member, the
+ * developer's version (from `local`) replaces the generator's version inside
+ * `incoming`, so diff3 sees both sides agree and auto-resolves to the developer's
+ * code. When the generator would itself have changed that member (its body
+ * differs between `base` and `incoming`), an advisory is emitted so the developer
+ * can deliberately re-sync rather than silently shadow a model-driven change.
+ */
+function applyCustomOverrides({ base, local, incoming, onWarning, }) {
+    if (!(0, custom_blocks_1.hasCustomOverrideMarkers)(local)) {
+        return { incoming };
+    }
+    const localLines = splitLines(local);
+    const baseLines = splitLines(base);
+    let incomingLines = splitLines(incoming);
+    for (const member of (0, custom_blocks_1.extractOverrideMemberNames)(local)) {
+        // `findMemberRange` starts at the member's signature line (it skips leading
+        // comments), so `localMember` deliberately excludes the `@custom-override`
+        // marker line that sits above it. That marker therefore stays in `local` as a
+        // local-only line relative to `base`/`incoming`, and diff3 auto-preserves it
+        // without it ever landing inside the substituted member body.
+        const localRange = (0, custom_blocks_1.findMemberRange)(localLines, member);
+        if (!localRange) {
+            onWarning(`@custom-override:${member} — member not found in the current file; ignoring this override.`);
+            continue;
+        }
+        const localMember = localLines.slice(localRange.start, localRange.end);
+        const incomingRange = (0, custom_blocks_1.findMemberRange)(incomingLines, member);
+        if (!incomingRange) {
+            onWarning(`@custom-override:${member} — the generator no longer emits this member; your version is preserved.`);
+            continue;
+        }
+        const incomingMember = incomingLines.slice(incomingRange.start, incomingRange.end);
+        const baseRange = (0, custom_blocks_1.findMemberRange)(baseLines, member);
+        if (baseRange) {
+            const baseMember = baseLines.slice(baseRange.start, baseRange.end);
+            if (!isWhitespaceOnlyDifference(baseMember, incomingMember)) {
+                onWarning(`@custom-override:${member} — the generator changed this member, but your override shadows it. ` +
+                    `Remove the override and re-sync if you want the new generated version.`);
+            }
+        }
+        incomingLines = [
+            ...incomingLines.slice(0, incomingRange.start),
+            ...localMember,
+            ...incomingLines.slice(incomingRange.end),
+        ];
+    }
+    return { incoming: incomingLines.join('\n') };
+}
 /**
  * Generates merge conflict output while preserving custom blocks.
  *

package/dist/utils/sync.d.ts

@@ -83,6 +83,15 @@ type SyncParams = {
      * `logSyncResult` to summarize the diff.
      */
     dryRun?: boolean;
+    /**
+     * The previous generation (`G(model_old)`) as a virtual file system, keyed by
+     * the same POSIX paths as `vfs`. When a file ends up in a `MergeConflict` state
+     * and its content is available here, sync performs a true three-way (diff3)
+     * merge instead of the 2-way disk-vs-fresh diff: developer edits and
+     * model-driven changes in disjoint regions merge cleanly. Omit (legacy projects
+     * / first run after upgrade) to fall back to the 2-way path.
+     */
+    baseVfs?: VirtualFileSystem;
 };
 /**
  * Error returned when files with unresolved merge conflicts are detected
@@ -125,7 +134,7 @@ export type SyncResults = {
  * merge conflict markers. If found, the sync will abort immediately and return an error with the
  * list of files that need to be resolved before generation can continue.
  */
-export declare function sync({ vfs, lockFilePath, diskFilePath, force, selectiveGeneration, dryRun, }: SyncParams): Promise<SyncResults>;
+export declare function sync({ vfs, lockFilePath, diskFilePath, force, selectiveGeneration, dryRun, baseVfs, }: SyncParams): Promise<SyncResults>;
 type FileState = {
     state: 'empty';
 } | {
@@ -158,6 +167,7 @@ type Action_MergeConflict = {
     type: `MergeConflict`;
     diskContent: FileContent;
     virtualContent: FileContent;
+    baseContent?: FileContent;
 };
 export type ActionType = Action['type'];
 export declare function executeAction(filePath: Path.PosixPath, action: Action): Promise<ActionResult>;

package/dist/utils/sync.js

@@ -121,7 +121,7 @@ const Path = __importStar(require("./path"));
  * merge conflict markers. If found, the sync will abort immediately and return an error with the
  * list of files that need to be resolved before generation can continue.
  */
-async function sync({ vfs, lockFilePath, diskFilePath, force, selectiveGeneration, dryRun, }) {
+async function sync({ vfs, lockFilePath, diskFilePath, force, selectiveGeneration, dryRun, baseVfs, }) {
     const diskPathNormalized = Path.normalize(diskFilePath);
     const files = await getFilesStates({ vfs, lockFilePath, diskFilePath, selectiveGeneration: !!selectiveGeneration });
     // Check for unresolved merge conflicts before writing any files
@@ -155,7 +155,7 @@ async function sync({ vfs, lockFilePath, diskFilePath, force, selectiveGeneratio
             };
             continue;
         }
-        const [action, isEjectedFile] = determineActionState({ virtual, lock, disk }, force);
+        const [action, isEjectedFile] = determineActionState({ virtual, lock, disk }, force, baseVfs?.get(filePath));
         if (dryRun) {
             // Dry-run: record the planned action but do not touch disk.
             result.files[filePath] = {
@@ -340,7 +340,7 @@ const actionMap = {
     'V:empty-L:empty-D:Hash0': ['NoAction', false, 'NoAction'], // Indistinguishable from "empty-empty-HashX"
     'V:empty-L:empty-D:empty': ['NoAction', false, 'NoAction'], // Cannot occur
 };
-function determineActionState({ virtual, lock, disk }, force) {
+function determineActionState({ virtual, lock, disk }, force, baseContent) {
     const stateKey = getStateKey({ virtual, lock, disk });
     const [defaultActionType, isEjected, forceActionType] = actionMap[stateKey];
     const actionType = force ? forceActionType : defaultActionType;
@@ -357,7 +357,15 @@ function determineActionState({ virtual, lock, disk }, force) {
         if (virtual.state === 'empty') {
             throw new Error(`This should not happen assuming that the actionMap only has 'Write' actions for entries starting with H1, ie a defined virtual file`);
         }
-        return [{ type: 'MergeConflict', diskContent: disk.content, virtualContent: virtual.content }, isEjected];
+        return [
+            {
+                type: 'MergeConflict',
+                diskContent: disk.content,
+                virtualContent: virtual.content,
+                ...(baseContent === undefined ? {} : { baseContent }),
+            },
+            isEjected,
+        ];
     }
     return [{ type: actionType }, isEjected];
 }
@@ -375,7 +383,11 @@ async function executeAction(filePath, action) {
             throw new utils_1.ExhaustiveSwitchCheck(action);
     }
 }
-async function writeMergeConflictFile(filePath, { diskContent, virtualContent }) {
-    const content = (0, merge_conflict_1.generateMergeConflict)({ contentSource: diskContent, contentIncoming: virtualContent });
+async function writeMergeConflictFile(filePath, { diskContent, virtualContent, baseContent }) {
+    const content = (0, merge_conflict_1.generateMergeConflict)({
+        contentSource: diskContent,
+        contentIncoming: virtualContent,
+        ...(baseContent === undefined ? {} : { contentBase: baseContent }),
+    });
     return (0, fs_utils_1.writeFile)(filePath, content);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postxl/generator",
-  "version": "1.6.3",
+  "version": "1.7.0",
   "description": "Core package that orchestrates the code generation of a PXL project",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -46,7 +46,7 @@
     "jszip": "3.10.1",
     "minimatch": "^10.2.5",
     "p-limit": "3.1.0",
-    "@postxl/schema": "^2.0.1",
+    "@postxl/schema": "^2.1.0",
     "@postxl/utils": "^1.4.1"
   },
   "devDependencies": {