Detector API v4

import { findUp, findWord, lineAt, matchesGlob, matchesGlobs, mentioned, onCommand, onDelete, onOutput, onPrompt, onRead, onWrite } from "@wellactually/sdk/v4";
import type { CommandEvent, DeleteEvent, File, Finding, OutputEvent, PromptEvent, ReadEvent, RemovedLine, TextFinding, WriteEvent, WrittenLine } from "@wellactually/sdk/v4";

Handlers#

Each registers a handler. Call them at the top level of detector.ts, as often as you need.

detect returns findings: usually a generator, written *detect(event) { ... }, or any other iterable, or nothing. globs are patterns for event.file.relativePath: **, *, ?, {a,b}, and ! in front to take files out. Only onWrite, onRead and onDelete take globs.

Events#

Every event has these fields:

And each kind adds its own:

cwd is the folder the session runs in, as an absolute path.

File#

WrittenLine#

A handler of onWrite may also yield a WrittenLine as it is. It becomes a finding on its line.

RemovedLine#

A line the agent changed is removed as it was and written as it is now. removed is empty when the host cannot tell what the file was before, as for a new file. A handler of onWrite or onDelete may yield a RemovedLine as it is, and the agent is shown "removed line 3: ..." with its text. Because a deletion has removed too, one helper serves both:

function* removedTests(event: WriteEvent | DeleteEvent) {
  for (const removed of event.removed) {
    if (removed.text.includes("test(")) {
      yield removed;
    }
  }
}

onWrite({ globs: ["test/**"], detect: removedTests });
onDelete({ globs: ["test/**"], detect: removedTests });

Finding#

What onWrite, onRead, onDelete and onOutput yield. Nothing in it is required.

TextFinding is what onPrompt and onCommand yield: the same without line and endLine. A detail that is wrong is left out and the finding still fires. Findings explains each field with examples.

Helpers#

findUp(name, from)#

findUp(name: string, from: string): string | null

The nearest file called name, in from or a folder above it, as an absolute path, or null.

findUp("pubspec.yaml", event.cwd); // for a prompt, a command or an output
findUp("pubspec.yaml", path.dirname(event.file.path)); // for a file

mentioned(event, names)#

mentioned(event: { text: string }, names: readonly string[]): TextFinding[]

A pointer finding for the first of names that the event's text mentions, or an empty list. A name counts where it stands alone, in any case, and with or without the separators people put inside names: rxdart also finds rx_dart, rx-dart and RxDart. A space in a name stands for any whitespace. Pass it on with yield*.

yield* mentioned(event, ["late keyword", "late final", "LateInitializationError"]);

findWord(text, word, from?)#

findWord(text: string, word: string, from?: number): number

The index of word in text where it stands alone, or -1. findWord("isolate", "late") is -1, and findWord("late final x", "late") is 0.

lineAt(text, offset)#

lineAt(text: string, offset: number): number

The 1-based line of a character offset, for a detector that searches the whole event.text with a regular expression.

for (const match of event.text.matchAll(/Future\.delayed\(/g)) {
  yield { line: lineAt(event.text, match.index), match: "Future.delayed(" };
}

matchesGlob(path, pattern) and matchesGlobs(path, globs)#

matchesGlob(path: string, pattern: string): boolean
matchesGlobs(path: string, globs: readonly string[]): boolean

The glob matching the handlers use, for a detector that decides about other paths itself, such as the files readdirSync lists. A pattern without a slash matches the file name in any folder.

The EVENTS constant#

["write", "read", "delete", "prompt", "command", "output"], the names of the events.

node:fs and node:path#

A detector may import node:fs and node:path. fs has readFileSync, existsSync, statSync and readdirSync, read-only and synchronous. See Reading project files.

Versions of the API#

A detector says which version it is written against by its import path, @wellactually/sdk/v4. A detector on version 3 keeps running as it was: it never sees removed lines or deletions. Detector API versions lists what each version added, and everything version 3 offers.