qbit-qa-capture/AGENTS.md

AGENTS.md

This file provides guidance to coding agents (Codex and others) working in this repository.

Project Overview

QBit QA Capture: QQQ QBit for optional, provider-pluggable QA bug capture (Jam first), with sanitizer rules, request correlation and QA reports as standard QQQ tables. Design: docs/DESIGN.md.

Build Commands

./mvnw compile          # Compile (always use the wrapper: Maven 3.10 cannot read the parent POM)
./mvnw test             # Unit tests
./mvnw verify           # Checkstyle, unit tests, JaCoCo gate (70% instructions, 90% classes)

Architecture

Entry point: QaCaptureQBitProducer implements QBitMetaDataProducer<QaCaptureQBitConfig> in com.kingsrook.qbits.qacapture. Packages: metadata (tables, permissions, help), service (enablement, rules, reports, QA mode), api (the qa-capture UI API extension), web (request ids, /qa/recorder, webhooks), spi (provider SPI, Jam, Svix). See docs/DESIGN.md.

Invariants

• The UI contract is src/main/resources/openapi/qqq-v1/qa-capture.yaml (extension qa-capture 1.0.0), shared with QRun-IO/qqq-frontend-next. QaCaptureApiContractTest fails when code and fragment differ; regenerate with ./mvnw -Dtest=QaCaptureApiContractTest -Dqacapture.openapi.update=true test and bump the semantic version for any change (MINOR additive, never breaking under /qqq/v1).
• Never 403 from the capability: enabled=false with a reason.
• Sanitizer rules are table data; built-in seeds are insert-only; secured-data rules are insert-only and never touch admin edits. Value patterns must be valid in Java and JavaScript (SanitizerRules.validate).
• Secrets (webhook secrets) only come from the config (host environment); never in tables, logs or responses.
• Table reads and writes from the runtime run in the system context; who may do what is decided in QaCaptureEnablement / QaCaptureService.
• Guardrail tests (QaCaptureGuardrailsTest, QaCaptureForeignKeyTest, QaCaptureChangelogTest) keep every table used, seeded or explained, helped, and every reference backed by a foreign key.

Naming (owner rule)

• Tables are lowercase snake_case prefixed qa_capture_. The QQQ table name and the backend (SQL) name are identical.
• Permissions use qa_capture.<action>.
• Qbit data lives in standard, visible QQQ tables, secured by permissions, never hidden.
• Processes run as table or record actions, never in the nav.
• Schema changes only through the qbit's Liquibase changelog; no superuser features; no filesystem.

Code Style

• 3-space indentation, opening braces on the next line, return (x);.
• Javadoc flower-box comments (/***** with ** lines) on every class and method.
• Fluent setters (withX()), wrapper types in config and entities.

Dependencies

• Java 21, parent com.kingsrook:qbit-build-parent:2.0.0; the default-active qqq-snapshot profile imports qqq-bom-pom:4.1.0-RC.11.

Release

• CircleCI qqq-orb 0.6.9: develop publishes SNAPSHOTs, release/* publishes RCs, vX.Y.Z tags publish releases.
• Merging a develop PR labelled release:rc cuts the next RC (.github/workflows/release-rc.yml).