rubocop-dev_doc 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a70fbdce97064f296200b1a77f663eb5c7f928973ea7be693d0ad36f1ff015bb
-  data.tar.gz: 3e285799f1deffcb5bd30c90d61b2f3bd5438cb7a6a30b358dd60eba61a31072
+  metadata.gz: 07e4fd6ab3ecb0208fb61db9e55757d6eb99cae95da51feb2623017c8339b0e8
+  data.tar.gz: c53126a7268ad824fa5da9cbb11aef8230ba8feaac0e57eb14ddabe1df0cabe0
 SHA512:
-  metadata.gz: 7eb23bbe57954d976ce2975b1eb35a616a306b56bfacacbbc18c03c40bfce86564efe48990649b4137ebdbe7f3773f77f4c3649df27a3bc3d33cc763afc10717
-  data.tar.gz: 2593c0b78fcc7d82755f1ae7ae7ee81e70a362f3f1e1eff2636ebd2b221c496304c3816cca489fa50d8f67711159ade8ecc7bd88dd2d705f3c820105579ae49c
+  metadata.gz: 303f94f3547ea900364756abceee715b72681a31aab1f9b92c7a817eca79957b11f2c93ab838ddc96109c2356a1741184f82fa9530acaab7fc57eccff72f77b3
+  data.tar.gz: e3ea10adeaceee99f587ff6af4879da1601b6f57fd2e1e1b9bba4cde530cd3736f5316b8f65e02d73bc62dafa8f8e8ef7f6aafe9282ff20548635b62689b87b8

data/config/default.yml

@@ -169,6 +169,25 @@ DevDoc/Rails/NoPerformLaterInModel:
   Include:
     - "app/models/**/*.rb"
 
+DevDoc/Rails/NoPersistenceInService:
+  Description: "app/services is for external-boundary adapters; domain persistence and transactions belong in a domain PORO or model method under app/models, enqueues at the calling controller/job."
+  Enabled: true
+  Include:
+    - "app/services/**/*.rb"
+  KnownWriteWrappers: []
+
+# Data-saving orchestration placement (see
+# best_practices/backend/en/12_orchestration.md): a transaction boundary
+# encodes which records must land together — a domain invariant owned by the
+# model layer, not the request layer. Jobs and rake tasks are deliberately
+# outside Include: they are asynchronous entry points and may transact
+# (best_practices/backend/en/08_job.md assumes idempotent writes).
+DevDoc/Rails/NoTransactionInController:
+  Description: "Controllers must not open transactions (`transaction`/`with_lock`); move the write sequence into a model method or domain PORO under app/models."
+  Enabled: true
+  Include:
+    - "app/controllers/**/*.rb"
+
 DevDoc/Rails/EnumMustBeSymbolized:
   Description: "Declare enums with `enum_symbolize :foo, { … }` instead of a bare `enum`, so the attribute type is set before the enum and the reader returns a symbol."
   Enabled: true
@@ -722,6 +741,66 @@ DevDoc/Auth/RolePredicateOutsidePolicy:
     - "test/**/*"
     - "spec/**/*"
 
