Skip to content

Code Review Guide

Jump to bottom
Fenris159 edited this page Jun 13, 2026 · 10 revisions

Code Review Guide

This guide is for reviewing the current RavenColonialWeb economy/SystemView changes. It is organized by risk area so reviewers can separate model behavior from UI-only diagnostics.

1. Start With The Model Boundaries

Recommended files:

  • src/economy/system-model2.ts
  • src/economy/economy-model2.ts
  • src/economy/economy-core.ts
  • src/economy/economy-documented.ts
  • src/economy/README.md

Review focus:

  • buildSystemModel2 remains the source of truth for calculated system output.
  • React views should render model output, not duplicate economy or tier-point rules.
  • system.sites[0] is still the only persisted system primary-port source. No new backend field should be required.

2. Review Primary Port And Body Primary Behavior

Recommended files:

  • src/economy/system-model2.ts
  • src/views/SystemView2/BuildOrder.tsx
  • src/views/SystemView2/SystemView2.tsx

Important behavior:

  • System primary port is inferred from system.sites[0].
  • buildSystemModel2 copies that into sysMap.primaryPortId for runtime use.
  • Saving the Order panel persists the reordered IDs back to system.sites.
  • Moving a different site into row 1 and saving should make that site the system primary after reload.
  • Body market-link primaries are inferred by the model from body site order, eligible type, tier, and calculation inclusion.

Review focus:

  • Confirm no new primaryPortId schema value is saved to the backend.
  • Confirm sites[0] survives load, reorder, save, and reload as the primary-port source.
  • Confirm same-body custom ordering is preserved within computed primary-rank groups.
  • Confirm market ID is not used as the within-body ordering fallback in the Order panel.

3. Review Order For Calculations Grouping

Recommended files:

  • src/views/SystemView2/BuildOrder.tsx
  • src/views/SystemView2/SystemView2.tsx
  • src/economy/system-model2.ts

Important behavior:

  • The Order panel groups rows by body for accessibility.
  • The system primary port remains first when it is present in the relevant section.
  • Sites below the cut line remain below the cut line.
  • Completed sites only puts only completed sites above the cut line.
  • Use all Sites puts non-planned sites first, then planned sites, while keeping grouping inside each section.
  • Build/in-progress sites do not appear above the cut line in completed-only mode, but they appear before planned sites in the table.

Review focus:

  • Confirm initial panel load mirrors the current main SystemView completed/all-sites toggle.
  • Confirm clicking the panel Completed sites only and Use all Sites buttons updates the same useIncomplete state as the main toolbar toggle.
  • Confirm pressing Okay rebuilds using the mode selected inside the panel.
  • Confirm planned sites are not interleaved above completed/building sites when all sites are included.

4. Review Tier Point Tax Calculation

Recommended file:

  • src/economy/system-model2.ts

Important behavior:

  • Tier-point totals now use a canonical tax order so UI row grouping does not change math.
  • Taxed starports are ordered by site tier descending, then body order, orbital before surface, market ID, then name/id fallback.
  • The actual tax percentage still uses site.type.tier, matching the deployed live behavior.
  • HIP 52675 should match the live deployed reference of Tier 2 = 0, Tier 3 = +12.

Review focus:

  • Confirm reordering rows for display does not change tierPoints.
  • Confirm calcNeeds is cleared and rebuilt every calculation pass.
  • Confirm completed-only vs all-sites still respects calcIds and build/plan status.
  • Confirm red insufficient-points warnings in the Order panel appear only for planned sites, not completed/building sites.

5. Review System Development Buff/Nerf

Recommended files:

  • src/economy/system-model2.ts
  • src/views/SystemView2/SystemStats.tsx
  • src/components/ModalCommander.tsx
  • src/views/ProjectView/ProjectView.tsx

Important behavior:

  • The public System Stats checkbox and experimental wording were removed.
  • Buff/nerf is treated as normal system development model behavior.
  • The commander settings checkbox remains as a developer/testing override.
  • The UI label is Apply system development buff/nerf model.
  • The testing override should normally remain enabled.
  • The initial buff is tied to sysMap.primaryPortId, which is derived from system.sites[0], not the first visible/included row.

Review focus:

  • Confirm disabling the commander testing override is only useful for comparing the old pre-balance model.
  • Confirm ProjectView interprets noBuffNerf consistently.
  • Confirm the initial starport buff follows a saved primary-port reorder after reload.
  • Confirm no backend schema change was added for this behavior.

6. Review Economy Link Graph And Per-Site Economy Pipeline

