diff --git a/.prettierignore b/.prettierignore index 9516d68..050f3d2 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,7 +1 @@ -node_modules -target -.git -out -dist -*.lock - +doc/templates/** diff --git a/doc/actors/systems.md b/doc/actors/systems.md index 86977db..65fd7dc 100644 --- a/doc/actors/systems.md +++ b/doc/actors/systems.md @@ -11,6 +11,10 @@ An automated Continuous Integration system that runs Docgraph checks. - Run automated tests. - Verify relationship rules. +### Participates in + +- [UC_CLI_ANALYSIS (CLI Traceability Analysis)](../usecases/cli-analysis.md#UC_CLI_ANALYSIS) + ## AI Agent @@ -21,3 +25,7 @@ An AI agent that consumes the document graph to build knowledge and assist users - Assist in documentation writing. - Verify rule compliance. + +### Participates in + +- [UC_AI_ASSISTANCE (AI-Assisted Documentation)](../usecases/ai-assistance.md#UC_AI_ASSISTANCE) diff --git a/doc/actors/users.md b/doc/actors/users.md index 1847266..5249e50 100644 --- a/doc/actors/users.md +++ b/doc/actors/users.md @@ -11,6 +11,10 @@ A human user who interacts with the Docgraph CLI or VS Code extension. - Read documentation. - Browse the graph. +### Participates in + +- [UC_CLI_ANALYSIS (CLI Traceability Analysis)](../usecases/cli-analysis.md#UC_CLI_ANALYSIS) + ## Developer @@ -21,3 +25,15 @@ A software developer who writes code and specifications, and runs Docgraph local - Write specifications. - Maintain relationships. + +### Participates in + +- [UC_WRITE (Write Specifications)](../usecases/writing-specification.md#UC_WRITE) +- [UC_CLI_ANALYSIS (CLI Traceability Analysis)](../usecases/cli-analysis.md#UC_CLI_ANALYSIS) +- [UC_INSTALL_MANUAL (Install Manual Setup)](../usecases/setup.md#UC_INSTALL_MANUAL) +- [UC_INSTALL_BINARY (Install via Binary Script)](../usecases/setup.md#UC_INSTALL_BINARY) +- [UC_CLAUDE_INSTALL (Install Claude Plugin)](../usecases/setup.md#UC_CLAUDE_INSTALL) +- [UC_VSCODE_INSTALL (Install VS Code Extension)](../usecases/setup.md#UC_VSCODE_INSTALL) +- [UC_ZED_INSTALL (Install Zed Extension)](../usecases/setup.md#UC_ZED_INSTALL) +- [UC_PREK_SETUP (Set Up Development Hooks)](../usecases/setup.md#UC_PREK_SETUP) +- [UC_EDITOR_LSP (Editor Support via LSP)](../usecases/lsp-editing.md#UC_EDITOR_LSP) diff --git a/doc/architecture/design/cicd.md b/doc/architecture/design/cicd.md index 91e3e34..bcfc8a7 100644 --- a/doc/architecture/design/cicd.md +++ b/doc/architecture/design/cicd.md @@ -18,10 +18,6 @@ validated, tested, and released. - [ADR_CI_ENV_PARITY (CI Environment Parity)](../../decisions/ci-env-parity.md#ADR_CI_ENV_PARITY) To minimize environmental discrepancies. -### Realized by - -- [MOD_CICD (CI/CD Pipelines)](../view/module.md#MOD_CICD) - Triggered when PR is merged to `main`. - **Publish**: (Planned) Publish binary or crate to registry. diff --git a/doc/architecture/design/dependency-rule.md b/doc/architecture/design/dependency-rule.md index 7e3b0a6..5a7eafe 100644 --- a/doc/architecture/design/dependency-rule.md +++ b/doc/architecture/design/dependency-rule.md @@ -1,23 +1,20 @@ +# The Dependency Rule + ## The Dependency Rule -Dependencies must point inwards, towards high-level policies. - -**Direction:** - -- **Outer Layers** (Infrastructure, adapters) depend on **Inner Layers** (Use Cases, Entities). -- **Inner Layers** MUST NOT depend on **Outer Layers**. +Source code dependencies must point only inward, toward higher-level policies. -**Core Layer Independence:** +**Rules:** -The `src/core/` module contains only domain types and business logic. It has NO references to CLI or LSP types. +1. Nothing in an inner circle (Core) can know anything at all about something in an outer circle (Handlers, UI). +2. The name of something declared in an outer circle must not be mentioned by the code in the an inner circle. -**Handler Layer Dependency:** +### Decided by -CLI and LSP handlers import from Core, but Core never imports from handlers. +- [ADR_LAYERED_ARCH (Layered Architecture)](../../decisions/layered-architecture.md#ADR_LAYERED_ARCH) -### Decided by +### Reflected in (Optional) -- [ADR_LAYERED_ARCH (Layered Architecture)](../../decisions/layered-architecture.md#ADR_LAYERED_ARCH) To enforce - directional dependency. +- [NFR_EXT (Modular Design)](../../requirements/non-functional/extensibility.md#NFR_EXT) diff --git a/doc/architecture/design/development-norm.md b/doc/architecture/design/development-norm.md index 39df1d9..f61ca73 100644 --- a/doc/architecture/design/development-norm.md +++ b/doc/architecture/design/development-norm.md @@ -30,10 +30,6 @@ Defined in [.devcontainer/devcontainer.json](../../../.devcontainer/devcontainer - [ADR_CI_ENV_PARITY (CI Environment Parity)](../../decisions/ci-env-parity.md#ADR_CI_ENV_PARITY) To ensure consistent development experience. -### Realized by - -- [MOD_DEV_CONTAINER (Dev Container)](../view/module.md#MOD_DEV_CONTAINER) - --- @@ -56,10 +52,6 @@ generation and versioning. - **test**: Adding missing tests or correcting existing tests - **chore**: Changes to the build process or auxiliary tools and libraries -### Realized by - -- [MOD_CICD (CI/CD Pipelines)](../view/module.md#MOD_CICD) - --- @@ -75,7 +67,3 @@ Given a version number **MAJOR.MINOR.PATCH**, increment the: 1. **MAJOR** version when you make incompatible API changes. 2. **MINOR** version when you add functionality in a backwards compatible manner. 3. **PATCH** version when you make backwards compatible bug fixes. - -### Realized by - -- [MOD_CICD (CI/CD Pipelines)](../view/module.md#MOD_CICD) diff --git a/doc/architecture/design/error-handling.md b/doc/architecture/design/error-handling.md index a54cbd6..5189f07 100644 --- a/doc/architecture/design/error-handling.md +++ b/doc/architecture/design/error-handling.md @@ -78,7 +78,3 @@ Errors automatically convert across boundaries: - [ADR_ERROR_HANDLING (Error Handling Strategy: thiserror for Core, anyhow for Binaries)](../../decisions/error-handling.md#ADR_ERROR_HANDLING) To unify error reporting. - -### Realized by - -- [MOD_CORE_ERRORS (Error Definitions)](../view/module.md#MOD_CORE_ERRORS) diff --git a/doc/architecture/design/testing.md b/doc/architecture/design/testing.md index a428b30..339bc4e 100644 --- a/doc/architecture/design/testing.md +++ b/doc/architecture/design/testing.md @@ -12,10 +12,6 @@ We employ a pyramid testing strategy to ensure reliability and velocity. 2. **Integration Tests (Middle)**: Verify component interactions. 3. **E2E Tests (Top)**: Verify full system behavior via LSP. -### Realized by - -- [MOD_TEST_INFRA (Test Infrastructure)](../view/module.md#MOD_TEST_INFRA) - --- @@ -30,11 +26,6 @@ Unit tests should cover all public functions and complex private logic. - **Speed**: Tests must run per commit. - **Coverage**: Aim for high branch coverage in core logic. -### Realized by - -- [MOD_CORE_RULES (Validation Rules)](../view/module.md#MOD_CORE_RULES) -- [MOD_CORE_GRAPH (Graph Logic)](../view/module.md#MOD_CORE_GRAPH) - --- @@ -53,11 +44,6 @@ E2E tests verify the system from the user's perspective (LSP client). - Rust standard test framework with a mock LSP client. -### Realized by - -- [MOD_LSP_SERVER (LSP Server)](../view/module.md#MOD_LSP_SERVER) -- [MOD_TEST_INFRA (Test Infrastructure)](../view/module.md#MOD_TEST_INFRA) - --- @@ -66,8 +52,6 @@ E2E tests verify the system from the user's perspective (LSP client). We use `cargo-llvm-cov` to measure test effectiveness. -**Realized by**: [MOD_LSP (LSP Library)](../../architecture/view/module.md#MOD_LSP) - **Running Coverage Locally:** 1. Install: `cargo install cargo-llvm-cov` diff --git a/doc/architecture/design/thin-handlers.md b/doc/architecture/design/thin-handlers.md index 7f87bc1..ee54903 100644 --- a/doc/architecture/design/thin-handlers.md +++ b/doc/architecture/design/thin-handlers.md @@ -22,7 +22,3 @@ Request handlers should be "thin," delegating business logic to core modules. - [ADR_THIN_HANDLERS (Thin Handlers)](../../decisions/thin-handlers.md#ADR_THIN_HANDLERS) To maintain separation of concerns. - -### Realized by - -- [MOD_LSP_HANDLERS (LSP Handlers)](../view/module.md#MOD_LSP_HANDLERS) diff --git a/doc/architecture/view/module.md b/doc/architecture/view/module.md index ac2393f..8545535 100644 --- a/doc/architecture/view/module.md +++ b/doc/architecture/view/module.md @@ -41,45 +41,103 @@ The `core` module contains the fundamental logic for analyzing documentation gra - **`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)](../../requirements/functional/core.md#FR_CORE_VALID_REF) +- [FR_CORE_UNIQUE (Unique Node IDs)](../../requirements/functional/core.md#FR_CORE_UNIQUE) +- [FR_CORE_AUDIT (Audit Logging)](../../requirements/functional/core.md#FR_CORE_AUDIT) +- [FR_CORE_AUTH (Authentication)](../../requirements/functional/core.md#FR_CORE_AUTH) +- [FR_CORE_TEMPLATE_VALIDATION (Template Validation)](../../requirements/functional/core.md#FR_CORE_TEMPLATE_VALIDATION) +- [FR_CORE_CONFIGURATION (Configuration)](../../requirements/functional/core.md#FR_CORE_CONFIGURATION) +- [NFR_AVAILABILITY (System Availability)](../../requirements/non-functional/performance.md#NFR_AVAILABILITY) +- [IF_CONFIG (docgraph.toml Configuration)](../../requirements/interfaces/interfaces.md#IF_CONFIG) + ### Validation Rules - **`lint`**: Implements the validation engine and individual rules (DG001-DG006). +### Realizes + +- [FR_CORE_TEMPLATE_VALIDATION (Template Validation)](../../requirements/functional/core.md#FR_CORE_TEMPLATE_VALIDATION) + ### Graph Logic - **`graph`**: Manages the construction and traversal of the dependency graph. +### Realizes + +- [FR_CORE_VALID_REF (Valid References)](../../requirements/functional/core.md#FR_CORE_VALID_REF) +- [FR_CORE_UNIQUE (Unique Node IDs)](../../requirements/functional/core.md#FR_CORE_UNIQUE) + ### Error Definitions - **`error`**: Defines the unified error types and handling strategies. +### Realizes + +- [CC_ERROR_HANDLING (Error Handling Strategy)](../design/error-handling.md#CC_ERROR_HANDLING) + ### CLI Application The `cli` module handles user interaction via the terminal. -- **`handlers`**: Contains the logic for each CLI command (`check`, `list`, `describe`, `graph`, `trace`, `rule`). +- **`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)](../../requirements/functional/cli.md#FR_CLI_LINT) +- [FR_CLI_GRAPH (Graph Command)](../../requirements/functional/cli.md#FR_CLI_GRAPH) +- [FR_CLI_LIST (List Capability)](../../requirements/functional/cli.md#FR_CLI_LIST) +- [FR_CLI_TRACE (Trace Capability)](../../requirements/functional/cli.md#FR_CLI_TRACE) +- [FR_CLI_DESCRIBE (Describe Command)](../../requirements/functional/cli.md#FR_CLI_DESCRIBE) +- [FR_CLI_TYPE (Type Command)](../../requirements/functional/cli.md#FR_CLI_TYPE) +- [FR_CLI_VERSION (Version Command)](../../requirements/functional/cli.md#FR_CLI_VERSION) +- [FR_CLI_HELP (Help Command)](../../requirements/functional/cli.md#FR_CLI_HELP) +- [FR_CLI_QUERY (Query Command)](../../requirements/functional/cli.md#FR_CLI_QUERY) +- [FR_INSTALL_MANUAL (Manual Installation)](../../requirements/functional/installation.md#FR_INSTALL_MANUAL) +- [FR_INSTALL_BINARY (Binary Installation Support)](../../requirements/functional/installation.md#FR_INSTALL_BINARY) +- [FR_INSTALL_PREK (Pre-commit Hook Support)](../../requirements/functional/installation.md#FR_INSTALL_PREK) +- [IF_CLI (Command Line Interface)](../../requirements/interfaces/interfaces.md#IF_CLI) + ### LSP Library The `lsp` module provides the Language Server Protocol implementation. +### Realizes + +- [FR_LSP_GOTO (Go to Definition)](../../requirements/functional/lsp.md#FR_LSP_GOTO) +- [FR_LSP_HOVER (Hover Information)](../../requirements/functional/lsp.md#FR_LSP_HOVER) +- [FR_LSP_COMP (Auto-completion)](../../requirements/functional/lsp.md#FR_LSP_COMP) +- [FR_LSP_REFS (Find References)](../../requirements/functional/lsp.md#FR_LSP_REFS) +- [FR_LSP_RENAME (Symbol Rename)](../../requirements/functional/lsp.md#FR_LSP_RENAME) +- [FR_LSP_HIERARCHY (Call Hierarchy)](../../requirements/functional/lsp.md#FR_LSP_HIERARCHY) +- [FR_LSP_DOC_SYMBOL (Document Symbol)](../../requirements/functional/lsp.md#FR_LSP_DOC_SYMBOL) +- [FR_LSP_WS_SYMBOL (Workspace Symbol)](../../requirements/functional/lsp.md#FR_LSP_WS_SYMBOL) +- [FR_LSP_SUPPORT (LSP Server)](../../requirements/functional/lsp.md#FR_LSP_SUPPORT) +- [NFR_LATENCY (System Latency)](../../requirements/non-functional/performance.md#NFR_LATENCY) +- [CC_COVERAGE (3. Code Coverage Standards)](../design/testing.md#CC_COVERAGE) + ### LSP Server - **`server`**: Implements the main event loop and lifecycle management. +### Realizes + +- [FR_LSP_SUPPORT (LSP Server)](../../requirements/functional/lsp.md#FR_LSP_SUPPORT) + ### LSP Handlers @@ -87,6 +145,10 @@ The `lsp` module provides the Language Server Protocol implementation. - **`handlers`**: Implements LSP capabilities such as `textDocument/definition`, `textDocument/references`, and `textDocument/hover`. +### Realizes + +- [CC_THIN_HANDLERS (Thin Handlers Pattern)](../design/thin-handlers.md#CC_THIN_HANDLERS) + ### VS Code Extension @@ -96,6 +158,15 @@ 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)](../../requirements/functional/vscode.md#FR_VSC_LSP_CLIENT) +- [FR_VSC_BINARY_PATH (Binary Path Configuration)](../../requirements/functional/vscode.md#FR_VSC_BINARY_PATH) +- [FR_VSC_MARKDOWN_ACTIVATION (Markdown Activation)](../../requirements/functional/vscode.md#FR_VSC_MARKDOWN_ACTIVATION) +- [FR_VSC_SERVER_LIFECYCLE (Server Lifecycle Commands)](../../requirements/functional/vscode.md#FR_VSC_SERVER_LIFECYCLE) +- [NFR_VSCODE_PORTABILITY (Cross-platform Portability)](../../requirements/non-functional/vscode.md#NFR_VSCODE_PORTABILITY) +- [NFR_VSCODE_PACKAGING (Lightweight Packaging)](../../requirements/non-functional/vscode.md#NFR_VSCODE_PACKAGING) + ### Zed Editor Extension @@ -105,6 +176,11 @@ 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)](../../requirements/functional/installation.md#FR_INSTALL_EXT_ZED) +- [IF_ZED_UI (Zed UI)](../../requirements/interfaces/interfaces.md#IF_ZED_UI) + ### CI/CD Pipelines @@ -115,6 +191,14 @@ The `.github` directory contains the CI/CD pipeline configuration. - **`.github/workflows/codeql.yml`**: Static application security testing. - **`.github/dependabot.yml`**: Automated dependency updates. +### Realizes + +- [FR_DEV_CI (Automated Validation)](../../requirements/functional/development.md#FR_DEV_CI) +- [FR_DEV_STANDARDS (Development Standards)](../../requirements/functional/development.md#FR_DEV_STANDARDS) +- [CC_CICD (CI/CD Pipeline)](../design/cicd.md#CC_CICD) +- [CC_CONVENTIONAL_COMMITS (Commit Messages)](../design/development-norm.md#CC_CONVENTIONAL_COMMITS) +- [CC_SEMANTIC_VERSIONING (Versioning)](../design/development-norm.md#CC_SEMANTIC_VERSIONING) + ### Claude Code Plugin @@ -124,6 +208,12 @@ The `docgraph-plugin` provides a Model Context Protocol (MCP) server for Claude - **`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)](../../requirements/interfaces/interfaces.md#IF_CLAUDE_CODE) + ### Dev Container @@ -134,6 +224,10 @@ The `.devcontainer` directory contains the development environment configuration - **`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)](../design/development-norm.md#CC_DEV_ENV) + ### Test Infrastructure @@ -142,3 +236,7 @@ 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)](../design/testing.md#CC_TESTING_STRATEGY) diff --git a/doc/constraints/development.md b/doc/constraints/development.md index 0cc48b4..95b9b50 100644 --- a/doc/constraints/development.md +++ b/doc/constraints/development.md @@ -1,15 +1,9 @@ -# Development Constraints - ## High Performance The system must satisfy strict performance requirements to support large codebases. -### Satisfied by - -- [NFR_PERF (High Performance)](../requirements/non-functional/performance.md#NFR_PERF) {To support large codebases} - ## Open Source Software (OSS) @@ -17,10 +11,6 @@ The system must satisfy strict performance requirements to support large codebas This project is Open Source Software. To facilitate community contribution and ensure long-term sustainability, we MUST adhere to de-facto industry standards for development workflows and project structure. -### Realized by - -- [FR_DEV_STANDARDS (Development Standards)](../requirements/functional/development.md#FR_DEV_STANDARDS) - ## Solo Development @@ -28,17 +18,8 @@ adhere to de-facto industry standards for development workflows and project stru This project is developed by a single individual. To maintain quality and velocity with limited resources, automation is mandatory. -### Realized by - -- [FR_DEV_CI (Automated Validation)](../requirements/functional/development.md#FR_DEV_CI) -- [FR_DEV_STANDARDS (Development Standards)](../requirements/functional/development.md#FR_DEV_STANDARDS) - ## Extensibility The system architecture must support easy extension of core capabilities. - -### Satisfied by - -- [NFR_EXT (Modular Design)](../requirements/non-functional/extensibility.md#NFR_EXT) {To allow future enhancements} diff --git a/doc/constraints/quality.md b/doc/constraints/quality.md index 0139e38..737cb20 100644 --- a/doc/constraints/quality.md +++ b/doc/constraints/quality.md @@ -1,5 +1,3 @@ -# Quality Constraints - ## Quality @@ -10,8 +8,3 @@ The system must maintain high quality standards across testing and security to e - Core business logic: 85%+ coverage - Overall codebase: 70%+ coverage - -### Satisfied by - -- [NFR_TEST (Comprehensive Testing)](../requirements/non-functional/test-quality.md#NFR_TEST) {To ensure reliability} -- [NFR_SECURITY (Security Testing)](../requirements/non-functional/security.md#NFR_SECURITY) {To ensure security} diff --git a/doc/decisions/error-handling.md b/doc/decisions/error-handling.md index 377a72e..3bd98a3 100644 --- a/doc/decisions/error-handling.md +++ b/doc/decisions/error-handling.md @@ -90,7 +90,19 @@ fn to_jsonrpc_error(err: anyhow::Error) -> jsonrpc::Error { We selected this hybrid approach to balance type safety in the core library with development velocity and error context in the application layers. -### 1. Core Library: thiserror (Typed Errors) +The `docgraph` project has a layered architecture with: + +- **Core library** (`src/core/`, `src/lib.rs`) - Reusable logic exposed to other crates +- **CLI binary** (`src/main.rs`, `src/cli/`) - Command-line interface +- **LSP server** (`src/lsp/`) - Language Server Protocol implementation + +We need a consistent error handling strategy that: + +1. Provides typed errors for library APIs +2. Offers rich context for end-user error messages +3. Converts errors appropriately at layer boundaries + +**1. Core Library: thiserror (Typed Errors)** **Why**: The core library is called by other crates (CLI, LSP), so errors should be **typed** for programmatic handling. @@ -125,7 +137,7 @@ pub enum Error { pub type Result = std::result::Result; ``` -#### 2. CLI Binary: anyhow (Contextual Reporting) +**2. CLI Binary: anyhow (Contextual Reporting)** **Why**: CLI is the final consumer - errors are displayed to users and then the program exits. We need **rich context** more than type safety. @@ -155,7 +167,7 @@ fn main() -> anyhow::Result<()> { Core's `Error` automatically converts to `anyhow::Error` via `?` operator. -#### 3. LSP Server: anyhow + JSON-RPC Conversion +**3. LSP Server: anyhow + JSON-RPC Conversion** **Why**: LSP handles requests asynchronously and needs to convert errors to JSON-RPC error responses. @@ -190,20 +202,8 @@ async fn handle_hover(...) -> Result, jsonrpc::Error> { - **Conversion overhead**: LSP needs explicit conversion to JSON-RPC errors - **Learning curve**: Developers need to understand when to use which crate -## Context - -The `docgraph` project has a layered architecture with: - -- **Core library** (`src/core/`, `src/lib.rs`) - Reusable logic exposed to other crates -- **CLI binary** (`src/main.rs`, `src/cli/`) - Command-line interface -- **LSP server** (`src/lsp/`) - Language Server Protocol implementation - -We need a consistent error handling strategy that: - -1. Provides typed errors for library APIs -2. Offers rich context for end-user error messages -3. Converts errors appropriately at layer boundaries +### Notes -## Related +**Related Decisions:** - [ADR_LAYERED_ARCH (Layered Architecture)](./layered-architecture.md#ADR_LAYERED_ARCH) diff --git a/doc/decisions/layered-architecture.md b/doc/decisions/layered-architecture.md index 7f7572f..76ffb4d 100644 --- a/doc/decisions/layered-architecture.md +++ b/doc/decisions/layered-architecture.md @@ -24,17 +24,21 @@ We adopt a 3-layer architecture: We selected this 3-layer architecture to maximize separation of concerns and reusability. -### 1. Separation of Concerns +`docgraph` is a tool for building and validating knowledge graphs from Markdown files. It needs to support multiple +interfaces (CLI, LSP) while sharing the same core logic, avoiding code duplication, and maintaining high +maintainability. + +**1. Separation of Concerns** - **Core**: Focuses on domain logic (parsing, validation, graph building) - **Handlers**: Focuses on bridging user interfaces -#### 2. Reusability +**2. Reusability** - CLI and LSP share the same Core logic - Adding new interfaces (e.g., Web API) requires no Core changes -#### 3. Testability +**3. Testability** - Core logic is independent of I/O and can be unit tested as pure functions - Handlers are thin layers verified through integration tests @@ -51,12 +55,12 @@ fn test_parse_spec_block() { } ``` -#### 4. Maintainability +**4. Maintainability** - Each handler is separated into its own file, making change impact clear -- Examples: `check.rs`, `rule.rs`, `graph.rs`, `list.rs`, `trace.rs`, `describe.rs` +- Examples: `check.rs`, `rule.rs`, `graph.rs`, `describe.rs` -#### 5. Dependency Rule +**5. Dependency Rule** The architecture enforces a strict dependency rule: **dependencies always point inward toward Core**. @@ -77,13 +81,9 @@ This provides: - Small changes may require modifications to multiple files - New developers may need time to understand the file structure -## Context - -`docgraph` is a tool for building and validating knowledge graphs from Markdown files. It needs to support multiple -interfaces (CLI, LSP) while sharing the same core logic, avoiding code duplication, and maintaining high -maintainability. +### Notes -### Example: `check` Command Flow +**Example: `check` Command Flow** The following diagram illustrates how the layered architecture works in practice: @@ -116,6 +116,6 @@ This flow demonstrates: 2. **Core Independence**: Core has no knowledge of CLI 3. **Reusability**: The same `lint::check_workspace` could be called from LSP or any other interface -## Related +**Related Decisions:** - [ADR_MARKDOWN_FORMAT (Choice of Plain Markdown and HTML Anchors)](./markdown-format.md#ADR_MARKDOWN_FORMAT) diff --git a/doc/decisions/single-responsibility.md b/doc/decisions/single-responsibility.md index 687f16c..301a413 100644 --- a/doc/decisions/single-responsibility.md +++ b/doc/decisions/single-responsibility.md @@ -11,6 +11,10 @@ practice, this means each file/module is responsible for exactly one thing. ## Rationale +As the `docgraph` codebase grows, we need a clear principle for organizing code into modules and files. Without a +guiding principle, modules can become bloated with multiple responsibilities, making the code harder to understand, +test, and maintain. + - **Easier to Understand**: When reading `check.rs`, developers only need to understand the `check` command logic. No other command logic is mixed in, reducing cognitive load. - **Limited Change Impact**: When modifying the `check` command, developers only need to edit `check.rs`. Other commands @@ -25,13 +29,9 @@ practice, this means each file/module is responsible for exactly one thing. - More files to manage (one per responsibility) - May require more navigation between files when working on related features -## Context - -As the `docgraph` codebase grows, we need a clear principle for organizing code into modules and files. Without a -guiding principle, modules can become bloated with multiple responsibilities, making the code harder to understand, -test, and maintain. +### Notes -### Anti-Pattern Example +**Anti-Pattern Example** **Bad** - Multiple responsibilities in one file: @@ -58,6 +58,6 @@ pub fn handle_rule(...) { /* ... */ } Each file has exactly one reason to change (changes to that specific command). -## Related +**Related Decisions:** - [ADR_LAYERED_ARCH (Layered Architecture)](./layered-architecture.md#ADR_LAYERED_ARCH) diff --git a/doc/decisions/thin-handlers.md b/doc/decisions/thin-handlers.md index f05e49a..c94fe44 100644 --- a/doc/decisions/thin-handlers.md +++ b/doc/decisions/thin-handlers.md @@ -122,6 +122,10 @@ pub fn handle_check(...) { ## Rationale +We selected this pattern because in a layered architecture with Core and Handler layers, we need to decide how much +logic should reside in handlers versus the Core. Putting too much logic in handlers leads to duplication across +interfaces (CLI, LSP) and makes testing harder. + - **Easy Testing**: Handlers are thin enough that integration tests are sufficient. Complex logic is tested in Core unit tests, which are faster and more reliable. - **Centralized Logic**: All business logic lives in Core, making it easy to find and modify. Developers don't need to @@ -134,12 +138,8 @@ pub fn handle_check(...) { - Requires discipline to avoid adding logic to handlers - May feel verbose for simple operations -## Context - -In a layered architecture with Core and Handler layers, we need to decide how much logic should reside in handlers -versus the Core. Putting too much logic in handlers leads to duplication across interfaces (CLI, LSP) and makes testing -harder. +### Notes -## Related +**Related Decisions:** - [ADR_LAYERED_ARCH (Layered Architecture)](./layered-architecture.md#ADR_LAYERED_ARCH) diff --git a/doc/requirements/functional/claude.md b/doc/requirements/functional/claude.md index 24ba799..6d81e60 100644 --- a/doc/requirements/functional/claude.md +++ b/doc/requirements/functional/claude.md @@ -7,9 +7,9 @@ The agent SHALL use the document graph to perform Retrieval-Augmented Generation, fetching relevant context for user queries via the [Claude Code Plugin](../../requirements/interfaces/interfaces.md#IF_CLAUDE_CODE). -### Realized by +### Derived from -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [UC_AI_ASSISTANCE (AI-Assisted Documentation)](../../usecases/ai-assistance.md#UC_AI_ASSISTANCE) @@ -17,9 +17,9 @@ queries via the [Claude Code Plugin](../../requirements/interfaces/interfaces.md The agent SHALL suggest appropriate commands and workflows based on the current document context. -### Realized by +### Derived from -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [UC_AI_ASSISTANCE (AI-Assisted Documentation)](../../usecases/ai-assistance.md#UC_AI_ASSISTANCE) @@ -28,9 +28,9 @@ The agent SHALL suggest appropriate commands and workflows based on the current The agent SHALL be able to automatically apply fixes to the documentation, such as formatting and structural corrections. -### Realized by +### Derived from -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [UC_AI_ASSISTANCE (AI-Assisted Documentation)](../../usecases/ai-assistance.md#UC_AI_ASSISTANCE) @@ -38,9 +38,9 @@ corrections. The agent SHALL be able to explain validation rules and errors to the user in natural language. -### Realized by +### Derived from -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [UC_AI_ASSISTANCE (AI-Assisted Documentation)](../../usecases/ai-assistance.md#UC_AI_ASSISTANCE) @@ -48,9 +48,9 @@ The agent SHALL be able to explain validation rules and errors to the user in na The agent SHALL guide the user through the document-driven development workflow, prompting for next steps. -### Realized by +### Derived from -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [UC_AI_ASSISTANCE (AI-Assisted Documentation)](../../usecases/ai-assistance.md#UC_AI_ASSISTANCE) @@ -60,14 +60,9 @@ The plugin SHALL support distribution via the [Claude Marketplace](../../requirements/interfaces/interfaces.md#IF_CLAUDE_MARKETPLACE) mechanism. This includes providing a valid `.claude-plugin/marketplace.json` file in the repository root that defines the plugin and its source. -### Realized by +### Derived from -- [MOD_PLUGIN (Claude Code Plugin)](../../architecture/view/module.md#MOD_PLUGIN) -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) - -### Qualified by - -- [NFR_VSCODE_PORTABILITY (Cross-platform Portability)](../../requirements/non-functional/vscode.md#NFR_VSCODE_PORTABILITY) +- [UC_CLAUDE_INSTALL (Install Claude Plugin)](../../usecases/setup.md#UC_CLAUDE_INSTALL) @@ -76,7 +71,6 @@ providing a valid `.claude-plugin/marketplace.json` file in the repository root The plugin SHALL be installable via the Claude Desktop `/plugin` commands. Specifically, it SHALL support being added as a marketplace and then installed as a local plugin. -### Realized by +### Derived from -- [MOD_PLUGIN (Claude Code Plugin)](../../architecture/view/module.md#MOD_PLUGIN) -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [UC_CLAUDE_INSTALL (Install Claude Plugin)](../../usecases/setup.md#UC_CLAUDE_INSTALL) diff --git a/doc/requirements/functional/cli.md b/doc/requirements/functional/cli.md index 968377d..70cfd8c 100644 --- a/doc/requirements/functional/cli.md +++ b/doc/requirements/functional/cli.md @@ -7,9 +7,9 @@ The `lint` command shall parse all Markdown files in the target directory, build the graph, and report any violations of validation rules via the [Command Line Interface](../../requirements/interfaces/interfaces.md#IF_CLI). -### Realized by +### Derived from -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) +- [UC_CLI_ANALYSIS (CLI Traceability Analysis)](../../usecases/cli-analysis.md#UC_CLI_ANALYSIS) @@ -17,14 +17,13 @@ validation rules via the [Command Line Interface](../../requirements/interfaces/ The `graph` command shall output the graph structure in JSON format. -### Realized by +### Derived from -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [UC_CLI_ANALYSIS (CLI Traceability Analysis)](../../usecases/cli-analysis.md#UC_CLI_ANALYSIS) -## List Command +## List Capability The `list` capability shall output nodes matching a specific query with their names. This is achieved using the `query` command. @@ -45,16 +44,16 @@ docgraph query "MATCH (n) WHERE n.id =~ 'FR-*' RETURN n.id, n.name" └────────┴─────────────┘ ``` -### Realized by +### Derived from -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) +- [UC_CLI_ANALYSIS (CLI Traceability Analysis)](../../usecases/cli-analysis.md#UC_CLI_ANALYSIS) -## Trace Command +## Trace Capability The `trace` capability shall find and display all paths between a start ID and target IDs matching a query. This is -achieved using the `query` command with path finding. +achieved using the `query` command. **Usage:** @@ -62,9 +61,9 @@ achieved using the `query` command with path finding. docgraph query "MATCH p=(src)-[*]->(dst) WHERE src.id = 'A' AND dst.id = 'B' RETURN p" ``` -### Realized by +### Derived from -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) +- [UC_CLI_ANALYSIS (CLI Traceability Analysis)](../../usecases/cli-analysis.md#UC_CLI_ANALYSIS) @@ -94,9 +93,9 @@ source_id: source_name ... ``` -### Realized by +### Derived from -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) +- [UC_CLI_ANALYSIS (CLI Traceability Analysis)](../../usecases/cli-analysis.md#UC_CLI_ANALYSIS) @@ -135,9 +134,9 @@ Rules: to [MOD] min=1 max=-: Each functional requirement must be realized by at least one module ``` -### Realized by +### Derived from -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) +- [UC_CLI_ANALYSIS (CLI Traceability Analysis)](../../usecases/cli-analysis.md#UC_CLI_ANALYSIS) @@ -145,9 +144,9 @@ Rules: The `version` command shall display the current version of the `docgraph` tool. -### Realized by +### Derived from -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) +- [UC_CLI_ANALYSIS (CLI Traceability Analysis)](../../usecases/cli-analysis.md#UC_CLI_ANALYSIS) @@ -155,9 +154,9 @@ The `version` command shall display the current version of the `docgraph` tool. The `help` command shall display usage information for `docgraph` and its subcommands. -### Realized by +### Derived from -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) +- [UC_CLI_ANALYSIS (CLI Traceability Analysis)](../../usecases/cli-analysis.md#UC_CLI_ANALYSIS) @@ -212,7 +211,6 @@ Returning the node variable itself (e.g., `RETURN n`) extends to all available p ] ``` -### Realized by +### Derived from -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [UC_CLI_ANALYSIS (CLI Traceability Analysis)](../../usecases/cli-analysis.md#UC_CLI_ANALYSIS) diff --git a/doc/requirements/functional/core.md b/doc/requirements/functional/core.md index c6b1bfb..186142f 100644 --- a/doc/requirements/functional/core.md +++ b/doc/requirements/functional/core.md @@ -6,13 +6,9 @@ The core engine MUST validate that all internal links reference existing node IDs. -### Realized by +### Derived from -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) - -### Qualified by - -- [NFR_AVAILABILITY (System Availability)](../../requirements/non-functional/performance.md#NFR_AVAILABILITY) +- [UC_WRITE (Write Specifications)](../../usecases/writing-specification.md#UC_WRITE) --- @@ -22,9 +18,9 @@ The core engine MUST validate that all internal links reference existing node ID The system MUST ensure that every node ID in the documentation remains unique across the entire workspace. -### Realized by +### Derived from -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [UC_WRITE (Write Specifications)](../../usecases/writing-specification.md#UC_WRITE) --- @@ -35,9 +31,9 @@ The system MUST ensure that every node ID in the documentation remains unique ac The system MUST record all validation results and structural changes in a persistent audit log for traceability and compliance. -### Realized by +### Derived from -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [UC_WRITE (Write Specifications)](../../usecases/writing-specification.md#UC_WRITE) --- @@ -48,9 +44,9 @@ compliance. The system SHOULD provide mechanisms to authenticate users before allowing certain operations, especially when interacting with remote marketplaces. -### Realized by +### Derived from -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [UC_CLAUDE_INSTALL (Install Claude Plugin)](../../usecases/setup.md#UC_CLAUDE_INSTALL) --- @@ -71,9 +67,9 @@ templates. - **Wildcards**: Supports `*` for ID matching and substring matching in links. - **Optional Sections**: Use `(Optional)` in headers to mark sections that can be omitted. -### Realized by +### Derived from -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [UC_WRITE (Write Specifications)](../../usecases/writing-specification.md#UC_WRITE) **Template Example:** @@ -87,9 +83,9 @@ repeating schemas. This requirement defines the behavior for {Feature}. -## Realized by +## Derived from -- [MOD\__(_)](*#MOD*) +- [UC\__(*)] (_#UC_) ## Parameters (Optional) @@ -139,6 +135,6 @@ UC = { desc = "Use Case" } rules = [{ dir = "to", targets = ["FR"], min = 1 }] ``` -### Realized by +### Derived from -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [UC_WRITE (Write Specifications)](../../usecases/writing-specification.md#UC_WRITE) diff --git a/doc/requirements/functional/development.md b/doc/requirements/functional/development.md index 772b9ea..3a31135 100644 --- a/doc/requirements/functional/development.md +++ b/doc/requirements/functional/development.md @@ -6,20 +6,9 @@ The system SHALL provide an automated validation pipeline to ensure document graph integrity on every change. -### Realized by +### Derived from -- [MOD_CICD (CI/CD Pipelines)](../../architecture/view/module.md#MOD_CICD) - -### Codified in (Optional) - -- [CC_CICD (CI/CD Pipeline)](../../architecture/design/cicd.md#CC_CICD) Ensures automated validation -- [CC_DEV_ENV (Development Environment)](../../architecture/design/development-norm.md#CC_DEV_ENV) Defines development - environment standards - -### Decided by (Optional) - -- [ADR_CI_ENV_PARITY (CI Environment Parity)](../../decisions/ci-env-parity.md#ADR_CI_ENV_PARITY) Decision to align CI - and dev environments +- [UC_PREK_SETUP (Set Up Development Hooks)](../../usecases/setup.md#UC_PREK_SETUP) @@ -31,13 +20,6 @@ management. - **Commit Messages**: MUST follow the Conventional Commits specification. - **Versioning**: MUST follow Semantic Versioning (SemVer). -### Realized by - -- [MOD_CICD (CI/CD Pipelines)](../../architecture/view/module.md#MOD_CICD) - -### Codified in (Optional) +### Derived from -- [CC_CONVENTIONAL_COMMITS (Commit Messages)](../../architecture/design/development-norm.md#CC_CONVENTIONAL_COMMITS) - Standardizes commit message format -- [CC_SEMANTIC_VERSIONING (Versioning)](../../architecture/design/development-norm.md#CC_SEMANTIC_VERSIONING) Defines - versioning strategy +- [UC_WRITE (Write Specifications)](../../usecases/writing-specification.md#UC_WRITE) diff --git a/doc/requirements/functional/installation.md b/doc/requirements/functional/installation.md index 2aed970..5af179b 100644 --- a/doc/requirements/functional/installation.md +++ b/doc/requirements/functional/installation.md @@ -16,9 +16,9 @@ The system must support manual installation by providing valid configurations fo 2. **Node.js**: - Version: v18 or higher (Required for VS Code Extension) -### Realized by +### Derived from -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) +- [UC_INSTALL_MANUAL (Install Manual Setup)](../../usecases/setup.md#UC_INSTALL_MANUAL) @@ -31,9 +31,9 @@ The system must provide pre-compiled binaries and official installation scripts 2. **Automated Scripts**: Provide a shell script for Unix-like systems and a PowerShell script for Windows to handle downloading, extraction, and PATH configuration. -### Realized by +### Derived from -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) +- [UC_INSTALL_BINARY (Install via Binary Script)](../../usecases/setup.md#UC_INSTALL_BINARY) @@ -50,9 +50,9 @@ The system must provide an extension for the Zed editor to enable LSP support vi 5. **Configuration**: Requires a `.zed/settings.json` in the project root to explicitly enable the `docgraph` language server. -### Realized by +### Derived from -- [MOD_EXT_ZED (Zed Editor Extension)](../../architecture/view/module.md#MOD_EXT_ZED) +- [UC_ZED_INSTALL (Install Zed Extension)](../../usecases/setup.md#UC_ZED_INSTALL) @@ -67,6 +67,6 @@ The system must support automated code quality checks before commits using `prek - Validation: `docgraph check`. 3. **Setup**: Supports a one-command setup via `prek install -f`. -### Realized by +### Derived from -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) +- [UC_PREK_SETUP (Set Up Development Hooks)](../../usecases/setup.md#UC_PREK_SETUP) diff --git a/doc/requirements/functional/lsp.md b/doc/requirements/functional/lsp.md index 29ae7fb..827408b 100644 --- a/doc/requirements/functional/lsp.md +++ b/doc/requirements/functional/lsp.md @@ -13,9 +13,9 @@ The server supports jumping to the source of a Node by clicking on its ID in a l **Behavior**: Maps markdown link syntax to the anchor HTML tag in the corresponding file. -### Realized by +### Derived from -- [MOD_LSP (LSP Library)](../../architecture/view/module.md#MOD_LSP) +- [UC_EDITOR_LSP (Editor Support via LSP)](../../usecases/lsp-editing.md#UC_EDITOR_LSP) @@ -27,9 +27,9 @@ The server displays the Node's description and metadata when hovering over an ID **Behavior**: Shows the human-readable name and reference counts (incoming/outgoing) for the Node under the cursor. -### Realized by +### Derived from -- [MOD_LSP (LSP Library)](../../architecture/view/module.md#MOD_LSP) +- [UC_EDITOR_LSP (Editor Support via LSP)](../../usecases/lsp-editing.md#UC_EDITOR_LSP) @@ -43,9 +43,9 @@ The server suggests existing Node IDs when typing links. **Behavior**: Returns a list of all Node IDs defined in the workspace. -### Realized by +### Derived from -- [MOD_LSP (LSP Library)](../../architecture/view/module.md#MOD_LSP) +- [UC_EDITOR_LSP (Editor Support via LSP)](../../usecases/lsp-editing.md#UC_EDITOR_LSP) @@ -57,9 +57,9 @@ The server searches all Markdown files for the ID string at the current cursor p **Behavior**: Lists all occurrences of a Node ID throughout the workspace. -### Realized by +### Derived from -- [MOD_LSP (LSP Library)](../../architecture/view/module.md#MOD_LSP) +- [UC_EDITOR_LSP (Editor Support via LSP)](../../usecases/lsp-editing.md#UC_EDITOR_LSP) @@ -74,9 +74,9 @@ The server renames a Node ID and automatically updates all its references across 1. Validates if the selected text is a valid anchor ID or reference. 2. Applies workspace-wide edits to change the ID in both its definition and all identified references. -### Realized by +### Derived from -- [MOD_LSP (LSP Library)](../../architecture/view/module.md#MOD_LSP) +- [UC_EDITOR_LSP (Editor Support via LSP)](../../usecases/lsp-editing.md#UC_EDITOR_LSP) @@ -88,12 +88,12 @@ The server explores incoming and outgoing relationship chains in a tree view for **Behavior**: -- **Incoming Calls**: Shows which Nodes reference the current block. -- **Outgoing Calls**: Shows which Nodes are referenced by the current block. +1. **Incoming Calls**: Shows which Nodes reference the current block. +2. **Outgoing Calls**: Shows which Nodes are referenced by the current block. -### Realized by +### Derived from -- [MOD_LSP (LSP Library)](../../architecture/view/module.md#MOD_LSP) +- [UC_EDITOR_LSP (Editor Support via LSP)](../../usecases/lsp-editing.md#UC_EDITOR_LSP) @@ -106,9 +106,9 @@ The server lists all nodes in the current document for navigation. **Behavior**: Returns a list of all Nodes defined in the current document. This populates the "Outline" view in most editors. -### Realized by +### Derived from -- [MOD_LSP (LSP Library)](../../architecture/view/module.md#MOD_LSP) +- [UC_EDITOR_LSP (Editor Support via LSP)](../../usecases/lsp-editing.md#UC_EDITOR_LSP) @@ -120,9 +120,9 @@ The server allows searching for Nodes across the entire workspace. **Behavior**: Allows searching for Nodes across the entire workspace by matching their ID or human-readable name. -### Realized by +### Derived from -- [MOD_LSP (LSP Library)](../../architecture/view/module.md#MOD_LSP) +- [UC_EDITOR_LSP (Editor Support via LSP)](../../usecases/lsp-editing.md#UC_EDITOR_LSP) @@ -130,6 +130,6 @@ The server allows searching for Nodes across the entire workspace. The system SHALL provide a Language Server Protocol server to support interactive editing. -### Realized by +### Derived from -- [MOD_LSP (LSP Library)](../../architecture/view/module.md#MOD_LSP) +- [UC_EDITOR_LSP (Editor Support via LSP)](../../usecases/lsp-editing.md#UC_EDITOR_LSP) diff --git a/doc/requirements/functional/vscode.md b/doc/requirements/functional/vscode.md index 1a1c910..7c318aa 100644 --- a/doc/requirements/functional/vscode.md +++ b/doc/requirements/functional/vscode.md @@ -11,14 +11,9 @@ SHALL implement a Language Server Protocol (LSP) client that establishes communi running in LSP mode (`docgraph lsp`) and exposes features via [VS Code UI](../../requirements/interfaces/interfaces.md#IF_VSCODE_UI). -### Realized by +### Derived from -- [MOD_VSEX (VS Code Extension)](../../architecture/view/module.md#MOD_VSEX) - -### Qualified by - -- [NFR_VSCODE_PORTABILITY (Cross-platform Portability)](../../requirements/non-functional/vscode.md#NFR_VSCODE_PORTABILITY) -- [NFR_LATENCY (System Latency)](../../requirements/non-functional/performance.md#NFR_LATENCY) +- [UC_VSCODE_INSTALL (Install VS Code Extension)](../../usecases/setup.md#UC_VSCODE_INSTALL) @@ -27,13 +22,9 @@ running in LSP mode (`docgraph lsp`) and exposes features via The extension SHALL provide a setting (`docgraph.binaryPath`) allowing the user to specify the absolute path to the `docgraph` executable. If not specified, it SHALL attempt to find the binary in the system `PATH`. -### Realized by - -- [MOD_VSEX (VS Code Extension)](../../architecture/view/module.md#MOD_VSEX) - -### Qualified by +### Derived from -- [NFR_VSCODE_PACKAGING (Lightweight Packaging)](../../requirements/non-functional/vscode.md#NFR_VSCODE_PACKAGING) +- [UC_VSCODE_INSTALL (Install VS Code Extension)](../../usecases/setup.md#UC_VSCODE_INSTALL) @@ -42,9 +33,9 @@ The extension SHALL provide a setting (`docgraph.binaryPath`) allowing the user The extension SHALL activate automatically when a workspace contains Markdown files (`*.md`) or when a Markdown file is opened. It SHALL associate its LSP capabilities exclusively with the `markdown` document selector. -### Realized by +### Derived from -- [MOD_VSEX (VS Code Extension)](../../architecture/view/module.md#MOD_VSEX) +- [UC_VSCODE_INSTALL (Install VS Code Extension)](../../usecases/setup.md#UC_VSCODE_INSTALL) @@ -53,6 +44,6 @@ opened. It SHALL associate its LSP capabilities exclusively with the `markdown` The extension SHALL provide a command to restart the `docgraph` language server manually, which is useful when the binary is updated or the configuration changes. -### Realized by +### Derived from -- [MOD_VSEX (VS Code Extension)](../../architecture/view/module.md#MOD_VSEX) +- [UC_VSCODE_INSTALL (Install VS Code Extension)](../../usecases/setup.md#UC_VSCODE_INSTALL) diff --git a/doc/requirements/interfaces/interfaces.md b/doc/requirements/interfaces/interfaces.md index 6664fea..aabfb37 100644 --- a/doc/requirements/interfaces/interfaces.md +++ b/doc/requirements/interfaces/interfaces.md @@ -11,9 +11,13 @@ The `docgraph.toml` file at the project root defines the validation rules and wo - **File Path**: `docgraph.toml` (Project Root) - **Format**: TOML -### Realized by +### Defined by -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) +- [FR_CORE_CONFIGURATION (Configuration)](../../requirements/functional/core.md#FR_CORE_CONFIGURATION) + +### Justified by + +- [UC_WRITE (Write Specifications)](../../usecases/writing-specification.md#UC_WRITE) --- @@ -23,9 +27,15 @@ The `docgraph.toml` file at the project root defines the validation rules and wo The `docgraph` CLI provides commands for linting, graph generation, and analysis of Markdown documentation. -### Realized by +### Defined by + +- [FR_CLI_LINT (Lint Command)](../../requirements/functional/cli.md#FR_CLI_LINT) +- [FR_CLI_GRAPH (Graph Command)](../../requirements/functional/cli.md#FR_CLI_GRAPH) +- [FR_CLI_LIST (List Capability)](../../requirements/functional/cli.md#FR_CLI_LIST) + +### Justified by -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) +- [UC_CLI_ANALYSIS (CLI Traceability Analysis)](../../usecases/cli-analysis.md#UC_CLI_ANALYSIS) --- @@ -55,9 +65,13 @@ The implementation is defined in: - [plugin.json (Plugin Definition)](../../../docgraph-plugin/.claude-plugin/plugin.json) - [SKILL.md (Plugin Skill Definition)](../../../docgraph-plugin/skills/docgraph/SKILL.md) -### Realized by +### Defined by -- [MOD_PLUGIN (Claude Code Plugin)](../../architecture/view/module.md#MOD_PLUGIN) +- [FR_CLAUDE_RAG (Retrieval-Augmented Generation)](../../requirements/functional/claude.md#FR_CLAUDE_RAG) + +### Justified by + +- [UC_AI_ASSISTANCE (AI-Assisted Documentation)](../../usecases/ai-assistance.md#UC_AI_ASSISTANCE) --- @@ -67,9 +81,13 @@ The implementation is defined in: The distribution platform for Claude Desktop plugins. -### Realized by +### Defined by + +- [FR_CLAUDE_MARKETPLACE (Claude Marketplace Support)](../../requirements/functional/claude.md#FR_CLAUDE_MARKETPLACE) + +### Justified by -- [MOD_PLUGIN (Claude Code Plugin)](../../architecture/view/module.md#MOD_PLUGIN) +- [UC_CLAUDE_INSTALL (Install Claude Plugin)](../../usecases/setup.md#UC_CLAUDE_INSTALL) --- @@ -79,9 +97,13 @@ The distribution platform for Claude Desktop plugins. The distribution platform for Visual Studio Code extensions. -### Realized by +### Defined by -- [MOD_VSEX (VS Code Extension)](../../architecture/view/module.md#MOD_VSEX) +- [FR_VSC_LSP_CLIENT (LSP Client Integration)](../../requirements/functional/vscode.md#FR_VSC_LSP_CLIENT) + +### Justified by + +- [UC_VSCODE_INSTALL (Install VS Code Extension)](../../usecases/setup.md#UC_VSCODE_INSTALL) --- @@ -91,9 +113,13 @@ The distribution platform for Visual Studio Code extensions. The user interface of Visual Studio Code, including commands, views, and settings. -### Realized by +### Defined by + +- [FR_VSC_LSP_CLIENT (LSP Client Integration)](../../requirements/functional/vscode.md#FR_VSC_LSP_CLIENT) + +### Justified by -- [MOD_VSEX (VS Code Extension)](../../architecture/view/module.md#MOD_VSEX) +- [UC_EDITOR_LSP (Editor Support via LSP)](../../usecases/lsp-editing.md#UC_EDITOR_LSP) --- @@ -109,9 +135,13 @@ The system interacts with GitHub Releases to distribute pre-compiled binaries an 2. **Access**: Public anonymous access for downloads. 3. **Format**: Compressed archives (`.tar.gz`, `.zip`) and VSIX packages. -### Realized by +### Defined by -- [MOD_CLI (CLI Application)](../../architecture/view/module.md#MOD_CLI) +- [FR_INSTALL_BINARY (Binary Installation Support)](../../requirements/functional/installation.md#FR_INSTALL_BINARY) + +### Justified by + +- [UC_INSTALL_BINARY (Install via Binary Script)](../../usecases/setup.md#UC_INSTALL_BINARY) --- @@ -121,6 +151,10 @@ The system interacts with GitHub Releases to distribute pre-compiled binaries an The user interface of the Zed editor, including the command palette and settings. -### Realized by +### Defined by + +- [FR_INSTALL_EXT_ZED (Zed Editor Extension)](../../requirements/functional/installation.md#FR_INSTALL_EXT_ZED) + +### Justified by -- [MOD_EXT_ZED (Zed Editor Extension)](../../architecture/view/module.md#MOD_EXT_ZED) +- [UC_ZED_INSTALL (Install Zed Extension)](../../usecases/setup.md#UC_ZED_INSTALL) diff --git a/doc/requirements/non-functional/extensibility.md b/doc/requirements/non-functional/extensibility.md index 885c766..42cb073 100644 --- a/doc/requirements/non-functional/extensibility.md +++ b/doc/requirements/non-functional/extensibility.md @@ -7,15 +7,20 @@ The system architecture must be modular to facilitate future extensions, such as new linter rules or graph analysis algorithms. -### Codified in (Optional) +### Qualifies (Optional) -- [CC_LAYERED_ARCH (Layered Architecture)](../architecture/design/layered-architecture.md#CC_LAYERED_ARCH) Defines +- [FR_DEV_CI (Automated Validation)](../../requirements/functional/development.md#FR_DEV_CI) +- [FR_DEV_STANDARDS (Development Standards)](../../requirements/functional/development.md#FR_DEV_STANDARDS) + +### Constrained by (Optional) + +- [CC_LAYERED_ARCH (Layered Architecture)](../../architecture/design/layered-architecture.md#CC_LAYERED_ARCH) Defines modular architecture -- [CC_DEPENDENCY_RULE (The Dependency Rule)](../architecture/design/dependency-rule.md#CC_DEPENDENCY_RULE) Enforces - dependency direction -- [CC_SINGLE_RESPONSIBILITY (Single Responsibility Principle (SRP))](../architecture/design/single-responsibility.md#CC_SINGLE_RESPONSIBILITY) +- [CC_DEPENDENCY_RULE (The Dependency Rule)](../../architecture/design/layered-architecture.md#CC_DEPENDENCY_RULE) + Enforces dependency direction +- [CC_SINGLE_RESPONSIBILITY (Single Responsibility Principle (SRP))](../../architecture/design/single-responsibility.md#CC_SINGLE_RESPONSIBILITY) Promotes modularity -- [CC_THIN_HANDLERS (Thin Handlers Pattern)](../architecture/design/thin-handlers.md#CC_THIN_HANDLERS) Simplifies +- [CC_THIN_HANDLERS (Thin Handlers Pattern)](../../architecture/design/thin-handlers.md#CC_THIN_HANDLERS) Simplifies extension points -- [CC_ERROR_HANDLING (Error Handling Strategy)](../architecture/design/error-handling.md#CC_ERROR_HANDLING) Isolates +- [CC_ERROR_HANDLING (Error Handling Strategy)](../../architecture/design/error-handling.md#CC_ERROR_HANDLING) Isolates error handling diff --git a/doc/requirements/non-functional/performance.md b/doc/requirements/non-functional/performance.md index 7ed3eb2..a699091 100644 --- a/doc/requirements/non-functional/performance.md +++ b/doc/requirements/non-functional/performance.md @@ -4,34 +4,28 @@ ## High Performance -The system must be highly performant to ensure a smooth user experience, even with large documentation sets. +The system must satisfy strict performance requirements to support large codebases. -**Criteria:** +### Qualifies (Optional) -- Linting 1000 nodes should take less than 1 second. -- Graph analysis operations should be O(N) where possible. +- [FR_CLI_LINT (Lint Command)](../functional/cli.md#FR_CLI_LINT) -### Codified in (Optional) +### Constrained by (Optional) -- [CC_PERF_TESTING (4. Performance Testing)](../../architecture/design/testing.md#CC_PERF_TESTING) Defines performance - testing standards - ---- +- [CC_PERF_TESTING (4. Performance Testing)](../../architecture/design/testing.md#CC_PERF_TESTING) ## System Availability -The docgraph tool should be available and operational at least 99.9% of the time in CI environments. - -- [MOD_CORE (Core Library)](../../architecture/view/module.md#MOD_CORE) - ---- +The system must be available for use when required by the user. ## System Latency -Interactive operations in the VS Code extension (hover, completion) should respond in less than 100ms. +LSP response time must be within acceptable limits. + +### Qualifies (Optional) -- [MOD_LSP (LSP Library)](../../architecture/view/module.md#MOD_LSP) +- [FR_LSP_COMP (Auto-completion)](../functional/lsp.md#FR_LSP_COMP) diff --git a/doc/requirements/non-functional/security.md b/doc/requirements/non-functional/security.md index 71440f8..e8c8951 100644 --- a/doc/requirements/non-functional/security.md +++ b/doc/requirements/non-functional/security.md @@ -2,18 +2,11 @@ -## Security Testing +## Secure Execution -The system must maintain high security standards through automated security testing and vulnerability scanning. +The system must not execute arbitrary code from the documentation or workspace without explicit user consent. -**Testing Strategy:** +### Constrained by (Optional) -- **Static Analysis**: Automated CodeQL analysis for security vulnerabilities -- **Dependency Scanning**: Dependabot and cargo-audit for vulnerable dependencies -- **Execution**: Runs on push to main, pull requests, and weekly schedule - -### Codified in (Optional) - -- [CC_SAST (SAST (CodeQL))](../../architecture/design/sast.md#CC_SAST) Defines SAST and dependency scanning approach -- [CC_SUPPLY_CHAIN_SECURITY (Supply Chain Security)](../../architecture/design/supply-chain-security.md#CC_SUPPLY_CHAIN_SECURITY) - Ensures supply chain security +- [CC_DEV_ENV (Development Environment)](../../architecture/design/development-norm.md#CC_DEV_ENV) +- [CC_CICD (CI/CD Pipeline)](../../architecture/design/cicd.md#CC_CICD) diff --git a/doc/requirements/non-functional/test-quality.md b/doc/requirements/non-functional/test-quality.md index 535a710..f8949c7 100644 --- a/doc/requirements/non-functional/test-quality.md +++ b/doc/requirements/non-functional/test-quality.md @@ -12,7 +12,7 @@ Testing strategy: - **E2E tests**: Verify CLI behavior, error messages, and file I/O - **Integration tests**: Test component interactions -### Codified in (Optional) +### Constrained by (Optional) - [CC_TESTING_STRATEGY (Testing Strategy)](../../architecture/design/testing.md#CC_TESTING_STRATEGY) Defines overall testing approach diff --git a/doc/requirements/non-functional/vscode.md b/doc/requirements/non-functional/vscode.md index 8cd361f..8f7d204 100644 --- a/doc/requirements/non-functional/vscode.md +++ b/doc/requirements/non-functional/vscode.md @@ -9,9 +9,9 @@ These requirements define the quality attributes and constraints of the `docgrap The extension (LSP client) SHALL be written in TypeScript/JavaScript to ensure it runs natively on all platforms supported by VS Code (macOS, Linux, Windows). -### Realized by (Optional) +### Qualifies (Optional) -- [MOD_VSEX (VS Code Extension)](../../architecture/view/module.md#MOD_VSEX) +- [FR_VSC_LSP_CLIENT (LSP Client Integration)](../../requirements/functional/vscode.md#FR_VSC_LSP_CLIENT) @@ -20,6 +20,6 @@ supported by VS Code (macOS, Linux, Windows). The bundled `.vsix` file SHALL be minimized and excluded of unnecessary development dependencies to keep the download size small and the extension footprint low. -### Realized by (Optional) +### Qualifies (Optional) -- [MOD_VSEX (VS Code Extension)](../../architecture/view/module.md#MOD_VSEX) +- [FR_VSC_BINARY_PATH (Binary Path Configuration)](../../requirements/functional/vscode.md#FR_VSC_BINARY_PATH) diff --git a/doc/templates/actors.md b/doc/templates/actors.md index 73087a8..d9f7751 100644 --- a/doc/templates/actors.md +++ b/doc/templates/actors.md @@ -7,3 +7,7 @@ ### Responsibilities - {Responsibility} + +### Participates in + +- [UC* (*)](*#UC_*) diff --git a/doc/templates/constraint.md b/doc/templates/constraint.md index c5720d3..48ad12d 100644 --- a/doc/templates/constraint.md +++ b/doc/templates/constraint.md @@ -1,13 +1,5 @@ -## {Title} +## {Name} {Description} - -### Realized by (Optional) - -- [FR* (*)](*#FR_*) - -### Satisfied by (Optional) - -- [NFR* (*)](*#NFR_*) {Reason} diff --git a/doc/templates/cross-cutting.md b/doc/templates/cross-cutting.md index c88dd3e..614f92b 100644 --- a/doc/templates/cross-cutting.md +++ b/doc/templates/cross-cutting.md @@ -6,8 +6,12 @@ ### Decided by (Optional) -- [ADR* (*)](*#ADR_*) {Reason} +- [ADR* (*)](*#ADR_*) +- [ADR* (*)](*#ADR_*) {description} -### Realized by (Optional) +### Reflected in (Optional) -- [MOD* (*)](*#MOD_*) +- [NFR* (*)](*#NFR_*) +- [NFR* (*)](*#NFR_*) {description} +- [FR* (*)](*#FR_*) +- [FR* (*)](*#FR_*) {description} diff --git a/doc/templates/decision.md b/doc/templates/decision.md index 5dbf978..0f9f40e 100644 --- a/doc/templates/decision.md +++ b/doc/templates/decision.md @@ -12,10 +12,19 @@ {Rationale} -## Context +### Trade-offs (Optional) + +- {Trade-off} + +### Notes (Optional) + +{Notes} + +## Context (Optional) {Context} -## Related (Optional) +## Informed by (Optional) -{Related} +- [* (*)](*#*) +- [* (*)](*#*) {description} diff --git a/doc/templates/functional.md b/doc/templates/functional.md index 2c1fc7a..40bf574 100644 --- a/doc/templates/functional.md +++ b/doc/templates/functional.md @@ -4,19 +4,7 @@ {Description} -### Realized by +### Derived from -- [MOD* (*)](*#MOD_*) - -### Qualified by (Optional) - -- [NFR* (*)](*#NFR_*) -- [FR* (*)](*#FR_*) {Reason} - -### Codified in (Optional) - -- [CC* (*)](*#CC_*) {Reason} - -### Decided by (Optional) - -- [ADR* (*)](*#ADR_*) {Reason} +- [UC* (*)](*#UC_*) +- [CON* (*)](*#CON_*) diff --git a/doc/templates/interface.md b/doc/templates/interface.md index 53f8151..5a33473 100644 --- a/doc/templates/interface.md +++ b/doc/templates/interface.md @@ -4,6 +4,10 @@ {Description} -### Realized by +### Defined by -- [MOD* (*)](../../architecture/view/module.md#MOD_*) +- [FR* (*)](*#FR_*) + +### Justified by + +- [UC* (*)](*#UC_*) diff --git a/doc/templates/module.md b/doc/templates/module.md index 8ce1377..947719f 100644 --- a/doc/templates/module.md +++ b/doc/templates/module.md @@ -3,3 +3,14 @@ ### {Title} {Description} + +### Realizes + +- [FR* (*)](*#FR_*) +- [FR* (*)](*#FR_*) {description} +- [NFR* (*)](*#NFR_*) +- [NFR* (*)](*#NFR_*) {description} +- [IF* (*)](*#IF_*) +- [IF* (*)](*#IF_*) {description} +- [CC* (*)](*#CC_*) +- [CC* (*)](*#CC_*) {description} diff --git a/doc/templates/non-functional.md b/doc/templates/non-functional.md index 0850cf0..d9df432 100644 --- a/doc/templates/non-functional.md +++ b/doc/templates/non-functional.md @@ -4,14 +4,12 @@ {Description} -### Codified in (Optional) +### Qualifies (Optional) -- [CC* (*)](*#CC_*) {Reason} +- [FR* (*)](*#FR_*) +- [FR* (*)](*#FR_*) {description} -### Realized by (Optional) +### Constrained by (Optional) -- [MOD* (*)](*#MOD_*) - -### Decided by (Optional) - -- [ADR* (*)](*#ADR_*) {Reason} +- [CC* (*)](*#CC_*) +- [CC* (*)](*#CC_*) {description} diff --git a/doc/templates/usecases.md b/doc/templates/usecases.md index fd5fc67..75d1f69 100644 --- a/doc/templates/usecases.md +++ b/doc/templates/usecases.md @@ -6,20 +6,19 @@ ### Actors -- [ACT* (*)](*#ACT_*) +- [* (*)](*#*) +- [* (*)](*#*) {description} ### Interfaces -- [IF* (*)](*#IF_*) +- [* (*)](*#*) +- [* (*)](*#*) {description} -### Requirements +### Requirements (Optional) -- [FR* (*)](*#FR_*) {Reason} +- [* (*)](*#*) +- [* (*)](*#*) {description} ### Flow 1. {Step} - -### Non-Functional Requirements (Optional) - -- [NFR* (*)](*#NFR_*) {Reason} diff --git a/doc/usecases/ai-assistance.md b/doc/usecases/ai-assistance.md index 503cfd2..a5ba239 100644 --- a/doc/usecases/ai-assistance.md +++ b/doc/usecases/ai-assistance.md @@ -13,22 +13,6 @@ The AI Agent leverages the Docgraph plugin to provide intelligent assistance for ### Interfaces - [IF_CLAUDE_CODE (Interface: Claude Code Plugin)](../requirements/interfaces/interfaces.md#IF_CLAUDE_CODE) -- [IF_CLAUDE_MARKETPLACE (Claude Marketplace)](../requirements/interfaces/interfaces.md#IF_CLAUDE_MARKETPLACE) - -### Requirements - -- [FR_CLAUDE_RAG (Retrieval-Augmented Generation)](../requirements/functional/claude.md#FR_CLAUDE_RAG) Powering - intelligent context-aware documentation search -- [FR_CLAUDE_SUGGEST (Usage Suggestions)](../requirements/functional/claude.md#FR_CLAUDE_SUGGEST) Aiding developers in - discovering relevant requirements -- [FR_CLAUDE_FIX (Automated Fixes)](../requirements/functional/claude.md#FR_CLAUDE_FIX) Automating the resolution of - documentation drift -- [FR_CLAUDE_EXPLAIN (Rule Explanation)](../requirements/functional/claude.md#FR_CLAUDE_EXPLAIN) Providing clarity on - complex validation rules -- [FR_CLAUDE_WORKFLOW (Workflow Assistance)](../requirements/functional/claude.md#FR_CLAUDE_WORKFLOW) Guiding the entire - specification development process -- [FR_CLAUDE_MARKETPLACE (Claude Marketplace Support)](../requirements/functional/claude.md#FR_CLAUDE_MARKETPLACE) - Ensuring seamless installation via Claude Desktop ### Flow diff --git a/doc/usecases/ci.md b/doc/usecases/ci.md index 5eb849d..4938f96 100644 --- a/doc/usecases/ci.md +++ b/doc/usecases/ci.md @@ -1,10 +1,8 @@ -# CI/CD Use Cases - -## Continuous Integration Validation +## CI Validation -The CI System automatically validates all documentation changes upon pull request submission. +Automated validation of documentation and code on every push. ### Actors @@ -13,19 +11,11 @@ The CI System automatically validates all documentation changes upon pull reques ### Interfaces -- [IF_CLI (Command Line Interface)](../requirements/interfaces/interfaces.md#IF_CLI) - -### Requirements - -- [FR_CORE_VALID_REF (Valid References)](../requirements/functional/core.md#FR_CORE_VALID_REF) Protecting the - documentation quality in CI -- [FR_CORE_AUDIT (Audit Logging)](../requirements/functional/core.md#FR_CORE_AUDIT) Capturing security and linting - trails -- [FR_DEV_CI (Automated Validation)](../requirements/functional/development.md#FR_DEV_CI) Pipeline integration for all - documentation changes +- [IF_GITHUB_RELEASES (GitHub Releases Interface)](../requirements/interfaces/interfaces.md#IF_GITHUB_RELEASES) ### Flow -1. CI system triggers on push. -2. CI system runs `docgraph check .` command. -3. CI System reports validation results back to the developer. +1. Developer pushes code to GitHub. +2. GitHub Actions triggers the CI workflow. +3. Docgraph validation runs. +4. If validation fails, the build fails. diff --git a/doc/usecases/cli-analysis.md b/doc/usecases/cli-analysis.md index a0b73bc..55ebdf8 100644 --- a/doc/usecases/cli-analysis.md +++ b/doc/usecases/cli-analysis.md @@ -14,26 +14,6 @@ The developer runs the `docgraph` CLI to analyze the documentation graph. - [IF_CLI (Command Line Interface)](../requirements/interfaces/interfaces.md#IF_CLI) -### Requirements - -- [FR_CLI_LINT (Lint Command)](../requirements/functional/cli.md#FR_CLI_LINT) Core CLI action for validating - documentation -- [FR_CLI_GRAPH (Graph Command)](../requirements/functional/cli.md#FR_CLI_GRAPH) Visualizing traceability relationships -- [FR_CORE_AUDIT (Audit Logging)](../requirements/functional/core.md#FR_CORE_AUDIT) Tracking CLI usage for compliance - monitoring -- [FR_CLI_TRACE (Trace Command)](../requirements/functional/cli.md#FR_CLI_TRACE) Analyzing dependency paths between - nodes (using `query`) -- [FR_CLI_QUERY (Query Command)](../requirements/functional/cli.md#FR_CLI_QUERY) Advanced pattern matching and graph - analysis -- [FR_CLI_DESCRIBE (Describe Command)](../requirements/functional/cli.md#FR_CLI_DESCRIBE) Showing detailed metadata for - a specific node -- [FR_CLI_TYPE (Type Command)](../requirements/functional/cli.md#FR_CLI_TYPE) Filtering nodes by their defined types -- [FR_CLI_LIST (List Command)](../requirements/functional/cli.md#FR_CLI_LIST) Listing all nodes found in the workspace - (using `query`) -- [FR_CLI_VERSION (Version Command)](../requirements/functional/cli.md#FR_CLI_VERSION) Displaying the current version of - the tool -- [FR_CLI_HELP (Help Command)](../requirements/functional/cli.md#FR_CLI_HELP) Providing usage guidance for CLI commands - ### Flow 1. Developer opens a terminal in the project root. diff --git a/doc/usecases/lsp-editing.md b/doc/usecases/lsp-editing.md index 85a20f3..11b615a 100644 --- a/doc/usecases/lsp-editing.md +++ b/doc/usecases/lsp-editing.md @@ -9,37 +9,12 @@ The developer edits documentation in an LSP-compatible editor with real-time fee ### Actors - [ACT_DEV (Developer)](../actors/users.md#ACT_DEV) +- [ACT_CI (CI System)](../actors/systems.md#ACT_CI) ### Interfaces -- [IF_CLI (Command Line Interface)](../requirements/interfaces/interfaces.md#IF_CLI) - [IF_VSCODE_UI (VS Code UI)](../requirements/interfaces/interfaces.md#IF_VSCODE_UI) -### Requirements - -- [FR_VSC_LSP_CLIENT (LSP Client Integration)](../requirements/functional/vscode.md#FR_VSC_LSP_CLIENT) Enabling - real-time communication between VS Code and the LSP server -- [FR_LSP_GOTO (Go to Definition)](../requirements/functional/lsp.md#FR_LSP_GOTO) Enabling quick navigation to - requirement definitions -- [FR_LSP_HOVER (Hover Information)](../requirements/functional/lsp.md#FR_LSP_HOVER) Displaying requirement titles and - descriptions on hover -- [FR_LSP_COMP (Auto-completion)](../requirements/functional/lsp.md#FR_LSP_COMP) Assisting in linking known Requirement - IDs -- [FR_LSP_REFS (Find References)](../requirements/functional/lsp.md#FR_LSP_REFS) Identifying all dependencies pointing - to a node -- [FR_LSP_RENAME (Symbol Rename)](../requirements/functional/lsp.md#FR_LSP_RENAME) Safely updating Node IDs across - multiple files -- [FR_LSP_HIERARCHY (Call Hierarchy)](../requirements/functional/lsp.md#FR_LSP_HIERARCHY) Visualizing the structural - layers of specifications -- [FR_LSP_DOC_SYMBOL (Document Symbol)](../requirements/functional/lsp.md#FR_LSP_DOC_SYMBOL) Providing an outline of - current file nodes -- [FR_CORE_VALID_REF (Valid References)](../requirements/functional/core.md#FR_CORE_VALID_REF) Immediate highlighting of - broken links -- [FR_LSP_WS_SYMBOL (Workspace Symbol)](../requirements/functional/lsp.md#FR_LSP_WS_SYMBOL) Searching for any - specification node in the workspace -- [FR_LSP_SUPPORT (LSP Server)](../requirements/functional/lsp.md#FR_LSP_SUPPORT) Mandatory core logic for editor - intelligence - ### Flow 1. Developer opens a Markdown file in an LSP-enabled editor. diff --git a/doc/usecases/setup.md b/doc/usecases/setup.md index d1b40c7..85a2e34 100644 --- a/doc/usecases/setup.md +++ b/doc/usecases/setup.md @@ -9,18 +9,10 @@ The developer sets up the development environment manually on their local machin ### Actors - [ACT_DEV (Developer)](../actors/users.md#ACT_DEV) -- [ACT_USER (User)](../actors/users.md#ACT_USER) ### Interfaces -- [IF_GITHUB_RELEASES (GitHub Releases Interface)](../requirements/interfaces/interfaces.md#IF_GITHUB_RELEASES) - -### Requirements - -- [FR_INSTALL_MANUAL (Manual Installation)](../requirements/functional/installation.md#FR_INSTALL_MANUAL) Required for - users choosing not to use automated scripts -- [FR_CORE_AUDIT (Audit Logging)](../requirements/functional/core.md#FR_CORE_AUDIT) Ensures installation events are - tracked for security +- [IF_CLI (Command Line Interface)](../requirements/interfaces/interfaces.md#IF_CLI) ### Flow @@ -43,11 +35,6 @@ The developer installs the `docgraph` CLI binary using automated scripts. - [IF_GITHUB_RELEASES (GitHub Releases Interface)](../requirements/interfaces/interfaces.md#IF_GITHUB_RELEASES) -### Requirements - -- [FR_INSTALL_BINARY (Binary Installation Support)](../requirements/functional/installation.md#FR_INSTALL_BINARY) - Provides a fast and automated way to set up the CLI - ### Flow 1. Developer runs the platform-specific install script. @@ -69,11 +56,6 @@ The developer installs the Docgraph plugin in Claude Desktop. - [IF_CLAUDE_MARKETPLACE (Claude Marketplace)](../requirements/interfaces/interfaces.md#IF_CLAUDE_MARKETPLACE) -### Requirements - -- [FR_CLAUDE_INSTALL (Claude Plugin Installation)](../requirements/functional/claude.md#FR_CLAUDE_INSTALL) Mandatory for - enabling Docgraph within Claude Desktop - ### Flow 1. Developer adds the marketplace to Claude. @@ -95,16 +77,6 @@ The developer installs the `docgraph` VS Code extension. - [IF_VSCODE_MARKETPLACE (VS Code Marketplace)](../requirements/interfaces/interfaces.md#IF_VSCODE_MARKETPLACE) -### Requirements - -- [FR_VSC_BINARY_PATH (Binary Path Configuration)](../requirements/functional/vscode.md#FR_VSC_BINARY_PATH) Enables the - extension to find the docgraph engine -- [FR_VSC_MARKDOWN_ACTIVATION (Markdown Activation)](../requirements/functional/vscode.md#FR_VSC_MARKDOWN_ACTIVATION) - Restricts extension logic to Markdown files -- [FR_VSC_SERVER_LIFECYCLE (Server Lifecycle Commands)](../requirements/functional/vscode.md#FR_VSC_SERVER_LIFECYCLE) - Allows manual control over the LSP server -- [FR_CORE_AUTH (Authentication)](../requirements/functional/core.md#FR_CORE_AUTH) Securely identifies the developer - ### Flow 1. Developer downloads the VSIX file. diff --git a/doc/usecases/writing-specification.md b/doc/usecases/writing-specification.md index 578b8dc..7e88b9c 100644 --- a/doc/usecases/writing-specification.md +++ b/doc/usecases/writing-specification.md @@ -14,19 +14,6 @@ The developer writes specifications in Markdown using anchor heading format. - [IF_CONFIG (docgraph.toml Configuration)](../requirements/interfaces/interfaces.md#IF_CONFIG) -### Requirements - -- [FR_CORE_UNIQUE (Unique Node IDs)](../requirements/functional/core.md#FR_CORE_UNIQUE) Preventing ambiguity in - requirement references -- [FR_CORE_VALID_REF (Valid References)](../requirements/functional/core.md#FR_CORE_VALID_REF) Ensuring internal - consistency of the documentation graph -- [FR_CORE_TEMPLATE_VALIDATION (Template Validation)](../requirements/functional/core.md#FR_CORE_TEMPLATE_VALIDATION) - Ensuring documentation follows defined structural templates -- [FR_CORE_CONFIGURATION (Configuration)](../requirements/functional/core.md#FR_CORE_CONFIGURATION) Customizing - workspace behavior via docgraph.toml -- [FR_DEV_STANDARDS (Development Standards)](../requirements/functional/development.md#FR_DEV_STANDARDS) Ensuring - consistent commit and versioning practices - ### Flow 1. Developer opens a Markdown file. diff --git a/docgraph.toml b/docgraph.toml index b644250..113b3ed 100644 --- a/docgraph.toml +++ b/docgraph.toml @@ -9,79 +9,61 @@ ignore = ["README.md", "SECURITY.md", ".agent", ".claude", ".claude-plugin", "do desc = "Use Case" template = "doc/templates/usecases.md" rules = [ - { dir = "to", targets = [ - "ACT", - ], min = 1, desc = "Every use case must identify the initiating participant (Actor) to define scope and responsibility", rel = "triggered_by" }, - { dir = "to", targets = [ - "IF", - ], min = 1, desc = "Business scenarios must specify their interaction points (Interfaces) to ensure architectural decoupling", rel = "interacts_through" }, - { dir = "to", targets = [ - "FR", - ], min = 1, desc = "Use cases must be connected to functional outcomes (FR) to maintain business value traceability", rel = "uses" }, + # Intent is the root. No outgoing semantic dependencies required for definition context? + # Actually, Flow often references other UCs, but that's internal. + # Checking templates: We removed outgoing links. + # So rules should be empty or only 'from'? + # UC is 'Derived From' by others. + { dir = "to", targets = ["ACT"], min = 0, desc = "Use cases involves actors", rel = "involves" }, + { dir = "to", targets = ["IF"], min = 0, desc = "Use cases requires interfaces", rel = "requires" }, + { dir = "to", targets = ["FR"], min = 0, desc = "Use cases are elaborated by requirements", rel = "elaborated_by" }, ] [nodes.FR] desc = "Functional Requirement" template = "doc/templates/functional.md" rules = [ - { dir = "from", targets = [ - "UC", - ], min = 1, desc = "Every functional requirement must be driven by at least one business scenario (UC) to ensure user value", rel = "used_by" }, - { dir = "from", targets = [ - "CON", - ], min = 0, desc = "Functional requirements define how the system must behave within foundational constraints", rel = "constrained_by" }, { dir = "to", targets = [ - "MOD", - ], min = 1, desc = "Every requirement must be allocated to a structural component (Module) to ensure no functionality is left unimplemented", rel = "realized_by" }, + "UC", + ], min = 1, desc = "Every functional requirement must be derived from at least one business scenario (UC)", rel = "derived_from" }, { dir = "to", targets = [ - "NFR", - ], min = 0, desc = "Functional requirements may drive specific quality attribute requirements (NFR)", rel = "qualified_by" }, + "CON", + ], min = 0, desc = "Functional requirements may be derived from foundational constraints", rel = "derived_from" }, { dir = "to", targets = [ "IF", - ], min = 0, desc = "Functional requirements may define public API contracts or user interfaces (IF)", rel = "defines" }, - { dir = "to", targets = [ - "CC", - ], min = 0, desc = "Functional requirements may be reflected in cross-cutting concerns (CC) that apply across multiple modules", rel = "reflected_in" }, + ], min = 0, desc = "Functional requirements may reference interfaces", rel = "references" }, ] [nodes.NFR] desc = "Quality Requirement (Non-Functional)" template = "doc/templates/non-functional.md" rules = [ - { dir = "from", targets = [ + { dir = "to", targets = [ "FR", - ], min = 0, desc = "Quality requirements define the performance or security expectations for functional behavior", rel = "qualifies" }, - { dir = "from", targets = [ - "CON", - ], min = 0, desc = "Quality requirements define the quality attributes dictated by foundational constraints", rel = "constrained_by" }, + ], min = 0, desc = "Quality requirements qualify specific functional behavior", rel = "qualifies" }, { dir = "to", targets = [ + "CON", "CC", - ], min = 0, desc = "Quality requirements are reflected in cross-cutting designs (CC) that apply across modules", rel = "reflected_in" }, - { dir = "to", targets = [ - "MOD", - ], min = 0, desc = "Quality requirements may be realized through specific implementation details in modules (MOD)", rel = "realized_by" }, + ], min = 0, desc = "Quality requirements may be constrained by foundational constraints", rel = "constrained_by" }, ] [nodes.CON] desc = "Constraint" template = "doc/templates/constraint.md" rules = [ - { dir = "to", targets = [ - "FR", - "NFR", - ], min = 1, desc = "Foundational constraints must be embodied in actionable functional or quality requirements to guide system behavior", rel = "constrains" }, + # Root nodes. ] [nodes.MOD] desc = "Module" template = "doc/templates/module.md" rules = [ - { dir = "from", targets = [ + { dir = "to", targets = [ "FR", "NFR", "IF", "CC", - ], min = 1, desc = "Every structural module must be justified by at least one requirement or architectural concept to ensure purposeful design", rel = "realized_by" }, + ], min = 1, desc = "Every structural module must realize at least one requirement or architectural concept", rel = "realizes" }, ] # Architecture types @@ -89,16 +71,13 @@ rules = [ desc = "Cross-cutting Concept" template = "doc/templates/cross-cutting.md" rules = [ - { dir = "from", targets = [ + { dir = "to", targets = [ "NFR", "FR", - ], min = 0, desc = "Cross-cutting concerns address requirements that span multiple system modules", rel = "reflected_by" }, + ], min = 0, desc = "Cross-cutting concerns are reflected in requirements", rel = "reflected_in" }, { dir = "to", targets = [ "ADR", - ], min = 0, desc = "Cross-cutting concern designs lead to specific architectural decisions (ADR)", rel = "justified_by" }, - { dir = "to", targets = [ - "MOD", - ], min = 0, desc = "Cross-cutting concerns are realized through implementation patterns in specific modules (MOD)", rel = "realized_by" }, + ], min = 0, desc = "Cross-cutting concerns are decided by architectural decisions", rel = "decided_by" }, ] # Documentation types @@ -106,19 +85,19 @@ rules = [ desc = "Actor" template = "doc/templates/actors.md" rules = [ - { dir = "from", targets = [ + { dir = "to", targets = [ "*", - ], min = 0, desc = "Actors represent external entities interacting with the system across various boundary points", rel = "involves" }, - { dir = "from", targets = [ + ], min = 0, desc = "Actors represent external entities interacting with the system", rel = "involves" }, + { dir = "to", targets = [ "UC", - ], min = 1, desc = "System actors must specify the business scenarios (UC) they participate in", rel = "involved_in" }, + ], min = 1, desc = "System actors must participate in at least one business scenario (UC)", rel = "participates_in" }, ] [nodes.DAT] desc = "Data Entity" template = "doc/templates/data.md" rules = [ - { dir = "from", targets = [ + { dir = "to", targets = [ "*", ], min = 0, desc = "Data entities provide shared domain models utilized across multiple system components", rel = "uses_data" }, ] @@ -127,25 +106,22 @@ rules = [ desc = "Interface Specification" template = "doc/templates/interface.md" rules = [ - { dir = "from", targets = [ + { dir = "to", targets = [ "*", - ], min = 0, desc = "System interfaces define the public contracts for communication and integration points", rel = "integrated_with" }, - { dir = "from", targets = [ + ], min = 0, desc = "System interfaces define the public contracts", rel = "integrated_with" }, + { dir = "to", targets = [ "UC", ], min = 1, desc = "Exposed interfaces must be justified by at least one business scenario (UC)", rel = "justified_by" }, - { dir = "from", targets = [ - "FR", - ], min = 1, desc = "Interfaces must be connected to functional requirements to define their behavior", rel = "defined_by" }, { dir = "to", targets = [ - "MOD", - ], min = 1, desc = "Every interface specification must be implemented by a module (MOD) to ensure its realization", rel = "realized_by" }, + "FR", + ], min = 1, desc = "Interfaces must be defined by functional requirements", rel = "defined_by" }, ] [nodes.ADR] desc = "Architecture Decision Record" template = "doc/templates/decision.md" rules = [ - { dir = "from", targets = [ + { dir = "to", targets = [ "*", - ], min = 0, desc = "Architectural decisions provide the design rationale and historical context for system elements", rel = "informed_by" }, + ], min = 0, desc = "Architectural decisions provide the design rationale", rel = "informed_by" }, ]