vibefpmgui

  1"""A desktop GUI for the Fortran Package Manager (fpm).
  2
  3> [!NOTE]
  4> These are the **API docs** for the `vibefpmgui` Python package, generated
  5> with [pdoc](https://pdoc.dev) from the docstrings in the source code. They
  6> describe the code; for what the app does and how to use it, see the
  7> [website](https://jacobwilliams.github.io/VibeFPMGUI/) or the
  8> [README](https://github.com/jacobwilliams/VibeFPMGUI#readme).
  9
 10VibeFPMGUI opens an `fpm.toml` and runs fpm's commands (build, run, test,
 11update, clean) with live progress, shows the project's dependencies as an
 12interactive graph, and has a built-in Fortran editor with a language server,
 13linting, formatting and an AI code reviewer that runs on your own computer.
 14It is written in Python with Qt (PySide6, through qtpy).
 15
 16*VibeFPMGUI is an experimental, vibe-coded project: expect rough edges.*
 17
 18## Links
 19
 20* **Website:** <https://jacobwilliams.github.io/VibeFPMGUI/>
 21* **Source code and issues:** <https://github.com/jacobwilliams/VibeFPMGUI>
 22* **fpm:** <https://fpm.fortran-lang.org>
 23* Tools it uses: [fortls](https://fortls.fortran-lang.org) (language server),
 24  [fortitude](https://fortitude.readthedocs.io) (linter),
 25  [fprettify](https://github.com/fortran-lang/fprettify) (formatter),
 26  [Ollama](https://ollama.com) (local AI models),
 27  [pyqtgraph](https://www.pyqtgraph.org) (graph) and
 28  [Pygments](https://pygments.org) (syntax highlighting).
 29
 30## Running it
 31
 32```sh
 33pixi run start                      # reopens the last project
 34pixi run start path/to/fpm.toml     # or a project folder
 35pixi run demo                       # the demo project in examples/demo
 36```
 37
 38With pip (Python 3.11+): `pip install .` (add `.[fortran]` for fortls,
 39fortitude and fprettify, `.[ai]` for the Ollama client), then
 40`vibefpmgui [path/to/fpm.toml]`. fpm and a Fortran compiler must be on the
 41`PATH`. The program starts in `vibefpmgui.main_window.main`.
 42
 43The editor tools are optional. Without fortls or fortitude their *View*
 44menu item says "not found" and the feature is off; without fprettify the
 45*Format* button is greyed out; AI review needs Ollama only when you start one.
 46
 47## Project structure
 48
 49**Main window**
 50
 51| Module | What it does |
 52|---|---|
 53| `vibefpmgui.main_window` | The window: starting it, building it in order, closing it, and `main` |
 54| `vibefpmgui.window` | The window's parts, one mixin per area: panels, View menu, project, graph, editor tabs, Edit menu, language server, search, running fpm, Output, Test and Run, coverage, AI |
 55| `vibefpmgui.dock_snap` | Dragging a panel's edge past its smallest size collapses it, as in VS Code |
 56| `vibefpmgui.manifest` | Reading `fpm.toml` files and resolving the dependency tree (no Qt) |
 57| `vibefpmgui.graph_view` | The interactive dependency graph (pyqtgraph) |
 58| `vibefpmgui.project_tree` | The *Project files* tree, with fpm folder badges and `.gitignore` handling |
 59| `vibefpmgui.build_outputs` | The *Build outputs* tab: what fpm keeps in `build/` |
 60| `vibefpmgui.dep_updates` | *Check for Dependency Updates* (`git ls-remote`) |
 61| `vibefpmgui.about` | The About window |
 62| `vibefpmgui.packages` | *About → Packages…*: the environment's installed packages (`pixi list` / `conda list`) |
 63
 64**Build, test and run panels**
 65
 66| Module | What it does |
 67|---|---|
 68| `vibefpmgui.build_monitor` | The *Build* tab: a live table of the files fpm compiles, and compiler-message parsing |
 69| `vibefpmgui.test_monitor` | The *Tests* tab: each test's progress, time and output |
 70| `vibefpmgui.run_monitor` | The *Run* tab (the Tests tab with different wording) |
 71| `vibefpmgui.test_runner` | The small wrapper given to `fpm test --runner` to mark where each test starts and ends |
 72| `vibefpmgui.parallel_tests` | Running tests several at a time, each with its own output |
 73| `vibefpmgui.fpm_args` | fpm's command line: link flags, `--runner`, the test wrapper's command |
 74| `vibefpmgui.processes` | Ending a process and everything it started |
 75| `vibefpmgui.ansi` | Terminal color codes in program output, shown as colors |
 76| `vibefpmgui.output_links` | File locations in the output (runtime errors, backtraces, compiler messages) that open the file on a click |
 77| `vibefpmgui.terminal` | The *Terminal* tab: your shell in the project's folder, with exactly the app's environment (pyte, drawn by our own widget) |
 78
 79**Editor**
 80
 81| Module | What it does |
 82|---|---|
 83| `vibefpmgui.editor` | The editor tab: the file (loading, saving, changes on disk), the outline, the status line |
 84| `vibefpmgui.editor_language` | The tab's language-server features: hover, definitions, completion, references, rename |
 85| `vibefpmgui.editor_checks` | The tab's checks: fortitude, spelling, gremlins; the compiler's, fortls's and the AI's markers |
 86| `vibefpmgui.code_editor` | The text widget: keys, mouse, selections, indentation, highlights, its right-click menu |
 87| `vibefpmgui.editor_gutter` | The gutter: line numbers, change bars, coverage, gremlins, markers |
 88| `vibefpmgui.editor_issues` | Squiggles under issues, and the hover cards over them |
 89| `vibefpmgui.multi_cursor` | Several cursors at once |
 90| `vibefpmgui.hover_popup` | The editor's hover card |
 91| `vibefpmgui.find_bar` | The find and replace bar |
 92| `vibefpmgui.editor_shared` | What the editor's modules share: colors, delays, severities, text helpers |
 93| `vibefpmgui.source_text` | Reading source files the same way everywhere: encoding, line ends, what Search skips |
 94| `vibefpmgui.command_palette` | View → Command Palette…: the menus' commands, found by typing |
 95| `vibefpmgui.new_project` | File → New fpm Project…: fpm new, its options chosen in a dialog |
 96| `vibefpmgui.line_edits` | Toggle Line Comment, Move Line Up / Down, Sort Lines, Change Case |
 97| `vibefpmgui.wrapping_tabs` | The editor's tabs on several rows (View → Editor Tabs) |
 98| `vibefpmgui.console` | Console programs started without a console window flashing up (Windows); no Qt |
 99| `vibefpmgui.git_status` | A repository's status and the versions of a changed file (the git program; no Qt) |
100| `vibefpmgui.git_panel` | The *Git* tab: *Diff* (the branch, the changed files, the selected one's diff) or *Stats* |
101| `vibefpmgui.git_stats` | A repository's statistics: its commits, people, branches, tags, files, size (no Qt) |
102| `vibefpmgui.git_stats_view` | The Git tab's *Stats*: tiles, the people, and their commits over time (pyqtgraph) |
103| `vibefpmgui.diff_view` | Two versions of a file side by side or unified: aligning them, folding unchanged lines |
104| `vibefpmgui.complexity` | Fortran code complexity, lizard's metrics (CCN, NLOC, tokens, parameters, length, depth); no Qt |
105| `vibefpmgui.metrics_table` | A sortable table drawn on demand (the Complexity tab's procedures and files) |
106| `vibefpmgui.complexity_panel` | The *Complexity* tab: each procedure's metrics and each file's totals |
107| `vibefpmgui.control_flow` | A procedure's control-flow graph (blocks, decisions, loops, exits) and its layered layout; no Qt |
108| `vibefpmgui.cfg_view` | Drawing a control-flow graph (pyqtgraph) |
109| `vibefpmgui.highlighter` | Pygments syntax highlighting and the *Syntax Colors* styles |
110| `vibefpmgui.themes` | *View → Theme*: the whole window's colors (System, Light, Dark and colorful ones) |
111| `vibefpmgui.lsp` | The client for the fortls language server (hover, definition, completion, references, rename) |
112| `vibefpmgui.completion` | The completion list and argument-hint popups |
113| `vibefpmgui.hover_card` | The HTML of the hover card |
114| `vibefpmgui.symbol_search` | *Go to Symbol in Project* |
115| `vibefpmgui.references_panel` | The *References* tab |
116| `vibefpmgui.result_tree` | The list of places in files shared by the *Search*, *References* and *Problems* tabs (icons, syntax-colored lines) |
117| `vibefpmgui.problems_panel` | The *Problems* tab: everything flagged in the file in the editor |
118| `vibefpmgui.project_search` | *Find in Files*: search and replace across the project and its dependencies (*Search* tab) |
119| `vibefpmgui.rename_dialog` | The *Rename Symbol* preview |
120| `vibefpmgui.lint` | Linting with fortitude |
121| `vibefpmgui.formatter` | Formatting with fprettify |
122| `vibefpmgui.spelling` | Spell checking comments and strings (pyspellchecker) |
123| `vibefpmgui.gremlins` | Finding non-ASCII and invisible characters, and drawing the gutter's gremlin |
124
125**AI review**
126
127| Module | What it does |
128|---|---|
129| `vibefpmgui.ai_review` | Prompting a local model through Ollama and parsing its findings |
130| `vibefpmgui.review_monitor` | The *Review* tab: a timeline of every review, explanation, question and edit |
131| `vibefpmgui.ai_edits` | The AI's proposed edits (search/replace blocks): finding and applying them |
132| `vibefpmgui.ai_context` | What a chat sends the model, so it fits its context window |
133| `vibefpmgui.edit_cards` | The proposed edits as cards to accept or reject |
134
135**Shared helpers**
136
137| Module | What it does |
138|---|---|
139| `vibefpmgui.icons` | Toolbar icons, symbol badges and the app icon, drawn with QPainter |
140| `vibefpmgui.coverage` | Test coverage: gcov's counts collected and read |
141| `vibefpmgui.coverage_panel` | The *Coverage* tab: totals, each file's coverage, its missed lines and functions |
142| `vibefpmgui.widgets` | Small shared widgets (a status line that never widens the window), and running a dialog |
143| `vibefpmgui.background` | Blocking calls (Format, Fix All, asking Ollama) on a pool thread, the result back in the GUI thread |
144| `vibefpmgui.compat` | Things that differ between macOS, Linux and Windows |
145
146## How it fits together
147
148* **fpm runs as a child process** (`QProcess`). Its output goes to the
149  *Output* panel and is parsed line by line for the *Build* tab. fpm only
150  prints compiler output when a compile fails, so warnings are read from
151  its per-file `.o.log` files.
152* **Tests and programs run through `vibefpmgui.test_runner`**, which fpm
153  calls for each one (`--runner`). The markers it prints tell the *Tests*
154  and *Run* tabs where each starts and ends and how it exited. For tests
155  run in parallel, it only reports each test's command line
156  (``--collect``), and `vibefpmgui.parallel_tests.ParallelTests` runs them.
157* **The editor's Fortran features use separate programs:** fortls (a
158  long-running language server, see `vibefpmgui.lsp.LspClient`), fortitude
159  and fprettify (run on the editor's text through stdin), and Ollama (over
160  HTTP, on a worker thread). None of them blocks the window.
161* **Settings** are stored with `QSettings`, some per project (keyed by the
162  manifest's path). Set the `VIBEFPMGUI_SETTINGS` environment variable to an
163  `.ini` path to use a separate settings file, e.g. for testing.
164
165## Development
166
167```sh
168pixi run ruff check .     # lint the code
169pixi run test             # the tests (pytest + pytest-qt; no windows appear)
170pixi run coverage         # the same, with a code coverage report in web/coverage
171pixi run docs             # these API docs, into web/api
172pixi run docs-serve       # the same, live in the browser
173```
174
175The tests in `tests/` drive the real windows with
176[pytest-qt](https://pytest-qt.readthedocs.io), using Qt's offscreen platform
177(so they also run on CI machines without a display) and a settings file of
178their own (your settings are never touched). To watch them run, set
179`QT_QPA_PLATFORM=cocoa` (macOS), `xcb` (Linux) or `windows`. CI runs them on
180every push and publishes the [test coverage report](../coverage/index.html)
181(which lines of the code the tests run) next to these docs.
182
183Docstrings are Markdown with Google-style sections (`Args:`, `Returns:`,
184`Raises:`); a name in backticks, such as `vibefpmgui.lsp.LspClient`,
185becomes a link here.
186
187MIT License. The fpm logo is © 2020 fpm contributors (MIT License). The
188Fortran file icon is adapted from [vscode-icons](https://github.com/vscode-icons/vscode-icons)
189(MIT License).
190"""
191
192__version__ = "0.0.7"
193__docformat__ = "google"  # docstrings: Markdown with Google-style sections (for pdoc)