dsh-plugin-codegraph-tree-sitter 0.2.0 → 0.3.0

package/lib/index.d.ts

@@ -15,6 +15,13 @@
  * backend serves from another execution world is watched where it actually lives, and a backend that
  * cannot watch at all degrades to explicit indexing instead of failing the plugin.
  *
+ * A workspace with no index yet is also indexed automatically the first time a session is created in
+ * it (`agent/created`), through the host's background-job registry when the composition has one. The
+ * graph is most useful on the first `codegraph` query, and a session that starts in an unindexed
+ * workspace is exactly the moment a caller would otherwise have to ask for a build by hand. This
+ * never runs synchronously inside the event dispatch: creating an agent must not wait on a
+ * multi-minute parse, and an index is an optimization, never a precondition for starting work.
+ *
  * Namespace plugin (named exports, no default export). Grammars load lazily, one per language, on
  * first sight of a matching file, and stay cached for the process — never eagerly for every grammar
  * this package ships with.
@@ -143,6 +150,16 @@ export interface Config {
      * covering only part of the tree.
      */
     maxWatchedDirectories?: number;
+    /**
+     * Build a first index automatically, in the background, when a session is created in a workspace
+     * that has none (default true). A workspace is only ever auto-indexed once per process and never
+     * when its status sidecar already exists, so this cannot rebuild a graph that is already there.
+     * Set false to keep every build explicitly requested.
+     *
+     * Requires the host's `jobs` service: the build is never run synchronously inside session creation,
+     * so a composition without background jobs simply schedules nothing.
+     */
+    autoIndexOnSession?: boolean;
 }
 export declare const Config: z<Config>;
 /**

package/lib/index.js

@@ -15,15 +15,23 @@
  * backend serves from another execution world is watched where it actually lives, and a backend that
  * cannot watch at all degrades to explicit indexing instead of failing the plugin.
  *
+ * A workspace with no index yet is also indexed automatically the first time a session is created in
+ * it (`agent/created`), through the host's background-job registry when the composition has one. The
+ * graph is most useful on the first `codegraph` query, and a session that starts in an unindexed
+ * workspace is exactly the moment a caller would otherwise have to ask for a build by hand. This
+ * never runs synchronously inside the event dispatch: creating an agent must not wait on a
+ * multi-minute parse, and an index is an optimization, never a precondition for starting work.
+ *
  * Namespace plugin (named exports, no default export). Grammars load lazily, one per language, on
  * first sight of a matching file, and stay cached for the process — never eagerly for every grammar
  * this package ships with.
  * @module dsh-plugin-codegraph-tree-sitter
  */
+import { existsSync } from 'node:fs';
 import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
-import { CodegraphIndexerId } from 'dsh-plugin-codegraph-service';
+import { CodegraphIndexerId, INDEX_STATUS_RELATIVE_PATH } from 'dsh-plugin-codegraph-service';
 import { LANGUAGE_TABLE } from "./languages.js";
 import { walkAndExtract } from "./walk.js";
 import { writeParseCache } from "./cache.js";
@@ -81,6 +89,7 @@ export const Config = z.object({
     watch: z.boolean().default(true),
     watchDebounceMs: z.number().default(DEFAULT_WATCH_DEBOUNCE_MS),
     maxWatchedDirectories: z.number().default(DEFAULT_MAX_WATCHED_DIRECTORIES),
+    autoIndexOnSession: z.boolean().default(true),
 });
 /**
  * Register the tree-sitter indexer.
@@ -105,6 +114,14 @@ export function apply(ctx, config) {
     // cross-plugin relation here for an invariant to describe — just process-local bookkeeping this
     // effect's cleanup below tears down on unload.
     const watchers = new Map();
+    // Roots this plugin instance has already started an automatic index for. The set is only a guard
+    // against a burst of agents opened on one workspace each scheduling the same rebuild; what a
+    // previous *process* indexed is recorded by the status sidecar `autoIndexOnSession` reads instead.
+    const autoIndexed = new Set();
+    // `agent/created` is typed by `@deepseek-ai/dsh-agent`'s module augmentation. Reading the event
+    // through a local structural face keeps this package's host dependencies unchanged: it needs one
+    // event name and one payload shape, not the whole agent package.
+    const agentEvents = ctx;
     /** Start (or leave running) file watching for `projectRoot`, once it has a baseline to refresh. */
     function ensureWatching(projectRoot) {
         if (watchers.has(projectRoot))
@@ -162,9 +179,92 @@ export function apply(ctx, config) {
                 watcher.stop();
             watchers.clear();
         };
+        if (resolved.autoIndexOnSession) {
+            // Registered inside this effect so the listener follows the plugin's lifetime: unloading the
+            // plugin must stop new sessions from scheduling work this instance can no longer run.
+            yield agentEvents.on('agent/created', payload => autoIndexOnSession(ctx, autoIndexed, payload));
+        }
         yield ctx.codegraph.registerIndexer(indexer);
     }, 'codegraph-tree-sitter');
 }
