docs: convert ASCII diagrams to Mermaid with dark-theme colors by unclesp1d3r · Pull Request #138 · EvilBit-Labs/libmagic-rs

unclesp1d3r · 2026-03-02T06:19:52Z

Summary

Convert ASCII art trust boundary diagram in security-assurance.md to Mermaid with proper untrusted/trusted zone styling
Convert ASCII art conversion pipeline diagrams in output.md to Mermaid flowcharts
Fix Mermaid syntax error in architecture.md hierarchical rule processing diagram (> in node labels broke rendering)
Replace all light pastel fill colors across 5 diagrams in architecture.md and 1 in security-assurance.md with dark-theme-compatible fills and light text
Update output.md references from evaluator::MatchResult to evaluator::RuleMatch

Test plan

mdbook build completes without errors
All Mermaid diagrams render correctly in the navy (dark) theme
No broken > characters in node labels
Text is readable against dark background fills

🤖 Generated with Claude Code

Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>

coderabbitai · 2026-03-02T06:20:09Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 8a8f6a1 and 0c581ec.

📒 Files selected for processing (3)

docs/src/architecture.md
docs/src/output.md
docs/src/security-assurance.md

Summary by CodeRabbit

Documentation
- Enhanced architecture diagrams with improved visual styling and clearer formatting for better readability.
- Updated documentation to reflect consistent API terminology across output documentation.
- Improved security documentation with modern visualization for trust boundary representation.

Walkthrough

Documentation updates across three markdown files: enriched Mermaid diagram styling in architecture.md, corrected type naming from MatchResult to RuleMatch in output.md, and replaced ASCII Trust Boundaries diagram with Mermaid flowchart in security-assurance.md.

Changes

Cohort / File(s)	Summary
Diagram Styling & Visualization `docs/src/architecture.md`, `docs/src/security-assurance.md`	Enhanced Mermaid diagram styling with richer colors (fill, stroke, text) and updated node label representations; replaced ASCII diagram with Mermaid flowchart for Trust Boundaries visualization.
Type Naming Corrections `docs/src/output.md`	Updated documentation terminology from `MatchResult` to `RuleMatch` across descriptions, diagrams, and example blocks to reflect evaluator-level type naming.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

libmagic-rs#33: Modifies the same documentation files and addresses related type naming changes (MatchResult vs. RuleMatch terminology).

Suggested labels

documentation, lgtm

Poem

🐰 Diagrams dance in colors bright,
Types renamed to fit just right,
Mermaid flows where ASCII stood,
Docs refined as they should! ✨

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch docs_tweaks

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

mergify · 2026-03-02T06:20:28Z

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟠 CI must pass

Waiting checks: coverage, test, test-cross-platform (macos-latest, macOS), test-cross-platform (ubuntu-22.04, Linux), test-cross-platform (ubuntu-latest, Linux), test-cross-platform (windows-latest, Windows).

All CI checks must pass. Release-plz PRs are exempt because they only bump versions and changelogs (code was already tested on main), and GITHUB_TOKEN-triggered force-pushes suppress CI.

check-success = coverage
check-success = test
check-success = test-cross-platform (macos-latest, macOS)
check-success = test-cross-platform (ubuntu-22.04, Linux)
check-success = test-cross-platform (ubuntu-latest, Linux)
check-success = test-cross-platform (windows-latest, Windows)
check-success = quality

🟢 Do not merge outdated PRs

Wonderful, this rule succeeded.

Make sure PRs are within 10 commits of the base branch before merging

#commits-behind <= 3

dosubot · 2026-03-02T06:20:35Z

Related Documentation

Checked 29 published document(s) in 1 knowledge base(s). No updates required.

^{How did I do? Any feedback?}

Copilot

Pull request overview

This PR updates the project documentation to replace ASCII diagrams with Mermaid diagrams and adjusts Mermaid styling to be readable in dark themes, while also aligning some docs with updated evaluator type naming.

Changes:

Converted ASCII trust-boundary and output conversion pipeline diagrams to Mermaid flowcharts.
Updated Mermaid diagram styling (fills/strokes/text colors) to be dark-theme compatible.
Updated output.md references from evaluator::MatchResult to evaluator::RuleMatch.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
docs/src/security-assurance.md	Replaces the trust boundary ASCII diagram with a Mermaid diagram and adds dark-theme styling.
docs/src/output.md	Updates evaluator type references and replaces ASCII pipeline diagrams with Mermaid flowcharts.
docs/src/architecture.md	Updates Mermaid diagram styling to dark-theme colors and adjusts hierarchical processing diagram labels.

Copilot · 2026-03-02T06:23:10Z

