drft

A structural integrity checker for linked file systems.

Files link to other files. When a target changes, the files that depend on it may no longer be accurate. drft tracks these dependencies and flags what needs review.

It treats your directory as a graph — files are nodes, links are edges — and validates the structure. drft check catches broken links, cycles, and staleness. drft lock snapshots hashes so it can detect when a dependency changes and flag everything downstream. drft impact <file> tells you what to review when you touch a file.

A subdirectory with its own drft.toml becomes a child graph with its own boundary. Links into it from outside are violations unless you declare public interface files. That's the model — everything else is configuration.

Install

cargo install drft-cli    # via Cargo
npm install -g drft-cli   # via npm

Or download a prebuilt binary from GitHub Releases.

The binary is called drft.

Quick start

drft init                 # create a drft.toml
drft check                # validate the graph
drft lock                 # snapshot file hashes
drft check                # now detects staleness too

How it works

drft discovers files matching your include patterns, runs parsers to extract links, and builds a dependency graph. It then validates the graph against rules:

• Broken links — edges to files that don't exist (dangling-edge)
• Cycles — circular dependencies (directed-cycle)
• Staleness — files changed since last lock, including transitive dependents (stale)
• Boundary escapes — links that reach outside the graph (boundary-violation)
• Encapsulation — links into a child graph that bypass its interface (encapsulation-violation)

drft ships with built-in rules covering structural integrity, plus support for custom rules via external commands. All rules default to warn. Override to error for CI enforcement or off to suppress.

Underneath the rules, drft computes structural analyses — degree, centrality, connected components, depth, and more. Rules consume these analyses; you can also query them directly with drft report.

Commands

Most commands support --format json, --recursive, and --watch. Run drft --help for the full flag reference.

Configuration

drft.toml in the directory root:

include = ["*.md"] # which files become nodes (default)
exclude = ["drafts/*"] # also respects .gitignore

[parsers.markdown] # built-in parser, no config needed

[rules]
stale = "error" # escalate for CI
orphan-node = "off" # suppress if expected

[rules.orphan-node] # or use table form for options
severity = "warn"
ignore = ["README.md"]

Parsers extract links from files. drft includes markdown and YAML frontmatter parsers; you can add custom parsers for any format. See the configuration reference for all options.

Graph nesting

A directory with a drft.toml is a graph. A child directory with its own config is a child graph — it appears as a single node in the parent and is checked independently.

project/
  drft.toml
  index.md
  docs/
    overview.md
  research/
    drft.toml          # child graph
    overview.md
    internal.md

Use --recursive to check or lock all graphs in one command. Declare [interface] in a child's drft.toml to specify which files are accessible from parent graphs.

LLM integration

All commands support --format json with actionable fix fields in every diagnostic. drft impact is designed for agent workflows — it shows which files to review after an edit, sorted by priority.

This repo dogfoods the pattern with Claude Code hooks. See CLAUDE.md for the agent instructions and .claude/settings.json for the hook configuration.

Docs

The full documentation covers parsers, graph construction, structural analyses, rules, and configuration.

License

MIT