standard_audit 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1d506a4bb5ad3811dd4a70b6be817374ec9a88ced8d1ffd9415bfddd28cc50b
-  data.tar.gz: 52c8aaa70f86810c6b308c86fa81e10c368ab5ddb011d16f422745e7681c88da
+  metadata.gz: 7fca49bbca23bc24c89aa7249f0ea4718c2f4fa6bae03748ec93a45df17c4bd0
+  data.tar.gz: 7920932fea8af270498c7620d7cb4e18e0cfaab1c0deb7f299715ce578882dd2
 SHA512:
-  metadata.gz: 2db9ee0ef4983ce2bd9a94d195bbbf973016f32a3e9e2a53b45476df6c9cc6d30f7edd2bfb7e9442d6839e05cc491263b91bb644462946510740c187eb861e29
-  data.tar.gz: cce577cbc3f1b5829429ab30765c451f4a0fdca18b9f6283f075e1b3487b3fb763ceaeca846e39768c53707361bfc87024da65e0f8e662885a47766f814dd5c1
+  metadata.gz: 7117529ed69a81588ea18b081e3b8a8047dc9441fe116bef9e594beacc692108a1c8d625e2d4c1a959ac01a1d03857d9d94e91a4dfe65c52c35ce894b980e797
+  data.tar.gz: bdb36b281136e0928c4bac601bbee408de0cf040d70222c8d3339153c53312e1bd1820f136488086184426f68ce9f930b75d521b75fd25950f4f7b3bb232c66d

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-07-31
+
+### Added
+
+- **`config.audit_error_context_key`** (default `:audit_action`) — renames the `Rails.error.report` context key naming the audit action, without needing a whole handler. Two apps had overridden `audit_write_error_handler` for nothing but this: both tag every OTHER audit-error report site with `audit_event:` (four sites in one, twelve across ten files in the other), so adopting the gem name left the operations layer as the only place forking the convention. A handler written to rename one key also silently opts out of every future improvement to the built-in reporter.
+
+### Changed
+
+- **The built-in reporter no longer fires when `raise_on_audit_write_error` re-raises.** The caller receives the error and owns it, so reporting as well produced two events for one failure in every host that both sets the flag and reports on what it catches — which is most hosts that set it at all, since the flag exists for hosts treating an unaudited write as a failure worth handling. Two of the five apps hit this independently and each wrote a log-only handler to work around it. A host that does NOT catch the error still gets a report, via its framework unhandled-error path. An explicitly configured `audit_write_error_handler` is unaffected and still runs under either policy — only the built-in reporter steps aside.
+
+### Fixed
+
+- **The write-site scan no longer reads comments as calls.** An operation declaring `audit_none!` that explained itself in prose naming `audit!` was flagged by `unexpected_write_sites` — a false failure, which hosts worked around by backticking the token in their own comments. Source is now lexed with `Ripper` and comment tokens dropped before scanning; a file that cannot be lexed falls back to raw source (the old behaviour). Lexing rather than stripping `#` to end-of-line, because the naive form eats `"#{interpolation}"` and `%w[#]` and would trade a false failure for a false pass.
+- **Corrected a docstring that was wrong for half its own surface.** It claimed the source-scanning predicates "err towards a false pass rather than a false failure". That held only for `missing_write_sites`; in the `unexpected_write_sites` direction the same match produced a false failure. Worse than the bug itself, since it told anyone hitting the failure not to suspect the scanner.
+
 ## [0.9.0] - 2026-07-31
 
 ### Added

data/lib/standard_audit/configuration.rb

@@ -10,7 +10,8 @@ module StandardAudit
                   :metadata_builder, :before_checksum_hooks,
                   :anonymizable_metadata_keys, :retention_days,
                   :audit_catalogue, :verify_audit_declarations,
-                  :raise_on_audit_write_error, :audit_write_error_handler
+                  :raise_on_audit_write_error, :audit_write_error_handler,
+                  :audit_error_context_key
 
     def initialize
       @subscriptions = []
@@ -124,6 +125,23 @@ module StandardAudit
       # write failure under either policy.
       @audit_write_error_handler = nil
 
+      # The `Rails.error.report` context key naming the audit action, for the
+      # built-in reporter. Exists because two apps independently overrode
+      # `audit_write_error_handler` for nothing but this key: both tag every
+      # OTHER audit-error report site with `audit_event:` (four sites in one
+      # app, twelve across ten files in the other), so adopting the gem's name
+      # left the operations layer as the only place forking the convention.
+      #
+      # That divergence fails silently and asymmetrically — a saved error-tracker
+      # search grouped on the host's key keeps working and simply stops
+      # containing operation write failures. Nothing errors, nothing goes red,
+      # and the search still looks healthy.
+      #
+      # A whole handler to rename one key is a lot of ceremony, and a handler
+      # written for that reason also silently opts out of every future
+      # improvement to the built-in reporter. Default keeps existing behaviour.
+      @audit_error_context_key = :audit_action
+
       # Retention defaults from ENV so it can be set per-environment without a
       # code change. Unset/blank/non-positive => nil (infinite retention, the
       # compliance-safe default that never auto-deletes). A host app can still

