agentic-workflow-manager 9.18.0 → 9.20.0

package/dist/src/core/changes/list.js

@@ -0,0 +1,408 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAG_LOOKUP_LIMIT = exports.PAGE_SIZE = exports.MAX_SUBJECT = exports.MAX_RECORDS_PER_RUN = exports.MAX_RECORDS_PER_ENTRY = exports.DEFAULT_LIMIT = void 0;
+exports.parseTreeEntries = parseTreeEntries;
+exports.listChanges = listChanges;
+const path_1 = __importDefault(require("path"));
+const git_1 = require("./git");
+const parse_1 = require("./parse");
+const range_1 = require("./range");
+const text_safety_1 = require("./text-safety");
+const list_parse_1 = require("./list-parse");
+const trailers_1 = require("./trailers");
+const types_1 = require("./types");
+const validate_shape_1 = require("./validate-shape");
+// `awm changes list` (R5): the first-parent history of the base ref, classified commit by commit. Everything here is read-only
+// and reads git history only: never the working tree, never HEAD. Nothing throws: failures come back as a value. Everything git
+// prints (commit ids, dates, subjects, paths, tag names, record contents) is untrusted: it is validated before it is used and
+// escaped before it is returned. The base is pinned to one commit id, so every later call describes the same history.
+exports.DEFAULT_LIMIT = 200;
+exports.MAX_RECORDS_PER_ENTRY = 50;
+exports.MAX_RECORDS_PER_RUN = 500;
+exports.MAX_SUBJECT = 1024;
+/** The first-parent history is read in pages of at most this many commits, so no git output approaches the 16 MiB bound. */
+exports.PAGE_SIZE = 10_000;
+const MAX_TAG_NAME = 255;
+/** R5.5: how many containing tags (earliest-dated first) are examined for an entry's release. */
+exports.TAG_LOOKUP_LIMIT = 500;
+const MAX_IDENTITY = 300;
+/** The largest instant a Date can hold, in seconds. */
+const MAX_EPOCH_SECONDS = 8.64e12;
+/**
+ * Columns of the subject that git is asked to print (`%<(N,trunc)`): enough for MAX_SUBJECT code units even when every character
+ * is two columns wide, and it bounds the output however long a subject is. Shorter subjects come back padded with spaces.
+ */
+const SUBJECT_COLUMNS = 2100;
+const SUBJECT_UNAVAILABLE = '<subject unavailable>';
+/** Columns of the END of the subject that git is asked to print: the trailing `(#<n>)` is found there, however long the subject is. */
+const TAIL_COLUMNS = 64;
+const fail = (code, message, remedy) => ({ ok: false, failure: remedy === undefined ? { code, message } : { code, message, remedy } });
+// ---- Text ----
+/** A value read from a valid record with bidi marks escaped in every string and key (the shape was validated, so it is shallow). */
+function cleanValue(value, depth = 0) {
+    if (typeof value === 'string')
+        return (0, text_safety_1.escapeBidi)(value);
+    if (depth > 8)
+        return null;
+    if (Array.isArray(value))
+        return value.map((v) => cleanValue(v, depth + 1));
+    // fromEntries defines own properties: a key named __proto__ stays a key.
+    if ((0, text_safety_1.isObj)(value))
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [(0, text_safety_1.escapeBidi)(k), cleanValue(v, depth + 1)]));
+    return value;
+}
+const cleanDiagnostics = (list) => list.map((d) => ({ ...d, message: (0, text_safety_1.escapeBidi)(d.message), ...(d.field === undefined ? {} : { field: (0, text_safety_1.escapeBidi)(d.field) }) }));
+const UNREADABLE = { ok: false };
+const RECORD_PATHSPEC = `:(top,literal)${types_1.RECORD_DIR}`;
+/** Files directly in docs/changes whose name looks like a record's date prefix (`*` does not cross `/` in a glob pathspec). Narrows R5.4's search; the exact R1.1 shape is checked per commit. */
+const RECORD_SHAPED_PATHSPEC = `:(top,glob)${types_1.RECORD_DIR}/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-*.md`;
+const SEP = '\x1f';
+const GIT_FAILED_RECORD = { path: types_1.RECORD_DIR, diagnostics: [{ code: 'git-failed', message: 'git could not list the records added by this commit' }] };
+/** Files added by a root commit under the record directory (the two-tree form of addedFilesUnder needs a parent). */
+function addedByRoot(root, sha) {
+    const out = (0, git_1.runGit)(root, ['-c', 'diff.relative=false', 'diff-tree', '--root', '-r', '--no-renames', '--ignore-submodules=none', '--diff-filter=A', '--name-only', '-z', '--no-commit-id', '--end-of-options', sha, '--', RECORD_PATHSPEC]);
+    return out === null ? null : out.split('\0').filter(Boolean);
+}
+/** `text` without the spaces `%<(N,trunc)` pads a short subject with (a subject has no meaningful trailing blanks). */
+function trimPadding(text) {
+    let end = text.length;
+    while (end > 0 && text[end - 1] === ' ')
+        end--;
+    return text.slice(0, end);
+}
+/** `<sha> SEP <field>` for the given commits in one call (`field` is a bounded git placeholder); null when git fails. */
+function readFormatted(root, shas, field) {
+    const out = (0, git_1.runGit)(root, ['log', ...git_1.LOG_SAFETY_ARGS, '--no-walk=unsorted', '-z', `--format=%H%x1f${field}`, '--end-of-options', ...shas, '--']);
+    if (out === null)
+        return null;
+    const values = new Map();
+    for (const entry of out.split('\0')) {
+        if (entry === '')
+            continue;
+        const at = entry.indexOf(SEP);
+        const sha = at < 0 ? '' : entry.slice(0, at);
+        if (!types_1.COMMIT_ID.test(sha))
+            return null;
+        values.set(sha, trimPadding(entry.slice(at + 1)));
+    }
+    return values;
+}
+/**
+ * A bounded placeholder of every commit, asked from git in one call. When the batch fails (a value that still outgrows git's
+ * output bound, for instance one made of zero-width characters, which the column bound does not count) it is halved until the
+ * commit at fault is alone; that one gets `fallback`: a subject never makes the run fail.
+ */
+function readBounded(root, shas, field, fallback) {
+    const values = new Map();
+    // A failing batch is halved until the commit that breaks it is alone: one bad commit among N costs about 2 log2(N) calls.
+    const fill = (part) => {
+        if (part.length === 0)
+            return;
+        const batch = readFormatted(root, part, field);
+        if (batch !== null && part.every((s) => batch.has(s))) {
+            for (const sha of part)
+                values.set(sha, batch.get(sha));
+        }
+        else if (part.length === 1) {
+            values.set(part[0], fallback);
+        }
+        else {
+            const middle = part.length >> 1;
+            fill(part.slice(0, middle));
+            fill(part.slice(middle));
+        }
+    };
+    fill(shas);
+    return values;
+}
+/**
+ * R5.5: the earliest-created tag that contains `sha`, annotated tags first (their creation time is the tagger date); a lightweight
+ * tag (git records only the commit date for it) is chosen only when no annotated tag contains the commit. Ties go by name ascending.
+ * Bounded: only the TAG_LOOKUP_LIMIT earliest-dated containing tags are examined (a commit contained in thousands of tags would
+ * otherwise cost an output proportional to them for every entry); the rules above apply to that list, so an annotated tag dated
+ * after that many earlier ones is not seen. Documented limit of R5.5.
+ * `{ ok: false }` when git fails.
+ */
+function earliestTag(root, sha) {
+    // For-each-ref sorts by the LAST --sort first: creation date, then name.
+    const out = (0, git_1.runGit)(root, ['for-each-ref', '--contains', sha, '--sort=refname', '--sort=creatordate', `--count=${exports.TAG_LOOKUP_LIMIT}`, '--format=%(objecttype) %(refname)', 'refs/tags/']);
+    if (out === null)
+        return UNREADABLE;
+    const rows = out.split('\n').filter((row) => row !== '');
+    if (rows.length === 0)
+        return { ok: true, value: null };
+    const pick = rows.find((row) => row.startsWith('tag ')) ?? rows[0];
+    const ref = pick.slice(pick.indexOf(' ') + 1);
+    const name = ref.slice('refs/tags/'.length);
+    // A name longer than the cap is clipped, never an error.
+    return ref.startsWith('refs/tags/') && name !== '' ? { ok: true, value: (0, list_parse_1.cleanLine)(name, MAX_TAG_NAME) } : UNREADABLE;
+}
+/** Mode, type, object id and size of exactly the given paths in the commit's tree, in ONE call. Null when git fails. */
+function readTreeEntries(root, sha, names) {
+    const out = (0, git_1.runGit)(root, ['ls-tree', '-l', '-z', '--full-tree', '--end-of-options', sha, '--', ...names]);
+    return out === null ? null : parseTreeEntries(out);
+}
+/** The pure part of readTreeEntries: parses the NUL-separated output of `git ls-tree -l -z`. Never throws. */
+function parseTreeEntries(out) {
+    const entries = new Map();
+    if (typeof out !== 'string')
+        return entries;
+    for (const line of out.split('\0')) {
+        const tab = line.indexOf('\t');
+        if (tab < 0)
+            continue;
+        const [mode, type, oid, size] = line.slice(0, tab).split(' ').filter(Boolean);
+        if (mode === undefined || type === undefined || oid === undefined || size === undefined)
+            continue;
+        const name = line.slice(tab + 1);
+        // A blob whose size git cannot tell is an object that is not in the repository: in a partial clone, with lazy fetch off,
+        // git 2.55 prints `BAD` as its size (and fails the listing in older versions). It is unreadable, not "not a regular
+        // file": a negative size marks it so that the caller reports git-failed. (`-` is what trees and gitlinks show.)
+        if (type === 'blob' && (size === 'BAD' || size === '-') && types_1.COMMIT_ID.test(oid)) {
+            entries.set(name, { mode, type, oid, size: -1 });
+            continue;
+        }
+        if (!types_1.COMMIT_ID.test(oid) || !/^\d{1,15}$/.test(size)) {
+            entries.set(name, { mode, type: 'unknown', oid, size: 0 });
+            continue;
+        }
+        entries.set(name, { mode, type, oid, size: Number(size) });
+    }
+    return entries;
+}
+const invalid = (rel, code, message) => ({ path: rel, diagnostics: [{ code, message }] });
+/** One record of a commit: size and kind are checked BEFORE the blob is read; the shape is validated without the working tree. */
+function readOne(root, rel, info) {
+    if (info === undefined)
+        return invalid(rel, 'record-invalid', 'the record is not in the commit');
+    if (info.type !== 'blob' || (info.mode !== '100644' && info.mode !== '100755'))
+        return invalid(rel, 'record-invalid', 'the record is not a regular file');
+    if (info.size < 0)
+        return invalid(rel, 'git-failed', 'git could not read the record');
+    if (info.size > types_1.MAX_RECORD_BYTES)
+        return invalid(rel, 'record-too-large', `record exceeds ${types_1.MAX_RECORD_BYTES} bytes`);
+    const bytes = (0, git_1.runGitBytes)(root, ['show', '--no-textconv', '--end-of-options', info.oid]);
+    if (bytes === null)
+        return invalid(rel, 'git-failed', 'git could not read the record');
+    // Strict, as validate reads a record (record-io.ts): a lossy decode would turn bad bytes into U+FFFD and report the record valid.
+    // `ignoreBOM: true` keeps a leading BOM, so the record then fails as invalid in both.
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        return invalid(rel, 'record-invalid', `${(0, text_safety_1.esc)(path_1.default.posix.basename(rel))} is not valid UTF-8`);
+    }
+    const shape = (0, validate_shape_1.validateRecordShape)(path_1.default.posix.basename(rel), text);
+    if (shape.record)
+        return { path: rel, ...cleanValue(shape.record) };
+    return { path: rel, diagnostics: cleanDiagnostics(shape.diagnostics) };
+}
+/**
+ * The records a commit added. A commit with more records than the per-commit bound, or than what is left of the per-run budget, is
+ * not read at all: one `too-many-records` diagnostic stands for it. The budget is spent only on records actually read.
+ */
+function readRecords(root, sha, names, budget) {
+    if (names.length > budget.entry || names.length > budget.run) {
+        return [invalid(types_1.RECORD_DIR, 'too-many-records', `${names.length} records were added; more than the read limit allows, none was read`)];
+    }
+    budget.run -= names.length;
+    const tree = readTreeEntries(root, sha, names);
+    return names.map((rel) => (tree === null ? invalid(rel, 'git-failed', 'git could not read the record') : readOne(root, rel, tree.get(rel))));
+}
+const isInvalid = (r) => 'diagnostics' in r;
+/** First-parent commits, newest first, with committer date and parents. Null when git prints something unexpected. */
+function parseScan(out) {
+    const entries = [];
+    for (const row of out.split('\0')) {
+        if (row === '')
+            continue;
+        const [sha, seconds, parentText, ...rest] = row.split(SEP);
+        if (rest.length > 0 || sha === undefined || seconds === undefined || parentText === undefined || !types_1.COMMIT_ID.test(sha))
+            return null;
+        const parents = parentText.split(' ').filter(Boolean);
+        if (!parents.every((p) => types_1.COMMIT_ID.test(p)))
+            return null;
+        // An empty, negative, non-numeric or out-of-range committer date is a date that cannot be shown to be outside any window.
+        const valid = seconds.length > 0 && seconds.length <= 13 && /^\d+$/.test(seconds) && Number(seconds) <= MAX_EPOCH_SECONDS;
+        entries.push({ sha, ms: valid ? Number(seconds) * 1000 : null, parents });
+    }
+    return entries;
+}
+/** True/false whether `sha` added a record-shaped file (R1.1) under docs/changes; null when git cannot tell. */
+function addsRecordShapedFile(root, sha, firstParent) {
+    const added = firstParent === undefined ? addedByRoot(root, sha) : (0, git_1.addedFilesUnder)(root, firstParent, sha, types_1.RECORD_DIR);
+    return added === null ? null : added.some(parse_1.isRecordPath);
+}
+/**
+ * R5.4: the oldest first-parent commit that added a record-shaped file (R1.1) under `docs/changes`; a README or any other file
+ * there does not count. The history is read in pages of `pageSize` commits that touch a file with a record-like name (each page
+ * continues from the first parent of the previous page's last commit), then the candidates are checked from the oldest up: the
+ * first that really added a record-shaped file is the adoption. `{ ok: true, value: null }` when there is none, `{ ok: false }`
+ * when git fails.
+ */
+function findAdoption(root, pinned, pageSize) {
+    let start = pinned;
+    const candidates = [];
+    for (;;) {
+        const out = (0, git_1.runGit)(root, ['log', ...git_1.LOG_SAFETY_ARGS, '--first-parent', `--max-count=${pageSize}`, '-s', '-z', '--format=%H%x1f%P', '--end-of-options', start, '--', RECORD_SHAPED_PATHSPEC]);
+        if (out === null)
+            return UNREADABLE;
+        const rows = out.split('\0').filter(Boolean).map((row) => row.split(SEP));
+        if (!rows.every(([sha, parents, ...rest]) => rest.length === 0 && types_1.COMMIT_ID.test(sha) && parents !== undefined))
+            return UNREADABLE;
+        for (const [sha, parents] of rows)
+            candidates.push({ sha, firstParent: parents.split(' ').filter(Boolean)[0] });
+        const next = rows.length === 0 ? undefined : candidates[candidates.length - 1].firstParent;
+        if (rows.length < pageSize || next === undefined || !types_1.COMMIT_ID.test(next))
+            break;
+        start = next;
+    }
+    for (let i = candidates.length - 1; i >= 0; i--) {
+        const adds = addsRecordShapedFile(root, candidates[i].sha, candidates[i].firstParent);
+        if (adds === null)
+            return UNREADABLE;
+        if (adds)
+            return { ok: true, value: candidates[i].sha };
+    }
+    return { ok: true, value: null };
+}
+/**
+ * R5.7: the first-parent commits from `pinned` down to the adopting commit, in pages of `pageSize`, each starting at the first
+ * parent of the previous page's last commit. Every commit is tested individually against the window; the first `cap` that are
+ * in it are kept and all of them are counted. The scan stops at the adoption point (the walk ends there) or at the first page
+ * with no commit in the window: dates are assumed not to decrease along the chain, so a commit dated inside the window beyond
+ * such a page is not listed. Null when git fails or prints something unexpected.
+ */
+function scanWindow(root, pinned, adoption, sinceMs, pageSize, cap) {
+    const window = { selected: [], total: 0 };
+    let start = pinned;
+    for (;;) {
+        const out = (0, git_1.runGit)(root, ['log', ...git_1.LOG_SAFETY_ARGS, '--first-parent', `--max-count=${pageSize}`, '-z', '--format=%H%x1f%ct%x1f%P', '--end-of-options', start, `^${adoption}^@`, '--']);
+        const page = out === null ? null : parseScan(out);
+        if (page === null)
+            return null;
+        const inside = page.filter((e) => e.ms === null || e.ms >= sinceMs);
+        if (inside.length === 0)
+            return window;
+        for (const entry of inside)
+            if (window.selected.length < cap)
+                window.selected.push(entry);
+        window.total += inside.length;
+        const last = page[page.length - 1];
+        const next = last.parents[0];
+        if (page.length < pageSize || last.sha === adoption || next === undefined)
+            return window;
+        start = next;
+    }
+}
+function classifyEntry(root, entry, subject, tail, budget) {
+    const [first] = entry.parents;
+    const added = first === undefined ? addedByRoot(root, entry.sha) : (0, git_1.addedFilesUnder)(root, first, entry.sha, types_1.RECORD_DIR);
+    const names = added === null ? null : added.filter(parse_1.isRecordPath);
+    let records;
+    let classification;
+    if (names === null) {
+        records = [GIT_FAILED_RECORD];
+        classification = 'invalid-record';
+    }
+    else if (names.length > 0) {
+        records = readRecords(root, entry.sha, names, budget);
+        classification = records.some(isInvalid) ? 'invalid-record' : 'recorded';
+        // An invalid-record commit lists EVERY added record: the valid ones with no diagnostics.
+        if (classification === 'invalid-record')
+            records = records.map((r) => (isInvalid(r) ? r : { path: r.path, diagnostics: [] }));
+    }
+    else {
+        records = [];
+        // The commits of a change: the commit itself, plus for a merge commit everything it brought in.
+        const revArgs = entry.parents.length > 1 ? [`${first}..${entry.sha}`] : ['-1', entry.sha];
+        classification = (0, trailers_1.hasOptOut)(root, revArgs) ? 'exempt' : 'missing';
+    }
+    const release = earliestTag(root, entry.sha);
+    if (!release.ok)
+        return null;
+    return {
+        sha: entry.sha,
+        subject: (0, list_parse_1.cleanLine)(subject, exports.MAX_SUBJECT),
+        classification,
+        merged_at: entry.ms === null ? null : new Date(entry.ms).toISOString(),
+        pr: (0, list_parse_1.parsePr)(tail),
+        release: release.value,
+        records,
+    };
+}
+const optionalCount = (v) => v === undefined || (typeof v === 'number' && Number.isSafeInteger(v) && v >= 1);
+/** The repository identity, or null when the remote is absent or unusable (a host that still carries a user part is not trusted). */
+function safeRepo(root) {
+    const identity = (0, git_1.repoIdentity)(root);
+    if (identity === null || identity.split('/')[0].includes('@'))
+        return null;
+    return (0, list_parse_1.cleanLine)(identity, MAX_IDENTITY);
+}
+function listUnsafe(root, opts) {
+    if (typeof root !== 'string' || root.length === 0 || root.includes('\0'))
+        return fail('invalid-input', 'the repository root must be a non-empty string');
+    if (!(0, text_safety_1.isObj)(opts))
+        return fail('invalid-input', 'the options must be an object');
+    const { base: explicit, since, limit, maxRecordsPerEntry, maxRecords, pageSize } = opts;
+    if (!(since instanceof Date) || Number.isNaN(since.getTime()))
+        return fail('invalid-input', 'the window start must be a valid date');
+    if (!optionalCount(limit) || !optionalCount(maxRecordsPerEntry) || !optionalCount(maxRecords) || !optionalCount(pageSize))
+        return fail('invalid-input', 'limits must be positive integers');
+    // R3.1/R3.2/R3.5, as `change new`; then the base is pinned to one commit id: history cannot move under the run.
+    const resolved = (0, range_1.resolveBaseRef)(root, explicit);
+    if (!resolved.ok)
+        return { ok: false, failure: resolved.failure };
+    const { base, sha: pinned } = resolved;
+    // R5.1: at a shallow boundary a commit looks like a root commit, so a shallow history cannot be classified.
+    const shallow = (0, git_1.runGit)(root, ['rev-parse', '--is-shallow-repository'])?.trim();
+    if (shallow === 'true')
+        return fail('shallow-history', 'this repository is a shallow clone; its oldest commits cannot be told from root commits', 'git fetch --unshallow');
+    if (shallow !== 'false')
+        return fail('git-failed', 'git could not tell whether the repository is shallow');
+    const page = Math.min(pageSize ?? exports.PAGE_SIZE, exports.PAGE_SIZE);
+    // R5.4: the first commit, in first-parent order, that touched docs/changes.
+    const adopting = findAdoption(root, pinned, page);
+    if (!adopting.ok)
+        return fail('git-failed', 'git could not read the history');
+    const adoption = adopting.value;
+    const result = { repo: safeRepo(root), base: (0, list_parse_1.cleanLine)(base, MAX_TAG_NAME), since: since.toISOString(), adopted: false, truncated: false, omitted: 0, changes: [] };
+    if (adoption === null)
+        return { ok: true, result };
+    result.adopted = true;
+    const cap = Math.min(limit ?? exports.DEFAULT_LIMIT, exports.DEFAULT_LIMIT);
+    const window = scanWindow(root, pinned, adoption, since.getTime(), page, cap);
+    if (window === null)
+        return fail('git-failed', 'git could not read the history');
+    const selected = window.selected;
+    result.truncated = window.total > selected.length;
+    result.omitted = window.total - selected.length;
+    const shas = selected.map((e) => e.sha);
+    const subjects = readBounded(root, shas, `%<(${SUBJECT_COLUMNS},trunc)%s`, SUBJECT_UNAVAILABLE);
+    const tails = readBounded(root, shas, `%<(${TAIL_COLUMNS},ltrunc)%s`, '');
+    const run = maxRecords ?? exports.MAX_RECORDS_PER_RUN;
+    const budget = { entry: maxRecordsPerEntry ?? exports.MAX_RECORDS_PER_ENTRY, run };
+    for (const entry of selected) {
+        const change = classifyEntry(root, entry, subjects.get(entry.sha), tails.get(entry.sha), budget);
+        if (change === null)
+            return fail('git-failed', `git could not tell which tags contain ${entry.sha.slice(0, 12)}`);
+        result.changes.push(change);
+    }
+    return { ok: true, result };
+}
+/**
+ * R5.1-R5.5, R5.7: the first-parent history of the base ref, classified. `base` is resolved as in R3.1 (an unsafe one is
+ * `invalid-input`, one that does not resolve is `base-unresolved`). Read-only; never throws.
+ */
+function listChanges(root, opts) {
+    try {
+        return listUnsafe(root, opts);
+    }
+    catch (error) {
+        return fail('internal-error', `unexpected failure (${(0, text_safety_1.esc)(error instanceof Error ? error.name : 'unknown')})`);
+    }
+}

