>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3618963. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !26 >>> <h3>Problem/Motivation</h3> <p>A contributor arriving at this module knows Drupal, not audit_trail. Every name that has no counterpart in Drupal core is a word they have to learn for no reason. This is the same audit already run on sibling projects, with the same method: build a corpus of every class, interface, trait, enum and method name declared in Drupal core 11.3.16 (core/lib plus core/modules, 24173 identifiers), split each of the module's own names into lowercase words, and count each word against that corpus. A word with zero hits in core is an invention, and an invention is a defect only where core already names the same thing. Words that name this module's own domain are kept.</p> <p>phpcs with the Drupal and DrupalPractice standards reports zero errors over the module root, so none of this is a sniff failure. Every finding below is convention-level and invisible to the sniffs.</p> <p>Verified clean and needing no change: 149 of 149 files match their declared type name, 9 of 9 interfaces end in Interface, none of the 409 test method names breaks the lowerCamel rule, config entity properties are snake_case (correct, they mirror config keys the way core's NodeType does), every constant is SCREAMING_SNAKE, every database table and column is snake_case, every plugin and entity type id is snake_case and prefixed, all 34 routes are prefixed, and accessor density is 20.2 percent get methods against core's 21.0 percent.</p> <h3>Proposed resolution</h3> <ol> <li>Hook classes. None of the 15 classes in a Hook directory matches core's shape: core has 153 of 171 ending in Hooks and 163 of 171 prefixed with the extension name, and three of the modules in this project each ship a class named HelpHook. ChainRegistryInvalidator carries three Hook attributes without saying it is a hook class. Rename all 15 to the ExtensionTopicHooks shape.</li> <li>Two hook methods are not named after the hook they implement: EntryDetailAlterHook::alter() and ChainFormAlterHook::chainFormAlter(). Core names 1106 of 1208 hook methods after their hook, and a form ID alter reads formAuditTrailChainFormAlter.</li> <li>passthru, 97 hits. passthru() is a PHP built-in that executes an external program, so the name invites the wrong reading. The same concept is also spelled fanout (24 hits) and CHAIN_ONLY, and both spellings appear in the same docblock. Settle on one word.</li> <li>Seven cron methods end in Pass. All 29 core classes ending in Pass are service container compiler passes.</li> <li>Agent nouns with no core precedent, where core has the word: EntitySnapshotter (core has 77 classes ending in Builder and zero ending in Snapshotter), KeyMapDetector (there is no map, its only public method is buildRequirement(), and core has zero Detector), ChainTimestamper, and EffectiveDelaysCalculator, which is also a plural attributive noun where English wants the singular.</li> <li>BaseSegmentOperationForm becomes SegmentOperationFormBase. Core has 336 classes ending in Base; of the 14 starting with Base, none is an abstract base class.</li> <li>Boolean methods that do not read as predicates: includeNonce(), opensslAvailable(), payloadValueIsRenderable() and anchorsStillValid(), plus filePurge() and mintCheckpoint(), which are verbs returning a boolean.</li> <li>spec has zero real hits in core: all 52 matches were specific, specify or aspects. The config keys are already contributors and filters, while the accessors read getContributorSpecs() and getFilterSpecs().</li> <li>chainedWrite() becomes write(), since the class already says chained. getAuthClientKeyKey() and getAuthClientKeyPassphraseKey() name the same key entity id that getKeyId() and key_id name everywhere else. CUD has zero hits in core; CRUD has 59.</li> <li>Constants. Core has zero constants ending in _S and zero ending in _SECONDS, while this module has COVERAGE_LOCK_TTL_S, COVERAGE_LOCK_ACQUIRE_DEADLINE_S and COVERAGE_LOCK_RENEW_INTERVAL_S. tick has zero hits in core, and four MAX_..._PER_TICK constants use it.</li> <li>Front-end prefixes drift. The audit-diff family (63 hits) and a bare audit class sit next to audit-trail- everywhere else, three of the four CSS file names are unprefixed, one submodule JavaScript file is unprefixed, chip has zero hits in core, ack is used where the rest of the module says acknowledgment, and the key generator is spelled three ways.</li> <li>Permissions. None of core's 113 permissions contains an underscore, and three of this module's four do.</li> <li>Tests. One class uses the group annotation while 53 use the Group attribute, and one class puts group annotations on 40 test methods, which core never does and which PHPUnit does not read in the next-major lane.</li> <li>Prefix drift inside a single namespace: AuditTrailChainWriter and AuditTrailVerifier next to ChainArchiver, ChainTimestamper and ChainWriteLock; the plugin directory Plugin/AuditTrailFilter next to Plugin/ContextContributor; the AuditTrailFilter attribute next to the ContextContributor attribute; AuditTrailCommands next to TsaCommands. Core prefixes 1091 of its 2665 module classes with the extension name, so either choice is defensible, but not both for peer classes.</li> </ol> <h3>Remaining tasks</h3> <p>Two decisions are deliberately left out of the first pass. ContextContributor has zero hits in core but 513 here, and core's ContextProvider already means something else, so any replacement has to be better rather than merely different. SnapshotDelta reads wrong to a Drupal developer, for whom delta is the field item index and the word for this is Diff, but delta is also a stored wire-format key, so moving it is a data-shape decision as much as a name.</p> <p>Deliberately kept, because core has no word for any of them and substituting a Drupal word there would be the wrong kind of consistency: chain, secret, segment, archive, purge, compaction, checkpoint, anchor, hmac, tsa, tsq, tsr, nonce, envelope, ndjson, acknowledgment, transient, permanent, resource, channel, action, bucket, granularity and verify.</p> <p>The module is pre-1.0, so renames are free and reinstall is the upgrade path.</p> <h3>Built</h3> <p>MR !26 carries fifteen commits, one per finding. Three items on the list above did not survive reading the code, and are recorded here rather than quietly dropped.</p> <ul> <li>ChainTimestamper stays. Timestamper has zero hits in core, but core has no word for requesting an RFC-3161 token from an external authority, so the invention is the correct call.</li> <li>filePurge() and mintCheckpoint() stay. Both were flagged above as verbs returning a boolean; core does exactly that wherever the boolean means "was the action performed", as LockBackendInterface::acquire() does. mint stays with them: minting an attestation is ordinary cryptographic vocabulary, alongside nonce, anchor and envelope.</li> <li>The prefix split in the parent module stays. It turned out to be principled rather than arbitrary: the module name prefixes what a developer meets from outside (entity types, forms, controllers, list builders, drush commands, the public interfaces), while internal collaborators inside a typed subdirectory go unprefixed. Only the two unprefixed classes in the TSA submodule moved.</li> </ul> <p>The two decisions called out above as open are still open: SnapshotDelta and ContextContributor.</p> <p>Verified before pushing: phpcs reports zero errors, phpstan at level 3 reports no errors, and cspell over the changed files reports nothing that is not already in the project dictionary or already on 1.x. phpstan caught two named arguments the component rename had left behind, which is precisely the failure mode a grep misses.</p> <p>AI-Generated: Yes (Claude Code was used to help draft this issue summary and will be used to write the code and tests on the merge request. I review and run the work myself before it goes out.)</p>