@zoldia/omnigraph 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +57 -89
  2. package/package.json +7 -2
package/README.md CHANGED
@@ -16,30 +16,49 @@ OmniGraph is a free, local developer tool that statically analyzes full-stack mo
16
16
 
17
17
  ## Quick Start
18
18
 
19
- **Prerequisites:** Node.js >= 18, npm >= 9
19
+ **Prerequisites:** Node.js >= 18
20
20
 
21
21
  ```bash
22
- # Clone the repository
23
- git clone https://github.com/RMV-Coder/OmniGraph.git
24
- cd OmniGraph
22
+ # Run directly with npx (no install needed)
23
+ npx @zoldia/omnigraph --path /path/to/your/project
25
24
 
26
- # Install dependencies
27
- npm install
25
+ # Or install globally
26
+ npm install -g @zoldia/omnigraph
27
+ omnigraph --path /path/to/your/project
28
+ ```
28
29
 
29
- # Build all packages
30
- npm run build
30
+ Then open `http://localhost:4000` in your browser.
31
31
 
32
- # Analyze a repository
33
- npm run dev -- --path ../my-project
34
- ```
32
+ ### CLI Commands
33
+
34
+ ```bash
35
+ # Start the visualization server (default action)
36
+ omnigraph --path <repo-path> # Starts server on port 4000
37
+ omnigraph --path <repo-path> serve --port 8080 # Custom port
35
38
 
36
- Then open `http://localhost:3000` in your browser.
39
+ # Query the dependency graph
40
+ omnigraph --path <repo-path> graph --stats # Summary statistics
41
+ omnigraph --path <repo-path> graph --node src/index.ts # Inspect a node
42
+ omnigraph --path <repo-path> graph --deps src/index.ts # Transitive dependencies
43
+ omnigraph --path <repo-path> graph --filter nextjs-api-route # Filter by type
37
44
 
38
- ### CLI Options
45
+ # Trace data flow
46
+ omnigraph --path <repo-path> trace --from src/app/api/users/route.ts
39
47
 
40
- ```
41
- omnigraph --path <repo-path> # Required: path to the repo to analyze
42
- omnigraph --path <repo-path> --port 4000 # Optional: custom port (default 3000)
48
+ # List methods in a file
49
+ omnigraph --path <repo-path> methods --file src/lib/auth.ts --exported
50
+
51
+ # Make HTTP requests (like curl/Postman)
52
+ omnigraph --path <repo-path> fetch --url http://localhost:3000/api/users \
53
+ --method POST --body '{"email":"test@test.com"}' --env-token AUTH_TOKEN
54
+
55
+ # Inspect database schema from graph
56
+ omnigraph --path <repo-path> schema --fk
57
+ omnigraph --path <repo-path> schema --table users
58
+
59
+ # Machine-readable JSON output (for AI coding agents)
60
+ omnigraph --path <repo-path> --json graph --stats
61
+ omnigraph --path <repo-path> --json trace --from src/index.ts
43
62
  ```
44
63
 
45
64
  ## Features
@@ -57,14 +76,24 @@ OmniGraph doesn't just find imports — it understands framework patterns:
57
76
  - **Obsidian/Markdown**: Detects wiki-links (`[[Page]]`), embeds (`![[Page]]`), YAML frontmatter (tags, aliases), and classifies MOC/daily/readme note types
58
77
 
59
78
  ### Interactive Visualization
60
- - **5 Layout Presets**: Directory (grouped by folder), Hierarchical, Force-Directed, Grid, Mind Map (LR/RL)
79
+ - **6 Layout Presets**: Directory (grouped by folder), Hierarchical, Column Flow (Frontend/API/Services/Database), Force-Directed, Grid, Mind Map (LR/RL)
80
+ - **Column Flow Layout**: Top-to-bottom layout with 4 columns. Nodes are auto-classified by type and file path. Column-aware compaction preserves columns while collapsing vertical gaps.
61
81
  - **Live Force Simulation**: In force-directed mode, dragging a node causes nearby nodes to push and pull reactively via d3-force physics
62
82
  - **Search & Filter with BFS Expansion**: Search nodes by name, filter by type with color-coded toggle chips. Hide or dim non-matching nodes. Connected nodes expand via BFS depth slider to reveal full data flow paths.
63
83
  - **Hub-Centric Compaction**: After filtering, compact visible nodes around the most-connected hub node(s) using d3-force. Single hub stays pinned; multiple hubs meet at their average position.
