#Project Quality Improvement Roadmap

Last audited: 2026-09-26

Baseline commit: 05f1ad8

Roadmap mode: quality-first, exit-criteria driven

This is the canonical engineering-quality backlog for the repository. Product capability detail remains in the capability matrices and parity audit; this document owns cross-cutting quality priorities, measurable exit criteria, and the order in which the work should be undertaken.

The roadmap is a living document. A completed item must link to its tests or CI evidence, update affected contracts and user documentation, and record the date on which its acceptance criteria were verified.

#Status and priority model

Work is ordered by exit criteria rather than dates. New functionality may be developed in parallel only when its affected subsystem already meets the P0 quality gates below.

#Audited baseline

The following measurements were collected from the baseline commit on 2026-08-31, before the Web Editor was retired on 2026-09-26. API/web entries are historical measurements, not current products or gates. The extended-lint row reflects the current frozen ratchet after that retirement; the remaining static/test rows are the pre-retirement snapshot and are refreshed when the baseline changes.

The global coverage average hides uneven risk. Parser and dialect code is near 87–89% line coverage, while migration is about 27%, activation 41%, views 49%, commands 59%, imports 58%, and exports 64%. The largest non-generated modules also concentrate orchestration and UI state: Result Panel bootstrap and host view code exceed 3,000 lines, while schema, metadata prefetch, filters, and grid construction exceed 2,000 lines.

At the baseline, the dependency check protected seven configured layers. The current desktop-only graph retains five layers: contracts, shared packages, desktop extension, webviews, and companions. It resolves workspace and alias imports, rejects forbidden platform dependencies, and fingerprints strongly connected components. A new forbidden edge or cycle fails the gate.

#Definition of done by risk

Every change keeps type checks, lint, affected builds, and targeted tests green. Additional requirements are based on risk:

High-risk work is not complete when only a mocked happy path passes. It must prove identity, state transitions, invalidation, failure recovery, cleanup, and backward compatibility at the closest production boundary.

#QG — Quality governance and metrics

Long-term exit criteria are at least 80% global line coverage, 70% branch coverage, zero lint warnings, zero forced test-worker exits, and no undocumented high-risk change merged without multi-layer evidence.

#CQ — Architecture and code quality

The follow-up shared-code preparation defines target ownership, audits duplicate contracts and public companion entry points, and orders migration slices with desktop-first parity gates. Its infrastructure adds pure-package import checks, exact exceptions with removal conditions and the read-only architecture:report inventory. The first SQL validation slice now has package-owned Netezza parser and semantic validation, a reversible compatibility boundary and a parity harness. Legacy validation remains for non-Netezza dialects. CQ01, CQ02, and CQ06 are complete for the current refactoring closure slice; subsequent runtime, coverage, accessibility, security, and product migrations remain separate work, ordered in the refactoring plan and the backlog below.

R2 runtime extraction is accepted as a separate vertical slice: SQLite, DuckDB and Netezza have instance-scoped Node runtime packages, API adapters use the registry, desktop SQLite/DuckDB facades share the runtime sessions, and the Netezza driver is imported only by @justybase/netezza-runtime. Evidence is in the three package manifests/sources, API/runtime tests, DuckDB/File SQL integration suites, packaging checks and the architecture package-boundary gate. The live Netezza integration gate now passes on Linux (13 suites, 153 tests); Windows Extension Host and Remote-WSL checks remain environment- specific release evidence.

The R4 metadata-rule slice is implemented as a concrete @justybase/metadata-core package. Desktop cache, prefetch, index, identifier, completeness, disk-restart, and both schema-provider paths use the shared rules; the API metadata service is server-instance/owner/connection scoped and generation guarded. Its Linux verification is recorded in REFACTORING_PLAN.md; Windows and live-database gates remain environment-specific follow-up evidence. CQ02 is complete for the broader schema/API/React coordinator decomposition described above.

Architecture completion means zero new cycles, no vscode dependency in shared packages, no untyped high-traffic webview command, and no state migration that silently applies data belonging to another result identity.

#TQ — Deep, live, and stateful testing

#Reference Result Panel state matrix

The existing scroll tests are the depth standard, not a one-off exception. Keep their current source/result switching coverage and add any missing cells below.

State to preserve:

• vertical offset, horizontal offset, and virtualizer anchor;
• sorting, global and column filters, grouping, and expanded groups;
• column order, width, visibility, and pinning;
• result formatting, alternate view, and disk-group expansion state.

Identity and invalidation:

• key state by source URI, result index, and stable resultSetId;
• accept execution timestamps only as the documented legacy fallback;
• never restore state from another result identity;
• invalidate incompatible state on a new execution while retaining explicitly pinned historical results.

