@huanlin/dsh-plugin-codegraph-tool 0.1.8

package/lib/index.js

@@ -0,0 +1,432 @@
+/**
+ * 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 z from '@deepseek-ai/schemastery';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { CodegraphError } from '@huanlin/dsh-plugin-codegraph-service';
+import { assertNever } from '@deepseek-ai/dsh-util-values';
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout';
+import { declarationsOnly, groupByFile, mergeByHits, mergeRelations, taskTerms } from "./compose.js";
+import { toAffected, toHop, toRelation, toSymbol } from "./projection.js";
+import { renderCodegraph } from "./render.js";
+import { CODEGRAPH_INDEX_PARAMETERS, CODEGRAPH_OUTPUT_SCHEMA, CODEGRAPH_PARAMETERS } from "./schema.js";
+import { readSlice } from "./source.js";
+export { CODEGRAPH_INDEX_PARAMETERS, CODEGRAPH_OPERATIONS, CODEGRAPH_OUTPUT_SCHEMA, CODEGRAPH_PARAMETERS, } from "./schema.js";
+export { declarationsOnly, groupByFile, mergeByHits, mergeRelations, taskTerms } from "./compose.js";
+export { toAffected, toHop, toRelation, toSymbol } from "./projection.js";
+export { renderCodegraph } from "./render.js";
+export { readSlice } from "./source.js";
+/** Cordis plugin name for loader diagnostics. */
+export const name = 'tool-codegraph';
+/** Services required by this plugin. */
+export const inject = ['tools', 'codegraph', 'fs', 'systemPrompt'];
+/** Default tool-call timeout budget (ms) for the query-side `codegraph` tool. */
+export const DEFAULT_CODEGRAPH_TOOL_TIMEOUT_MS = 30_000;
+/** Default timeout budget (ms) for the `codegraph_index` tool. Indexing a monorepo is a different order of work than a query. */
+export const DEFAULT_CODEGRAPH_INDEX_TIMEOUT_MS = 300_000;
+/** The stable system-prompt guidance positioning the code graph against search and read. */
+export 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 — it runs on its own, longer timeout budget than a query — then retry. Results reflect the last time the workspace was indexed; a declaration added since then is absent.';
+export const Config = z.object({
+    defaultLimit: z.number().default(20),
+    maxLimit: z.number().default(200),
+    defaultDepth: z.number().default(2),
+    maxDepth: z.number().default(6),
+    maxPaths: z.number().default(5),
+    maxSourceFiles: z.number().default(5),
+    maxSourceLines: z.number().default(200),
+    maxSourceChars: z.number().default(8000),
+    maxDocstringChars: z.number().default(400),
+    maxSignatureChars: z.number().default(200),
+    maxContextTerms: z.number().default(6),
+    timeoutMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_CODEGRAPH_TOOL_TIMEOUT_MS),
+    indexTimeoutMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_CODEGRAPH_INDEX_TIMEOUT_MS),
+});
+/**
+ * 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 function projectRoot(args, exec) {
+    return resolvedProjectRoot(args.project_path, exec);
+}
+/**
+ * Shared root-resolution logic behind {@link projectRoot} and the index tool's own argument shape.
+ * @param explicit - the model's `project_path`, if given.
+ * @param exec - the tool-execution context; only its optional `agent` is read.
+ * @returns the absolute project root.
+ */
+function resolvedProjectRoot(explicit, exec) {
+    if (explicit !== undefined && explicit.trim() !== '')
+        return explicit;
+    const sessionCwd = exec.agent?.session.header.cwd;
+    if (sessionCwd === undefined) {
+        throw new CodegraphError('the codegraph tool requires a session workspace or an explicit project_path', 'CODEGRAPH_WORKSPACE_REQUIRED');
+    }
+    return sessionCwd;
+}
+/** Read a required string argument, rejecting an absent or blank value. */
+function required(args, field) {
+    const value = args[field];
+    if (value === undefined || value.trim() === '') {
+        throw new CodegraphError(`the codegraph "${args.operation}" operation requires a non-empty "${field}"`, 'CODEGRAPH_INVALID_REQUEST');
+    }
+    return value;
+}
+/** Clamp a model-supplied bound into the configured range. */
+function bounded(value, fallback, max) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(1, Math.trunc(value)));
+}
+/**
+ * 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 function apply(ctx, config) {
+    const resolved = config;
+    for (const field of [
+        'defaultLimit', 'maxLimit', 'defaultDepth', 'maxDepth', 'maxPaths', 'maxSourceFiles',
+        'maxSourceLines', 'maxSourceChars', 'maxDocstringChars', 'maxSignatureChars', 'maxContextTerms',
+    ]) {
+        assertPositiveInteger(field, resolved[field]);
+    }
+    assertTimer('timeoutMs', resolved.timeoutMs);
+    assertTimer('indexTimeoutMs', resolved.indexTimeoutMs);
+    ctx.systemPrompt.section({ name: 'tool:codegraph', order: 111, text: CODEGRAPH_PROMPT_TEXT });
+    ctx.tools.register(defineTool({
+        name: 'codegraph',
+        description: 'Query a pre-built index of the workspace\'s declarations and their relationships. Find where a symbol is declared, what calls it, what it calls, what a change to it can affect, and how one symbol reaches another. More precise than text search: it matches declarations, not occurrences in comments or strings. Answers reflect the last time the workspace was indexed.',
+        parameters: CODEGRAPH_PARAMETERS,
+        output: {
+            schema: CODEGRAPH_OUTPUT_SCHEMA,
+            render: (_args, value) => [{ type: 'text', text: renderCodegraph(value) }],
+        },
+        timeoutMs: resolved.timeoutMs,
+        async execute(args, exec) {
+            return run(ctx, resolved, args, exec);
+        },
+        presentCall: args => ({
+            card: 'generic',
+            title: callTitle(args),
+            kind: 'search',
+            rawInput: args,
+        }),
+    }));
+    ctx.tools.register(defineTool({
+        name: 'codegraph_index',
+        description: 'Build or refresh the codegraph index for a workspace, so the codegraph tool can answer. Indexing a large workspace can take minutes, so this runs on its own timeout budget, separate from codegraph\'s query operations.',
+        parameters: CODEGRAPH_INDEX_PARAMETERS,
+        output: {
+            schema: CODEGRAPH_OUTPUT_SCHEMA,
+            render: (_args, value) => [{ type: 'text', text: renderCodegraph(value) }],
+        },
+        timeoutMs: resolved.indexTimeoutMs,
+        async execute(args, exec) {
+            return runIndex(ctx, args, exec);
+        },
+        presentCall: args => ({
+            card: 'generic',
+            title: args.project_path === undefined ? 'codegraph_index' : `codegraph_index ${args.project_path}`,
+            kind: 'search',
+            rawInput: args,
+        }),
+    }));
+}
+/**
+ * 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 function callTitle(args) {
+    const subject = args.symbol ?? args.query ?? args.task
+        ?? (args.from === undefined ? undefined : `${args.from} → ${args.to ?? '?'}`)
+        ?? args.pattern ?? args.path;
+    return subject === undefined ? `codegraph ${args.operation}` : `codegraph ${args.operation} ${subject}`;
+}
+/**
+ * Build or refresh the on-disk index for one project. The dedicated tool this backs carries its own,
+ * much larger timeout budget than a query — indexing a monorepo is a different order of work.
+ * @param ctx - the plugin context.
+ * @param args - the index tool's validated arguments.
+ * @param exec - the tool-execution context.
+ * @returns the index operation's canonical value.
+ */
+async function runIndex(ctx, args, exec) {
+    const root = resolvedProjectRoot(args.project_path, exec);
+    const report = await ctx.codegraph.index(root, exec.signal);
+    return {
+        operation: 'index',
+        project_path: root,
+        files_indexed: report.filesIndexed,
+        files_skipped: report.filesSkipped,
+        symbol_count: report.nodeCount,
+        edge_count: report.edgeCount,
+        unresolved_count: report.unresolvedCount,
+        unresolved_likely_internal_count: report.unresolvedLikelyInternalCount,
+        languages: report.languages.map(entry => ({ language: entry.language, file_count: entry.fileCount })),
+    };
+}
+/**
+ * Answer one tool call.
+ * @param ctx - the plugin context.
+ * @param config - the resolved plugin configuration.
+ * @param args - the validated tool arguments.
+ * @param exec - the tool-execution context.
+ * @returns the canonical value for the requested operation.
+ */
+async function run(ctx, config, args, exec) {
+    const root = projectRoot(args, exec);
+    const limit = bounded(args.limit, config.defaultLimit, config.maxLimit);
+    const depth = bounded(args.depth, config.defaultDepth, config.maxDepth);
+    const projection = {
+        maxDocstringChars: config.maxDocstringChars,
+        maxSignatureChars: config.maxSignatureChars,
+    };
+    const source = { maxLines: config.maxSourceLines, maxChars: config.maxSourceChars };
+    const signal = exec.signal;
+    switch (args.operation) {
+        case 'search': {
+            const result = await ctx.codegraph.query({
+                operation: 'search',
+                projectRoot: root,
+                query: required(args, 'query'),
+                ...args.kind === undefined ? {} : { kind: args.kind },
+                ...args.language === undefined ? {} : { language: args.language },
+                limit,
+            }, signal);
+            return {
+                operation: 'search',
+                project_path: root,
+                symbols: result.nodes.map(node => toSymbol(node, projection)),
+                total: result.total,
+                truncated: result.truncated,
+            };
+        }
+        case 'node': {
+            const result = await ctx.codegraph.query({
+                operation: 'node',
+                projectRoot: root,
+                symbol: required(args, 'symbol'),
+                limit,
+            }, signal);
+            const symbol = result.node === null ? null : toSymbol(result.node, projection);
+            const code = args.include_code === true && result.node !== null
+                ? (await readSlice(ctx, root, result.node.filePath, result.node.startLine, result.node.endLine, source, signal)).code
+                : null;
+            return {
+                operation: 'node',
+                project_path: root,
+                symbol,
+                incoming: result.incoming.map(relation => toRelation(relation, projection)),
+                outgoing: result.outgoing.map(relation => toRelation(relation, projection)),
+                alternatives: result.alternatives.map(node => toSymbol(node, projection)),
+                code,
+            };
+        }
+        case 'callers':
+        case 'callees': {
+            const result = await ctx.codegraph.query({
+                operation: args.operation,
+                projectRoot: root,
+                symbol: required(args, 'symbol'),
+                limit,
+            }, signal);
+            return {
+                operation: args.operation,
+                project_path: root,
+                symbol: result.subject === null ? null : toSymbol(result.subject, projection),
+                relations: result.relations.map(relation => toRelation(relation, projection)),
+                total: result.total,
+                truncated: result.truncated,
+            };
+        }
+        case 'impact': {
+            const result = await ctx.codegraph.query({
+                operation: 'impact',
+                projectRoot: root,
+                symbol: required(args, 'symbol'),
+                depth,
+                limit,
+            }, signal);
+            return {
+                operation: 'impact',
+                project_path: root,
+                symbol: result.subject === null ? null : toSymbol(result.subject, projection),
+                affected: result.entries.map(entry => toAffected(entry, projection)),
+                total: result.total,
+                truncated: result.truncated,
+            };
+        }
+        case 'trace': {
+            const result = await ctx.codegraph.query({
+                operation: 'trace',
+                projectRoot: root,
+                from: required(args, 'from'),
+                to: required(args, 'to'),
+                maxDepth: depth,
+                maxPaths: config.maxPaths,
+            }, signal);
+            return {
+                operation: 'trace',
+                project_path: root,
+                from: result.from === null ? null : toSymbol(result.from, projection),
+                to: result.to === null ? null : toSymbol(result.to, projection),
+                paths: result.paths.map(path => path.map(hop => toHop(hop, projection))),
+            };
+        }
+        case 'files': {
+            const result = await ctx.codegraph.query({
+                operation: 'files',
+                projectRoot: root,
+                ...args.path === undefined ? {} : { path: args.path },
+                ...args.pattern === undefined ? {} : { pattern: args.pattern },
+                limit,
+            }, signal);
+            return {
+                operation: 'files',
+                project_path: root,
+                files: result.files.map(file => ({
+                    path: file.path,
+                    language: file.language,
+                    size: file.size,
+                    symbol_count: file.nodeCount,
+                })),
+                total: result.total,
+                truncated: result.truncated,
+            };
+        }
+        case 'status': {
+            const available = await ctx.codegraph.available(root, signal);
+            if (!available) {
+                return { operation: 'status', project_path: root, indexed: false };
+            }
+            const result = await ctx.codegraph.query({ operation: 'status', projectRoot: root }, signal);
+            return {
+                operation: 'status',
+                project_path: root,
+                indexed: true,
+                file_count: result.fileCount,
+                symbol_count: result.nodeCount,
+                edge_count: result.edgeCount,
+                format_version: result.formatVersion,
+                indexed_at: result.indexedAt,
+                languages: result.languages.map(entry => ({
+                    language: entry.language,
+                    file_count: entry.fileCount,
+                })),
+                stale_file_count: result.staleFileCount,
+                stale_file_count_truncated: result.staleFileCountTruncated,
+            };
+        }
+        case 'explore': {
+            const result = await ctx.codegraph.query({
+                operation: 'search',
+                projectRoot: root,
+                query: required(args, 'query'),
+                limit,
+            }, signal);
+            const declarations = declarationsOnly(result.nodes);
+            const groups = groupByFile(declarations, config.maxSourceFiles);
+            return {
+                operation: 'explore',
+                project_path: root,
+                files: await Promise.all(groups.map(group => explored(ctx, root, group, projection, source, signal))),
+                total: result.total,
+                truncated: result.truncated || groups.length < countFiles(declarations),
+            };
+        }
+        case 'context': {
+            const task = required(args, 'task');
+            const terms = taskTerms(task, config.maxContextTerms);
+            const batches = await Promise.all(terms.map(async (term) => (await ctx.codegraph.query({
+                operation: 'search',
+                projectRoot: root,
+                query: term,
+                limit,
+            }, signal)).nodes));
+            const ranked = mergeByHits(batches.map(declarationsOnly), limit).map(scored => scored.node);
+            const related = await relatedTo(ctx, root, ranked, config, signal);
+            const groups = groupByFile(ranked, config.maxSourceFiles);
+            return {
+                operation: 'context',
+                project_path: root,
+                task,
+                entry_points: ranked.map(node => toSymbol(node, projection)),
+                related: related.map(relation => toRelation(relation, projection)),
+                files: await Promise.all(groups.map(group => explored(ctx, root, group, projection, source, signal))),
+            };
+        }
+        /* v8 ignore next -- exhaustive over the parameter schema's closed operation enum; unreachable. */
+        default:
+            return assertNever(args.operation, 'tool-codegraph operation');
+    }
+}
+/** How many distinct files a ranked result set spans. */
+function countFiles(nodes) {
+    return new Set(nodes.map(node => node.filePath)).size;
+}
+/** Read one file group's source and pair it with the declarations that selected it. */
+async function explored(ctx, root, group, projection, source, signal) {
+    const slice = await readSlice(ctx, root, group.path, group.startLine, group.endLine, source, signal);
+    return {
+        path: group.path,
+        symbols: group.nodes.map(node => toSymbol(node, projection)),
+        code: slice.code,
+        ...slice.startLine === undefined ? {} : { code_start_line: slice.startLine },
+        truncated: slice.truncated,
+    };
+}
+/**
+ * Callers and callees of the highest-ranked declarations a task matched.
+ *
+ * Only the top declarations are expanded: a task's context is the neighbourhood of what it is about,
+ * and querying every match's relations would spend the result budget on the tail of the ranking.
+ * @param ctx - the plugin context.
+ * @param root - the project root.
+ * @param ranked - the task's matched declarations, most relevant first.
+ * @param config - the resolved plugin configuration.
+ * @param signal - aborts the queries.
+ * @returns the merged relations.
+ */
+async function relatedTo(ctx, root, ranked, config, signal) {
+    const seeds = ranked.slice(0, config.maxSourceFiles);
+    const batches = await Promise.all(seeds.flatMap(node => ['callers', 'callees'].map(async (operation) => (await ctx.codegraph.query({
+        operation,
+        projectRoot: root,
+        symbol: node.qualifiedName,
+        limit: config.defaultLimit,
+    }, signal)).relations)));
+    return mergeRelations(batches, config.defaultLimit);
+}
+/** Reject a non-positive-integer config value at load, so misconfiguration fails loud. */
+function assertPositiveInteger(field, value) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`tool-codegraph: ${field} must be a positive integer`);
+    }
+}
+/** Reject a timer value Node would clamp instead of scheduling as configured. */
+function assertTimer(field, value) {
+    if (!Number.isInteger(value) || value < 1 || value > MAX_TIMER_DELAY_MS) {
+        throw new Error(`tool-codegraph: ${field} must be a positive integer no greater than ${MAX_TIMER_DELAY_MS}`);
+    }
+}
+//# sourceMappingURL=index.js.map

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `dsh-plugin-codegraph-tool`.
+ * @module dsh-plugin-codegraph-tool/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-codegraph-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/invariant.js