+# Presence of the policy record is a LOADING fact, not an authorization fact.
+# Headless-policy stacks can hand `record` a truthy placeholder (the policy-name
+# Symbol) when a lookup resolves nothing, turning `record.present?` fail-open for
+# exactly the request it was written to refuse. Observed in production code as a
+# cross-tenant guard reduced to `record.present?`. The remedy — a type check plus
+# ownership/attribute conditions — is strictly stronger in every case, so there
+# is no legitimate hit to tolerate.
+DevDoc/Auth/NoRecordPresenceInPolicy:
+  Description: "`record.present?`/`record.blank?` is a loading fact, not an authorization fact; use a type check (`record.is_a?(SomeModel)`) plus ownership/attribute conditions."
+  Enabled: true
+  Include:
+    - "app/policies/**/*.rb"
+
+# A login-only gate authorizes every signed-in user, including other tenants'.
+# That is safe only when something else scopes what the action reaches — and the
+# cop cannot see the controller from the policy file, so it makes the developer
+# state that scoping in an adjacent "login-only:" comment. Expect a one-time
+# justification sweep on adoption; writing each sentence honestly IS the audit
+# ("what stops a stranger with someone else's id?"). Observed shipped IDORs had
+# exactly this shape: params-resolved records behind user_signed_in?-only gates.
+# A policy that is login-only throughout (current-user pages, own-resource CRUD)
+# can carry one marker above its class instead of one per gate.
+DevDoc/Auth/LoginOnlyPolicyJustification:
+  Description: "A gate that is only `user_signed_in?`/`everyone`/`true` needs an adjacent `login-only:` comment stating where per-record scoping happens — or bind the decision to the record."
+  Enabled: true
+  JustificationMarker: "login-only:"
+  LoginOnlyPredicates:
+    - user_signed_in?
+    - everyone
+  Include:
+    - "app/policies/**/*.rb"
+
+# `Post.find(params[:id])` reaches every row from a client-controlled, usually
+# enumerable id. Unless the policy binds the resolved record (or its tenant) to
+# the requester, that is a cross-tenant IDOR — the observed shipped shape. The
+# fix the cop pushes toward is scoping the lookup itself (current_user.posts,
+# parent association); a genuinely necessary root find carries an adjacent
+# "unscoped-find:" comment naming the binding. Pairs with
+# LoginOnlyPolicyJustification: shipping a new IDOR past both requires writing
+# two dishonest justifications in two files.
+DevDoc/Auth/UnscopedFindJustification:
+  Description: "A `Model.find(params[...])` with a constant receiver is unscoped; scope it through an association/current_user or add an adjacent `unscoped-find:` comment naming the binding."
+  Enabled: true
+  JustificationMarker: "unscoped-find:"
+  FinderMethods:
+    - find
+    - find_by
+    - find_by!
+  # Lookup keys treated as non-enumerable capability ids: a keyword lookup
+  # whose params-derived values are all keyed by one of these
+  # (`find_by!(uuid: params[:id])`) is skipped — the unguessable key is the
+  # binding. Key NAMES only; the cop cannot verify entropy. `slug` is
+  # deliberately absent (public, guessable). Set to [] to disable.
+  NonEnumerableKeys:
+    - uuid
+    - token
+    - secret_key
+  Include:
+    - "app/controllers/**/*.rb"
+
 DevDoc/I18n/AvoidTitleizeHumanize:
   Description: "Avoid `.titleize`/`.humanize` for display text; it's English-only and bypasses I18n. Use `t(...)`."
   # A review aid, not a clean lint: it can't tell a display string from one

data/lib/dev_doc/test/best_practice_lints.rb

@@ -1,5 +1,7 @@
 require_relative 'lints/cron_schedule'
 require_relative 'lints/duplicate_snapshot'
+require_relative 'lints/enqueue_disable_naming'
+require_relative 'lints/external_io_boundary'
 require_relative 'lints/no_file_excludes'
 
 module DevDoc
@@ -24,6 +26,8 @@ module DevDoc
       def self.included(base)
         base.include Lints::CronSchedule
         base.include Lints::DuplicateSnapshot
+        base.include Lints::EnqueueDisableNaming
+        base.include Lints::ExternalIoBoundary
         base.include Lints::NoFileExcludes
       end
     end

data/lib/dev_doc/test/lints/cross_tenant_canary_check.rb

