npm package: @gi11i4m/dia-log
Description: Visualize git logs and TODO counts on your architecture diagram
Latest version: 0.1.11

# 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

```bash
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:

```json
{
  "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:**

```bash
# 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:**

```bash
# 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](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid)
- **Browser** — [mermaid.live](https://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

```bash
npx dia-log --help
```

---

## Contributing / local dev

```bash
git clone <repo>
cd dia-log
npm install
```

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

```bash
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