next-route-graph 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.2.0] - 2026-11-10
+
+### Added
+- Offline SVG route maps with intermediate URL segments and source information; available through `--svg`, `--format svg`, and the SDK.
+- A focused HTML explorer with route selection, layout chains, search, endpoint filters, health diagnostics, and downloadable exports.
+- `--output <file>` for every format, including creation of parent directories.
+- `inspectProject()` and immutable `filterRoutes()` SDK helpers, plus a shared `buildRouteGraph()` model for visual exporters.
+- Offline browser regression tests and Windows/Linux CI checks.
+
+### Fixed
+- Interception markers now resolve target URL segments while ignoring route groups and parallel slots.
+- Valid parallel and intercepted views no longer trigger duplicate URL diagnostics. API-only projects do not require UI layouts.
+- Dynamic parameter conflicts are detected even when descendant endpoints differ; static paths remain case-sensitive.
+- File read failures abort with `ERR_FILE_READ` instead of silently producing incomplete metadata.
+- Named HTTP exports use the exported alias and ignore type-only entries.
+- HTML uses escaped markup and text nodes for source data, a restrictive content policy, and spreadsheet-safe CSV cells.
+- Preview binds to `127.0.0.1`, validates ports, handles occupied ports, and serves only the report.
+- Format conflicts and unknown formats fail explicitly. Reports remain available when strict validation fails; status messages use stderr.
+- Mermaid and DOT now share the URL hierarchy, including segments without endpoints; DOT line breaks render correctly.
+- Tests rebuild production artifacts first, preventing stale CLI and SDK tests.
+
+### Changed
+- Indexed layout lookup replaces repeated scans of every discovered file per endpoint.
+- Search updates every endpoint summary count while keeping convention totals and diagnostics project-wide.
+- CLI version is read from package metadata; npm packages include the linked guides, changelog, and report screenshot.
+
+## [1.1.0] - 2026-11-07
+
+### Added
+- **Route Linter & Collision Detection Engine**: Built-in validation rules detecting dynamic segment collisions (`/users/[id]` vs `/users/[slug]`), duplicate URL path conflicts across route groups (`no-duplicate-paths`), conflicting `page.tsx` and `route.ts` handlers, missing root layouts, and unhandled parallel route slots (`@slot`).
+- **Strategy Pattern Renderers**:
+  - `MermaidRenderer` (`--mermaid` or `--format mermaid`): Generates Mermaid flowchart diagrams with entity-encoded node shapes.
+  - `DotRenderer` (`--dot` or `--format dot`): Generates Graphviz DOT graphs with properly escaped string literals.
+  - `MarkdownRenderer` (`--markdown` or `--format markdown`): Generates GitHub-flavored Markdown tables.
+  - `HtmlRenderer` (`--html`, `--serve`, or `--format html`): Generates a standalone, zero-dependency interactive visual HTML report with route hierarchy cards, searchable data table, CSV export, integrated tabbed format explorer (Mermaid, DOT, Markdown, ANSI Terminal, JSON, Flat), and built-in local preview server.
+- **Deep HTTP Method & Metadata Inspection**: Automatically detects exported HTTP handlers (`GET`, `POST`, `PUT`, `DELETE`, etc.) in `route.ts`, React Server Actions (`"use server"`), and route segment configurations (`runtime`, `dynamic`).
+- **Programmatic TypeScript SDK**: Exported root module `dist/index.js` with TypeScript type declarations (`dist/index.d.ts`) and `"exports"` map, enabling library usage via `import { analyzeRoutes } from 'next-route-graph'`.
+- **Domain Error Hierarchy**: Structured error classes (`ProjectNotFoundError`, `AmbiguousRouterError`, `NoAppRouterError`, `RouteLintError`) with machine-readable codes and actionable hints.
+- **New CLI Commands & Flags**:
+  - `next-route-graph check`: Run route linting checks with exit codes.
+  - `--strict`: Fails with non-zero exit code if route issues or collisions are detected.
+  - `--format <tree|flat|json|mermaid|dot|markdown|html>`: Flexible format selector.
+  - `--html [file]`: Export self-contained interactive HTML report (defaults to `route-graph.html`).
+  - `--serve [port]`: Spin up zero-dependency local HTTP preview server (defaults to port 3000) and open in default browser.
+- **Comprehensive Automated Test Suite**: Expanded test coverage from 9 to 50 unit and integration tests, including end-to-end Next.js project fixtures, CLI subprocess tests, scanner edge cases, linter edge cases, external SDK consumer verification, and HTML report validation.
+- **Documentation & Governance Suite**: Added `docs/ARCHITECTURE.md`, `docs/adr/0001-hybrid-parsing-and-strategy-renderers.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md`.
+
+### Fixed
+- **Private Folders**: Ignored Next.js private folders (`_folder`, e.g. `_components`, `_lib`) and hidden directories during route discovery so internal components are not treated as public routes.
+- **Multiple Root Layouts**: Added support for Multiple Root Layouts partitioned within top-level route groups (e.g. `app/(marketing)/layout.tsx` and `app/(shop)/layout.tsx`), eliminating false-positive `require-root-layout` errors.
+- **Intercepting Routes**: Fixed regex in `parseRoutePath` and `extractRouteMetadata` to match multi-level intercepting tokens `(..)(..)` before single-level `(..)`.
+- **Directive Truncation**: Replaced 500-character slice heuristic with a prologue parser (`getPrologueDirectives`), fixing missed `"use client"` / `"use server"` directives in files with long license headers.
+- **Comment-Stripped Extraction**: Stripped comments before extracting HTTP methods, Server Actions, and route configs to prevent commented-out code (e.g. `// export function GET()`) from being reported.
+- **Renderer Escaping**:
+  - Escaped backslashes before double quotes in Graphviz DOT output.
+  - Entity-encoded square brackets (`#91;`, `#93;`) in Mermaid labels to prevent broken node shape syntax.
+  - Escaped pipe characters (`\|`) in Markdown table cells.
+
+### Performance
+- **Reduced Disk I/O**: Reduced filesystem reads by 66% in `analyzer.ts` by reading each file once into memory and caching parsed metadata.
+- **Deterministic Route Ordering**: Implemented composite multi-level sorting (`path`, then `file`) guaranteeing consistent output across operating systems.
+
+### Changed
+- Refactored `analyzer.ts` into a decoupled pipeline supporting layout hierarchy tracking and slot resolution.
+- Enriched `AnalysisResult` and `SummaryStats` with API route, parallel route, and interceptor counts.
+- Enabled direct path execution in `detectAppRouter` when targeting `app/` or `src/app/` directly.
+- Decoded Next.js `%5F` prefix syntax to underscores in URL routes (e.g. `%5Fprivate` ➔ `/_private`).
+- Aligned route tree columns dynamically based on the longest route path in the project.
+- Fixed nested markdown code blocks in `README.md`.
+
+---
+
+## [1.0.2] - 2026-09-13
+
+### Changed
+- Improved rendering performance and CLI tree layout formatting.
+
+---
+
+## [1.0.0] - 2026-09-05
+
+### Added
+- Initial release of `next-route-graph`.
+- Support for static, dynamic, catch-all, and optional catch-all route detection.
+- App Router directory auto-discovery (`app` and `src/app`).
+- Basic tree, flat, and JSON output formats.

