@voxket-ai/qa-source-plugin

Stamps data-vx-source="app/orders/page.tsx:42:8:OrderTable" onto host JSX elements in QA builds. @voxket-ai/qa-reporter reads it back when a teammate points at something, so a bug report arrives carrying the exact file and line.

This is the difference between an agent being told "the button on the orders page looks wrong" and being told "app/orders/page.tsx:42, component OrderTable". It is the highest-leverage input the coding agent gets.

Usage

npm install -D @voxket-ai/qa-source-plugin

// next.config.ts
import { withVoxketSource } from "@voxket-ai/qa-source-plugin";

export default withVoxketSource({
  reactStrictMode: true,
});

Set NEXT_PUBLIC_VOXKET_ENV=qa in the QA environment only.

Production is untouched

Outside QA, withVoxketSource returns the same config object it was given — identity, not a clone. A production build is byte-identical to one where this package was never installed. test/next.test.ts asserts that with toBe.

It also never adds a webpack key. Next 16 hard-errors on next build when a custom webpack config is present, so injecting a webpack rule would break the very builds this is meant to support. Turbopack runs webpack-compatible loaders through turbopack.rules, which is the supported path.

Design decisions

Parse-only, then splice strings. @babel/parser is used purely as a parser; the original source is edited at the reported offsets. The alternatives are worse: a full Babel transform means adding a Babel config to the app, which disables SWC in Next and makes builds dramatically slower; a Rust SWC plugin is tightly coupled to whichever SWC version Next ships internally. This has neither problem, and because the source is preserved apart from the inserted attributes, sourcemaps stay usable.

Babel's offsets are JS string indices rather than byte offsets, so splicing cannot corrupt multi-byte source. There is a test with Devanagari, Japanese and an emoji to keep that honest.

Host elements only. A data-* attribute on <div> lands in the DOM. On a custom component it becomes a prop, which the component may not spread, may forward somewhere unexpected, or may trip a prop-types check — a real way to break the app being tested. Skipping components costs nothing: the host elements they render get stamped with their own locations, which is what the reporter needs.

Never fails a build. A parse error returns the source unchanged; a loader throw emits a warning and passes through. QA instrumentation must not be able to break compilation.

Attribute format

data-vx-source="{relative-path}:{line}:{column}:{Component}"

The reporter parses this with raw.split(":") and destructures four fields, so the value always contains exactly three separators. Colons, quotes and backslashes in paths and component names are replaced with _ — a Windows drive letter would otherwise shift every field silently.

Component is the nearest enclosing PascalCase function, variable or class, and is empty when there is no enclosing component.

test/contract.test.ts re-implements the reporter's parser and asserts against it. Nothing in the type system links the two packages, so if this format drifts the reporter starts producing wrong file paths and the agent gets sent to the wrong line — a failure that would stay invisible until someone read a bad diagnosis. That test is the only thing standing between us and that.

Development

npm install
npm run build   # loader.cjs requires dist/, so build before the loader tests
npm test
npm run typecheck

Status

Stage 0.5. Wired for Next 16 / Turbopack. Not yet applied to voxket-web-2.0 — that is the remaining stage gate, and it needs a QA build to verify the attributes appear in the DOM and are absent from production output.