approval-md 0.4.3 → 0.4.6

package/dist/src/core/git-push-argv.js

@@ -0,0 +1,375 @@
+/**
+ * `git push` read the way git 2.50's option parser reads it (APRV-517).
+ *
+ * The classifier's `git-push` row used to look for flags by exact spelling:
+ * `--delete` and `-d`, `--force` and `-f`. git's parser accepts more than
+ * that, and every extra spelling it accepts did the same thing as the one it
+ * stands for while classifying as a plain push:
+ *
+ * - a short bundle: `-ud`, `-du`, `-fd`, `-dn` carry `-d` (and `-f`);
+ * - a long-option abbreviation by unique prefix: `--de`, `--del`, `--dele`
+ *   and `--delet` are `--delete`, `--m` is `--mirror`, `--pru` is `--prune`;
+ * - a deleting option the exact list never named: `--prune` removes every
+ *   remote ref a wildcard refspec no longer matches;
+ * - the words after a value-taking option (`-o x`, `--repo x`) shift the
+ *   positionals, and a global option in front of `push` (`git --no-pager
+ *   push origin`) shifted them too.
+ *
+ * So this file is the closed rule: it walks the argv exactly as git's
+ * `parse-options.c` does over the option table of `builtin/push.c` in git
+ * 2.50, and reports what the push does rather than which words it contains.
+ * Anything it cannot walk is a refusal, never a guess:
+ *
+ * - `unreadable`: a word the shell may split or expand into words this walk
+ *   never saw (`$`, a backtick, a glob, a brace expansion), a word that came
+ *   out of a command substitution, or an assignment or global option in
+ *   front of `push` that steers which configuration git reads (`GIT_*=`,
+ *   `HOME=`, `XDG_CONFIG_HOME=`, `--git-dir=`, `--work-tree=`,
+ *   `--config-env=`: `remote.origin.push=:refs/heads/main` deletes the trunk
+ *   with no refspec on the command line, and `remote.<name>.mirror` turns a
+ *   plain push into a mirror). Any of these can hold `-d`, `:main` or `+main`;
+ * - `unparseable`: an option git does not know, an ambiguous abbreviation, a
+ *   value where none is taken, a missing value, or a global option in front
+ *   of `push` this file does not know. git refuses all of these itself, so
+ *   refusing them costs nothing, and a newer git that grew an option this
+ *   table lacks is refused rather than read as a plain push;
+ * - `runs-program`: `--receive-pack` / `--exec` name the program git starts
+ *   for the far side, which for a local or `file://` remote runs on this
+ *   machine, and `git --exec-path=` picks where git finds its helpers. What it runs is a command line this classifier is not reading,
+ *   the reason `find -exec` is opaque (APRV-283).
+ *
+ * Negations (`--no-delete`) never clear a flag an earlier word set: a push
+ * that both deletes and un-deletes is read as deleting, which only ever picks
+ * the stricter class for a spelling nobody writes.
+ *
+ * The walk is checked against the real binary: tests/git-push-delete-spellings
+ * runs every deleting spelling against a bare local remote and asserts the ref
+ * is gone, and the generated differential there runs the corpus through git
+ * and asserts every deletion and every forced update it observed was
+ * classified at least that strictly.
+ */
+/**
+ * `git push -h` on git 2.50, in `builtin/push.c` order. Order matters only for
+ * which candidate an ambiguity error names, never for which option matches.
+ */
+export const GIT_PUSH_OPTIONS = [
+    { long: "verbose", short: "v", value: "none" },
+    { long: "quiet", short: "q", value: "none" },
+    { long: "repo", value: "required" },
+    { long: "all", value: "none", effect: "all" },
+    { long: "branches", value: "none", aliasOf: "all", effect: "all" },
+    { long: "mirror", value: "none", effect: "mirror" },
+    { long: "delete", short: "d", value: "none", effect: "remove" },
+    { long: "tags", value: "none", effect: "tags" },
+    { long: "dry-run", short: "n", value: "none" },
+    { long: "porcelain", value: "none" },
+    { long: "force", short: "f", value: "none", effect: "force" },
+    { long: "force-with-lease", value: "optional", effect: "force" },
+    { long: "force-if-includes", value: "none", effect: "force" },
+    { long: "recurse-submodules", value: "required", effect: "submodules" },
+    { long: "thin", value: "none" },
+    { long: "receive-pack", value: "required", effect: "program" },
+    { long: "exec", value: "required", effect: "program" },
+    { long: "set-upstream", short: "u", value: "none" },
+    { long: "progress", value: "none" },
+    { long: "prune", value: "none", effect: "prune" },
+    { long: "no-verify", value: "none" },
+    { long: "follow-tags", value: "none", effect: "tags" },
+    { long: "signed", value: "optional" },
+    { long: "atomic", value: "none" },
+    { long: "push-option", short: "o", value: "required" },
+    { long: "ipv4", short: "4", value: "none", noneg: true },
+    { long: "ipv6", short: "6", value: "none", noneg: true },
+];
+/**
+ * The help options parse-options itself answers, by exact spelling only
+ * (`-h` is the short one): each prints usage and exits without pushing, so it
+ * adds nothing to the reading.
+ */
+const INTERNAL_LONG = ["help", "help-all"];
+/**
+ * Global options in front of the subcommand (`git.c` `handle_options`, git
+ * 2.50), matched by exact spelling, as git matches them. These take no value
+ * and change nothing about what a push sends.
+ */
+const GIT_GLOBAL_BARE = [
+    "-p",
+    "--paginate",
+    "-P",
+    "--no-pager",
+    "--no-replace-objects",
+    "--no-lazy-fetch",
+    "--no-optional-locks",
+    "--no-advice",
+    "--bare",
+    "--literal-pathspecs",
+    "--glob-pathspecs",
+    "--noglob-pathspecs",
+    "--icase-pathspecs",
+];
+/** `=`-joined globals that change nothing about what a push sends either. */
+const GIT_GLOBAL_JOINED = ["--namespace=", "--attr-source="];
+/**
+ * `=`-joined globals that decide which configuration the push runs under:
+ * another repository's `.git/config` (`--git-dir`, `--work-tree`) or a value
+ * injected from the environment (`--config-env`). Configuration can carry a
+ * deleting refspec or `mirror = true`, so these read like a steering
+ * assignment.
+ */
+const GIT_GLOBAL_STEERING = ["--git-dir=", "--work-tree=", "--config-env="];
+/** `--exec-path=` picks the directory git runs its helper programs from. */
+const GIT_GLOBAL_PROGRAM = "--exec-path";
+// Anything else in front of `push` is refused, the separate-value forms
+// (`-C dir`, `-c k=v`, `--git-dir dir`) included: there the word the
+// classifier took for the subcommand may have been that option's value.
+/** Assignments in front of `git` that steer which configuration it reads. */
+const STEERING_ENV = /^(?:GIT_[A-Za-z0-9_]*|HOME|XDG_CONFIG_HOME)=/u;
+/** `$`, a backtick, or a glob character: the shell may expand the word into others. */
+const EXPANDING_CHAR = /[$`*?[\]]/u;
+/** A brace expansion: `{a,b}` or `{1..3}`. A reflog `@{1}` is neither. */
+const BRACE_EXPANSION = /\{[^{}]*(?:,|\.\.)[^{}]*\}/u;
+/** Can the shell turn this word into a different word, or into several? */
+export function isUnreadablePushWord(word) {
+    return EXPANDING_CHAR.test(word) || BRACE_EXPANSION.test(word);
+}
+/** Are these two options one option under two names (`OPT_ALIAS`)? */
+function isAlias(a, b) {
+    return a.aliasOf === b.long || b.aliasOf === a.long || (a.aliasOf !== undefined && a.aliasOf === b.aliasOf);
+}
+/**
+ * `parse_long_opt` in git 2.50's `parse-options.c`, over `name` (the text
+ * after `--` and before any `=`).
+ *
+ * An exact spelling wins outright. Otherwise every option the text is a
+ * prefix of is a candidate, positively or through `no-`; two candidates that
+ * are not aliases of each other are ambiguous, which git refuses.
+ */
+function matchLong(name) {
+    let abbrev = null;
+    let ambiguous = false;
+    const candidate = (option, unset) => {
+        if (abbrev !== null && !isAlias(abbrev.option, option))
+            ambiguous = true;
+        abbrev = { option, unset };
+    };
+    for (const option of GIT_PUSH_OPTIONS) {
+        let long = option.long;
+        let optUnset = false;
+        if (long.startsWith("no-")) {
+            long = long.slice(3);
+            optUnset = true;
+        }
+        if (name.startsWith(long)) {
+            if (name === long)
+                return { option, unset: optUnset };
+            continue;
+        }
+        if (long.startsWith(name)) {
+            candidate(option, optUnset);
+            continue;
+        }
+        if (option.noneg === true)
+            continue;
+        if ("no-".startsWith(name)) {
+            candidate(option, !optUnset);
+            continue;
+        }
+        if (!name.startsWith("no-"))
+            continue;
+        const rest = name.slice(3);
+        if (rest.startsWith(long)) {
+            if (rest === long)
+                return { option, unset: !optUnset };
+            continue;
+        }
+        if (long.startsWith(rest))
+            candidate(option, !optUnset);
+    }
+    if (ambiguous)
+        return "ambiguous";
+    return abbrev;
+}
+/** The option a short letter names, or `null`. */
+function matchShort(letter) {
+    return GIT_PUSH_OPTIONS.find((option) => option.short === letter) ?? null;
+}
+/**
+ * Split the words after `git` at the `push` subcommand: the global options in
+ * front of it, and the push's own argv after it.
+ */
+export function splitGitPush(gitArgs) {
+    const at = gitArgs.findIndex((word) => !(word.startsWith("-") && word !== "-"));
+    if (at === -1 || gitArgs[at] !== "push")
+        return null;
+    return { globals: gitArgs.slice(0, at), words: gitArgs.slice(at + 1) };
+}
+/** The global options in front of `push`, judged; `null` when they change nothing. */
+function judgeGlobals(globals) {
+    for (const word of globals) {
+        if (isUnreadablePushWord(word)) {
+            return { ok: false, kind: "unreadable", detail: `the shell may expand ${word} into other words` };
+        }
+        if (GIT_GLOBAL_BARE.includes(word))
+            continue;
+        if (GIT_GLOBAL_JOINED.some((prefix) => word.startsWith(prefix)))
+            continue;
+        if (GIT_GLOBAL_STEERING.some((prefix) => word.startsWith(prefix))) {
+            return {
+                ok: false,
+                kind: "unreadable",
+                detail: `git ${word.slice(0, word.indexOf("=") + 1)}… decides which configuration the push reads`,
+            };
+        }
+        if (word === GIT_GLOBAL_PROGRAM || word.startsWith(`${GIT_GLOBAL_PROGRAM}=`)) {
+            return { ok: false, kind: "runs-program", detail: "git --exec-path picks the directory git runs its helpers from" };
+        }
+        return {
+            ok: false,
+            kind: "unparseable",
+            detail: `git ${word} in front of push: this classifier does not read that global option`,
+        };
+    }
+    return null;
+}
+/**
+ * Walk a `git push` argv (the words after `push`) the way git does.
+ *
+ * `assignments` are the `NAME=value` words in front of `git`, `substituted`
+ * says whether any word came out of a command substitution, and `globals` are
+ * the git options in front of `push` ({@link splitGitPush}).
+ */
+export function parseGitPushArgv(words, assignments = [], substituted = false, globals = []) {
+    const globalRefusal = judgeGlobals(globals);
+    if (globalRefusal !== null)
+        return globalRefusal;
+    if (substituted) {
+        return { ok: false, kind: "unreadable", detail: "a word of this push is a command substitution's output" };
+    }
+    const steering = assignments.find((word) => STEERING_ENV.test(word));
+    if (steering !== undefined) {
+        return {
+            ok: false,
+            kind: "unreadable",
+            detail: `${steering.slice(0, steering.indexOf("="))}=… in front of git steers which configuration the push reads`,
+        };
+    }
+    const unreadable = words.find(isUnreadablePushWord);
+    if (unreadable !== undefined) {
+        return { ok: false, kind: "unreadable", detail: `the shell may expand ${unreadable} into other words` };
+    }
+    const reading = {
+        force: false,
+        remove: false,
+        prune: false,
+        tags: false,
+        all: false,
+        positionals: [],
+    };
+    const unparseable = (detail) => ({ ok: false, kind: "unparseable", detail });
+    const apply = (option, unset, value) => {
+        if (unset)
+            return null;
+        switch (option.effect) {
+            case "force":
+                reading.force = true;
+                break;
+            case "mirror":
+                reading.force = true;
+                reading.all = true;
+                break;
+            case "remove":
+                reading.remove = true;
+                break;
+            case "prune":
+                reading.prune = true;
+                break;
+            case "tags":
+                reading.tags = true;
+                break;
+            case "all":
+                reading.all = true;
+                break;
+            case "submodules":
+                // `check` only verifies and `no` turns it off; `on-demand` and `only`
+                // push the submodules' own branches, which may be their trunks.
+                if (value !== "check" && value !== "no")
+                    reading.all = true;
+                break;
+            case "program":
+                return {
+                    ok: false,
+                    kind: "runs-program",
+                    detail: `git push --${option.long} names the program git runs for the far side`,
+                };
+            default:
+                break;
+        }
+        return null;
+    };
+    for (let index = 0; index < words.length; index += 1) {
+        const word = words[index];
+        if (word === "--" || word === "--end-of-options") {
+            reading.positionals.push(...words.slice(index + 1));
+            break;
+        }
+        if (word.startsWith("--")) {
+            const body = word.slice(2);
+            const equals = body.indexOf("=");
+            const name = equals === -1 ? body : body.slice(0, equals);
+            if (INTERNAL_LONG.includes(body))
+                continue;
+            const matched = matchLong(name);
+            if (matched === "ambiguous")
+                return unparseable(`git push --${name} is ambiguous`);
+            if (matched === null)
+                return unparseable(`git push has no option --${name}`);
+            const { option, unset } = matched;
+            let value;
+            if (equals !== -1) {
+                if (unset || option.value === "none")
+                    return unparseable(`git push --${name} takes no value`);
+                value = body.slice(equals + 1);
+            }
+            else if (!unset && option.value === "required") {
+                if (index + 1 >= words.length)
+                    return unparseable(`git push --${name} requires a value`);
+                index += 1;
+                value = words[index];
+            }
+            const refusal = apply(option, unset, value);
+            if (refusal !== null)
+                return refusal;
+            continue;
+        }
+        if (word.startsWith("-") && word !== "-") {
+            const letters = word.slice(1);
+            for (let at = 0; at < letters.length; at += 1) {
+                const letter = letters[at];
+                if (letter === "h")
+                    break;
+                const option = matchShort(letter);
+                if (option === null)
+                    return unparseable(`git push has no switch -${letter}`);
+                if (option.value === "required") {
+                    // The rest of the bundle is the value, or else the next word.
+                    if (at + 1 >= letters.length) {
+                        if (index + 1 >= words.length)
+                            return unparseable(`git push -${letter} requires a value`);
+                        index += 1;
+                    }
+                    const refusal = apply(option, false, undefined);
+                    if (refusal !== null)
+                        return refusal;
+                    break;
+                }
+                const refusal = apply(option, false, undefined);
+                if (refusal !== null)
+                    return refusal;
+            }
+            continue;
+        }
+        reading.positionals.push(word);
+    }
+    return { ok: true, reading };
+}
+//# sourceMappingURL=git-push-argv.js.map

package/dist/src/core/git-push-argv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-push-argv.js","sourceRoot":"","sources":["../../../src/core/git-push-argv.ts"],"names":[],"mappings":"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"}

package/dist/src/core/harness-version.d.ts

@@ -73,19 +73,56 @@ export declare const HARNESS_BINARY: Readonly<Record<HarnessKind, string>>;
  * forever. So the write boundary takes one line, printable ASCII only, capped.
  */
 export declare const HARNESS_VERSION_LIMIT = 64;
+/**
+ * The longest leading run of printable ASCII, U+0020 through U+007E.
+ *
+ * The one place the recordable-character rule lives (APRV-419). The run stops
+ * at the first character outside that range, so a non-ASCII character, a
+ * control character (a newline, a tab, a carriage return, a BEL) and EVERYTHING
+ * after any of them is cut, even when what follows would be printable again.
+ * The schema's pattern for `payload.harness_version` (`^[\u0020-\u007e]+$`)
+ * admits exactly the strings this can return, so the rule and the write
+ * boundary cannot drift apart.
+ */
+export declare function printableAsciiPrefix(text: string): string;
 /**
  * The one spelling of a harness version this runtime ever writes or compares.
  *
- * First line, trimmed, and nothing else: `claude --version` prints
- * `2.0.14 (Claude Code)` and a future release may add a second line of banner.
- * Both the hook (which records) and doctor (which compares) call this, so the
- * comparison is between two values normalized identically — a row that failed
- * because one side kept a trailing newline would be a false alarm, and a false
- * alarm in a health check trains an operator to ignore it.
+ * First line, trimmed, then its printable-ASCII prefix ({@link
+ * printableAsciiPrefix}), trimmed again. `claude --version` prints
+ * `2.0.14 (Claude Code)` and passes through whole; a future release may add a
+ * second line of banner, which the prefix never reaches. Both the hook (which
+ * records) and doctor (which compares) call this, so the comparison is between
+ * two values normalized identically: a row that failed because one side kept a
+ * trailing newline would be a false alarm, and a false alarm in a health check
+ * trains an operator to ignore it.
+ *
+ * ## Why a prefix rather than a refusal (APRV-419, option (c))
+ *
+ * Until APRV-419 a line holding any byte outside printable ASCII was refused
+ * whole. Hermes prints `Hermes Agent v0.21.3 (2026.9.14) · upstream 913d4098`
+ * and the separator is U+00B7, so no record ever carried a Hermes version and
+ * doctor could never compare one. Carter chose, on 2026-10-17, to record the
+ * prefix instead: for that line, `Hermes Agent v0.21.3 (2026.9.14)`. The
+ * upstream commit after the separator is lost, which is why the fail-closed
+ * floor below still reads the raw line.
+ *
+ * The SET of recordable values is unchanged. Every value returned here is a
+ * string the old rule accepted as a whole line (one line, printable ASCII,
+ * 1..64 characters), so the schema, the read side ({@link
+ * readHarnessProvenance}) and every record already written are unchanged. What
+ * moved is which part of a line is recorded: the line is cut at its first
+ * non-printable character, and the 64-character cap then applies to that prefix
+ * rather than to the whole line. So a long line whose printable-ASCII prefix
+ * fits the cap now records the prefix where the old rule refused the line, and
+ * at most 64 printable-ASCII characters of any line reach the log (SPEC.md
+ * §11.1 invariant 3).
  *
  * Returns `null` for anything that is not a usable version: empty output, a
- * line that is not printable ASCII, or one longer than the cap. Absence is
- * always available and always honest.
+ * line with no printable-ASCII prefix, or a prefix longer than the cap. The cut
+ * at the first non-printable character is the one truncation this applies; a
+ * prefix still over the cap after it is refused whole. Absence is always
+ * available and always honest.
  */
 export declare function normalizeHarnessVersion(raw: unknown): string | null;
 /**
@@ -109,9 +146,10 @@ export declare const HARNESS_PROBE_TIMEOUT_MS = 10000;
  * the log (only {@link normalizeHarnessVersion}'s output is), and what needs the
  * raw line is a diagnostic that must be able to read a build stamp a harness
  * prints beside its semver. Hermes prints
- * `Hermes Agent v0.21.3 (2026.9.14) · upstream 913d4098`, which the log's own
- * rule rejects on the non-ASCII separator alone. Capped and stripped of control
- * characters all the same: this is third-party output on its way to a terminal.
+ * `Hermes Agent v0.21.3 (2026.9.14) · upstream 913d4098`, of which the log keeps
+ * only the part before the non-ASCII separator (APRV-419), losing the upstream
+ * commit. Capped and stripped of control characters all the same: this is
+ * third-party output on its way to a terminal.
  */
 export declare const HARNESS_RAW_VERSION_LIMIT = 200;
 /**
@@ -119,38 +157,41 @@ export declare const HARNESS_RAW_VERSION_LIMIT = 200;
  *
  * One line, trimmed, control characters removed, capped. `null` for empty output
  * or a line past the cap. It keeps non-ASCII bytes, which is the whole difference
- * from {@link normalizeHarnessVersion}: a build stamp behind a typographic
+ * from {@link normalizeHarnessVersion}: an upstream commit behind a typographic
  * separator is exactly the fact a version floor has to read, and it is exactly
- * the fact the write boundary will not accept.
- */
-export declare function rawHarnessVersionLine(raw: unknown): string | null;
-/**
- * Run `<binary> --version` once, uncached, and return its raw first line.
+ * the part of the line the write boundary cuts.
  *
- * Every failure is a value rather than an exception, in the manner of
- * {@link spawnGloss}: a missing binary, a non-zero exit and a timeout kill are
- * all reported on the result object, and all of them are simply "no version".
- *
- * The child is STARVED, for the reason the gloss runner is: this is a
- * third-party CLI spawned by a process that may be holding a bot token and a
- * vault passphrase, and it has no use for either. Nothing is declared, because
- * reading a version is not a granted action.
+ * Never the source of a RECORDED value. Removing a control character glues what
+ * followed it onto what preceded it, so text a `\r` hid on a terminal would
+ * reach the log if this line were normalized. The recordable form is read off
+ * the untouched first line instead ({@link installedHarnessVersion}), where the
+ * control character cuts exactly as it does for an event-supplied value (APRV-419).
  */
+export declare function rawHarnessVersionLine(raw: unknown): string | null;
+/** Run `<binary> --version` once, uncached, and return its first line as a diagnostic may print it. */
 export declare function probeHarnessVersionRaw(kind: HarnessKind): string | null;
 /**
  * Run `<binary> --version` once, uncached, and normalize what came back.
  *
- * The recordable form: one line, printable ASCII, capped. Exported for the test
- * that proves the memo below is a memo.
+ * The recordable form: one line, its printable-ASCII prefix, capped, read off
+ * the untouched first line so a control character cuts here as it does on the
+ * event path. Exported for the test that proves the memo below is a memo.
  */
 export declare function probeHarnessVersion(kind: HarnessKind): string | null;
-/** The raw first line of `<binary> --version`, read at most once per process. */
+/**
+ * The first line of `<binary> --version` as a diagnostic may print it (control
+ * characters removed, non-ASCII kept), read at most once per process. For the
+ * version floor and terminal output; never recorded.
+ */
 export declare function installedHarnessVersionRaw(kind: HarnessKind): string | null;
 /**
  * The installed version of `kind`, read at most once per process.
  *
- * This is the only entry point callers should use for a RECORDABLE version.
- * `probeHarnessVersion` is exported for the test that proves the memo is a memo.
+ * This is the only entry point callers should use for a RECORDABLE version. It
+ * normalizes the untouched first line, never {@link installedHarnessVersionRaw}'s
+ * stripped one, so the recorded value follows the one rule in {@link
+ * printableAsciiPrefix} whichever path supplied it. `probeHarnessVersion` is
+ * exported for the test that proves the memo is a memo.
  */
 export declare function installedHarnessVersion(kind: HarnessKind): string | null;
 /** Drop the memo. TEST ONLY: a process reads a version once, by design. */