@@ -0,0 +1,111 @@
+module DevDoc
+  module Test
+    module Lints
+      # Cross-tenant canary sweep: catches a tenant-isolation leak by
+      # *observing responses/side-effects*, not by inspecting source. The
+      # static auth cops (DevDoc/Auth/*) flag the leak-shaped code patterns
+      # we have seen before; this lint fails when another tenant's data
+      # actually APPEARS somewhere a persona must not see it — regardless of
+      # which novel controller shape caused it.
+      #
+      # ## The canary convention (consumer-side)
+      # Fixtures give every tenant globally-unique, greppable markers on
+      # fields that render into responses (e.g. `CANARY-<tenant>-<field>`),
+      # seeded for at least two tenants so "foreign" is well-defined. Markers
+      # must be STATIC fixture strings — never minted at runtime — so a leak
+      # is a pure substring test with zero false positives.
+      #
+      # ## What it covers, honestly
+      # - A passive scan of every crawled response catches leaks on routes a
+      #   persona can reach. It reads CONTENT, not status: an endpoint that
+      #   returns 200 by design but embeds foreign data (a metadata preview)
+      #   is caught where a status-only probe passes it.
+      # - An adversarial replay (id-like params substituted with a foreign
+      #   tenant's ids) reaches leaks no page ever links the persona to.
+      #   Only 2xx bodies are asserted on — a substituted id that 404s has
+      #   no body to leak, and status is not the signal.
+      # - An outbound-recipient scan catches side-effect leaks (mail sent to
+      #   a foreign tenant's address) that leave no trace in any response.
+      #
+      # NOT covered: anything a persona can neither be linked to nor have
+      # its params mutated into, and any field carrying no marker. The lint
+      # reduces the cross-tenant surface; it does not eliminate it.
+      #
+      # ## Usage
+      # This file holds only the pure, Rails-free core (so the gem's own
+      # spec suite can load it). Projects include the runtime wrapper into
+      # their base integration test instead — see
+      # DevDoc::Test::Lints::CrossTenantCanarySweep.
+      module CrossTenantCanaryCheck
+        # The marker convention: `CANARY-<tenant>-<field>`. Consumers seed these
+        # STATIC strings onto tenant-owned fields. The tenant id is embedded, so
+        # collection needs no per-model knowledge — grouping is by the marker
+        # itself.
+        MARKER = /CANARY-\d+-[a-z0-9-]+/
+        TENANT_FROM_MARKER = /\ACANARY-(\d+)-/
+
+        module_function
+
+        # Build `{ tenant_key => [markers...] }` from arbitrary text sources —
+        # fixture-file contents, DB column values, rendered snapshots — grouping
+        # each marker by the tenant id embedded in it. Pure string logic: the
+        # consumer owns WHERE the text comes from (fixtures path, models), the
+        # gem owns the marker format and the grouping. Deduped per tenant.
+        def tenant_registry(texts)
+          registry = Hash.new { |hash, key| hash[key] = [] }
+          texts.each do |text|
+            text.to_s.scan(MARKER).each do |marker|
+              registry[marker[TENANT_FROM_MARKER, 1]] << marker
+            end
+          end
+          registry.transform_values(&:uniq)
+        end
+
+        # Markers belonging to every tenant OUTSIDE the persona's allowed
+        # set. Takes a SET of allowed tenant keys, not a single tenant — a
+        # global admin legitimately sees every tenant (pass all keys and the
+        # check is vacuous for it), and hierarchical tenants can grant a
+        # parent visibility into its children. Keys compare as strings so
+        # fixture-derived integers and configured symbols can't miss.
+        def foreign_markers(allowed_tenant_keys, registry)
+          allowed = allowed_tenant_keys.map(&:to_s)
+          registry.reject { |key, _| allowed.include?(key.to_s) }
+                  .values.flatten.uniq
+        end
+
+        # The subset of markers present in the body. Boundary-aware, like
+        # CopDriftCheck.unmentioned_cops: a marker that PREFIXES a longer
+        # marker must not match on the longer one's occurrence, or the
+        # failure names the wrong leaked field.
+        def leaked_markers(body, markers)
+          return [] if body.nil? || body.empty?
+
+          markers.select { |marker| body.match?(/#{Regexp.escape(marker)}(?![A-Za-z0-9-])/) }
+        end
+
+        # Outbound recipients that belong to a foreign tenant. Emails are
+        # case-insensitive per RFC domain rules and common practice, so the
+        # intersection normalizes case on both sides.
+        def leaked_recipients(recipients, foreign_emails)
+          normalize(recipients) & normalize(foreign_emails)
+        end
+
+        # Param keys worth substituting with a foreign tenant's values in an
+        # adversarial replay: `id`, anything ending `_id`, plus an explicit
+        # project-configured allowlist (e.g. a display-mode toggle that
+        # switches a form into a data-bearing preview).
+        def id_like_param_keys(keys, extra: [])
+          extras = extra.map(&:to_s)
+          keys.map(&:to_s)
+              .select { |key| key == 'id' || key.end_with?('_id') || extras.include?(key) }
+              .uniq
+        end
+
+        def normalize(emails)
+          Array(emails).compact.map { |email| email.to_s.downcase }
+        end
+        private_class_method :normalize
+      end
+    end
+  end
+end

data/lib/dev_doc/test/lints/cross_tenant_canary_sweep.rb

@@ -0,0 +1,103 @@
+require 'dev_doc/test/lints/cross_tenant_canary_check'
+
+module DevDoc
+  module Test
+    module Lints
+      # L1 of the cross-tenant canary sweep (see CrossTenantCanaryCheck for the
+      # doctrine and the honest coverage/miss statement). Passive: it asserts
+      # that no response a persona receives contains another tenant's canary
+      # marker. It adds no requests of its own — it rides whatever crawl/replay
+      # the host test already drives.
+      #
+      # Include into the project's base integration test:
+      #
+      #   Glib::IntegrationTest.include DevDoc::Test::Lints::CrossTenantCanarySweep
+      #
+      # ## The choke point
+      # Every request helper (`get`/`post`/...) funnels through the verb methods
+      # this module overrides (the module sits ahead of the framework Runner in
+      # the MRO). A JSON crawler that drives requests via `send(:get, ...)` on
+      # the test instance is caught the same way as a direct call — no crawler
+      # changes needed. After `super` returns, `response.body` holds the body to
+      # scan.
+      #
+      # ## Where this has signal, and where it deliberately doesn't
+      # The scan only sees what the response actually rendered:
+      # - Full-render harnesses (a crawler that renders pages to follow their
+      #   links; a permission replay run in FULL mode) → real signal: a foreign
+      #   marker in a persona's own reachable page is a data-bleed leak.
+      # - A permission replay in its default SKIP mode short-circuits the
+      #   controller action to a status-only body, so there is no rendered
+      #   content to scan. That harness catches cross-tenant access at the
+      #   STATUS level (its response-matrix snapshot); this lint contributes no
+      #   content signal there, and that is fine — the two are complementary,
+      #   not redundant. Passing this lint in skip mode is not evidence of
+      #   isolation; the matrix is.
+      # This layer is passive, so it never reaches a leak a persona is not
+      # already linked to — that is the adversarial replay's job (L2/L3), which
+      # the host app owns because param-mutation and mail-capture are too
+      # app-shaped to generalize. Keep this core pure.
+      #
+      # ## Consumer contract
+      # The including test must provide two things, refreshed per persona:
+      # - `canary_registry` → `{ tenant_key => [markers...] }`, scanned from
+      #   fixtures once (static strings only — never runtime-minted, per the
+      #   determinism doctrine).
+      # - `canary_allowed_tenant_keys` → the tenant keys the CURRENT persona may
+      #   legitimately see. A single-tenant member returns its one key; a global
+      #   admin returns every key (making the scan vacuous for it — correct, it
+      #   sees everything); a parent in a tenant hierarchy returns itself plus
+      #   its descendants. Returning nil disables the scan for that request
+      #   (e.g. before any persona has logged in).
+      module CrossTenantCanarySweep
+        %i[get post patch put delete head options].each do |verb|
+          define_method(verb) do |*args, **kwargs, &block|
+            result = super(*args, **kwargs, &block)
+            __dev_doc_scan_for_foreign_canary
+            result
+          end
+        end
+
+        private
+
+        def __dev_doc_scan_for_foreign_canary
+          allowed = canary_allowed_tenant_keys
+          return if allowed.nil?
+
+          registry = canary_registry
+          return if registry.nil? || registry.empty?
+
+          foreign = CrossTenantCanaryCheck.foreign_markers(allowed, registry)
+          leaked = CrossTenantCanaryCheck.leaked_markers(__dev_doc_response_body, foreign)
+          return if leaked.empty?
+
+          raise Minitest::Assertion, __dev_doc_canary_message(allowed, leaked)
+        end
+
+        def __dev_doc_response_body
+          response&.body.to_s
+        rescue StandardError
+          ''
+        end
+
+        def __dev_doc_canary_message(allowed, leaked)
+          <<~MSG
+            Cross-tenant leak: this persona (allowed tenants: #{Array(allowed).join(', ')}) received a
+            response containing #{leaked.join(', ')}, which belongs to a tenant it must not see.
+            Route: #{__dev_doc_route_label}
+            Another tenant's data rendered into this persona's response — a cross-tenant read leak.
+            Bind the record to the requester: scope the lookup through the persona's tenant
+            (current_user / current organization), or gate the policy on the record's tenant.
+            See DevDoc/Auth/UnscopedFindJustification and DevDoc/Auth/LoginOnlyPolicyJustification
+            for the static companions.
+          MSG
+        end
+
+        def __dev_doc_route_label
+          req = request
+          req ? "#{req.request_method} #{req.fullpath}" : '(unknown)'
+        end
+      end
+    end
+  end
+end

data/lib/dev_doc/test/lints/enqueue_disable_naming.rb

@@ -0,0 +1,138 @@
+require 'pathname'
+
+module DevDoc
+  module Test
+    module Lints
+      # Framework-agnostic check: finds every inline disable of
+      # `DevDoc/Rails/NoPerformLaterInModel` under `app/models/` and returns
+      # offender descriptions for directives whose enclosing method name does
+      # not signal the enqueue (`notify_*` / `send_*` / `deliver_*`).
+      #
+      # Wrapped by the Minitest module `EnqueueDisableNaming` below — see that
+      # module for the rationale.
+      class EnqueueDisableNamingChecker
+        DIRECTIVE = %r{rubocop:(?:disable|todo)[^#]*DevDoc/Rails/NoPerformLaterInModel}
+        DEF_PATTERN = /\A(\s*)def\s+(?:self\.)?([a-zA-Z_][a-zA-Z0-9_]*[!?=]?)/
+
+        # Bare `notify`/`send`/`deliver` (with optional !/?) count too — the
+        # prefix convention is about the verb being first, not about
+        # requiring a suffix.
+        DEFAULT_NAME_PATTERN = /\A(?:notify|send|deliver)(?:_|[!?]?\z)/
+
+        def initialize(project_root, name_pattern: DEFAULT_NAME_PATTERN)
+          @project_root = Pathname(project_root)
+          @name_pattern = name_pattern
+        end
+
+        # Returns an Array<String> of offender descriptions, or `[]` when
+        # every disable sits inside a conforming method.
+        def offenders
+          Dir.glob(@project_root.join('app/models/**/*.rb')).flat_map do |path|
+            file_offenders(path)
+          end
+        end
+
+        private
+
+        def file_offenders(path)
+          lines = File.readlines(path)
+          lines.each_index.filter_map do |index|
+            next unless lines[index].match?(DIRECTIVE)
+
+            method_name = enclosing_method_name(lines, index)
+            next if method_name&.match?(@name_pattern)
+
+            described = method_name ? "method `#{method_name}`" : 'no enclosing method'
+            "  #{relative(path)}:#{index + 1}: #{described}"
+          end
+        end
+
+        # Nearest `def` above the directive that is still open at the
+        # directive's line — a def is closed by an `end` at (or left of) its
+        # own indentation. Indentation-based, which the standard Layout cops
+        # make reliable; an `end` inside a heredoc is the known blind spot.
+        def enclosing_method_name(lines, directive_index)
+          same_line = DEF_PATTERN.match(lines[directive_index])
+          return same_line[2] if same_line
+
+          (directive_index - 1).downto(0) do |i|
+            def_match = DEF_PATTERN.match(lines[i])
+            next unless def_match
+
+            return def_match[2] unless closed_before?(lines, i, directive_index, def_match[1].size)
+          end
+          nil
+        end
+
+        def closed_before?(lines, def_index, directive_index, def_indent)
+          ((def_index + 1)...directive_index).any? do |i|
+            end_match = /\A(\s*)end\b/.match(lines[i])
+            end_match && end_match[1].size <= def_indent
+          end
+        end
+
+        def relative(path)
+          Pathname(path).relative_path_from(@project_root).to_s
+        end
+      end
+
+      # Naming tripwire for the sanctioned `NoPerformLaterInModel` escape:
+      # every inline disable of that cop in `app/models/` must sit inside an
+      # explicitly named `notify_*` / `send_*` / `deliver_*` method.
+      #
+      # ## Rationale
+      # A model-level enqueue is legitimate only when it is inseparable from a
+      # record state change (see the orchestration best-practice doc,
+      # execution-flow category) — and the convention that makes that
+      # legitimate is TWO-part: a justified per-line disable AND an explicit
+      # method name that announces the side effect at every call site. The
+      # meta-guard (`Style/DisableCopsWithinSourceCodeDirective`) reviews who
+      # may disable; nothing machine-checks the naming half. This lint closes
+      # that: a disable inside `finalize` or at class level fails the suite.
+      #
+      # NOTE: Limitations:
+      # - Enclosing-method detection is indentation-based (reliable under the
+      #   standard Layout cops); an `end` keyword inside a heredoc between the
+      #   `def` and the directive can misattribute the method.
+      # - The lint validates the NAME only. Whether the enqueue is genuinely
+      #   state-coupled — the justification for the disable — stays with the
+      #   reviewer.
+      #
+      # ## Usage
+      # Include this module in a Minitest test class (Rails test env). To
+      # change the accepted verb prefixes, redefine the constant on the test
+      # class:
+      #
+      #   class EnqueueDisableNamingTest < ActiveSupport::TestCase
+      #     include DevDoc::Test::Lints::EnqueueDisableNaming
+      #     # ENQUEUE_METHOD_NAME_PATTERN = /\A(?:notify|send|deliver|dispatch)_/
+      #   end
+      module EnqueueDisableNaming
+        # Default verb prefixes. Per-project override: redefine the constant
+        # on the test class that includes this module.
+        ENQUEUE_METHOD_NAME_PATTERN = EnqueueDisableNamingChecker::DEFAULT_NAME_PATTERN
+
+        def test_model_enqueue_disables_sit_in_explicitly_named_methods
+          offenders = EnqueueDisableNamingChecker.new(
+            Rails.root,
+            name_pattern: self.class::ENQUEUE_METHOD_NAME_PATTERN
+          ).offenders
+
+          assert offenders.empty?, enqueue_disable_naming_message(offenders)
+        end
+
+        private
+
+        def enqueue_disable_naming_message(offenders)
+          "Inline disables of DevDoc/Rails/NoPerformLaterInModel are sanctioned " \
+            "only inside an explicitly named notify_*/send_*/deliver_* method — " \
+            "the name announces the side effect at every call site " \
+            "(backend/12_orchestration.md). Rename the enclosing method, or move " \
+            "the enqueue to the calling controller if it is not coupled to a " \
+            "record state change.\n\n" \
+            "Offenders:\n#{offenders.join("\n")}"
+        end
+      end
+    end
+  end
+end

data/lib/dev_doc/test/lints/external_io_boundary.rb

@@ -0,0 +1,132 @@
+require 'pathname'
+
+module DevDoc
+  module Test
+    module Lints
+      # Framework-agnostic check: scans Ruby sources under `app/` (excluding
+      # `app/services/`) for HTTP-client tokens and returns offender
+      # descriptions for every hit.
+      #
+      # Wrapped by the Minitest module `ExternalIoBoundary` below — see that
+      # module for the rationale.
+      class ExternalIoBoundaryChecker
+        # The generic Ruby HTTP-client surface. Provider SDKs (Stripe, AWS,
+        # etc.) are project vocabulary and belong in the per-project token
+        # override on the `ExternalIoBoundary` module, not here.
+        DEFAULT_HTTP_CLIENT_TOKENS = %w[
+          Net::HTTP Faraday HTTParty RestClient OpenURI URI.open Typhoeus Excon Curl
+        ].freeze
+
+        def initialize(project_root, tokens: DEFAULT_HTTP_CLIENT_TOKENS, allowed_paths: [])
+          @project_root = Pathname(project_root)
+          @tokens = tokens
+          @allowed_paths = allowed_paths
+        end
+
+        # Returns an Array<String> of offender descriptions
+        # ("  app/models/foo.rb:12: Net::HTTP"), or `[]` when the boundary
+        # holds. Token matching is boundary-aware, so `Net::HTTP` does not
+        # fire on `Net::HTTPSuccess` and `Curl` does not fire on `Curly`.
+        def offenders
+          ruby_files.flat_map { |path| file_offenders(path) }
+        end
+
+        private
+
+        def ruby_files
+          Dir.glob(@project_root.join('app/**/*.rb')).reject do |path|
+            relative = relative(path)
+            relative.start_with?('app/services/') ||
+              @allowed_paths.any? { |allowed| relative.start_with?(allowed) }
+          end
+        end
+
+        def file_offenders(path)
+          [].tap do |offenders|
+            File.foreach(path).with_index(1) do |line, lineno|
+              token = @tokens.find { |candidate| code_portion(line).match?(token_pattern(candidate)) }
+              offenders << "  #{relative(path)}:#{lineno}: #{token}" if token
+            end
+          end
+        end
+
+        # Comments never count: full-line comments are dropped, and trailing
+        # ` # ...` comments are stripped (string interpolation survives —
+        # `#{` has no space after the hash).
+        def code_portion(line)
+          line.sub(/\A\s*#.*/, '').sub(/\s#\s.*/, '')
+        end
+
+        def token_pattern(token)
+          /(?<![A-Za-z0-9_])#{Regexp.escape(token)}(?![A-Za-z0-9_])/
+        end
+
+        def relative(path)
+          Pathname(path).relative_path_from(@project_root).to_s
+        end
+      end
+
+      # External-I/O boundary tripwire: HTTP-client code must live only in
+      # `app/services/` adapters.
+      #
+      # ## Rationale
+      # External-I/O sequencing (requests, retries, provider fallback,
+      # pagination) is the one kind of orchestration whose home is
+      # `app/services/` — see `best_practices/backend/en/12_orchestration.md`.
+      # `DevDoc/Rails/NoPersistenceInService` enforces the inward half of that
+      # boundary (adapters cannot persist or enqueue); this lint enforces the
+      # outward half: no HTTP client leaks into models, controllers, jobs, or
+      # views, where it would be unmockable, untracked, and invisible to the
+      # adapter conventions. A tripwire rather than a cop because it guards an
+      # invariant that currently holds — there is nothing for a cop's
+      # observed-violation justification gate to measure.
+      #
+      # NOTE: Limitations:
+      # - Matching is textual (per line, comments stripped) over `app/**/*.rb`
+      #   only — an HTTP call assembled via `Object.const_get` or made from
+      #   `lib/` is invisible.
+      # - Only the generic Ruby HTTP clients are in the default token list;
+      #   add each provider SDK your project uses (e.g. `Stripe`) via the
+      #   per-project override.
+      #
+      # ## Usage
+      # Include this module in a Minitest test class (Rails test env). To
+      # extend the token list or exempt a sanctioned path, redefine the
+      # constants on the test class:
+      #
+      #   class ExternalIoBoundaryTest < ActiveSupport::TestCase
+      #     include DevDoc::Test::Lints::ExternalIoBoundary
+      #     # HTTP_CLIENT_TOKENS =
+      #     #   (ExternalIoBoundaryChecker::DEFAULT_HTTP_CLIENT_TOKENS + %w[Stripe]).freeze
+      #     # ALLOWED_EXTERNAL_IO_PATHS = %w[app/middleware/proxy.rb].freeze
+      #   end
+      module ExternalIoBoundary
+        # Defaults. Per-project override: redefine the constants on the test
+        # class that includes this module.
+        HTTP_CLIENT_TOKENS = ExternalIoBoundaryChecker::DEFAULT_HTTP_CLIENT_TOKENS
+        ALLOWED_EXTERNAL_IO_PATHS = [].freeze
+
+        def test_no_http_clients_outside_app_services
+          offenders = ExternalIoBoundaryChecker.new(
+            Rails.root,
+            tokens: self.class::HTTP_CLIENT_TOKENS,
+            allowed_paths: self.class::ALLOWED_EXTERNAL_IO_PATHS
+          ).offenders
+
+          assert offenders.empty?, external_io_boundary_message(offenders)
+        end
+
+        private
+
+        def external_io_boundary_message(offenders)
+          "HTTP-client code outside app/services — external-I/O sequencing " \
+            "belongs in an app/services adapter (backend/12_orchestration.md). " \
+            "Move the call behind an adapter that returns data; if this site is " \
+            "a sanctioned exception, add it to ALLOWED_EXTERNAL_IO_PATHS on the " \
+            "including test class with a comment.\n\n" \
+            "Offenders:\n#{offenders.join("\n")}"
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/auth/adjacent_justification.rb

@@ -0,0 +1,55 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Auth
+        # The adjacent-justification contract shared by the auth "flag and make
+        # the developer state the mechanism" cops: an offense is silenced by a
+        # comment containing the cop's marker phrase either on the flagged
+        # node's own line (trailing) or in the contiguous comment block ending
+        # on the line directly above it. Adjacency is the point — a marker
+        # elsewhere in the file justifies nothing. Host cops must provide
+        # `justification_marker`.
+        #
+        # With `standalone_only: true` the upward walk only crosses comment-ONLY
+        # lines. Use this when the checked node is a class/module declaration:
+        # there the "trailing comment on a preceding code line" rule would let a
+        # marker trailing the PREVIOUS class's `end` silence the next class.
+        module AdjacentJustification
+          private
+
+          def adjacent_justification?(node, standalone_only: false)
+            marker = justification_marker.downcase
+            comments_by_line = processed_source.comments.group_by { |comment| comment.location.line }
+
+            return true if contains_marker?(comments_by_line[node.first_line], marker)
+
+            marker_in_block_above?(node.first_line - 1, comments_by_line, marker, standalone_only)
+          end
+
+          # Walk the contiguous comment block upward from the line directly
+          # above. A trailing comment on a preceding code line also counts —
+          # still adjacent, still a deliberate statement — except in
+          # standalone_only mode.
+          def marker_in_block_above?(line, comments_by_line, marker, standalone_only)
+            while (line_comments = comments_by_line[line])
+              break if standalone_only && !comment_only_line?(line)
+              return true if contains_marker?(line_comments, marker)
+
+              line -= 1
+            end
+
+            false
+          end
+
+          def comment_only_line?(line)
+            processed_source.lines[line - 1].lstrip.start_with?('#')
+          end
+
+          def contains_marker?(comments, marker)
+            Array(comments).any? { |comment| comment.text.downcase.include?(marker) }
+          end
+        end
+      end
+    end
+  end
+end