dctx1.3.1

Crate map

View source · Edit on GitHub · Markdown · docs/CRATE-MAP.md · 1,899 words · updated

On this page

Static checkout guide for contributors and coding assistants. 40 non-fixture Cargo packages: 36 under crates/, one plugin, one desktop, and two standalone tools. Root Cargo.toml includes crates, plugins and desktop; each tool declares its own workspace. bindings/README.md describes planned bindings; root membership for Python/Node is commented out. Fixture manifests under tests are not product crates.

How to read the inventory#

Each row gives purpose, layer, direct first-party path dependencies, and direct external normal dependencies. none means std-only at that crate boundary; first-party only means no direct external normal dependency, not an assertion about the complete dependency closure. Dev/build dependencies are excluded. Optional and target-specific normal dependencies are explicitly marked. Resolved transitive dependencies and runtime behavior are unverified here.

Source convention: for every row named X, purpose is taken from crates/X/src/lib.rs:1 (first six lines), and dependency names from crates/X/Cargo.toml [dependencies]. These two paths are the row's evidence. Exceptions use the directory shown in the row. Desktop purpose comes from apps/dctx-desktop/README.md:3; its lib header has no purpose description. Layer labels are navigation classifications of those headers, using the accepted boundaries in docs/design/ARCHITECTURE-DECISIONS.md (DX-ARCH-01).

Shipped CLI path (v1)#

What the dctx binary (crates/dctx-cli) actually runs, as of v1. No refactor: the other crates stay in the workspace.

  • Shipped: dctx-cli and the crates/dctx facade session (index, find, grep, callers, callees, neighbors, skeleton, hubs, pack, read), with dctx-core (selection), dctx-hash, dctx-ports, dctx-pack, dctx-template, dctx-adapter-cache, dctx-adapter-fs (compatibility IO), dctx-map-model (records and rendering) and the dctx-lex-* extractors.
  • Request types only: dctx-map-query. The CLI imports Request, Verb, Direction, Format, AnswerBudget and EdgeKind; its Index engine is never called.
  • Internal or legacy (compiled as dependencies of dctx-map-query, not run by the CLI): the dctx-map-query Index engine, dctx-map-store, dctx-map-scan, dctx-map-resolve, dctx-map-segment, dctx-adapter-store; dctx-map-parse likewise. docs/SPEC-MAP-MODE.md sections 6–8 and 10 describe this engine.
  • Unstable (no stability promise in v1): dctx-plugin-host, dctx-plugin-platform, dctx-plugin-protocol, dctx-plugin-distribution and dctx-desktop-api. The default dctx-cli build enables the plugin runtime and the bundled Git plugin process; --no-default-features --features strict builds without them.

Core, engines and adapters#