data/lib/standard_audit/operation/audit.rb

@@ -1,3 +1,5 @@
+require "ripper"
+
 module StandardAudit
   module Operation
     # The registry, the catalogue resolver, the write-error policy, and the
@@ -19,10 +21,20 @@ module StandardAudit
       #
       # The scan is FILE-scoped, not class-scoped — two operations defined in
       # one file share a verdict. Zeitwerk requires one class per file in a
-      # real app, so this only matters for fixtures. A commented-out or
-      # documented `audit!` in the same file also counts as a write site; the
-      # predicates deliberately err towards a false pass rather than a false
-      # failure, since the runtime guard is the authoritative check.
+      # real app, so this only matters for fixtures.
+      #
+      # Comments are stripped before scanning (see .strip_comments), so a
+      # documented or commented-out `audit!` is not a write site. Until 0.9.1
+      # it was, and the docstring here claimed the predicates "err towards a
+      # false pass rather than a false failure" — which was only ever true of
+      # {.missing_write_sites}. In the {.unexpected_write_sites} direction the
+      # same match produces a false FAILURE, so an `audit_none!` class that
+      # explained itself in prose failed the check. The claim was wrong for
+      # half its own surface, which is worse than the bug: it told anyone
+      # hitting the failure not to suspect the scanner.
+      #
+      # What remains genuinely heuristic: a string literal containing `audit!`
+      # still counts, and the runtime guard is still the authoritative check.
       WRITE_SITE_PATTERN = /(?<![\w.:])audit!\s*(?:\(|["':@$\w])/
 
       class << self
@@ -118,15 +130,24 @@ module StandardAudit
         # @raise [StandardError] the original error when
         #   `config.raise_on_audit_write_error` is true
         def handle_write_error(error, action:, operation:)
+          raising = StandardAudit.config.raise_on_audit_write_error
           handler = StandardAudit.config.audit_write_error_handler
 
           if handler
             handler.call(error, action: action, operation: operation)
-          else
+          elsif !raising
+            # Deliberately NOT reported when re-raising: the caller receives the
+            # error and owns it from here. Reporting as well produced two events
+            # for one failure in every host that both sets
+            # `raise_on_audit_write_error` and reports on the error it catches —
+            # which is most hosts that set the flag at all, since the flag exists
+            # for hosts that treat an unaudited write as a failure worth
+            # handling. And a host that does NOT catch it still gets the report,
+            # via its framework's own unhandled-error path.
             report_write_error(error, action: action, operation: operation)
           end
 
-          raise error if StandardAudit.config.raise_on_audit_write_error
+          raise error if raising
 
           nil
         end
@@ -228,7 +249,29 @@ module StandardAudit
           path = source_path(klass)
           return nil unless path && File.exist?(path)
 
-          File.read(path)
+          strip_comments(File.read(path))
+        end
+
+        # Comments are not write sites. Scanning raw source made a class that
+        # declares `audit_none!` and *explains why* in prose ("No direct audit!
+        # here") fail `unexpected_write_sites` — the scanner matched the word in
+        # the comment. That is a false failure, and it forced hosts to backtick
+        # the token in their own comments to appease a static check.
+        #
+        # Lexing rather than regex-stripping `#` to end-of-line, because the
+        # naive form eats `"#{interpolation}"` and `%w[#]`, which would trade a
+        # false failure for a false pass. A file Ripper cannot lex (syntax the
+        # running Ruby doesn't accept) falls back to the raw source: the old
+        # behaviour, which is conservative in the `audits` direction.
+        def strip_comments(src)
+          tokens = Ripper.lex(src)
+          return src if tokens.nil?
+
+          tokens.reject { |(_pos, type, _tok, _state)| type == :on_comment }
+                .map { |(_pos, _type, tok, _state)| tok }
+                .join
+        rescue StandardError
+          src
         end
 
         def subclassed?(klass)
@@ -244,7 +287,8 @@ module StandardAudit
           Rails.error.report(
             error,
             handled: true,
-            context: { audit_action: action, operation: operation.class.name }
+            context: { StandardAudit.config.audit_error_context_key => action,
+                       operation: operation.class.name }
           )
         end
       end

data/lib/standard_audit/version.rb

@@ -1,3 +1,3 @@
 module StandardAudit
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_audit
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Jaryl Sim