How pahen/madge works
Project Type and Purpose
• Madge is an open-source command-line and programmatic Node.js tool for analyzing JavaScript (and CSS preprocessor) module dependency trees, detecting circular dependencies, and generating visual graphs (via Graphviz).
• It exposes a CLI entrypoint (bin/cli.js) and a Promise-based API (lib/api.js), orchestrating a pipeline of sub-modules that handle tree extraction, cycle detection, graph construction, and output formatting.
High-Level File Structure Analysis
• Top-Level
– bin/cli.js: CLI bootstrap, argument parsing, invokes the API.
– lib/: core modules implementing the pipeline:
• api.js: facade that wires up the pipeline and returns results (obj, circular, dot, image, svg, etc.).
• tree.js: uses dependency-tree/precinct to traverse the file system and build the raw dependency graph.
• cyclic.js: analyzes the raw graph to find circular dependencies.
• graph.js: transforms the dependency data into a Graphviz-compatible DOT structure.
• output.js: serializes DOT to console text or writes image files (SVG, DOT).
• log.js: centralized logging and warning management.
– test/: comprehensive suite covering AMD, CommonJS, ES6, TypeScript, Vue, JSX, CSS preprocessors, circular cases, error scenarios.
• Configuration & Metadata
– package.json, .eslintrc, .editorconfig, .nvmrc, GitHub workflows, .release-it.json.
README-Driven Insights
• Core external dependencies:
• dependency-tree (via precinct/detective) for file parsing and AST-based dependency resolution.
• Graphviz (optional) to render DOT graphs to images.
• Supported module formats: AMD, CJS, ES6, TypeScript, JSX, Vue, CSS preprocessors.
• API methods: .obj(), .circular(), .dot(), .image(), .svg(), etc., each returning Promises.
• Configurable via CLI flags or .madgerc/package.json madge section.
a. Main Components
1. CLI Layer
• Entry (bin/cli.js) → parses CLI args + config → calls API.
2. API Facade (lib/api.js)
• Validates inputs/config → orchestrates pipeline → exposes Promise interface.
3. Dependency Tree Generator (lib/tree.js)
• File system walker → AST parsing → builds raw module graph.
4. Cycle Detector (lib/cyclic.js)
• Graph traversal → identifies strongly connected components.
5. Graph Builder (lib/graph.js)
6. Output Manager (lib/output.js)
• Renders DOT text, writes SVG/PNG via Graphviz CLI or Graphviz JS.
7. Logging/Warnings (lib/log.js)
• Captures debug/info/warning messages.
8. External Services
• File System (fs) for module reads.
• Graphviz for image rendering.
• Optional Webpack/RequireJS/TypeScript configs for resolving aliases.
b. Relationships & Data Flow
– Config flows top-down from CLI/API to each module (tree, graph, output).
– Logging cross-cuts all modules.
c. Architectural Patterns & Principles
– Pipeline pattern: sequential processing stages.
– Modular separation of concerns: each lib/*.js has a single responsibility.
– Promise-based asynchronous flow.
– Plugin-style extensibility via config (e.g., custom detective options, Graphviz flags).
d. Key Technologies & Libraries
– Node.js core: fs, path.
– dependency-tree/precinct for module analysis.
– Graphviz (via CLI).
– Promises (native or Bluebird).
– Commander or minimist (in CLI for argument parsing).
– Test frameworks (Mocha, Chai, or similar).