package/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to next-route-graph
+
+Thank you for your interest in contributing! We welcome bug reports, documentation improvements, new renderers, and feature contributions.
+
+---
+
+## Development Setup
+
+1. **Prerequisites**:
+   * Node.js >= 18.0.0
+   * npm >= 9.0.0
+   * Node.js >= 20 for the optional browser tests
+
+2. **Clone and Install**:
+   ```bash
+   git clone https://github.com/Nima-sltn/next-route-graph.git
+   cd next-route-graph
+   npm install
+   ```
+
+3. **Running the Development CLI**:
+   ```bash
+   npm run dev -- [path-to-nextjs-app]
+   ```
+
+---
+
+## Quality Checks & Testing
+
+Before submitting a Pull Request, ensure all tests, type checks, and builds pass:
+
+```bash
+# Run unit tests
+npm test
+
+# Run TypeScript type check
+npm run typecheck
+
+# Build the project
+npm run build
+
+# Exercise the offline HTML report in Chromium
+npx playwright install chromium
+npm run test:browser
+
+# Run the complete pre-publish verification suite
+npm run prepublishOnly
+```
+
+---
+
+## Project Structure
+
+* `src/cli.ts` - Command line interface definition and options.
+* `src/index.ts` - Programmatic public SDK entry point.
+* `src/core/detector.ts` - App Router root directory detection.
+* `src/core/scanner.ts` - File discovery and directory traversal.
+* `src/core/parser.ts` - Directive detection, HTTP method parsing, and URL resolution.
+* `src/core/linter.ts` - Route collision and framework best practice validation.
+* `src/core/analyzer.ts` - Core analysis orchestrator and indexed layout lookup.
+* `src/core/inspect.ts` - Shared CLI/SDK scan entry point and immutable filtering.
+* `src/render/` - Text, SVG, and offline HTML renderers with a shared URL graph.
+* `src/preview.ts` - Loopback-only static report serving.
+* `src/errors/` - Domain error classes and actionable hints.
+* `tests/` - Node.js built-in unit/integration tests and Playwright browser checks.
+
+---
+
+## Pull Request Guidelines
+
+1. Create a descriptive branch name (e.g. `feature/openapi-export` or `fix/parallel-routes`).
+2. Add unit tests for any new functionality in `tests/`.
+3. Follow existing code conventions and maintain explicit TypeScript types.
+4. Update `README.md` and `CHANGELOG.md` when introducing user-facing changes.

