Add automated OVERVIEW.md generator with B-method specifications and Mermaid diagrams

[Copilot]

Implements a Python script that analyzes the codebase and generates formal documentation with B-method style specifications and visual architecture diagrams.

Implementation

Script (generate_overview.py)

• Analyzes 55 JavaScript source files via regex-based AST extraction
• Extracts classes, functions, dependencies, and JSDoc comments
• Categorizes modules by architecture layer (main process, renderer, shared, plugins)
• Zero external dependencies (stdlib only)

Generated Documentation (OVERVIEW.md)

• B-method formal specifications: Abstract machines with SETS, INVARIANTS, OPERATIONS, and refinement layers
• 18 Mermaid diagrams: System context, multi-process architecture, state machines (3 FSMs), dependency graphs, data flow sequences
• Module catalog: All 55 files with extracted structure and relationships
• Formal properties: System invariants, liveness/safety properties, proof obligations

Usage

python3 generate_overview.py [project_path]

Generates 1,902-line specification document with:

• Abstract-to-concrete refinement mapping
• State machine specifications for application, prompt, and story lifecycles
• Security model (IPC bridge isolation, validation chains)
• Plugin extensibility contracts

Code Quality

• Regex patterns extracted as module constants (REQUIRE_PATTERN, CLASS_PATTERN, etc.)
• Configurable limits (MAX_DIAGRAM_NODES, MAX_FUNCTIONS_DISPLAY)
• Dynamic project name detection from package.json
• Robust I/O error handling with validation

Original prompt

Generate a OVERVIEW.md document by running a loop against each file using a puthon script; looking at each file; approximate the program as a high level spec and then refinements; give the docs a B-method flavor. Use mermaid diagrams to picture things.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.