module.md

Module View

The docgraph project is organized into several distinct modules, separating the core domain logic, the command-line interface, the language server, and the editor integration.

Module Structure Overview

graph TD
    subgraph "Editor Layer"
        VSEX["vsix (VS Code Extension)"]
    end

    subgraph "Application Layer"
        CLI["cli (Command Line Interface)"]
        LSP["lsp (Language Server)"]
    end

    subgraph "Domain Layer (core)"
        CORE["core (Business Logic)"]
        PARSE["parse (Markdown Parsing)"]
        LINT["lint (Validation Rules)"]
        COLL["collect (Block Collection)"]
    end

    VSEX -- LSP --> LSP
    CLI --> CORE
    LSP --> CORE
    CORE --> COLL
    COLL --> PARSE
    COLL --> LINT

Loading

Core Library

The core module contains the fundamental logic for analyzing documentation graphs.

• types: Defines the data structures for Node, RefUse, and Graph.
• parse: Responsible for extracting {document} blocks and HTML anchors from Markdown files.
• collect: Orchestrates the scanning of directories and aggregation of nodes.

Realizes

• FR_CORE_VALID_REF (Valid References)
• FR_CORE_UNIQUE (Unique Node IDs)
• FR_CORE_AUDIT (Audit Logging)
• FR_CORE_AUTH (Authentication)
• FR_CORE_TEMPLATE_VALIDATION (Template Validation)
• FR_CORE_CONFIGURATION (Configuration)
• NFR_AVAILABILITY (System Availability)
• IF_CONFIG (docgraph.toml Configuration)

Validation Rules

• lint: Implements the validation engine and individual rules (DG001-DG006).

Realizes

• FR_CORE_TEMPLATE_VALIDATION (Template Validation)

Graph Logic

• graph: Manages the construction and traversal of the dependency graph.

Realizes

• FR_CORE_VALID_REF (Valid References)
• FR_CORE_UNIQUE (Unique Node IDs)

Error Definitions

• error: Defines the unified error types and handling strategies.

Realizes

• CC_ERROR_HANDLING (Error Handling Strategy)

CLI Application

The cli module handles user interaction via the terminal.

• handlers: Contains the logic for each CLI command (check, describe, graph, rule).
• output: Manages the formatting of results (Text, JSON).

Realizes

• FR_CLI_LINT (Lint Command)
• FR_CLI_GRAPH (Graph Command)
• FR_CLI_LIST (List Capability)
• FR_CLI_TRACE (Trace Capability)
• FR_CLI_DESCRIBE (Describe Command)
• FR_CLI_TYPE (Type Command)
• FR_CLI_VERSION (Version Command)
• FR_CLI_HELP (Help Command)
• FR_CLI_QUERY (Query Command)
• FR_INSTALL_MANUAL (Manual Installation)
• FR_INSTALL_BINARY (Binary Installation Support)
• FR_INSTALL_PREK (Pre-commit Hook Support)
• IF_CLI (Command Line Interface)

LSP Library

The lsp module provides the Language Server Protocol implementation.

Realizes

• FR_LSP_GOTO (Go to Definition)
• FR_LSP_HOVER (Hover Information)
• FR_LSP_COMP (Auto-completion)
• FR_LSP_REFS (Find References)
• FR_LSP_RENAME (Symbol Rename)
• FR_LSP_HIERARCHY (Call Hierarchy)
• FR_LSP_DOC_SYMBOL (Document Symbol)
• FR_LSP_WS_SYMBOL (Workspace Symbol)
• FR_LSP_SUPPORT (LSP Server)
• NFR_LATENCY (System Latency)
• CC_COVERAGE (3. Code Coverage Standards)

LSP Server

• server: Implements the main event loop and lifecycle management.

Realizes

• FR_LSP_SUPPORT (LSP Server)

LSP Handlers

• handlers: Implements LSP capabilities such as textDocument/definition, textDocument/references, and textDocument/hover.

Realizes

• CC_THIN_HANDLERS (Thin Handlers Pattern)

VS Code Extension

The vsix module is a TypeScript-based project that acts as the LSP client.

• src/extension.ts: Manages the lifecycle of the docgraph language server and registers editor-specific commands.

Realizes

• FR_VSC_LSP_CLIENT (LSP Client Integration)
• FR_VSC_BINARY_PATH (Binary Path Configuration)
• FR_VSC_MARKDOWN_ACTIVATION (Markdown Activation)
• FR_VSC_SERVER_LIFECYCLE (Server Lifecycle Commands)
• NFR_VSCODE_PORTABILITY (Cross-platform Portability)
• NFR_VSCODE_PACKAGING (Lightweight Packaging)

Zed Editor Extension

The zed-extension is a WASM-based extension for the Zed editor.

• zed-extension/src/lib.rs: Implements the zed::Extension trait and the language_server_command to bridge Zed and the docgraph binary.

Realizes

• FR_INSTALL_EXT_ZED (Zed Editor Extension)
• IF_ZED_UI (Zed UI)

CI/CD Pipelines

The .github directory contains the CI/CD pipeline configuration.

• .github/workflows/ci.yml: Automated validation and testing on pull requests.
• .github/workflows/codeql.yml: Static application security testing.
• .github/dependabot.yml: Automated dependency updates.

Realizes

• FR_DEV_CI (Automated Validation)
• FR_DEV_STANDARDS (Development Standards)
• CC_CICD (CI/CD Pipeline)
• CC_CONVENTIONAL_COMMITS (Commit Messages)
• CC_SEMANTIC_VERSIONING (Versioning)

Claude Code Plugin

The docgraph-plugin provides a Model Context Protocol (MCP) server for Claude Code.

• skills/docgraph: Defines the tools and resources available to the AI agent.
• .claude-plugin: Contains the plugin manifest and capability definitions.

Realizes

• IF_CLAUDE_CODE (Interface: Claude Code Plugin)

Dev Container

The .devcontainer directory contains the development environment configuration.

• devcontainer.json: Defines the container image, features, and tool installations.
• postCreateCommand: Installs additional tools (docgraph, Claude Code).
• Extensions: Pre-configured VS Code extensions for Rust, TOML, debugging, and AI assistance.

Realizes

• CC_DEV_ENV (Development Environment)

Test Infrastructure

The tests directory and test utilities.

• tests/: Integration and E2E tests.
• src/test_utils: Helper functions and mocks for testing.

Realizes

• CC_TESTING_STRATEGY (Testing Strategy)