dsh-graphlint

DeepSeek Harness plugin bundle for graphlint — dead-code detection for AI-generated codebases.

Installing this bundle gives every agent in the profile three tools (graphlint_query, graphlint_build, graphlint_config) plus a graphlint skill describing when and how to use them.

Requirements

• Node.js >= 20.
• A DeepSeek Harness profile (dsh plugin initializes one on first use).
• The graphlint CLI on PATH (pip install graphlint) or inside the project's virtualenv (env/, .venv/, venv/ are probed automatically).

Supported DSH core

The bundle imports defineTool from @deepseek-ai/dsh-tools at runtime — an out-of-tree plugin resolves it from the running installation (it is one of the plugin manager's protected modules) — and type-checks its tool definitions against it. Declared compatibility:

| Package | Range | |---------|-------| | @deepseek-ai/dsh-tools | >=0.1.0-rc.6 <0.3 | | @deepseek-ai/cordis | >=4.0.5-alpha.1 <5 |

Development and CI compile against the exact published versions pinned in devDependencies (currently the 0.2.1-alpha.2 core), so a contract change in any seam the plugin consumes (ctx.tools, ctx.subprocess, ctx.fs, ctx.skills, ctx.jobs, ctx.workingDirectory, ctx.timer) fails the build instead of failing a live tool call. Bump the pins with the core.

Install

Install the published bundle into a DeepSeek Harness profile:

dsh plugin --profile web add dsh-graphlint

# or via the graphlint CLI (requires dsh on PATH):
graphlint install dsh --profile web

Then restart the profile (and refresh the browser page). The bundle's patch layer inserts the plugin row at the profile root; you can address it by id dsh-graphlint in your own cordis.patch.yml (e.g. to disable it per profile).

Development / repository install (linking a local checkout):

# 1. Clone the repository and build the bundle
git clone https://github.com/AngelosZou/graphlint.git
cd graphlint/integrations/dsh
npm install
npm run build

# 2. Link the bundle into a profile (run from the repository root)
cd ..
dsh plugin --profile web add link:./integrations/dsh

# 3. Restart dsh web

Tools

| Tool | Purpose | |------|---------| | graphlint_query | Query the dependency graph for dead code, unused imports, write-only variables, and other warnings. Fast incremental mode; JSON result. Common filters: warn_types, graph_id, exclude_clean, include_tests, public_as_entry. | | graphlint_build | Full or incremental index rebuild as a background job (poll with job_output). | | graphlint_config | show / diff / get / set entries in the project's .graphlint/config.json, plus add-entry-rule / remove-entry-rule / add-exclude / remove-exclude for custom entry rules and excludes. diff reports how the config differs from the shipped default rule template. |

The graphlint skill leads with these tools (they run inside the session working directory and return structured results); the canonical CLI guidance follows as reference.

root_dir restriction

Every tool accepts an optional root_dir. It must stay inside the session working directory (the default) — a hard guard rejects anything else with a clear error. Scanning a high-level root (such as a user home directory) makes graphlint build a huge first-time index and can block for many minutes.

The default root comes from the workingDirectory service (the seam that owns a session's effective directory and repairs a deleted project), falling back to the session header's original cwd and then to the harness process directory. graphlint_query and graphlint_config then pass --root-dir; graphlint_build and graphlint config run the CLI with that directory as their working directory, because those subcommands read their own cwd.

Optional Secondary working directories (dsh-multi-folder)

When the dsh-multi-folder plugin is installed and the user has configured secondary working directories for the session, those directories automatically become valid root_dir values for all three tools: the analysis root is accepted inside any configured secondary directory, graphlint runs with that directory as its working directory, and the index lands in its .graphlint/. A relative root_dir still resolves against the primary session workspace.

This compatibility is automatic and optional. Each tool probes ctx.get('multiFolder') at call time and nothing else changes:

• multi-folder absent, unconfigured, incompatible, or throwing → the plugin behaves exactly as if it did not exist (the guard falls back to the session working directory, and the refusal message keeps its original wording);
• multi-folder present → a refusal still names the configured secondary directories and the /multi-folder command that adds one, so the model learns the valid roots instead of retrying blindly.

The multiFolder service and the workingDirectory service are both optional seams, read through ctx.get and never declared in inject, so neither plugin becomes a hard dependency of the other.

Development

cd integrations/dsh
npm install          # first time only; afterwards npm ci
npm run build        # generate-skill.mjs + tsc → lib/
npm test             # node --test lib/test/

Type-checking is part of npm run build, and the seam types come from the real @deepseek-ai/* packages rather than hand-written copies — build failure is the signal that a core contract moved. src/types.ts re-exports them and narrows the two optional seams; nothing in src/ restates an engine-shaped service a second time.

The test suite covers the pure logic layers (root guard, argv construction, JSON parsing), the optional multi-folder probe and its end-to-end tool wiring (root resolution and spawned CLI cwd, with and without the peer plugin), the workingDirectory root resolution and its fallbacks, the background-job owner type, and manifest/patch contract checks. A committed package-lock.json is required (CI runs npm ci).

If the sandbox forbids the Node test runner's per-file child processes (spawn EPERM on a Windows confined run), run the same suite in one process:

node --test --experimental-test-isolation=none "lib/test/**/*.test.js"