François
90502c0762
UI restructuring:
- Dashboard (`screen_dashboard.cpp`, `screen_idx = 6`) is the new home
screen at boot. Reads Overview / Health / Analysis / Modules from
the current System every frame; per-module rows list parts grouped
by `connector_type` and a Power/Gnd inference summary (yellow when
any name-Power signal is refuted). Scrollable via PgUp/PgDn/Home/End.
Letter shortcuts: `c`=console, `s`=search, `p`=plug (alias of
connect), `t`=set-type, `e`=explore, `n`=net, `a`=analyze, `q`=quit.
- Global Ctrl-P palette (`screen_palette.cpp`) — fuzzy-finds over
registered commands + module / signal names. Activation runs the
bare command or jumps to the matching screen with state seeded.
- Unified analyze screen (`screen_analyze.cpp`, `screen_idx = 7`):
tabbed layout (`Issues / Groups / Types`), Tab or ←→ to switch
tabs, ↑/↓ to navigate the focused list. Replaces the previous
shell-bouncing `[v]erify` shortcut — `verify` content is now in
the Issues tab. Types tab attaches the decision rationale to each
signal row (fan-out / voltage / hard floor).
- Context help panel: `RenderHelpPanel(title, entries)` in
`tui_helpers.{hpp,cpp}` rendered on the right of every screen.
- Console (former "log") rename: screen 0 is `[c]onsole` in the UI
and "console" in its help-panel title. The underlying screen and
the shell prompt are unchanged.
- Esc from any non-home screen returns to the dashboard. The
dashboard itself swallows Esc; quit via `q` / the `quit` command.
`quit` now calls `screen_ptr->Exit()` directly so it works from
any screen including via the palette.
Signal type inference:
- `Signal::type` defaults to `Other` — auto-inference no longer
happens at construction.
- `infer_signal_types(System*)` is called at the end of every load.
Three rules: GndShield from name alone; Power requires name match
+ a hard fan-out floor (< 3 pins = always Other, regardless of
name or voltage) + at least one positive structural signal
(fan-out ≥ 4 OR voltage pattern in the name like `3V3`, `5V`).
- Thresholds exposed in `analysis.hpp` (`POWER_FANOUT_HARD_FLOOR`,
`POWER_FANOUT_CONFIRM_MIN`, `has_voltage_pattern`) so the analyze
screen can render the same rationale without duplicating logic.
- `set-signal-type` still wins; save/restore round-trips the type.
Analysis groups & anomalies:
- New `GroupKind::DiffBus` — ≥ 2 diff pairs sharing the same
outer-stem with consecutive integer indices are aggregated into a
single bus (`MDI[0..3]_P/N`). `MDI0` and `PCIE_TX_0` index forms
both accepted. Solo pairs under a bus-able stem fall back to
`DiffPair`.
- New `AnomalyKind::DiffBusGap` for missing lanes.
Documentation:
- `DESIGN.md`: dedicated "Categorization rules (normative)" section
consolidating signal type, NC origin, signal groups, anomalies,
component kind, and connector wiring rules with exact thresholds
and decision order.
- `doc/user/analysis.md` (new): user-facing version of the same
rules in plain language. Linked from `doc/user/index.md`.
Tests: +6 new cases (62 total). Adjusted `test_persist.cpp` to set
the signal type explicitly in the fixture (no more auto-inference).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
essim documentation
Auto-generated API reference and high-level design notes for the essim system digital twin.
Layout
user/— user-facing docs (hand-written intro/tutorial- auto-generated command reference). Start at
user/index.md.
- auto-generated command reference). Start at
api/— developer-facing API reference (Doxygen XML → custom Markdown emitter). Browse classes and files directly in gitea's Markdown renderer. Top page:api/index.md.../DESIGN.md— implementation notes: domain conventions, TUI flow, gotchas. Hand-maintained.classes.puml— PlantUML class diagram for the domain model. Render withplantuml classes.pumlfor a PNG/SVG.Doxyfile.in/gen_api_md.py— the toolchain (templated Doxygen config + custom XML→Markdown emitter).
Regenerating the API reference
The Markdown tree under doc/api/ is committed so it's readable directly
on gitea. After substantive code changes, regenerate it:
# 1. Tooling (once): Doxygen, plus a Python 3 interpreter (already on Arch).
pacman -S doxygen
# 2. Configure once (or after editing doc/Doxyfile.in):
cmake -S . -B build
# 3. Regenerate:
cmake --build build --target doc
# 4. Review and commit the updated doc/api/ tree:
git add doc/api/
git status doc/api/
Pipeline:
src/**/*.{hpp,cpp} ──┐
README.md ─┼─► doxygen ─► build/doc/xml/ ─► gen_api_md.py ─► doc/api/
DESIGN.md ─┘ (Doxyfile.in)
(built essim) ────────► essim --commands-md ──────────────────────────► doc/user/commands.md
doc/user/index.md and doc/user/scripting.md are hand-written; only
doc/user/commands.md is regenerated. The doc target depends on the
essim binary so a stale build is rebuilt before the dump is taken.
If either Doxygen or Python 3 is missing at CMake-configure time the
doc target is silently disabled (the regular build still works) and a
status line is emitted in the CMake log telling you which one to install.
Why a custom emitter rather than doxybook2 / moxygen
doxybook2is not packaged in Arch / AUR and gets stale upstream.moxygendrags Node into a pure-C++ project.- The emitter is one Python file (
gen_api_md.py, ~330 lines) with zero external dependencies — easy to read, easy to tweak, robust to Doxygen version changes (the XML schema is stable).
Tailor the output by editing gen_api_md.py directly: add columns to
the class table, change the source-link format, group sections
differently, etc.
Comment style
The codebase uses standard Doxygen markers:
///for single-line briefs./** … */for multi-line blocks.@param,@return,@brief(or@short) tags inside blocks.@throwsfor exceptions a function may raise.
JAVADOC_AUTOBRIEF = YES is set so the first sentence of a multi-line
comment counts as the brief description without needing an explicit
@brief tag.