64
- - **Node Inspector**: Click any node to see its file path, type, route metadata, and ID in the sidebar
65
- - **Color-Coded Types**: Each node type has a distinct color — controllers (red), injectables (blue), modules (orange), Python files (blue), FastAPI routes (teal), Laravel controllers (red), markdown (purple), and more
84
+ - **Node Inspector**: Click any node to see its file path, type, route metadata, and ID in the sidebar. Expand file nodes into individual method-level nodes.
85
+ - **Database ERD**: DB tables connected via foreign key edges (ERD-style). Click an API route to highlight all connected DB tables.
86
+ - **Color-Coded Types**: Each node type has a distinct color — controllers (red), injectables (blue), modules (orange), Python files (blue), FastAPI routes (teal), Laravel controllers (red), markdown (purple), DB tables (steel-blue), and more
66
87
  - **Clickable Minimap**: Zoom and pan directly on the minimap for faster navigation
67
88
 
89
+ ### CLI for Humans and AI Agents
90
+ All CLI commands support `--json` for machine-readable output, designed for AI coding agents (Claude Code, Cursor, etc.):
91
+ - **`graph`** — Query nodes, edges, dependencies, reverse dependencies, stats
92
+ - **`trace`** — Trace data flow from a file through HTTP calls to database queries
93
+ - **`fetch`** — HTTP client with `.env` token resolution (like curl/Postman)
94
+ - **`methods`** — List functions/methods in a file with filters
95
+ - **`schema`** — Inspect database tables, foreign keys, code references
96
+
68
97
  ### Export
69
98
  - **PNG** — 2x resolution raster image
70
99
  - **SVG** — Scalable vector graphic
@@ -73,16 +102,15 @@ OmniGraph doesn't just find imports — it understands framework patterns:
73
102
 
74
103
  ### Sidebar Tabs
75
104
  The right sidebar has four tabs:
76
- - **Graph** — Layout selector, search/filter with depth slider, type chips, node inspector, export dropdown, compact button
77
- - **API** — Postman-style API debugger (auto-fills from cross-network edges)
78
- - **Trace** — Step-through flow tracer with Back/Next navigation and animated highlighting
79
- - **Settings** — Configurable edge labels (show/hide per type, color, font size), graph options (minimap, animations), search defaults, with per-category reset and localStorage persistence
105
+ - **Graph** — Layout selector (6 presets), search/filter with depth slider, type chips, node inspector with method expansion, export dropdown, compact button
106
+ - **API** — Postman-style API debugger with configurable base URL (auto-fills from cross-network edges)
107
+ - **Trace** — Step-through flow tracer with Back/Next navigation, animated highlighting, and database query/join/result steps
108
+ - **Settings** — Configurable edge labels (show/hide per type, color, font size), graph options (minimap, edge animation, FK labels), search defaults, with per-category reset and localStorage persistence
80
109
 
81
110
  ## Technology Stack
82
111
 
83
112
  | Component | Technology |
84
113
  |-----------|-----------|
85
- | Monorepo | npm workspaces (5 packages) |
86
114
  | CLI | Node.js + TypeScript + Commander.js |
87
115
  | Server | Express.js with rate limiting |
88
116
  | TypeScript/JS Parser | `@typescript-eslint/typescript-estree` |
@@ -91,9 +119,8 @@ The right sidebar has four tabs:
91
119
  | Markdown Parser | Regex-based wiki-link/embed/frontmatter extraction |
92
120
  | Frontend | React 18 + Vite |
93
121
  | Graph Engine | React Flow |
94
- | Layout Engines | dagre (hierarchical/mind map), d3-force (force-directed, compaction) |
122
+ | Layout Engines | dagre (hierarchical/mind map), d3-force (force-directed, compaction), custom column flow |
95
123
  | GIF Export | gif.js (web worker encoding) |
96
- | Testing | Vitest |
97
124
 
98
125
  ## Architecture
99
126
 
