t1k:web:frontend:script-graph
| Field | Value |
|---|---|
| Module | frontend |
| Version | 1.24.11 |
| Effort | medium |
| Tools | — |
Keywords: app-router, class-diagram, dep-cruiser, module-graph, nextjs, pages-router, react-router, route-graph, ts-morph, web
How to invoke
Section titled “How to invoke”/t1k:web:frontend:script-graphweb-script-graph
Section titled “web-script-graph”Web diagram adapter for the T1K diagram toolchain. Produces three diagram types from a React/TypeScript web project:
- modules — Import-level module dependency graph via
dependency-cruiser - classes — Class/interface extraction via
ts-morph(honest skip notice emitted for functional-only projects) - routes — Next.js route tree (App Router or Pages Router) — falls back to React Router static detection
Executed by
Section titled “Executed by”Interpreting a diagram and acting on it stay on a reasoning tier (routing SSOT:
rules/orchestration-rules.md § “Task-Type → Agent Routing”). Only the deterministic generators are
mechanical:
| Step | Agent |
|---|---|
Run scripts/detect.cjs, list-capabilities.cjs or requirements.cjs and report the result | t1k-fact-fetcher — runs a bundled script and returns its output |
Run scripts/generate.cjs --type modules|classes|routes --out-dir <dir> and list the files written | t1k-metrics-reporter — runs the generator and tabulates the outputs |
Stays reasoning-tier: deciding which diagram answers the question and reading it for architecture conclusions.
Prerequisites
Section titled “Prerequisites”Install the full Web toolchain:
t1k diagram install --preset webThis installs mermaid-cli globally and records dependency-cruiser + ts-morph as per-project installs. To enable per-project capabilities:
bun install --dev dependency-cruiser ts-morphThe routes capability works without either per-project tool (it uses a pure file-system walker + regex parser).
Priority & Polyglot Detection
Section titled “Priority & Polyglot Detection”This adapter declares priority: 80. In polyglot repos where the RN adapter (priority: 100) also detects, RN wins the tiebreak. Users may override with --engine web.
This adapter’s detect.cjs treats a package.json that depends on react-native (core) as an RN-first project and exits non-zero. react-native-web alone (without react-native) is accepted as a web-first signal.
# Auto-detect and generate all diagramst1k diagram refresh
# Generate specific typebun scripts/generate.cjs --type modules --out-dir /tmp/outbun scripts/generate.cjs --type classes --out-dir /tmp/outbun scripts/generate.cjs --type routes --out-dir /tmp/out
# Check if this adapter applies to current projectbun scripts/detect.cjs # exit 0 = match
# List available capabilitiesbun scripts/list-capabilities.cjs
# Show tool requirementsbun scripts/requirements.cjsOutput Files
Section titled “Output Files”| Capability | Output |
|---|---|
modules | modules.md — Mermaid graph LR of module-to-module imports |
classes | classes.md — class diagram, or honest “not applicable” notice |
routes | routes.md — Mermaid flowchart TD of route tree |
Route Detection
Section titled “Route Detection”routes tries in order:
- Next.js App Router — if
app/orsrc/app/containspage.tsx|jsx|ts|jsorlayout.tsx, walk the directory tree and emit a route hierarchy. Route groups(groupName)are collapsed, dynamic segments[slug]preserved as:slug, catch-all[...rest]as*rest. - Next.js Pages Router — if
pages/orsrc/pages/exists with.tsx/.jsx/.ts/.jsfiles, each file is a route.index.tsx→/,about.tsx→/about,[id].tsx→/:id. - React Router fallback — regex-scan source for
<Route path="..."JSX orpath: "..."object routes (static only, documented limitations).
If none match, routes.md contains the honest notice: No static routes detected — project uses dynamic routing or no router is installed.
Class Diagrams — Honest Notice
Section titled “Class Diagrams — Honest Notice”Modern React and most new TypeScript web apps are functional-component-based. When ts-morph finds fewer than 3 class declarations in the project, classes.md contains:
Class diagrams have limited value for this project — fewer than 3 class declarations found. Modern React uses functional components with hooks. See
modules.mdandroutes.mdfor more relevant views.
This follows the rules/development-principles.md → “Errors Over Silent Fallbacks” policy — we don’t invent a fake diagram.
Known Limitations
Section titled “Known Limitations”- React Router dynamic routes (routes composed at runtime from config objects pulled in from a DB) cannot be statically analyzed — the regex parser handles only inline JSX
<Route>and top-levelpath:literals. - dep-cruiser per-project install required for the
modulescapability. If not installed,modules.mdcontains a skip notice with thebun install --dev dependency-cruiserhint. - Monorepo workspaces (Nx / Turborepo) are not auto-detected in v1.0.0 — operate in single-package mode. Planned for v1.1.0.
References
Section titled “References”| File | Content |
|---|---|
| references/depcruise-setup.md | dep-cruiser invocation, per-project config, fallback behavior |
| references/ts-morph-class-extraction.md | ts-morph AST traversal, class + interface extraction, functional-component notice |
| references/nextjs-route-graph.md | App Router vs Pages Router detection, dynamic/catch-all segment rendering |
| references/react-router-fallback.md | Static regex parser design + limitations |