@jawache/flow 0.1.0

package/dist/types/checks/domain.d.ts

@@ -0,0 +1,792 @@
+import type { Case, CaseWorld, Check, Ctx, ExecResult, LoadedEntry, Moment, Unanswered } from "../language/domain.ts";
+/** One pattern that matched, and the 1-based line it matched on. */
+export interface PatternHit {
+    readonly pattern: string;
+    readonly line: number;
+}
+/**
+ * Every pattern that matches, per line, in order.
+ *
+ * A pattern is applied per LINE rather than to the whole text, because a hit has to be able to
+ * name one: "matches /TODO/" sends a reader to a file, "line 42: matches /TODO/" sends them to the
+ * place. A single-line subject — a command — simply has one line.
+ */
+export declare function patternHits(text: string, patterns: readonly string[]): PatternHit[];
+/**
+ * Ban a word or shape in a file's text.
+ *
+ * For code shapes prefer `astGrep` — it parses, so it will not match the word inside a string
+ * literal or inside a comment that is talking ABOUT the ban.
+ */
+export declare const textBan: (options: {
+    ban: readonly string[];
+}) => Check;
+/**
+ * Ban a dangerous command before it runs.
+ *
+ * A DETERRENT: the patterns ARE its scope, so matching nothing in a repo is the rule working, not
+ * a rule watching the wrong place.
+ *
+ * MATCHED WHOLE, and that is the one difference from `textBan` above. A command is ONE subject
+ * however many lines it occupies — `git commit -m "subject\n\nCo-Authored-By: …"` is a single
+ * invocation, and the patterns that police it span the newline on purpose. Swept line by line
+ * (which is right for a file, where a hit must be able to name its line) every one of those
+ * patterns matches nothing, silently: the rule loads, counts, and cannot catch the thing it
+ * names.
+ */
+export declare const banCommands: (options: {
+    ban: readonly string[];
+}) => Check;
+/**
+ * A `banCommands` pattern for: a command that writes permanent prose, with a BACKTICK inside a
+ * double-quoted argument.
+ *
+ * Reads as: <one of `heads`> … <an OPEN double quote> … <a backtick>, where the quote-pair walk
+ * skips arguments that are already closed, and both scans refuse to cross a QUOTED heredoc opener
+ * — inside one the shell substitutes nothing, so it is the sanctioned way to carry backticks and
+ * must not be blocked. An unquoted `<<EOF` is deliberately still caught: there, substitution
+ * really does happen. This is the one pattern that has to span a newline, and the reason
+ * `banCommands` matches a command whole rather than line by line.
+ *
+ * A BUILDER over a `heads` list rather than one frozen expression, because the commands that
+ * record prose belong to different packs: `git commit` and `gh pr|issue` are `git`'s, which every
+ * repo binds, and the `work …` verbs are `work`'s, which only a repo running the work lifecycle
+ * binds. One tail, two heads, and neither pack carries a copy of the other's — a second copy of
+ * this expression is how the two would drift while both still read as armed.
+ *
+ * WHY IT IS CORE and not a helper beside the packs: TWO PACKS
+ * SHARE IT, and that is the whole rule the fold settled — anything two packs share is a core
+ * check. A shared file sitting beside the packs is a library with two users and no owner, and this
+ * one proved it by growing four unrelated sections around this pair. Here it sits next to the
+ * check it builds a pattern for, and the door that exports one exports both.
+ */
+export declare function substitutionInProse(heads: readonly string[]): string;
+/**
+ * What a blocked prose-writing command is told, and it is the same sentence whichever pack caught
+ * it: the mechanism, the absence of an undo, the fix, and the one false positive the rule owns.
+ *
+ * ONE constant rather than a message per pack. The sentence never named the verb that was blocked
+ * — it names the shape — so two copies would be two places for the same advice to drift, and the
+ * copy that drifted would still read as correct.
+ */
+export declare const SUBSTITUTION_MESSAGE: string;
+/**
+ * Refuse a hand-edit of a protected path.
+ *
+ * The entry's `.on()` IS the protected set and the engine has already filtered on it, so any file
+ * that reaches this check is protected by definition: matching it is the violation. There is no
+ * second list of paths inside the check: a rule that could be scoped one way and protect another
+ * is a rule whose two halves can disagree in silence.
+ *
+ * `existingOnly` is what an APPEND-ONLY tree needs: a migrations folder, where yesterday's file is
+ * history and may never move while today's is the whole point of the folder. Absent means no
+ * narrowing — every write to a protected path is refused — which is the empty value rather than a
+ * default a reader has to know about.
+ */
+export declare const protectedPath: (options: {
+    existingOnly?: boolean;
+}) => Check;
+/**
+ * A file must have a required companion on disk — every `src/domain/**` needs its `.test.ts`.
+ *
+ * Path shape only: it reads no content, just asks whether the sibling is there. The template fills
+ * `{dir}` `{name}` `{base}` `{path}` from the touched path.
+ */
+export declare const siblingExists: (options: {
+    sibling: string;
+}) => Check;
+/**
+ * The canon a feature folder is judged against.
+ *
+ * `root` and `allow` are REQUIRED: the canon IS the content of the rule, so an entry that does not
+ * state it is an entry nobody can read, and a default would be one repo's canon applied silently
+ * in every other.
+ * `thinking` and `folders` stay optional because absent means "no exemption" and "the folder tier
+ * is not policed" — the empty value in both cases.
+ */
+export interface CanonOptions {
+    /** The tier boundary — everything below it is judged. */
+    readonly root: string;
+    /** The filenames a feature folder may hold. Empty means the filename tier is not policed. */
+    readonly allow: readonly string[];
+    /** The one file that may carry a `.test.<ext>` sibling. Absent means none may. */
+    readonly thinking?: string;
+    /**
+     * The names allowed DIRECTLY under `root` — the folder tier.
+     *
+     * A second allowlist rather than a mode flag, because the two questions are genuinely different
+     * and a repo can want either alone. `docs/` wants only this one (exactly `user/` and `agent/` at
+     * the top, anything below them); a feature tree wants only the filename one. Absent means the
+     * folder tier is not policed, which is what every caller before docs asked for.
+     */
+    readonly folders?: readonly string[];
+}
+/**
+ * What the canon says about one path.
+ *
+ * A DISCRIMINATED reason rather than a boolean, because there are two different violations here
+ * and they earn different sentences. The decision and the wording used to be two functions, each
+ * re-deriving the tier from the path — which meant the message could describe a different fault
+ * from the one that fired, and only a reader comparing the two would ever notice.
+ */
+export type CanonVerdict = {
+    readonly ok: true;
+}
+/** A name directly under `root` that the folder tier does not allow. `found` is that name. */
+ | {
+    readonly ok: false;
+    readonly tier: "folder";
+    readonly found: string;
+}
+/** A filename inside a feature folder that the canon does not allow. */
+ | {
+    readonly ok: false;
+    readonly tier: "filename";
+};
+/**
+ * Judge one path against the canon. The ONE place the tier decision is made.
+ *
+ * The rule. A file directly under `root` is the shared-util tier and may be named anything — the
+ * test and coverage rules already cover it. A file INSIDE a feature folder (`<root>/<feature>/…`)
+ * must be one of `allow`. An invented name (payload · helpers · utils · views · mappers) is the
+ * classic escape hatch: somewhere to stash logic that dodges the domain's test and its coverage
+ * gate. So it is refused, and the fix is to fold that logic into the thinking file or to rename
+ * the talking file after the thing it talks to.
+ *
+ * The extensions are derived from the path rather than configured — a repo that writes .ts and one
+ * that writes .mjs want the same rule, and a second list to keep in step is a second list to get
+ * wrong. It reads no content: this is a claim about NAMES, and reading the file would only invite
+ * the rule to start having opinions about what is in it.
+ */
+export declare function judgeCanonical(path: string, o: CanonOptions): CanonVerdict;
+/** The sentence a verdict earns. It renders what was decided — it never decides anything itself. */
+export declare function canonicalFault(verdict: CanonVerdict, path: string, o: CanonOptions): string;
+/** A feature folder may hold only canonical filenames. */
+export declare const canonicalFiles: (options: CanonOptions) => Check;
+/**
+ * One assertion about a JSON file: a dotted path, and one thing that must hold at it.
+ *
+ * `required` is what tells an absent OPTIONAL path from an absent mandatory one. Without it every
+ * assertion would either have to exist, or would silently pass the day the key was renamed.
+ */
+export interface JsonAssert {
+    /** The dotted path to dig to. Absent (or empty) means the document root. */
+    readonly path?: string;
+    /** The value is an object and EVERY key starts with this string. */
+    readonly keysPrefixedWith?: string;
+    /** The value deep-equals this (compared as JSON). */
+    readonly equals?: unknown;
+    /** The value, stringified, matches this regular expression. */
+    readonly matches?: string;
+    /** The path must exist at all. An absent optional path is skipped silently. */
+    readonly required?: boolean;
+}
+/**
+ * Every assertion that fails over one JSON document.
+ *
+ * Text that will not parse yields NO violations, and that is deliberate rather than lax: this runs
+ * on a would-be file at write time, which is frequently mid-keystroke, and a rule that shouted
+ * "invalid JSON" at every second character would be turned off within a day. A file that really is
+ * broken JSON is a problem the tool that reads it will name, loudly, on its own.
+ */
+export declare function jsonViolations(jsonText: string, assert: readonly JsonAssert[]): string[];
+/** A structured (JSON) file must hold an invariant. */
+export declare const jsonInvariant: (options: {
+    assert: readonly JsonAssert[];
+}) => Check;
+/** Of some exported names, which are never mentioned in the sibling test's text? */
+export declare function unreferenced(names: readonly string[], siblingText: string): string[];
+/**
+ * The names a TypeScript source exports — functions, classes and consts.
+ *
+ * A real parser rather than a regex, because `export const x = …` inside a string or a comment is
+ * exactly the false positive that teaches people to ignore a rule. Parsing is not reaching the
+ * world — a string in, a tree out — which is why the grammar library sits in this layer's import
+ * allowlist beside the HTML parser, and why the import is dynamic: the native binding costs real
+ * milliseconds to load and no other check needs it.
+ */
+export declare function exportedNames(content: string): Promise<string[]>;
+/** Every exported symbol is referenced in its sibling test. */
+export declare const symbolsInSibling: (options: {
+    sibling: string;
+}) => Check;
+/**
+ * The changed set this event is about.
+ *
+ * ONE read, in one place, because three separate checks used to derive it three ways: the commit
+ * gate had it as an event fact, the tool-gate re-shelled for it, and change-together shelled for
+ * it again with its own error handling. It is an event FACT first — the adapter puts the staged
+ * paths on ctx at the commit moment — and a capability call only when the moment carried none,
+ * which is what lets a `.test()` case supply it as plain data.
+ */
+export declare function changedSet(ctx: Ctx): Promise<readonly string[]>;
+/** One "these move together" group: if any `if` glob changed, some `thenAny` glob must have too. */
+export interface ChangeGroup {
+    readonly if: readonly string[];
+    readonly thenAny: readonly string[];
+}
+/** Which groups were triggered without their companion. */
+export declare function lonelyChanges(changed: readonly string[], groups: readonly ChangeGroup[]): string[];
+/** Files that must move in the SAME commit — a schema and its migration, a dep and its lockfile. */
+export declare const changeTogether: (options: {
+    groups: readonly ChangeGroup[];
+}) => Check;
+/**
+ * git's own options that TAKE A VALUE, and therefore swallow the token after them.
+ *
+ * They have to be known by name to find where the subcommand starts: `git -C ~/repo commit -m x`
+ * puts two tokens between `git` and `commit`, and a scan that took the first argument as the
+ * subcommand saw `-C` and walked away. Knowing them by name is also what keeps `git commit -C
+ * HEAD` — the reuse-this-message flag, nothing to do with directories — from reading as a command
+ * aimed at a directory called HEAD.
+ */
+export declare const GIT_VALUE_OPTS: ReadonlySet<string>;
+/**
+ * A shell-ish tokeniser: quotes respected (so a commit message mentioning `git commit` is not a
+ * second command), operators emitted as their own tokens.
+ *
+ * Null on unparseable input — an unclosed quote — and null means "cannot tell", which every caller
+ * must read as "do not judge". A guard that guesses at a line it cannot parse is worse than one
+ * that stands aside.
+ */
+export declare function tokenizeCommand(command: string): string[] | null;
+/** One `git …` in a command line, split where git stops and its subcommand starts. */
+export interface GitInvocation {
+    /** git's OWN options, before the subcommand — where `-C` counts and only there. */
+    readonly globals: readonly string[];
+    /** The subcommand word (`commit`, `status`), or null when the invocation carries none. */
+    readonly subcommand: string | null;
+    /** Everything after the subcommand — its own flags and arguments. */
+    readonly args: readonly string[];
+}
+/**
+ * Every git invocation in a command line, in order. Null when the line cannot be parsed at all.
+ *
+ * A token only starts an invocation at a COMMAND position — the start of the line or just after an
+ * operator — so a `git` inside a quoted message or as an argument to something else is not one.
+ */
+export declare function gitInvocations(command: string): GitInvocation[] | null;
+/**
+ * The body of the first heredoc in the raw command, or null.
+ *
+ * `git commit -F -` reads its message on stdin, and a QUOTED heredoc is the safe way to write one
+ * containing backticks — a form this codebase's own rules push commits toward. The argument scan
+ * cannot see it: there is no `-m` token, so a message written that way goes unjudged, and every
+ * rule that reads a commit message is inert on it.
+ *
+ * Deliberately last-resort and deliberately dumb — it runs only when no inline message was found,
+ * and reads the FIRST heredoc, because a commit command carrying two is not a shape anyone writes
+ * and guessing between them would be worse than the gap.
+ */
+export declare function heredocBody(command: string): string | null;
+/**
+ * The message a `git commit` in this command line carries, or null when there is no judgeable
+ * commit in it at all. Null is the "not our business" answer and every caller passes on it.
+ *
+ * EVERY `-m` IS READ, AND THEY JOIN AS PARAGRAPHS. This returned the FIRST one and stopped, which
+ * made `git commit -m "<subject>" -m "<body>"` — git's own two-paragraph form, and the one an agent
+ * reaches for when the reason will not fit in a subject — a commit whose body was never read. The
+ * consequence was not a missed block but the worse direction: a commit that HAD recorded its reason
+ * in the second `-m` was refused, on the one rail whose whole job is to be obeyed.
+ *
+ * The separator is a BLANK line because that is what git writes. Verified rather than assumed:
+ * `git commit -m a -m b -m c` then `git log --format=%B | od -c` shows `a\n\nb\n\nc\n\n`.
+ *
+ * The forms it sees, settled from the two scripts this absorbed rather than invented:
+ *
+ *   git commit -m MSG · -mMSG · --message MSG · --message=MSG      judged
+ *   git commit -m SUBJECT -m BODY   (repeated, any mix of forms)   judged, joined as git joins them
+ *   git commit -F - <<'EOF' … EOF   (any heredoc on the line)      judged, via the heredoc body
+ *   git commit -F path/to/file                                     NOT judged — the message is on
+ *                                                                  disk, and reading it is a read
+ *                                                                  of the world this layer does not
+ *                                                                  do
+ *   git commit            (an editor commit, no message anywhere)  NOT judged — there is nothing to
+ *                                                                  read before the editor opens
+ *
+ * The boundary is on the record: this rail polices AGENT-typed commits, which are its audience. A
+ * human committing from an editor is not its subject and never was.
+ */
+export declare function commitMessage(command: string): string | null;
+/** One shell argument, single-quoted so nothing in it can be expanded or re-parsed. */
+export declare function quoteArg(value: string): string;
+/**
+ * WHICH WORKING TREE THIS COMMAND IS ABOUT, as a `-C` prefix to copy onto every read — or "".
+ *
+ * It is COPIED rather than resolved. Resolving it to an absolute root needs a root and a cwd to
+ * point at one, and a check has neither: inventing a `root` on ctx would put a filesystem fact into
+ * a contract whose whole promise is that there is no filesystem in it. Copying the tokens through
+ * means the shell resolves them exactly as git would have, relative to wherever `ctx.exec` runs —
+ * which is the repo.
+ *
+ * TWO WAYS A COMMAND LEAVES THIS REPO, and until F3 only one of them was read.
+ *
+ *   · `git -C <path> …`   — git's own option.
+ *   · `cd <path> && git …` — the shell's, and the one a person actually types.
+ *
+ * The second was found the way the first was: live, by a guard allowing what it existed to refuse.
+ * The F3 builder ran `git checkout <path>` from a session rooted in another worktree, and every
+ * git read the check made answered about the session's tree, where the path did not exist — so the
+ * discard was judged against a repo it was never aimed at, found nothing to lose, and went through.
+ * A rule that reads the wrong tree does not fail loudly; it passes quietly, which is the whole
+ * failure this package is about.
+ *
+ * BOTH ARE EMITTED, in the order the shell would apply them, because git chains multiple `-C`
+ * options exactly as a shell chains directory changes: `cd /a && git -C b status` runs in `/a/b`,
+ * and `-C '/a' -C 'b'` says precisely that. Nothing has to decide which of the two wins.
+ *
+ * ONLY A LEADING `cd`, and only when an operator follows its path. A `cd` in the middle of a chain
+ * can be preceded by another that already moved, and a command line that walks two trees is beyond
+ * what one answer can honestly describe — the same reason the FIRST git invocation decides below.
+ *
+ * A path the SHELL would have expanded — `~`, a variable — is quoted here and so reaches git
+ * literally, which makes the read fail rather than lie. Every caller treats a failed read as "not
+ * a repo, git owns that error" and passes: a false negative, which is this pack's stated trade.
+ */
+export declare function gitDirPrefix(command: string): string;
+/**
+ * Does the message carry the token, on a LINE OF ITS OWN?
+ *
+ * A line, not a mention. The line is what makes the reason findable later — a reviewer reads these
+ * at every phase boundary — and a token buried mid-sentence ("reverted the new-dep: thing") is both
+ * unreadable to them and a free pass to anyone who types the word by accident. The two scripts this
+ * absorbed matched the token anywhere; this is the one place the rebuild is deliberately stricter,
+ * and the hit says so in as many words.
+ *
+ * The token is regex-ESCAPED. Both absorbed scripts interpolated it raw, so a token carrying `.` or
+ * `+` quietly matched more than it said.
+ */
+export declare function givesReason(message: string, token: string): boolean;
+/** What the working tree is about to carry, split by whether each path is new to the repo. */
+export interface WorkingState {
+    /** Everything that moved — tracked edits, staged adds, and untracked files. */
+    readonly changed: readonly string[];
+    /** The subset that is NEW here: a staged add, or untracked. */
+    readonly added: readonly string[];
+}
+/**
+ * One file whose DIFF is read for names that owe a reason, and the shape of the third condition.
+ *
+ * The two conditions above it ask about PATHS — a file changed, a file is new — and there is a
+ * third question a guard keeps wanting to ask that neither can reach: not "did this file change"
+ * but "what did this commit ADD INSIDE it". A dispatch surface is the case that forced it: every
+ * commit to `cli/work.ts` changes the file, so a path condition there asks for a sentence about
+ * every edit and is turned off within a week; what actually owes one is a NEW VERB, and a verb is
+ * a name on an added line.
+ *
+ * WHY IT REPLACED A CHECK OF ITS OWN. This arrived as `newCommandNeedsCaller` in the shared file
+ * beside the packs, and it was `commitReason` with one condition missing and everything else
+ * rewritten: its own commit detection, its own message parse, its own token read, its own
+ * one-sentence refusal. No pack bound it — two house packs in two repos did — so it was a shipped
+ * check with no shipped user, carrying a second copy of a mechanism that already existed. As a
+ * condition it inherits all of it, and the `known` list stays where it always had to be: on the
+ * binding, because which names are already there is a project's own fact.
+ */
+export interface DiffAdds {
+    /** The one file whose `git diff HEAD -- <file>` is read. Nothing else in the commit is looked at. */
+    readonly file: string;
+    /**
+     * Regex sources, each with exactly ONE capture group — the name a hit is reported by.
+     *
+     * Several, because one surface registers a name several ways: a `case "x":` in a dispatch
+     * switch, a `command === "x"`, a `sub === "x"` in a subcommand router. Two of those three went
+     * unwatched for a year under a check that hard-coded them, which is the argument for the list
+     * being a parameter a reader of the binding can see rather than a constant inside a function.
+     */
+    readonly patterns: readonly string[];
+    /**
+     * Names already on the surface: matched, and ignored.
+     *
+     * This is what makes it a RATCHET rather than a rule about editing the file at all. Renaming,
+     * moving or reformatting an existing name is silent by design — a rule that fired on every
+     * dispatch tidy is a rule someone turns off — and a stale list is the same silent failure the
+     * ratchet exists to catch, which is why it is stated at the binding and never inside the check.
+     */
+    readonly known?: readonly string[] | undefined;
+}
+/**
+ * The names one file's diff ADDED and did not already know.
+ *
+ * Added lines only: removals and context are ignored, so a rename shows the new name and nothing
+ * else, and a reformat shows nothing. `+++` is skipped — it is the header naming the file, not a
+ * line of the file.
+ *
+ * A pattern with no capture group contributes nothing rather than throwing: the binding is
+ * TypeScript and a missing group is a mistake, but the moment this runs is a commit gate, and a
+ * gate that crashes on a bad pattern refuses every commit in the repo until someone reads a stack
+ * trace.
+ */
+export declare function addedNames(diff: string, patterns: readonly string[], known?: readonly string[]): string[];
+export interface ReasonInput {
+    /** The commit message, as the command line carries it. */
+    readonly message: string;
+    /**
+     * What the working tree has to say — index and worktree, tracked and untracked.
+     *
+     * Deliberately the generous reading: a commit is usually typed straight after the staging,
+     * `git commit -a` sweeps tracked worktree edits in, and the cost of asking for a sentence that
+     * was not strictly owed is a sentence, while the cost of missing one is the record this rule
+     * exists to keep.
+     */
+    readonly state: WorkingState;
+    /** Paths that owe a reason when they change at all. */
+    readonly whenChanged?: readonly string[] | undefined;
+    /** Paths that owe a reason only when they are NEW. */
+    readonly whenAdded?: readonly string[] | undefined;
+    /** Paths that never owe one, whichever condition matched — a test sibling, typically. */
+    readonly except?: readonly string[] | undefined;
+    /**
+     * What the third condition found: names added inside a watched file, each with the file it came
+     * from. Already filtered against that file's `known` list by `addedNames` — reading the diff is
+     * IO and belongs to the check, and what is left here is the same pure judgement as the other two.
+     */
+    readonly namesAdded?: readonly {
+        readonly name: string;
+        readonly file: string;
+    }[] | undefined;
+    /** The key the message must carry on a line of its own. */
+    readonly token: string;
+}
+/**
+ * The findings for one commit. Empty means either nothing this rule watches moved, or the reason is
+ * there.
+ *
+ * ONE hit, naming everything that asked and why it asked — `(new)`, `(changed)`, or `(added in
+ * <file>)` for a name the third condition found inside a diff. A message that names four things
+ * when one is the reason is a message nobody reads twice, so all three conditions report together
+ * in one sentence rather than one hit each.
+ *
+ * WHAT IT BLOCKS is the UNEXPLAINED act, never the act. Adding a dependency is fine; adding one
+ * with nothing written down is not, because the one thing a diff can never show is which
+ * alternatives were weighed.
+ */
+export declare function reasonHits(o: ReasonInput): string[];
+/**
+ * This commit needs a reason recorded, and here is whether it gave one.
+ *
+ * WHAT THIS REPLACES. THREE hand-rolled checks asked the same question about different nouns — a
+ * commit adding a dependency, a commit adding a file to a pure core, and a commit adding a verb to
+ * a dispatch surface — each carrying its own git-commit detection, its own read of what moved, its
+ * own message parse and its own refusal sentence. One check, three conditions and a token: that is
+ * the whole mechanism now, and it is stated on the entry where a reader meets it.
+ *
+ * THE THIRD CONDITION is `diffAdds`, and it is the one that is not about paths: see `DiffAdds`. It
+ * came in from `newCommandNeedsCaller`, a shipped check no pack ever bound — two house packs in two
+ * repos did — which on inspection was this check with one condition missing and everything else
+ * written a second time.
+ *
+ * AT WHICH RAIL, and the boundary that comes with it: the COMMAND moment — the Bash rail, before
+ * the command runs, which is where an agent's commit can still be stopped and rewritten. git's own
+ * commit-msg hook (which would also catch a human committing from an editor) was considered and
+ * shelved on the record: the agent is the audience.
+ *
+ * THREE COMMANDS, AND NOT `git status`. The old script read `git status --porcelain=v1` and carried
+ * a fixed-width parser for the answer. That parser reads the world's own format and went with the
+ * adapter; what is left here asks three questions whose answers need no format knowledge at all —
+ * each one is a list of paths, one per line. It is also strictly better: the porcelain parser had a
+ * war story about eating the first character of a path, and there is now no column to slice.
+ *
+ * …AND IT ASKS THEM ONLY WHEN A PATH CONDITION IS BOUND. A binding that names `diffAdds` alone —
+ * the verb ratchets in both house packs do — reads one diff and nothing else. This is not a
+ * micro-optimisation: every one of these commands is a question a `.test()` case has to answer, so
+ * asking three that cannot change the verdict makes every case for a diff-adds entry carry three
+ * lines of git output that mean nothing, and a case full of noise is a case nobody re-reads.
+ *
+ * Fails safe on every read: not a git repo, or git unavailable, and the check stands aside rather
+ * than trapping a commit it cannot judge.
+ */
+export declare const commitReason: (options: {
+    whenChanged?: readonly string[];
+    whenAdded?: readonly string[];
+    except?: readonly string[];
+    diffAdds?: readonly DiffAdds[];
+    token: string;
+}) => Check;
+/**
+ * "You changed X this turn but never ran Y afterwards" — the turn-end rule.
+ *
+ * The actions arrive as harness-neutral facts on ctx, which is what makes this rule drivable by a
+ * case and reachable by a replay: a rule that opened the transcript and parsed it would be reading
+ * the world three times inside a check. Which tool names count as an edit is the adapter's
+ * knowledge and stays there.
+ *
+ * Stands aside when the moment carried no turn facts at all: there is nothing to judge, and a rule
+ * that blocked on the absence of evidence would block every turn on a harness that supplies none.
+ */
+export declare const ranSinceEdit: (options: {
+    edited: readonly string[];
+    mustRun: string;
+}) => Check;
+/**
+ * Should a scoped gate skip — is its area untouched?
+ *
+ * True only when `changed` globs are given AND none of the changed files match, so a file-scoped
+ * gate (a type-checker for `site/**`) stays quiet on commits that do not touch its area. No globs,
+ * or nothing changed to judge → run it. Fail-safe: never silently skip a gate we cannot scope.
+ */
+export declare function skipForChanged(files: readonly string[], changed: readonly string[] | undefined): boolean;
+/**
+ * The lines worth showing FIRST when a tool fails — the errors, not the success chatter.
+ *
+ * Prefer lines that look like a failure; fall back to the tail. Capped, so a blocked commit stays
+ * terse: quiet on pass, and on failure the error is up top rather than buried under a progress log.
+ */
+export declare function failureExcerpt(output: string, cap?: number): string;
+/**
+ * Run a whole-project tool and block on its failure — the one tool-delegated check.
+ *
+ * Some checks need the whole tree in a consistent state (a transitive import boundary, coverage,
+ * the type graph) and cannot run per keystroke, so this belongs at commit or turn-end.
+ *
+ * IT IS HANDED THE CHANGED SET. A gate spawned with empty argv makes a repo's own script re-scan
+ * the whole tree and leaves it unable to name the file that broke it. Here the changed set is an
+ * event fact: it scopes the gate (`changed`), and
+ * `{files}` in the run string expands to the files themselves, shell-quoted. A run string naming
+ * `{files}` with nothing changed does not run at all, because a tool handed an empty file list
+ * usually reads that as "do everything".
+ */
+export declare const execPasses: (options: {
+    run: string;
+    changed?: readonly string[];
+}) => Check;
+export type Matcher = Record<string, unknown>;
+export interface NativeRule {
+    name: string;
+    severity: string;
+    comment?: string;
+    from?: Matcher;
+    to?: Matcher;
+    module?: Matcher;
+}
+export interface NativeConfig {
+    forbidden: NativeRule[];
+    required: NativeRule[];
+    options: Record<string, unknown>;
+}
+export interface ForbidEdge {
+    readonly from?: string;
+    readonly to?: string;
+    readonly transitive?: boolean;
+    readonly why?: string;
+    /** A feature importing a DIFFERENT feature, sideways — named by the layer it applies within. */
+    readonly cyclesBetween?: string;
+}
+export interface RequireEdge {
+    readonly in: string;
+    readonly import: string;
+    readonly why?: string;
+}
+/**
+ * The dialect an entry writes its fences in.
+ *
+ * `layers` names sets of path globs, npm packages or node builtins; everything else declares a
+ * relationship between them. It exists because dependency-cruiser's native schema is a regex
+ * language, and a fence written in regexes is a fence nobody re-reads — the compiled literals of
+ * one such config were dead for four days while the guard's own status reported it healthy.
+ */
+export interface Dialect {
+    /** What to cruise. A GLOB, because a bare directory makes depcruise cruise zero modules. */
+    readonly scan: string;
+    readonly layers: Readonly<Record<string, readonly string[]>>;
+    /** Fail-closed allowlist: a layer may reach ONLY these layers. */
+    readonly only?: Readonly<Record<string, readonly string[]>>;
+    /** Forbidden edges, each carrying the `why` its violation prints. */
+    readonly forbid?: readonly (ForbidEdge | "circular" | "orphans")[];
+    /** An inverted fence: modules in a path MUST import a target. */
+    readonly require?: readonly RequireEdge[];
+    /** Carve-outs — `type-only` above all, since a type import is erased at compile time. */
+    readonly except?: readonly string[];
+    /** Informational rules that never block. `sdp` = the Stable Dependencies Principle. */
+    readonly warn?: readonly string[];
+    /** dependency-cruiser's own options, passed through. */
+    readonly options?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A path glob → a module-path regex for dependency-cruiser (posix module paths).
+ *
+ * It emits from ../glob.ts's tokens, and that is the whole point: this used to be a SECOND glob
+ * translator, and it did not speak the whole dialect. It escaped `{` and `}` into literals, so
+ * `src/**` + `/*.{ts,tsx}` — an ordinary layer glob — compiled to a fence that matched nothing,
+ * silently, behind a green tick. One parser now, and a construct either has a token every emitter
+ * maps or it is not in the dialect at all.
+ *
+ * The ONE thing this emitter does differently, and why it is an anchor rule rather than a dialect:
+ * a TRAILING `**` means "everything under here", so the prefix is emitted and the end is left
+ * unanchored. dependency-cruiser matches module paths unanchored at the tail, and every layer in
+ * every repo already written against that behaviour must keep meaning what it meant.
+ */
+export declare function globToRe(glob: string): string;
+/**
+ * A layer entry → a module-path regex or a marker. `node:*` → the builtin marker; a bare name with
+ * no slash, no star and no DOT → an npm package under node_modules; anything else → a path glob.
+ *
+ * THE DOT IS WHAT TELLS A ROOT FILE FROM A PACKAGE, and it is a fix rather than a nicety. Read as a
+ * package name, an entry for a file at the repo root — `glob.ts`, `index.ts` — compiled to a matcher
+ * for `node_modules/glob.ts`, so the layer covered nothing at all while `flow status` reported the
+ * fence armed. It bit twice in this package alone, and only the commit gate caught either.
+ *
+ * The mirror case is the cost, and it has a spelling already: an npm package whose NAME carries a
+ * dot (`socket.io`) now reads as a file, and is named the way a SCOPED package has always had to be
+ * named here — as a path under node_modules, behind a leading globstar. One escape, already in use,
+ * rather than a second convention.
+ */
+export declare function entryToMatcher(entry: string): {
+    core?: true;
+    path?: string;
+};
+/** Layer names → a depcruise matcher fragment. `path` is an OR-list; builtins become a type. */
+export declare function layersMatcher(names: readonly string[], layers: Readonly<Record<string, readonly string[]>>): Matcher;
+/** The whole dialect → a native `{ forbidden, required, options }` config. */
+export declare function compileDialect(rule: Dialect): NativeConfig;
+/**
+ * The one command the depcruise check runs.
+ *
+ * A separate function because it is the whole of what this check DOES, and a case that stubs the
+ * tool has to be able to see it. Three facts about its shape, each load-bearing:
+ *
+ *   The config travels in a QUOTED heredoc. dependency-cruiser takes its rules from a file and
+ *   nothing else, and a check may not write one — so the command writes it, into a temp dir it
+ *   removes afterwards. A quoted heredoc is literal: no expansion, no quoting hazard, and the one
+ *   way it could break (a body line equal to the delimiter) cannot happen, because `JSON.stringify`
+ *   with no indent emits exactly one line.
+ *
+ *   `npx --no-install`. dependency-cruiser is one of flow's own dependencies, so installing flow
+ *   installs it; `--no-install` means the command resolves the local copy or fails loudly, and
+ *   never silently downloads a different version in the middle of a commit.
+ *
+ *   The exit code is the TOOL's. `rm -rf` on the temp dir must not swallow a non-zero exit, which
+ *   is what the explicit `rc` capture is for.
+ */
+export declare function depcruiseCommand(dialect: Dialect): string;
+/** The tool's JSON report → one hit per violation, each naming the fence and its `why`. */
+export declare function depcruiseHits(result: ExecResult): string[];
+/**
+ * The generic import-fence runner.
+ *
+ * A whole-graph check: bind it at commit or turn-end, never per keystroke. It orchestrates and
+ * never reimplements — the graph walk is dependency-cruiser's job, and the dialect above exists
+ * only so the fences are readable by the person who has to change them.
+ */
+export declare const depcruise: (options: Dialect) => Check;
+/** The grammars that need no install. */
+export declare const NATIVE_LANGUAGES: readonly string[];
+/** A resolved grammar, or the sentence saying why there is none. */
+type LangResult = {
+    readonly ok: true;
+    readonly lang: unknown;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+/**
+ * Resolve a grammar name to something `parse()` accepts.
+ *
+ * TWO ROUTES. A tier-0 native is free. A published
+ * `@ast-grep/lang-<name>` package (sql, python, go, rust…) is registered on first use — its
+ * compiled binary lives in node_modules, and `registerDynamicLanguage` is safe to call per grammar.
+ *
+ * A THIRD ROUTE is deliberately absent: a hand-built grammar declared in an `sgconfig.yml` under a
+ * rule library. flow has no library, and resolving one would mean reading a YAML file from a path
+ * this layer may not touch. It can arrive the day someone needs it, as a parameter naming a built
+ * `.so`, which would be a decision rather than a leftover.
+ *
+ * An unknown name is a REFUSAL VALUE, and it never falls through to Tsx. The check turns it into a
+ * block, which is the fail-loud doctrine at its narrowest and most useful: a silent fall-through is
+ * how a rule ends up parsing the wrong grammar, matching nothing, and reporting green forever.
+ */
+export declare function resolveLang(name: string): Promise<LangResult>;
+/** Every match of an ast-grep rule in some source, as `line: text` — or why there are none. */
+export declare function astGrepHits(content: string, rule: unknown, language: string): Promise<{
+    readonly ok: true;
+    readonly hits: string[];
+} | {
+    readonly ok: false;
+    readonly detail: string;
+}>;
+/**
+ * Ban or require a code shape.
+ *
+ * ast-grep is a Rust tool with a native Node binding, so the would-be file is handed over AS A
+ * STRING and the matches come back — no subprocess, no temp file — which is what lets a structural
+ * rule run pre-emptively on every edit as well as at commit.
+ *
+ * `language` is mandatory. A default here is a private fallback the entry cannot show — and the
+ * wrong parser mis-parses a file and then matches nothing, silently, which is the failure this
+ * package exists to delete.
+ */
+export declare const astGrep: (options: {
+    rule: unknown;
+    language: string;
+}) => Check;
+/** The four dialects a case can be written in — one per kind of event fact. */
+export type CaseDialect = "command" | "write" | "commit" | "turn-end";
+/**
+ * Read a case once: which dialect it speaks, the event facts it carries, and its recorded world.
+ *
+ * ONE ladder over the union, and it is the only one. There were three — this, a `caseMoment` that
+ * asked the same questions to answer half of it, and a `momentSpeaks` that hard-coded the same
+ * pairing a fourth time — so adding a fifth case shape meant finding three places, and missing one
+ * of them would have produced a case that ran at the wrong moment rather than an error.
+ */
+export declare function readCase(c: Case): {
+    readonly dialect: CaseDialect;
+    readonly facts: Partial<Ctx>;
+    readonly world: CaseWorld;
+};
+/** Which moment's dialect a case speaks. */
+export declare function caseMoment(c: Case): Moment;
+/**
+ * Build the ctx one case becomes, at one moment.
+ *
+ * BOTH halves are the language layer's, and deliberately the same two calls the live engine makes:
+ * `cannedWorld` turns what the case wrote down into the three capabilities, and `makeCtx` assembles
+ * the ctx from those and the event's facts. A case is a recorded WORLD handed to one assembler, not
+ * a second kind of ctx — the moment either of those is written twice, a green case stops being
+ * evidence about the live rail, which is the whole value of cases existing.
+ */
+export declare function cannedCtx(moment: Moment, c: Case, unanswered: Unanswered[]): Ctx;
+/**
+ * Every ctx one case becomes for one entry — one, or one per staged file it is scoped to.
+ *
+ * The plural is the whole of the fan-out fix, and the world is built ONCE and shared across the
+ * subjects: a case records one world, and a per-file rule reading it four times must see the same
+ * four answers the live gate would.
+ */
+export declare function caseCtxs(entry: LoadedEntry, moment: Moment, c: Case, unanswered: Unanswered[]): Promise<Ctx[]>;
+/** How one case came out. */
+export interface CaseResult {
+    readonly entry: string;
+    readonly expect: "pass" | "block";
+    /** The case's index within its own list — what `flow test` prints to point at one. */
+    readonly index: number;
+    readonly ok: boolean;
+    /** Empty when it went as declared; otherwise the one sentence saying what happened instead. */
+    readonly detail: string;
+}
+/**
+ * One case, driven.
+ *
+ * Three ways it fails besides the obvious one, and each was a real hole:
+ *
+ *   The case speaks a dialect the entry has no rail for. A write rule tested with a command string
+ *   proves nothing about the rule and looks exactly like proof.
+ *
+ *   The check throws. A crashing check is a failing check everywhere in flow; here it is the case's
+ *   failure, named, which is the earliest anyone could have found out.
+ *
+ *   The check reached the world and the case did not answer. Left alone, that case would pass on a
+ *   fiction — the canned world's silence read as a clean exit or an empty file.
+ */
+export declare function runCase(entry: LoadedEntry, check: Check, c: Case, expect: "pass" | "block", index: number): Promise<CaseResult>;
+/** The sentence an unanswered reach earns — it names what to add to the case. */
+export declare function unansweredText(missing: readonly Unanswered[]): string;
+/**
+ * Every bound entry's cases, driven — what `flow test` is.
+ *
+ * Disabled entries are skipped: they are listed with their reason and never run, so asking them to
+ * prove anything is how an opt-out becomes cheaper to delete than to explain. Breadcrumbs carry no
+ * check and have nothing to prove. Everything else must have cases at all, which the load already
+ * refused it without.
+ */
+export declare function runCases(entries: readonly LoadedEntry[]): Promise<CaseResult[]>;
+export {};