@@ -104,36 +131,6 @@ CLI (@omnigraph/cli) → Server (@omnigraph/server) → Parsers (@omnigraph/pars
104
131
 
105
132
  **Data flow:** Filesystem → AST parsing → OmniGraph model (nodes/edges) → JSON API (`/api/graph`) → React Flow UI
106
133
 
107
- ## How to Add a New Language Parser
108
-
109
- OmniGraph is extensible by design. To add support for a new language or framework:
110
-
111
- 1. Create a new file in `packages/parsers/src/<language>/<language>-parser.ts`
112
- 2. Implement the `IParser` interface:
113
- ```typescript
114
- import { IParser } from '../IParser';
115
- import { OmniGraph } from '../types';
116
-
117
- export class MyLanguageParser implements IParser {
118
- canHandle(filePath: string): boolean {
119
- return /\.mylang$/.test(filePath);
120
- }
121
-
122
- parse(filePath: string, source: string): Partial<OmniGraph> {
123
- // Extract nodes and edges from source code
124
- return { nodes: [...], edges: [...] };
125
- }
126
- }
127
- ```
128
- 3. Register your parser in `packages/parsers/src/parser-registry.ts`:
129
- ```typescript
130
- import { MyLanguageParser } from './mylanguage/mylanguage-parser';
131
- const parsers: IParser[] = [..., new MyLanguageParser()];
132
- ```
133
- 4. Add node colors in `packages/ui/src/layout/shared.ts` and labels in `packages/ui/src/components/Sidebar.tsx`
134
-
135
- No changes to the server, CLI, or graph engine are needed — the plugin architecture handles the rest.
136
-
137
134
  ## Omni JSON Schema
138
135
 
139
136
  All parsers produce a standardized graph format regardless of source language:
@@ -162,40 +159,11 @@ All parsers produce a standardized graph format regardless of source language:
162
159
  }
163
160
  ```
164
161
 
165
- ## Running Tests
166
-
167
- ```bash
168
- npx vitest run # Run all tests (132 tests across 9 files)
169
- npx vitest --watch # Watch mode
170
- ```
171
-
172
- ## Contributing
173
-
174
- Contributions are welcome! Here's how to get started:
175
-
176
- 1. **Fork the repo** and create a feature branch
177
- 2. **Install dependencies**: `npm install`
178
- 3. **Build**: `npm run build`
179
- 4. **Run tests**: `npx vitest run` — make sure all tests pass
180
- 5. **Submit a PR** with a clear description of what you changed and why
181
-
182
- ### Good First Issues
183
-
184
- - Add a new language parser (Go, Rust, Java, C#, Ruby)
185
- - Improve import resolution for edge cases (barrel exports, dynamic imports)
186
- - Add dark/light theme toggle
187
- - WebSocket connection tracing
188
-
189
- ## Project Documentation
162
+ ## Links
190
163
 
191
- | Document | Description |
192
- |----------|-------------|
193
- | [PRD](docs/PRD.md) | Product requirements, feature status, and roadmap |
194
- | [SAD](docs/SAD.md) | Software architecture, data flow, and design decisions |
195
- | [ADR-001](docs/adr/ADR-001-parsing-engine.md) | Why typescript-estree for Phase 1 |
196
- | [ADR-002](docs/adr/ADR-002-phase2-multi-language-parsing.md) | Why regex-based parsing for Phase 2 Python/PHP |
197
- | [ADR-003](docs/adr/ADR-003-markdown-obsidian-parser.md) | Markdown/Obsidian wiki-link parser design |
198
- | [API Spec](docs/API-SPEC.md) | HTTP endpoint and CLI interface documentation |
164
+ - [GitHub Repository](https://github.com/RMV-Coder/OmniGraph)
165
+ - [Changelog](https://github.com/RMV-Coder/OmniGraph/blob/main/CHANGELOG.md)
166
+ - [API Specification](https://github.com/RMV-Coder/OmniGraph/blob/main/docs/API-SPEC.md)
199
167
 
200
168
  ## License
201
169
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zoldia/omnigraph",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "A multi-language, AST-driven dependency visualizer for complex codebases. Parses TypeScript/NestJS/Next.js, Python/FastAPI/Django, PHP/Laravel, and Markdown/Obsidian and renders an interactive dependency graph.",
5
5
  "bin": {
6
6
  "omnigraph": "dist/cli.js"
@@ -28,7 +28,12 @@
28
28
  "obsidian",
29
29
  "wiki-links",
30
30
  "react-flow",
31
- "gif-export"
31
+ "gif-export",
32
+ "erd",
33
+ "foreign-keys",
34
+ "cli",
35
+ "method-extraction",
36
+ "tsconfig-paths"
32
37
  ],
33
38
  "repository": {
34
39
  "type": "git",