🐚 shtracer

Zero-dependency requirements traceability for modern development workflows

Track requirements → architecture → implementation → tests using simple markdown tags. Built with pure POSIX shell for maximum portability and CI/CD integration.

---

🎯 Why shtracer?

Traditional requirements traceability tools are heavy, proprietary, and hard to integrate into modern development workflows. shtracer takes a different approach:

✨ Key Benefits

🔗 CI/CD Native

• Structured JSON output for seamless pipeline integration
• Parse, validate, and enforce traceability in your CI checks
• No databases, no servers—just pipe JSON to any tool you want

📦 Zero Dependencies

• Pure POSIX shell—works on Linux, macOS, Windows (Git Bash/WSL)
• No Python, Node.js, or runtime environments required

📝 Developer-Friendly

• Write requirements in plain Markdown—no proprietary formats
• Simple tag syntax in comments: e.g. <!-- @REQ-001@ --> (Tag syntax is written in the config file)
• Version control friendly: diffs are readable, merges are clean

🔄 Automated Maintenance

• Change mode: Rename tags across entire codebase in one command
• Verify mode: Detect orphaned or duplicate tags automatically
• Keep your traceability matrix accurate as requirements evolve

---

🚀 Quick Start

# Clone and run (no installation needed)
git clone https://github.com/qq3g7bad/shtracer.git
cd shtracer
chmod +x ./shtracer

# Generate traceability matrix
./shtracer ./sample/config.md

# Output structured JSON for CI/CD
./shtracer ./sample/config.md > traceability.json

# Generate interactive HTML report
./shtracer --html ./sample/config.md > report.html

# Generate markdown report
./shtracer --markdown ./sample/config.md > report.md

---

📖 How It Works

1. Tag your documents and code

requirements.md

<!-- @REQ-001@ -->
## User Authentication
Users must be able to log in with email and password.

architecture.md

<!-- @ARCH-101@ (FROM: @REQ-001@) -->
## Authentication Service
Implements OAuth 2.0 with JWT tokens.

auth.sh

# @IMPL-201@ (FROM: @ARCH-101@)
function authenticate_user() {
    # Implementation
}

auth_test.sh

# @TEST-301@ (FROM: @IMPL-201@)
test_authenticate_user() {
    # Test implementation
}

2. Generate traceability matrix

./shtracer ./sample/config.md

Output (JSON snippet):

{
  "metadata": {
    "version": "0.1.3",
    "generated": "2025-12-27T03:57:27Z",
    "config_path": "/path/to/config.md"
  },
  "files": [
    {"layer": "Requirement", "file": "requirements.md", "total": 10, "upstream_count": 0, "downstream_count": 8, "upstream_percent": 0, "downstream_percent": 80, "version": "git:abc123"},
    {"layer": "Architecture", "file": "architecture.md", "total": 5, "upstream_count": 5, "downstream_count": 3, "upstream_percent": 100, "downstream_percent": 60, "version": "git:def456"}
  ],
  "nodes": [
    {"id": "@REQ-001@", "description": "User authentication", "line": 15, "file_id": 0},
    {"id": "@ARCH-101@", "description": "Auth service design", "line": 42, "file_id": 1}
  ],
  "chains": [
    ["@REQ-001@", "@ARCH-101@", "@IMPL-201@", "@TEST-301@", "NONE"]
  ],
  "links": [
    {"source": "@REQ-001@", "target": "@ARCH-101@"}
  ]
}

3. (Optioanal) Interactive HTML Report

Coverage

Full trace

Sortable matrix with interactive tabs

---

⚙️ Usage

Basic Commands

# Generate traceability artifacts (tag table + JSON files)
./shtracer ./sample/config.md

# Generate standalone HTML report (Method 1: Use option)
./shtracer --html ./sample/config.md > report.html
# Generate standalone HTML report (Method 2: Use viewer)
./shtracer ./sample/config.md | ./scripts/main/shtracer_html_viewer.sh > report.html

# Generate markdown report (Method 1: Use option)
./shtracer --markdown ./sample/config.md > report.md
# Generate markdown report (Method 2: Use viewer)
./shtracer ./sample/config.md | ./scripts/main/shtracer_markdown_viewer.sh > report.md

# Rename tags across entire project
./shtracer -c @OLD-TAG@ @NEW-TAG@ ./sample/config.md

# Verify traceability (detect orphaned/duplicate tags)
./shtracer -v ./sample/config.md

# Run unit tests
./shtracer -t

Configuration File Format