@@ -0,0 +1,22 @@
+/**
+ * Package-owned invariant companion for `dsh-plugin-codegraph-tool`.
+ * @module dsh-plugin-codegraph-tool/invariant
+ */
+const PACKAGE_NAME = 'dsh-plugin-codegraph-tool';
+/** Cordis companion plugin name. */
+export const name = 'tool-codegraph-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: this stateless adapter contributes one tool and prompt section, while graph
+ * query results and source retrieval remain owned by the codegraph and filesystem seams it composes.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/projection.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Seam records to model-facing values. The tool owns this projection because the seam's vocabulary
+ * describes a graph while the model's describes code: `filePath`/`startLine` become `path`/`line`,
+ * an edge's kind becomes `via`, and the fields a model cannot act on — opaque node ids, index
+ * timestamps, provenance — are dropped rather than spent as tokens.
+ * @module @huanlin/dsh-plugin-codegraph-tool/projection
+ */
+import type { CodegraphImpactEntry, CodegraphNode, CodegraphRelation, CodegraphTraceHop } from '@huanlin/dsh-plugin-codegraph-service';
+/** Caps applied while projecting, so one enormous doc comment cannot dominate a result. */
+export interface ProjectionLimits {
+    /** Largest documentation string carried per symbol, in characters. */
+    readonly maxDocstringChars: number;
+    /** Largest signature carried per symbol, in characters. */
+    readonly maxSignatureChars: number;
+}
+/** The model-facing shape of one declaration. */
+export interface SymbolView {
+    readonly name: string;
+    readonly qualified_name: string;
+    readonly kind: string;
+    readonly path: string;
+    readonly line: number;
+    readonly end_line: number;
+    readonly language: string;
+    readonly exported: boolean;
+    readonly signature?: string;
+    readonly docstring?: string;
+}
+/**
+ * Project one declaration.
+ * @param node - the seam's node record.
+ * @param limits - the caps to apply to free text.
+ * @returns the model-facing symbol.
+ */
+export declare function toSymbol(node: CodegraphNode, limits: ProjectionLimits): SymbolView;
+/** A symbol plus how it was reached. */
+export interface RelationView extends SymbolView {
+    readonly via: string;
+    readonly site_line?: number;
+    readonly site_count: number;
+}
+/**
+ * Project one related declaration.
+ * @param relation - the seam's relation record.
+ * @param limits - the caps to apply to free text.
+ * @returns the model-facing relation.
+ */
+export declare function toRelation(relation: CodegraphRelation, limits: ProjectionLimits): RelationView;
+/** A symbol reached by a transitive walk. */
+export interface AffectedView extends SymbolView {
+    readonly via: string;
+    readonly distance: number;
+}
+/**
+ * Project one impact entry.
+ * @param entry - the seam's impact record.
+ * @param limits - the caps to apply to free text.
+ * @returns the model-facing affected symbol.
+ */
+export declare function toAffected(entry: CodegraphImpactEntry, limits: ProjectionLimits): AffectedView;
+/** One hop of a traced path. */
+export interface HopView extends SymbolView {
+    readonly via?: string;
+    readonly site_line?: number;
+}
+/**
+ * Project one traced hop.
+ * @param hop - the seam's hop record.
+ * @param limits - the caps to apply to free text.
+ * @returns the model-facing hop.
+ */
+export declare function toHop(hop: CodegraphTraceHop, limits: ProjectionLimits): HopView;
+//# sourceMappingURL=projection.d.ts.map

