@huanlin/dsh-plugin-codegraph-tool 0.1.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CC ZHAO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @huanlin/dsh-plugin-codegraph-tool
+
+The model-facing tools: a read-only `codegraph` tool with ten structural query operations, plus a `codegraph_index` tool that builds or refreshes the index on its own, much larger timeout budget.
+
+Part of **[dsh-plugin-codegraph](https://github.com/CC19990113/dsh-plugin-codegraph)** — structural code intelligence for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+
+Most users should install the bundle instead, which mounts this package and its siblings in one layer:
+
+```sh
+dsh plugin --profile <name> add dsh-plugin-codegraph
+```
+
+See the [project README](https://github.com/CC19990113/dsh-plugin-codegraph#readme) for setup, configuration, and the full tool reference.
+
+## License
+
+[MIT](LICENSE)

package/lib/compose.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The two operations that are not seam queries. `explore` and `context` compose the graph primitives
+ * with `ctx.fs` reads, which is why they live in the consumer: a graph store returns positions and
+ * cannot reach a remote workspace's bytes, so aggregation belongs to the role that holds both.
+ * @module @huanlin/dsh-plugin-codegraph-tool/compose
+ */
+import type { CodegraphNode, CodegraphRelation } from '@huanlin/dsh-plugin-codegraph-service';
+/**
+ * Split a task description into the terms worth searching for.
+ *
+ * A task is prose, but a graph is indexed by identifiers, so the terms that carry signal are the
+ * identifier-shaped words: `camelCase` and `snake_case` names survive whole because splitting them
+ * would search for their fragments instead of the symbol the author meant.
+ * @param task - the free-text task description.
+ * @param maxTerms - largest number of terms to return.
+ * @returns the search terms, longest first so the most specific one is searched before the budget
+ * runs out.
+ */
+export declare function taskTerms(task: string, maxTerms: number): string[];
+/**
+ * Keep only the declarations among matched nodes.
+ * @param nodes - the matched nodes.
+ * @returns the nodes that declare something.
+ */
+export declare function declarationsOnly(nodes: readonly CodegraphNode[]): CodegraphNode[];
+/** A node with the evidence that it matched. */
+export interface ScoredNode {
+    /** The matched declaration. */
+    readonly node: CodegraphNode;
+    /** How many distinct terms found it. */
+    readonly hits: number;
+}
+/**
+ * Merge per-term search results into one ranked list.
+ *
+ * A declaration found by several of a task's terms is more likely to be what the task is about than
+ * one found by a single term, so hit count leads the ranking; within an equal count the earliest
+ * position any single search gave it wins, preserving the store's own relevance order.
+ * @param batches - each term's search results, in the order the store ranked them.
+ * @param limit - largest number of declarations to return.
+ * @returns the merged declarations, most relevant first.
+ */
+export declare function mergeByHits(batches: readonly (readonly CodegraphNode[])[], limit: number): ScoredNode[];
+/** Declarations that share one file, in the order the search ranked them. */
+export interface FileGroup {
+    /** The file, relative to the project root. */
+    readonly path: string;
+    /** The matched declarations in that file. */
+    readonly nodes: CodegraphNode[];
+    /** One-based first line spanned by {@link nodes}. */
+    readonly startLine: number;
+    /** One-based last line spanned by {@link nodes}. */
+    readonly endLine: number;
+}
+/**
+ * Group ranked declarations by file, preserving rank.
+ *
+ * Grouping is what makes `explore` cheaper than reading each symbol separately: several matches in
+ * one file share a single read and a single contiguous slice, and the file that held the top-ranked
+ * match is presented first.
+ * @param nodes - the ranked declarations.
+ * @param maxFiles - largest number of files to return.
+ * @returns the groups, best-ranked file first.
+ */
+export declare function groupByFile(nodes: readonly CodegraphNode[], maxFiles: number): FileGroup[];
+/**
+ * Merge relations from several symbols, keeping each related declaration once.
+ * @param batches - relation lists to merge.
+ * @param limit - largest number of relations to return.
+ * @returns the merged relations, in first-seen order.
+ */
+export declare function mergeRelations(batches: readonly (readonly CodegraphRelation[])[], limit: number): CodegraphRelation[];
+//# sourceMappingURL=compose.d.ts.map

package/lib/compose.js

@@ -0,0 +1,138 @@
+/**
+ * The two operations that are not seam queries. `explore` and `context` compose the graph primitives
+ * with `ctx.fs` reads, which is why they live in the consumer: a graph store returns positions and
+ * cannot reach a remote workspace's bytes, so aggregation belongs to the role that holds both.
+ * @module @huanlin/dsh-plugin-codegraph-tool/compose
+ */
+/** Words a task description contributes no search signal through. */
+const STOPWORDS = new Set([
+    'a', 'an', 'and', 'are', 'as', 'at', 'be', 'but', 'by', 'can', 'do', 'does', 'for', 'from',
+    'how', 'in', 'into', 'is', 'it', 'its', 'not', 'of', 'on', 'or', 'that', 'the', 'their', 'then',
+    'there', 'this', 'to', 'was', 'what', 'when', 'where', 'which', 'why', 'will', 'with', 'work',
+    'works', 'add', 'fix', 'bug', 'code', 'file', 'files', 'need', 'make', 'use', 'used', 'using',
+]);
+/**
+ * Split a task description into the terms worth searching for.
+ *
+ * A task is prose, but a graph is indexed by identifiers, so the terms that carry signal are the
+ * identifier-shaped words: `camelCase` and `snake_case` names survive whole because splitting them
+ * would search for their fragments instead of the symbol the author meant.
+ * @param task - the free-text task description.
+ * @param maxTerms - largest number of terms to return.
+ * @returns the search terms, longest first so the most specific one is searched before the budget
+ * runs out.
+ */
+export function taskTerms(task, maxTerms) {
+    const words = task.split(/[^\p{L}\p{N}_$]+/u).filter(word => word.length > 0);
+    const kept = new Map();
+    for (const word of words) {
+        if (word.length < 3)
+            continue;
+        if (STOPWORDS.has(word.toLowerCase()))
+            continue;
+        const key = word.toLowerCase();
+        if (!kept.has(key))
+            kept.set(key, word);
+    }
+    return [...kept.values()]
+        .sort((left, right) => right.length - left.length)
+        .slice(0, maxTerms);
+}
+/**
+ * Node kinds that name code without declaring any. An `import` node exists once per importing file,
+ * so a widely used symbol contributes a dozen of them under its own name; a `file` node repeats the
+ * path its results are already grouped by. `search` still returns both, because a model that asked
+ * for a name asked for every occurrence of it — but the operations that answer "what is this task
+ * about" must spend their budget on declarations.
+ */
+const STRUCTURAL_KINDS = new Set(['import', 'export', 'file', 'module']);
+/**
+ * Keep only the declarations among matched nodes.
+ * @param nodes - the matched nodes.
+ * @returns the nodes that declare something.
+ */
+export function declarationsOnly(nodes) {
+    return nodes.filter(node => !STRUCTURAL_KINDS.has(node.kind));
+}
+/** A stable identity for one declaration across separate searches. */
+function nodeKey(node) {
+    return `${node.filePath}:${node.startLine}:${node.qualifiedName}`;
+}
+/**
+ * Merge per-term search results into one ranked list.
+ *
+ * A declaration found by several of a task's terms is more likely to be what the task is about than
+ * one found by a single term, so hit count leads the ranking; within an equal count the earliest
+ * position any single search gave it wins, preserving the store's own relevance order.
+ * @param batches - each term's search results, in the order the store ranked them.
+ * @param limit - largest number of declarations to return.
+ * @returns the merged declarations, most relevant first.
+ */
+export function mergeByHits(batches, limit) {
+    const merged = new Map();
+    for (const batch of batches) {
+        batch.forEach((node, position) => {
+            const key = nodeKey(node);
+            const existing = merged.get(key);
+            if (existing === undefined)
+                merged.set(key, { node, hits: 1, best: position });
+            else {
+                existing.hits += 1;
+                existing.best = Math.min(existing.best, position);
+            }
+        });
+    }
+    return [...merged.values()]
+        .sort((left, right) => right.hits - left.hits || left.best - right.best)
+        .slice(0, limit)
+        .map(entry => ({ node: entry.node, hits: entry.hits }));
+}
+/**
+ * Group ranked declarations by file, preserving rank.
+ *
+ * Grouping is what makes `explore` cheaper than reading each symbol separately: several matches in
+ * one file share a single read and a single contiguous slice, and the file that held the top-ranked
+ * match is presented first.
+ * @param nodes - the ranked declarations.
+ * @param maxFiles - largest number of files to return.
+ * @returns the groups, best-ranked file first.
+ */
+export function groupByFile(nodes, maxFiles) {
+    const groups = new Map();
+    for (const node of nodes) {
+        const existing = groups.get(node.filePath);
+        if (existing === undefined) {
+            groups.set(node.filePath, {
+                path: node.filePath,
+                nodes: [node],
+                startLine: node.startLine,
+                endLine: node.endLine,
+            });
+            continue;
+        }
+        existing.nodes.push(node);
+        existing.startLine = Math.min(existing.startLine, node.startLine);
+        existing.endLine = Math.max(existing.endLine, node.endLine);
+    }
+    return [...groups.values()].slice(0, maxFiles);
+}
+/**
+ * Merge relations from several symbols, keeping each related declaration once.
+ * @param batches - relation lists to merge.
+ * @param limit - largest number of relations to return.
+ * @returns the merged relations, in first-seen order.
+ */
+export function mergeRelations(batches, limit) {
+    const merged = new Map();
+    for (const batch of batches) {
+        for (const relation of batch) {
+            const key = `${nodeKey(relation.node)}:${relation.edge.kind}`;
+            if (!merged.has(key))
+                merged.set(key, relation);
+            if (merged.size >= limit)
+                return [...merged.values()];
+        }
+    }
+    return [...merged.values()];
+}
+//# sourceMappingURL=compose.js.map

package/lib/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Model-facing `codegraph` tool family over `ctx.codegraph` and `ctx.fs`. The `codegraph` tool is
+ * read-only, with ten operations: the eight the seam answers directly, plus `explore` and `context`,
+ * which compose graph queries with source reads because a graph store returns positions and cannot
+ * reach a workspace's bytes. A second tool, `codegraph_index`, builds or refreshes the graph on
+ * explicit request; it is separate so it can carry its own, much larger timeout budget than a query
+ * — `defineTool`'s `timeoutMs` is fixed per registration, not per call, so one operation cannot borrow
+ * a bigger budget from within a shared tool.
+ *
+ * The tools own every default the seam refuses to guess — result limits, traversal depth, source
+ * caps — so the seam's requests stay fully specified and a deployment can retune the model's answer
+ * size without touching a store. They runtime-inject only `tools`, `codegraph`, `fs`, and
+ * `systemPrompt`, and import no store.
+ *
+ * Namespace plugin (named exports, no default export).
+ * @module @huanlin/dsh-plugin-codegraph-tool
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { CodegraphToolArgs } from './schema.ts';
+export { CODEGRAPH_INDEX_PARAMETERS, CODEGRAPH_OPERATIONS, CODEGRAPH_OUTPUT_SCHEMA, CODEGRAPH_PARAMETERS, type CodegraphIndexToolArgs, type CodegraphToolArgs, type CodegraphToolOperation, type CodegraphToolValue, type CodegraphValueFor, } from './schema.ts';
+export { declarationsOnly, groupByFile, mergeByHits, mergeRelations, taskTerms } from './compose.ts';
+export { toAffected, toHop, toRelation, toSymbol } from './projection.ts';
+export { renderCodegraph } from './render.ts';
+export { readSlice } from './source.ts';
+/** Cordis plugin name for loader diagnostics. */
+export declare const name = "tool-codegraph";
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** Default tool-call timeout budget (ms) for the query-side `codegraph` tool. */
+export declare const DEFAULT_CODEGRAPH_TOOL_TIMEOUT_MS = 30000;
+/** Default timeout budget (ms) for the `codegraph_index` tool. Indexing a monorepo is a different order of work than a query. */
+export declare const DEFAULT_CODEGRAPH_INDEX_TIMEOUT_MS = 300000;
+/** The stable system-prompt guidance positioning the code graph against search and read. */
+export declare const CODEGRAPH_PROMPT_TEXT = "Use codegraph for structural questions about code: where a symbol is declared, what calls it, what it calls, what a change to it reaches, and how one symbol reaches another. It answers from a pre-built index, so it is both faster and more precise than grepping for a name, which also matches comments, strings, and unrelated identifiers. Use search/read instead for literal text, and when codegraph reports no index for a workspace. When status reports no index, call codegraph_index once to build one \u2014 it runs on its own, longer timeout budget than a query \u2014 then retry. Results reflect the last time the workspace was indexed; a declaration added since then is absent.";
+/** Plugin configuration: the defaults and caps the seam requires the consumer to own. */
+export interface Config {
+    /** Results returned when the model names no `limit` (default 20). */
+    defaultLimit?: number;
+    /** Largest `limit` honored, whatever the model asks for (default 200). */
+    maxLimit?: number;
+    /** Hops traversed by `impact` and `trace` when the model names no `depth` (default 2). */
+    defaultDepth?: number;
+    /** Largest `depth` honored (default 6). */
+    maxDepth?: number;
+    /** Distinct paths `trace` returns (default 5). */
+    maxPaths?: number;
+    /** Files whose source `explore` and `context` return (default 5). */
+    maxSourceFiles?: number;
+    /** Lines of source carried per file (default 200). */
+    maxSourceLines?: number;
+    /** Characters of source carried per file (default 8000). */
+    maxSourceChars?: number;
+    /** Characters of documentation carried per symbol (default 400). */
+    maxDocstringChars?: number;
+    /** Characters of signature carried per symbol (default 200). */
+    maxSignatureChars?: number;
+    /** Search terms extracted from a `context` task description (default 6). */
+    maxContextTerms?: number;
+    /** Tool-call timeout budget in ms for the query-side `codegraph` tool (default 30000). */
+    timeoutMs?: number;
+    /** Tool-call timeout budget in ms for the `codegraph_index` tool (default 300000). */
+    indexTimeoutMs?: number;
+}
+export declare const Config: z<Config>;
+/**
+ * The project root a call runs against: the model's explicit `project_path`, else the calling
+ * agent's session workspace. There is no process-cwd fallback — a graph query that silently answered
+ * about a different checkout than the session is working in would be wrong in a way the model cannot
+ * detect.
+ * @param args - the validated tool arguments.
+ * @param exec - the tool-execution context; only its optional `agent` is read.
+ * @returns the absolute project root.
+ */
+export declare function projectRoot(args: CodegraphToolArgs, exec: ToolExecution): string;
+/**
+ * Register the `codegraph` tool and its system-prompt guidance.
+ * @param ctx - the plugin context (must inject `tools`, `codegraph`, `fs`, `systemPrompt`).
+ * @param config - the resolved plugin configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+/**
+ * The one-line label a pending call shows.
+ * @param args - the validated tool arguments.
+ * @returns the card title naming the operation and whichever subject the operation takes.
+ */
+export declare function callTitle(args: CodegraphToolArgs): string;
+//# sourceMappingURL=index.d.ts.map