serve + improvements by ilijaljubicic · Pull Request #43 · reqvire-org/reqvire

ilijaljubicic · 2025-10-11T17:44:14Z

This PR introduces significant improvements to Reqvire's verification analysis capabilities, documentation serving, and CLI ergonomics.

🎯 Key Features

Redundant Verification Relations Detection (bf87d15)

Automatically detects and reports redundant verification relations where a verification verifies both a requirement and its ancestor in the hierarchy.

Implementation: Single-pass algorithm during trace tree building
Output Formats:
- Markdown: Displays Redundant Relations: section with clickable links under each verification diagram
- JSON: Includes redundant_relations array field (empty if none)
CLI Command: New slash command /find-redundant-verifications for identifying cleanup opportunities
Benefits: Helps maintain clean models by identifying redundant verify relations that can be removed

Example:
OAuth Flow Test verifies:

OAuth Implementation (redundant - ancestor)
Session Management (leaf - keep this)

HTTP Documentation Server (7e85541)

New serve command provides local HTTP server for documentation preview without manual export steps.

Command: reqvire serve [--host HOST] [--port PORT]
Features:
- Exports HTML to temp directory automatically
- Serves via lightweight HTTP server (tiny_http)
- Displays clickable terminal URL with ANSI formatting
- Quiet mode for export operations
- Proper Content-Type headers for all file types
Default: http://localhost:8080
Use Case: Quick local preview of documentation without publishing

Orphaned Verifications Tracking (e1d5e2a)

Enhanced coverage reports now identify verifications without any verify relations.

New Metrics:
- Total verifications count
- Orphaned verifications count and percentage
- ⚠️ Warning indicator in output
Output: Both text and JSON formats include orphaned verification details
Benefits: Identifies potentially misconfigured or redundant verification elements

CLI Command Restructuring (6b95724)

Reorganized command structure for better usability:

Before: Nested subcommands (e.g., model validate, verification traces)
After: Flat structure (e.g., validate, traces, matrix, coverage)
Improvements:
- Simplified command invocation
- Better discoverability
- Consistent with Unix CLI conventions

Non-Destructive HTML Export (6b95724)

HTML export no longer mutates source files:

Change: Uses temp folder for processing instead of modifying specifications
Artifacts: Includes traces, index, and matrix as header links
Benefits: Safer workflow, prevents accidental git commits of generated content

- Implement serve command that exports HTML to temp directory and serves via HTTP - Add --host and --port options with defaults (localhost:8080) - Display clickable terminal URL using ANSI escape codes - Implement quiet mode for export operations using thread-local flag - Add info_println! macro for conditional output based on quiet mode - Use tiny_http for lightweight HTTP server implementation - Create serve.rs module for static file serving with proper Content-Type headers - Add serve command verification and e2e test - Update agent instructions with Playwright MCP for visual inspection - Update diagrams to include serve command traceability

Implements automatic detection of redundant verification relations where a verification verifies both a requirement and its ancestor. Redundant relations are identified during trace tree building and displayed in both markdown and JSON outputs. Changes: - Add redundant_relations field to VerificationTrace struct - Implement redundancy detection during trace tree traversal - Display redundant relations in markdown output with links - Include redundant_relations array in JSON output (empty if none) - Update specifications and tests for redundant relations feature - Add test cases and expected outputs for validation

Document when to use requirements-engineer and e2e-test-engineer agents for model management, specification updates, and test implementation tasks.

