agentic-workflow-manager 9.18.0 → 9.20.0

package/dist/src/commands/sensors/read-only-observation.js

@@ -0,0 +1,305 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EXCLUSION_NAMES = exports.READ_ONLY_MAX_BYTES = exports.READ_ONLY_MAX_ENTRIES = void 0;
+exports.loadAdmissionConfig = loadAdmissionConfig;
+exports.createExclusionPolicy = createExclusionPolicy;
+exports.gitVerifier = gitVerifier;
+exports.filesystemSnapshot = filesystemSnapshot;
+exports.snapshotUnavailableRemedy = snapshotUnavailableRemedy;
+exports.admissionConfigRemedy = admissionConfigRemedy;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const child_process_1 = require("child_process");
+/**
+ * Admission's read-only observation (issue #215). `runSensors({ readOnly })` hashes
+ * the project tree before and after the sensors run; any difference means the
+ * evidence is not read-only. Generated output (node_modules, .next, …) can push that
+ * walk past its limits, so a directory that git ignores and that holds no tracked
+ * file may be skipped. Source files, `.gitignore`, and `.awm/` stay observed.
+ */
+exports.READ_ONLY_MAX_ENTRIES = 250_000;
+exports.READ_ONLY_MAX_BYTES = 1024 * 1024 * 1024;
+exports.DEFAULT_EXCLUSION_NAMES = Object.freeze(['node_modules', '.next', '.turbo', 'dist', 'build', 'coverage', '.venv', 'target']);
+const ADMISSION_CONFIG_LABEL = '.awm/admission.json';
+const GIT_TIMEOUT_MS = 5_000;
+const GIT_MAX_OUTPUT_BYTES = 64 * 1024;
+const MAX_FIELD_LABEL = 64;
+const MAX_CONFIG_BYTES = 65_536;
+// Control characters (C0, DEL, C1), bidi controls (marks, embeddings, isolates) and line/paragraph separators.
+const UNSAFE_LABEL_CHARS = /[\p{Cc}\p{Bidi_Control}\u2028\u2029]/gu;
+// Variables that relocate the repository, index or object store: inherited ones would
+// make git answer for a different repository than `projectRoot` (fail-open).
+const GIT_LOCATION_VARIABLES = new Set([
+    'GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_COMMON_DIR', 'GIT_NAMESPACE', 'GIT_PREFIX',
+]);
+const RESERVED_NAMES = new Set(['.git', '.awm']);
+const DEFAULT_LIMITS = { maxEntries: exports.READ_ONLY_MAX_ENTRIES, maxBytes: exports.READ_ONLY_MAX_BYTES };
+function requireRoot(value, label) {
+    if (typeof value !== 'string' || value.trim() === '')
+        throw new Error(`${label} must be a non-empty string`);
+    return value;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Unknown keys come from the project file: bound them and neutralize control characters. */
+function fieldLabel(key) {
+    const clean = key.replace(UNSAFE_LABEL_CHARS, '?');
+    return clean.length <= MAX_FIELD_LABEL ? clean : `${clean.slice(0, MAX_FIELD_LABEL - 1)}…`;
+}
+function defaultRules() {
+    return exports.DEFAULT_EXCLUSION_NAMES.map(name => ({ kind: 'name', name }));
+}
+/** Exact, case-insensitive match: `my.awm` and `.gitignore-dir` are not reserved. */
+function isReservedSegment(segment) {
+    return RESERVED_NAMES.has(segment.toLowerCase());
+}
+function entryProblem(entry) {
+    if (entry === '')
+        return 'must not be empty';
+    if (/[\0\r\n\\*?[]/.test(entry))
+        return 'must not contain a backslash, wildcard, NUL or line break';
+    if (entry.startsWith('/') || /^[A-Za-z]:/.test(entry))
+        return 'must be relative to the project root';
+    if (entry.endsWith('/'))
+        return 'must not end with "/"';
+    const segments = entry.split('/');
+    if (segments.some(segment => segment === '' || segment === '.' || segment === '..'))
+        return 'must not contain an empty, "." or ".." segment';
+    if (segments.some(isReservedSegment))
+        return 'must not exclude .git or .awm';
+    return null;
+}
+/** Strict parser for the optional `.awm/admission.json`; absent means AWM defaults. */
+function loadAdmissionConfig(projectRoot) {
+    const root = requireRoot(projectRoot, 'admission config projectRoot');
+    const invalid = (field, message) => ({ ok: false, field, message });
+    const file = path_1.default.join(root, '.awm', 'admission.json');
+    // The file is repo-controlled: inspect it before reading so a link, device or huge
+    // file can never be followed or slurped into memory.
+    let stat;
+    try {
+        stat = fs_1.default.lstatSync(file);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { ok: true, config: { defaults: true, rules: defaultRules() } };
+        return invalid('(file)', 'could not be read');
+    }
+    if (!stat.isFile())
+        return invalid('(file)', 'must be a regular file, not a link or device');
+    if (stat.size > MAX_CONFIG_BYTES)
+        return invalid('(file)', `is larger than ${MAX_CONFIG_BYTES} bytes`);
+    let raw;
+    try {
+        raw = fs_1.default.readFileSync(file, 'utf8');
+    }
+    catch {
+        return invalid('(file)', 'could not be read');
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return invalid('(file)', 'is not valid JSON');
+    }
+    if (!isRecord(value))
+        return invalid('(root)', 'must be a JSON object');
+    const unknownRoot = Object.keys(value).find(key => key !== 'schemaVersion' && key !== 'readOnlyObservation');
+    if (unknownRoot !== undefined)
+        return invalid(fieldLabel(unknownRoot), 'is not a known field');
+    if (value.schemaVersion !== 1)
+        return invalid('schemaVersion', 'must be 1');
+    const observation = 'readOnlyObservation' in value ? value.readOnlyObservation : {};
+    if (!isRecord(observation))
+        return invalid('readOnlyObservation', 'must be an object');
+    const unknownObservation = Object.keys(observation).find(key => key !== 'defaults' && key !== 'exclude');
+    if (unknownObservation !== undefined)
+        return invalid(`readOnlyObservation.${fieldLabel(unknownObservation)}`, 'is not a known field');
+    const defaults = 'defaults' in observation ? observation.defaults : true;
+    if (typeof defaults !== 'boolean')
+        return invalid('readOnlyObservation.defaults', 'must be a boolean');
+    const exclude = 'exclude' in observation ? observation.exclude : [];
+    if (!Array.isArray(exclude))
+        return invalid('readOnlyObservation.exclude', 'must be an array of strings');
+    const rules = defaults ? defaultRules() : [];
+    for (const [index, entry] of exclude.entries()) {
+        const field = `readOnlyObservation.exclude[${index}]`;
+        if (typeof entry !== 'string')
+            return invalid(field, 'must be a string');
+        const problem = entryProblem(entry);
+        if (problem)
+            return invalid(field, problem);
+        rules.push(entry.includes('/') ? { kind: 'path', path: entry } : { kind: 'name', name: entry });
+    }
+    return { ok: true, config: { defaults, rules } };
+}
+/**
+ * Rule matching plus cached verdicts. The same policy instance serves the before and
+ * after snapshots, so a candidate is verified once and both passes agree.
+ */
+function createExclusionPolicy(config, verifier) {
+    if (!config || !Array.isArray(config.rules) || typeof config.defaults !== 'boolean')
+        throw new Error('exclusion policy requires a validated admission config');
+    if (typeof verifier !== 'function')
+        throw new Error('exclusion policy requires a candidate verifier');
+    const names = new Set(config.rules.flatMap(rule => (rule.kind === 'name' ? [rule.name] : [])));
+    const paths = new Set(config.rules.flatMap(rule => (rule.kind === 'path' ? [rule.path] : [])));
+    const verdicts = new Map();
+    return {
+        isExcluded(relativePath, name) {
+            // .git and .awm are never excluded, at any depth, nor anything inside them (B-R5).
+            if (relativePath.split('/').some(isReservedSegment))
+                return false;
+            if (!names.has(name) && !paths.has(relativePath))
+                return false;
+            let verdict = verdicts.get(relativePath);
+            if (verdict === undefined) {
+                verdict = verifier(relativePath);
+                verdicts.set(relativePath, verdict);
+            }
+            return verdict === 'excluded';
+        },
+        evidence() {
+            const excluded = [];
+            const rejected = [];
+            const sorted = [...verdicts.entries()].sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+            for (const [candidate, verdict] of sorted) {
+                if (verdict === 'excluded')
+                    excluded.push(candidate);
+                else
+                    rejected.push({ path: candidate, reason: verdict });
+            }
+            return { defaults: config.defaults, excluded, rejected };
+        },
+    };
+}
+/** A copy of `env` without repository-location variables (case-insensitive: Windows). */
+function scrubGitLocation(env) {
+    const scrubbed = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (!GIT_LOCATION_VARIABLES.has(key.toUpperCase()))
+            scrubbed[key] = value;
+    }
+    return scrubbed;
+}
+/** Git decides: no tracked file inside (checked first) and ignored. Any doubt observes. */
+function gitVerifier(projectRoot, env = process.env, spawn = child_process_1.spawnSync) {
+    const cwd = requireRoot(projectRoot, 'git verifier projectRoot');
+    const childEnv = scrubGitLocation(env);
+    const git = (args) => spawn('git', args, {
+        cwd,
+        env: childEnv,
+        encoding: 'utf8',
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: GIT_MAX_OUTPUT_BYTES,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return relativePath => {
+        // Git reads magic prefixes (":(top)", ":/") even after "--"; a leading "./"
+        // makes the candidate an ordinary relative pathspec, so a directory that is
+        // literally named like magic is never mistaken for a different path.
+        const pathspec = `./${relativePath}`;
+        // Tracked first: git already reports a directory holding a force-added file
+        // as not ignored, which would hide the more precise reason.
+        const tracked = git(['ls-files', '-z', '--', pathspec]);
+        if (tracked.error?.code === 'ENOBUFS')
+            return 'contains-tracked';
+        if (tracked.error || tracked.status !== 0)
+            return 'git-unavailable';
+        if (tracked.stdout !== '')
+            return 'contains-tracked';
+        const ignored = git(['check-ignore', '-q', '--', pathspec]);
+        if (ignored.error)
+            return 'git-unavailable';
+        if (ignored.status === 0)
+            return 'excluded';
+        return ignored.status === 1 ? 'not-ignored' : 'git-unavailable';
+    };
+}
+class SnapshotLimitError extends Error {
+    failure;
+    constructor(failure) {
+        super(failure);
+        this.failure = failure;
+    }
+}
+/**
+ * A git status only sees tracked and non-ignored paths, while a sensor can mutate
+ * ignored runtime files (notably `.awm/`) just as easily, so the actual tree is
+ * hashed. The walk is bounded: inability to observe the whole declared project means
+ * no admission certificate. Excluded directories contribute nothing; observed
+ * directories are hashed without their size, which changes as entries come and go
+ * and is already covered by their children.
+ */
+function filesystemSnapshot(root, policy, limits = DEFAULT_LIMITS) {
+    requireRoot(root, 'snapshot root');
+    if (!Number.isSafeInteger(limits.maxEntries) || limits.maxEntries < 1 || !Number.isSafeInteger(limits.maxBytes) || limits.maxBytes < 1) {
+        throw new Error('snapshot limits must be positive integers');
+    }
+    try {
+        const digest = crypto_1.default.createHash('sha256');
+        let entriesSeen = 0;
+        let bytesSeen = 0;
+        const visit = (directory, relative) => {
+            const entries = fs_1.default.readdirSync(directory, { withFileTypes: true })
+                .sort((left, right) => left.name.localeCompare(right.name));
+            for (const entry of entries) {
+                // Git's internal bookkeeping changes as a consequence of normal
+                // observation, not project sensor execution.
+                if (relative === '' && entry.name === '.git')
+                    continue;
+                const child = path_1.default.join(directory, entry.name);
+                const childRelative = relative === '' ? entry.name : `${relative}/${entry.name}`;
+                const stat = fs_1.default.lstatSync(child);
+                if (stat.isDirectory() && policy?.isExcluded(childRelative, entry.name))
+                    continue;
+                if (++entriesSeen > limits.maxEntries)
+                    throw new SnapshotLimitError('limit-entries');
+                if (stat.isDirectory()) {
+                    digest.update(`${childRelative}\0${stat.mode}\0directory\0`);
+                    visit(child, childRelative);
+                    continue;
+                }
+                digest.update(`${childRelative}\0${stat.mode}\0${stat.size}\0`);
+                if (stat.isFile()) {
+                    if ((bytesSeen += stat.size) > limits.maxBytes)
+                        throw new SnapshotLimitError('limit-bytes');
+                    digest.update('file\0');
+                    digest.update(fs_1.default.readFileSync(child));
+                }
+                else if (stat.isSymbolicLink()) {
+                    digest.update(`symlink\0${fs_1.default.readlinkSync(child)}\0`);
+                }
+                else {
+                    digest.update(`special\0${stat.rdev}\0`);
+                }
+            }
+        };
+        visit(root, '');
+        return { ok: true, digest: digest.digest('hex') };
+    }
+    catch (error) {
+        // Every unexpected error (unreadable entry, vanished file, a throwing injected
+        // policy) is deliberately reported as 'unreadable': a tree that cannot be fully
+        // observed must fail closed instead of yielding a digest.
+        return { ok: false, failure: error instanceof SnapshotLimitError ? error.failure : 'unreadable' };
+    }
+}
+function snapshotUnavailableRemedy(failure) {
+    if (failure === 'unreadable')
+        return 'run admission from a readable git worktree';
+    const limit = failure === 'limit-bytes' ? `${exports.READ_ONLY_MAX_BYTES / 1024 ** 3} GiB of observed file content` : `${exports.READ_ONLY_MAX_ENTRIES} observed entries`;
+    return `the project tree exceeds the read-only observation limit of ${limit}; git-ignore heavy generated directories `
+        + `(ignored ${exports.DEFAULT_EXCLUSION_NAMES.join(', ')} are skipped by default) or declare them in ${ADMISSION_CONFIG_LABEL} readOnlyObservation.exclude`;
+}
+function admissionConfigRemedy(problem) {
+    return `repair ${ADMISSION_CONFIG_LABEL}: ${problem.field} ${problem.message}`;
+}

package/dist/src/commands/sensors/run.js

@@ -6,12 +6,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyBaseline = void 0;
 exports.findManifestDir = findManifestDir;
 exports.detectPackDrift = detectPackDrift;
+exports.shouldRun = shouldRun;
 exports.resolveConcurrency = resolveConcurrency;
 exports.runSensors = runSensors;
-const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
-const crypto_1 = __importDefault(require("crypto"));
 const baseline_1 = require("./baseline");
 const result_1 = require("./result");
 Object.defineProperty(exports, "applyBaseline", { enumerable: true, get: function () { return result_1.applyBaseline; } });
@@ -28,64 +27,12 @@ const registries_1 = require("../../core/registries");
 const prepare_1 = require("./prepare");
 const verdict_1 = require("./verdict");
 const project_1 = require("./project");
+const read_only_observation_1 = require("./read-only-observation");
 // Sensor JSON output can be several MB on large repos (e.g. `eslint --format json`
 // with thousands of findings). A 1MB cap killed the child with SIGTERM when
 // exceeded — which previously surfaced as a false "timeout".
 /** Hard ceiling on parallel sensors: past this, they only contend for the same cores. */
 const MAX_CONCURRENCY = 4;
-const READ_ONLY_MAX_ENTRIES = 250_000;
-const READ_ONLY_MAX_BYTES = 1024 * 1024 * 1024;
-/**
- * A git status only sees tracked and non-ignored paths, while a sensor can
- * mutate ignored runtime files (notably `.awm/`) just as easily. Hash the
- * actual project tree instead. The scan is deliberately bounded: inability to
- * observe the whole declared project means no admission certificate.
- */
-function filesystemSnapshot(root) {
-    try {
-        const digest = crypto_1.default.createHash('sha256');
-        let entriesSeen = 0;
-        let bytesSeen = 0;
-        const visit = (directory, relative) => {
-            const entries = fs_1.default.readdirSync(directory, { withFileTypes: true })
-                .sort((left, right) => left.name.localeCompare(right.name));
-            for (const entry of entries) {
-                // Git's internal bookkeeping changes as a consequence of normal
-                // observation, not project sensor execution. Everything else,
-                // including ignored/untracked `.awm`, is evidence-relevant.
-                if (relative === '' && entry.name === '.git')
-                    continue;
-                if (++entriesSeen > READ_ONLY_MAX_ENTRIES)
-                    throw new Error('snapshot-entry-limit');
-                const child = path_1.default.join(directory, entry.name);
-                const childRelative = relative === '' ? entry.name : `${relative}/${entry.name}`;
-                const stat = fs_1.default.lstatSync(child);
-                digest.update(`${childRelative}\0${stat.mode}\0${stat.size}\0`);
-                if (stat.isDirectory()) {
-                    digest.update('directory\0');
-                    visit(child, childRelative);
-                }
-                else if (stat.isFile()) {
-                    if ((bytesSeen += stat.size) > READ_ONLY_MAX_BYTES)
-                        throw new Error('snapshot-byte-limit');
-                    digest.update('file\0');
-                    digest.update(fs_1.default.readFileSync(child));
-                }
-                else if (stat.isSymbolicLink()) {
-                    digest.update(`symlink\0${fs_1.default.readlinkSync(child)}\0`);
-                }
-                else {
-                    digest.update(`special\0${stat.rdev}\0`);
-                }
-            }
-        };
-        visit(root, '');
-        return digest.digest('hex');
-    }
-    catch {
-        return null;
-    }
-}
 async function resolveLiveFromSource(cwd, source, packSelection) {
     try {
         const parsed = (0, contract_1.parseSensorPack)(JSON.parse(source.content), source.path);
@@ -213,9 +160,20 @@ async function runSensors(opts = {}) {
         configured = project;
     }
     const manifestDir = configured.projectRoot;
-    const beforeReadOnly = opts.readOnly ? filesystemSnapshot(manifestDir) : undefined;
-    if (opts.readOnly && beforeReadOnly === null) {
-        return { sensors: [], overall: 'not_certified', projectRoot: configured.projectRoot, manifestPath: configured.manifestPath, mode: 'invalid', reason: 'read-only-observation-unavailable', remedy: 'run admission from a readable git worktree' };
+    // Admission-only: `.awm/admission.json` is never read for ordinary runs.
+    let readOnlyPolicy;
+    let beforeReadOnly;
+    if (opts.readOnly) {
+        const admissionConfig = (0, read_only_observation_1.loadAdmissionConfig)(manifestDir);
+        if (!admissionConfig.ok) {
+            return { sensors: [], overall: 'not_certified', projectRoot: configured.projectRoot, manifestPath: configured.manifestPath, mode: 'invalid', reason: 'admission-config-invalid', remedy: (0, read_only_observation_1.admissionConfigRemedy)(admissionConfig) };
+        }
+        readOnlyPolicy = (0, read_only_observation_1.createExclusionPolicy)(admissionConfig.config, (0, read_only_observation_1.gitVerifier)(manifestDir));
+        const before = (0, read_only_observation_1.filesystemSnapshot)(manifestDir, readOnlyPolicy);
+        if (!before.ok) {
+            return { sensors: [], overall: 'not_certified', projectRoot: configured.projectRoot, manifestPath: configured.manifestPath, mode: 'invalid', reason: 'read-only-observation-unavailable', remedy: (0, read_only_observation_1.snapshotUnavailableRemedy)(before.failure), readOnlyObservation: readOnlyPolicy.evidence() };
+        }
+        beforeReadOnly = before.digest;
     }
     const parsed = configured.manifest;
     const authority = { projectRoot: configured.projectRoot, manifestPath: configured.manifestPath };
@@ -382,8 +340,14 @@ async function runSensors(opts = {}) {
         ...(drift?.drift ? { packDrift: drift.drift } : {}),
         ...(changed ? { changedScope: { files: changed.files.length, ...(changed.error ? { error: changed.error } : {}) } } : {}),
     };
-    if (opts.readOnly && filesystemSnapshot(manifestDir) !== beforeReadOnly) {
-        return { ...output, overall: 'not_certified', reason: 'read-only-mutation-detected', remedy: 'sensor execution changed the worktree; repair it before using this evidence for admission' };
+    if (readOnlyPolicy) {
+        // Same policy instance: cached verdicts keep both passes consistent.
+        const after = (0, read_only_observation_1.filesystemSnapshot)(manifestDir, readOnlyPolicy);
+        const readOnlyObservation = readOnlyPolicy.evidence();
+        if (!after.ok || after.digest !== beforeReadOnly) {
+            return { ...output, overall: 'not_certified', reason: 'read-only-mutation-detected', remedy: 'sensor execution changed the worktree; repair it before using this evidence for admission', readOnlyObservation };
+        }
+        return { ...output, readOnlyObservation };
     }
     return output;
 }

package/dist/src/core/admission/index.js

@@ -101,6 +101,16 @@ function currentness(report, consumedRegistryComponents) {
     return { status, cli, diagnostics: [diagnostic('ADMISSION_CURRENTNESS_BLOCKED', `Consumed contract currentness is ${status}: ${names}.`)] };
 }
 function sensorVerdict(report) { return report.overall === 'not_certified' ? 'not-certified' : report.overall === 'pass' ? 'pass' : 'fail'; }
+/** A not-certified verdict alone does not say what to fix; carry the run's own cause. */
+function sensorBlockedMessage(report, verdict) {
+    // The diagnostic code must stay the message's only ADMISSION_ token (recovery classification counts them); echoed text may carry user-chosen ones.
+    const plain = (text) => text.trim().replace(/ADMISSION_/g, 'ADMISSION-');
+    const reason = verdict === 'not-certified' && typeof report.reason === 'string' ? plain(report.reason) : '';
+    if (!reason)
+        return `Sensor verdict is ${verdict}.`;
+    const remedy = typeof report.remedy === 'string' ? plain(report.remedy).replace(/\.+$/, '') : '';
+    return remedy ? `Sensor verdict is ${verdict} (${reason}): ${remedy}.` : `Sensor verdict is ${verdict} (${reason}).`;
+}
 function journalStatus(input, plan) {
     if (input.journalCorrupt)
         return 'corrupt';
@@ -237,7 +247,7 @@ async function admitPlan(input) {
         const sensors = sensorVerdict(input.sensors);
         const registryOptOut = sensors === 'not-certified' && input.sensorClosurePolicy === 'r8-registry-opt-out' && input.sensors.mode === 'opt-out';
         if (sensors !== 'pass' && !registryOptOut)
-            return blocked(input, [diagnostic('ADMISSION_SENSORS_BLOCKED', `Sensor verdict is ${sensors}.`)], { planDigest: plan.planDigest, provider, executionMode: mode, currentness: input.requireCurrent ? 'current' : 'not-checked', cliCurrentness, sensors });
+            return blocked(input, [diagnostic('ADMISSION_SENSORS_BLOCKED', sensorBlockedMessage(input.sensors, sensors))], { planDigest: plan.planDigest, provider, executionMode: mode, currentness: input.requireCurrent ? 'current' : 'not-checked', cliCurrentness, sensors });
         sensorsReported = sensors;
         if (registryOptOut)
             sensorEvidence = { sensorEvidence: 'r8-registry-opt-out' };

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

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.failed = exports.fail = exports.line = void 0;
+exports.inCwd = inCwd;
+const command_result_1 = require("../command-result");
+const text_safety_1 = require("./text-safety");
+// What the Change Record commands (`change new`, `change validate`, `changes list`) share of their command line: one line of
+// output, the stderr form of a failure and the working-directory guard of an action. Nothing here throws or imports a command.
+/** One line of output: control characters escaped, at most 300 UTF-16 units (an ellipsis replaces the cut), never splitting a surrogate pair. */
+const line = (text) => (0, text_safety_1.clipMessage)((0, text_safety_1.cleanText)(text));
+exports.line = line;
+/**
+ * Exit 2 with `code: message` as ONE clipped line (the code counts), and an optional static remedy as a second clipped line.
+ * Untrusted text is escaped by the caller with esc().
+ */
+const fail = (code, message, remedy) => ({
+    code: 2, stdout: '',
+    stderr: `${(0, exports.line)(`${code}: ${message}`)}\n${remedy ? `${(0, exports.line)(`  remedy: ${remedy}`)}\n` : ''}`,
+});
+exports.fail = fail;
+/** A shared-helper Failure as the stderr form. */
+const failed = (f) => (0, exports.fail)(f.code, f.message, f.remedy);
+exports.failed = failed;
+/**
+ * The action wrapper: runs `command` in the working directory and emits its result. The working directory may be gone: then
+ * `noCwd()` is emitted instead. Nothing may throw out of the action.
+ */
+function inCwd(command, noCwd) {
+    let cwd;
+    try {
+        cwd = process.cwd();
+    }
+    catch {
+        (0, command_result_1.emit)(noCwd());
+        return;
+    }
+    (0, command_result_1.emit)(command(cwd));
+}

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

@@ -0,0 +1,120 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveFromCommits = deriveFromCommits;
+exports.deriveModules = deriveModules;
+exports.commitsFromRecords = commitsFromRecords;
+exports.deriveFields = deriveFields;
+const path_1 = __importDefault(require("path"));
+const core_1 = require("../../release/core");
+const git_1 = require("./git");
+const text_safety_1 = require("./text-safety");
+const types_1 = require("./types");
+// Pathspecs relative to the repository top, so the result does not depend on the directory git runs in.
+const ALL_FILES = ':/';
+const EXCLUDE_RECORDS = `:(top,exclude,literal)${types_1.RECORD_DIR}`;
+const PARSER_TYPE = /^\w+$/;
+const RECORD_TYPE = /^[a-z]+$/;
+const MODULE_DEPTH = 3;
+// R3.3: the release parser's header regex backtracks quadratically on a long subject with blanks and line terminators, so a
+// subject (the text before the first US of a record) over this many UTF-16 units is never handed to it.
+const MAX_SUBJECT_UNITS = 1024;
+/** Keeps the commits the release parser can produce (a `\w+` type, any spelling) with a scope that is usable text; anything else is ignored. */
+function usable(commits) {
+    if (!Array.isArray(commits))
+        return [];
+    const out = [];
+    for (const c of commits) {
+        if (typeof c !== 'object' || c === null)
+            continue;
+        const { type, scope, breaking, subject } = c;
+        if (typeof type !== 'string' || !PARSER_TYPE.test(type))
+            continue;
+        const cleanScope = typeof scope === 'string' && scope.trim() !== '' && (0, text_safety_1.isSingleLine)(scope) ? scope.trim() : null;
+        out.push({ type, scope: cleanScope, breaking: breaking === true, subject: typeof subject === 'string' ? subject : '' });
+    }
+    return out;
+}
+const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * R3.3. `breaking` and `semver` cover every usable commit, with the release parser's exact-type semantics; the recorded type is
+ * the highest-impact commit's type lowercased, or `other` when that is still not purely letters. Null when no commit is usable.
+ */
+function deriveFromCommits(input) {
+    const commits = usable(input);
+    if (commits.length === 0)
+        return null;
+    const breaking = commits.some((c) => c.breaking);
+    const pick = commits.find((c) => c.breaking) ?? commits.find((c) => c.type === 'feat') ?? commits.find((c) => c.type === 'fix')
+        ?? commits.find((c) => c.type === 'perf') ?? commits[0];
+    const counts = new Map();
+    for (const c of commits)
+        if (c.scope)
+            counts.set(c.scope, (counts.get(c.scope) ?? 0) + 1);
+    const scope = [...counts.entries()].sort((a, b) => b[1] - a[1] || byCodeUnit(a[0], b[0]))[0]?.[0] ?? null;
+    const semver = (0, core_1.determineBump)(commits) ?? 'none';
+    const type = pick.type.toLowerCase();
+    return { type: RECORD_TYPE.test(type) ? type : 'other', scope, semver, breaking };
+}
+/** R3.4. Directories a record cannot hold (control characters, backslashes, `..` ...) are left out rather than leaked into it. */
+function deriveModules(files) {
+    if (!Array.isArray(files))
+        return [];
+    const modules = new Set();
+    for (const f of files) {
+        if (typeof f !== 'string' || f.length === 0 || f.startsWith(`${types_1.RECORD_DIR}/`))
+            continue;
+        const dir = path_1.default.posix.dirname(f);
+        const module = dir === '.' ? '.' : dir.split('/').slice(0, MODULE_DEPTH).join('/');
+        if (module === '.' || (0, text_safety_1.isSafeRelativePath)(module))
+            modules.add(module);
+    }
+    return [...modules].sort();
+}
+/**
+ * The conventional commits of NUL-separated `git log` records. Measured on the raw record, before RS is stripped (the stripped text
+ * is never longer): like the release parser, the subject ends at the first US, so only the text before it counts, and a subject over
+ * MAX_SUBJECT_UNITS is never handed to the parser.
+ */
+function commitsFromRecords(records) {
+    return records.flatMap((record) => {
+        const end = record.indexOf(core_1.US);
+        return (end < 0 ? record.length : end) > MAX_SUBJECT_UNITS ? [] : (0, core_1.parseCommits)(record.split(core_1.RS).join(''));
+    });
+}
+const fail = (code, message) => ({ ok: false, diagnostic: { code, message: (0, text_safety_1.clipMessage)(message) } });
+/**
+ * Derives from the non-merge commits in mergeBaseSha..HEAD, ignoring commits and files that only touch docs/changes/.
+ * `mergeBaseSha` must be a full commit id (the output of `mergeBase`); anything else is `invalid-input`.
+ */
+function deriveFields(root, mergeBaseSha) {
+    if (typeof root !== 'string' || root.length === 0)
+        return fail('invalid-input', 'repository root must be a non-empty string');
+    if (typeof mergeBaseSha !== 'string' || !types_1.COMMIT_ID.test(mergeBaseSha))
+        return fail('invalid-input', `merge-base must be a full commit id, got "${(0, text_safety_1.esc)(mergeBaseSha)}"`);
+    // HEAD is read once: the log and the diff below both use this sha, so a HEAD that moves meanwhile cannot mix snapshots.
+    const head = (0, git_1.headSha)(root);
+    if (head === null)
+        return fail('git-failed', 'git could not read HEAD');
+    const range = `${mergeBaseSha}..${head}`;
+    // --full-history: with a pathspec git would otherwise prune the side of a merge whose tree equals the other parent
+    // (`merge -s ours`), silently dropping real commits from the range.
+    // -z ends every commit with NUL, which a message cannot contain: each record is exactly one commit, so a message that
+    // embeds the parser's own separator cannot be read as a second commit.
+    const raw = (0, git_1.runGit)(root, ['log', ...git_1.LOG_SAFETY_ARGS, '--no-merges', '--full-history', '--reverse', '-z', `--format=${core_1.GIT_LOG_FORMAT}`, '--end-of-options', range, '--', ALL_FILES, EXCLUDE_RECORDS]);
+    if (raw === null)
+        return fail('git-failed', `git could not read the commits in ${range}`);
+    const records = raw.split('\0').filter((record) => record !== '');
+    if (records.length === 0)
+        return fail('no-commits', `no non-merge commits outside ${types_1.RECORD_DIR}/ in ${range}`);
+    const commits = commitsFromRecords(records);
+    const derived = deriveFromCommits(commits);
+    if (derived === null)
+        return fail('no-conventional-commits', 'no commit in the range uses a conventional-commit subject (type(scope): subject)');
+    const files = (0, git_1.changedFiles)(root, mergeBaseSha, head);
+    if (files === null)
+        return fail('git-failed', `git could not list the files changed in ${range}`);
+    return { ok: true, fields: { ...derived, modules: deriveModules(files) } };
+}

package/dist/src/core/changes/fs-safe.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRegularFileInside = isRegularFileInside;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const text_safety_1 = require("./text-safety");
+// Read-only filesystem checks. No import of the write-capable record-io: the pure record validator depends on this module.
+/** True when `name` is listed in `parent` exactly as spelled: on a case-insensitive file system `stat` also finds other spellings. */
+function listedAs(parent, name) {
+    try {
+        return fs_1.default.readdirSync(parent).includes(name);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A repo-relative path naming a regular file (not a link) that lies inside `root` once every link on the way is resolved, and
+ * whose every segment is spelled exactly as on disk (so the answer is the same on a case-insensitive file system as on Linux,
+ * where the validation of the committed record will run). Never throws.
+ */
+function isRegularFileInside(root, rel) {
+    if (typeof root !== 'string' || !(0, text_safety_1.isSafeRelativePath)(rel))
+        return false;
+    const segments = rel.split('/');
+    const abs = path_1.default.join(root, ...segments);
+    try {
+        if (!fs_1.default.lstatSync(abs).isFile())
+            return false;
+        const inside = path_1.default.relative(fs_1.default.realpathSync.native(root), fs_1.default.realpathSync.native(abs));
+        if (inside === '' || inside === '..' || inside.startsWith(`..${path_1.default.sep}`) || path_1.default.isAbsolute(inside))
+            return false;
+        let parent = root;
+        for (const segment of segments) {
+            if (!listedAs(parent, segment))
+                return false;
+            parent = path_1.default.join(parent, segment);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}