The config.md file defines which files to trace and how to organize traceability links. Each section header defines a traceability level (e.g., ## Requirement, ## Architecture), and properties specify paths, tag patterns, and filters. List markers can use either * or -.

Quick Example:

## Requirement
* **PATH**: "./docs/requirements.md"
* **TAG FORMAT**: `@REQ[0-9\.]+@`
* **TAG LINE FORMAT**: `<!--.*-->`

## Implementation
* **PATH**: "./src/"
* **EXTENSION FILTER**: "*.sh"
* **TAG FORMAT**: `@IMP[0-9\.]+@`
* **TAG LINE FORMAT**: `#.*`

Key Properties:

• **PATH**: File or directory path (relative to config file)
• **TAG FORMAT**: ERE regex pattern for tags (in backticks)
• **TAG LINE FORMAT**: ERE pattern for lines containing tags (#.* for shell, <!--.*--> for markdown)
• **EXTENSION FILTER**: Optional file extension filter (e.g., *.sh)
• **IGNORE FILTER**: Optional ignore pattern using | for multiple conditions

📖 See ./sample/config.md for a complete working example.

---

🔧 Command Reference

Usage: shtracer <configfile> [options]

Options:
  -c, --change <old_tag> <new_tag> [--dry-run] Change mode: swap or rename trace target tags
  -v, --verify                     Verify mode: detect duplicate or isolated tags
  -t, --test                       Test mode: execute unit tests
  --html                           Export a single HTML document to stdout (JSON -> viewer)
  --markdown                       Export a print-friendly Markdown report to stdout (JSON -> markdown)
  --summary                        Print traceability summary to stdout (direct links only)
  --debug                          Keep temp files and output tag table to stderr
  -h, --help                       Show this help message

Examples:
  1. Normal mode (JSON output)
     $ ./shtracer ./sample/config.md
     $ ./shtracer ./sample/config.md > output.json

  2. Change mode (swap or rename tags)
     $ ./shtracer -c old_tag new_tag ./sample/config.md
     $ ./shtracer --change old_tag new_tag ./sample/config.md
     $ ./shtracer --dry-run -c old_tag new_tag ./sample/config.md

  3. Verify mode (check for duplicate or isolated tags)
     $ ./shtracer -v ./sample/config.md
     $ ./shtracer --verify ./sample/config.md

  4. Test mode
     $ ./shtracer -t
     $ ./shtracer --test

  5. Summary mode
     $ ./shtracer --summary ./sample/config.md

  6. HTML mode
     $ ./shtracer --html ./sample/config.md > output.html

  7. Markdown mode
     $ ./shtracer --markdown ./sample/config.md > report.md

  8. Debug mode (JSON + tag table to stderr)
     $ ./shtracer --debug ./sample/config.md > output.json

Note:
  - Arguments can be specified in any order.
  - Only one option can be used at a time.

---

💡 Use Cases

Available Exit Codes for CI/CD

• 0 - Success
• 1 - Invalid usage or arguments
• 2 - Config file not found
• 3 - Config file format invalid
• 10 - Failed to extract tags
• 11 - Failed to create tag table
• 12 - Failed to generate JSON
• 13 - Viewer script execution failed
• 20 - Found isolated tags (verify mode)
• 21 - Found duplicate tags (verify mode - highest priority)
• 22 - Found dangling FROM tag references (verify mode)
• 30 - Internal error
• 31 - Viewer script not found

Note (verify mode): If multiple issues exist, all are reported to stderr but exit code reflects highest-priority error (21 > 22 > 20)

Automated Documentation

Generate up-to-date traceability reports on every commit:

# In your CI/CD pipeline
./shtracer --html config.md > docs/traceability.html
git add docs/traceability.html
git commit -m "docs: update traceability matrix [skip ci]"

---

🔄 Pipeline Architecture & Custom Integration

Architecture Overview

flowchart LR
    A[shtracer<br/>Backend] -->|JSON| B{Processors}
    B -->|Built-in| C[shtracer_html_viewer.sh]
    B -->|Built-in| D[shtracer_markdown_viewer.sh]
    B -->|Standard| E[jq]
    B -->|Custom| F[Your Tool]
    C --> G[Interactive HTML]
    D --> H[Markdown Report]
    E --> I[Filtered Data]
    F --> J[Custom Output]

    style A fill:#e1f5ff,stroke:#01579b
    style B fill:#fff3e0,stroke:#e65100
    style C fill:#f3e5f5,stroke:#4a148c
    style D fill:#f3e5f5,stroke:#4a148c
    style E fill:#e8f5e9,stroke:#1b5e20
    style F fill:#fce4ec,stroke:#880e4f

Loading

Key Concepts:

• shtracer core = Backend (generates JSON only)
• Viewers = Independent filters (consume JSON from stdin/file)
• You = Can build custom tools using the JSON API

Using Viewers as Filters

Viewers can be invoked via flags (convenience) or as standalone filters (composability):

# Method 1: Using built-in flags (convenience)
./shtracer --html ./sample/config.md > report.html
./shtracer --markdown ./sample/config.md > report.md

# Method 2: Explicit pipeline (composability)
./shtracer ./sample/config.md | ./scripts/main/shtracer_html_viewer.sh > report.html
./shtracer ./sample/config.md | ./scripts/main/shtracer_markdown_viewer.sh > report.md

# Method 3: Custom processing before viewing
./shtracer ./sample/config.md | jq '.nodes |= map(select(.trace_target == ":Requirement"))' | ./scripts/main/shtracer_html_viewer.sh > filtered.html

---

🛠️ Development & Testing

System Requirements

POSIX-Compliant Shell (bash, dash, zsh, etc.)

• ✅ Linux/macOS: Built-in by default
• ✅ Windows: Git Bash, WSL, MinGW, or Cygwin

Optional Dependencies

• shUnit2 - Unit testing framework
• shellcheck - Shell script linter
• shfmt - Shell script formatter

Running Tests

# Run all unit tests (66 unit tests)
./shtracer -t

# Run integration tests (32 tests)
./scripts/test/integration/shtracer_integration_test.sh

# Lint shell scripts
shellcheck ./shtracer ./scripts/main/*.sh

# Format shell scripts (use v3.8.0 to match CI)
shfmt -w -i 2 -ci -bn ./shtracer ./scripts/main/*.sh

---

📄 License

This project is licensed under the MIT License.

---

🌐 Learn More

• 📖 Requirements Traceability Matrix (Wikipedia)
• 🐚 POSIX Shell Specification
• 🔗 GitHub Repository