Changed format command behavior to be safer by default: - Default mode now previews changes without applying them - Added --fix flag to actually apply formatting changes - Removed --dry-run flag (no longer needed as it's the default) - Updated CLI help text to reflect new behavior This aligns the format command with the new lint command pattern where safe preview is the default and explicit action is required to make changes. Updated files: - CLI implementation (cli.rs) - Requirements and verifications - Test cases and expected outputs - Documentation (CLAUDE.md, specifications/CLAUDE.md, tests/CLAUDE.md) All tests passing.

Updated the requirements-engineer agent to include running 'reqvire lint --fix' as part of the feature addition workflow to automatically clean up redundant verify relations and other semantic issues after adding or modifying specifications and verifications.

Updated note to clarify that linting should be done after completing a logical unit of work (complete feature) rather than after each individual change.

Add comprehensive linting functionality to analyze model quality and detect redundant relations in requirements specifications. Core Features: - Detects redundant verify relations (auto-fixable) - Detects maybe-redundant hierarchical relations (manual review needed) - Supports --fix flag to automatically remove redundant verify relations - Supports --fixable and --auditable flags to filter output - Supports --json flag for programmatic processing - Markdown link formatting for all file references Architecture: - Created shared trace_tree_builder module to avoid code duplication - Added remove_element_relation method to GraphRegistry for bidirectional relation removal (removes verify and verifiedBy pairs) - Implemented apply_fixes method in LintReport to remove redundant relations - Reuses format_files infrastructure to rewrite markdown files after fixes Implementation Details: - lint.rs: Core linting logic with issue detection and fixing - trace_tree_builder.rs: Shared upward trace traversal logic - graph_registry.rs: Added remove_element_relation with bidirectional support - cli.rs: CLI handler with --fix flag support Test Coverage: - test-lint-command: Comprehensive e2e test with 6 test scenarios - Tests verify detection, filtering, JSON output, fix functionality - Updated test-cli-help-structure to include new lint command

- Increase page width to 95% viewport for better space utilization - Add pan/zoom controls to all Mermaid diagrams with directional navigation buttons - Include satisfiedBy relations to code files and external resources in model diagram - Position diagrams at top-center by default for better initial view - Make diagram container use full available height with proper flexbox layout Improves usability for users without touchscreens and ensures all requirement traceability links (including to implementation files) are visible in diagrams.

- Updated section diagrams, model diagrams, and verification trace diagrams - userRequirement: fill:#f9d6d6, stroke:#f55f5f - systemRequirement: fill:#fce4e4, stroke:#e68a8a - verification: fill:#d6f9d6, stroke:#5fd75f - Updated test expectations to match new color scheme

- Check for correct userRequirement, systemRequirement, and verification colors - Ensures future color changes are caught by the test suite

- Changed description from 'Output traceability matrix as SVG' to 'Output model as Cypher queries for graph database import' - Updated test expectations to match corrected help text

ilijaljubicic · 2025-10-12T10:12:35Z

/reqvire impact

github-actions · 2025-10-12T10:13:41Z

Change Impact Report

Removed Elements

New Elements

File Pattern Exclusion for Format
- satisfiedBy -> utils.rs
- derive -> Excluded File Relation Validation ⚠️
  - satisfiedBy -> parser.rs
  - verifiedBy -> Unstructured Documents Test
    - satisfiedBy -> test.sh
Lint Output Formatting
Lint Command Verification
Redundant Verify Relations Detection
Inconsistent Newlines Format Implementation
- satisfiedBy -> format.rs
Lint Auto-fix Capability
Reserved Subsections Format Implementation
- satisfiedBy -> format.rs
Excess Whitespace Format Implementation
- satisfiedBy -> format.rs
Model Linting
- derive -> CLI Lint Command (new)
Missing Separators Format Implementation
- satisfiedBy -> format.rs
Maybe-Redundant Hierarchical Relations Detection

Changed Elements

Formatting Output
- derive -> Git-Style Diff Output for Format (new)
  - satisfiedBy -> format.rs
  - verifiedBy -> Format Command Requirements Verification ⚠️
    - satisfiedBy -> test.sh
Export HTML specifications
- derive -> HTML Export ⚠️
  - satisfiedBy -> cli.rs
  - satisfiedBy -> html.rs
  - satisfiedBy -> html_export.rs
  - derive -> Export Related System Elements
  - derive -> Model HTML Pages Design
Two-Pass Validation Strategy
- satisfiedBy -> model.rs
Verification Coverage Report
- derive -> CLI Coverage Command
  - satisfiedBy -> cli.rs
  - verifiedBy -> Verification Coverage Report Test
    - satisfiedBy -> test.sh
Model Formatting
- derive -> Format Command ⚠️
  - satisfiedBy -> cli.rs
Validate Cross-Component Dependencies
Serve Command
- satisfiedBy -> cli.rs
- satisfiedBy -> serve.rs
- verifiedBy -> Serve Command Verification (new)
  - satisfiedBy -> test.sh
Format Consistency Enforcement
Generate Diagrams
- derive -> Complete Model Structure Visualization (new)
  - derive -> Model Diagram SVG Generation (new)
    - verifiedBy -> Model Diagram SVG Verification (new)
Sections Summary Report Generator
- satisfiedBy -> sections_summary.rs
- derive -> CLI Sections Summary Command
  - satisfiedBy -> cli.rs
  - verifiedBy -> Sections Summary Tests
    - satisfiedBy -> test.sh
Validate Internal Consistency
Verification Upward Traceability
- derive -> CLI Matrix Command
  - satisfiedBy -> cli.rs
  - satisfiedBy -> matrix_generator.rs
  - derive -> CLI Matrix JSON Flag
Documentation Index for HTML Export
- derive -> HTML Navigation Enhancement
  - satisfiedBy -> html.rs
  - satisfiedBy -> html_export.rs
  - verifiedBy -> HTML Export Verification
    - satisfiedBy -> test.sh
CLI Interface Structure
- satisfiedBy -> cli.rs
- derive -> CLI Change Impact Report Command
  - derive -> Change Impact Command Line Interface
    - verifiedBy -> Change Impact Detection Test
  - derive -> CLI Git Commit Hash Flag
    - verifiedBy -> CLI Git Commit Hash Flag Test
Validate Markdown Structure
Remove Generated Diagrams
- derive -> Diagram Removal ⚠️
  - satisfiedBy -> diagrams.rs
  - derive -> CLI Remove Diagrams Flag
    - satisfiedBy -> cli.rs
Ignoring Unstructured Documents
- satisfiedBy -> config.rs
- derive -> Excluded File Relation Validation ⚠️
  - verifiedBy -> Unstructured Documents Test
    - satisfiedBy -> test.sh
Promote Automation and Efficiency
- derive -> Efficient Processing
Verification Trace Builder
- derive -> CLI Traces Command ⚠️
  - satisfiedBy -> cli.rs
  - derive -> CLI Traces Filter Options
    - verifiedBy -> Verification Traces Filter Options Test ⚠️
      - satisfiedBy -> test.sh
  - derive -> CLI Traces From-Folder Option
    - verifiedBy -> Verification Traces From-Folder Test
Interactive Mermaid Diagrams
- derive -> Diagram Generation
  - satisfiedBy -> diagrams.rs
  - derive -> Auto-Generated Diagram Identification
    - satisfiedBy -> parser.rs
    - satisfiedBy -> utils.rs
    - verifiedBy -> Diagram Generation Test
  - derive -> Interactive Mermaid Diagram Node Behavior
Model Structure and Summaries
- derive -> Model Summary Report Generator
  - satisfiedBy -> reports.rs
  - derive -> CLI Summary Report Command ⚠️
    - satisfiedBy -> cli.rs
    - derive -> Display Name-Regex Option in Help
      - verifiedBy -> Model Summary Tests
        
        satisfiedBy -> test.sh
Validating Structures
- derive -> Enhanced Validation Error Reporting
  - derive -> Detailed Error Handling and Logging ⚠️
    - satisfiedBy -> error.rs
    - derive -> Validation Error Handling
      - satisfiedBy -> model.rs
- derive -> Validate Filesystem Structure
Verification Coverage Report Generator
- derive -> CLI Coverage Command
  - satisfiedBy -> cli.rs
  - verifiedBy -> Verification Coverage Report Test
    - satisfiedBy -> test.sh
Provide Validation Reports

Invalidated Verifications

- Updated generate_model_diagram() to accept optional root_element_id parameter - When root_element_id is provided, generates focused diagram from that element - Adds collect_related_elements() to traverse graph from root element - Adds group_elements_by_file_filtered() to filter elements in diagram - Default behavior (None) maintains full model diagram generation - Enables future CLI support for focused model diagrams

Added sorting to ensure deterministic output in model command: - Sort elements within sections by identifier - Sort relations by source_id, target_id, and relation_type - Existing sorting for folders, files, and sections maintained This fixes the test-model-command test failure caused by HashMap iteration order being non-deterministic across runs.

Implement distinction between safe (auto-fixable) and unsafe (manual review) redundant hierarchical relations in the lint command. Safe redundant relations are those with a single unambiguous chain (A→B→C with redundant direct A→C). These can be safely auto-removed when using `reqvire lint --fix`. Unsafe redundant relations occur when multiple paths converge to the same ancestor (A→B→C and A→D→C with redundant direct A→C). These require manual review as both paths may have semantic meaning. Implementation: - Add SafeRedundantHierarchicalRelations variant to AutoFixableIssue - Implement path counting logic to distinguish single-chain from multi-path - Split detect_maybe_redundant_hierarchical_relations into safe/unsafe cases - Update apply_fixes to handle safe hierarchical relation removal - Add sorting for deterministic output in lint reports - Update test suite with comprehensive test cases Testing: - Extended test-lint-command with single-chain and multi-path examples - Verified diff-based test validation for file modifications - All tests pass successfully Traceability: - Satisfies: specifications/SystemRequirements/Requirements.md#safe-redundant-hierarchical-relations-auto-removal - Verified by: specifications/Verifications/Misc.md#lint-command-verification

ilijaljubicic added 15 commits October 11, 2025 18:33

Reformated

74b4e66

Updayed agent

a389eee

Add specialized agent usage guidelines to CLAUDE.md

ae68f3c

Document when to use requirements-engineer and e2e-test-engineer agents for model management, specification updates, and test implementation tasks.

Clarify lint timing in requirements-engineer workflow

dd7ef47

Updated note to clarify that linting should be done after completing a logical unit of work (complete feature) rather than after each individual change.

model diagram added: WIP

814c2d1

Add color scheme validation to diagram generation test

1f868a3

- Check for correct userRequirement, systemRequirement, and verification colors - Ensures future color changes are caught by the test suite

removed redudant cerify relations

22810fb

Fix incorrect cypher flag description in summary command

7e08682

- Changed description from 'Output traceability matrix as SVG' to 'Output model as Cypher queries for graph database import' - Updated test expectations to match corrected help text

reqvire-org deleted a comment from github-actions bot Oct 12, 2025

Merge branch 'main' into reqvire-browser

1157346

ilijaljubicic added 3 commits October 12, 2025 15:27

ilijaljubicic merged commit e0ed43b into main Oct 12, 2025
3 checks passed

ilijaljubicic deleted the reqvire-browser branch October 12, 2025 12:28

github-actions bot locked and limited conversation to collaborators Oct 12, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

serve + improvements#43

serve + improvements#43
ilijaljubicic merged 19 commits intomainfrom
reqvire-browser

ilijaljubicic commented Oct 11, 2025

Uh oh!

ilijaljubicic commented Oct 12, 2025

Uh oh!

github-actions bot commented Oct 12, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

ilijaljubicic commented Oct 11, 2025

Uh oh!

ilijaljubicic commented Oct 12, 2025

Uh oh!

github-actions bot commented Oct 12, 2025

Change Impact Report

Removed Elements

New Elements

Changed Elements

Invalidated Verifications

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant