@mmnto/cli 1.122.0 → 1.123.0

package/dist/commands/legs.d.ts

@@ -0,0 +1,259 @@
+/**
+ * `totem legs deposit` / `totem legs gate` — the two verbs over the
+ * leg-deposit store (mmnto-ai/totem#2698, ruled 2026-09-03;
+ * `doctrine/model-tiering.md` § Review legs).
+ *
+ * `deposit` is the ONLY writer: it resolves the head a falsification leg
+ * actually read, binds the leg's findings file to that sha, and hands the
+ * bytes to core's validate-on-write `saveLegDeposit`. `gate` is a READER — it
+ * never writes, never judges a finding's severity, and never decides policy:
+ * it answers one question for a push, *was this head read by a leg*, and says
+ * exactly how it derived the answer.
+ *
+ * Three properties of the gate are contract, not style:
+ *
+ * 1. **The tier changes only the exit code.** `--advisory` prints the
+ *    BYTE-IDENTICAL lines of every state and exits 0; the strict caller is
+ *    the pre-push hook, which maps 3 and 2 to a block. That is why the
+ *    derivation returns its lines and BOTH codes, and the flag is applied at
+ *    one place at the very end — a second formatting path per tier is how the
+ *    advisory line and the blocking line drift apart.
+ * 2. **Not owed never consults the store.** The predicate is derived from the
+ *    changed-file set alone; a repo whose diff matches no glob must not have
+ *    its deposit directory read, so the "not owed" line is honest about
+ *    having judged globs and nothing else.
+ * 3. **stdout is written SYNCHRONOUSLY before exit.** A piped write is
+ *    asynchronous on macOS, so `process.stdout.write` followed by
+ *    `process.exit` can truncate the very line the `sh` arm is about to echo
+ *    — the `fs.writeSync(1, …)` precedent from the strict pre-commit reader.
+ *
+ * Everything the gate echoes is control-character sanitized. The deposit's own
+ * strings are already refused at the schema boundary (core `artifacts/legs.ts`),
+ * but paths, glob names and corrupt-file reasons come off a filesystem and a
+ * config file, so they are sanitized here too rather than trusted by provenance.
+ *
+ * Per the CLI command-module contract, every VALUE import is dynamic inside
+ * the command bodies (the core barrel pulls LanceDB into `--help` otherwise);
+ * `import type` is erased at build and stays static.
+ */
+import type { LegCoverageQuery, LegGitAdapter } from '@mmnto/totem';
+/**
+ * List what a candidate could have READ: the paths its own branch diff added
+ * relative to `base` (three-dot).
+ *
+ * `-z` is load-bearing, not a style choice (mmnto-ai/totem#2698 fold 4). Under
+ * git's default `core.quotePath=true`, `--name-only` C-QUOTES any path with a
+ * non-ASCII byte, a quote or a backslash — `docs/caf\303\251.md` — while the
+ * owed set comes from `extractChangedFiles`, which is unquoted. The two sets
+ * then never intersect for such a path, and a covering ancestor is rejected
+ * with the false reason "predates every owed change". `-z` emits raw
+ * NUL-separated names and never quotes, so both sides speak one spelling.
+ *
+ * One helper, taking the runner: the gate shells out through `safeExec` and the
+ * covariate through its injected `GitExec`, and a second copy of this argv is
+ * exactly how one of them would drift back to the quoted form.
+ */
+export declare function legReachPaths(run: (args: readonly string[]) => string, base: string, head: string): string[];
+export interface LegsDepositOptions {
+    /** The head the leg READ. Any rev git accepts; defaults to `HEAD`. */
+    sha?: string;
+    /** Path to the leg's findings JSON. */
+    from: string;
+    /** Overwrite an existing deposit for this sha, reporting what was replaced. */
+    replace?: boolean;
+    /** The leg's own instant (ISO-8601). Overrides the file's `readAt`. */
+    readAt?: string;
+}
+/**
+ * `totem legs deposit --sha <ref> --from <file> [--replace] [--read-at <iso>]`
+ *
+ * The writer. Refuses, loudly and before touching the store, every way the
+ * deposit could name the wrong head: a `--sha` that is not a commit, a file
+ * whose own `diffSha` disagrees with it, and an occupied address without
+ * `--replace`. `readAt` is the leg's own instant — when the file carries none
+ * and none is passed, the stamp is `now` and that substitution is PRINTED,
+ * because a deposit's instant is what the resolver breaks ties on.
+ */
+export declare function legsDepositCommand(options: LegsDepositOptions): Promise<void>;
+export interface LegsGateOptions {
+    /**
+     * Print every line of the derived state, but exit 0 for every GATE state
+     * (not owed, evidence, blocked, not derived). A failure BEFORE the
+     * derivation — an unloadable config, an unknown flag — still exits non-zero.
+     */
+    advisory?: boolean;
+}
+/**
+ * There is deliberately no `--head`: the gate judges `HEAD` and nothing else
+ * (mmnto-ai/totem#2698 fold 2, MATERIAL). A caller-chosen head turns a block
+ * into a pass — a deposit written on a sibling branch answers for a commit
+ * this push does not contain — and the hook has no reason to ask about any
+ * head but the one being pushed. Tests inject a head through
+ * {@link LegsGateDeps.resolveHead}, which is a seam, not a public flag.
+ */
+/**
+ * The derivation seam. Everything the gate needs that touches the world —
+ * git, the config's globs, the diff — arrives through this interface, so the
+ * five states are testable against a temp store and a fake git without a
+ * fixture repo per case (core's `LegGitAdapter` precedent).
+ */
+export interface LegsGateDeps {
+    /** The root every printed path is relative to (the config root). */
+    root: string;
+    /** Absolute totem dir — the deposit store lives under it. */
+    totemDirAbs: string;
+    /** The judgment-dense floor this push is judged against. */
+    globs: readonly string[];
+    /** Ancestry seam handed to core's resolver. */
+    git: LegGitAdapter;
+    /** Full 40-hex head sha. Throws when the head cannot be resolved. */
+    resolveHead(): string;
+    /** The push's resolved branch scope. Throws when the diff cannot be resolved. */
+    changedFiles(): Promise<LegsGateScope>;
+}
+/**
+ * The branch scope the gate judges: the unfiltered changed-file set, plus the
+ * base it was resolved against.
+ *
+ * The base is carried because COVERAGE is measured against it
+ * (mmnto-ai/totem#2698 fold 3) — a candidate's reach is `base...<diffSha>`, and
+ * it has to be the SAME base HEAD was resolved against or the two diffs are not
+ * comparable. Absent when the resolution produced no base, which the gate
+ * treats as "coverage is not derivable" rather than guessing one.
+ */
+export interface LegsGateScope {
+    files: readonly string[];
+    base?: string;
+}
+/**
+ * The coverage query for a set of owed paths, or `undefined` when it cannot be
+ * derived (no base). Exported because the covariate resolves through the SAME
+ * inputs as the gate — a field that named a deposit the gate rejects would be
+ * the round reading evidence the push gate does not accept.
+ *
+ * The basis lists one entry per `glob -> file` MATCH, so a file matching three
+ * globs appears three times; the owed set is those files, deduplicated in
+ * basis order.
+ */
+export declare function legsCoverageForBasis(base: string | undefined, basis: readonly {
+    glob: string;
+    file: string;
+}[]): LegCoverageQuery | undefined;
+/** Exit vocabulary: 0 not owed / evidence · 2 could not derive · 3 owed, no deposit. */
+export type LegsGateCode = 0 | 2 | 3;
+export interface LegsGateOutcome {
+    /** The DERIVED state — what the gate concluded, before any tier mapping. */
+    derived: LegsGateCode;
+    /** What the process exits with: `derived`, or 0 under `--advisory`. */
+    status: LegsGateCode;
+    /** stdout lines, in order. Identical for both tiers, by contract. */
+    stdout: string[];
+    /** stderr lines (the corrupt-deposit sensor rows). */
+    stderr: string[];
+}
+/**
+ * Derive the gate's verdict and its lines.
+ *
+ * The tier is applied ONLY to `status`; `stdout` is produced once, so an
+ * advisory run and a strict run of the same state cannot print different text.
+ */
+export declare function runLegsGate(options: LegsGateOptions, deps: LegsGateDeps): Promise<LegsGateOutcome>;
+/**
+ * How a caller wants the branch scope resolved.
+ *
+ * `run` is the git seam (mmnto-ai/totem#2698 fold 5, Q1): the covariate
+ * resolves HEAD and ancestry through an INJECTED runner, and a reach probe that
+ * shelled out to real git regardless left half that seam unhonored — a test
+ * could fake the ancestry half and silently get real git for the other.
+ */
+export interface LegsScopeOptions {
+    /** Suppress this module's `[Legs]` scope lines AND the resolver's own. */
+    suppressScopeNarration?: boolean;
+    /** Git runner; defaults to `safeExec('git', …, { cwd })`. */
+    run?: (args: readonly string[]) => string;
+}
+/**
+ * Resolve the branch scope the floor is judged on — the ONE derivation the gate
+ * and the covariate both use (mmnto-ai/totem#2698 fold 3 item 3), so the
+ * covariate can never name a deposit the gate would reject.
+ *
+ * The push-gate scope (`--branch`): the branch-vs-base diff is what the leg
+ * read, and it is what the push actually proposes. An empty result is not owed
+ * — there is nothing for a leg to read.
+ *
+ * UNFILTERED, deliberately (mmnto-ai/totem#2698 fold 1). The same base/head
+ * resolution runs, but with an EMPTY ignore configuration, so neither
+ * `ignorePatterns` nor `shieldIgnorePatterns` can hide a path from the floor.
+ * Those keys carry INDEX-exclusion semantics that were merged into the
+ * review/lint diff filter for back-compat (mmnto-ai/totem#1746,
+ * mmnto-ai/totem#1748) — letting them narrow this predicate would mean a repo
+ * that excludes `README.md` from its index silently stops owing a leg for its
+ * public copy, which is the claim-without-mechanism shape the floor exists to
+ * close.
+ *
+ * The resolved BASE rides back with the files: coverage is measured against it,
+ * and it must be the same base HEAD was resolved against.
+ */
+export declare function resolveUnfilteredBranchScope(cwd: string, options?: LegsScopeOptions): Promise<LegsGateScope>;
+/**
+ * The judgment-dense floor this repo declares, or the default when it declares
+ * none — the ONE spelling, shared by the gate and both covariate sites.
+ */
+export declare function legsOwedGlobs(config: {
+    hooks?: {
+        legsOwed?: {
+            globs?: readonly string[];
+        };
+    };
+}): Promise<readonly string[]>;
+/**
+ * What a covariate site learned when it asked for coverage inputs: either the
+ * query, or the reason it is not derivable for that site's scope.
+ */
+export interface LegsCoverageResolution {
+    query?: LegCoverageQuery;
+    /** Present iff `query` is absent — the caller discloses it as one Sensor line. */
+    reason?: string;
+}
+/**
+ * Derive the coverage query for a COVARIATE site (mmnto-ai/totem#2698 fold 3,
+ * corrected in fold 4).
+ *
+ * The inputs come from HEAD's branch-vs-base scope ALWAYS — never from the
+ * scope the review itself ran on. The leg field answers "was THIS HEAD read",
+ * so what it owes is a property of HEAD, not of whether the operator happened
+ * to review a staged slice or a dirty tree. Deriving from the review's scope
+ * meant the default `uncommitted` scope resolved ancestry-only and NAMED the
+ * merge-base deposit the gate rejects — the field disagreeing with the gate,
+ * which is the one thing it must never do.
+ *
+ * Both covariate sites route through this one function, and it reuses the
+ * gate's own pieces — the unfiltered branch scope and core's single
+ * `classifyLegsOwed` — so the guarantee is unconditional: the field never names
+ * a deposit the gate would reject. When HEAD has no branch base the answer is
+ * `leg: none` plus one sensor, never a name resolved on ancestry alone.
+ */
+export declare function deriveLegsCoverageForHead(cwd: string, globs: readonly string[], options?: LegsScopeOptions): Promise<LegsCoverageResolution>;
+/**
+ * Build the gate's real-world seam from the repo's config and git.
+ *
+ * Exported so the UNFILTERED-diff contract below is testable against a real
+ * checkout without capturing a process exit: a test resolves these deps in a
+ * fixture repo and asserts what `changedFiles()` actually returns.
+ *
+ * It takes no options: since `--head` was removed (mmnto-ai/totem#2698 fold 2)
+ * nothing about the seam varies with a flag — `--advisory` is applied to the
+ * STATUS, after the derivation, and never to what is derived.
+ */
+export declare function buildLegsGateDeps(): Promise<LegsGateDeps>;
+/**
+ * `totem legs gate [--advisory]`
+ *
+ * The reader the strict pre-push arm calls. Loads the repo's config, builds
+ * the real git and diff seams, derives, writes SYNCHRONOUSLY, exits with the
+ * tier-mapped status. `--advisory` maps every GATE state to 0; a failure
+ * before the derivation (config load, flag parse) still exits non-zero
+ * through the CLI's error boundary.
+ */
+export declare function legsGateCommand(options: LegsGateOptions): Promise<void>;
+//# sourceMappingURL=legs.d.ts.map

package/dist/commands/legs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legs.d.ts","sourceRoot":"","sources":["../../src/commands/legs.ts"],"names":[],"mappings":"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"}