package/lib/projection.js

@@ -0,0 +1,68 @@
+/**
+ * Seam records to model-facing values. The tool owns this projection because the seam's vocabulary
+ * describes a graph while the model's describes code: `filePath`/`startLine` become `path`/`line`,
+ * an edge's kind becomes `via`, and the fields a model cannot act on — opaque node ids, index
+ * timestamps, provenance — are dropped rather than spent as tokens.
+ * @module @huanlin/dsh-plugin-codegraph-tool/projection
+ */
+/** Cut a string to a cap, marking the cut so a truncated value never reads as complete. */
+function clip(value, max) {
+    return value.length <= max ? value : `${value.slice(0, max)}…`;
+}
+/**
+ * Project one declaration.
+ * @param node - the seam's node record.
+ * @param limits - the caps to apply to free text.
+ * @returns the model-facing symbol.
+ */
+export function toSymbol(node, limits) {
+    return {
+        name: node.name,
+        qualified_name: node.qualifiedName,
+        kind: node.kind,
+        path: node.filePath,
+        line: node.startLine,
+        end_line: node.endLine,
+        language: node.language,
+        exported: node.isExported,
+        ...node.signature === undefined ? {} : { signature: clip(node.signature, limits.maxSignatureChars) },
+        ...node.docstring === undefined ? {} : { docstring: clip(node.docstring, limits.maxDocstringChars) },
+    };
+}
+/**
+ * Project one related declaration.
+ * @param relation - the seam's relation record.
+ * @param limits - the caps to apply to free text.
+ * @returns the model-facing relation.
+ */
+export function toRelation(relation, limits) {
+    return {
+        ...toSymbol(relation.node, limits),
+        via: relation.edge.kind,
+        ...relation.edge.line === undefined ? {} : { site_line: relation.edge.line },
+        site_count: relation.siteCount,
+    };
+}
+/**
+ * Project one impact entry.
+ * @param entry - the seam's impact record.
+ * @param limits - the caps to apply to free text.
+ * @returns the model-facing affected symbol.
+ */
+export function toAffected(entry, limits) {
+    return { ...toSymbol(entry.node, limits), via: entry.via, distance: entry.distance };
+}
+/**
+ * Project one traced hop.
+ * @param hop - the seam's hop record.
+ * @param limits - the caps to apply to free text.
+ * @returns the model-facing hop.
+ */
+export function toHop(hop, limits) {
+    return {
+        ...toSymbol(hop.node, limits),
+        ...hop.edge === undefined ? {} : { via: hop.edge.kind },
+        ...hop.edge?.line === undefined ? {} : { site_line: hop.edge.line },
+    };
+}
+//# sourceMappingURL=projection.js.map

package/lib/render.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Model-facing text for each operation's canonical value.
+ *
+ * Every line leads with `path:line` so a location can be acted on directly, and a truncated answer
+ * always says so — a capped list that reads as complete is worse than a short one, because the model
+ * concludes it has seen everything.
+ * @module @huanlin/dsh-plugin-codegraph-tool/render
+ */
+import type { CodegraphToolValue } from './schema.ts';
+/**
+ * Render one result as the text the model reads.
+ * @param value - the canonical value the operation returned.
+ * @returns the rendered text.
+ */
+export declare function renderCodegraph(value: CodegraphToolValue): string;
+//# sourceMappingURL=render.d.ts.map