next-route-graph 1.0.2 → 1.2.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,71 @@
+# Architecture
+
+`next-route-graph` scans App Router source files without importing the target project's code. The CLI and SDK share the same analysis pipeline. Renderers consume plain analysis data and return strings; file writes, HTTP serving, and exit policy belong outside that pipeline.
+
+```mermaid
+flowchart TD
+  CLI[CLI: options, output, exit policy] --> Inspect[inspectProject]
+  SDK[TypeScript SDK] --> Inspect
+  Inspect --> Detect[Detect App Router root]
+  Detect --> Scan[Discover source files]
+  Scan --> Analyze[Analyze convention files]
+  Analyze --> Parse[Comment-aware text parser]
+  Analyze --> Lint[Route diagnostics]
+  Analyze --> Result[AnalysisResult]
+  Result --> Filter[Optional immutable endpoint filter]
+  Filter --> Render[OutputRenderer]
+  Render --> Text[Tree / Flat / JSON / Markdown]
+  Render --> Graph[Shared URL graph]
+  Graph --> Visual[SVG / Mermaid / DOT / HTML]
+  Render --> CLI
+  CLI --> Files[File or stdout]
+  CLI --> Preview[Loopback HTTP preview]
+```
+
+## Boundaries
+
+| Module | Responsibility |
+| --- | --- |
+| `core/detector.ts` | Select `app/`, `src/app/`, or a direct App Router directory; report missing or ambiguous roots. |
+| `core/scanner.ts` | Walk supported source files. Skip private, hidden, dependency, and build directories; do not traverse symlinks. |
+| `core/parser.ts` | Recognize convention files, directives, declared methods, and literal config. Resolve URL paths, including interception relative to URL segments. It is a text parser, not an AST. |
+| `core/analyzer.ts` | Read each convention file once, construct endpoint entries, index layout files, attach outer-to-inner layout chains, compute counts, and run lint. |
+| `core/inspect.ts` | Compose detection → scan → analysis for the CLI and SDK; provide immutable filtering and full scan timing. |
+| `core/linter.ts` | Return diagnostics, never choose process exit codes. Partition collision checks by parallel branch and exclude intercepted variants from ordinary URL collision checks. |
+| `render/graph.ts` | Build a URL trie including non-endpoint segments; retain every source at shared URLs. Provide shared markup escaping for HTML/XML. |
+| `render/*` | Convert `AnalysisResult` into text, SVG, or HTML. No filesystem writes, network calls, or process exits. |
+| `preview.ts` | Serve only an in-memory HTML report on `127.0.0.1`, with GET/HEAD, no filesystem access, and explicit listen errors. |
+| `cli.ts` | Validate output selection and port; choose format, destination, and CI policy; report errors to stderr. |
+
+## Data contracts
+
+`DiscoveredFile` has an absolute path for reads and a normalized App Router-relative path for output. `RouteEntry` represents an endpoint source, not a unique URL: parallel views and intercepted variants can share a public path. `RouteFile` describes convention files in the endpoint's filesystem directory. `layoutChain` records the layouts found in ancestor directories.
+
+`AnalysisResult` contains project identity, endpoint entries, summary counts, scan duration, and lint results. JSON exports preserve that shape. `filterRoutes()` returns a new result, recalculates endpoint-related counts, and retains project-wide convention totals and diagnostics. Strict validation always uses the full scan.
+
+`RouteGraphNode` represents a URL segment. Its `routes` array retains every endpoint source at that path; an empty array means a grouping segment. Nodes have unique export-local IDs, a parent ID, depth, and normalized path. SVG, Mermaid, and DOT use this same model. These edges represent URL ancestry, not layout or import relationships.
+
+## Complexity and failure handling
+
+Scanning and source extraction scale with discovered files and bytes read. Layout lookup uses a directory index and walks only each endpoint's ancestors, rather than searching every file at every depth. Graph construction creates nodes for URL prefixes and sorts siblings for deterministic traversal. Source reads remain sequential to bound open files and memory; no concurrency framework or cache is needed for a one-shot local scan.
+
+Detection, directory reads, and convention-file reads raise typed errors with codes and hints. Read failures abort analysis: silently substituting an empty source would turn missing metadata into misleading findings. Renderers do not catch these errors or mutate process state. Unknown renderer formats throw rather than silently producing a terminal tree.
+
+CLI reports are written before strict lint exit policy runs, so failing CI jobs can retain artifacts. Preview validates strict policy before starting, so a failed check never leaves a server alive. Operational notices use stderr; successful exports go to stdout or a file.
+
+## Offline report and security
+
+The report contains a pre-rendered SVG, route table, health diagnostics, and encoded JSON for interaction. HTML/XML text and attributes are escaped; `<` is Unicode-escaped in embedded JSON to prevent script termination. Browser interactions create text nodes instead of interpolating source data into HTML. A content security policy blocks network dependencies. Browser script and styles are inline so reports work from disk.
+
+CSV cells are quoted and formula-leading values receive a leading apostrophe. Downloads use local Blob URLs. Clipboard failure opens the selectable source instead. The preview serves a static snapshot with no cache, no directory listing, and no arbitrary file routes.
+
+The report exposes filenames, endpoint names, and detected metadata, not file bodies. Its purpose is architecture inspection, not vulnerability detection or runtime verification.
+
+## Verification
+
+- Node's test runner covers parsing, scanning, linting, renderers, source escaping, immutable filtering, the built SDK, CLI file exports, strict policy, and HTTP preview behavior.
+- `npm test` builds production artifacts first, so CLI and consumer tests cannot accidentally validate an old `dist/`.
+- Playwright is development-only. Browser tests open local HTML offline and exercise keyboard selection, duplicate endpoint details, search, filters, all downloads, SVG XML validity, hostile source data, formula-safe CSV, and mobile overflow.
+- CI tests the CLI on Windows and Linux and runs browser checks on Linux. No Next.js runtime is required.
+
+See [ADR 0001](adr/0001-offline-reports-and-shared-route-graph.md) for the rendering trade-off and [README limitations](../README.md#scope-and-limitations) for the analysis boundary.

package/docs/NEW_FEATURES.md

@@ -0,0 +1,16 @@
+# Improvement evidence
+
+The purpose of this work is a more useful route inspector, not a larger feature count. GitRoll scores must be measured by GitRoll after a rescan; this document makes no predicted score claims.
+
+| Area | Concrete improvement | Evidence |
+| --- | --- | --- |
+| Architecture | One scan entry point for CLI and SDK; output and preview stay outside analysis; indexed layout lookup. | `src/core/inspect.ts`, `src/core/analyzer.ts`, workflow and consumer tests. |
+| Interoperability | Rendered SVG, offline HTML, existing documentation/machine formats, and a shared graph exposed to SDK consumers. | `src/render/graph.ts`, `src/render/svg.ts`, export and browser tests. |
+| Useful exploration | Select endpoint sources and layout chains; search/filter routes; inspect project health; download results. | `src/render/html.ts`, `tests/browser/report.test.mjs`. |
+| Correctness | Interception target resolution, valid parallel variants, API-only layouts, case-sensitive paths, dynamic-prefix collisions, explicit read failures. | `tests/report_workflow.test.ts` plus existing parser/linter fixtures. |
+| Safety | Escaped source data, restrictive report CSP, spreadsheet-safe CSV, loopback-only preview. | Hostile-input browser checks, markup checks, HTTP integration tests. |
+| Documentation | Working examples, exit-code contract, explicit static-analysis limitations, architecture boundaries, and an implemented ADR. | README, architecture guide, ADR, CI workflow. |
+
+The SVG URL graph is deliberately simple. It includes missing parent segments and keeps all endpoint sources without adding a graph runtime, CDN, database, plugin framework, watch daemon, or a replacement Next.js compiler. Mermaid/DOT remain useful source exports; HTML renders a native SVG instead of pretending those source blocks are visual previews.
+
+Run `npm run typecheck`, `npm test`, and `npm run test:browser` to reproduce the checks. Browser setup and artifact generation are documented in the [README](../README.md#development).

package/docs/adr/0001-offline-reports-and-shared-route-graph.md

@@ -0,0 +1,29 @@
+# ADR 0001: Offline SVG reports with a shared URL graph
+
+- Status: Accepted
+- Date: 2026-11-10
+
+## Context
+
+The CLI exports Mermaid and DOT source, but users also need a diagram that is already rendered and a report they can inspect without running a graph tool. A list of route cards does not convey nesting. Duplicate public URLs can represent valid parallel or intercepted sources and must remain inspectable.
+
+## Decision
+
+Build one URL hierarchy from `RouteEntry[]`, including URL segments without endpoints. Keep an array of endpoint sources on each node. Use the model for SVG, Mermaid, and DOT; embed SVG directly in the offline HTML report. Provide source/layout details beside the diagram, a filterable route table, full-project health checks, and one export selector.
+
+Keep analysis independent of transport: renderers return strings; the CLI writes files or starts a small loopback HTTP server. Reuse the same `inspectProject()` pipeline in the CLI and SDK. Retain existing low-level APIs.
+
+## Alternatives
+
+- Bundle Mermaid and Graphviz renderers: more JavaScript and maintenance for a graph that can be drawn directly with SVG.
+- Load a CDN: breaks offline reports and introduces network and privacy requirements.
+- Add a graph application/framework: unnecessary for URL ancestry, selection, and basic filtering.
+- Keep only source exports: useful for pipelines, but does not meet the need for a rendered artifact.
+
+## Consequences
+
+No new runtime dependency is required. SVG works in browsers, documents, and design tools, and the HTML remains a portable single file. Missing segments and parallel sources use consistent semantics across visual formats.
+
+The map is a scrollable hierarchy rather than a force-directed canvas; it does not attempt drag layouts, runtime navigation, import analysis, or continuous watching. Large reports grow with endpoint count. The source parser remains heuristic and documented as such; adding a compiler dependency would require demonstrated parsing needs and its own decision.
+
+Playwright is a development-only dependency to verify the actual offline browser behavior and downloads. Unit and integration tests continue using Node's built-in runner.

package/package.json

@@ -1,52 +1,71 @@
-{
-  "name": "next-route-graph",
-  "version": "1.0.2",
-  "description": "Visualize and inspect the structure of a Next.js App Router project from the terminal",
-  "type": "module",
-  "bin": {
-    "next-route-graph": "dist/cli.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "dev": "tsx src/cli.ts",
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "tsx --test tests/**/*.test.ts",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build"
-  },
-  "keywords": [
-    "nextjs",
-    "app-router",
-    "routes",
-    "cli",
-    "visualization",
-    "route-map",
-    "typescript"
-  ],
-  "author": {
-    "name": "Nima Soltanian",
-    "url": "https://github.com/Nima-sltn"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Nima-sltn/next-route-graph.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Nima-sltn/next-route-graph/issues"
-  },
-  "dependencies": {
-    "commander": "^12.1.0",
-    "picocolors": "^1.1.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.19.43",
-    "tsx": "^4.7.0",
-    "typescript": "^5.3.3"
-  }
-}
+{
+  "name": "next-route-graph",
+  "version": "1.2.0",
+  "description": "Inspect, lint, and visualize the structure of a Next.js App Router project from the terminal or SDK",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "next-route-graph": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "pretest": "npm run build",
+    "test": "tsx --test tests/run.mjs",
+    "pretest:browser": "npm run build",
+    "test:browser": "node --test tests/browser/report.test.mjs",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "keywords": [
+    "nextjs",
+    "app-router",
+    "routes",
+    "cli",
+    "visualization",
+    "route-map",
+    "mermaid",
+    "linter",
+    "typescript"
+  ],
+  "author": {
+    "name": "Nima Soltanian",
+    "url": "https://github.com/Nima-sltn"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nima-sltn/next-route-graph.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Nima-sltn/next-route-graph/issues"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "playwright": "^1.62.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
+  }
+}