Fable - Flutter

Living Documentation for Flutter Apps
BDD feature visualization, module documentation, and Gherkin scenario management

Overview

Fable transforms your Flutter codebase into living documentation. It helps teams maintain structured, discoverable documentation by:

• Discovering modules automatically from lib/features/*
• Parsing BDD .feature files with Gherkin syntax (Rules, Scenarios, Given/When/Then)
• Managing module README.md documentation following BDD standards
• Visualizing git activity per feature with contributor insights
• ✨ AI-assisted documentation generation for undocumented modules

Perfect for enterprise Flutter apps where understanding "what this module does, why it exists, and what changed" is critical.

Features

Feature Discovery

Automatically scans your lib/features/ directory and displays all modules in a sidebar tree view. Instantly see which modules have documentation and which need attention.

BDD Feature Visualization

Parse and display Gherkin .feature files with:

• Intent blocks (In order to / As a / I need to)
• Rules and their scenarios
• Given/When/Then steps with proper formatting
• Validation against BDD best practices

Module Documentation

Generate and manage README.md files following the BDD Module Documentation Template:

• Purpose & Business Domain
• Features list
• Key Business Rules
• Stakeholders
• Related Modules
• Dependencies
• Git Contributors (auto-populated)

Git Activity Panel

Git history showing:

• Commit hash (clickable to view diff)
• Author per commit
• Date and message
• Bug fix highlighting

✨ AI-Assisted Generation

• Generate BDD .feature files from code analysis
• Generate module README.md templates
• "Generate with AI" button to populate templates with real content

Installation

From Source

1. Clone the repository:

   git clone https://github.com/cyenite/fable-flutter.git
   cd fable-flutter
   

2. Install dependencies:

   npm install
   

3. Build & run in debug mode:

   • Press F5 (opens Extension Development Host window)

4. Package for installation:

   npm run compile
   npx vsce package
   

   → Produces fable-flutter-x.y.z.vsix

5. Install the .vsix in VS Code:

   • Extensions view → ⋯ → Install from VSIX...

From Marketplace

(Coming soon) Search for "Fable - Flutter" in the VS Code Extensions marketplace.

Usage

1. Open the Fable Sidebar

Click the Fable icon in the Activity Bar (left sidebar), or use:

• Ctrl+Shift+P → Fable: Refresh

2. Browse Features

• Click any feature module in the tree view
• Opens a detailed panel with tabs:
  • Module Info - README.md content
  • Features - BDD scenarios and rules
  • Validation - Documentation quality checks
  • Rules - All business rules at a glance

3. Generate Documentation

For undocumented modules:

• Click the ✨ Generate button to create a .feature file
• Click Generate README to create module documentation
• Use Generate with AI to populate templates with real content

4. View Git History

• Expand the Git Activity panel (right side)
• Click commit hashes to view diffs
• See contributor information per commit

Project Structure Expected

Fable works best with feature-first architecture:

lib/
└── features/
    ├── authentication/
    │   ├── README.md           # Module documentation
    │   ├── FEATURE.md          # BDD feature file (Gherkin)
    │   ├── bloc/
    │   ├── data/
    │   ├── domain/
    │   └── presentation/
    ├── dashboard/
    │   ├── README.md
    │   ├── FEATURE.md
    │   └── ...
    └── offline_sync/
        └── ...

BDD Feature File Format

Fable parses .feature files following Gherkin 6 syntax:

Feature: User Authentication
  In order to access secure areas of the application
  As a registered user
  I need to authenticate with valid credentials

  Rule: Only users with valid credentials may access the system

    Scenario: The one where valid credentials grant access
      Given a user "john@example.com" with password "secure123"
      When the user submits login credentials
      Then access is granted
      And the user is redirected to the dashboard

    Scenario: The one where invalid password is rejected
      Given a user "john@example.com" with password "wrong"
      When the user submits login credentials
      Then access is denied
      And an error message is displayed

Requirements

• VS Code 1.85+
• Git installed and available in PATH
• Workspace must be a Git repository
• Flutter/Dart project using lib/features/ convention

Commands

Configuration

AI Model Selection

Fable uses VS Code's Language Model API to generate content with AI. When multiple models are available:

1. First Use: A quick pick dialog appears letting you choose which model to use
2. Save Preference: After selecting, you can save your choice as the default
3. Change Model: Use Fable: Select AI Model command to switch models anytime
4. Progress Indicator: Shows which model is being used during generation

Available models depend on your GitHub Copilot subscription and may include:

• GPT-4o
• Claude 4.5 Sonnet
• Other models provided by Copilot

To set a preferred model, add to your settings:

{
  "fable.aiModel": "gpt-4o"
}

Roadmap

• [ ] Configurable feature paths via settings
• [ ] Export documentation as PDF/Markdown
• [ ] Integration with Jira/Linear for ticket linking
• [ ] Support for monorepo structures
• [ ] Mermaid diagram generation from features
• [ ] Test coverage integration
• [ ] Multi-language support (i18n for Gherkin)

Contributing

1. Fork & branch: git checkout -b feature/your-feature
2. Follow existing code style
3. Add tests for core logic changes
4. Update documentation
5. Open PR with clear description

License

MIT

Built with ❤️ for Flutter teams practicing BDD