docs: C4 diagram fixes + complete Tier 2 risk mitigation implementation (#272) by raifdmueller · Pull Request #283 · docToolchain/dacli

raifdmueller · 2026-02-12T09:10:23Z

Summary

This PR contains two main improvements:

1. Documentation: C4 Diagram Fixes (#272)

Fixed C4 diagrams based on Simon Brown's feedback
Added cross-references to parser specs as Level 4 (Code)
Improved Building Block View consistency

2. Security: Complete Tier 2 Risk Mitigation Implementation

Implemented all required security mitigations based on Risk Radar assessment:

Tier 1 — Automated Gates (100%)

✅ Pre-commit hooks with Ruff linting/formatting
✅ Dependency vulnerability scanning (pip-audit in CI)
✅ Security fixes: cryptography 46.0.3→46.0.5, pip 24.0→26.0.1

Tier 2 — Extended Assurance (100%)

✅ SAST: CodeQL with security-extended queries
✅ Property-based testing: Hypothesis (11 new tests, 1,100+ cases)
✅ PR Review Policy: Risk-based sampling (20-30%)
✅ SonarCloud: Quality gate integration

3. Architecture Decision Records (ADRs)

Created three ADRs documenting the Risk Radar assessment and mitigation decisions:

✅ ADR-011: Risk Classification - dacli CLI (Tier 2)
✅ ADR-012: Risk Classification - dacli-mcp (Tier 2)
✅ ADR-013: Security Mitigations - Tier 2 Implementation

Changes

Documentation

Fix C4 diagram issues (File System as ContainerDb, consistent component boundaries)
Add C4 quality rules to CLAUDE.md
Link parser specs as Level 4 from Building Block View
NEW: Add three Risk Radar ADRs to arc42 documentation

Security Mitigations (11 commits)

Add pre-commit hooks (.pre-commit-config.yaml)
Add pip-audit to CI pipeline
Fix 3 known vulnerabilities in dependencies
Add CodeQL SAST workflow (runs on upstream only)
Add SonarCloud quality gate workflow (runs on upstream only)
Create 11 property-based tests with Hypothesis
Create PR review policy (.github/PR_REVIEW_POLICY.md)
Update Risk Radar Assessment in CLAUDE.md
NEW: Document decisions in arc42 ADRs (ADR-011, ADR-012, ADR-013)

Code Quality

Auto-format entire codebase with Ruff (64 files)
Fix isinstance syntax to modern union type (int | float)
Add sonar-project.properties for quality metrics

Test Results

✅ All 713 tests passing (702 existing + 11 new property-based)
✅ No known vulnerabilities (pip-audit clean)
✅ All CI checks passing
✅ Pre-commit hooks validated

Breaking Changes

None

Migration Guide

For contributors:

Run uv sync --extra dev to install new dev dependencies (pre-commit, hypothesis)
Pre-commit hooks will auto-install on first commit
See .github/PR_REVIEW_POLICY.md for review requirements

Related Issues

Closes Docs: Feedback for 'Building Block View' 👍 #272 (C4 diagram improvements)
Implements Risk Radar Tier 2 mitigations
Documents decisions in ADR-011, ADR-012, ADR-013

Generated with 🤖 Claude Code (AI-assisted development)

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com

…hain#272) Add cross-references from the "Document Parser Architecture" section to the existing parser component specifications (04_markdown_parser, 05_asciidoc_parser) which contain state machine diagrams, data models, and include resolution algorithms — serving as C4 Level 4 (Code) views. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add pre-commit to dev dependencies (pyproject.toml) - Configure hooks: Ruff linting/formatting + basic file checks - Auto-fix formatting across codebase (ruff-format) - Fix isinstance syntax to use modern union syntax (int | float) - Hooks run automatically on git commit

- Add pip-audit step to GitHub Actions workflow - Scans all Python dependencies against PyPI Advisory Database - CI will fail if known vulnerabilities are found - Helps prevent supply chain attacks

- Add cryptography>=46.0.5 to fix CVE-2026-26007 - Upgrade pip to 26.0.1 (addresses 2 CVEs) - Verified with pip-audit: no known vulnerabilities - All 702 tests pass

- Configure GitHub CodeQL for Python analysis - Use security-extended query suite for deeper analysis - Run on push/PR to main/develop branches - Schedule weekly scans on Mondays - Detects: SQL injection, command injection, crypto issues, etc.

- Add Hypothesis to dev dependencies - Create property-based tests for parser utilities - Test slugify() and strip_doc_extension() functions - Verify functions never crash on random input - Test invariants: lowercase, no multiple dashes, idempotency - 11 new tests, each running 100 random examples (1,100+ test cases)

- Define review requirements by change type - Implement 20-30% sampling for non-critical PRs - Mandatory review for security, breaking changes, architecture - Auto-merge eligible: dependency updates, formatting fixes - Include review checklist and metrics tracking - Support AI-assisted development workflow

- Mark all implemented mitigations as 'Eingerichtet' - Update test count to 713 (added 11 property-based tests) - Add completion rates: Tier 1 100%, Tier 2 80% - Document commit hashes for each mitigation - Note security fixes applied

- Configure SonarCloud for code quality analysis - Set up GitHub Actions workflow for automatic scans - Use coverage.xml from pytest for code coverage metrics - Organization: doctoolchain - Project: docToolchain_dacli - Scans run on push/PR to main/develop branches

- Update mitigation status for both dacli modules - SonarCloud configured and integrated - Tier 2 completion: 5/5 (100%) - All required mitigations for Tier 2 now in place

- Add condition to skip SonarCloud on forks - Prevents SONAR_TOKEN errors on fork PRs - SonarCloud only runs on docToolchain/dacli - Forks don't need SonarCloud secrets configured

- Use continue-on-error for forks (missing SONAR_TOKEN) - Fails normally on upstream (docToolchain/dacli) - Prevents CI failures on fork PRs - SonarCloud runs when available, skips gracefully when not

- Workflows only needed on upstream (docToolchain/dacli) - Prevents CI failures on fork due to missing secrets - Workflows will be active after PR merge to upstream - CodeQL default setup already enabled on upstream

Created three Architecture Decision Records (Nygard format) documenting the Risk Radar assessment and mitigation implementation: - ADR-011: Risk Classification - dacli CLI (Tier 2) - ADR-012: Risk Classification - dacli-mcp (Tier 2) - ADR-013: Security Mitigations - Tier 2 Implementation Key decisions documented: - Tier 2 classification based on Code Type=2, Language=2, Blast Radius=2 - Repository-wide mitigation strategy (both modules share codebase) - 100% Tier 1+2 measure implementation (9/9 measures complete) - PR review policy with risk-based sampling (20-30%) - Security fixes: cryptography 46.0.5, pip 26.0.1 Each ADR includes: - Context with dimension scoring and evidence - Decision rationale with tier requirements - Pugh Matrix comparing alternatives - Consequences (positive and negative) - Implementation timeline with commit references Updated CLAUDE.md with links to new ADRs. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

raifdmueller · 2026-02-12T09:13:26Z

Closing to reorganize into separate PRs: parser-crossref (#272) and security mitigations

raifdmueller and others added 14 commits February 11, 2026 07:22

chore: add dependency vulnerability scanning to CI

fee56b6

- Add pip-audit step to GitHub Actions workflow - Scans all Python dependencies against PyPI Advisory Database - CI will fail if known vulnerabilities are found - Helps prevent supply chain attacks

security: fix dependency vulnerabilities

7766e90

- Add cryptography>=46.0.5 to fix CVE-2026-26007 - Upgrade pip to 26.0.1 (addresses 2 CVEs) - Verified with pip-audit: no known vulnerabilities - All 702 tests pass

chore: add CodeQL SAST security scanning

fead47e

- Configure GitHub CodeQL for Python analysis - Use security-extended query suite for deeper analysis - Run on push/PR to main/develop branches - Schedule weekly scans on Mondays - Detects: SQL injection, command injection, crypto issues, etc.

docs: mark SonarQube as implemented - Tier 2 now 100% complete

1a52130

- Update mitigation status for both dacli modules - SonarCloud configured and integrated - Tier 2 completion: 5/5 (100%) - All required mitigations for Tier 2 now in place

fix: restrict SonarCloud workflow to upstream repository only

64f4810

- Add condition to skip SonarCloud on forks - Prevents SONAR_TOKEN errors on fork PRs - SonarCloud only runs on docToolchain/dacli - Forks don't need SonarCloud secrets configured

fix: make SonarCloud optional on forks

0b26b83

- Use continue-on-error for forks (missing SONAR_TOKEN) - Fails normally on upstream (docToolchain/dacli) - Prevents CI failures on fork PRs - SonarCloud runs when available, skips gracefully when not

chore: remove CodeQL and SonarCloud workflows from fork

f9693d1

- Workflows only needed on upstream (docToolchain/dacli) - Prevents CI failures on fork due to missing secrets - Workflows will be active after PR merge to upstream - CodeQL default setup already enabled on upstream

raifdmueller closed this Feb 12, 2026

raifdmueller deleted the docs/parser-crossref-272 branch February 12, 2026 09:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: C4 diagram fixes + complete Tier 2 risk mitigation implementation (#272)#283

docs: C4 diagram fixes + complete Tier 2 risk mitigation implementation (#272)#283
raifdmueller wants to merge 14 commits intodocToolchain:mainfrom
raifdmueller:docs/parser-crossref-272

raifdmueller commented Feb 12, 2026

Uh oh!

raifdmueller commented Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

raifdmueller commented Feb 12, 2026

Summary

1. Documentation: C4 Diagram Fixes (#272)

2. Security: Complete Tier 2 Risk Mitigation Implementation

3. Architecture Decision Records (ADRs)

Changes

Documentation

Security Mitigations (11 commits)

Code Quality

Test Results

Breaking Changes

Migration Guide

Related Issues

Uh oh!

raifdmueller commented Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant