Code Review Guide

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.
• Auto re-order markets applies current Spansh inversion hints only. It swaps each recommended same-body market inversion pair once and does not run the old broad site sorter.

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.
• Confirm Auto re-order markets is disabled when no inversion hints exist, and that pressing it preserves the cut line while swapping only the hinted pairs.

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
• src/economy/economy-documented.ts
• src/economy/economy-model2.ts

Important behavior:

• Fixed non-agriculture specialized ports do not run the full colony applyBodyType path.
• Fixed non-agriculture specialized ports can receive a post-link BIO agriculture buff only after agriculture exists from links.
• That same post-link fixed-port BIO rule adds the observed +0.4 terraforming marker when terraforming is otherwise absent.
• Agriculture strong-link TIDAL penalties include explicit non-BIO tidal body features as well as bodies tidal to a star.
• Tidal orbital cluster colony ports use a narrower agriculture weak-link budget: 0.65, or 0.55 when same-body agriculture strong links are present.

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.
• Confirm fixed-port post-link BIO logic does not give agriculture/terraforming to fixed ports that never received agriculture from links.
• Confirm BIO + tidal bodies that previously matched are not penalized by the explicit tidal strong-link rule.

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.
• The Auto re-order markets action consumes the same derived inversion hints and swaps each unique recommended pair once.

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.
• Confirm automatic market reordering is still UI/order state only and does not persist inversion metadata.

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, market-inversion auto reorder, 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, especially the fixed-port BIO and tidal agriculture weak-link exceptions.
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.
• When inversion arrows are visible, press Auto re-order markets and confirm only those recommended market pairs swap.
• After correcting HIP 52675 market inversions, confirm agriculture estimates match for Barron Town, Christy Beacon, and Si-myung Legacy.
• 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.