Crate Purpose from header Layer Direct path dependencies Direct external normal dependencies
dctx-hash First-party SHA-256 content digests. pure core none none (std-only)
dctx-core Pure domain: ids, selection decisions, budgets, errors, pack facts and settings parsing. pure core dctx-hash first-party only
dctx-ports Boundary traits Source, FactStore, Cache, Clock, Cancellation; in-memory implementations and spies. pure core dctx-core first-party only
dctx-map-model IO-free map identities, byte spans, precision, provenance and answers. pure core dctx-hash serde, serde_json (optional wire-json, enabled by default)
dctx-map-segment Pure safe codec for immutable map index segments. pure core dctx-hash thiserror
dctx-template Pure DTS v1 renderer and v2 ContextPlan compiler. mode engine dctx-core, dctx-hash first-party only
dctx-pack Pack snapshot and diff engine over injected ports, with no concrete IO. mode engine dctx-core, dctx-hash, dctx-ports first-party only
dctx-map-scan Model-independent scan privacy rules. mode engine none sha2, thiserror
dctx-map-parse Per-file syntax facts; PureParser over lexers, optional tree-sitter oracle. lexer/parser dctx-map-model, dctx-lex-rust, dctx-lex-js, dctx-lex-md, dctx-lex-py, dctx-lex-go, dctx-lex-java, dctx-lex-c, dctx-lex-cfg, dctx-lex-cs, dctx-lex-kt, dctx-lex-rb, dctx-lex-php, dctx-lex-swift sha2, thiserror; optional: tree-sitter, tree-sitter-rust, tree-sitter-md, tree-sitter-javascript, tree-sitter-typescript (syntax-tree-sitter)
dctx-map-resolve Pure symbol resolution and move detection. mode engine dctx-map-model thiserror
dctx-map-store Persistent graph facts, pack snapshots and content-addressed comparison cache. adapter dctx-core, dctx-hash, dctx-map-model, dctx-ports rusqlite (bundled), thiserror, serde_json
dctx-map-query Incremental indexing and bounded traversal; wires scan, parse, resolve and store APIs. mode engine dctx-map-model, dctx-map-scan, dctx-map-parse, dctx-map-resolve, dctx-map-store, dctx-map-segment, dctx-ports, dctx-adapter-fs, dctx-adapter-store, dctx-adapter-cache, dctx-core, dctx-hash thiserror, serde, serde_json
dctx-adapter-fs Confined filesystem Source adapter; selection before content. adapter dctx-hash thiserror
dctx-adapter-store Filesystem publication of immutable map segments and manifest generations. adapter dctx-hash, dctx-map-segment thiserror
dctx-adapter-cache Cache quotas, leases, expiry, persisted ledger and bounded auto-clean. adapter dctx-core, dctx-hash, dctx-ports thiserror

Lexers and structural extractors#

Purpose below retains the language and extractor role from each lib header. Several headers say “zero-dependency”; manifests qualify that statement: the model-dependent lexers have first-party direct dependencies, and dctx-map-model defaults to external JSON dependencies. Do not infer an external-free closure from the header wording.

Crate Purpose from header Layer Direct path dependencies Direct external normal dependencies
dctx-lex-rust Structural Rust extractor built on syn. lexer/parser none proc-macro2, quote, syn, thiserror
dctx-lex-js Hand-written JavaScript and TypeScript structural extractor. lexer/parser dctx-hash, dctx-map-model first-party only
dctx-lex-md Hand-written Markdown structure extractor. lexer/parser none none (std-only)
dctx-lex-py Hand-written Python structural extractor. lexer/parser dctx-hash, dctx-map-model first-party only
dctx-lex-go Hand-written Go structural extractor. lexer/parser dctx-hash, dctx-map-model first-party only
dctx-lex-java Hand-written Java structural extractor. lexer/parser dctx-hash, dctx-map-model first-party only
dctx-lex-c Hand-written C and C++ structural extractor. lexer/parser dctx-hash, dctx-map-model first-party only
dctx-lex-cfg Hand-written configuration structural extractor (JSON, TOML, YAML). lexer/parser dctx-hash, dctx-map-model first-party only
dctx-lex-cs Hand-written C# structural extractor. lexer/parser dctx-hash, dctx-map-model first-party only
dctx-lex-kt Hand-written Kotlin structural extractor. lexer/parser dctx-hash, dctx-map-model first-party only
dctx-lex-rb Hand-written Ruby structural extractor. lexer/parser dctx-hash, dctx-map-model first-party only
dctx-lex-php Hand-written PHP structural extractor. lexer/parser dctx-hash, dctx-map-model first-party only
dctx-lex-swift Hand-written Swift structural extractor. lexer/parser dctx-hash, dctx-map-model first-party only

Plugin infrastructure, facade and surfaces#

