refactor: resolve Mirabel64 Stellar Wave issues #483, #484, #485, #486

[Mirabel64]

PR — Resolve Mirabel64 Stellar Wave issues (#483, #484, #485, #486)

Closes #483
Closes #484
Closes #485
Close #486
— all open issues assigned to @Mirabel64 in the Stellar Wave Program (6th wave). Bundled into a single PR per the wave's "one PR per assignee" convention.

Summary

Four production-safety and code-health issues filed by the code-review sweep:

• refactor: consolidate logger usage #486 (refactor) — Consolidate logger usage. Three offenders (ViewToggle, TransactionDetailsModal, earlyErrorSuppression) used console.* directly, and ~5 components imported the deprecated @/utils/structuredLogger singleton rather than the canonical @/utils/logger.
• perf: next.config.ts build statistics plugin runs unconditionally #485/perf: next.config.ts build statistics plugin runs unconditionally #484 (perf, duplicate issues) — next.config.ts BuildStatsPlugin needed explicit production gating in addition to the ANALYZE=true opt-in.
• refactor: split large referralStore into focused slices #483 (refactor) — 350-line referralStore.ts mixed referralLinks, stats, leaderboard, notifications, settings, and the underlying Zustand store in one file.

This PR resolves all four with a coordinated set of changes that keeps existing consumer imports working.

Changes

#486 — Logger consolidation (@/utils/logger is canonical)

• Documented canonical logger in README.md § "Logging", including the migration message, the @/utils/structuredLogger deprecation, and the intentional raw-console exemption in earlyErrorSuppression.ts.
• Marked src/utils/structuredLogger.ts @deprecated with JSDoc pointing new code to @/utils/logger. The wrapper keeps re-exporting the canonical symbols, plus its domain-specific StructuredLogger class (with batching / remote-send) and logNetworkRequest / logWeb3Activity / logTransaction helpers, so existing callers compile unchanged.
• Migrated console.* to logger.* in:
  • src/components/ViewToggle.tsx (4 console.warn/error → logger.warn/error)
  • src/components/TransactionDetailsModal.tsx (1 console.error → logger.error with the error object)
  • src/utils/errorHandlingTest.ts (all console.log → logger.info)
• Migrated @/utils/structuredLogger callers to canonical @/utils/logger, including translation of structured-call signatures:
  • src/utils/errorMonitoringService.ts (trackError(err, ctx) → logger.errorWithStack(err.message, err, ctx); inline info({metadata: {...}}) flattened to info({...}))
  • src/components/error/GlobalErrorBoundary.tsx (structuredLogger.error(msg, err, {component, action, metadata}) → logger.errorWithStack(msg, err, {component, action, ...metadata}); warn/info similar)
  • src/components/LanguageSwitcher.tsx (structuredLogger.component(name, action, ...) → logger.info(\Component: ${name} - ${action}`, {component, action})`)
  • src/app/page.tsx (structuredLogger.info(msg, {component, action, metadata}) → logger.info(msg, {component, action, ...metadata}))
• Annotated src/utils/earlyErrorSuppression.ts with a header comment explaining why it intentionally uses raw console.* (intercepts browser-extension noise that fires before the structured logger initialises). Exempt from no-console via ESLint flat config.
• ESLint enforcement (eslint.config.mjs):
  • no-restricted-imports rejects @/utils/structuredLogger paths/patterns with a clear migration message.
  • no-console: 'error' denies direct console.* calls everywhere except the three logger-wrapper files (logger.ts, structuredLogger.ts, earlyErrorSuppression.ts) and test/story files in __tests__/, *.test.*, *.stories.*.

#485 / #484 — Build stats plugin gating (next.config.ts)

The plugin was already gated by isAnalyzeEnabled && !isServer. Added an explicit production guard:

const isProd = process.env.NODE_ENV === "production";
…
if (isAnalyzeEnabled && !isServer && !isProd) {
  class BuildStatsPlugin { /* … */ }
}

Production CI must not pass ANALYZE=true; if it does, the plugin is still disabled by the NODE_ENV === 'production' guard. Documented in README.md § "Build stats plugin".

#483 — Split referralStore.ts into focused slices

New layout:

src/store/
├── referralStore.ts            # thin back-compat re-export layer
└── referral/
    ├── store.ts                # source of truth — useReferralStore + actions
    ├── referralLinks.ts        # useReferralLinks
    ├── referralStats.ts        # useReferralStats, useRecentRewards
    ├── leaderboard.ts          # useLeaderboard (canonical) + useLeaderboardCache (alias)
    ├── referralNotifications.ts # useReferralNotification, useReferralLoading, useReferralError
    ├── misc.ts                 # useCurrentReferralCampaign, useReferralTermsAccepted
    └── index.ts                # barrel for new code

• useReferralStore (the create+persist source of truth with all actions) now lives in src/store/referral/store.ts.
• src/store/referralStore.ts is now a thin backwards-compat re-export layer (marked @deprecated in JSDoc) that re-exports useReferralStore and all 9 selector hooks, so existing consumers (and tests, e.g. ReferralLeaderboard.test.tsx's jest.mock('@/store/referralStore', …)) continue to compile unchanged.
• Slice files import useReferralStore from ./referral/store (not the back-compat layer) to avoid a circular import.
• programSettings: any tightened to ReferralProgramSettings = Record<string, unknown> | null, which is compatible with the persist partialize logic and is more useful for downstream narrowing.
• Initial state is now typed via Pick<ReferralStoreState, …> to prevent [] literals widening to never[].

Acceptance criteria status

#486

• Single canonical logger documented in README.

• Codemod or ESLint rule applied to migrate remaining files (manual migration + ESLint enforcement in place).

• No references to the deprecated module remain outside the wrapper.

  Verified: zero remaining imports of @/utils/structuredLogger outside src/utils/structuredLogger.ts itself and src/utils/__tests__/structuredLogger.test.ts (which tests the wrapper contract).

#485 / #484

• Plugin gated by environment flag (ANALYZE=true AND !isProd).
• Build logs are quiet without ANALYZE.
• Documented the new behavior in README § "Build stats plugin".

#483

• Focused slices (useReferralLinks, useReferralStats, useLeaderboard, useReferralNotifications) live under @/store/referral/<slice>.
• Backwards-compatible re-exports preserved; existing consumers and tests unchanged.

Out-of-scope observations (not addressed in this PR)

These are surfaced for visibility but intentionally not fixed here to keep the diff focused on the wave's assigned issues:

• src/stories/ReferralLinksCard.stories.tsx calls useReferralStore.setState({ referralLinks: links }), but the store key is currentReferralLinks. The Empty, WithLinks, OverflowLinks decorators are therefore no-ops. Pre-existing bug — please file a separate issue.
• Many other pre-existing console.* usages remain in the codebase (src/hooks/useAxeAudit.ts, src/lib/requireEnv.ts, src/store/debug.ts, several src/utils/security/ files, etc.). These are now flagged by the new no-console rule; they are NOT directly mentioned by refactor: consolidate logger usage #486's "notable offenders" list. A follow-up PR should migrate them.

Validation

• pnpm typecheck (TypeScript) — no new errors caused by this PR. Pre-existing syntax errors in src/components/TransactionConfirmation.tsx, src/components/TransactionProgress.tsx, src/components/WalletModal.tsx, JSON locale files, src/store/comparisonStore.ts, and src/stories/ResponsiveContainerExample.stories.ts are unrelated.
• pnpm lint — pre-existing violations in unrelated files remain (@storybook/react imports, missing react/display-name rule, etc.). No new violations introduced by files modified in this PR.

Files changed

README.md                                                (modified)
eslint.config.mjs                                        (modified)
next.config.ts                                           (modified)
src/components/LanguageSwitcher.tsx                      (modified)
src/components/TransactionDetailsModal.tsx               (modified)
src/components/ViewToggle.tsx                            (modified)
src/components/error/GlobalErrorBoundary.tsx             (modified)
src/app/page.tsx                                         (modified)
src/store/referralStore.ts                               (rewritten as back-compat layer)
src/store/referral/store.ts                              (new — source of truth)
src/store/referral/referralLinks.ts                      (new)
src/store/referral/referralStats.ts                      (new)
src/store/referral/leaderboard.ts                        (new)
src/store/referral/referralNotifications.ts             (new)
src/store/referral/misc.ts                               (new)
src/store/referral/index.ts                              (new)
src/utils/earlyErrorSuppression.ts                       (modified — header comment)
src/utils/errorHandlingTest.ts                           (modified)
src/utils/errorMonitoringService.ts                      (modified)
src/utils/structuredLogger.ts                            (modified — JSDoc @deprecated)

Linked issues

• Closes refactor: split large referralStore into focused slices #483, perf: next.config.ts build statistics plugin runs unconditionally #485, refactor: consolidate logger usage #486.
• Closes perf: next.config.ts build statistics plugin runs unconditionally #484 (exact duplicate of perf: next.config.ts build statistics plugin runs unconditionally #485 — same fix closes both).

---

🤖 Generated with Codebuff via the Stellar Wave Program.

[drips-wave]

@Mirabel64 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[nanaf6203-bit]

Solid Stellar Wave refactor — taking care of #483–#486 in one clean sweep 🚀