@jawache/flow 0.1.0 → 0.1.1

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.
  *
@@ -358,7 +372,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 +395,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 +509,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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jawache/flow",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",