Recommended files:

  • src/economy/system-model2.ts
  • src/economy/economy-model2.ts
  • src/economy/economy-core.ts
  • src/economy/economy-documented.ts
  • src/economy/economy-link-sources.ts
  • src/economy/economy-weak-links.ts

Important behavior:

  • Body primaries, subordinate links, strong sources, weak sources, and same-body weak sources are modeled before economy calculation.
  • Economy-source sites are pre-calculated when needed so primaryEconomy is available.
  • Economy calculation state prevents cyclic pre-calculation noise.
  • The stabilization pass keeps initial render output aligned with manual recalculation.

Review focus:

  • Confirm calcIds is respected for complete-only vs all-sites mode.
  • Confirm link pools are assigned before dependent economies are calculated.
  • Confirm strong/weak links do not double-count sources.
  • Confirm body primary changes caused by custom same-body order produce expected market-link primaries.

7. Review Agriculture And Facility-Specific Rules

Recommended files:

  • src/economy/economy-ag-modifiers.ts
  • src/economy/economy-ag-heuristics.ts
  • src/economy/economy-facility-registry.ts
  • src/economy/economy-facilities.ts

Review focus:

  • Confirm agriculture-specific exceptions remain isolated.
  • Confirm terraformable agriculture is controlled by enableTerraformableAgricultureBonus.
  • Confirm hub/installation registry classifications match intended link-only, fixed-intrinsic, and special-case behavior.
  • Confirm facility rows do not accidentally create market economies when they should only act as link sources.

8. Review Spansh Compare And Inversion Hints

Recommended files:

  • src/economy/compare/spansh-economy-resolve.ts
  • src/economy/compare/spansh-compare-reliability.ts
  • src/economy/compare/spansh-inversion-detect.ts
  • src/views/SystemView2/AuditTestWholeSystem.tsx
  • src/views/SystemView2/BuildOrder.tsx
  • src/views/SystemView2/EconomyTable2.tsx

Important behavior:

  • Spansh compare remains UI-only and must not feed back into buildSystemModel2.
  • Same-body inversion hints are derived from current audit data and are not persisted.
  • Exact swapped economy matches get highest confidence.
  • Strong stale-data hints require a large swapped-match improvement and can use market-link-primary economy-count evidence.
  • The Order panel shows up/down hint icons after existing row icons, with hover reasons.

Review focus:

  • Confirm inversion hints disappear after the current model/data no longer indicates inversion.
  • Confirm excluded or informational Spansh rows do not create hard inversion warnings.
  • Confirm hover text names the swap partner and explains exact or strong confidence.
  • Confirm no backend field stores inversion state.

9. Review UI Icons And Row Signals

Recommended file:

  • src/views/SystemView2/BuildOrder.tsx

Important behavior:

  • Primary port icon still appears on row 1.
  • Primary market-link icon appears for body orbital/surface primary sites.
  • Planned/building/demolished icons still appear after the site description.
  • Spansh inversion arrows appear after existing row icons.

Review focus:

  • Confirm icons fit the row height and do not overlap row text.
  • Confirm hover/title text is useful and not misleading.
  • Confirm cutoff rows and greyed-out rows still render legibly.

10. Suggested Review Order

  1. Review system-model2.ts primary-port, tier-point, system-effect, and link-graph changes.
  2. Review BuildOrder.tsx grouping, mode mirroring, icon rendering, and saved-order preservation.
  3. Review Spansh inversion detection as UI-only derived state.
  4. Review SystemView and commander setting changes for buff/nerf behavior.
  5. Review economy rule modules only after the ordering/model invariants are clear.
  6. Review tests and docs last.

11. Suggested Test Plan

Tracked repo checks:

npm run test:economy
npm run build
git diff --check

Expected notes:

  • npm run build may print the existing CRA/Node fs.F_OK deprecation warning.
  • On Windows, git diff --check may print LF-to-CRLF notices for touched files while still exiting successfully.

12. High-Value Manual Smoke Checks

  • Open HIP 52675 and confirm tier points match the live reference: Tier 2 = 0, Tier 3 = +12.
  • Open Order for Calculations in completed-only mode and confirm only completed sites are above the cut line.
  • Switch to Use all Sites and confirm building sites appear before planned sites, with planned sites grouped last.
  • Reorder same-body market-link candidates, save, reload, and confirm the inferred primary market link follows the saved order.
  • Run whole-system Spansh compare and confirm possible inversion arrows show only as derived hints.
  • Hover an inversion arrow and confirm the reason names the partner and confidence.
  • Confirm System Stats no longer shows the old experimental buff/nerf checkbox.
  • In commander settings, confirm the buff/nerf checkbox reads as a developer/testing override.

Clone this wiki locally