@opengsd/gsd-core 1.18.0 → 1.19.0

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 };
+}