General source code refactoring
This commit is contained in:
184
docs/refactoring.md
Normal file
184
docs/refactoring.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# Incremental Refactoring Record
|
||||
|
||||
## Stage 1: Characterization Baseline
|
||||
|
||||
Stage 1 initially added tests and documentation only, before any runtime extraction.
|
||||
The following records that historical baseline. The completed integration and
|
||||
remaining verification gaps are recorded under "Completed Extraction Stages" below.
|
||||
|
||||
### Coverage Added
|
||||
|
||||
`tests/characterization.test.cjs` contains 22 test cases using Node's built-in
|
||||
test runner, assert and vm. `tests/support/characterization.cjs` provides isolated
|
||||
fixtures: no real browser cookies, account identifiers, tokens or network access.
|
||||
Unexpected fetches reject rather than falling through to global fetch.
|
||||
|
||||
- Exact current manifests and source/output equality, with classic-script syntax validation.
|
||||
- Disallowed-origin initialization and reinjection when the tile already exists.
|
||||
- Fiscal boundaries, leap years, rolling quarters and unsupported RENEWALS.
|
||||
- Full opportunity query payload, pagination offsets/counts and stale request versions.
|
||||
- Filter storage round-trip, WON_PENDING, search, numeric sort, reference reset and malformed preferences.
|
||||
- Missing-cookie tokenrelay recovery and existing 400/401/403 retry limit.
|
||||
- Chrome callback and Firefox promise mocks for background dispatch, storage, cookies and tabs.
|
||||
- Product pagination, default/custom TTL, concurrency limit, in-flight sharing and partial errors.
|
||||
- Persisted product reads after recreating the background context; storage failures and stalled pages.
|
||||
- XSRF discovery, recovery timeout, successful recovery and temporary-tab cleanup.
|
||||
- SPA credential selection, account payloads, encoded identifiers and debug envelopes.
|
||||
- Invalid messages, network errors, HTTP 401 and HTTP 200 invalid JSON in consumption.
|
||||
|
||||
Existing suites remain intact: consumption normalization/requests, consumer-session
|
||||
recovery, AI summary rendering/state, scoped token reuse/expiry and bounded retry.
|
||||
Tests for the current security defects are deliberately not encoded as acceptable
|
||||
behavior. They belong to separately approved fixes.
|
||||
|
||||
### Former Temporary Test Seam
|
||||
|
||||
The original content IIFE had no exports, so baseline tests initially exposed
|
||||
functions before initialization with a guarded source marker. That temporary
|
||||
mechanism is now removed. Tests use the actual application factories through
|
||||
`tests/support/application.cjs`, without replacing source strings. Background
|
||||
integration tests still execute the production listener and asynchronous replies.
|
||||
|
||||
### Running Checks
|
||||
|
||||
```sh
|
||||
npm test
|
||||
npm run check
|
||||
```
|
||||
|
||||
Without npm, use the Node commands in package.json individually. The new suite is:
|
||||
|
||||
```sh
|
||||
node tests/characterization.test.cjs
|
||||
```
|
||||
|
||||
At baseline, `build.mjs --check` did not compare output contents. It now checks
|
||||
both generated manifests and both scripts byte-for-byte against composition.
|
||||
Characterization tests retain the exact manifest expectations.
|
||||
|
||||
Stage-1 verification on Node.js v24.19.0:
|
||||
|
||||
| Command | Result |
|
||||
| --- | --- |
|
||||
| `node --check src/content.js` and `node --check src/background.js` | Passed |
|
||||
| `node --check tests/support/characterization.cjs` | Passed |
|
||||
| `node tests/consumptionTrend.test.cjs` | Passed |
|
||||
| `node tests/consumerTokenSessionRetry.test.cjs` | Passed |
|
||||
| `node tests/aiSummary.test.cjs` | Passed |
|
||||
| `node tests/characterization.test.cjs` | 22 passed, 0 failed |
|
||||
| `node scripts/build.mjs --check` | Passed; distribution equivalence also checked by the suite |
|
||||
| `git diff --check` | Passed |
|
||||
|
||||
The individual commands from the npm scripts were executed directly. No build
|
||||
regeneration was needed because runtime sources and the build were unchanged;
|
||||
`git diff -- src dist scripts/build.mjs` was empty.
|
||||
|
||||
### Verification Limits
|
||||
|
||||
- API mocks are not proof of Chrome/Edge/Firefox compatibility or real authentication.
|
||||
- Recreating a VM tests cache rehydration, not actual service-worker suspension or job recovery.
|
||||
- DOM mocks do not prove layout, focus, accessibility or SPA lifecycle correctness.
|
||||
- The original visual fixture used eval. The completed extraction removed it and
|
||||
serves the composed factory through a normal local script instead.
|
||||
- No installed-browser smoke test or live Fusion request was performed in stage 1.
|
||||
- No JavaScript export/generator feature was located. Do not create a generators
|
||||
directory until its actual source and standalone-output contracts are identified.
|
||||
|
||||
## Separate Security and Reliability Backlog
|
||||
|
||||
These are preexisting observations, not authorized functional changes in this refactor.
|
||||
|
||||
| Issue | Evidence/impact | Separate change to evaluate |
|
||||
| --- | --- | --- |
|
||||
| Debug redaction after truncation | Invalid/truncated JSON is returned unmasked by formatDebugBody; reproduced with a synthetic token | Redact before truncation, fail closed on malformed bodies, test all response shapes |
|
||||
| Debug secrets and shared DOM | Raw headers/bodies are retained for the reveal control; revealed text is in page DOM | Review retention, safe diagnostic schema and whether revealing credentials remains acceptable |
|
||||
| Cookie store selection | Lookup scans all stores instead of binding to sender account/container | Scope selection to the requesting context and test multi-account behavior |
|
||||
| Product cache isolation | Cache and in-flight keys use OptyNumber only | Design identity partitioning and explicit cache migration/retention policy |
|
||||
| Privileged message validation | No explicit sender identity/origin check; supplied header names are accepted | Validate senders/messages and allowlist headers without introducing an arbitrary proxy |
|
||||
| Session tab retry | Opening failures retry indefinitely; interruption can strand work | Decide cancellation/limits and worker lifecycle recovery explicitly |
|
||||
| DOM lifecycle | Observer can remain active; guards do not cover every reinjection/resize path | Define ownership/disposal and characterize navigation before changing behavior |
|
||||
| Token expiry | General/SPA tokens have policies different from Sales Common | Review independently; do not unify policies as part of extraction |
|
||||
|
||||
Never include real secrets in repro cases, snapshots, documentation or test output.
|
||||
Do not add persistent token storage to compensate for worker termination.
|
||||
|
||||
## Completed Extraction Stages
|
||||
|
||||
All modules listed below are integrated through `scripts/sources.cjs` and the
|
||||
two composition roots. Former `src/content.js` and `src/background.js` were removed;
|
||||
their names remain only for the generated distribution scripts. No version change,
|
||||
commit, publication, runtime dependency, permission expansion or CSP change occurred.
|
||||
|
||||
| Stage/responsibility | Files/boundaries | Preserved contracts and evidence | Remaining risk/next safe step |
|
||||
| --- | --- | --- | --- |
|
||||
| Build and pure logic | `scripts/compose.cjs`, `sources.cjs`; fiscal-periods, formatters, consumption model | Classic IIFEs, exact manifests, dates, payload/normalization tests; syntax checked per source and composed bundle | Native browser package loading still needs a smoke test |
|
||||
| Platform and dispatch | `platform/`, `background/main.js`, `messages.js`, `shared/messages.js` | Sync listener registration, callback/promise mocks, async responses, sender-frame progress and unknown-message behavior | Sender validation is a separate security change |
|
||||
| Auth and HTTP operations | `auth/`, `services/` | Credential selection, scoped-token reuse/expiry, 401/403 retry, missing-cookie and HTML-session recovery, request/debug envelopes | Real SSO and worker suspension not simulated completely |
|
||||
| Products | `features/products/` | Four-worker queue, pagination, TTL, cache restore, in-flight sharing, partial errors and expansion behavior | Existing identity/cache-retention policy unchanged |
|
||||
| Content features | opportunities, preferences, AI-summary, consumption and debug factories/state | Filter/search storage round-trip, sorting, stale requests, AI safe text, plan/period controls, preserved labels and DOM | Existing DOM lifecycle and narrow-screen limitations remain |
|
||||
| Bootstrap, CSS and documentation | `content/main.js`, `background/main.js`, application roots, styles; README/docs | CSS byte-identical to original (hash test); factories connected, no orphan sources or peer-factory dependencies; old marker/eval fixture removed | Native browser matrix below remains pending |
|
||||
|
||||
The automated suites were run after the initial extraction and again after the
|
||||
platform/auth refinements, cleanup and final composition. Intermediate verification
|
||||
found and corrected test-harness expectations for source inventory and fixture
|
||||
callback messaging; no production auth, cookie or session policy was changed.
|
||||
|
||||
### Final Automated Verification
|
||||
|
||||
Executed with Node.js 24.19.0, directly through the package-script equivalents:
|
||||
|
||||
| Command | Result |
|
||||
| --- | --- |
|
||||
| `node scripts/build.mjs` | Both packages regenerated; all source/composed JavaScript syntax valid |
|
||||
| `node scripts/test.cjs` | All five suite files passed: AI, architecture (6 cases), characterization (22 cases), session recovery, consumption |
|
||||
| `node scripts/build.mjs --check` | Generated scripts/manifests match source composition |
|
||||
| `git diff --check` | No whitespace errors |
|
||||
|
||||
There is no configured linter. Syntax validation uses Node's JavaScript parser
|
||||
through vm.Script, not eval or new Function in the extension. No generators feature
|
||||
was located; standalone JavaScript generation therefore has no feature-specific
|
||||
snapshot to assert. The architectural suite verifies deterministic composition,
|
||||
source coverage, dependency injection, independent per-frame state and lazy
|
||||
localStorage failure handling. Feature suites use synthetic credentials only.
|
||||
|
||||
### UI Smoke Verification
|
||||
|
||||
The loopback fixture was exercised in the Codex in-app browser, using the same
|
||||
composed content factories with injected synthetic runtime/fetch/storage adapters.
|
||||
It is not an installed extension and does not validate privileged browser APIs.
|
||||
|
||||
- Paginated synthetic opportunities, product progress/counts and dashboard rendered.
|
||||
- Search text/filter remained after closing and reopening the modal.
|
||||
- Light/dark toggle and product expansion retained the existing presentation.
|
||||
- AI text, including literal HTML delimiters, appeared as text above the product table.
|
||||
- Preferences retained checkbox/cache-duration selections after Save and reopen.
|
||||
- Cloud Consumption opened with plan tabs; weekly default, daily switch, alternate
|
||||
plan and series visibility toggles worked. Debug listed scoped relay and AI calls.
|
||||
- Screenshots inspected at 1920x1080, 1280x720 and 390x844. Desktop columns rendered
|
||||
with complete Last Update Date and WON_PENDING. Existing compact-table scrolling
|
||||
and clipping at 1280 remain unchanged; mobile controls stack. This is not a full
|
||||
mobile workflow/accessibility audit and no layout redesign was included.
|
||||
- No console errors were reported during the exercised flows.
|
||||
|
||||
### Outstanding Native Browser Matrix
|
||||
|
||||
| Target | Package/runtime | Status |
|
||||
| --- | --- | --- |
|
||||
| Chrome | `dist/chromium`, MV3 service worker | Not run as an installed extension |
|
||||
| Edge | `dist/chromium`, MV3 service worker | Not run as an installed extension |
|
||||
| Firefox | `dist/firefox`, MV3 background scripts | Not run as an installed extension |
|
||||
|
||||
The available automation connection exposed the in-app browser and a Brave
|
||||
profile, not Chrome, Edge or Firefox. No live Fusion requests, user-session access
|
||||
or extension installation were used to substitute for the missing native tests.
|
||||
Actual suspension/reactivation, container routing and SSO remain unverified.
|
||||
|
||||
The next safe validation is to load the generated packages in an authorized test
|
||||
profile in each target browser, then exercise tile insertion, modal reopen,
|
||||
filters/preferences, products, AI, consumption, debug and background restart.
|
||||
Resolve the separately listed security issues only in explicitly approved changes.
|
||||
|
||||
See [the native browser checklist and execution record](browser-smoke.md) for the
|
||||
2026-09-17 follow-up. Local tests and output checks passed again; Chrome/Edge were
|
||||
installed but not connected to automation. Native verification remains pending
|
||||
while the user connects those browsers.
|
||||
Reference in New Issue
Block a user