+/** Stable job kind of an automatic session-start index, used for retention and diagnostics. */
+const AUTO_INDEX_JOB_KIND = 'codegraph-index';
+/**
+ * Index a new session's workspace in the background, when nothing has indexed it yet.
+ *
+ * Runs synchronously inside `agent/created` dispatch, so it must never block or throw: it only decides
+ * whether a build is warranted and hands one to the host's job registry. A synchronous build here
+ * would stall agent creation for the length of a parse, which is why a composition without background
+ * jobs does nothing instead.
+ * @param ctx - the plugin context, consulted for the optional job registry.
+ * @param autoIndexed - roots this process has already started an automatic index for.
+ * @param payload - the `agent/created` dispatch payload.
+ */
+function autoIndexOnSession(ctx, autoIndexed, payload) {
+    try {
+        const agent = payload.agent;
+        const root = agent?.session?.header?.cwd;
+        // No workspace means no root to claim: an agent created without a `cwd` has nothing to index.
+        if (agent === undefined || !root)
+            return;
+        // Once per root per process. A second agent opened on the same workspace must not queue a second
+        // full rebuild of a graph the first one is already building.
+        if (autoIndexed.has(root))
+            return;
+        // An existing status sidecar means a previous run already indexed this workspace. Checked before
+        // the job lookup so a composition without background jobs never pays for a filesystem probe.
+        if (existsSync(join(root, INDEX_STATUS_RELATIVE_PATH)))
+            return;
+        // `ctx.get` rather than an `inject` entry: `jobs` is a host composition choice, and requiring it in
+        // `inject` would hide this whole indexer from a profile that runs no background jobs.
+        const jobs = ctx.get('jobs');
+        if (jobs === undefined)
+            return;
+        jobs.start({
+            // The registry keys a job by its owning session id, not the agent object.
+            owner: agent.id,
+            kind: AUTO_INDEX_JOB_KIND,
+            label: `codegraph auto index ${root}`,
+            run: handle => runAutoIndexJob(ctx, root, handle),
+        });
+        // Marked only after the registry accepted the job, so a transient refusal leaves the workspace
+        // eligible for the next session that opens in it.
+        autoIndexed.add(root);
+    }
+    catch (error) {
+        // The host treats a throwing listener as vetoing publication. Losing an index is a degradation,
+        // never a reason to stop a session from starting.
+        console.error(`codegraph-tree-sitter: automatic indexing for a new session failed: ${String(error)}`);
+    }
+}
+/**
+ * The producer body of one automatic indexing job.
+ *
+ * Both halves of the host's job contract are mandatory: `cancel` aborts the run, and `done` settles
+ * even on failure — a rejected `done` breaks the registry's bookkeeping and leaves the job looking
+ * stuck forever.
+ * @param ctx - the plugin context.
+ * @param root - the workspace to index.
+ * @param handle - the job's producer face, for the job's live log.
+ * @returns the job's cancellation hook and settlement promise.
+ */
+function runAutoIndexJob(ctx, root, handle) {
+    const controller = new AbortController();
+    const done = (async () => {
+        try {
+            const report = await ctx.codegraph.index(root, controller.signal);
+            handle.append(`Indexed ${root}: ${report.filesIndexed} files, ${report.nodeCount} symbols, ` +
+                `${report.edgeCount} relationships.\n`);
+            return { status: 'completed' };
+        }
+        catch (error) {
+            const message = String(error);
+            handle.append(`codegraph auto index failed for ${root}: ${message}\n`);
+            return { status: 'failed', detail: message };
+        }
+    })();
+    return { cancel: () => controller.abort(), done };
+}
 /**
  * Run one watch-triggered reindex. Always a full rebuild in this version — `runIndex` has no notion of
  * a file subset — so the watcher's own collected paths are not consulted here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-codegraph-tree-sitter",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Self-built code-graph indexer for DeepSeek Harness — parses a workspace with web-tree-sitter and writes schema version 4 to .codegraph/codegraph.db, the same on-disk format the codegraph CLI writes, so no external indexer is required",
   "keywords": [
     "dsh",
@@ -51,7 +51,7 @@
     "@deepseek-ai/schemastery": "^3.18.1",
     "tree-sitter-wasms": "^0.1.13",
     "web-tree-sitter": "^0.25.10",
-    "dsh-plugin-codegraph-service": "^0.2.0"
+    "dsh-plugin-codegraph-service": "^0.3.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.1",