protonsystems/qa

Reusable Drupal module for pre-release QA gate checks and Drush reporting.

v2.1.0 2026-08-16 22:00 UTC

Requires

• php: ^8.3
• drupal/core: ^10 || ^11

GPL-2.0-or-later

Published on Packagist.org on 2026-08-17 03:00 UTC

README

Reusable Drupal module for pre-release QA checks, release gating, and Drush reporting.

Purpose

The module is intended to be reused across Drupal 10 and Drupal 11 projects by installing it as a Composer package and enabling it in the target site.

Requirements

• PHP 8.3+
• Drupal 10 or 11
• No extra package is required for shared scanners; this package bundles the qa_audit_core submodule

Features

• Runs a consistent pre-release QA gate through drush qa:run
• Supports full runs or targeted check selection with --checks=<ids>
• Produces table output for operators and JSON output for automation
• Auto-saves timestamped reports to docs/report/ by default
• Reads per-check defaults from qa.config.yml without a cache rebuild

Available Checks

• config_drift: verifies active configuration matches config/sync
• prod_split: validates expected production and development config split state
• forbidden_modules: blocks dev-only modules from production releases
• performance_hardening: validates cache, asset, Twig, and error-level production settings
• migration_integrity: detects invalid translation source rows and broken entity references with field-level breakdowns
• translation_completeness: reports translation coverage, missing languages, and sample untranslated nodes
• orphaned_content: finds stale unpublished content and configurable content lacking menu or taxonomy relationships
• broken_links: validates entity links, internal paths, and sampled external URLs
• missing_required_fields: reports published content missing required or configured critical fields
• orphaned_paragraphs: surfaces orphan paragraph findings through the shared qa_audit_core service layer
• render_smoke: runs sampled render validation across selected bundles

Installation

composer require protonsystems/qa
drush en qa

This package bundles the reusable qa_audit_core submodule so release QA and other ProtonSystems tools can share audit services without a third Composer project.

Usage

# Run all enabled checks.
drush qa:run

# Run a selected subset of checks.
drush qa:run --checks=config_drift,prod_split,performance_hardening

# Emit JSON to stdout and write a specific artifact file.
drush qa:run --format=json --output=tmp/qa/latest.json

# Fail on warnings as well as failures.
drush qa:run --fail-on-warn

The command alias drush release-qa:run is also available.

Configuration

All check settings live in qa.config.yml at the module root.

checks:
  broken_links:
    enabled: false
    defaults:
      max_links: 200

Rules:

• enabled: false skips the check during an unfiltered drush qa:run
• --checks=<id> always runs the named check even if it is disabled in YAML
• defaults: values act as baselines and CLI options always override them
• The YAML file is read at runtime, so no cache rebuild is required

Useful options:

• --fail-on-warn: return a non-zero exit code for warnings
• --checks=<ids>: comma-separated subset of checks
• --format=table|json: choose human or machine output
• --output=<path>: write the JSON report to a specific location
• --save-report=0|1: control automatic report export to docs/report/
• --sample-size=<n>, --max-bundles=<n>, --bundles=<ids>: render smoke scope overrides
• --max-broken-refs=<n>, --max-invalid-translations=<n>: migration integrity thresholds
• --max-links=<n>: broken link scan limit

Reports

When --save-report is enabled, qa:run writes a timestamped JSON report to docs/report/qa-YYYY-MM-DD_HHMMSS.json. Passing --output=<path> overrides the default report location.

For the report format and examples, see docs/report/README.md.

Releasing A New Version On Packagist

Packagist publishes versions of protonsystems/qa from git tags. Do not add a version field to composer.json; create and push a new release tag instead.

For the first public release, submit the public Git repository URL to Packagist. If you want automatic updates from GitLab, configure the Packagist integration in GitLab under Settings > Integrations using your Packagist username and API token.

Prepare the release commit on main:

git checkout main
git pull origin main
composer validate --no-check-publish --strict
git status
git add <files>
git commit -m "Release v1.0.0"
git push origin main

Create and push an annotated tag for the release:

git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

Use semantic version tags such as v1.0.0. After the tag is pushed, Packagist should detect the new version automatically. If it does not appear, open the package page in Packagist and trigger a manual update.

Notes

• The bundled qa_audit_core submodule ships with this package and does not require a separate Packagist release