Skip to content

CLAUDE.md

Latest commit

 

History

History
235 lines (193 loc) · 7.89 KB

CLAUDE.md

File metadata and controls

235 lines (193 loc) · 7.89 KB

Claude Instructions for Flowditor

Critical Rules

1. Commit Every Change

ALWAYS create a new git commit after completing each feature, fix, or change. This allows easy reverting if needed.

  • One commit per logical change (don't bundle unrelated changes)
  • Use descriptive commit messages following conventional commits (e.g., feat:, fix:, refactor:)
  • Commit AFTER updating documentation and verifying the build compiles

2. Update Documentation

ALWAYS update the documentation when making any changes to the codebase. This includes:

  • README.md - User-facing documentation
  • CHANGELOG.md - Version history (add to [Unreleased] section)
  • This CLAUDE.md file - Development instructions
  • ideas.md - Feature tracking (mark as completed if from ideas list)

Documentation must be 100% accurate and reflect the current state of the code.

Project Overview

Flowditor is a VSCode extension for security auditors to create and manage "flows" - named collections of functions representing execution paths or logical groupings in a codebase.

Architecture

flowditor/
├── src/
│   ├── extension.ts           # Main entry point, activates extension
│   ├── types.ts               # TypeScript interfaces (FlowData, FunctionData, FlowItem)
│   ├── storage/
│   │   └── FlowStorage.ts     # Persistence layer (.vscode/flowditor.json)
│   ├── providers/
│   │   ├── FlowsTreeProvider.ts  # TreeView data provider
│   │   └── FlowCodeLensProvider.ts  # CodeLens provider for in-editor annotations
│   ├── commands/
│   │   └── index.ts           # All command implementations
│   └── utils/
│       └── symbols.ts         # Symbol provider utilities
├── resources/
│   └── flowditor-icon.svg     # Activity bar icon
├── package.json               # Extension manifest
└── tsconfig.json              # TypeScript config

Key Components

FlowStorage (src/storage/FlowStorage.ts)

  • Reads/writes flows to .vscode/flowditor.json
  • Tracks last used flow in workspaceState (for quick add feature)
  • Handles export/import to external JSON files
  • moveFunctionInFlow() - Reorders functions within a flow

FlowsTreeProvider (src/providers/FlowsTreeProvider.ts)

  • Implements TreeDataProvider<FlowItem> and TreeDragAndDropController<FlowItem>
  • Fetches fresh symbol positions when building tree (handles file changes)
  • Groups functions by file URI to minimize symbol provider calls
  • Supports drag-and-drop reordering of functions within a flow (with confirmation dialog)

FlowCodeLensProvider (src/providers/FlowCodeLensProvider.ts)

  • Implements CodeLensProvider to show flow membership in editor
  • Displays clickable annotations above functions that belong to flows
  • Builds function-to-flow index for efficient lookup
  • Refreshes when flows change via refresh() method

Commands (src/commands/index.ts)

  • createFlow - Create new empty flow
  • createFlowFromFunction - Create flow with initial function
  • addFunctionToFlow - Add function via picker
  • quickAddFunction - Add function at cursor to last used flow
  • renameFlow, deleteFlow, removeFunction - Management
  • goToFunction - Navigate with 500ms highlight
  • expandAll - Expand all flows in tree
  • exportFlows, importFlows - JSON export/import

Symbol Utilities (src/utils/symbols.ts)

  • showFunctionPicker() - QuickPick with visible functions prioritized
  • getFunctionAtCursor() - Get function containing cursor position
  • Filters to callable symbols only (Function, Method, Constructor)

Data Types

FlowData

interface FlowData {
  id: string;
  name: string;
  functions: FunctionData[];
  createdAt: number;
  updatedAt: number;
}

FunctionData

interface FunctionData {
  id: string;
  name: string;
  uri: string;           // File URI as string
  range: {
    start: { line: number; character: number };
    end: { line: number; character: number };
  };
  kind: SymbolKind;
}

FlowItem

  • Extends vscode.TreeItem
  • Has itemType: 'flow' | 'function'
  • Functions have navigation command attached

Commands Reference

Command ID Description
flowditor.createFlow Create new flow
flowditor.createFlowFromFunction Create flow from function
flowditor.addFunctionToFlow Add function via picker
flowditor.quickAddFunction Add function at cursor
flowditor.deleteFlow Delete a flow
flowditor.renameFlow Rename a flow
flowditor.removeFunction Remove function from flow
flowditor.goToFunction Navigate to function
flowditor.exportFlows Export to JSON file
flowditor.importFlows Import from JSON file
flowditor.refreshFlows Refresh tree view
flowditor.expandAll Expand all flows
flowditor.revealInFlow Reveal function in sidebar (from CodeLens)

Keybindings

Key Command
Cmd+Shift+A (Mac) / Ctrl+Shift+A (Win/Linux) Quick Add Function

Development

Build

npm run compile    # Compile TypeScript
npm run watch      # Watch mode
npm run lint       # Run ESLint

Debug

  1. Press F5 in VSCode to launch Extension Development Host
  2. Set breakpoints in TypeScript files
  3. Use Debug Console for output

Adding a New Command

  1. Add command definition to package.json under contributes.commands
  2. Add menu entries if needed under contributes.menus
  3. Register handler in src/commands/index.ts
  4. Run npm run compile to verify build
  5. Update README.md with the new command
  6. Update CHANGELOG.md (add to [Unreleased] section)
  7. Commit the changes

Adding a New Feature

  1. Plan the implementation
  2. Implement the feature
  3. Run npm run compile to verify build
  4. Test thoroughly
  5. Update README.md
  6. Update CHANGELOG.md (add to [Unreleased] section)
  7. Update ideas.md (mark as completed if from ideas list)
  8. Update this CLAUDE.md if architecture changes
  9. Commit the changes with a descriptive message (e.g., feat: Add <feature name>)

Storage Location

  • Flows: .vscode/flowditor.json (visible file, can be committed to git)
  • Last used flow: VSCode workspaceState (temporary preference)

Testing Checklist

When making changes, verify:

  • Extension compiles without errors (npm run compile)
  • New flows can be created
  • Functions can be added via picker
  • Quick add works (Cmd+Shift+A)
  • Navigation works and highlights function
  • Line numbers update when file changes
  • Export/import works
  • Tree view refreshes correctly
  • CodeLens annotations appear above functions in flows
  • Clicking CodeLens reveals function in sidebar
  • Drag-and-drop reordering works within a flow

Common Patterns

Refreshing Tree and CodeLens

// Use refreshAll helper in commands/index.ts
refreshAll(provider, codeLensProvider);

// Or individually:
provider.refresh();         // Refreshes tree view
codeLensProvider.refresh(); // Refreshes CodeLens annotations

Getting Current Symbols

const symbols = await vscode.commands.executeCommand<vscode.DocumentSymbol[]>(
  'vscode.executeDocumentSymbolProvider',
  uri
);

Showing Messages

vscode.window.showInformationMessage('Success message');
vscode.window.showWarningMessage('Warning message');
vscode.window.showErrorMessage('Error message');

Feature Ideas

See ideas.md for planned features. When implementing:

  1. Check the box in ideas.md
  2. Update README.md
  3. Update CHANGELOG.md (add to [Unreleased] section)
  4. Update this file if needed

Releasing a New Version

  1. Move [Unreleased] changes to a new version section in CHANGELOG.md
  2. Update version in package.json
  3. Update Release Notes in README.md
  4. Run npm run compile to verify build
  5. Create git tag: git tag v0.x.x
  6. Publish to marketplace: vsce publish