dotclaude-codegraph

1// Generated by `just generate` from `src/plugins/dotclaude-codegraph/slices/*/slice.ts`. Edit the source and run `just generate`.
2import type { On } from "claude-code";
3import { onTreeChange as h0 } from "../slices/graph/adapters/mod.ts";
4
5export const register = (on: On): void => {
6  // eval: tool.call graph
7  on(
8    "tool.call",
9    {
10      tool: "Bash",
11      command:
12        /(?:^|[;&|])\s*git(?:\s+(?:-[Cc]\s+(?:[^\s"']|"[^"]*"|'[^']*')+|--(?:git-dir|work-tree|namespace)(?:=|\s+)(?:[^\s"']|"[^"]*"|'[^']*')+|--(?!(?:git-dir|work-tree|namespace)(?:=|\s))[a-z][\w-]*|-[pP]))*\s+(?:commit|merge|rebase|pull|checkout|switch|reset|cherry-pick|revert|stash|apply|am)(?:\s|$)/,
13    },
14    h0,
15  );
16};
17

1// Generated by `just generate` from `src/plugins/dotclaude-codegraph/slices/graph/adapters/mod.ts`. Edit the source and run `just generate`.
2// The mod handler of the `graph` slice: a `tool.call` on a `Bash` command with a `git` command that changes the tree syncs the index after the command.
3// The filter in `slice.ts` is `TREE_CHANGE`, which the mod runtime tests in process, so a `Bash` call of any other kind starts no process.
4// This replaces 12 classic `PostToolUse` hooks, each with an `if` for one `git` command.
5// The sync runs with `$.process.run` and no shell, in a project with `.codegraph/codegraph.db` only.
6// The hook fails open: a missing `codegraph`, a timeout, or a deny of the call adds nothing and never changes the result of the call.
7// Each `$` call is in this file, because `$` is not followed across an import.
8
9import type { EngineInterface } from "claude-code";
10import type { Handler } from "../../../kernel/slice.ts";
11import { INDEX_PATH } from "../domain/graph.ts";
12import { GIT_SYNC_TIMEOUT_MS } from "../limits.ts";
13
14/**
15 * The `next` of a `tool.call` hook, with a method signature so that its parameter is bivariant.
16 * The generated `register` passes this handler to `on` with the filter of `slice.ts`, which gives `next` the narrow type of that call.
17 * The generator does not narrow the handler type, so the method signature lets both `next` types fit.
18 */
19type PassOn = {
20  pass(
21    e: Parameters<Parameters<Handler<"tool.call">>[2]>[0],
22  ): ReturnType<Parameters<Handler<"tool.call">>[2]>;
23}["pass"];
24
25/** The project folder: `CLAUDE_PROJECT_DIR`, or the folder of the session. */
26const projectRoot = async ($: EngineInterface): Promise<string> =>
27  (await $.env.get("CLAUDE_PROJECT_DIR")) || ".";
28
29/** Syncs the index when the project has one. The catch has no narrower test, because `$.process.run` documents no error type. */
30const syncIndex = async ($: EngineInterface): Promise<void> => {
31  const root = await projectRoot($);
32  if (!(await $.fs.exists(`${root}/${INDEX_PATH}`))) return;
33  try {
34    await $.process.run(["codegraph", "sync", "-q"], {
35      cwd: root,
36      timeoutMs: GIT_SYNC_TIMEOUT_MS,
37    });
38  } catch {
39    // A missing `codegraph` or a timeout leaves the index as it is. The next sync catches up.
40  }
41};
42
43/** The `tool.call` handler on a `git` command that changes the tree. It runs the command, then syncs the index. */
44export const onTreeChange = async (
45  $: EngineInterface,
46  e: Parameters<Handler<"tool.call">>[1],
47  next: PassOn,
48) => {
49  const out = await next(e);
50  if (out.deny === undefined) await syncIndex($);
51  return out;
52};
53

1// Generated by `just generate` from `src/kernel/slice.ts`. Edit the source and run `just generate`.
2// The contract of a slice manifest: what a slice folder exports from its `slice.ts`.
3// The generator reads each manifest, and the types of the mod API come from `claude-code`.
4// This file has no runtime import, so the hooks module can load it.
5
6import type {
7  Args,
8  EventName,
9  Events,
10  Matcher,
11  PluginOptions,
12} from "claude-code";
13
14/** The order of the phases of a mod handler, from the first to the last. The generator sorts by it. */
15export const PHASES = [
16  "observe",
17  "normalize",
18  "rewrite",
19  "check",
20  "answer",
21] as const;
22
23/** One phase of a mod handler, from `PHASES`. */
24export type Phase = (typeof PHASES)[number];
25
26/** The filter of a mod handler: a matcher over the argument of the event `E`. */
27export type EventFilter<E extends EventName = EventName> = Matcher<Args<E>>;
28
29/** The hook signature of the event `E`, as the mod API declares it. */
30export type Handler<E extends EventName = EventName> = Events[E];
31
32/**
33 * Keeps the `userConfig` values of the plugin, which the mod runtime gives to `register`, for a hook to read.
34 * The generated `register` calls it once, before the `on()` calls.
35 * The hook itself goes to `on()` by its name, because `claude plugin validate --strict` follows `$` only into a function of `register.ts`.
36 */
37export type Configure = (options: PluginOptions) => void;
38
39/**
40 * The eval kinds of one hook, which the generator writes to `evals/hooks.json` under the id `<event> <slice>`.
41 * A test is `<file from the repository root> > <test name>`.
42 * A hook that runs a model has `requests` above 0 and names its `claude plugin eval` case in `eval`.
43 * A hook that can block also names `block` and `false`.
44 */
45export interface HookEvals {
46  readonly requests: number;
47  readonly tokens: number;
48  readonly blocks: boolean;
49  readonly allow: string;
50  readonly text: string;
51  readonly block?: string;
52  readonly false?: string;
53  readonly eval?: string;
54}
55
56/**
57 * One mod handler of a slice. A slice can have more than one for one event, each with its own filter.
58 * It has `run`, the hook, and `configure`, when the hook reads the `userConfig` values of the plugin.
59 */
60export interface ModHandler<E extends EventName = EventName> {
61  readonly event: E;
62  readonly filter?: EventFilter<E>;
63  readonly phase: Phase;
64  /**
65   * The hook. A hook with a `filter` can take the event that the filter narrows, as `MatchedHook` of the mod API types it.
66   * The generated `register.ts` gives the hook and the filter to `on()`, and the compiler checks the pair there.
67   */
68  readonly run: Handler<E> | ((...args: never[]) => unknown);
69  readonly configure?: Configure;
70  /** The eval kinds of the hook. One entry covers each handler of the slice on the same event. */
71  readonly evals?: HookEvals;
72}
73
74/** One classic command hook, for an event that the mod API does not cover. */
75export interface ClassicHook {
76  readonly event: string;
77  readonly matcher?: string;
78  readonly command: string;
79  readonly timeout?: number;
80  readonly async?: boolean;
81  /** The eval kinds of the hook. Its id is the event and the command, without the `bun` launcher and the plugin root. */
82  readonly evals?: HookEvals;
83}
84
85/** One segment of the status line. The `row` is the row of the status line that holds it. */
86export interface StatusSegment {
87  readonly id: string;
88  readonly row: number;
89  readonly render: (status: unknown) => string | null;
90}
91
92/** One `userConfig` field of a plugin manifest, such as the `backend` of `dotclaude-browser`. */
93export interface UserConfigOption {
94  readonly type: "string" | "number" | "boolean";
95  readonly title: string;
96  readonly description?: string;
97  readonly default: string | number | boolean;
98  readonly options?: readonly string[];
99}
100
101/** The manifest of one slice: the name, and each part that the slice adds to the plugin. */
102export interface Slice {
103  readonly name: string;
104  readonly mod?: readonly ModHandler[];
105  readonly hooks?: readonly ClassicHook[];
106  readonly cli?: { readonly bin: string };
107  readonly segments?: readonly StatusSegment[];
108  readonly skills?: readonly string[];
109  readonly agents?: readonly string[];
110  readonly outputStyles?: readonly string[];
111  readonly userConfig?: Readonly<Record<string, UserConfigOption>>;
112  readonly settings?: Readonly<Record<string, unknown>>;
113}
114

1// Generated by `just generate` from `src/plugins/dotclaude-codegraph/slices/graph/domain/graph.ts`. Edit the source and run `just generate`.
2// The pure logic of the code-graph hooks: the text that goes to Claude, and the parse of the payload.
3// No function here runs a command or reads a file.
4
5/** The fields of a hook payload that the hooks read. */
6export interface HookPayload {
7  cwd?: string;
8}
9
10/** The install command that the check prints. The add-on never runs it. */
11export const INSTALL_COMMAND = "bun i -g @colbymchenry/codegraph";
12
13/** The command that builds the first index. It is the opt-in of a project. */
14export const INIT_COMMAND = "codegraph init -y";
15
16/** The path of the index database in a project. A project with this file has opted in. */
17export const INDEX_PATH = ".codegraph/codegraph.db";
18
19/**
20 * The line that `SessionStart` adds.
21 * `impact` has a default depth of 2, so the line gives `-d 5`.
22 * A run on the fixture of the comparison missed 2 of 8 affected functions at depth 2.
23 */
24export const SESSION_LINE =
25  "This project has a code graph. " +
26  "`codegraph impact <symbol> -d 5` lists the code that a change to a symbol affects. " +
27  "The default depth of 2 misses some of it. " +
28  "`codegraph callers <symbol>` and `codegraph callees <symbol>` list who calls a symbol and what it calls.";
29
30/** One word of an option value, with its quoted parts, such as `"my dir"`. */
31const GIT_WORD = String.raw`(?:[^\s"']|"[^"]*"|'[^']*')+`;
32
33/**
34 * A global option of `git` before its verb: `-C <path>`, `-c <k=v>`, `--git-dir=<p>`, `--git-dir <p>`, `--work-tree`, `--namespace`, or a flag such as `--no-pager` or `-p`.
35 */
36const GIT_OPTION = String.raw`(?:-[Cc]\s+${GIT_WORD}|--(?:git-dir|work-tree|namespace)(?:=|\s+)${GIT_WORD}|--(?!(?:git-dir|work-tree|namespace)(?:=|\s))[a-z][\w-]*|-[pP])`;
37
38/**
39 * A `Bash` command with a `git` command that changes the tree: `commit`, `merge`, `rebase`, `pull`, `checkout`, `switch`, `reset`, `cherry-pick`, `revert`, `stash`, `apply`, or `am`.
40 * The `git` command starts the command or follows `;`, `&`, or `|`, so `cd x && git commit` matches.
41 * Global options before the verb are skipped, so `git -C dir commit` matches too.
42 * The mod handler uses it as its filter, so a command of any other kind starts no process.
43 */
44export const TREE_CHANGE = new RegExp(
45  String.raw`(?:^|[;&|])\s*git(?:\s+${GIT_OPTION})*\s+(?:commit|merge|rebase|pull|checkout|switch|reset|cherry-pick|revert|stash|apply|am)(?:\s|$)`,
46);
47
48/** `text` as a parsed payload, or `null` when it is not JSON. */
49export const parseJson = (text: string): HookPayload | null => {
50  try {
51    return JSON.parse(text);
52  } catch (err) {
53    if (!(err instanceof SyntaxError)) throw err;
54    return null;
55  }
56};
57
58/** What the check prints, as lines, from whether the CLI answers and whether the project has an index. */
59export const checkLines = (
60  found: boolean,
61  version: string,
62  indexed: boolean,
63): string[] => {
64  if (!found)
65    return [
66      "`codegraph` is not on `PATH`, so the code-graph hooks do nothing.",
67      `To install it, run \`${INSTALL_COMMAND}\`.`,
68      "The add-on does not install it.",
69    ];
70  return [
71    `\`codegraph\` ${version} is on \`PATH\`.`,
72    indexed
73      ? "This project has an index, so the code-graph hooks run."
74      : `This project has no index, so the hooks do nothing. To opt in, run \`${INIT_COMMAND}\` in the project.`,
75  ];
76};
77

1// Generated by `just generate` from `src/plugins/dotclaude-codegraph/slices/graph/limits.ts`. Edit the source and run `just generate`.
2// The bounds of the `graph` slice.
3
4/** How long `codegraph --version` may run for the check. */
5export const QUERY_TIMEOUT_MS = 2000;
6
7/** The hook timeout of `SessionStart`, in seconds, as `slice.ts` gives it to Claude Code. */
8export const SESSION_START_HOOK_TIMEOUT_S = 10;
9
10/**
11 * How long the sync at session start may run.
12 * On Windows the sync also gets `TREE_GRACE_MS` more, so the total is 9 s, which is 1 s under the hook timeout.
13 */
14export const START_SYNC_TIMEOUT_MS = 6000;
15
16/** The time that `run-tree.ts` gets to start and to end the process tree after the limit on Windows. */
17export const TREE_GRACE_MS = 3000;
18
19/** How long the background sync after an edit may run. The hook timeout in `slice.ts` is longer. */
20export const BACKGROUND_SYNC_TIMEOUT_MS = 60000;
21
22/** How long the sync after a `git` command may run. The `git` result waits for it, so it is shorter. */
23export const GIT_SYNC_TIMEOUT_MS = 15000;
24