Transitions:

• Logs → result → Logs → the same result;
• result set → another result set and back;
• source/editor tab → another source and back;
• panel hide/reveal and initially zero-sized layout;
• webview reload/revival and VS Code window reload where persistence applies;
• pin, unpin, close, index shift, refresh, and new execution;
• active streaming, cancellation with partial rows, disk-backed data, and empty results.

Assertions and layers:

• prefer exact stable identity and virtualizer-anchor assertions;
• assert both axes; use pixel tolerance only when no anchor exists;
• wait for hydrate, layout, and persistence acknowledgement rather than sleep;
• cover pure persistence logic, bundled DOM behavior, the real Extension Host, and scheduled repeated race runs.

#Other mandatory state/failure matrices

• Editor/LSP: rapid edits, stale diagnostics, metadata refresh, connection switching, disconnect/reconnect, document close, and server restart.
• Query execution: stream sequencing, retry, cancellation, row limits, partial results, multi-statement errors, and late callbacks.
• Metadata: warm/cold cache, incomplete layers, concurrent refresh, disk restart, corruption, and schema-changing DDL.
• Data movement: format/type boundaries, target rollback or partial-write reporting, source/target capability mismatch, and cleanup.

#UX — Accessibility, consistency, and performance

#DQ — Documentation quality

#SQ — Security, supply chain, and release quality

#FQ — Functional completeness

Functional work follows quality readiness; it does not bypass it.

#Delivery sequence

#Phase 0 — Establish truth (delivered 2026-08-31)

• Publish this roadmap and audited baseline.
• Correct stale web parity and UX claims.
• Define metrics, evidence, status, and ownership rules.

Exit: the active backlog has one canonical location, current claims match code, and every P0 item has an owner role and measurable acceptance criteria.

#Phase 1 — P0 foundations

• Fix test teardown and freeze coverage/warning baselines.
• Add changed-code, architecture, React, accessibility, and state-contract gates.
• Version persisted state and type high-traffic protocols.

Exit: full tests terminate naturally, quality cannot regress silently, and high-risk UI/transport changes have enforceable contracts.

#Phase 1A — Quality ratchet (delivered 2026-08-31)

• Add a versioned quality baseline/report and machine-readable lint/coverage gates.
• Enforce the initial root coverage floors and changed high-risk coverage in CI.
• Replace the obsolete branch-only PR checklist with risk, state/failure, and cleanup evidence requirements.
• Reduce the first Result Panel lint-warning target to 162 warnings and make increases blocking.
• Remove the known unit-test timeout leak; the complete Jest suite exits naturally.

Exit evidence: npm run test:quality-tools, npm run lint:extended:check, npm run test:validate, npm run docs:check, and npm run check-types:media. The 100-warning milestone was surpassed; the current frozen baseline is 70 and the next cleanup target is zero warnings. Phase 1 continues with React, accessibility, architecture, and state-contract gates.

#Phase 2 — Reliability and decomposition

• Expand race, persistence, metadata, execution, and security tests.
• Decompose critical modules without behavior changes.
• Reduce warning and low-coverage hotspots.

Exit: critical subsystems meet their coverage targets, have no unresolved P0 state/failure cells, and have explicit resource ownership.

#Phase 3 — Quality-gated functionality

• Deliver verified web and dialect gaps in FQ priority order.
• Include contracts, integration tests, accessibility, security, and docs in the same change.

Exit: promoted functionality has executable parity evidence and no unsupported capability is advertised as complete.

#Phase 4 — Continuous control

• Run scheduled live, stress, performance, mutation, and security checks.
• Review metrics monthly and ratchet warning/coverage thresholds.
• Smoke-test release artifacts on the supported platform matrix.

Exit: regression trends are visible before release and every release carries a reproducible quality record.

#Interfaces and compatibility policy

Roadmap implementation must keep shared contracts additive. Future interface work is expected in three internal boundaries:

1. exhaustive host/webview message unions with runtime validation;
2. a versioned persisted-grid-state envelope with legacy migration;
3. a versioned quality-report schema consumed by CI.

Removing or retyping an existing public field requires deprecation, consumer migration, and compatibility tests. New platform-neutral behavior must remain free of vscode imports.

#Maintenance rules

• Update this document when a baseline, priority, dependency, or acceptance criterion changes.
• Do not mark an item done solely because code was merged; attach passing verification and update affected documentation.
• Do not lower a threshold to make a regression pass. Record a time-bounded exception with owner, reason, and recovery item instead.
• Keep live credentials, customer SQL/data, screenshots, and generated reports out of source control.
• Re-audit the complete roadmap after a major architecture or product-scope change and at least once per release cycle.