release-skill 0.1.1

package/src/artifacts/merge/markdown.mjs

@@ -0,0 +1,246 @@
+/**
+ * Markdown format-preserving three-way merge.
+ *
+ * Splits the file into frontmatter, managed regions (declared by start/end
+ * markers), and unmanaged body ranges.  Unmanaged ranges are byte-preserved
+ * from the current side.  Managed regions are merged via text diff3 on the
+ * region content.  Frontmatter is merged via text diff3 on the YAML block.
+ *
+ * No full-file parse or stringify is ever performed — all edits are
+ * localised byte-range replacements.
+ *
+ * @module artifacts/merge/markdown
+ */
+
+import { parseManagedRegions } from './regions.mjs';
+import { mergeText } from './text.mjs';
+
+/**
+ * Detect YAML frontmatter in a Markdown buffer.
+ *
+ * Frontmatter starts with `---\n` at offset 0 and ends at the next `---\n`.
+ *
+ * @param {Buffer} bytes
+ * @returns {{ endOffset: number }|null} End offset (exclusive) of the frontmatter
+ *   block including the closing `---\n`, or null if no frontmatter.
+ */
+function detectFrontmatter(bytes) {
+  const text = bytes.toString('utf8');
+  if (!text.startsWith('---\n') && !text.startsWith('---\r\n')) return null;
+
+  // Find the closing ---
+  const afterFirstDelimiter = text.startsWith('---\r\n') ? 5 : 4;
+  const rest = text.substring(afterFirstDelimiter);
+  const closeIdx = rest.indexOf('\n---\n');
+  if (closeIdx < 0) return null;
+
+  // end offset = afterFirstDelimiter + closeIdx + length of "\n---\n"
+  return { endOffset: afterFirstDelimiter + closeIdx + 5 };
+}
+
+/**
+ * Merge two Markdown modifications of the same base content.
+ *
+ * @param {object} options
+ * @param {Buffer} options.base      - Base Markdown content.
+ * @param {Buffer} options.current   - Current (human) Markdown content.
+ * @param {Buffer} options.generated - Generated (producer) Markdown content.
+ * @param {Array<{ id: string, start: string, end: string }>} [options.managedRegions]
+ *   Managed-region declarations.  Each region is delimited by start/end markers.
+ * @returns {{ status: 'MERGEABLE'|'CONFLICT'|'STRUCTURE_INVALID', bytes?: Buffer, conflicts: object[] }}
+ */
+export function mergeMarkdown({ base, current, generated, managedRegions = [] } = {}) {
+  // Null/missing inputs → CONFLICT
+  if (!base || !current || !generated) {
+    return Object.freeze({
+      status: 'CONFLICT',
+      bytes: undefined,
+      conflicts: Object.freeze([{ reason: 'missing input' }]),
+    });
+  }
+
+  // Parse managed regions from the CURRENT side (authoritative layout)
+  let currentRanges;
+  try {
+    currentRanges = parseManagedRegions(current, managedRegions);
+  } catch (err) {
+    if (err.code === 'STRUCTURE_INVALID') {
+      return Object.freeze({
+        status: 'STRUCTURE_INVALID',
+        bytes: undefined,
+        conflicts: Object.freeze([{ reason: err.message }]),
+      });
+    }
+    throw err;
+  }
+
+  // Also parse from base and generated to verify consistency
+  let baseRanges;
+  try {
+    baseRanges = parseManagedRegions(base, managedRegions);
+  } catch (err) {
+    if (err.code === 'STRUCTURE_INVALID') {
+      return Object.freeze({
+        status: 'STRUCTURE_INVALID',
+        bytes: undefined,
+        conflicts: Object.freeze([{ reason: `base: ${err.message}` }]),
+      });
+    }
+    throw err;
+  }
+
+  let generatedRanges;
+  try {
+    generatedRanges = parseManagedRegions(generated, managedRegions);
+  } catch (err) {
+    if (err.code === 'STRUCTURE_INVALID') {
+      return Object.freeze({
+        status: 'STRUCTURE_INVALID',
+        bytes: undefined,
+        conflicts: Object.freeze([{ reason: `generated: ${err.message}` }]),
+      });
+    }
+    throw err;
+  }
+
+  // Detect frontmatter on all three sides
+  const baseFm = detectFrontmatter(base);
+  const currentFm = detectFrontmatter(current);
+  const genFm = detectFrontmatter(generated);
+
+  // Build output by walking unmanaged and managed ranges in order
+  const output = [];
+  let cursor = 0;
+
+  // Process frontmatter first (if present on any side).
+  // Three-way frontmatter rules for all 8 presence combinations:
+  //   base current generated → action
+  //   0    0       0         → no FM
+  //   0    0       1         → include generated FM (generated-only addition)
+  //   0    1       0         → preserve current FM (human addition)
+  //   0    1       1         → preserve current FM (human overrides)
+  //   1    0       0         → accept removal
+  //   1    0       1         → if changed → CONFLICT; else accept removal
+  //   1    1       0         → preserve current FM (generated removed, human kept)
+  //   1    1       1         → three-way merge
+  if (currentFm || baseFm || genFm) {
+    const baseFmEnd = baseFm?.endOffset ?? 0;
+    const currentFmEnd = currentFm?.endOffset ?? 0;
+    const genFmEnd = genFm?.endOffset ?? 0;
+
+    if (baseFm && currentFm && genFm) {
+      // All three have frontmatter — three-way merge
+      const baseFmBytes = base.subarray(0, baseFmEnd);
+      const currentFmBytes = current.subarray(0, currentFmEnd);
+      const genFmBytes = generated.subarray(0, genFmEnd);
+
+      const fmResult = mergeText({
+        base: baseFmBytes,
+        current: currentFmBytes,
+        generated: genFmBytes,
+      });
+
+      if (fmResult.status === 'CONFLICT') {
+        return Object.freeze({
+          status: 'CONFLICT',
+          bytes: undefined,
+          conflicts: Object.freeze(fmResult.conflicts.map((c) =>
+            Object.freeze({ ...c, regionId: 'frontmatter' }),
+          )),
+        });
+      }
+
+      output.push(fmResult.bytes);
+      cursor = currentFmEnd;
+    } else if (!baseFm && !currentFm && genFm) {
+      // Generated-only new frontmatter — include it
+      output.push(generated.subarray(0, genFmEnd));
+      cursor = 0; // no frontmatter consumed from current
+    } else if (currentFm) {
+      // Current has frontmatter — preserve it (covers 0/1/0, 0/1/1, 1/1/0)
+      output.push(current.subarray(0, currentFmEnd));
+      cursor = currentFmEnd;
+    } else if (baseFm && genFm) {
+      // Base and generated have frontmatter, current removed it (1/0/1)
+      const baseFmContent = base.subarray(0, baseFmEnd);
+      const genFmContent = generated.subarray(0, genFmEnd);
+      if (!baseFmContent.equals(genFmContent)) {
+        // Generated changed frontmatter but current removed it → conflict
+        return Object.freeze({
+          status: 'CONFLICT',
+          bytes: undefined,
+          conflicts: Object.freeze([{
+            reason: 'frontmatter removed by current but modified by generated',
+            regionId: 'frontmatter',
+          }]),
+        });
+      }
+      // Generated didn't change frontmatter — accept current's removal (1/0/0)
+    }
+  }
+
+  // Sort regions by start offset for ordered processing
+  const sortedRegions = [...currentRanges.entries()]
+    .sort(([, a], [, b]) => a.start - b.start);
+
+  for (const [regionId, currentRange] of sortedRegions) {
+    // Emit unmanaged bytes before this region (from current)
+    if (cursor < currentRange.start) {
+      output.push(current.subarray(cursor, currentRange.start));
+    }
+
+    // Get the corresponding range in base and generated
+    const baseRange = baseRanges.get(regionId);
+    const genRange = generatedRanges.get(regionId);
+
+    if (!baseRange || !genRange) {
+      // Region missing in base or generated — structural mismatch
+      return Object.freeze({
+        status: 'STRUCTURE_INVALID',
+        bytes: undefined,
+        conflicts: Object.freeze([{
+          reason: `managed region '${regionId}' has inconsistent marker positions across sides`,
+        }]),
+      });
+    }
+
+    // Extract region content from each side (between markers, exclusive)
+    const baseContent = base.subarray(baseRange.start, baseRange.end);
+    const currentContent = current.subarray(currentRange.start, currentRange.end);
+    const generatedContent = generated.subarray(genRange.start, genRange.end);
+
+    // Text merge the region content
+    const regionResult = mergeText({
+      base: baseContent,
+      current: currentContent,
+      generated: generatedContent,
+    });
+
+    if (regionResult.status === 'CONFLICT') {
+      return Object.freeze({
+        status: 'CONFLICT',
+        bytes: undefined,
+        conflicts: Object.freeze(regionResult.conflicts.map((c) =>
+          Object.freeze({ ...c, regionId }),
+        )),
+      });
+    }
+
+    // Emit merged region bytes
+    output.push(regionResult.bytes);
+    cursor = currentRange.end;
+  }
+
+  // Emit any trailing unmanaged bytes after the last region
+  if (cursor < current.length) {
+    output.push(current.subarray(cursor));
+  }
+
+  const bytes = Buffer.concat(output);
+
+  return Object.freeze({
+    status: 'MERGEABLE',
+    bytes,
+    conflicts: Object.freeze([]),
+  });
+}

