@jawache/flow 0.1.1 → 0.2.1

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

@@ -33,9 +33,20 @@ export declare const textBan: (options: {
  * (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.
+ *
+ * WITHOUT ITS HEREDOC BODIES (`elideHeredocs`), by default. A heredoc is text fed to a program,
+ * and a python script or a note that names a banned command is not a use of it: matched whole,
+ * `python3 - <<'PY'` scripts were refused for naming a recipe in a string. Only the bodies go —
+ * the newlines the patterns above span are kept — and a body a shell reads stays, because it is
+ * commands.
+ *
+ * `matchHeredocs: true` matches the whole command instead. A rule about what a command is FED —
+ * the text of a commit message given on stdin, `git commit -F - <<'EOF'` — has to see the body,
+ * and would be blind to that message without it.
  */
 export declare const banCommands: (options: {
     ban: readonly string[];
+    matchHeredocs?: boolean;
 }) => Check;
 /**
  * A `banCommands` pattern for: a command that writes permanent prose, with a BACKTICK inside a
@@ -86,6 +97,24 @@ export declare const SUBSTITUTION_MESSAGE: string;
 export declare const protectedPath: (options: {
     existingOnly?: boolean;
 }) => Check;
+/**
+ * Only the listed categories may change a file: a write or a delete by any other actor is refused.
+ *
+ * It reads `ctx.actor` — the categories the acting session wears, recognised from what the host
+ * wrote about it, never from a claim it made — and nothing about the file. A session wearing none
+ * of `writers` is refused whatever it wrote, and one wearing none at all is refused too: "no
+ * category" is not "every category".
+ *
+ * `.for(…)` on an entry says which actors a RULE applies to; this says which actors may WRITE. Both
+ * read the same categories, and they answer different questions — a rule for a checker says what a
+ * checker may not do, this says that everybody but a builder may not write.
+ *
+ * An empty `writers` is refused at load: it would refuse every change by everyone, which is a
+ * frozen worktree, not a rule about who writes it.
+ */
+export declare const oneWriter: (options: {
+    writers: readonly string[];
+}) => Check;
 /**
  * A file must have a required companion on disk — every `src/domain/**` needs its `.test.ts`.
  *
@@ -241,6 +270,44 @@ export declare const changeTogether: (options: {
  * aimed at a directory called HEAD.
  */
 export declare const GIT_VALUE_OPTS: ReadonlySet<string>;
+/** A heredoc's opener: its delimiter, whether `<<-` strips leading tabs, and where the opener ends. */
+export interface HeredocOpen {
+    readonly delim: string;
+    readonly tabs: boolean;
+    readonly end: number;
+}
+/**
+ * The first heredoc opener anywhere in a line, quoted context or not — the one definition of "this
+ * line carries a heredoc". A here-string (`<<<`) is stepped over whole, so its tail is not read as
+ * one.
+ */
+export declare function firstHeredoc(s: string): HeredocOpen | null;
+/**
+ * Where a `$(` closes, honouring quotes, nesting and any heredoc inside it — a body is text, so an
+ * apostrophe or a `)` in it closes nothing. -1 when it never closes.
+ */
+export declare function closeParen(s: string, from: number): number;
+/** Where a double-quoted run closes — a `"` inside a `$(…)` in it does not close it. -1 when it never does. */
+export declare function dquoteEnd(s: string, from: number): number;
+/**
+ * THE COMMAND LINE WITHOUT ITS HEREDOC BODIES — what a command ban matches unless the rule sets
+ * `matchHeredocs`.
+ *
+ * A heredoc is text fed to a program on its standard input: a python script, a file being written,
+ * a note. The words of a banned command inside it are not a use of that command, and matching
+ * them refused `python3 - <<'PY'` scripts for naming a recipe in a string. Every body is removed
+ * (its terminator line stays, so the opener still ends), whether the delimiter is quoted or not,
+ * and wherever the heredoc sits —
+ * inside a `$(…)` or a quoted argument too. EVERYTHING ELSE IS LEFT AS WRITTEN — newlines
+ * included, because the patterns that police a commit message span them.
+ *
+ * One exception keeps a body: a heredoc fed to a SHELL (`bash`, `sh`, `zsh`, `eval`, or a pipeline
+ * into one), whose body is commands, and a banned one in it will run.
+ *
+ * Best-effort, and it errs toward matching: from a word whose quote never closes, the line is
+ * returned as written, so a ban still sees everything it saw before.
+ */
+export declare function elideHeredocs(command: string): 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.
@@ -266,19 +333,6 @@ export interface GitInvocation {
  * 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.
@@ -296,7 +350,10 @@ export declare function heredocBody(command: string): string | null;
  *
  *   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 - <<'EOF' … EOF   (the commit reads stdin)        judged, via the heredoc body
+ *   python3 - <<'PY' … PY; git commit -F msg.txt                    NOT judged — the heredoc is
+ *                                                                  another command's script, and
+ *                                                                  the message is on disk
  *   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
@@ -584,10 +641,24 @@ export interface RequireEdge {
  * 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.
  */
+/**
+ * One layer: the globs that are in it, and — optionally — the globs that are NOT.
+ *
+ * `not` exists because the shape a real architecture wants is "this folder, except these few": the
+ * marketing surface of a site is `src/pages/**` minus the handful of subtrees that are endpoints.
+ * Written as an enumeration of what IS marketing, the fence silently stops covering the next folder
+ * somebody adds — which is the failure this dialect is supposed to prevent, not cause. It compiles
+ * to dependency-cruiser's own `pathNot`, which is the same pair the `only` rule already uses.
+ */
+export interface Layer {
+    readonly path: readonly string[];
+    readonly not?: readonly string[];
+}
 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[]>>;
+    /** Each layer, as globs — a bare list, or `{ path, not }` when it has holes in it. */
+    readonly layers: Readonly<Record<string, readonly string[] | Layer>>;
     /** 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. */
@@ -635,7 +706,12 @@ export declare function entryToMatcher(entry: string): {
     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 globs a layer holds, whichever of the two ways it was written. */
+export declare function layerGlobs(layer: readonly string[] | Layer | undefined): {
+    path: readonly string[];
+    not: readonly string[];
+};
+export declare function layersMatcher(names: readonly string[], layers: Readonly<Record<string, readonly string[] | Layer>>): Matcher;
 /** The whole dialect → a native `{ forbidden, required, options }` config. */
 export declare function compileDialect(rule: Dialect): NativeConfig;
 /**
@@ -660,6 +736,25 @@ export declare function compileDialect(rule: Dialect): NativeConfig;
 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[];
+/**
+ * Every layer entry that is a regex where a glob belongs — the fault `depcruise` refuses to load with.
+ *
+ * MEASURED, NOT IMAGINED: the first repo to convert its guard to flow brought its fence across
+ * verbatim, layers and all, from an engine whose layers WERE regexes. They compiled to
+ * `^\^src/pages/\([^/]!app/…` — a pattern no module path can match — and the fence loaded, reported
+ * armed, walked the graph and found nothing, for as long as it took somebody to plant a probe and
+ * watch the commit sail through. A rule that cannot do its job must refuse to load.
+ */
+export declare function nonGlobLayers(layers: Readonly<Record<string, readonly string[] | Layer>>): string[];
+/**
+ * A layer with holes, named in an `only` allowlist — refused, because the holes would be silent.
+ *
+ * `only` is compiled by INVERTING the allowed layers: everything not in them blocks. The inversion
+ * reads the `path` globs and nothing else, so a layer's `not` would simply not be there — the
+ * allowlist would quietly be wider than the layer it names. Rather than half-apply it, this says so
+ * at load: use plain globs for a layer that an `only` names, or express the exclusion as a `forbid`.
+ */
+export declare function holesInAnOnlyList(opts: Dialect): string[];
 /**
  * The generic import-fence runner.
  *

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

@@ -266,8 +266,16 @@ export declare const FLOW_DIR = ".flow";
 export declare const FLOW_GITIGNORE = "# flow's own state \u2014 telemetry and session marks, never committed.\n*\n";
 /** The log schema this build writes, stamped into every session file's first row. */
 export declare const LOG_VERSION = 1;
-/** Every kind a log row may be. Closed — a reader that meets another word has met corruption. */
-export declare const ROW_KINDS: readonly ["meta", "tool", "breadcrumb", "guardrail", "compaction", "run"];
+/**
+ * Every kind a log row may be. Closed — a reader that meets another word has met corruption.
+ *
+ * `read` and `write` are what went ROUND the tool rows: a file a shell command read by name, and a
+ * file a call changed that the call did not name — a heredoc, a `sed -i`, a script. A `tool` row
+ * says a call happened; these say what it did to the tree, so the coverage and lead numbers count
+ * work done through the shell as well as through Edit. `mismatch` is the host's own list of the
+ * files a command changed disagreeing with flow's diff: a fact to read, never an input to a rule.
+ */
+export declare const ROW_KINDS: readonly ["meta", "tool", "breadcrumb", "guardrail", "compaction", "run", "read", "write", "mismatch"];
 export type RowKind = (typeof ROW_KINDS)[number];
 export declare function flowDir(root: string): string;
 /** A session id becomes a filename, so it is held to a filename's charset. */

package/dist/types/glob.d.ts

@@ -1,4 +1,21 @@
 export declare function escapeRe(s: string): string;
+/**
+ * Is that a REGULAR EXPRESSION where this dialect wants a glob?
+ *
+ * It lives beside `escapeRe` because it is that function read backwards: these are the shapes
+ * `escapeRe` turns into literals, which is how a pattern written as a regex comes to match nothing
+ * at all while reading as a fence. Four of them — a leading `^`, a `(?` group, a `|`, a trailing `$`
+ * — and nothing broader is claimed: this is not a regex detector, it is the list of characters whose
+ * meaning is silently lost here.
+ *
+ * ANY `|` COUNTS, with no carve-out for a backslash before it. The dialect has no escape character:
+ * `\|` is a literal backslash followed by a pipe, and a path with either in it is not a path anyone
+ * has. A carve-out would only ever wave through the thing it was meant to catch.
+ *
+ * It was found the hard way — a repo's fence, brought across from an engine whose layers WERE
+ * regexes, loaded green and refused nothing for a week.
+ */
+export declare function notAGlob(entry: string): boolean;
 /** One piece of a glob. The whole dialect: `**` · `*` · `?` · `{a,b}` · literal text. */
 export type GlobToken = {
     readonly kind: "literal";

package/dist/types/index.d.ts

@@ -1,8 +1,8 @@
 export { guardrail, breadcrumb, type Sentence, type EntrySpec, type GuardrailSpec, type BreadcrumbSpec, type GuardrailSentence, type BreadcrumbSentence, type EntryGroup, type DisabledMark, } from "./language/domain.ts";
 export { definePack, pack, override, defineConfig, type Pack, type PackDefinition, type EntryRef, type RefTarget, type FlowConfig, type Binding, type PackBinding, type OverrideBinding, type ConfigSentence, } from "./language/domain.ts";
-export { defineCheck, type Check, type Ctx, type World, type Verdict, type ExecResult, type TurnAction, type Case, type CaseWorld, type Cases, } from "./language/domain.ts";
+export { defineCheck, withFaults, faultsOf, type Check, type Ctx, type World, type Verdict, type ExecResult, type TurnAction, type Case, type CaseWorld, type Cases, } from "./language/domain.ts";
 export { defineCategory, type Category, type Classifier, type SessionFacts } from "./language/domain.ts";
-export { astGrep, banCommands, canonicalFiles, changeTogether, commitReason, depcruise, execPasses, jsonInvariant, protectedPath, ranSinceEdit, siblingExists, symbolsInSibling, textBan, type CanonOptions, type ChangeGroup, type Dialect, type DiffAdds, type ForbidEdge, type JsonAssert, type RequireEdge, } from "./checks/domain.ts";
+export { astGrep, banCommands, canonicalFiles, changeTogether, commitReason, depcruise, execPasses, jsonInvariant, oneWriter, protectedPath, ranSinceEdit, siblingExists, symbolsInSibling, textBan, type CanonOptions, type ChangeGroup, type Dialect, type Layer, type DiffAdds, type ForbidEdge, type JsonAssert, type RequireEdge, } from "./checks/domain.ts";
 export { substitutionInProse, SUBSTITUTION_MESSAGE } from "./checks/domain.ts";
 export { commitMessage, gitDirPrefix, gitInvocations, givesReason, quoteArg, tokenizeCommand, type GitInvocation, } from "./checks/domain.ts";
 export { spawnedAs, type SpawnRecipe } from "./engine/domain.ts";

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

@@ -141,6 +141,12 @@ export interface Ctx {
     readonly staged?: readonly string[] | undefined;
     /** turn-end: what the actor did this turn, in order. */
     readonly turn?: readonly TurnAction[] | undefined;
+    /**
+     * Every moment: the category names that match the session making this change — the categories
+     * some bound entry names, whose recognizer said yes to the host-written evidence about it. Empty
+     * when it matches none, which is not "every category".
+     */
+    readonly actor: readonly string[];
     exec(cmd: string): Promise<ExecResult>;
     readonly fs: {
         read(path: string): Promise<string>;
@@ -191,6 +197,24 @@ export type World = Pick<Ctx, "exec" | "fs" | "git">;
  * would be called with `ctx` as its receiver and break any world that closes over itself.
  */
 export declare function makeCtx(moment: Moment, facts: Partial<Ctx>, world: World): Ctx;
+/**
+ * Mark a configured check as built with options it cannot work with, and say why.
+ *
+ * WHY IT IS A VALUE AND NOT A THROW: a check factory runs while the config module is evaluating, so
+ * a throw there is a module that will not import, and the reader gets one fault with a stack trace
+ * instead of every fault with its entry named. Marked instead, the load collects it beside the
+ * grammar's own refusals and the engine blocks every gated moment with the same text — which is the
+ * shape every other load failure already has.
+ *
+ * WHY IT EXISTS AT ALL: an option can be well-TYPED and still be nonsense — the class that bit here
+ * was a depcruise layer written as a regex where the dialect takes globs, which compiled to a
+ * pattern matching nothing. The fence loaded, `flow status` called it armed, and it walked no graph
+ * for as long as nobody planted a probe. A rule that cannot do its job must refuse to load, never
+ * report green.
+ */
+export declare function withFaults<C extends Check>(check: C, faults: readonly string[]): C;
+/** What a configured check said is wrong with its own options. Empty for every healthy check. */
+export declare function faultsOf(check: Check | undefined): readonly string[];
 /**
  * Declare a CONFIGURED check: a function that takes options and returns a check.
  *
@@ -245,16 +269,20 @@ export type Case =
 string | {
     readonly command: string;
     readonly world?: CaseWorld;
+    readonly actor?: readonly string[];
 } | {
     readonly path: string;
     readonly content: string;
     readonly world?: CaseWorld;
+    readonly actor?: readonly string[];
 } | {
     readonly staged: readonly string[];
     readonly world?: CaseWorld;
+    readonly actor?: readonly string[];
 } | {
     readonly actions: readonly TurnAction[];
     readonly world?: CaseWorld;
+    readonly actor?: readonly string[];
 };
 /** The cases an entry carries: what must pass it, and what must be blocked by it. */
 export interface Cases {
@@ -520,6 +548,19 @@ export interface Settings {
      * it two ways.
      */
     readonly grammars?: readonly Grammar[];
+    /**
+     * Globs for the IGNORED paths the snapshot records as well. The snapshot is git's view of the
+     * tree — tracked files, and untracked ones git does not ignore — so a shell write to an ignored
+     * file is never seen unless a glob here brings it back. `.env` is the usual one.
+     */
+    readonly snapshotInclude?: readonly string[];
+    /**
+     * What is put back when a rule refuses a write that has already landed: `"refused"` (the default)
+     * writes back only the files a rule refused, `"all"` every file that call changed. While another
+     * agent's call overlaps it, only the refused files are put back whatever this says — that call's
+     * writes can be in the same diff.
+     */
+    readonly revert?: "refused" | "all";
 }
 /**
  * One hand-built tree-sitter grammar, as `registerDynamicLanguage` wants it.
@@ -631,7 +672,7 @@ export interface Overlaid {
  */
 export declare function overlay(base: EntrySpec, spoken: Readonly<Record<string, unknown>>, prior?: Readonly<Record<string, "pack" | "override">>): Overlaid;
 /** The closed vocabulary of refusals. Every load failure is exactly one of these. */
-export declare const REFUSAL_CODES: readonly ["not-a-pack", "missing-parameter", "unknown-entry", "unknown-key", "unknown-moment", "missing-mandatory", "undeclared-category", "no-cases", "duplicate-id", "dead-scope"];
+export declare const REFUSAL_CODES: readonly ["not-a-pack", "missing-parameter", "unknown-entry", "unknown-key", "unknown-moment", "missing-mandatory", "undeclared-category", "no-cases", "duplicate-id", "dead-scope", "bad-check-options"];
 export type RefusalCode = (typeof REFUSAL_CODES)[number];
 /** One reason the config will not load. */
 export interface Refusal {

package/dist/types/packs/docs.d.ts

@@ -5,9 +5,9 @@
  * least possible cognitive load, and the agent wants almost nothing in context. So `docs/` has
  * exactly two doors and everything inside follows its door's rules.
  *
- * @setup A `docs/` folder holding exactly `user/` and `agent/`, each with its own index —
- * `docs/user/index.html` for people and `docs/agent/README.md` as a list of pointers. The two
- * guardrails below refuse anything else at the top of the folder, so a repo with a different shape
+ * @setup A `docs/` folder holding exactly `user/` and `agent/`, each with its own index — an index
+ * file under `docs/user/` for people and `docs/agent/README.md` as a list of pointers. The
+ * guardrail below refuses anything else at the top of the folder, so a repo with a different shape
  * either moves its pages or does not bind this pack.
  */
 export interface Doors {
@@ -45,5 +45,4 @@ export declare const docs: import("../index.ts").Pack<{
      * drawer, and neither audience's rules can be applied to what is in it.
      */
     docsShape: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
-    noMarkdownInUserDocs: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
 }, Doors | undefined>;

package/dist/types/packs/work.d.ts

@@ -17,6 +17,20 @@ export declare const builder: import("../index.ts").Category;
  * a frontmatter list somebody can widen.
  */
 export declare const checker: import("../index.ts").Category;
+/** The rungs that may be named as writers — a checker is the rung that never writes. */
+export type Writer = "builder" | "parent";
+/** What a repo may say about how it runs the lifecycle. Every field is optional. */
+export interface Rungs {
+    /**
+     * The rungs allowed to change files in a worktree, turning on ONE WRITER: a write or a delete by
+     * any other actor is refused — an Edit before it lands, anything else put back after.
+     *
+     * OPTIONAL, and with no list there is no entry at all. One writer is for a worktree several
+     * agents share with one builder in it; in a repo where a helper agent of any other kind is
+     * expected to write, it would refuse that helper's every change, so it is off until a repo asks.
+     */
+    readonly writers?: readonly Writer[];
+}
 /**
  * The WORK LIFECYCLE's rungs: who is acting, and what each rung may do.
  *
@@ -38,12 +52,14 @@ export declare const checker: import("../index.ts").Category;
  * so in a repo that does not run the lifecycle they are five rules that can never fire.
  * @adopt Bind it only in a repo whose tasks are actually run through the lifecycle. The three rung
  * rules are scoped to categories this pack defines, so they judge nobody until a session is
- * classified as a builder or a checker — a human at a keyboard is neither.
+ * classified as a builder or a checker — a human at a keyboard is neither. Name `writers` to let
+ * only those rungs change files in the worktree.
  */
 export declare const work: import("../index.ts").Pack<{
+    builderWrites?: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "write" | "delete">;
     planIsTheParents: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "for" | "description", "command">;
     checkersDoNotWrite: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "for" | "description", "write">;
     ticksAreTheChilds: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "for" | "description", "command">;
     noAgentInboxItems: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
     noShellSubstitutionInProse: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
-}, undefined>;
+}, Rungs | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jawache/flow",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Guardrails and breadcrumbs as code — packs you import, a config that typechecks, one adapter per harness.",
   "license": "MIT",
   "repository": {