+    R -->|match| C1["Child Rule 1<br/>e.g., #gt;4 ubyte 0x14"]
+    R -->|match| C2["Child Rule 2<br/>e.g., #gt;4 ubyte 0x06"]


#gt; is not a valid HTML escape for > and will render literally in the node labels. If the goal is to avoid Mermaid/Markdown parsing issues with >, use > (or remove the > from the label text) so the diagram renders correctly and matches the PR’s intent of fixing the >-related syntax issue.

Suggested change

R -->|match| C1["Child Rule 1<br/>e.g., #gt;4 ubyte 0x14"]

R -->|match| C2["Child Rule 2<br/>e.g., #gt;4 ubyte 0x06"]

R -->|match| C1["Child Rule 1<br/>e.g., >4 ubyte 0x14"]

R -->|match| C2["Child Rule 2<br/>e.g., >4 ubyte 0x06"]

Copilot · 2026-03-02T06:23:10Z

+    subgraph libmagic-rs["libmagic-rs (Trusted Zone)"]
+        IO["I/O Layer<br/>mmap files, size limits"]
+        CLI["CLI<br/>clap args, validates paths"]
+        P["Parser<br/>validates magic syntax"]
+        E["Evaluator<br/>bounds-checks all access"]
+        O["Output<br/>formats results"]
+    end
+
+    IF -- "file bytes" --> IO
+    MF -- "magic syntax" --> P
+    CA -- "user paths" --> CLI
+    IO -- "mapped buffer" --> E
+    CLI -- "validated paths" --> IO
+    P -- "validated AST" --> E
+    E -- "match results" --> O
+
+    style Untrusted fill:#4a1a1a,stroke:#ef5350,color:#e0e0e0,stroke-width:2px
+    style libmagic-rs fill:#1b3d1b,stroke:#66bb6a,color:#e0e0e0,stroke-width:2px


In Mermaid flowcharts, subgraph identifiers should be simple IDs (typically alphanumeric/underscore). Using libmagic-rs as the subgraph ID risks being parsed incorrectly because of the -, and it’s also referenced in the style directive. Rename the subgraph ID to something like libmagic_rs (and update the corresponding style line) while keeping the displayed label as "libmagic-rs (Trusted Zone)".

codecov · 2026-03-02T06:23:28Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

unclesp1d3r added 2 commits March 2, 2026 01:08

docs(security): update security assurance case with new threat vectors

4a92b20

Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>

style(docs): update diagram styles for architecture and output sections

0c581ec

Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>

Copilot AI review requested due to automatic review settings March 2, 2026 06:19

dosubot Bot added the size:L This PR changes 100-499 lines, ignoring generated files. label Mar 2, 2026

Copilot started reviewing on behalf of unclesp1d3r March 2, 2026 06:20 View session

unclesp1d3r self-assigned this Mar 2, 2026

dosubot Bot added the documentation Improvements or additions to documentation label Mar 2, 2026

unclesp1d3r enabled auto-merge (squash) March 2, 2026 06:21

unclesp1d3r disabled auto-merge March 2, 2026 06:21

unclesp1d3r merged commit 762fbc1 into main Mar 2, 2026
25 of 27 checks passed

unclesp1d3r deleted the docs_tweaks branch March 2, 2026 06:21

coderabbitai Bot added the lgtm Approved for the merge queue label Mar 2, 2026

Copilot AI reviewed Mar 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: convert ASCII diagrams to Mermaid with dark-theme colors#138

docs: convert ASCII diagrams to Mermaid with dark-theme colors#138
unclesp1d3r merged 2 commits into
mainfrom
docs_tweaks

unclesp1d3r commented Mar 2, 2026

Uh oh!

coderabbitai Bot commented Mar 2, 2026 •

edited

Loading

Review failed

Uh oh!

mergify Bot commented Mar 2, 2026 •

edited

Loading

Uh oh!

dosubot Bot commented Mar 2, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 2, 2026

Uh oh!

Copilot AI Mar 2, 2026

Uh oh!

codecov Bot commented Mar 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		R -->\|match\| C1["Child Rule 1<br/>e.g., #gt;4 ubyte 0x14"]
		R -->\|match\| C2["Child Rule 2<br/>e.g., #gt;4 ubyte 0x06"]

Uh oh!

Conversation

unclesp1d3r commented Mar 2, 2026

Summary

Test plan

Uh oh!

coderabbitai Bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Summary by CodeRabbit

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Poem

Uh oh!

mergify Bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Protections

🟠 CI must pass

🟢 Do not merge outdated PRs

Uh oh!

dosubot Bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Mar 2, 2026

Codecov Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitai Bot commented Mar 2, 2026 •

edited

Loading

mergify Bot commented Mar 2, 2026 •

edited

Loading

dosubot Bot commented Mar 2, 2026 •

edited

Loading