@opengsd/gsd-core 1.17.0 → 1.19.0

package/gsd-core/bin/lib/markdown-line-diff.cjs

@@ -0,0 +1,147 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SCOPED_EDIT_DISTANCE = void 0;
+exports.matchLines = matchLines;
+exports.writeScope = writeScope;
+/**
+ * Line alignment for scoped Markdown normalization (#5165).
+ *
+ * `platformWriteSync` re-spaces a `.md` document on every write. Given the
+ * document the write replaces, only the line junctions the write itself made
+ * need that treatment; everything else is published byte-for-byte. This module
+ * is the pure half of that: it aligns the new lines against the prior lines and
+ * says which junctions the write left alone. It performs no I/O.
+ */
+/**
+ * Largest line-edit distance `matchLines` will search for. A write that changed
+ * more than this many lines is a rewrite, not an edit: it falls back to
+ * whole-document normalization (the pre-#5165 behavior), which also bounds the
+ * diff's time and memory.
+ */
+exports.MAX_SCOPED_EDIT_DISTANCE = 400;
+/**
+ * Align the lines of the document being written (`next`) against the document
+ * it replaces (`prev`). Returns, per `next` line, the index of its counterpart
+ * in `prev` (a longest-common-subsequence match, Myers' O(ND) greedy diff after
+ * trimming the common prefix and suffix), or -1 for a line the write added or
+ * changed. Null when the documents differ by more than MAX_SCOPED_EDIT_DISTANCE
+ * edits.
+ */
+function matchLines(prev, next) {
+    const match = new Int32Array(next.length).fill(-1);
+    const common = Math.min(prev.length, next.length);
+    let lo = 0;
+    while (lo < common && prev[lo] === next[lo]) {
+        match[lo] = lo;
+        lo++;
+    }
+    let prevEnd = prev.length;
+    let nextEnd = next.length;
+    while (prevEnd > lo && nextEnd > lo && prev[prevEnd - 1] === next[nextEnd - 1]) {
+        prevEnd--;
+        nextEnd--;
+        match[nextEnd] = prevEnd;
+    }
+    const a = prev.slice(lo, prevEnd);
+    const b = next.slice(lo, nextEnd);
+    const n = a.length;
+    const m = b.length;
+    if (n === 0 || m === 0)
+        return match;
+    const max = Math.min(n + m, exports.MAX_SCOPED_EDIT_DISTANCE);
+    const off = max + 1;
+    const v = new Int32Array(2 * max + 3);
+    const trace = [];
+    let found = -1;
+    for (let d = 0; d <= max && found < 0; d++) {
+        trace.push(v.slice()); // the furthest-reaching points after d-1 edits
+        for (let k = -d; k <= d; k += 2) {
+            let x = (k === -d || (k !== d && v[off + k - 1] < v[off + k + 1])) ? v[off + k + 1] : v[off + k - 1] + 1;
+            let y = x - k;
+            while (x < n && y < m && a[x] === b[y]) {
+                x++;
+                y++;
+            }
+            v[off + k] = x;
+            if (x >= n && y >= m) {
+                found = d;
+                break;
+            }
+        }
+    }
+    if (found < 0)
+        return null;
+    let x = n;
+    let y = m;
+    for (let d = found; d > 0; d--) {
+        const before = trace[d];
+        const k = x - y;
+        const prevK = (k === -d || (k !== d && before[off + k - 1] < before[off + k + 1])) ? k + 1 : k - 1;
+        const prevX = before[off + prevK];
+        const prevY = prevX - prevK;
+        while (x > prevX && y > prevY) {
+            x--;
+            y--;
+            match[lo + y] = lo + x;
+        }
+        x = prevX;
+        y = prevY;
+    }
+    while (x > 0 && y > 0) {
+        x--;
+        y--;
+        match[lo + y] = lo + x;
+    }
+    return match;
+}
+/**
+ * Derive a {@link WriteScope} from a line alignment. A junction is the write's
+ * own — and so is normalized — when it is wholly inside text the write added,
+ * or when a deletion between two kept lines made them newly adjacent. The
+ * boundary of an edit that replaced lines inherits the surrounding spacing:
+ * replacing a line in place must not add blank lines around it.
+ */
+function writeScope(match, prevLength) {
+    // For each unmatched line: how many prior lines its run of changed lines replaced.
+    const replaced = new Int32Array(match.length);
+    const priorIndex = new Int32Array(match.length).fill(-1);
+    for (let i = 0; i < match.length;) {
+        if (match[i] >= 0) {
+            i++;
+            continue;
+        }
+        let end = i;
+        while (end + 1 < match.length && match[end + 1] < 0)
+            end++;
+        const before = i > 0 ? match[i - 1] : -1;
+        const after = end + 1 < match.length ? match[end + 1] : prevLength;
+        const dropped = after - before - 1;
+        for (let j = i; j <= end; j++) {
+            replaced[j] = dropped;
+            if (j - i < dropped)
+                priorIndex[j] = before + 1 + (j - i);
+        }
+        i = end + 1;
+    }
+    return {
+        junctionKept(i) {
+            const left = match[i] >= 0;
+            const right = match[i + 1] >= 0;
+            // Two kept lines are one junction only if nothing sat between them in the
+            // prior document; a deletion made them adjacent, so the write owns it.
+            if (left && right)
+                return match[i + 1] - match[i] === 1;
+            if (left)
+                return replaced[i + 1] >= 1;
+            if (right)
+                return replaced[i] >= 1;
+            return false;
+        },
+        lineWritten(i) {
+            return match[i] < 0;
+        },
+        replacedPriorIndex(i) {
+            return priorIndex[i] ?? -1;
+        },
+    };
+}

package/gsd-core/bin/lib/markdown-sectionizer.cjs

@@ -25,6 +25,9 @@ exports.updateBullet = updateBullet;
 exports.updateHeading = updateHeading;
 exports.extractTaggedBlocks = extractTaggedBlocks;
 exports.stripTaggedBlocks = stripTaggedBlocks;
+exports.editOutsideTaggedBlocks = editOutsideTaggedBlocks;
+exports.maskFences = maskFences;
+exports.editOutsideFences = editOutsideFences;
 exports.replaceSection = replaceSection;
 exports.withSection = withSection;
 exports.deleteSection = deleteSection;
@@ -850,6 +853,116 @@ function stripTaggedBlocks(content, tagName, allowAttributes = false, caseSensit
         return content;
     return content.replace(taggedBlockPattern(tagName, caseSensitive ? 'g' : 'gi', allowAttributes), '');
 }
+/**
+ * Run `edit` over `content` with every `<tagName>…</tagName>` block hidden from
+ * it, then put the blocks back byte-for-byte (#5543). The blocks are swapped for
+ * one-line placeholder comments, so `edit` sees the rest of the document in its
+ * original order and cannot touch, or be captured by, a block's contents.
+ *
+ * Same hardened block pattern as `stripTaggedBlocks` (exact `<tag>` opener, so
+ * `<details open>` stays visible to `edit`). If `edit` returns a non-string, or
+ * drops a placeholder, the original `content` is returned unchanged rather than
+ * a document with a block missing.
+ *
+ * Nested blocks are NOT supported, exactly as for `extractTaggedBlocks` and
+ * `stripTaggedBlocks`: the first `</tag>` closes the block. Every ROADMAP reader
+ * that strips shipped milestones shares that grammar, so this writer sees the
+ * same blocks those readers do.
+ */
+function editOutsideTaggedBlocks(content, tagName, edit, allowAttributes = false, caseSensitive = false) {
+    if (typeof content !== 'string' || content.length === 0)
+        return content;
+    if (typeof tagName !== 'string' || tagName.length === 0)
+        return edit(content);
+    const blocks = [];
+    let nonce = 0;
+    while (content.includes(`<!-- gsd-masked-${tagName}-${nonce}-`))
+        nonce += 1;
+    const placeholder = (i) => `<!-- gsd-masked-${tagName}-${nonce}-${i} -->`;
+    const masked = content.replace(taggedBlockPattern(tagName, caseSensitive ? 'g' : 'gi', allowAttributes), (block) => {
+        blocks.push(block);
+        return placeholder(blocks.length - 1);
+    });
+    if (blocks.length === 0)
+        return edit(content);
+    const edited = edit(masked);
+    if (typeof edited !== 'string')
+        return content;
+    let restored = edited;
+    for (let i = 0; i < blocks.length; i++) {
+        const marker = placeholder(i);
+        const at = restored.indexOf(marker);
+        if (at === -1 || restored.indexOf(marker, at + marker.length) !== -1)
+            return content;
+        restored = restored.slice(0, at) + blocks[i] + restored.slice(at + marker.length);
+    }
+    return restored;
+}
+/**
+ * Hide every fenced code block from a line-oriented edit. State-transition writers locate their
+ * target with `/^Field:.*$/m`-style patterns; those match a fenced EXAMPLE of the field as readily
+ * as the live line, so the example got the new value and the live line stayed stale. Masking each
+ * block to a single `<!-- gsd-masked-fence-… -->` line lets the same pattern see only live lines;
+ * `restore` splices the blocks back byte-for-byte (CRLF included — the original line text is kept).
+ * The fence grammar is `scanFencedBlocks`' (the one every reader here uses), and an unterminated
+ * fence masks to the end of the content, as `stripFencedCode` treats it.
+ */
+function maskFences(content) {
+    const identity = { masked: content, restore: (edited) => edited };
+    if (typeof content !== 'string' || content.length === 0)
+        return identity;
+    const lines = content.split('\n');
+    const blocks = scanFencedBlocks(lines);
+    if (blocks.length === 0)
+        return identity;
+    let nonce = 0;
+    while (content.includes(`<!-- gsd-masked-fence-${nonce}-`))
+        nonce += 1;
+    const placeholder = (i) => `<!-- gsd-masked-fence-${nonce}-${i} -->`;
+    const kept = [];
+    const originals = [];
+    let cursor = 0;
+    for (const block of blocks) {
+        const end = block.closeLineIdx === -1 ? lines.length - 1 : block.closeLineIdx;
+        for (; cursor < block.openLineIdx; cursor++)
+            kept.push(lines[cursor]);
+        originals.push(lines.slice(block.openLineIdx, end + 1).join('\n'));
+        kept.push(placeholder(originals.length - 1));
+        cursor = end + 1;
+    }
+    for (; cursor < lines.length; cursor++)
+        kept.push(lines[cursor]);
+    return {
+        masked: kept.join('\n'),
+        restore(edited) {
+            if (typeof edited !== 'string')
+                return null;
+            let restored = edited;
+            for (let i = 0; i < originals.length; i++) {
+                const marker = placeholder(i);
+                const at = restored.indexOf(marker);
+                if (at === -1 || restored.indexOf(marker, at + marker.length) !== -1)
+                    return null;
+                restored = restored.slice(0, at) + originals[i] + restored.slice(at + marker.length);
+            }
+            return restored;
+        },
+    };
+}
+/**
+ * Run `edit` over `content` with every fenced code block hidden from it (see `maskFences`).
+ * Content without a fence is edited as given. An edit that returns a non-string, or that loses a
+ * placeholder, returns the original content unchanged.
+ */
+function editOutsideFences(content, edit) {
+    if (typeof content !== 'string' || content.length === 0)
+        return content;
+    const mask = maskFences(content);
+    const edited = edit(mask.masked);
+    if (typeof edited !== 'string')
+        return content;
+    return mask.restore(edited) ?? content;
+}
 // ─── replaceSection ───────────────────────────────────────────────────────────
 /**
  * Splice `newBody` in place of a section's body and return the resulting

package/gsd-core/bin/lib/milestone-lock.cjs

@@ -57,6 +57,7 @@ exports.releaseMilestonePhase = releaseMilestonePhase;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const clock_cjs_1 = require("./clock.cjs");
+const git_info_exclude_cjs_1 = require("./git-info-exclude.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- active-workstream-store.cjs is an export= CommonJS module
@@ -122,7 +123,13 @@ function readClaim(cwd) {
 }
 function writeClaim(cwd, claim) {
     ensureClaimDir(cwd);
-    node_fs_1.default.writeFileSync(milestoneLockPath(cwd), JSON.stringify(claim, null, 2) + '\n');
+    const lockPath = milestoneLockPath(cwd);
+    node_fs_1.default.writeFileSync(lockPath, JSON.stringify(claim, null, 2) + '\n');
+    // #5551: the claim is per-machine state, never project content. Keep it out
+    // of `git status` (the ship preflight refuses a dirty tree). Every write, not
+    // only the first, so a claim file that predates this fix is covered too; the
+    // helper is idempotent and best-effort.
+    (0, git_info_exclude_cjs_1.excludeFromGit)(node_path_1.default.dirname(lockPath), exports.MILESTONE_LOCK_FILENAME);
 }
 // planningWorkspace.planningDir targets .planning (or the workstream-scoped
 // variant); the parent is created by every GSD command that gets this far, but

package/gsd-core/bin/lib/milestone-release-map.cjs

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * Milestone Release Map — validation, rendering and archive read-back for the
+ * per-repository release record `milestone complete --release-map` persists
+ * (#5706, phase 2 of epic #3628, docs/adr/3628-milestone-release-mapping.md).
+ *
+ * A release map is the caller-supplied record of what each repository shipped
+ * for a milestone. It is data: this module never resolves a repository to a
+ * directory, never consults `planning.sub_repos`, and never creates a tag. The
+ * map is archived by recorded value, so a repository that later leaves
+ * `planning.sub_repos` does not change an already-archived map.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELEASE_MAP_TAG_STATES = exports.RELEASE_MAP_STATUSES = exports.MAX_RELEASE_MAP_FILE_BYTES = exports.MAX_RELEASE_MAP_FIELD_LENGTH = exports.MAX_RELEASE_MAP_ENTRIES = void 0;
+exports.validateReleaseMap = validateReleaseMap;
+exports.renderReleaseMapMarkdown = renderReleaseMapMarkdown;
+exports.releaseMapArchivePath = releaseMapArchivePath;
+exports.serializeReleaseMapArchive = serializeReleaseMapArchive;
+exports.loadReleaseMapFile = loadReleaseMapFile;
+exports.readArchivedReleaseMap = readArchivedReleaseMap;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const security_cjs_1 = require("./security.cjs");
+/** Maximum number of entries a single release map may carry. */
+exports.MAX_RELEASE_MAP_ENTRIES = 256;
+/** Maximum length (UTF-16 code units) of any single string field in an entry. */
+exports.MAX_RELEASE_MAP_FIELD_LENGTH = 200;
+/** Maximum size in bytes of a `--release-map` input file. */
+exports.MAX_RELEASE_MAP_FILE_BYTES = 1048576;
+/** Allowed values of an entry's `status`. */
+exports.RELEASE_MAP_STATUSES = Object.freeze(['released', 'deployed', 'unreleased']);
+/** Allowed values of an entry's `tag`. */
+exports.RELEASE_MAP_TAG_STATES = Object.freeze(['created', 'already_tagged', 'skipped', 'none']);
+const OPTIONAL_STRING_FIELDS = ['release', 'reference', 'environment'];
+const ENTRY_FIELDS = Object.freeze(['repo', ...OPTIONAL_STRING_FIELDS, 'status', 'tag']);
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function describeType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * Validate a release map (an array of entries) and return the normalized
+ * entries. Every problem is reported in one pass so a caller fixes the file
+ * once. Strict on shape: unknown fields are an error, not silently dropped.
+ */
+function validateReleaseMap(input) {
+    if (!Array.isArray(input)) {
+        return { ok: false, errors: [`release map must be an array of entries (got ${describeType(input)})`] };
+    }
+    const errors = [];
+    if (input.length > exports.MAX_RELEASE_MAP_ENTRIES) {
+        errors.push(`release map has ${input.length} entries; the maximum is ${exports.MAX_RELEASE_MAP_ENTRIES}`);
+    }
+    const map = [];
+    const seenRepos = new Set();
+    const limit = Math.min(input.length, exports.MAX_RELEASE_MAP_ENTRIES);
+    for (let i = 0; i < limit; i++) {
+        const raw = input[i];
+        const label = `entries[${i}]`;
+        if (!isPlainObject(raw)) {
+            errors.push(`${label} must be an object (got ${describeType(raw)})`);
+            continue;
+        }
+        let entryOk = true;
+        for (const key of Object.keys(raw)) {
+            if (!ENTRY_FIELDS.includes(key)) {
+                errors.push(`${label} has unknown field "${key.slice(0, exports.MAX_RELEASE_MAP_FIELD_LENGTH)}"`);
+                entryOk = false;
+            }
+        }
+        const repo = raw['repo'];
+        if (typeof repo !== 'string' || repo.trim() === '') {
+            errors.push(`${label}.repo must be a non-blank string`);
+            entryOk = false;
+        }
+        else if (repo.length > exports.MAX_RELEASE_MAP_FIELD_LENGTH) {
+            errors.push(`${label}.repo exceeds ${exports.MAX_RELEASE_MAP_FIELD_LENGTH} characters`);
+            entryOk = false;
+        }
+        else if (seenRepos.has(repo)) {
+            errors.push(`${label}.repo is a duplicate of an earlier entry`);
+            entryOk = false;
+        }
+        else {
+            seenRepos.add(repo);
+        }
+        const optional = {};
+        for (const field of OPTIONAL_STRING_FIELDS) {
+            const value = raw[field];
+            if (value === undefined || value === null) {
+                optional[field] = null;
+            }
+            else if (typeof value !== 'string') {
+                errors.push(`${label}.${field} must be a string or null (got ${describeType(value)})`);
+                entryOk = false;
+            }
+            else if (value.length > exports.MAX_RELEASE_MAP_FIELD_LENGTH) {
+                errors.push(`${label}.${field} exceeds ${exports.MAX_RELEASE_MAP_FIELD_LENGTH} characters`);
+                entryOk = false;
+            }
+            else {
+                optional[field] = value;
+            }
+        }
+        const status = raw['status'];
+        if (typeof status !== 'string' || !exports.RELEASE_MAP_STATUSES.includes(status)) {
+            errors.push(`${label}.status must be one of: ${exports.RELEASE_MAP_STATUSES.join(', ')}`);
+            entryOk = false;
+        }
+        const tag = raw['tag'];
+        if (typeof tag !== 'string' || !exports.RELEASE_MAP_TAG_STATES.includes(tag)) {
+            errors.push(`${label}.tag must be one of: ${exports.RELEASE_MAP_TAG_STATES.join(', ')}`);
+            entryOk = false;
+        }
+        if (entryOk) {
+            map.push({
+                repo: repo,
+                release: optional['release'] ?? null,
+                reference: optional['reference'] ?? null,
+                environment: optional['environment'] ?? null,
+                status: status,
+                tag: tag,
+            });
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, map };
+}
+/**
+ * Escape one value for a GFM table cell: a pipe, newline, backtick, angle
+ * bracket or other markdown control character in recorded data can neither
+ * end the cell, start a new row, nor inject structure (headings, HTML).
+ */
+function escapeCell(value) {
+    if (value === null)
+        return '-';
+    const flattened = value.replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, ' ').trim();
+    if (flattened === '')
+        return '-';
+    const escaped = flattened.replace(/[\\|`*_[\]<>&~#!]/g, (ch) => {
+        if (ch === '<')
+            return '&lt;';
+        if (ch === '>')
+            return '&gt;';
+        if (ch === '&')
+            return '&amp;';
+        return `\\${ch}`;
+    });
+    return escaped;
+}
+/**
+ * Render a validated release map as the `**Release mapping:**` markdown block
+ * appended to a MILESTONES.md entry. One table row per entry, always six cells.
+ */
+function renderReleaseMapMarkdown(map) {
+    const lines = [
+        '**Release mapping:**',
+        '',
+        '| Repository | Release | Reference | Environment | Status | Tag |',
+        '| --- | --- | --- | --- | --- | --- |',
+    ];
+    for (const entry of map) {
+        lines.push(`| ${escapeCell(entry.repo)} | ${escapeCell(entry.release)} | ${escapeCell(entry.reference)} | ${escapeCell(entry.environment)} | ${escapeCell(entry.status)} | ${escapeCell(entry.tag)} |`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** Path of the archived release map for a milestone version. */
+function releaseMapArchivePath(milestonesDir, version) {
+    return node_path_1.default.join(milestonesDir, `${version}-RELEASE-MAP.json`);
+}
+/** Serialize the archive document `{ version, entries }`. */
+function serializeReleaseMapArchive(version, map) {
+    return `${JSON.stringify({ version, entries: map }, null, 2)}\n`;
+}
+/**
+ * Read and validate a caller-supplied `--release-map` file. Refuses anything
+ * that is not a regular file (directory, FIFO, device), anything over 1 MiB and
+ * anything unreadable or unparseable, without ever opening a non-regular file.
+ */
+function loadReleaseMapFile(filePath) {
+    let stat;
+    try {
+        stat = node_fs_1.default.statSync(filePath);
+    }
+    catch (err) {
+        const code = err.code ?? 'unknown';
+        return { ok: false, errors: [`release map file cannot be read (${code}): ${node_path_1.default.basename(filePath)}`] };
+    }
+    if (!stat.isFile()) {
+        return { ok: false, errors: [`release map path is not a regular file: ${node_path_1.default.basename(filePath)}`] };
+    }
+    if (stat.size > exports.MAX_RELEASE_MAP_FILE_BYTES) {
+        return { ok: false, errors: [`release map file is ${stat.size} bytes; the maximum is ${exports.MAX_RELEASE_MAP_FILE_BYTES}`] };
+    }
+    let text;
+    try {
+        text = node_fs_1.default.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        const code = err.code ?? 'unknown';
+        return { ok: false, errors: [`release map file cannot be read (${code}): ${node_path_1.default.basename(filePath)}`] };
+    }
+    const parsed = (0, security_cjs_1.safeJsonParse)(text, { maxLength: exports.MAX_RELEASE_MAP_FILE_BYTES, label: 'release map' });
+    if (!parsed.ok) {
+        return { ok: false, errors: [parsed.error ?? 'release map: invalid JSON'] };
+    }
+    return validateReleaseMap(parsed.value);
+}
+/**
+ * Read a milestone's archived release map back by recorded value. A milestone
+ * archived without a map yields `{ ok: true, map: null }` ("no map"), never an
+ * error; a present-but-corrupt archive is reported, not guessed at.
+ */
+function readArchivedReleaseMap(milestonesDir, version) {
+    const file = releaseMapArchivePath(milestonesDir, version);
+    let text;
+    try {
+        text = node_fs_1.default.readFileSync(file, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { ok: true, map: null };
+        return { ok: false, error: `release map archive cannot be read: ${node_path_1.default.basename(file)}` };
+    }
+    const parsed = (0, security_cjs_1.safeJsonParse)(text, { maxLength: exports.MAX_RELEASE_MAP_FILE_BYTES, label: 'release map archive' });
+    if (!parsed.ok)
+        return { ok: false, error: parsed.error ?? 'release map archive: invalid JSON' };
+    const doc = parsed.value;
+    if (!isPlainObject(doc))
+        return { ok: false, error: 'release map archive: expected an object' };
+    const validated = validateReleaseMap(doc['entries']);
+    if (!validated.ok)
+        return { ok: false, error: validated.errors.join('; ') };
+    return { ok: true, map: validated.map };
+}