trail-code 0.0.0-stage → 0.28.0-semantic.3

package/dist/graph/queries/gleam.scm

@@ -0,0 +1,51 @@
+; Gleam tags for graft's generic breadth tier. Gleam v1 syntax: the pre-1.0
+; `external fn` / `external type` declarations are gone, replaced by an
+; `@external` attribute that parses as a sibling `attribute` node beside an
+; ordinary `function` — so the rules below already cover it.
+;
+; Qualified calls (`list.map(…)`) are deliberately NOT captured here. The
+; grammar gives only the bare label (`map`), and since EVERY stdlib call in
+; Gleam is spelled that way, a bare-name edge collides with in-repo names
+; constantly. generic.ts's Gleam pass re-reads those calls alongside the file's
+; import table, where the qualifier can be tied to the module it names.
+
+(function name: (identifier) @name) @definition.function
+
+(constant name: (identifier) @name) @definition.constant
+
+(type_definition
+  (type_name
+    name: (type_identifier) @name)) @definition.type
+
+(type_alias
+  (type_name
+    name: (type_identifier) @name)) @definition.type
+
+; A data constructor IS a function in Gleam — `Busy(since: 0)` applies it and
+; `list.map(xs, Some)` passes it as a value. Capturing it keeps a custom type's
+; variants findable by name and gives construction sites something to point at.
+(data_constructor
+  name: (constructor_name) @name) @definition.function
+
+(function_call
+  function: (identifier) @name) @reference.call
+
+; Construction, record update and destructuring all name a constructor. The
+; first two apply it; the third takes it apart, which is the same dependency on
+; the same callable — the breadth tier records all three as call edges, so a
+; type that is only ever matched on does not read as unused.
+(record
+  name: (constructor_name) @name) @reference.call
+
+(record_update
+  constructor: (constructor_name) @name) @reference.call
+
+(record_pattern
+  name: (constructor_name) @name) @reference.call
+
+; A type annotation is the only thing that ever names a Gleam type outside its
+; own declaration, so without this a custom type is an orphan no matter how
+; widely it is used. `type_name` (the declaration's own name) is a different node
+; and is not matched here; builtins like `Int` resolve to nothing and drop.
+(type
+  name: (type_identifier) @name) @reference.class

package/dist/graph/queries/java.scm

@@ -0,0 +1,20 @@
+(class_declaration
+  name: (identifier) @name) @definition.class
+
+(method_declaration
+  name: (identifier) @name) @definition.method
+
+(method_invocation
+  name: (identifier) @name
+  arguments: (argument_list) @reference.call)
+
+(interface_declaration
+  name: (identifier) @name) @definition.interface
+
+(type_list
+  (type_identifier) @name) @reference.implementation
+
+(object_creation_expression
+  type: (type_identifier) @name) @reference.class
+
+(superclass (type_identifier) @name) @reference.class

package/dist/graph/queries/kotlin.scm

@@ -0,0 +1,43 @@
+; Classes
+(class_declaration
+  (type_identifier) @name) @definition.class
+
+; Objects
+(object_declaration
+  (type_identifier) @name) @definition.class
+
+; Functions (top-level and member)
+(function_declaration
+  (simple_identifier) @name) @definition.function
+
+; Properties
+(property_declaration
+  (variable_declaration
+    (simple_identifier) @name)) @definition.constant
+
+; Enum entries
+(enum_entry
+  (simple_identifier) @name) @definition.constant
+
+; Type aliases
+(type_alias
+  (type_identifier) @name) @definition.type
+
+; Companion objects (only named ones)
+(companion_object
+  (type_identifier) @name) @definition.class
+
+; Function calls
+(call_expression
+  (simple_identifier) @name) @reference.call
+
+; Method calls via navigation
+(call_expression
+  (navigation_expression
+    (navigation_suffix
+      (simple_identifier) @name))) @reference.call
+
+; Constructor invocations (class references)
+(constructor_invocation
+  (user_type
+    (type_identifier) @name)) @reference.class

package/dist/graph/queries/lua.scm

@@ -0,0 +1,36 @@
+(function_declaration
+  name: [
+    (identifier) @name
+    (dot_index_expression
+      field: (identifier) @name)
+  ]) @definition.function
+
+(function_declaration
+  name: (method_index_expression
+    method: (identifier) @name)) @definition.method
+
+(assignment_statement
+  (variable_list
+    .
+    name: [
+      (identifier) @name
+      (dot_index_expression
+        field: (identifier) @name)
+    ])
+  (expression_list
+    .
+    value: (function_definition))) @definition.function
+
+(table_constructor
+  (field
+    name: (identifier) @name
+    value: (function_definition))) @definition.function
+
+(function_call
+  name: [
+    (identifier) @name
+    (dot_index_expression
+      field: (identifier) @name)
+    (method_index_expression
+      method: (identifier) @name)
+  ]) @reference.call

package/dist/graph/queries/nix.scm

@@ -0,0 +1,32 @@
+; Nix tags — standard tree-sitter tags convention (@definition.<kind> + @name + @reference.call).
+; Based on upstream tree-sitter-nix queries, extended for graft's breadth tier.
+;
+; Note: `binding` inside `let_expression` cannot have its children matched in
+; tree-sitter queries (parse error), so let-bound variables are NOT captured as
+; @definition. They are still searchable via the file node's residual body.
+
+; Function definitions: `name = args: body` or `name = body` (where body is a function)
+(binding
+  (attrpath (identifier) @name)
+  (function_expression) @definition.function)
+
+; Inherit statements: `inherit (source) name1 name2`
+(inherit
+  (inherited_attrs (identifier) @name @definition.constant))
+
+; Function calls: `function arg` or `function arg1 arg2` (nested apply_expression)
+; Matches e.g. `import ./path` when `import` is applied to arguments.
+(apply_expression
+  function: (apply_expression
+    function: (variable_expression
+      name: (identifier) @name))) @reference.call
+
+; Method/attribute calls: `builtins.map`, `pkgs.python3.withPackages`, etc.
+(apply_expression
+  function: (select_expression
+    attrpath: (attrpath attr: (identifier) @name))) @reference.call
+
+; Direct function application: `f arg`
+(apply_expression
+  function: (variable_expression
+    name: (identifier) @name)) @reference.call

package/dist/graph/queries/php.scm

@@ -0,0 +1,40 @@
+(namespace_definition
+  name: (namespace_name) @name) @definition.module
+
+(interface_declaration
+  name: (name) @name) @definition.interface
+
+(trait_declaration
+  name: (name) @name) @definition.interface
+
+(class_declaration
+  name: (name) @name) @definition.class
+
+(class_interface_clause [(name) (qualified_name)] @name) @reference.implementation
+
+(property_declaration
+  (property_element (variable_name (name) @name))) @definition.field
+
+(function_definition
+  name: (name) @name) @definition.function
+
+(method_declaration
+  name: (name) @name) @definition.function
+
+(object_creation_expression
+  [
+    (qualified_name (name) @name)
+    (variable_name (name) @name)
+  ]) @reference.class
+
+(function_call_expression
+  function: [
+    (qualified_name (name) @name)
+    (variable_name (name)) @name
+  ]) @reference.call
+
+(scoped_call_expression
+  name: (name) @name) @reference.call
+
+(member_call_expression
+  name: (name) @name) @reference.call

package/dist/graph/queries/ruby.scm

@@ -0,0 +1,65 @@
+; Method definitions
+
+(
+  (comment)* @doc
+  .
+  [
+    (method
+      name: (_) @name) @definition.method
+    (singleton_method
+      name: (_) @name) @definition.method
+  ]
+  (#strip! @doc "^#\\s*")
+  (#select-adjacent! @doc @definition.method)
+)
+
+(alias
+  name: (_) @name) @definition.method
+
+(setter
+  (identifier) @ignore)
+
+; Class definitions
+
+(
+  (comment)* @doc
+  .
+  [
+    (class
+      name: [
+        (constant) @name
+        (scope_resolution
+          name: (_) @name)
+      ]) @definition.class
+    (singleton_class
+      value: [
+        (constant) @name
+        (scope_resolution
+          name: (_) @name)
+      ]) @definition.class
+  ]
+  (#strip! @doc "^#\\s*")
+  (#select-adjacent! @doc @definition.class)
+)
+
+; Module definitions
+
+(
+  (module
+    name: [
+      (constant) @name
+      (scope_resolution
+        name: (_) @name)
+    ]) @definition.module
+)
+
+; Calls
+; NB: only explicit call nodes — the upstream tags.scm also tags bare
+; [(identifier)(constant)] as @reference.call gated by (#is-not? local), but that
+; predicate needs the paired @local.* captures (from locals.scm, which graft does
+; not load) to mean anything. Without them it's a no-op, so bare *variable reads*
+; that share a name with a same-file/unique method become bogus `calls` edges
+; (resolve.ts can't tell a var read from a zero-arg call). Dropped for precision —
+; consistent with every other breadth-tier query (all use explicit call nodes).
+
+(call method: (identifier) @name) @reference.call

package/dist/graph/queries/rust.scm

@@ -0,0 +1,41 @@
+; Rust tags — standard tree-sitter tags convention (@definition.<kind> + @name + @reference.call).
+; Vendored for graft's generic breadth tier. Predicates like (#strip! ...) are
+; sanitized out at load time by generic.ts.
+
+(function_item (identifier) @name) @definition.function
+
+(function_signature_item (identifier) @name) @definition.function
+
+(struct_item (type_identifier) @name) @definition.struct
+
+(enum_item (type_identifier) @name) @definition.enum
+
+(union_item (type_identifier) @name) @definition.struct
+
+(trait_item (type_identifier) @name) @definition.interface
+
+(type_item (type_identifier) @name) @definition.type
+
+(mod_item (identifier) @name) @definition.module
+
+(macro_definition (identifier) @name) @definition.function
+
+(const_item (identifier) @name) @definition.constant
+
+(static_item (identifier) @name) @definition.constant
+
+; associated functions / methods inside impl blocks are function_item too,
+; already captured above; call sites below:
+
+(call_expression
+  function: [
+    (identifier) @name
+    (field_expression field: (field_identifier) @name)
+    (scoped_identifier name: (identifier) @name)
+  ]) @reference.call
+
+(macro_invocation
+  macro: [
+    (identifier) @name
+    (scoped_identifier name: (identifier) @name)
+  ]) @reference.call

package/dist/graph/queries/scala.scm

@@ -0,0 +1,66 @@
+; Definitions
+
+(package_clause
+  name: (package_identifier) @name) @definition.module
+
+(trait_definition
+  name: (identifier) @name) @definition.interface
+
+(enum_definition
+  name: (identifier) @name) @definition.enum
+
+(simple_enum_case
+  name: (identifier) @name) @definition.class
+
+(full_enum_case
+  name: (identifier) @name) @definition.class
+
+(class_definition
+  name: (identifier) @name) @definition.class
+
+(object_definition
+  name: (identifier) @name) @definition.object
+
+(function_definition
+  name: (identifier) @name) @definition.function
+
+(val_definition
+  pattern: (identifier) @name) @definition.variable
+
+(given_definition
+  name: (identifier) @name) @definition.variable
+
+(var_definition
+  pattern: (identifier) @name) @definition.variable
+
+(val_declaration
+  name: (identifier) @name) @definition.variable
+
+(var_declaration
+  name: (identifier) @name) @definition.variable
+
+(type_definition
+  name: (type_identifier) @name) @definition.type
+
+(class_parameter
+  name: (identifier) @name) @definition.property
+
+; References 
+
+(call_expression
+  (identifier) @name) @reference.call
+
+(instance_expression
+  (type_identifier) @name) @reference.interface
+
+(instance_expression
+  (generic_type
+    (type_identifier) @name)) @reference.interface
+
+(extends_clause
+  (type_identifier) @name) @reference.class
+
+(extends_clause
+  (generic_type
+    (type_identifier) @name)) @reference.class
+

package/dist/graph/queries/solidity.scm

@@ -0,0 +1,43 @@
+;; Method and Function declarations
+(contract_declaration (_
+    (function_definition
+        name: (identifier) @name) @definition.method))
+
+(source_file
+    (function_definition
+        name: (identifier) @name) @definition.function)
+
+;; Contract, struct, enum and interface declarations
+(contract_declaration
+  name: (identifier) @name) @definition.class
+
+(interface_declaration
+  name: (identifier) @name) @definition.interface
+
+(library_declaration
+  name: (identifier) @name) @definition.interface
+
+(struct_declaration name: (identifier) @name) @definition.class
+(enum_declaration name: (identifier) @name) @definition.class
+(event_definition name: (identifier) @name) @definition.class
+
+;; Function calls
+(call_expression (expression (identifier)) @name ) @reference.call
+
+(call_expression
+    (expression (member_expression
+        property: (_) @name ))) @reference.call
+
+;; Log emit
+(emit_statement name: (_) @name) @reference.class
+
+
+;; Inheritance
+
+(inheritance_specifier
+    ancestor: (user_defined_type (_) @name . )) @reference.class
+
+
+;; Imports ( note that unknown is not standardised )
+(import_directive
+  import_name: (_) @name ) @reference.unknown

package/dist/graph/queries/swift.scm

@@ -0,0 +1,51 @@
+(class_declaration
+  name: (type_identifier) @name) @definition.class
+
+(protocol_declaration
+  name: (type_identifier) @name) @definition.interface
+
+(class_declaration
+    (class_body
+        [
+            (function_declaration
+                name: (simple_identifier) @name
+            )
+            (subscript_declaration
+                (parameter (simple_identifier) @name)
+            )
+            (init_declaration "init" @name)
+            (deinit_declaration "deinit" @name)
+        ]
+    )
+) @definition.method
+
+(protocol_declaration
+    (protocol_body
+        [
+            (protocol_function_declaration
+                name: (simple_identifier) @name
+            )
+            (subscript_declaration
+                (parameter (simple_identifier) @name)
+            )
+            (init_declaration "init" @name)
+        ]
+    )
+) @definition.method
+
+(class_declaration
+    (class_body
+        [
+            (property_declaration
+                (pattern (simple_identifier) @name)
+            )
+        ]
+    )
+) @definition.property
+
+(property_declaration
+    (pattern (simple_identifier) @name)
+) @definition.property
+
+(function_declaration
+    name: (simple_identifier) @name) @definition.function

package/dist/graph/refresh.d.ts

@@ -0,0 +1,106 @@
+/**
+ * `ensureFreshGraph` — the pre-query gate that keeps retrieval honest.
+ *
+ * A graph is a set of `file:line` spans for one working tree, so an answer drawn
+ * from it is only as honest as its freshness. That cannot be somebody else's job:
+ * an edit made outside the agent (your editor, a branch switch, a stash, a merge)
+ * sets no flag anywhere. So freshness lives in the query path: every retrieval
+ * call probes the working tree (`fingerprint.ts`, ~3ms) and, when something moved,
+ * repairs the structural graph. Properties worth keeping:
+ *
+ * - **$0 and offline.** Tier-1 only — never a summarizer, never `--deep`. Anything
+ *   that runs without being asked must not spend money.
+ * - **Never fatal.** A failed refresh degrades to answering from the graph on
+ *   disk. A query that works today must not start failing because a rebuild did.
+ * - **Never a stampede.** It takes the same `.cache/.sync.lock` a background build
+ *   takes, so concurrent MCP calls and the rebuild they trigger can't pile up.
+ * - **Bounded.** Up to `DRIFT_INLINE_MAX` changed files are re-extracted before
+ *   answering; more than that is handed to a background rebuild and the answer
+ *   carries `[stale: N files changed, rebuilding in background]`. A branch switch
+ *   never blocks a query.
+ * - **Writes only what a query reads** (`graphOnly`): the graph, the `ask` sidecar,
+ *   the freshness record. Not the markdown cards, not `INDEX.md`, not `.gitignore`.
+ *   Those belong to an explicit `trail build`, so retrieval stays cheap and a read
+ *   stays a read. `stats.json` is left alone too.
+ * - **Lexical here, semantic elsewhere.** The inline repair updates the graph only.
+ *   The vector index loads an ONNX model, so it refreshes in a detached process
+ *   (`build-run.ts`) and never on the path that answers.
+ *
+ * One case is not drift but absence: inside a git worktree there is no graph at all,
+ * because `.trail/`/`graft/` is gitignored and so was never checked out. The gate
+ * covers that too — it copies the parent checkout's graph in (`./seed.ts`) and then
+ * treats the difference between the two checkouts as ordinary drift, which is
+ * exactly what it is.
+ *
+ * The other absence is a repo this machine never built: `trail init` ran somewhere
+ * else, or the clone is new. Its queries find no code and the agent goes back to
+ * grep for the rest of the session. So the first query there starts a full build in
+ * the background and waits a while for it (`buildMissingMap`).
+ */
+import { type Drift } from "./fingerprint.js";
+/**
+ * Most files a query will re-extract before answering, instead of handing the
+ * rebuild to a background process.
+ *
+ * A constant, not a flag: a merge or an ordinary edit of a handful of files stays
+ * well under it and gets answered from a current graph; a branch switch or a fresh
+ * clone blows past it, and blocking that query to re-parse hundreds of files is
+ * exactly the cost this gate exists to avoid. See design decision 5.
+ */
+export declare const DRIFT_INLINE_MAX = 50;
+export interface RefreshResult {
+    /** True when the graph on disk was rebuilt by this call. */
+    refreshed: boolean;
+    /** What the probe found, when it ran and found something. */
+    drift?: Drift;
+    /**
+     * How many files changed when the drift was too large to patch inline, so the
+     * rebuild went to the background and this answer is about the graph as it was.
+     */
+    stale?: number;
+    /** One-line explanation for the agent/user, when there's something worth saying. */
+    note?: string;
+}
+export interface RefreshOptions {
+    contextDir?: string;
+    /** Skip everything (the `--no-refresh` flag). */
+    disabled?: boolean;
+    /** How long to wait for a first build of a repo on trail; 0 starts it and answers
+     * at once. Default `GRAFT_FIRST_BUILD_WAIT_MS`, else FIRST_BUILD_WAIT_MS. */
+    firstBuildWaitMs?: number;
+}
+/**
+ * Release the lock if this process is asked to die while holding it. Returns the
+ * un-hook.
+ *
+ * Not hypothetical: the Claude Code prompt hook runs `graft ask` with a timeout, and
+ * `execFileSync` enforces it with SIGTERM. Node's default disposition for SIGTERM is
+ * to exit without unwinding, so the `finally` below never runs and the lock outlives
+ * the process — after which the background sync is blocked and every query waits and
+ * then answers stale until the lock ages out. Ctrl-C on a CLI query is the same story
+ * with SIGINT.
+ *
+ * Adding a listener replaces that default disposition, so re-raise it explicitly
+ * afterwards: remove ourselves, then `process.kill(process.pid, sig)`, so the exit
+ * status still says "terminated by signal" for whoever is waiting on us.
+ */
+export declare function releaseOnSignal(cache: string): () => void;
+/**
+ * Rebuild `root`'s structural graph if the working tree has moved since the last
+ * build. Cheap and side-effect-free when nothing changed, which is the usual case.
+ *
+ * `root` is the repository root (the same value the query itself is given), not
+ * the context dir.
+ */
+export declare function ensureFreshGraph(root: string, opts?: RefreshOptions): Promise<RefreshResult>;
+/**
+ * Workspace variant: refresh each child repo's own graph (a workspace parent holds
+ * an index, never nodes). Children are independent, but they're refreshed in
+ * sequence — a fan-out of concurrent tree-sitter builds would spike CPU on the
+ * very path that's supposed to feel free.
+ */
+export declare function ensureFreshChildren(root: string, children: string[], opts?: RefreshOptions): Promise<RefreshResult>;
+/** The one-line note a CLI/MCP surface prints when a refresh actually happened.
+ * Null when there's nothing to say (the overwhelmingly common case). */
+export declare function refreshNote(r: RefreshResult): string | null;
+//# sourceMappingURL=refresh.d.ts.map

package/dist/graph/refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.d.ts","sourceRoot":"","sources":["../../src/graph/refresh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAaH,OAAO,EAAoD,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAMhG;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAgBnC,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;iFAC6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAoID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,IAAI,CAWzD;AAuCD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CA4FtG;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAAE,EAClB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,aAAa,CAAC,CA4BxB;AAED;wEACwE;AACxE,wBAAgB,WAAW,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAY3D"}