Crate Purpose from header Layer Direct path dependencies Direct external normal dependencies
dctx-ed25519 Ed25519 verification for plugin trust, via audited ed25519-dalek. pure core none ed25519-dalek
dctx-plugin-protocol Std-only codec and typed records for frozen plugin API v1. plugin none none (std-only)
dctx-plugin-host Plugin host domain and brokers; authority, receipts, resources, lifecycle and hooks. plugin dctx-hash, dctx-plugin-protocol first-party only
dctx-plugin-platform Native plugin admission and platform security primitives; general native launches fail closed. adapter dctx-hash, dctx-plugin-protocol thiserror; Linux-only: rustix, landlock, seccompiler (target dependency section)
dctx-plugin-distribution Plugin installer, trust and discovery client: signed manifests, offline bundles, atomic activation. plugin dctx-ed25519, dctx-hash, dctx-plugin-protocol first-party only
dctx-plugin-git (plugins/dctx-plugin-git/) Bundled git plugin: local .gitignore protection and brokered git add .gitignore. plugin dctx-plugin-protocol first-party only
dctx Stable library facade for pack, map, templates, cache and optional plugin host. facade dctx-adapter-cache, dctx-core, dctx-hash, dctx-lex-js, dctx-lex-md, dctx-map-model, dctx-pack, dctx-ports, dctx-template; optional: dctx-lex-rust, dctx-plugin-host, dctx-plugin-platform, dctx-plugin-protocol first-party only
dctx-cli Library surface for cache administration; dctx binary wires the same modules. surface dctx, dctx-adapter-cache, dctx-core, dctx-map-query, dctx-plugin-distribution, dctx-plugin-protocol, dctx-template; optional: dctx-plugin-git first-party only
dctx-desktop-api Desktop engine seam for snapshots, settings, recent projects and plugin management. surface dctx, dctx-plugin-distribution, dctx-template serde, serde_json
dctx-desktop (apps/dctx-desktop/src-tauri/) Cross-platform GUI for dctx — Directory Context Generator (app README). surface dctx-desktop-api, dctx-plugin-distribution, dctx-plugin-protocol tauri, tauri-plugin-shell, tauri-plugin-dialog, tauri-plugin-clipboard-manager, serde, serde_json, tokio, chrono, dirs
architecture-bench (tools/architecture-bench/) Baseline for current dctx map mode. tool dctx-map-query serde, serde_json, sha2, thiserror
plugin-index (tools/plugin-index/) Local public-index validator for plugins. tool dctx-ed25519, dctx-hash thiserror

Tool purpose evidence: each tool's src/lib.rs:1; dependencies: its Cargo.toml. Plugin purpose evidence: plugins/dctx-plugin-git/src/lib.rs:1. Desktop dependencies: apps/dctx-desktop/src-tauri/Cargo.toml. tauri-build is a desktop build dependency, outside the normal-dependency columns. Linux plugin dependencies are the one target-specific addition above. The facade does not directly depend on dctx-map-query: do not turn an intended architectural boundary into an invented Cargo edge. Its optional Rust extractor uses syntax-rust; plugin runtime dependencies use plugin-runtime.

Dependency picture: core toward consumers#

This is a selected-edge tree, not an exhaustive DAG. Children consume parents; repeated nodes have other inputs listed in the inventory. Every edge shown is a direct path dependency in the child's manifest. Braces group sibling crates.

dctx-hash
|-- dctx-core
|   |-- dctx-ports
|   |   `-- dctx-pack
|   |       `-- dctx
|   |           |-- dctx-cli
|   |           `-- dctx-desktop-api
|   |               `-- dctx-desktop
|   `-- dctx-template --> {dctx, dctx-cli, dctx-desktop-api}
|-- dctx-map-model
|   |-- dctx-lex-{js,py,go,java,c,cfg,cs,kt,rb,php,swift}
|   |   `-- dctx-map-parse <-- {dctx-lex-rust, dctx-lex-md}
|   |       `-- dctx-map-query
|   |           |-- dctx-cli
|   |           `-- architecture-bench
|   |-- dctx-map-resolve --> dctx-map-query
|   `-- dctx-map-store --> dctx-map-query
|-- dctx-map-segment
|   `-- dctx-adapter-store --> dctx-map-query
|-- dctx-adapter-fs --> dctx-map-query
|-- dctx-adapter-cache --> {dctx, dctx-cli, dctx-map-query}
|-- dctx-plugin-host --> dctx [optional]
|-- dctx-plugin-platform --> dctx [optional]
|-- dctx-plugin-distribution --> {dctx-cli, dctx-desktop-api, dctx-desktop}
`-- plugin-index
dctx-map-scan --> dctx-map-query
dctx-ed25519 --> {dctx-plugin-distribution, plugin-index}
dctx-plugin-protocol
`-- {dctx-plugin-host, dctx-plugin-platform, dctx-plugin-distribution,
     dctx-plugin-git, dctx [optional], dctx-cli, dctx-desktop}
