>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3619114. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !28 >>> <p>A pre-release audit of the 1.x head ahead of alpha7, covering the three commits since 1.0.0-alpha6, across duplicated logic, security, performance, documentation, translations, accessibility and house style. Every linter and every job of the last pipeline was green, so none of what follows was found by CI.</p> <h3>Documentation, which is where the worst of it was</h3> <ul> <li><code>README.md</code> listed six shipped features as future work under Roadmap: the verify, purge and rotate-secret commands, the admin pages, cron auto-verify and TSA timestamping. That text is what drupal.org renders on the project page.</li> <li>The documentation landing page stated that the module "does not yet ship a Drush command or admin page" and "does not handle retention purging". It ships thirteen commands, five admin surfaces and a four-stage retention lifecycle whose whole point is purging without breaking the chain.</li> <li>Five drush commands were undocumented anywhere, <code>audit_trail:compact</code> among them. Added <code>docs/commands.md</code> as a reference for all thirteen.</li> <li>The configuration guide named a permission that does not exist, <code>run audit_trail verification</code> with an underscore. Copied into a role, it grants nothing and reports no error.</li> <li>The roadmap listed three of five submodules, claimed "185+ tests" against 421, and carried the published docs site as near-term work although it is live.</li> <li>The metrics page was measured before alpha6 and before a 136-file rename. Regenerated, and it now says to regenerate it as a release step.</li> </ul> <h3>Duplicated logic</h3> <ul> <li>"The head row of a chain" was written six times. <code>AuditTrailVerifier::headIdFor()</code> already owned that query and five other sites hand-rolled it, including one inside the verifier's own class, and one in a form that had the verifier injected and called it two lines earlier.</li> <li>"The most recent checkpoint of a chain" had three implementations, differing only in which columns each caller wanted.</li> <li>Two range guards were copied across seven sites in the archiver and the verifier, throwing near-identical messages.</li> </ul> <p>All three now live in a new <code>ChainRepository</code>, which reads the chain tables and nothing else, plus a <code>ChainRange</code> holding the two guards. Six classes that injected <code>AuditTrailVerifier</code> purely to enumerate chains now take the repository instead, so the verifier leaves six dependency graphs it was never verifying anything in.</p> <h3>Accessibility</h3> <ul> <li>Nothing in the module announced a state change: there was no live region in any of the three scripts. The copy button swapped its text to "Copied!" under an <code>aria-label</code> that overrides text for assistive technology, so nothing was announced, and its failure path was a console line. The TSA certificate upload said nothing on success and nothing on failure, for every user. All of them now go through <code>Drupal.announce()</code>.</li> <li>The list diff separated added from removed items by background colour alone, inside cells where position carries no meaning. Per-line spans now carry a <code>-</code> or <code>+</code> gutter marker in their text, and the empty side of an added or removed field says so in words rather than showing a dash.</li> </ul> <h3>Performance</h3> <ul> <li>The chains collection ran an unfiltered <code>COUNT(*)</code> over <code>audit_trail</code> plus a checkpoint lookup for every row of the table, which on the multi-million-row tables this module is built for is one index scan per line of a page an operator opens because a chain is large. Both are now prefetched in one grouped query each.</li> <li>The segment add form issued one head query per chain in a loop. It now asks once for the whole set.</li> </ul> <h3>Translations</h3> <ul> <li><code>@count</code> was used inside a plain <code>t()</code>, where it is reserved for <code>formatPlural()</code>. The string extracted as a malformed plural and read "1 secrets" on a single-secret site. It was the only such slip; the module's nine other count strings are correct.</li> </ul> <h3>Release hygiene</h3> <ul> <li>The CHANGELOG had no Unreleased section, so <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/audit_trail/-/work_items/3618963" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/audit_trail/-/work_items/3618963</a></span>, which renamed fifteen hook classes, three services, four permissions, the asset filenames and the writer's <code>chainedWrite()</code> method, was recorded nowhere. Written up now, with the upgrading note the permission rename needs.</li> <li><code>audit_trail.post_update.php</code> shipped two update hooks on a project whose CHANGELOG states there are none before 1.0.0. Both were redundant on a fresh install. Removed.</li> </ul> <h3>House style</h3> <ul> <li>The dash sweep had never run here: 1,414 lines carried an em dash, en dash or arrow and 199 more a spaced double hyphen, including forty-five in strings that reach a reader, an arrow inside a form label and an em dash used as an empty-cell marker. Swept, with the punctuation chosen from what follows each dash rather than substituted blindly. Curly apostrophes in msgids straightened at the same time.</li> <li>Ten docblocks narrated a state that was never publicly released. Rewritten to describe the current design and the reason for it.</li> </ul> <h3>Not in this issue</h3> <p>The Drupal 12 lane has never been played on the 1.x head: <code>composer (next major)</code> is a manual job, so both dependent jobs sat skipped under a green badge, and the lane is known red on the <code>entity_test</code> fixture. That is <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/audit_trail/-/work_items/3619018" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/audit_trail/-/work_items/3619018</a></span>, already open with a merge request. The Automated Project Update Bot merge request has been open since June and is superseded by the compatibility work that landed in <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/audit_trail/-/work_items/3614385" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/audit_trail/-/work_items/3614385</a></span>.</p> <h3>Verification</h3> <p>PHPStan at level 3 reports no errors. PHPCS with Drupal and DrupalPractice over the whole module reports no errors. The kernel and unit classes covering everything touched pass locally against MySQL, including a new <code>ChainRepositoryTest</code> that interleaves two chains throughout, because a query that forgets its chain condition still looks correct on a single-chain fixture.</p> <p>AI-Generated: Yes (Claude Code was used to help draft this issue summary and to write the code and tests on the merge request. I reviewed and ran the work myself before posting it.)</p>