Merge pull request #64 from bartstc/chore/add-madge

chore: introduce madge

Author: bartstc

.devcontainer/Dockerfile

@@ -2,12 +2,12 @@ FROM mcr.microsoft.com/devcontainers/typescript-node:dev-22
 
 RUN corepack enable
 
-# Install GitHub CLI
+# Install GitHub CLI and graphviz (graphviz is required by `pnpm madge:graph` to render the dependency graph image)
 RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
     && chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
     && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
     && apt update \
-    && apt install -y gh
+    && apt install -y gh graphviz
 
 # Setup Claude Code
 

.github/workflows/ci.yml

@@ -26,6 +26,12 @@ jobs:
       test-type: typecheck
       test-command: pnpm typecheck
 
+  madge-circular:
+    uses: ./.github/workflows/run-tests.yml
+    with:
+      test-type: madge-circular
+      test-command: pnpm madge:circular
+
   playwright-tests:
     uses: ./.github/workflows/playwright.yml
     with:
@@ -159,7 +165,14 @@ jobs:
 
   build:
     needs:
-      [lint-tests, typecheck, unit-tests, storybook-tests, playwright-tests]
+      [
+        lint-tests,
+        typecheck,
+        madge-circular,
+        unit-tests,
+        storybook-tests,
+        playwright-tests,
+      ]
     runs-on: ubuntu-latest
     steps:
       - name: Checkout

.gitignore

@@ -14,6 +14,7 @@ dist-ssr
 storybook-static
 coverage
 storybook-report.json
+graph.png
 
 # Editor directories and files
 .idea

README.md

@@ -9,6 +9,7 @@ An opinionated, production-ready starter for **Single Page Application** develop
 - [Vite](https://vitejs.dev/) — fast dev server and build tooling
 - [TypeScript](https://www.typescriptlang.org/) — strict type safety
 - [ESLint](https://eslint.org/) (with custom rules) + [Prettier](https://prettier.io/) + [Husky](https://typicode.github.io/husky/) — consistent code style
+- [madge](https://github.com/pahen/madge) — circular dependency check + module graph visualization
 - [PNPM](https://pnpm.io/) — fast, disk-efficient package manager
 - [Devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) — reproducible VS Code dev environment
 - [GitHub Actions](https://docs.github.com/en/actions) CI — tests, build, coverage reports, deploy draft
@@ -42,6 +43,7 @@ e2e/        Playwright end-to-end tests
 
 - Feature slice architecture with clean architecture principles — each feature has four layers (`components/`, `application/`, `providers/`, `models/`) with strict dependency rules
 - Strict ESLint guardrails enforce the feature-slice layer boundaries. See [`eslint.config.mjs`](eslint.config.mjs).
+- Circular dependency check and dependency graph visualization via `madge` (`pnpm madge:circular` / `pnpm madge:graph`)
 - Centralized API layer with endpoint-based organization and type consolidation
 - Spec-driven development for AI-assisted workflows — four-phase gated spec process, typed building block patterns, and a self-improvement loop
 - Formatting utilities for numbers, monetary values, and dates
@@ -75,24 +77,26 @@ It's recommended to run the dev server inside a container for consistent Node/PN
 
 ## Commands
 
-| Command                | Description                                |
-| ---------------------- | ------------------------------------------ |
-| `pnpm dev`             | Dev server with HMR on port `5173`         |
-| `pnpm dev:server`      | Local API server only on port `3001`       |
-| `pnpm dev:all`         | Frontend + API server together             |
-| `pnpm typecheck`       | Type-check all sources without emitting    |
-| `pnpm lint`            | Check for lint errors                      |
-| `pnpm build`           | Production build                           |
-| `pnpm test`            | Run all tests (unit + storybook)           |
-| `pnpm test:unit`       | Unit tests only                            |
-| `pnpm test:storybook`  | Storybook component tests only             |
-| `pnpm test:coverage`   | Tests with coverage report                 |
-| `pnpm test:e2e`        | E2E tests (headless)                       |
-| `pnpm test:e2e:ui`     | E2E in interactive web UI mode             |
-| `pnpm test:e2e:headed` | E2E with visible browser                   |
-| `pnpm test:e2e:debug`  | E2E in debug mode                          |
-| `pnpm test:e2e:report` | Open the HTML report from the last E2E run |
-| `pnpm storybook`       | Storybook on port `6006`                   |
+| Command                | Description                                                         |
+| ---------------------- | ------------------------------------------------------------------- |
+| `pnpm dev`             | Dev server with HMR on port `5173`                                  |
+| `pnpm dev:server`      | Local API server only on port `3001`                                |
+| `pnpm dev:all`         | Frontend + API server together                                      |
+| `pnpm typecheck`       | Type-check all sources without emitting                             |
+| `pnpm lint`            | Check for lint errors                                               |
+| `pnpm madge:circular`  | Check for circular module dependencies                              |
+| `pnpm madge:graph`     | Generate dependency graph image (`graph.png`) — requires `graphviz` |
+| `pnpm build`           | Production build                                                    |
+| `pnpm test`            | Run all tests (unit + storybook)                                    |
+| `pnpm test:unit`       | Unit tests only                                                     |
+| `pnpm test:storybook`  | Storybook component tests only                                      |
+| `pnpm test:coverage`   | Tests with coverage report                                          |
+| `pnpm test:e2e`        | E2E tests (headless)                                                |
+| `pnpm test:e2e:ui`     | E2E in interactive web UI mode                                      |
+| `pnpm test:e2e:headed` | E2E with visible browser                                            |
+| `pnpm test:e2e:debug`  | E2E in debug mode                                                   |
+| `pnpm test:e2e:report` | Open the HTML report from the last E2E run                          |
+| `pnpm storybook`       | Storybook on port `6006`                                            |
 
 ## Testing strategy
 

package.json

@@ -23,6 +23,8 @@
     "preview": "vite preview",
     "typecheck": "tsc --noEmit",
     "lint": "eslint . --ignore-pattern '*.d.ts' --report-unused-disable-directives --max-warnings 0",
+    "madge:circular": "madge --circular --extensions ts,tsx --ts-config tsconfig.json src/main.tsx",
+    "madge:graph": "madge --image graph.png --extensions ts,tsx --ts-config tsconfig.json src/main.tsx",
     "prepare": "husky install",
     "storybook": "storybook dev -p 6006",
     "dev:server": "pnpm --filter server dev",
@@ -89,6 +91,7 @@
     "eslint-plugin-vitest": "0.5.4",
     "husky": "8.0.3",
     "jsdom": "21.1.2",
+    "madge": "8.0.0",
     "msw": "2.12.7",
     "msw-storybook-addon": "2.0.7",
     "playwright": "1.57.0",