dctx-plugin-git --> dctx-cli [optional]

Language wiring#

Authoritative variants and extension selection: crates/dctx-map-parse/src/domain/facts.rs:8 (Language, for_path). Dispatch: crates/dctx-map-parse/src/adapters/mod.rs:40 (PureParser). Adapter paths below are relative to crates/dctx-map-parse/src/adapters/; each file imports the named lexer. These are all 13 dctx-lex-* packages.

Language variant(s) Lexer crate Adapter
Rust dctx-lex-rust rust.rs
JavaScript, TypeScript, Tsx dctx-lex-js javascript.rs
Markdown dctx-lex-md markdown.rs
Python dctx-lex-py python.rs
Go dctx-lex-go go.rs
Java dctx-lex-java java.rs
C (C and C++) dctx-lex-c c.rs
Config (JSON/JSONC, TOML, YAML) dctx-lex-cfg config.rs
CSharp dctx-lex-cs csharp.rs
Kotlin dctx-lex-kt kotlin.rs
Ruby dctx-lex-rb ruby.rs
Php dctx-lex-php php.rs
Swift dctx-lex-swift swift.rs
Unknown none mod.rs fallback: module-only

The optional TreeSitterParser in adapters/mod.rs:74 uses grammars for Rust, JavaScript/TypeScript/Tsx and Markdown. Other known languages take the pure adapters; Unknown takes fallback. This is an oracle feature, not the default.

Cross-cutting rules and evidence locations#

  • No Git in the core: product contracts records the core ban and plain-text .gitignore exception. Enforcement evidence: crates/dctx-map-query/tests/no_git.rs (source spawn audit, PATH trap and source-port privacy tests). VCS effects belong to the plugin, not the core.
  • Privacy, selection before content: crates/dctx-adapter-fs/tests/privacy.rs uses read spies to check ignored/omitted paths remain unopened; crates/dctx-map-query/tests/source_privacy.rs checks secrets, ignored files, traversal and symlinks, with an included-file positive control.
  • Pure domain boundary: crates/dctx-core/src/lib.rs:1 points to crates/dctx-core/tests/purity.rs, which checks every source module without a directory exemption. Comments and unit-test tails are excluded from the IO scan. The crate retains its first-party dctx-hash dependency.
  • Plugin PP1–PP10: historical PP matrix maps tests, formal evidence and gaps: PP1 authority narrows; PP2 excluded-source privacy; PP3 effect audit; PP4 protocol binding; PP5 no blind replay; PP6 strict isolation; PP7 bounded resources; PP8 lifecycle progress; PP9 install integrity; PP10 hook order/result truth. The matrix is dated scout evidence, not a fresh passing test result or certification of today's product acceptance.
  • Legacy removal: The migration removed the core IO wrappers and their exports. legacy removal inventory remains the historical inventory; compatibility record maps retired families to retained tests. Pack codecs, template rendering, filesystem adapters and CLI compatibility IO own the replacements. Pure core modules, settings and template assets remain.

Validation commands#

Use TESTING.md for the current commands, toolchains, matrix and exclusions. Desktop backend checks use tools/desktop-check.sh; browser evidence uses bun run e2e from apps/dctx-desktop. A skipped desktop check does not qualify a desktop release. Standalone tools have their own workspaces and checks.