package/dist/src/core/changes/parse.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRecordPath = exports.RECORD_FILE_RE = void 0;
+exports.isValidSlug = isValidSlug;
+exports.isValidRecordFileName = isValidRecordFileName;
+exports.splitRecord = splitRecord;
+exports.loadFrontmatter = loadFrontmatter;
+const path_1 = __importDefault(require("path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const text_safety_1 = require("./text-safety");
+const types_1 = require("./types");
+exports.RECORD_FILE_RE = /^(\d{4})-(\d{2})-(\d{2})-([a-z0-9]+(?:-[a-z0-9]+)*)\.md$/;
+/** True for a repo-relative, `/`-separated path directly inside `docs/changes/` whose file name looks like a record (`YYYY-MM-DD-<slug>.md`). */
+const isRecordPath = (rel) => typeof rel === 'string' && path_1.default.posix.dirname(rel) === types_1.RECORD_DIR && exports.RECORD_FILE_RE.test(path_1.default.posix.basename(rel));
+exports.isRecordPath = isRecordPath;
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function isValidSlug(slug) {
+    return typeof slug === 'string' && slug.length > 0 && slug.length <= 64 && SLUG_RE.test(slug);
+}
+function isValidRecordFileName(name) {
+    if (typeof name !== 'string')
+        return false;
+    const m = exports.RECORD_FILE_RE.exec(name);
+    if (!m || !isValidSlug(m[4]))
+        return false;
+    const iso = `${m[1]}-${m[2]}-${m[3]}`;
+    const d = new Date(`${iso}T00:00:00Z`);
+    return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === iso;
+}
+const INPUT_INVALID = { code: 'input-invalid', message: 'input must be a string' };
+/** Normalizes CRLF and splits a leading `---` frontmatter block from the body. */
+function splitRecord(raw) {
+    if (typeof raw !== 'string')
+        return { ok: false, diagnostic: INPUT_INVALID };
+    const text = raw.replace(/\r\n/g, '\n');
+    if (!text.startsWith('---\n'))
+        return { ok: false, diagnostic: { code: 'frontmatter-missing', message: 'record must start with a --- frontmatter block' } };
+    const end = text.indexOf('\n---\n', 3);
+    if (end < 0)
+        return { ok: false, diagnostic: { code: 'frontmatter-missing', message: 'frontmatter block is not closed with ---' } };
+    return { ok: true, frontmatterText: text.slice(4, end), body: text.slice(end + 5) };
+}
+/**
+ * CORE_SCHEMA: no custom tags, no implicit timestamps (dates stay strings).
+ * Every anchor is rejected (scalar, collection, used or unused); an alias cannot exist without one.
+ * The parse listener sees the anchor of each node on `close`, so quoted `&a` / `*a` text is unaffected.
+ */
+function loadFrontmatter(text) {
+    if (typeof text !== 'string')
+        return { ok: false, diagnostic: INPUT_INVALID };
+    let value;
+    let anchored = false;
+    try {
+        value = js_yaml_1.default.load(text, {
+            schema: js_yaml_1.default.CORE_SCHEMA,
+            json: false,
+            listener: (event, state) => {
+                if (event === 'close' && state.anchor !== null)
+                    anchored = true;
+            },
+        });
+    }
+    catch (error) {
+        return { ok: false, diagnostic: { code: 'yaml-invalid', message: (0, text_safety_1.clipMessage)(`frontmatter is not valid YAML: ${(0, text_safety_1.escapeText)(error.message.split('\n')[0])}`) } };
+    }
+    if (anchored)
+        return { ok: false, diagnostic: { code: 'yaml-alias', message: 'YAML anchors/aliases are not allowed' } };
+    return { ok: true, value };
+}

package/dist/src/core/changes/range.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HEAD_MOVED = void 0;
+exports.resolveBaseRef = resolveBaseRef;
+exports.resolveRange = resolveRange;
+exports.headMovedFailure = headMovedFailure;
+exports.recordDirProblem = recordDirProblem;
+const git_1 = require("./git");
+const text_safety_1 = require("./text-safety");
+const types_1 = require("./types");
+const REMEDY_BASE = 'pass --base <ref>';
+exports.HEAD_MOVED = { code: 'head-moved', message: 'HEAD moved during derivation' };
+const KINDS = ['ok', 'absent', 'unsafe', 'error'];
+const failure = (code, message, remedy) => ({ ok: false, failure: remedy === undefined ? { code, message } : { code, message, remedy } });
+/**
+ * R3.1/R3.2/R3.5: the base ref: `explicitBase` (checked with `isSafeRef` before git sees it: `invalid-input`), else origin/HEAD,
+ * main, master; `base-unresolved` when none resolves. The one place that decides it, for `change new`, `change validate` and `changes list`.
+ */
+function resolveBaseRef(root, explicitBase) {
+    if (explicitBase !== undefined && !(0, git_1.isSafeRef)(explicitBase))
+        return failure('invalid-input', `--base "${(0, text_safety_1.esc)(explicitBase)}" is not a safe git ref`);
+    const resolved = (0, git_1.resolveBaseCommit)(root, explicitBase);
+    return resolved === null ? failure('base-unresolved', 'could not resolve a base branch', REMEDY_BASE) : { ok: true, ...resolved };
+}
+/**
+ * R3.1/R3.2/R3.5: pins HEAD, then resolves the base (explicit `--base`, else origin/HEAD, main, master) and its merge base with HEAD.
+ * An explicit base is checked with `isSafeRef` before git sees it.
+ */
+function resolveRange(root, explicitBase) {
+    const head = (0, git_1.headSha)(root);
+    if (head === null)
+        return failure('git-failed', 'git could not read HEAD');
+    const resolved = resolveBaseRef(root, explicitBase);
+    if (!resolved.ok)
+        return resolved;
+    const mergeBaseSha = (0, git_1.mergeBase)(root, resolved.base);
+    if (mergeBaseSha === null)
+        return failure('base-unresolved', `no merge base between "${(0, text_safety_1.esc)(resolved.base)}" and HEAD`, REMEDY_BASE);
+    return { ok: true, head, mergeBase: mergeBaseSha };
+}
+/** `HEAD_MOVED` when HEAD is no longer `head` (or cannot be read), else null: a verdict about a moving target is never given. */
+function headMovedFailure(root, head) {
+    return (0, git_1.headSha)(root) === head ? null : exports.HEAD_MOVED;
+}
+function recordDirProblem(dir, purpose) {
+    if (!(0, text_safety_1.isObj)(dir) || !KINDS.includes(dir.kind))
+        return { code: 'invalid-input', message: 'the record directory state is not valid' };
+    if (dir.kind === 'unsafe')
+        return { code: 'unsafe-path', message: `${types_1.RECORD_DIR} or its parent is a symlink or not a directory; refusing to ${purpose === 'read' ? 'read' : 'write'}` };
+    if (dir.kind === 'error' || (dir.kind === 'absent' && purpose === 'create'))
+        return { code: 'io-failed', message: `could not ${purpose === 'create' ? 'create' : 'inspect'} ${types_1.RECORD_DIR}` };
+    return null;
+}