How piotrfleury/discover works
Step 1: Identify the project type and purpose
• This is a Dart-based command-line interface (CLI) tool called “discover” whose main job is to analyze a Dart/Flutter project’s coverage data, find untested Dart source files, generate an updated coverage file (discover-lcov.info), and produce an HTML report.
• It is not a web or mobile app; it is a developer tool that invokes underlying test runners (e.g. flutter test --coverage), parses coverage outputs, and writes new reports.
Step 2: Analyze the file structure
• bin/discover.dart: the Dart CLI entrypoint.
• lib/src/command_runner.dart: sets up the CLI framework (parses args, dispatches commands).
• lib/src/commands/scan_command.dart & update_command.dart: implement the “scan” and “update” sub-commands.
• lib/src/converters: modules that parse LCOV files and Dart source to extract coverage and code-line metrics.
• lib/src/system/system_runner.dart: abstracts process invocation (calling flutter test, genhtml, opening files).
• lib/src/extensions & models: utility extensions on filesystem entities and data models (e.g., CodeLine).
• flutter_example/: a sample Flutter app project used to demonstrate Discover against a real codebase.
• test/: unit tests for each command, converter, extension, and runner.
Step 3: Examine the README for extra insights
• The “scan” command: looks for an existing coverage tracefile or runs flutter test --coverage, reads lcov.info, finds untested sources, writes discover-lcov.info, and generates an HTML report.
• There’s an “ignore” mechanism via a .discoverignore file to filter out files and patterns.
• A minimal “update” command exists (likely to merge or refresh coverage).
a. CLI Layer
• Entrypoint (bin/discover.dart)
• Command Runner (lib/src/command_runner.dart)
b. Command Modules
• ScanCommand
• UpdateCommand
c. Core Services
• SystemRunner (process orchestration)
• Converters
– LcovConverter (parses coverage data)
– DartParser (scans Dart files)
d. Data & Models
• CodeLine model
• Version info
• .discoverignore patterns
e. External Dependencies/Tools
• Flutter test runner (shell command)
• genhtml (coverage HTML generator)
• File system (source directories, lcov.info, discover-lcov.info)
f. User Environment
• Developer’s terminal (stdin/stdout)
• Browser (for HTML report)
Step 5: Determine relationships and data flows
ScanCommand asks SystemRunner: “Is there an existing lcov.info?”
– If no, SystemRunner runs flutter test --coverage.
SystemRunner optionally opens the HTML in a browser.
Step 6: Highlight architectural patterns and design principles
• Modular command pattern: each CLI sub-command is isolated (Scan, Update).
• Separation of concerns: converters handle parsing, SystemRunner isolates side-effects, extensions provide reusable helpers.
• Extensibility: new commands or converters can be added under lib/src/commands or lib/src/converters.
• Flow from user input → core logic → external tools → output artifacts.
• Clear boundaries between in-process components (Dart modules) and out-of-process tools (flutter test, genhtml).
• Plugin/ignore extension point (.discoverignore file).
• Use rectangles for in-process modules (CommandRunner, ScanCommand, LcovConverter, DartParser, SystemRunner).
• Use parallelograms for external tools (Flutter test, genhtml, Browser).
• CLI input → CommandRunner → Commands
• Commands → SystemRunner → External tool
• External tool output → Converters → Commands
• Commands → File system → HTML report
• Commands → SystemRunner → Browser
• Green for core Dart modules
• Blue for external processes/tools
• Orange for data artifacts (coverage files, HTML)
Step 9: Emphasize detail and completeness
• Sub-components under lib/src (commands, converters, system).
• Ignore mechanism as a decision/filter step.
• Error handling paths if relevant (e.g., missing coverage file leads to test run).