dchains

Language-agnostic code annotation parser. Extracts @dc: tags from source files into dependency maps for LLMs and humans.

Why

LLMs break production when they can't see the blast radius of a change. DChains solves this by mapping every module, dependency, and construct in your project into a format both machines and humans can read.

How It Works

Two-part workflow:

1. Annotate — An LLM skill (or you, manually) adds @dc: comments to your source files describing modules, dependencies, and constructs
2. Parse — dchains extracts those annotations into output files

Quick Start

# Initialize dchains in your project
npx dchains init

# If using Claude Code, the skill is auto-installed.
# Ask Claude to "map this project" — it will annotate your files.

# Parse annotations into output files
npx dchains

Output Files

DChains generates four files:

| File | Purpose | |------|---------| | dchains.ctx | LLM context file. Feed this to an LLM so it can see every module, dependency, and construct in your project. Shows the full blast radius of any change — forward deps (deps:) and reverse deps (used-by:). | | dchains.json | Machine-readable JSON manifest. For tooling, CI integration, or building custom visualizations. | | dchains.html | Interactive D3.js constellation visualizer. Open in a browser to explore modules, layers, and dependency edges visually. | | dchains.diagnostics.json | Validation report. Warnings for broken references, orphan modules, stale dependencies, and coverage stats. |

Annotation Basics

Annotations live in source code comments using the @dc: prefix. The comment character adapts to the language:

// @dc:module Auth/Login
// @dc:description Handle user login flow
// @dc:layer Entry
// @dc:depends-on Auth/Session, Service/API
// @dc:exposes LoginPage

// @dc:def fn validateCredentials
// @dc:description Check email format and password strength
// @dc:param email string - User email address
// @dc:returns boolean
// @dc:async

# @dc:module Data/Pipeline
# @dc:description ETL pipeline for user analytics
# @dc:layer Data

-- @dc:module Data/Queries
-- @dc:description Core database queries
-- @dc:layer Data

Key Tags

Module level (top of file):

• @dc:module — Module name (e.g., Auth/Login)
• @dc:description — What this module does
• @dc:layer — Entry, UI, Logic, Service, Data, Config, or Utility
• @dc:depends-on — Other modules this depends on
• @dc:exposes — Public exports
• @dc:consumes — External services (e.g., Firebase:Auth)

Construct level (above functions/classes):

• @dc:def — Type and name (e.g., fn validateEmail)
• @dc:description — What it does
• @dc:param, @dc:returns, @dc:throws
• @dc:async, @dc:pure, @dc:idempotent
• @dc:uses, @dc:reads, @dc:writes — Cross-references

See the full tag reference in ANNOTATION-GUIDE.md or the bundled skill file.

CLI Usage

# Parse current directory
dchains

# Parse a specific project
dchains parse /path/to/project

# Initialize in a new project
dchains init

# Custom output directory
dchains --output ./docs

# Ignore additional directories
dchains --ignore vendor --ignore generated

# Version and help
dchains --version
dchains --help

Configuration

dchains.config.json in the project root:

{
  "project": "my-project",
  "description": "What this project does",
  "ignore": ["vendor", "generated"],
  "output": "."
}

| Field | Purpose | |-------|---------| | project | Project name (shown in output headers) | | description | One-line description | | ignore | Directories to skip during scanning | | output | Where to write output files (default: project root) |

Claude Code Integration

When you run dchains init in a project that has .claude/skills/, the annotation skill is automatically installed. This teaches Claude how to annotate your codebase with @dc: tags.

If .claude/skills/ doesn't exist, the skill is placed as DCHAINS-SKILL.md in your project root. You can feed this to any LLM as annotation instructions.

Zero Dependencies

DChains uses only Node.js built-in modules. No npm dependencies to install, audit, or update.

License

MIT