How 1weiho/next-lens works
Project Type and Purpose
• This is a Node.js/TypeScript-based CLI tool (“next-lens”) that scans Next.js App Router projects to report page and API routes plus framework/package info.
• It follows a modular “command” architecture (see src/commands/*.ts) and uses TSup for bundling, Vitest for testing, and GitHub Actions for CI.
File Structure
• Top‐level files:
– src/index.ts: CLI entry point and command dispatcher.
– src/commands/: Individual command modules (about.ts, api-list.ts, page-list.ts, info.ts).
• Config/build/test:
– tsup.config.ts (bundler), vitest.config.ts (test runner), GitHub workflows for CI (.github/workflows/ci.yml).
• Tests and fixtures: isolated unit tests and mock Next apps under tests/.
Extract Key Architectural Insights from README
• Core workflow: user runs next-lens <command> [target] → CLI dispatcher loads the proper command →
– Commands perform a recursive directory walk (skipping build folders).
– For page routes: scan app/**/page.*, check co-located/inherited loading & error files.
– For API routes: parse route.* files’ AST to detect exported handler methods.
– For info: read package.json + lockfile to detect versions and package manager.
Main Components & Relationships
a. CLI Entry & Dispatcher
• Component: CLI Runner (src/index.ts)
• Role: parse arguments, instantiate the corresponding Command class, invoke its execute() method.
b. Command Modules
• Components: AboutCommand, ApiListCommand, PageListCommand, InfoCommand
• Role: define high-level workflows and coordinate scanning, parsing, and rendering.
c. File System Walker
• Component: RouteDiscovery
• Role: traverse the project directory, filter files by naming conventions (page, route).
d. AST Parser & Route Mapper
• Component: HandlerParser (using TypeScript Compiler API)
• Role: parse .ts/.tsx route files to extract HTTP methods.
e. Page Boundary Analyzer
• Component: BoundaryScanner
• Role: detect loading / error co-located or inherited files.
f. Package/Framework Inspector
• Component: InfoFetcher
• Role: read package.json, lockfiles, and installed modules to report versions & PM.
g. Renderer
• Component: ConsoleRenderer
h. External Services & Dependencies
• File system (fs) module
• TypeScript Compiler API
• PNPM/NPM for package metadata
Architectural Patterns & Principles
• Command Pattern: each CLI action is encapsulated in its own module with a common interface (execute()).
• Single Responsibility: scanning, parsing, and rendering are separated to simplify testing and extension.
• Test fixtures isolate real-world examples (mock Next apps) for deterministic testing of discovery logic.