Navigate code documentation graphs extracted from @flowdoc-* comment tags.

• 📝 Parse @flowdoc-* tags from PHP, TypeScript, JavaScript files
• 🔗 Build navigable graphs per topic
• 🧭 Step-by-step navigation with branching support
• ⚠️ Warnings for duplicates, missing dependencies, cycles

// @flowdoc-topic: user-registration
// @flowdoc-id: REG-001
// @flowdoc-step: User submits registration form

// @flowdoc-topic: user-registration
// @flowdoc-id: REG-002
// @flowdoc-step: Validate email and password
// @flowdoc-dependency: REG-001

// @flowdoc-topic: user-registration
// @flowdoc-id: REG-003
// @flowdoc-step: Create user in database
// @flowdoc-dependency: REG-002 [After validation passes]
// @flowdoc-links: file:app/Models/User.php:45; symbol:App\\Models\\User@create

1. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Run FlowDoc: Pick Topic
3. Select a topic
4. Use Prev/Next buttons to navigate the graph

• Node.js 18+
• VS Code 1.85+

cd flowdoc
npm install
npm run compile

1. Open the flowdoc folder in VS Code
2. Press F5 (or Run → Start Debugging)
3. A new VS Code window opens (Extension Development Host)
4. Open a folder with @flowdoc-* comments
5. Run FlowDoc: Pick Topic from Command Palette

npm run watch

Changes auto-compile. Reload Extension Host with Cmd+R / Ctrl+R.

Create flowdoc.config.yaml in workspace root:

version: 1
repos:
  other-repo:
    path: /path/to/other/repo

FlowDoc supports bidirectional navigation between repositories:

Backward navigation (child → parent): Use @flowdoc-dependency with repo-name@node-id:

// In frontend-app repo
// @flowdoc-topic: authentication
// @flowdoc-id: login-handler
// @flowdoc-step: Handle login form submission
// @flowdoc-dependency: backend-api@auth-endpoint

Forward navigation (parent → children): Use @flowdoc-children with comma-separated IDs:

// In backend-api repo
// @flowdoc-topic: authentication
// @flowdoc-id: auth-endpoint
// @flowdoc-step: Backend auth endpoint
// @flowdoc-children: frontend-app@login-handler, mobile-app@auth-screen

Cross-repo navigation opens the target repository in a new VS Code window.

Use @flowdoc-line for compact single-line documentation:

@flowdoc-line: TOPIC | ID | STEP | links | dependency | children

Examples:

// Minimal (required fields only)
// @flowdoc-line: checkout | CART-001 | User adds item to cart

// With dependency
// @flowdoc-line: checkout | CART-002 | Cart totals calculated | | CART-001

// Full format
// @flowdoc-line: checkout | CART-003 | Proceed to payment | file:checkout.ts:50 | CART-002 [After validation] | CART-004

FlowDoc automatically detects numeric sequences in IDs and creates bidirectional links:

// No explicit dependencies needed - FlowDoc auto-links these!
// @flowdoc-topic: onboarding
// @flowdoc-id: STEP-001
// @flowdoc-step: Welcome screen

// @flowdoc-topic: onboarding
// @flowdoc-id: STEP-2       // Auto-linked to STEP-001
// @flowdoc-step: Profile setup

// @flowdoc-topic: onboarding
// @flowdoc-id: STEP-03      // Auto-linked to STEP-2
// @flowdoc-step: Preferences

How it works:

• Detects numeric suffix in IDs (e.g., STEP-001, TASK-2, FLOW-03)
• Handles mixed formats: 001 links to 2 links to 03
• Auto-assigns dependency to {prefix}{n-1} if it exists
• Auto-assigns children to {prefix}{n+1} if it exists
• Only applies within the same topic
• Explicit dependencies/children override auto-detection

FlowDoc shows validation errors as VS Code diagnostics (yellow underlines) directly in your code for missing required fields:

• missing-topic: Block has @flowdoc-id but no @flowdoc-topic
• missing-id: Block has @flowdoc-topic but no @flowdoc-id
• missing-step: Block has topic and id but no @flowdoc-step

These appear in the Problems panel and as squiggly underlines in the editor.

FlowDoc shows non-blocking warnings in the webview panel for:

• Duplicate ID: Same ID used twice in a topic (first occurrence wins)
• Missing Dependency: Dependency ID not found (node treated as root)
• Cycle Detected: Circular dependency chain

• .php
• .ts
• .js

Files in node_modules are excluded.

src/
├── extension.ts          # Entry point, command registration
├── types/
│   └── index.ts          # TypeScript interfaces
├── parser/
│   └── commentParser.ts  # Line-based @flowdoc-* parser
├── indexer/
│   └── workspaceIndexer.ts  # FileSystemWatcher + caching
├── graph/
│   └── graphBuilder.ts   # DAG construction with cycle detection
├── config/
│   └── configLoader.ts   # YAML/JSON config loader
└── webview/
    └── webviewProvider.ts  # Webview panel management

media/
├── styles.css            # VSCode theme-aware styles
└── main.js               # Webview UI logic

MIT