{"id":17570946,"url":"https://github.com/qq3g7bad/shtracer","last_synced_at":"2026-03-07T02:35:35.510Z","repository":{"id":258016686,"uuid":"871955131","full_name":"qq3g7bad/shtracer","owner":"qq3g7bad","description":"Open source traceability matrix generator written in shell scripts.","archived":false,"fork":false,"pushed_at":"2026-02-18T23:09:54.000Z","size":1580,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-19T04:53:09.134Z","etag":null,"topics":["requirements-management","requirements-traceability","requirements-tracing","shell","shell-script"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qq3g7bad.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-13T12:16:11.000Z","updated_at":"2026-02-08T10:51:19.000Z","dependencies_parsed_at":"2024-10-25T01:14:15.357Z","dependency_job_id":"7a8ebf47-e37b-4620-88b3-1ccc539c36e6","html_url":"https://github.com/qq3g7bad/shtracer","commit_stats":{"total_commits":8,"total_committers":2,"mean_commits":4.0,"dds":0.25,"last_synced_commit":"62f4923c8e2aaa08cc1048eaf1a3ec48fbafb797"},"previous_names":["qq3g7bad/shtracer"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/qq3g7bad/shtracer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qq3g7bad%2Fshtracer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qq3g7bad%2Fshtracer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qq3g7bad%2Fshtracer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qq3g7bad%2Fshtracer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qq3g7bad","download_url":"https://codeload.github.com/qq3g7bad/shtracer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qq3g7bad%2Fshtracer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30206087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"online","status_checked_at":"2026-03-07T02:00:06.765Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["requirements-management","requirements-traceability","requirements-tracing","shell","shell-script"],"created_at":"2024-10-21T18:04:38.630Z","updated_at":"2026-03-07T02:35:35.486Z","avatar_url":"https://github.com/qq3g7bad.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐚 shtracer\n\n[![CI Tests](https://github.com/qq3g7bad/shtracer/actions/workflows/test.yml/badge.svg)](https://github.com/qq3g7bad/shtracer/actions/workflows/test.yml)\n[![License](https://img.shields.io/github/license/qq3g7bad/shtracer)](LICENSE)\n[![Shell](https://img.shields.io/badge/shell-POSIX-green.svg)](https://pubs.opengroup.org/onlinepubs/9699919799/)\n\n**Zero-dependency requirements traceability for modern development workflows**\n\nTrack requirements → architecture → implementation → tests using simple markdown tags. Built with pure POSIX shell for maximum portability and CI/CD integration.\n\n---\n\n## 🎯 Why shtracer?\n\nTraditional requirements traceability tools are **heavy, proprietary, and hard to integrate** into modern development workflows. shtracer takes a different approach:\n\n### ✨ Key Benefits\n\n**🔗 CI/CD Native**\n\n- **Structured JSON output** for seamless pipeline integration\n- Parse, validate, and enforce traceability in your CI checks\n- No databases, no servers—just pipe JSON to any tool you want\n\n**📦 Zero Dependencies**\n\n- Pure POSIX shell—works on Linux, macOS, Windows (Git Bash/WSL)\n- No Python, Node.js, or runtime environments required\n\n**📝 Developer-Friendly**\n\n- Write requirements in **plain Markdown**—no proprietary formats\n- Simple tag syntax in comments: e.g. `\u003c!-- @REQ-001@ --\u003e` (Tag syntax is written in the config file)\n- Version control friendly: diffs are readable, merges are clean\n\n**🔄 Automated Maintenance**\n\n- **Change mode**: Rename tags across entire codebase in one command\n- **Verify mode**: Detect orphaned or duplicate tags automatically\n- Keep your traceability matrix accurate as requirements evolve\n\n---\n\n## 🚀 Quick Start\n\n```bash\n# Clone and run (no installation needed)\ngit clone https://github.com/qq3g7bad/shtracer.git\ncd shtracer\nchmod +x ./shtracer\n\n# Generate traceability matrix\n./shtracer ./sample/config.md\n\n# Output structured JSON for CI/CD\n./shtracer ./sample/config.md \u003e traceability.json\n\n# Generate interactive HTML report\n./shtracer --html ./sample/config.md \u003e report.html\n\n# Generate markdown report\n./shtracer --markdown ./sample/config.md \u003e report.md\n```\n\n---\n\n## 📖 How It Works\n\n### 1. Tag your documents and code\n\n**requirements.md**\n\n```markdown\n\u003c!-- @REQ-001@ --\u003e\n## User Authentication\nUsers must be able to log in with email and password.\n```\n\n**architecture.md**\n\n```markdown\n\u003c!-- @ARCH-101@ (FROM: @REQ-001@) --\u003e\n## Authentication Service\nImplements OAuth 2.0 with JWT tokens.\n```\n\n**auth.sh**\n\n```bash\n# @IMPL-201@ (FROM: @ARCH-101@)\nfunction authenticate_user() {\n    # Implementation\n}\n```\n\n**auth_test.sh**\n\n```bash\n# @TEST-301@ (FROM: @IMPL-201@)\ntest_authenticate_user() {\n    # Test implementation\n}\n```\n\n### 2. Generate traceability matrix\n\n```bash\n./shtracer ./sample/config.md\n```\n\n**Output (JSON snippet)**:\n\n```json\n{\n  \"metadata\": {\n    \"version\": \"0.1.3\",\n    \"generated\": \"2025-12-27T03:57:27Z\",\n    \"config_path\": \"/path/to/config.md\"\n  },\n  \"files\": [\n    {\"layer\": \"Requirement\", \"file\": \"requirements.md\", \"total\": 10, \"upstream_count\": 0, \"downstream_count\": 8, \"upstream_percent\": 0, \"downstream_percent\": 80, \"version\": \"git:abc123\"},\n    {\"layer\": \"Architecture\", \"file\": \"architecture.md\", \"total\": 5, \"upstream_count\": 5, \"downstream_count\": 3, \"upstream_percent\": 100, \"downstream_percent\": 60, \"version\": \"git:def456\"}\n  ],\n  \"nodes\": [\n    {\"id\": \"@REQ-001@\", \"description\": \"User authentication\", \"line\": 15, \"file_id\": 0},\n    {\"id\": \"@ARCH-101@\", \"description\": \"Auth service design\", \"line\": 42, \"file_id\": 1}\n  ],\n  \"chains\": [\n    [\"@REQ-001@\", \"@ARCH-101@\", \"@IMPL-201@\", \"@TEST-301@\", \"NONE\"]\n  ],\n  \"links\": [\n    {\"source\": \"@REQ-001@\", \"target\": \"@ARCH-101@\"}\n  ]\n}\n```\n\n### 3. (Optioanal) Interactive HTML Report\n\n#### Coverage\n\n![type](./docs/img/type.png)\n\n#### Full trace\n\n![full](./docs/img/full.png)\n\n#### Sortable matrix with interactive tabs\n\n![matrix](./docs/img/matrix.png)\n\n---\n\n## ⚙️ Usage\n\n### Basic Commands\n\n```bash\n# Generate traceability artifacts (tag table + JSON files)\n./shtracer ./sample/config.md\n\n# Generate standalone HTML report (Method 1: Use option)\n./shtracer --html ./sample/config.md \u003e report.html\n# Generate standalone HTML report (Method 2: Use viewer)\n./shtracer ./sample/config.md | ./scripts/main/shtracer_html_viewer.sh \u003e report.html\n\n# Generate markdown report (Method 1: Use option)\n./shtracer --markdown ./sample/config.md \u003e report.md\n# Generate markdown report (Method 2: Use viewer)\n./shtracer ./sample/config.md | ./scripts/main/shtracer_markdown_viewer.sh \u003e report.md\n\n# Rename tags across entire project\n./shtracer -c @OLD-TAG@ @NEW-TAG@ ./sample/config.md\n\n# Verify traceability (detect orphaned/duplicate tags)\n./shtracer -v ./sample/config.md\n\n# Run unit tests\n./shtracer -t\n```\n\n### Configuration File Format\n\nThe `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.\n\n**Quick Example:**\n\n```markdown\n## Requirement\n* **PATH**: \"./docs/requirements.md\"\n* **TAG FORMAT**: `@REQ[0-9\\.]+@`\n* **TAG LINE FORMAT**: `\u003c!--.*--\u003e`\n\n## Implementation\n* **PATH**: \"./src/\"\n* **EXTENSION FILTER**: \"*.sh\"\n* **TAG FORMAT**: `@IMP[0-9\\.]+@`\n* **TAG LINE FORMAT**: `#.*`\n```\n\n**Key Properties:**\n\n- `**PATH**`: File or directory path (relative to config file)\n- `**TAG FORMAT**`: ERE regex pattern for tags (in backticks)\n- `**TAG LINE FORMAT**`: ERE pattern for lines containing tags (`#.*` for shell, `\u003c!--.*--\u003e` for markdown)\n- `**EXTENSION FILTER**`: Optional file extension filter (e.g., `*.sh`)\n- `**IGNORE FILTER**`: Optional ignore pattern using `|` for multiple conditions\n\n📖 **See [`./sample/config.md`](./sample/config.md) for a complete working example.**\n\n---\n\n## 🔧 Command Reference\n\n```text\nUsage: shtracer \u003cconfigfile\u003e [options]\n\nOptions:\n  --html                           Generate standalone HTML report to stdout\n  --markdown                       Generate markdown report to stdout\n  --summary                        Print traceability summary (direct links only)\n  -c \u003cold_tag\u003e \u003cnew_tag\u003e           Rename/swap tags across all traced files\n  -v                               Verify mode: detect duplicate or orphaned tags\n  -t                               Run unit tests\n  -h, --help                       Show this help message\n\nExamples:\n  # Generate traceability matrix\n  ./shtracer ./sample/config.md\n\n  # CI/CD pipeline integration\n  ./shtracer ./sample/config.md | jq '.chains'\n\n  # Create HTML report\n  ./shtracer --html ./sample/config.md \u003e report.html\n\n  # Refactor: rename tags across entire project\n  ./shtracer -c @OLD-001@ @NEW-001@ ./sample/config.md\n\n  # Quality check: find broken traceability\n  ./shtracer -v ./sample/config.md\n```\n\n---\n\n## 💡 Use Cases\n\n### Available Exit Codes for CI/CD\n\n- `0` - Success\n- `1` - Invalid usage or arguments\n- `2` - Config file not found\n- `10` - Failed to extract tags\n- `11` - Failed to create tag table\n- `12` - Failed to generate JSON\n- `20` - Found isolated tags (verify mode)\n- `21` - Found duplicate tags (verify mode)\n- `22` - Found both isolated and duplicate tags (verify mode)\n\n### Automated Documentation\n\nGenerate up-to-date traceability reports on every commit:\n\n```bash\n# In your CI/CD pipeline\n./shtracer --html config.md \u003e docs/traceability.html\ngit add docs/traceability.html\ngit commit -m \"docs: update traceability matrix [skip ci]\"\n```\n\n---\n\n## 🔄 Pipeline Architecture \u0026 Custom Integration\n\n### Architecture Overview\n\n```mermaid\nflowchart LR\n    A[shtracer\u003cbr/\u003eBackend] --\u003e|JSON| B{Processors}\n    B --\u003e|Built-in| C[shtracer_html_viewer.sh]\n    B --\u003e|Built-in| D[shtracer_markdown_viewer.sh]\n    B --\u003e|Standard| E[jq]\n    B --\u003e|Custom| F[Your Tool]\n    C --\u003e G[Interactive HTML]\n    D --\u003e H[Markdown Report]\n    E --\u003e I[Filtered Data]\n    F --\u003e J[Custom Output]\n\n    style A fill:#e1f5ff,stroke:#01579b\n    style B fill:#fff3e0,stroke:#e65100\n    style C fill:#f3e5f5,stroke:#4a148c\n    style D fill:#f3e5f5,stroke:#4a148c\n    style E fill:#e8f5e9,stroke:#1b5e20\n    style F fill:#fce4ec,stroke:#880e4f\n```\n\n**Key Concepts:**\n\n- **shtracer core** = Backend (generates JSON only)\n- **Viewers** = Independent filters (consume JSON from stdin/file)\n- **You** = Can build custom tools using the JSON API\n\n### Using Viewers as Filters\n\nViewers can be invoked via flags (convenience) or as standalone filters (composability):\n\n```bash\n# Method 1: Using built-in flags (convenience)\n./shtracer --html ./sample/config.md \u003e report.html\n./shtracer --markdown ./sample/config.md \u003e report.md\n\n# Method 2: Explicit pipeline (composability)\n./shtracer ./sample/config.md | ./scripts/main/shtracer_html_viewer.sh \u003e report.html\n./shtracer ./sample/config.md | ./scripts/main/shtracer_markdown_viewer.sh \u003e report.md\n\n# Method 3: Custom processing before viewing\n./shtracer ./sample/config.md | jq '.nodes |= map(select(.trace_target == \":Requirement\"))' | ./scripts/main/shtracer_html_viewer.sh \u003e filtered.html\n```\n\n---\n\n## 🛠️ Development \u0026 Testing\n\n### System Requirements\n\n**POSIX-Compliant Shell** (bash, dash, zsh, etc.)\n\n- ✅ Linux/macOS: Built-in by default\n- ✅ Windows: Git Bash, WSL, MinGW, or Cygwin\n\n**Optional Dependencies**\n\n- [shUnit2](https://github.com/kward/shunit2) - Unit testing framework\n- [shellcheck](https://www.shellcheck.net/) - Shell script linter\n- [shfmt](https://github.com/mvdan/sh) - Shell script formatter\n\n### Running Tests\n\n```bash\n# Run all unit tests (66 unit tests)\n./shtracer -t\n\n# Run integration tests (32 tests)\n./scripts/test/integration/shtracer_integration_test.sh\n\n# Lint shell scripts\nshellcheck ./shtracer ./scripts/main/*.sh\n\n# Format shell scripts (use v3.8.0 to match CI)\nshfmt -w -i 2 -ci -bn ./shtracer ./scripts/main/*.sh\n```\n\n---\n\n## 📄 License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n---\n\n## 🌐 Learn More\n\n- 📖 [Requirements Traceability Matrix (Wikipedia)](https://en.wikipedia.org/wiki/Traceability_matrix)\n- 🐚 [POSIX Shell Specification](https://pubs.opengroup.org/onlinepubs/9699919799/)\n- 🔗 [GitHub Repository](https://github.com/qq3g7bad/shtracer)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqq3g7bad%2Fshtracer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqq3g7bad%2Fshtracer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqq3g7bad%2Fshtracer/lists"}