dia-log

Annotate a Mermaid architecture diagram with TODO comment counts or git changes, mapped to the modules in your project.

Getting started

1. Scaffold config files

npx dia-log init

Creates files in your project:

| File | Purpose | |---|---| | dia-log/base.mmd | Your architecture diagram in Mermaid syntax | | dia-log/mapping.json | Maps each diagram node to a source directory |

2. Edit dia-log/mapping.json

Point each key at a real source directory in your repo:

{
  "adapter_in": "src/adapter/in"
}

Paths are relative to your repository root. If a path doesn't exist, the tool will warn you and skip that node.

3. Optionally update dia-log/base.mmd

The scaffolded diagram shows a single hexagonal module. Add more subgraphs, change node labels, or restructure the layout to match your architecture. Node IDs in base.mmd must match the keys in mapping.json.

4. Generate

Annotate with TODO comment counts:

# All TODOs
npx dia-log --todos

# Only TODOs containing a specific string (e.g. a ticket ID)
npx dia-log --todos IOM-1425

Annotate with git changes:

# Open / uncommitted changes (staged + unstaged)
npx dia-log --changes

# Changes introduced by the last commit
npx dia-log --changes HEAD~1

# Last N commits combined
npx dia-log --changes HEAD~5

# Diff vs another branch or tag
npx dia-log --changes main
npx dia-log --changes v1.0..HEAD

Output is written to dia-log/generated.mmd.

5. View

Open dia-log/generated.mmd in any Mermaid viewer:

• IntelliJ / WebStorm — built-in Mermaid preview
• VS Code — Markdown Preview Mermaid Support
• Browser — mermaid.live

Change colours

| Class | Used for | Default colour | |---|---|---| | core | Adapters, Application, Domain | amber | | port | Port In / Port Out | yellow | | sk | Shared Kernel, Mapping | purple | | infra | Infrastructure modules | grey | | orchestrator | Orchestrator / main module | blue | | lib | Standalone libraries | green |

Edit the classDef lines in base.mmd to customise.

Help

npx dia-log --help

Contributing / local dev

git clone <repo>
cd dia-log
npm install

Run the tool locally from the dia-log/ folder:

npm run dia-log             # --todos, opens generated.mmd in IntelliJ
npm run dia-log:changes     # --changes
npm run dia-log:last-commit # --changes HEAD~1

How the code is structured

| File | Role | |---|---| | bin/cli.js | CLI entry point — parses commands/flags via commander, sets DIA_LOG_ROOT, delegates to generate.js | | generate.js | Core logic — reads mapping.json + base.mmd, walks files or queries git, injects annotations, writes generated.mmd | | init/ | Scaffold templates copied by npx dia-log init |

Adding a new node style

1. Add a classDef line in init/base.mmd (e.g. classDef myStyle fill:#abc)
2. Apply it to nodes with :::myStyle
3. Document the new class in the colour table above