package/src/artifacts/merge/regions.mjs

@@ -0,0 +1,156 @@
+/**
+ * Managed region parser for structured merge drivers.
+ *
+ * Parses managed-region declarations (start/end marker pairs) from raw
+ * byte content and returns a projection map of region id → byte range.
+ *
+ * Enforces:
+ * - No duplicate start or end markers for the same region id.
+ * - No nested or overlapping regions.
+ * - Every declared region must have both start and end markers present.
+ *
+ * All operations are byte-level; no full-file parse or stringify.
+ *
+ * @module artifacts/merge/regions
+ */
+
+import { ReleaseError, STRUCTURE_INVALID } from '../../core/errors.mjs';
+
+/**
+ * @typedef {{ start: number, end: number }} ByteRange
+ * start is inclusive byte offset of the start marker; end is the exclusive
+ * byte offset past the end marker (i.e., end marker last byte + 1).
+ */
+
+/**
+ * Parse managed-region declarations from raw bytes.
+ *
+ * Returns a Map of region id → { start, end } byte ranges.
+ *
+ * @param {Buffer} bytes - Raw file content.
+ * @param {Array<{ id: string, start: string, end: string }>} declarations
+ * @returns {Map<string, ByteRange>}
+ * @throws {ReleaseError} with code STRUCTURE_INVALID on duplicate/nested/missing markers.
+ */
+export function parseManagedRegions(bytes, declarations) {
+  const result = new Map();
+
+  // Reject empty marker strings upfront to prevent infinite loops
+  for (const decl of declarations) {
+    if (!decl.start || !decl.end) {
+      throw new ReleaseError(
+        STRUCTURE_INVALID,
+        `managed region '${decl.id}' has empty start or end marker`,
+        { regionId: decl.id },
+      );
+    }
+  }
+
+  // Reject duplicate declaration ids
+  const seenIds = new Set();
+  for (const decl of declarations) {
+    if (seenIds.has(decl.id)) {
+      throw new ReleaseError(
+        STRUCTURE_INVALID,
+        `duplicate declaration id '${decl.id}' in managed region declarations`,
+        { regionId: decl.id },
+      );
+    }
+    seenIds.add(decl.id);
+  }
+
+  /** @type {Array<{ id: string, kind: 'start'|'end', offset: number }>} */
+  const markers = [];
+
+  // Collect all marker occurrences
+  for (const decl of declarations) {
+    let offset = 0;
+    while (offset <= bytes.length) {
+      const idx = bytes.indexOf(decl.start, offset, 'utf8');
+      if (idx < 0) break;
+      markers.push({ id: decl.id, kind: 'start', offset: idx });
+      offset = idx + Buffer.byteLength(decl.start, 'utf8');
+      // Guard: if marker is empty this would be an infinite loop (handled above)
+    }
+    offset = 0;
+    while (offset <= bytes.length) {
+      const idx = bytes.indexOf(decl.end, offset, 'utf8');
+      if (idx < 0) break;
+      markers.push({ id: decl.id, kind: 'end', offset: idx });
+      offset = idx + Buffer.byteLength(decl.end, 'utf8');
+    }
+  }
+
+  // Reject declared regions whose markers are completely absent from content
+  for (const decl of declarations) {
+    const hasStart = markers.some((m) => m.id === decl.id && m.kind === 'start');
+    const hasEnd = markers.some((m) => m.id === decl.id && m.kind === 'end');
+    if (!hasStart && !hasEnd) {
+      throw new ReleaseError(
+        STRUCTURE_INVALID,
+        `managed region '${decl.id}' markers not found in content`,
+        { regionId: decl.id },
+      );
+    }
+  }
+
+  // Sort by offset, then 'start' before 'end' at same offset
+  markers.sort((a, b) => a.offset - b.offset || (a.kind === 'start' ? -1 : 1));
+
+  // Validate and extract ranges
+  /** @type {Map<string, { startOffset: number }>} */
+  const openRegions = new Map();
+
+  for (const marker of markers) {
+    if (marker.kind === 'start') {
+      if (openRegions.has(marker.id)) {
+        throw new ReleaseError(
+          STRUCTURE_INVALID,
+          `duplicate start marker for managed region '${marker.id}'`,
+          { regionId: marker.id, offset: marker.offset },
+        );
+      }
+      // Check for nesting: any currently-open region with a different id
+      // whose start is after this offset indicates overlap
+      for (const [openId, openInfo] of openRegions) {
+        if (openId !== marker.id && openInfo.startOffset < marker.offset) {
+          // There's an open region that started before this one — overlapping
+          throw new ReleaseError(
+            STRUCTURE_INVALID,
+            `managed region '${marker.id}' overlaps with open region '${openId}'`,
+            { regionId: marker.id, overlappingWith: openId },
+          );
+        }
+      }
+      openRegions.set(marker.id, { startOffset: marker.offset });
+    } else {
+      // end marker
+      if (!openRegions.has(marker.id)) {
+        throw new ReleaseError(
+          STRUCTURE_INVALID,
+          `end marker for managed region '${marker.id}' found without matching start`,
+          { regionId: marker.id, offset: marker.offset },
+        );
+      }
+      const openInfo = openRegions.get(marker.id);
+      const decl = declarations.find((d) => d.id === marker.id);
+      const endMarkerLen = Buffer.byteLength(decl.end, 'utf8');
+      result.set(marker.id, {
+        start: openInfo.startOffset,
+        end: marker.offset + endMarkerLen,
+      });
+      openRegions.delete(marker.id);
+    }
+  }
+
+  // Any remaining open regions are missing their end markers
+  for (const [id] of openRegions) {
+    throw new ReleaseError(
+      STRUCTURE_INVALID,
+      `managed region '${id}' has start marker but no end marker`,
+      { regionId: id },
+    );
+  }
+
+  return result;
+}