@opengsd/gsd-core 1.15.0 → 1.16.0

package/gsd-core/bin/lib/drift.cjs

@@ -4,17 +4,31 @@
  * Detects structural drift between a committed codebase and the
  * `.planning/codebase/STRUCTURE.md` map produced by `gsd-codebase-mapper`.
  *
- * Four categories of drift element:
+ * Six categories of drift element:
  *   - new_dir    → a newly-added file whose directory prefix does not appear
- *                  in STRUCTURE.md
+ *                  in any generated document
  *   - barrel     → a newly-added barrel export at
  *                  (packages|apps)/<name>/src/index.(ts|tsx|js|mjs|cjs)
  *   - migration  → a newly-added migration file under one of the recognized
  *                  migration directories (supabase, prisma, drizzle, src/migrations, …)
  *   - route      → a newly-added route module under a `routes/` or `api/` dir
+ *   - modified   → a modified file whose directory prefix IS mapped
+ *   - deleted    → a deleted file whose directory prefix IS mapped
+ *
+ * Inverse-territory rule (#4886, #5134): an addition is drift OUTSIDE mapped
+ * territory (the map cannot describe what did not exist); a modification or
+ * deletion is drift INSIDE mapped territory (the map describes it and it
+ * changed). A rename is a deletion of the old path plus an addition of the new
+ * path; a copy is an addition of the new path. Mapped territory is any
+ * directory prefix named in ANY provided generated document.
  *
  * Each file is counted at most once; when a file matches multiple categories
- * the most specific category wins (migration > route > barrel > new_dir).
+ * the most specific category wins
+ * (deleted > modified > migration > route > barrel > new_dir).
+ *
+ * Every path that leaves this module (`affectedPaths`, the `--paths` argument,
+ * message bullets) passes `sanitizePaths` (#4923); dropped paths are reported
+ * as data in `withheldPaths`, never interpolated into the message.
  *
  * Design decisions (see PR for full rubber-duck):
  *   - The library is pure. It takes parsed git diff output and returns a
@@ -38,11 +52,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 // ─── Constants ───────────────────────────────────────────────────────────────
-const DRIFT_CATEGORIES = Object.freeze(['new_dir', 'barrel', 'migration', 'route']);
+const DRIFT_CATEGORIES = Object.freeze(['new_dir', 'barrel', 'migration', 'route', 'modified', 'deleted']);
 // Category priority when a single file matches multiple rules.
 // Higher index = more specific = wins.
-const CATEGORY_PRIORITY = { new_dir: 0, barrel: 1, route: 2, migration: 3 };
+const CATEGORY_PRIORITY = {
+    new_dir: 0, barrel: 1, route: 2, migration: 3, modified: 4, deleted: 5,
+};
 const BARREL_RE = /^(packages|apps)\/[^/]+\/src\/index\.(ts|tsx|js|mjs|cjs)$/;
 const MIGRATION_RES = [
     /^supabase\/migrations\/.+\.sql$/,
@@ -78,30 +95,99 @@ function classifyFile(file) {
         return 'barrel';
     return null;
 }
+// Characters that continue a path component: a prefix occurrence directly
+// preceded by one of `BEFORE_CONT` or followed by one of `AFTER_CONT` is a
+// fragment of a longer word or name, not the prefix itself.
+const BEFORE_CONT_RE = /[A-Za-z0-9_.-]/;
+const AFTER_CONT_RE = /[A-Za-z0-9_-]/;
 /**
- * True iff any prefix of `file` (dir1, dir1/dir2, …) appears as a substring
- * of `structureMd`. Used to decide whether a file is in "mapped territory".
+ * True iff `needle` occurs in `corpus` at path-component boundaries: the
+ * character before it (or the start) is not a path-component character, and
+ * the character after it (or the end) is not one either. `.` may follow (a
+ * sentence end) but may not precede (`x.src`). Linear scan, no regex built
+ * from `needle`.
+ */
+function occursAtBoundary(corpus, needle) {
+    if (!needle)
+        return false;
+    let from = 0;
+    for (;;) {
+        const at = corpus.indexOf(needle, from);
+        if (at === -1)
+            return false;
+        const end = at + needle.length;
+        const beforeOk = at === 0 || !BEFORE_CONT_RE.test(corpus[at - 1]);
+        const afterOk = end >= corpus.length || !AFTER_CONT_RE.test(corpus[end]);
+        if (beforeOk && afterOk)
+            return true;
+        from = at + 1;
+    }
+}
+/**
+ * True iff any prefix of `file` (dir1, dir1/dir2, …) appears in `corpus` (the
+ * provided generated documents joined) at path-component boundaries. Used to
+ * decide whether a file is in "mapped territory".
  *
- * Matching is deliberately substring-based — STRUCTURE.md is free-form
- * markdown, not a structured manifest. If the map mentions `src/lib/` the
- * check `structureMd.includes('src/lib')` holds.
+ * The documents are free-form markdown, not a structured manifest, so the
+ * match is textual — but it is component-aware: `src/lib/` and `` `src/lib` ``
+ * map `src/lib`; the word `library` does not map `lib` and `capital` does not
+ * map `api`. The `name/` and `` `name` `` forms of the top-level directory
+ * fall out of the same boundary rule.
  */
-function isPathMapped(file, structureMd) {
+function isPathMapped(file, corpus) {
     const norm = (0, shell_command_projection_cjs_1.posixNormalize)(file);
     const parts = norm.split('/');
-    // Check prefixes from longest to shortest; any hit means "mapped".
+    // A path with an empty component (`/x`, `a//b`) has no mappable prefix at
+    // that depth; never search for the empty string.
     for (let i = parts.length - 1; i >= 1; i--) {
-        const prefix = parts.slice(0, i).join('/');
-        if (structureMd.includes(prefix))
+        const prefixParts = parts.slice(0, i);
+        if (prefixParts.some((part) => part === ''))
+            continue;
+        if (occursAtBoundary(corpus, prefixParts.join('/')))
+            return true;
+    }
+    // A single-component path (a root-level file) has no directory prefix; the
+    // documented forms name the component itself as a directory.
+    if (parts.length === 1 && parts[0] !== '') {
+        if (occursAtBoundary(corpus, parts[0] + '/'))
+            return true;
+        if (corpus.includes('`' + parts[0] + '`'))
             return true;
     }
-    // Finally, if even the top-level dir is mentioned, count as mapped.
-    if (parts.length > 0 && structureMd.includes(parts[0] + '/'))
-        return true;
-    if (parts.length > 0 && structureMd.includes('`' + parts[0] + '`'))
-        return true;
     return false;
 }
+// Characters that would let a path rewrite a terminal or the reader's view of
+// it: C0 controls, DEL, C1 controls, bidi controls, zero-width characters and
+// the line/paragraph separators.
+const DISPLAY_UNSAFE_RE = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028\u2029\u202a-\u202e\u2060\u2066-\u2069\ufeff]/;
+const DISPLAY_MAX_UNITS = 200;
+/**
+ * Render an attacker-controlled path for a display surface. Display-unsafe
+ * characters become `\uXXXX` (lowercase hex); every other character —
+ * including ordinary non-ASCII — is left alone. A result longer than 200
+ * UTF-16 code units is cut on a code-point (and escape) boundary so that the
+ * result, with its trailing `…`, is exactly 200 code units or fewer.
+ */
+function displaySafePath(p) {
+    const pieces = [];
+    let total = 0;
+    for (const ch of String(p)) {
+        const piece = DISPLAY_UNSAFE_RE.test(ch)
+            ? '\\u' + ch.codePointAt(0).toString(16).padStart(4, '0')
+            : ch;
+        pieces.push(piece);
+        total += piece.length;
+    }
+    if (total <= DISPLAY_MAX_UNITS)
+        return pieces.join('');
+    let out = '';
+    for (const piece of pieces) {
+        if (out.length + piece.length > DISPLAY_MAX_UNITS - 1)
+            break;
+        out += piece;
+    }
+    return out + '…';
+}
 // ─── Main detection ──────────────────────────────────────────────────────────
 /**
  * Detect codebase drift.
@@ -112,40 +198,62 @@ function detectDrift(input) {
             return skipped('invalid-input');
         }
         const inp = input;
-        const { addedFiles, modifiedFiles, deletedFiles, structureMd, } = inp;
+        const { addedFiles, modifiedFiles, deletedFiles, documents, } = inp;
         const threshold = Number.isInteger(inp.threshold) && inp.threshold >= 1
             ? inp.threshold
             : 3;
         const action = inp.action === 'auto-remap' ? 'auto-remap' : 'warn';
+        // STRUCTURE.md is the one required document; the other six only widen the
+        // mapped territory and are ignored when absent or not text.
+        const docs = documents !== null && typeof documents === 'object'
+            ? documents
+            : {};
+        const structureMd = docs['STRUCTURE.md'];
         if (structureMd === null || structureMd === undefined) {
             return skipped('missing-structure-md');
         }
         if (typeof structureMd !== 'string') {
             return skipped('invalid-structure-md');
         }
+        const corpus = Object.values(docs)
+            .filter((doc) => typeof doc === 'string')
+            .join('\n');
         const added = Array.isArray(addedFiles) ? addedFiles.filter((x) => typeof x === 'string') : [];
         const modified = Array.isArray(modifiedFiles) ? modifiedFiles : [];
         const deleted = Array.isArray(deletedFiles) ? deletedFiles : [];
         // Build elements. One element per file, highest-priority category wins.
         const elements = [];
         const seen = new Map();
+        const count = (file, category) => {
+            // Dedup: if we've already counted this path at higher-or-equal priority, skip
+            const prior = seen.get(file);
+            if (prior && CATEGORY_PRIORITY[prior] >= CATEGORY_PRIORITY[category])
+                return;
+            seen.set(file, category);
+        };
         for (const rawFile of added) {
             const file = (0, shell_command_projection_cjs_1.posixNormalize)(rawFile);
             const specific = classifyFile(file);
             let category = specific;
             if (!category) {
-                if (!isPathMapped(file, structureMd)) {
+                if (!isPathMapped(file, corpus)) {
                     category = 'new_dir';
                 }
                 else {
                     continue; // mapped, known, ordinary file — not drift
                 }
             }
-            // Dedup: if we've already counted this path at higher-or-equal priority, skip
-            const prior = seen.get(file);
-            if (prior && CATEGORY_PRIORITY[prior] >= CATEGORY_PRIORITY[category])
-                continue;
-            seen.set(file, category);
+            count(file, category);
+        }
+        // Inverse territory: an edit is drift only where the map describes the file.
+        for (const [rawFiles, category] of [[modified, 'modified'], [deleted, 'deleted']]) {
+            for (const rawFile of rawFiles) {
+                if (typeof rawFile !== 'string')
+                    continue;
+                const file = (0, shell_command_projection_cjs_1.posixNormalize)(rawFile);
+                if (file && isPathMapped(file, corpus))
+                    count(file, category);
+            }
         }
         for (const [file, category] of seen.entries()) {
             elements.push({ category, path: file });
@@ -158,14 +266,20 @@ function detectDrift(input) {
         let directive = 'none';
         let spawnMapper = false;
         let affectedPaths = [];
+        let withheldPaths = [];
         let message = '';
         if (actionRequired) {
             directive = action;
-            affectedPaths = chooseAffectedPaths(elements.map((e) => e.path));
-            if (action === 'auto-remap') {
-                spawnMapper = true;
-            }
-            message = buildMessage(elements, affectedPaths, action, inp.runtime);
+            // The one egress seam (#4923): `affectedPaths` is the only path list
+            // that reaches the result, the auto-remap line and `--paths`.
+            const elementPaths = elements.map((e) => e.path);
+            const chosen = chooseAffectedPaths(elementPaths);
+            affectedPaths = sanitizePaths(chosen);
+            const kept = new Set([...sanitizePaths(elementPaths), ...affectedPaths]);
+            withheldPaths = [...new Set([...elementPaths, ...chosen].filter((p) => !kept.has(p)))].sort();
+            // An empty `--paths` would remap the whole repo (#3418).
+            spawnMapper = action === 'auto-remap' && affectedPaths.length > 0;
+            message = buildMessage(elements, affectedPaths, withheldPaths.length, action, inp.runtime);
         }
         return {
             skipped: false,
@@ -174,6 +288,7 @@ function detectDrift(input) {
             directive,
             spawnMapper,
             affectedPaths,
+            withheldPaths,
             threshold,
             action,
             message,
@@ -199,12 +314,16 @@ function skipped(reason) {
         directive: 'none',
         spawnMapper: false,
         affectedPaths: [],
+        withheldPaths: [],
         message: '',
     };
 }
-function buildMessage(elements, affectedPaths, action, runtime) {
+function buildMessage(elements, affectedPaths, withheldCount, action, runtime) {
     const byCat = {};
+    const listable = new Set(sanitizePaths(elements.map((e) => e.path)));
     for (const e of elements) {
+        if (!listable.has(e.path))
+            continue;
         if (!byCat[e.category])
             byCat[e.category] = [];
         byCat[e.category].push(e.path);
@@ -218,8 +337,10 @@ function buildMessage(elements, affectedPaths, action, runtime) {
         barrel: 'New barrel exports',
         migration: 'New migrations',
         route: 'New route modules',
+        modified: 'Modified files in mapped directories',
+        deleted: 'Deleted files in mapped directories',
     };
-    for (const cat of ['new_dir', 'barrel', 'migration', 'route']) {
+    for (const cat of DRIFT_CATEGORIES) {
         if (byCat[cat]) {
             lines.push(`${labels[cat]}:`);
             for (const p of byCat[cat])
@@ -227,12 +348,18 @@ function buildMessage(elements, affectedPaths, action, runtime) {
         }
     }
     lines.push('');
-    if (action === 'auto-remap') {
+    // Dropped paths are counted, never named: the names are data in `withheldPaths`.
+    if (withheldCount > 0) {
+        lines.push(`${withheldCount} path(s) withheld: not passed to the mapper or listed (absolute, traversal, whitespace, non-ASCII or shell-metacharacter characters)`);
+    }
+    // Nothing safe to scope a refresh to (empty `affectedPaths`): an empty
+    // `--paths` would remap the whole repo (#3418), so no command line is emitted.
+    if (affectedPaths.length > 0 && action === 'auto-remap') {
         lines.push(`Auto-remap scheduled for paths: ${affectedPaths.join(', ')}`);
     }
-    else {
+    else if (affectedPaths.length > 0) {
         // drift.cts is a pure library — it must never read env/config. The
-        // caller (verify.cmdVerifyCodebaseDrift) resolves the runtime once and
+        // caller (gate-codebase-drift.cts) resolves the runtime once and
         // passes it in via input.runtime so emitted commands match the project
         // the caller is targeting, not the current process directory.
         const mapCmd = (0, runtime_slash_cjs_1.formatGsdSlash)('map-codebase', runtime || 'claude');
@@ -256,6 +383,8 @@ function chooseAffectedPaths(paths) {
         if (parts.length === 0)
             continue;
         const top = parts[0];
+        if (!top)
+            continue; // an empty first component (`/x`) names no directory
         if ((top === 'apps' || top === 'packages') && parts.length >= 2) {
             out.add(`${top}/${parts[1]}`);
         }
@@ -281,26 +410,31 @@ function sanitizePaths(paths) {
             continue;
         if (!SAFE_PATH_RE.test(p))
             continue;
+        // A `.` component would make `--paths .` (the whole repo) producible (#3418).
+        if (p.split('/').some((component) => component === '.'))
+            continue;
         out.push(p);
     }
     return out;
 }
-// ─── Frontmatter helpers ─────────────────────────────────────────────────────
-const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+/**
+ * The block is the one the one fence owner finds (`locateFrontmatterFence`); `body` is
+ * everything after the closing fence line and its line ending.
+ */
 function parseFrontmatter(content) {
     if (typeof content !== 'string')
         return { data: {}, body: '' };
-    const m = content.match(FRONTMATTER_RE);
-    if (!m)
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content);
+    if (!fence?.closed)
         return { data: {}, body: content };
     const data = {};
-    for (const line of m[1].split(/\r?\n/)) {
+    for (const line of content.slice(fence.openEnd, fence.bodyEnd).split(/\r?\n/)) {
         const kv = line.match(/^([A-Za-z0-9_][A-Za-z0-9_-]*):\s*(.*)$/);
         if (!kv)
             continue;
         data[kv[1]] = kv[2];
     }
-    return { data, body: content.slice(m[0].length) };
+    return { data, body: content.slice(fence.closingFenceEnd).replace(/^\r?\n/, '') };
 }
 function serializeFrontmatter(data, body) {
     const keys = Object.keys(data);
@@ -357,6 +491,7 @@ module.exports = {
     detectDrift,
     chooseAffectedPaths,
     sanitizePaths,
+    displaySafePath,
     readMappedCommit,
     writeMappedCommit,
     // Exposed for the CLI layer to reuse the same parser.

package/gsd-core/bin/lib/frontmatter-fence.cjs

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * frontmatter-fence.cts — the one owner of "where does a document's frontmatter block start
+ * and stop" (ADR-5057 one-owner rule; found while implementing #5105).
+ *
+ * Source in src/frontmatter-fence.cts, compiled to gsd-core/bin/lib/frontmatter-fence.cjs
+ * (gitignored), per the repo's ADR-457 build-at-publish convention.
+ *
+ * Before this module the answer was re-derived some thirty times across `src/` — regexes such
+ * as `/^---\r?\n([\s\S]*?)\r?\n---/`, `indexOf('\n---', 4)` scans, `lines[0].trim() === '---'`
+ * checks — and the copies disagreed on a BOM, CRLF, an adjacent empty block, `----`, `--- x`,
+ * a `---` inside a value and leading whitespace. Every frontmatter reader and writer in `src/`
+ * (planning documents, agent/skill/command files, the installer's converters and injectors),
+ * in the runtime hooks, and in the two hand-written entry points that load `bin/lib`
+ * (`bin/install.js`, `gsd-core/bin/gsd-tools.cjs`) now reads the fence from
+ * `locateFrontmatterFence` — directly for offsets, or through `frontmatterRegion`/
+ * `frontmatterBlock`/`extractFrontmatter`/`stripFrontmatter` (`frontmatter.cts`) for content.
+ * `scripts/lint-frontmatter-fence-drift.cjs` (run by `lint:ci`) fails on a new hand-rolled
+ * fence in any of them.
+ *
+ * A "genuine leaf" module (CONTEXT.md's term): zero I/O, zero imports, so both
+ * `frontmatter.cts` and `shell-command-projection.cts` — which import each other's side of a
+ * cycle — can depend on it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.locateFrontmatterFence = locateFrontmatterFence;
+/** A closing fence is a WHOLE line: three dashes, then only spaces or tabs. */
+const CLOSING_FENCE_LINE = /^---[ \t]*$/;
+/**
+ * The lenient closer: a WHOLE line of four or more dashes, then only spaces or tabs. It closes
+ * a block only when no exact closer follows the opening fence — the pre-existing lenient parse
+ * of a `----`-closed block (#1882, `tests/unusable-input.test.cjs`), kept so such a document
+ * still reads its keys instead of reading as unterminated.
+ */
+const LENIENT_CLOSING_FENCE_LINE = /^-{4,}[ \t]*$/;
+function locateFrontmatterFence(text, options = {}) {
+    if (typeof text !== 'string') {
+        throw new TypeError(`locateFrontmatterFence: expected a string, got ${typeof text}`);
+    }
+    const bom = text.charCodeAt(0) === 0xfeff ? String.fromCharCode(0xfeff) : '';
+    const openingEolAt = (at) => {
+        if (text.startsWith('---\r\n', at))
+            return '\r\n';
+        if (text.startsWith('---\n', at))
+            return '\n';
+        return null;
+    };
+    let start = bom.length;
+    let found = openingEolAt(start);
+    if (found === null && options.allowPreamble === true) {
+        for (let newline = text.indexOf('\n', start); newline !== -1; newline = text.indexOf('\n', newline + 1)) {
+            found = openingEolAt(newline + 1);
+            if (found !== null) {
+                start = newline + 1;
+                break;
+            }
+        }
+    }
+    if (found === null)
+        return null;
+    const eol = found;
+    const openEnd = start + 3 + eol.length;
+    const closedAt = (lineStart, lineEnd) => {
+        let bodyEnd = openEnd;
+        if (lineStart > openEnd) {
+            // Back over the line ending that ends the last content line.
+            bodyEnd = lineStart - 1;
+            if (bodyEnd > openEnd && text[bodyEnd - 1] === '\r')
+                bodyEnd -= 1;
+        }
+        return { bom, eol, openEnd, closed: true, closingStart: lineStart, closingFenceEnd: lineEnd, bodyEnd };
+    };
+    let lenient = null;
+    let lineStart = openEnd;
+    while (lineStart <= text.length) {
+        const newline = text.indexOf('\n', lineStart);
+        const lineEnd = newline === -1 ? text.length : newline > lineStart && text[newline - 1] === '\r' ? newline - 1 : newline;
+        const line = text.slice(lineStart, lineEnd);
+        if (CLOSING_FENCE_LINE.test(line))
+            return closedAt(lineStart, lineEnd);
+        if (lenient === null && LENIENT_CLOSING_FENCE_LINE.test(line))
+            lenient = [lineStart, lineEnd];
+        if (newline === -1)
+            break;
+        lineStart = newline + 1;
+    }
+    if (lenient !== null)
+        return closedAt(lenient[0], lenient[1]);
+    return { bom, eol, openEnd, closed: false, closingStart: -1, closingFenceEnd: -1, bodyEnd: text.length };
+}