package/README.md

@@ -1,134 +1,169 @@
-````md
-# next-route-graph
-
-> Visualize and inspect your Next.js App Router structure from the terminal.
-
-`next-route-graph` is a lightweight, zero-config CLI that scans your `app/` or `src/app/` directory and turns your routing structure into a clear overview.
-
-Useful for quickly understanding unfamiliar projects, documenting routes in a GitHub README, onboarding developers, or giving AI coding tools a structured view of your project's routing architecture.
-
-No configuration. No network requests. No Next.js runtime.
-
-## Features
-
-- Detects static, dynamic, catch-all, and optional catch-all routes
-- Supports Route Groups, Parallel Routes, and Intercepting Routes
-- Detects Server/Client rendering
-- Detects layouts, route handlers, and special App Router files
-- Tree, flat, and JSON output
-- Route search and filtering
-- Lightweight and fast
-
-## Installation
-
-```bash
-npx next-route-graph
-```
-````
-
-Or install globally:
-
-```bash
-npm install -g next-route-graph
-```
-
-## Usage
-
-Run from your Next.js project:
-
-```bash
-npx next-route-graph
-```
-
-Analyze another project:
-
-```bash
-npx next-route-graph ./my-next-app
-```
-
-Example output:
-
-```text
-Project     my-next-app
-Router      App Router
-Root        src/app
-
-Routes
-────────────────────────────────────────
-├── /[locale]                    page.tsx  [dynamic]
-├── /[locale]/about              page.tsx  [dynamic]
-├── /[locale]/blog               page.tsx  [dynamic]
-├── /[locale]/blog/[slug]        page.tsx  [dynamic]
-└── /api                         route.ts
-
-Summary
-────────────────────────────────────────
-Routes       5
-Dynamic      4
-Client       0
-Server       5
-Layouts      1
-```
-
-## CLI
-
-```text
-next-route-graph
-next-route-graph <projectPath>
-next-route-graph --flat
-next-route-graph --json
-next-route-graph --search <query>
-next-route-graph --help
-next-route-graph --version
-```
-
-### `--flat`
-
-Show only route paths:
-
-```bash
-npx next-route-graph --flat
-```
-
-### `--json`
-
-Output structured JSON for scripts, automation, AI tools, or CI:
-
-```bash
-npx next-route-graph --json
-```
-
-### `--search`
-
-Filter routes:
-
-```bash
-npx next-route-graph --search blog
-```
-
-Options can be combined:
-
-```bash
-npx next-route-graph --search blog --json
-```
-
-## Development
-
-```bash
-git clone https://github.com/Nima-sltn/next-route-graph.git
-cd next-route-graph
-npm install
-npm test
-npm run typecheck
-npm run build
-```
-
-## License
-
-MIT © 2026 Nima Soltanian
-
-[GitHub](https://github.com/Nima-sltn/next-route-graph) · [npm](https://www.npmjs.com/package/next-route-graph)
-
-```
-
-```
+# next-route-graph
+
+[![npm version](https://img.shields.io/npm/v/next-route-graph.svg)](https://www.npmjs.com/package/next-route-graph)
+[![CI](https://github.com/Nima-sltn/next-route-graph/actions/workflows/ci.yml/badge.svg)](https://github.com/Nima-sltn/next-route-graph/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Inspect, lint, and visualize a Next.js App Router project without starting Next.js or executing its code. Use the terminal for quick inspection, an offline HTML report for exploration, and SVG for a diagram you can share anywhere.
+
+```sh
+npx next-route-graph ./my-app
+npx next-route-graph ./my-app --html reports/routes.html
+npx next-route-graph ./my-app --svg --output reports/routes.svg
+```
+
+Version **1.2.0** adds rendered SVG exports, an offline HTML explorer, and shared CLI/SDK scanning. See the [changelog](CHANGELOG.md) for details.
+
+![Offline route map with parallel endpoint details](docs/route-report.png)
+
+## What it tells you
+
+- Public URL paths, dynamic segments, route groups, parallel slots, and intercepted targets.
+- Page and API handler source files, declared HTTP methods, client directives, Server Actions, and literal segment configuration.
+- Layout chains from the outermost layout to each endpoint.
+- Route collisions, missing page layouts, page/handler conflicts, slot fallback warnings, and misplaced global error files.
+
+Private folders and build/dependency directories are excluded. Routes are sorted for consistent output. All exports work without a Next.js server.
+
+## Install
+
+Requires Node.js 18 or newer. Run with `npx`, or install in your project:
+
+```sh
+npm install -D next-route-graph
+```
+
+## Explore visually
+
+```sh
+# Standalone report; opens directly from disk and works offline
+npx next-route-graph ./my-app --html reports/routes.html
+
+# Local static snapshot; visit the printed URL (default port 3000)
+npx next-route-graph ./my-app --serve
+
+# Choose a port, or 0 to choose an available port
+npx next-route-graph ./my-app --serve 4300
+```
+
+The report has four sections:
+
+| Section | Purpose |
+| --- | --- |
+| Route map | Rendered SVG hierarchy, including segments without endpoints. Select a node with a mouse or keyboard to inspect every source and its layout chain. |
+| Routes | Search paths, source files, methods, or layouts; filter pages, handlers, rendering declarations, dynamic routes, slots, or interceptions. Download matching rows as CSV. |
+| Health | Project-wide diagnostics with rule names, locations, and actionable hints. |
+| Exports | Download SVG, Mermaid, DOT, Markdown, JSON, flat paths, or a plain terminal tree. One selector keeps the interface compact. |
+
+Multiple sources at one URL remain inspectable. Map filtering dims unrelated branches and retains ancestors for context. Report downloads contain all endpoints included in the report; CSV uses the current browser filter.
+
+SVG is a real vector image. Mermaid and Graphviz DOT are source formats for their respective renderers; they do not need to render in your terminal. The HTML map renders directly without a CDN or a graph library. The preview server binds only to `127.0.0.1` and serves the in-memory report. Rerun the command to refresh its snapshot.
+
+## Export and automate
+
+Choose one format flag, or use `--format`. `--output` works for every format and creates missing parent directories. File-write notices go to stderr; stdout remains suitable for pipes.
+
+| Format | Flag | Use |
+| --- | --- | --- |
+| Terminal tree | Default / `--format tree` | Quick overview and lint summary |
+| Flat paths | `--flat` | Shell pipelines |
+| JSON | `--json` | SDK consumers, build tools, or AI context |
+| SVG | `--svg` | Rendered image for reports and design tools |
+| HTML | `--html [file]` / `--format html` | Offline interactive report |
+| Mermaid | `--mermaid` | Fenced diagram for Markdown documentation |
+| Graphviz DOT | `--dot` | Graphviz processing |
+| Markdown | `--markdown` | Documentation table |
+
+```sh
+npx next-route-graph ./my-app --json --output reports/routes.json
+npx next-route-graph ./my-app --mermaid --output reports/routes.md
+npx next-route-graph ./my-app --dot --output reports/routes.dot
+dot -Tsvg reports/routes.dot -o reports/graphviz.svg
+
+# Stream HTML instead of writing a report file
+npx next-route-graph ./my-app --format html > routes.html
+
+# Case-insensitive filtering by path, file, or HTTP method
+npx next-route-graph ./my-app --search POST --json
+```
+
+`--search` changes endpoint counts in the report; layout/loading/error-file totals and diagnostics still describe the whole project. A filtered export cannot hide a CI failure. Use `--output -` to explicitly write to stdout. `--html` defaults to `route-graph.html`.
+
+## Validate in CI
+
+```sh
+npx next-route-graph check ./my-app
+npx next-route-graph check ./my-app --strict --json
+
+# Save a reviewable artifact even if validation fails
+npx next-route-graph ./my-app --strict --format html --output reports/routes.html
+```
+
+| Command | Exit 1 when |
+| --- | --- |
+| Default scan | Scanning or output fails |
+| `check` / `--check` | Scanning fails or lint errors exist |
+| `--strict` | Scanning fails or lint errors or warnings exist |
+
+JSON scan errors are written as `{ "error": "…", "code": "…" }` to stderr. Successful report data is written to stdout or the requested file. Invalid options also fail. A strict file export is written before lint determines the exit code.
+
+Example GitHub Actions step after installing your project's dependencies:
+
+```yaml
+- name: Check routing and generate a report
+  run: npx next-route-graph . --strict --format html --output reports/routes.html
+- name: Save report
+  if: always()
+  uses: actions/upload-artifact@v4
+  with:
+    name: route-report
+    path: reports/routes.html
+```
+
+## TypeScript SDK
+
+```ts
+import { inspectProject, filterRoutes, getRenderer } from "next-route-graph";
+import { writeFile } from "node:fs/promises";
+
+const result = await inspectProject("./my-app");
+await writeFile("routes.html", getRenderer("html").render(result));
+await writeFile("routes.svg", getRenderer("svg").render(result));
+
+const api = filterRoutes(result, "api/"); // returns a new result
+console.log(api.summary.apiRoutes);
+if (result.lint?.hasErrors) process.exitCode = 1;
+```
+
+The lower-level `detectAppRouter()`, `scanAppDir()`, `analyzeRoutes()`, and `lintRoutes()` APIs remain available. `buildRouteGraph(result.routes)` exposes URL nodes with stable IDs within an export, parent IDs, depth, and all endpoint sources attached to each node. `getRenderer()` rejects unknown formats. See [architecture](docs/ARCHITECTURE.md) for module boundaries.
+
+## Scope and limitations
+
+This is static **App Router** source inspection, not a replacement for `next build`. Pages Router, metadata-generated endpoints, custom `pageExtensions`, rewrites, redirects, middleware/proxy behavior, and imports are not evaluated. Source extraction uses comment-aware text parsing, not an AST or TypeScript evaluation; computed exports, complex string contents, and re-export chains can be incomplete. Detected HTTP methods are declared methods, not Next.js-generated methods.
+
+“Server” means the file has no top-level `use client` directive. It does not prove static generation, caching, SSR behavior, or imported component boundaries. Runtime and dynamic configuration show local literal declarations, not inherited effective values. The URL graph describes structure; its edges do not imply imports, navigation links, or layout inheritance. Layout inheritance appears separately in the details panel.
+
+Diagnostics intentionally cover a small set of routing conventions. Parallel fallback warnings flag potentially unmatched navigation; the tool does not simulate navigation. Share exported reports with the same care as source filenames and internal endpoint names: they contain those names and detected metadata, but never source file contents.
+
+Framework references: [intercepting routes](https://nextjs.org/docs/app/api-reference/file-conventions/intercepting-routes), [parallel routes](https://nextjs.org/docs/app/api-reference/file-conventions/parallel-routes), and [layouts](https://nextjs.org/docs/app/api-reference/file-conventions/layout).
+
+## Development
+
+```sh
+npm ci
+npm run typecheck
+npm test                 # builds first; unit, CLI, SDK, and HTTP integration tests
+npx playwright install chromium
+npm run test:browser     # builds first; real offline browser workflow
+```
+
+Browser development tests require Node.js 20 or newer. To use installed Chrome in PowerShell: `$env:PLAYWRIGHT_CHROMIUM_CHANNEL='chrome'`. Set `NRG_REPORT_ARTIFACT_DIR=reports` to save the example HTML and desktop/mobile screenshots during browser tests.
+
+- [Contributing](CONTRIBUTING.md)
+- [Architecture and trade-offs](docs/ARCHITECTURE.md)
+- [Architecture decision](docs/adr/0001-offline-reports-and-shared-route-graph.md)
+- [Improvement evidence](docs/NEW_FEATURES.md)
+- [Changelog](CHANGELOG.md)
+- [Security](SECURITY.md)
+
+[MIT](LICENSE) © 2026 Nima Soltanian

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.2.x   | :white_check_mark: |
+| 1.1.x   | :white_check_mark: |
+| 1.0.x   | :x:                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in `next-route-graph`, please report it responsibly:
+
+1. **Do not open a public GitHub issue.**
+2. Send an email to the repository maintainer or open a private security advisory through GitHub.
+3. Include detailed steps to reproduce the issue along with a minimal reproduction project if possible.
+
+You will receive an acknowledgment within 48 hours, followed by updates on the timeline for a patch.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}