@jawache/flow 0.1.0 → 0.1.2

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

@@ -1,4 +1,4 @@
-import type { Case, CaseWorld, Check, Ctx, ExecResult, LoadedEntry, Moment, Unanswered } from "../language/domain.ts";
+import type { Case, CaseWorld, Check, Ctx, ExecResult, Grammar, 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;
@@ -584,10 +584,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 +649,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 +679,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.
  *
@@ -670,6 +708,23 @@ export declare function depcruiseHits(result: ExecResult): string[];
 export declare const depcruise: (options: Dialect) => Check;
 /** The grammars that need no install. */
 export declare const NATIVE_LANGUAGES: readonly string[];
+/**
+ * WHAT A MISSING GRAMMAR LIBRARY SAYS — one sentence, in one place.
+ *
+ * It is read at two moments that must not disagree: `flow status` says it before anything runs, and
+ * `resolveLang` says it when a rule on that language is reached. Two spellings would be two accounts
+ * of the same fact, and the day one of them was improved the other would quietly become the older,
+ * worse answer — which is the drift this package refuses everywhere else.
+ */
+export declare function missingGrammarText(name: string, libraryPath: string): string;
+/**
+ * Declare the config's grammars, and how to tell whether one is built.
+ *
+ * Called once per config read; the last config read wins, and one declaring none clears the list —
+ * which is what makes `flow test <other-config>` an honest answer rather than one coloured by the
+ * file read before it.
+ */
+export declare function useGrammars(grammars: readonly Grammar[], exists?: (path: string) => boolean): void;
 /** A resolved grammar, or the sentence saying why there is none. */
 type LangResult = {
     readonly ok: true;
@@ -681,14 +736,17 @@ type LangResult = {
 /**
  * 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.
+ * THREE ROUTES, in this order. A tier-0 native is free. A grammar the CONFIG DECLARED is registered
+ * from the library the repo built — this is how a language nobody publishes (astro, vue, svelte)
+ * gets in, and it is tried SECOND, before the package route, because a repo that went to the trouble
+ * of building and declaring one has said which library it means. 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 DECLARED GRAMMAR THAT WILL NOT LOAD IS ITS OWN REFUSAL, naming the library file. The path is a
+ * build artefact, machine-specific and never committed, so "missing" is the ordinary state of a
+ * fresh clone and the message has to say which file and who builds it — not "unknown grammar",
+ * which sends the reader looking for a package that does not exist.
  *
  * 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

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

@@ -89,6 +89,8 @@ export interface BriefEvent {
     readonly moment: BreadcrumbMoment;
     /** touch: the path the tool call is about. A call carrying no path narrows nothing. */
     readonly path?: string | undefined;
+    /** command: the line about to run — what a command note's `on` is matched against. */
+    readonly command?: string | undefined;
     readonly wearing: readonly string[];
     /** How far this session has drifted, in context tokens. The adapter measures it. */
     readonly tokens: number;
@@ -650,6 +652,7 @@ export type RecordedStep = {
     readonly rail: "brief";
     readonly moment: BreadcrumbMoment;
     readonly path?: string | undefined;
+    readonly command?: string | undefined;
     readonly wearing: readonly string[];
     readonly tokens: number;
 }

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, 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

@@ -12,7 +12,7 @@ export type BreadcrumbMoment = (typeof BREADCRUMB_MOMENTS)[number];
 /** Either vocabulary. `turn-end` is the one word in both. */
 export type Moment = GuardrailMoment | BreadcrumbMoment;
 export declare const GUARDRAIL_MOMENTS: readonly GuardrailMoment[];
-export declare const BREADCRUMB_MOMENTS: readonly ["session", "touch", "turn-end"];
+export declare const BREADCRUMB_MOMENTS: readonly ["session", "touch", "command", "turn-end"];
 export declare const write: "write";
 export declare const command: "command";
 export declare const commit: "commit";
@@ -40,6 +40,20 @@ export declare const PATH_MOMENTS: readonly ["write", "delete", "commit", "touch
 export type PathMoment = (typeof PATH_MOMENTS)[number];
 /** Does this moment carry a path for `on` / `ignore` to narrow? */
 export declare function isPathMoment(m: string): m is PathMoment;
+/**
+ * THE SUBJECT A NOTE'S SCOPE IS MATCHED AGAINST — a path at the path moments, and the COMMAND LINE
+ * at `command`, which is the one moment where the two kinds of entry are scoped differently.
+ *
+ * A command GUARDRAIL needs no scope and must not have one: its patterns are its scope, and a rule
+ * that could be narrowed one way and match another is a rule whose halves can disagree in silence.
+ * A command NOTE is the opposite case — it has no patterns at all, so without `.on(…)` it would show
+ * on every shell call in the session, which is the same as showing on none. `.on("npm install*")` is
+ * how it says which commands it is about, matched as a glob over the line about to run.
+ */
+export declare const BRIEF_SCOPE_MOMENTS: readonly ["write", "delete", "commit", "touch", "command"];
+export type BriefScopeMoment = (typeof BRIEF_SCOPE_MOMENTS)[number];
+/** Does a scope narrow anything for this KIND of entry at this moment? */
+export declare function isScopable(kind: EntrySpec["kind"], m: string): boolean;
 /**
  * The host-written record of one session × agent, as a classifier sees it.
  *
@@ -177,6 +191,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.
  *
@@ -358,7 +390,7 @@ type DeadScope = "flow: every moment this entry fires at carries no path, so .on
  * every scope is live. Saying `.on(…)` above `.at(command)` is the same mistake with the words in
  * the other order, and the load's `dead-scope` refusal is what catches it. Both halves, always.
  */
-type Scoping<At extends Moment, Verb> = [Extract<At, PathMoment>] extends [never] ? (dead: DeadScope) => never : Verb;
+type Scoping<At extends Moment, Verb, Scopable extends Moment = PathMoment> = [Extract<At, Scopable>] extends [never] ? (dead: DeadScope) => never : Verb;
 /** Anything a pack may file under an entry name. The one shape `definePack` walks. */
 export interface Sentence<S extends EntrySpec = EntrySpec> {
     readonly spec: S;
@@ -381,8 +413,8 @@ export interface GuardrailSentence<Spoken extends GuardrailKey = never, At exten
 export interface BreadcrumbSentence<Spoken extends BreadcrumbKey = never, At extends BreadcrumbMoment = BreadcrumbMoment> extends Sentence<BreadcrumbSpec> {
     readonly at: Once<Spoken, "at", <M extends BreadcrumbMoment[]>(...moments: M) => BreadcrumbSentence<Spoken | "at", M[number]>>;
     readonly for: Once<Spoken, "for", (...categories: Category[]) => BreadcrumbSentence<Spoken | "for", At>>;
-    readonly on: Once<Spoken, "on", Scoping<At, (...globs: string[]) => BreadcrumbSentence<Spoken | "on", At>>>;
-    readonly ignore: Once<Spoken, "ignore", Scoping<At, (...globs: string[]) => BreadcrumbSentence<Spoken | "ignore", At>>>;
+    readonly on: Once<Spoken, "on", Scoping<At, (...globs: string[]) => BreadcrumbSentence<Spoken | "on", At>, BriefScopeMoment>>;
+    readonly ignore: Once<Spoken, "ignore", Scoping<At, (...globs: string[]) => BreadcrumbSentence<Spoken | "ignore", At>, BriefScopeMoment>>;
     readonly text: Once<Spoken, "text", (text: string) => BreadcrumbSentence<Spoken | "text", At>>;
     readonly file: Once<Spoken, "file", (path: string) => BreadcrumbSentence<Spoken | "file", At>>;
     readonly disabled: Once<Spoken, "disabled", (reason?: string) => BreadcrumbSentence<Spoken | "disabled", At>>;
@@ -495,6 +527,34 @@ export type Binding = PackBinding | OverrideBinding;
 export interface Settings {
     /** Context tokens between re-showings of a breadcrumb. Absent = the engine's own default. */
     readonly driftTokens?: number;
+    /**
+     * Grammars this repo built itself, for `astGrep` rules whose language has no published package.
+     *
+     * ast-grep parses five languages out of the box and resolves anything else as an
+     * `@ast-grep/lang-<name>` package. A grammar that nobody publishes — astro, vue, svelte — has no
+     * third route unless a repo can hand over the tree-sitter library it built, which is what this is.
+     * Declared here rather than on the entry because a grammar is a fact about the MACHINE the guard
+     * runs on, not about any one rule: two rules on the same language must never be able to resolve
+     * it two ways.
+     */
+    readonly grammars?: readonly Grammar[];
+}
+/**
+ * One hand-built tree-sitter grammar, as `registerDynamicLanguage` wants it.
+ *
+ * `libraryPath` is a path to a compiled library (`.so` / `.dylib`), relative to the repo root or
+ * absolute. It is a BUILD ARTEFACT — machine-specific, never committed — so a repo declaring one
+ * carries the recipe that builds it, and the refusal when it is missing names that file.
+ */
+export interface Grammar {
+    /** The name an `astGrep` rule spells as its `language`. */
+    readonly name: string;
+    /** The compiled tree-sitter library, relative to the repo root or absolute. */
+    readonly libraryPath: string;
+    /** The file extensions the grammar is for — ast-grep wants them, and they document the rule's reach. */
+    readonly extensions: readonly string[];
+    /** The symbol inside the library. Defaults to ast-grep's own `tree_sitter_<name>`. */
+    readonly languageSymbol?: string;
 }
 /** A whole guard, as its config file states it: bindings, in the order they were spoken. */
 export interface FlowConfig {
@@ -589,7 +649,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jawache/flow",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Guardrails and breadcrumbs as code — packs you import, a config that typechecks, one adapter per harness.",
   "license": "MIT",
   "repository": {
@@ -48,6 +48,7 @@
     "dependency-cruiser": "^18.1.0"
   },
   "devDependencies": {
+    "@ast-grep/lang-python": "^0.0.6",
     "@types/node": "^24.13.4",
     "@vitest/coverage-v8": "4.1.10",
     "commit-and-tag-version": "^13.1.2",