rails-ai-context 5.32.2 → 5.34.0

data/lib/rails_ai_context/redaction.rb

@@ -17,6 +17,8 @@ module RailsAiContext
     PLACEHOLDER_NAMES = SafePath::PLACEHOLDER_SUFFIXES.map { |suffix| Regexp.escape(suffix.delete_prefix(".")) }.join("|")
     EXAMPLE_FILE = /\.(?:#{PLACEHOLDER_NAMES})\b/
     YAML_FILE = /\.ya?ml(?:\.(?:erb|#{PLACEHOLDER_NAMES}))*\z/
+    # A log, rotated or kept ones included: Logger's development.log.0, logrotate's .log-20261001, .log-2026-10-01 and .log.old, and a .log.bak.
+    LOG_FILE = /\.log(?:\.\d+|-\d{4}-?\d{2}-?\d{2}(?:-?\d{2})?|\.old|\.bak)?\z/
 
     # Regex by design: these scrub vocabulary out of values already read from
     # the AST or a log file rather than parsing structure. A credential can
@@ -32,7 +34,10 @@ module RailsAiContext
 
     # The secret word has to be a whole underscore-delimited part of the name,
     # so `secret_key` and `api_key` match while `passwordless_login` does not.
-    SECRET_NAME = /(?<!\w)(?:\w+_)?(?:#{SECRET_WORD})(?:_\w+)?(?!\w)/i
+    # A name is a whole word, so it is taken atomically: when what follows it
+    # fails, trying the word split another way cannot help, and doing so cost
+    # the square of a long word with the secret word in many of its parts.
+    SECRET_NAME = /(?<!\w)(?>(?:\w+_)?(?:#{SECRET_WORD})(?:_\w+)?(?!\w))/i
 
     # A name ending in `_KEY`/`Key`/`key` is as often a cache or i18n key as a credential,
     # so under it only a credential-looking value is filtered (see key_credential?).
@@ -66,24 +71,18 @@ module RailsAiContext
     CREDENTIAL_SHAPE = /[a-f0-9]{16,}|sk_|pk_/i
 
     ANSI_ESCAPE = /\e\[[0-9;]*[mGKHF]/
-    EMAIL_PATTERN = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z]{2,}\b/i
+    # An address in any script (jürgen@example.com, anna@münchen.de). It starts
+    # where a run of name characters starts and takes the name whole, with
+    # nothing to give back, so a 1 MB line of near-addresses costs a pass,
+    # not a pass per character.
+    EMAIL_PATTERN = /(?<![\p{L}\p{M}\p{N}._%+-])[\p{L}\p{M}\p{N}._%+-]++@(?:[\p{L}\p{M}\p{N}-]++\.)+[\p{L}\p{M}]{2,}(?![\p{L}\p{M}\p{N}-])/
+    # The same for a line in another encoding, which a Unicode pattern cannot read.
+    ASCII_EMAIL_PATTERN = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z]{2,}\b/i
     DOTENV_LINE = /\[dotenv\]\s+Set\s+.*/i
     # A log value: quoted whole, or bare up to a space, a quote or a separator,
     # so the quotes and the comma around it survive its redaction.
     LOG_VALUE = /(?!["']?\[FILTERED\])(?:"[^"]*"|'[^']*'|[^\s"',;)\]}]+)/
 
-    # A log line spells an assignment four ways: `key=value`, `key: value`,
-    # `"key"=>"value"` and `"key":"value"`. One pattern over SECRET_NAME
-    # covers every secret-ish name in all four; a per-name lookbehind list
-    # covered four names in two shapes and shipped the rest verbatim.
-    # Lookbehind is unavailable here because SECRET_NAME is variable width,
-    # so the key and the assignment are captured and written back.
-    LOG_SECRET_ASSIGNMENT = /
-      (["']?)(#{SECRET_NAME}|#{KEYISH_NAME})\1
-      (\s*(?:=>|:|=(?!>))\s*)
-      (?!["']?\[FILTERED\])(?:"([^"]*)"|'([^']*)'|([^\s,;&)\]}]+))
-    /xi
-
     # Formats that are a credential wherever they appear: nothing else in
     # code or config is written this way. A JWT's signature may be empty.
     CREDENTIAL_TOKENS = [
@@ -112,12 +111,28 @@ module RailsAiContext
     # Each entry is [pattern, replacement]. The replacement is spelled beside
     # the pattern rather than worked out later by grepping the pattern's own
     # source for a distinguishing substring.
+    #
+    # The names are matched, not looked behind for. Under /i Unicode case
+    # folding makes `s` two bytes long (`ſ` is one), so a look-behind holding
+    # one has no fixed length, and Onigmo before Ruby 3.4 raises on it as
+    # soon as the line carries any non-ASCII character - which every
+    # development log's `↳` query-source line does. read_logs then failed
+    # outright, and diagnose lost its log section.
     LOG_PATTERNS = ([
-      [ /(?<=authorization:\s)(?:Bearer\s)?[^\s"',;)\]}]+/i, FILTERED ],
-      # A `value` group is filtered in place, keeping the name and the quotes.
-      [ /(?<=cookie:\s)(?<value>#{LOG_VALUE})/i, :value ],
-      [ /(?<=session_id=)(?<value>#{LOG_VALUE})/i, :value ],
-      [ /(?<=_session=)(?<value>#{LOG_VALUE})/i, :value ],
+      # A `value` group, which ends the match, is filtered in place, keeping
+      # the name and the quotes. The Authorization header goes whole, its
+      # scheme with it, however the line spells it: `Authorization: Basic ...`,
+      # a quoted value, a hash or JSON key, Rack's `HTTP_AUTHORIZATION`.
+      # Unquoted, the name needs a header's space after its colon (so
+      # `Authorization::UnauthorizedError` is a class), or an env dump's `=` or
+      # a debug line's `=>`; after `name=` an `&` starts the next query parameter.
+      [ /(?:(?<quote>["'])(?:HTTP_(?:PROXY_)?|Proxy-|X-)?authorization\k<quote>\s*(?:=>|:|=(?!>))\s*|authorization(?::\s+|\s*=>\s*|\s*(?<query>=)(?![=~>])\s*))
+         (?<value>(?!["']?\[FILTERED\]|(?:true|false|nil|null)(?=[\s,;)\]}]|\z|(?(<query>)&|(?!))))(?:"(?:[^"\\]|\\.)*+"|'(?:[^'\\]|\\.)*+'
+           |(?:Token|Digest)\s+[\w-]+=(?:"[^"]*"|\[FILTERED\]|[^\s",]+)(?:,\s*[\w-]+=(?:"[^"]*"|\[FILTERED\]|[^\s",]+))*
+           |(?:(?:Bearer|Basic|Token)\s+)?(?:\[FILTERED\]|="[^"]*"|(?(<query>)[^\s"',;&)\]}]|[^\s"',;)\]}]))+))/xi, :value ],
+      [ /cookie:\s(?<value>#{LOG_VALUE})/i, :value ],
+      [ /session_id=(?<value>#{LOG_VALUE})/i, :value ],
+      [ /_session=(?<value>#{LOG_VALUE})/i, :value ],
       [ PEM_BEGIN, FILTERED ]
     ] + CREDENTIAL_TOKENS.map { |pattern| [ pattern, FILTERED ] }).freeze
 
@@ -126,11 +141,42 @@ module RailsAiContext
 
     # A key is a name, bare or quoted whole (`'api/verify_token'` is a route path). Password
     # words hold short literals (a PIN), so they stay out of SECRET_WORD, which logs share.
-    PASSWORD_WORD = /passphrase|password|passwd|pass|pin/i
-    PASSWORD_NAME = /(?<!\w)(?:\w+_)?(?:#{PASSWORD_WORD})(?:_\w+)?(?!\w)/i
-    KEY_NAME = /#{SECRET_NAME}|#{PASSWORD_NAME}|#{KEYISH_NAME}/
+    # `requirepass` and `masterauth` are Redis's two password settings, and `MYSQL_PWD` and
+    # `REDISCLI_AUTH` the variables the mysql and redis-cli clients read theirs from.
+    PASSWORD_WORD = /passphrase|password|passwd|pass|pin|requirepass|masterauth|mysql_pwd|rediscli_auth/i
+    # A long password word that ends a name may have another joined on before it: Postgres's
+    # `PGPASSWORD`, `dbpassword`, a camel-cased `userPassword`. A short word may not (`bypass`,
+    # `spin`), nor may one with more after it (`ONEPASSWORD_VAULT` names 1Password's vault).
+    PASSWORD_NAME = /(?<!\w)(?>(?:\w+_)?(?:(?:#{PASSWORD_WORD})(?:_\w+)?|[a-z\d]+(?:passphrase|password|passwd))(?!\w))/i
+    # JSON and JavaScript write a key's words in camel case: one of them is the secret's
+    # (`accessToken`, `clientSecret`, `secretAccessKey`, `jwtSecretKey`), as one between
+    # underscores is in SECRET_NAME. `tokenizer` and `secretary` have none.
+    CAMEL_SECRET_NAME = /(?<!\w)(?>(?:secret|token|[a-z][a-z\d]*(?:[A-Z][a-z\d]*)*?(?:Secret|Token))(?:[A-Z][a-z\d]*)*(?!\w))/
+    # Each of these takes a whole word, and when two of them can, they take the same one.
+    KEY_NAME = /(?>#{SECRET_NAME}|#{PASSWORD_NAME}|#{KEYISH_NAME}|#{CAMEL_SECRET_NAME})/
+    # A header or an attribute joins its words with dashes (`"X-Api-Key"`, `"x-auth-token"`). Quoted,
+    # one with a part a key name reads is taken whole and read with its dashes as underscores (see
+    # key_name); one with none (`"Content-Type"`) is not matched, so its literal stays in reach of
+    # every pattern. The run is taken in one pass, never given back, so a long one costs no more.
+    DASHED_KEY_NAME = /(?=[\w-]*?(?:#{KEY_NAME}))[\w-]++/
+
+    # A log line spells an assignment four ways: `key=value`, `key: value`,
+    # `"key"=>"value"` and `"key":"value"`. One pattern over KEY_NAME covers
+    # every secret-ish name in all four, a camel-cased or joined one included
+    # (`{"accessToken"=>...}`, `PGPASSWORD: ...`); a per-name lookbehind list
+    # covered four names in two shapes and shipped the rest verbatim.
+    # Lookbehind is unavailable here because KEY_NAME is variable width,
+    # so the key and the assignment are captured and written back. A header
+    # name comes whole (`"X-Api-Key"=>`), its dashes read as underscores (see
+    # key_name): a run of words and dashes with a secret-ish part, taken from
+    # its start in one pass, as DASHED_KEY_NAME takes one in source.
+    LOG_SECRET_ASSIGNMENT = /
+      (["']?)((?<![\w-])(?=[\w-]*?(?:#{KEY_NAME}))[\w-]++)\1
+      (\s*(?:=>|:|=(?!>))\s*)
+      (?!["']?\[FILTERED\])(?:"([^"]*)"|'([^']*)'|([^\s,;&)\]}]+))
+    /xi
     # A quoted key may close an index (`ENV["API_TOKEN"] =`); the assignment may be `||=` or another op-assign.
-    SECRET_KEY = /"(?<name>#{KEY_NAME})"\]?|'(?<name>#{KEY_NAME})'\]?|(?<![\w"'\/\\-])(?<name>#{KEY_NAME})/
+    SECRET_KEY = /"(?<name>#{DASHED_KEY_NAME})"\]?|'(?<name>#{DASHED_KEY_NAME})'\]?|(?<![\w"'\/\\-])(?<name>#{KEY_NAME})/
     KEYED_LITERAL = /(?:#{SECRET_KEY})(?<assign>\s*(?::|=>|(?:\|\||&&|[-+*\/|&])?=(?![=~>]))\s*)(?<literal>#{STRING_LITERAL})/
 
     # A call or block whose first argument names the secret holds its value: a setter or a
@@ -138,27 +184,61 @@ module RailsAiContext
     # a `default:` (`option :client_secret, :string, default: "..."`), a `credentials.fetch` default.
     # Any other call's second argument is just another argument (`include("password", "email")`).
     SECRET_ARG = /:(?<name>#{KEY_NAME})|"(?<name>#{KEY_NAME})"|'(?<name>#{KEY_NAME})'/
+    # A call's receiver and name are read from where their run of characters starts, and taken
+    # whole: tried from each character, a long word or hex blob cost the square of its length,
+    # a minute for 80 KB on Ruby 3.1, and on 3.2 and later passed the second Rails 8 allows a match.
+    CALL_RECEIVER = /(?<![\w.!?])[.!?]*+\w[\w.!?]*+/
     CALL_KEYED = /
       \b(?:fetch|store|stub_const|update_column|update_attribute|write_attribute|set|put|append|setenv)
       \(\s*(?:#{SECRET_ARG})\s*,\s*(?<literal>#{STRING_LITERAL})
     |
-      \w[\w.!?]*\(\s*(?:#{SECRET_ARG})\s*\)\s*\{\s*(?<literal>#{STRING_LITERAL})
+      #{CALL_RECEIVER}\(\s*(?:#{SECRET_ARG})\s*\)\s*\{\s*(?<literal>#{STRING_LITERAL})
     |
-      \w[\w.!?]*[(\ ]\s*:(?<name>#{KEY_NAME})(?:\s*,\s*:\w+)*\s*,\s*default:\s*(?<literal>#{STRING_LITERAL})
+      #{CALL_RECEIVER}[(\ ]\s*:(?<name>#{KEY_NAME})(?:\s*,\s*:\w+)*\s*,\s*default:\s*(?<literal>#{STRING_LITERAL})
     |
       (?<name>credentials)\.(?:fetch|dig)\([^()]*?,\s*(?<literal>#{STRING_LITERAL})
     /x
 
     # Shell, Dockerfile, compose, env files and log lines: `NAME=value`, no space
     # around the `=` (Ruby never writes that), the value unquoted and not `$VAR`/ERB.
-    # The same shape sits in a URL query or a quoted env entry, so the value
-    # stops where a quote, bracket or separator starts; a `:name=` setter
-    # symbol and a `(?<=name=` lookbehind are not assignments.
-    ENV_ASSIGNMENT = /(?<![\w.:=!-])(?<name>#{KEY_NAME})=(?!\#\{)(?<value>[^\s"'`$<>\\()\[\]{},;&]+)/
+    # The same shape sits in a URL query, a quoted env entry or a flag
+    # (`--password=...`, `x-api-key=...`), so the value stops where a quote,
+    # bracket or separator starts; a `:name=` setter symbol, a `(?<=name=`
+    # lookbehind and a regex's wildcard (`/--password=.+/`) are not assignments.
+    ENV_ASSIGNMENT = /(?<![\w.:=!])(?<name>#{KEY_NAME})=(?!\#\{|\.[*+?])(?<value>[^\s"'`$<>\\()\[\]{},;&]+)/
+
+    # A flag may take its value as the next word, bare or quoted (`redis-server --requirepass ...`,
+    # `docker login --password "..."`), its name read as a dashed name is (key_name). Prose names a
+    # flag that way too (`the --password option`), so there only a value with a digit is a secret
+    # (flag_secret?). A `--no-...` switch takes no value; a value that is another flag, a variable,
+    # ERB, a placeholder or a path (`~/`, `./`, `/`) is no literal.
+    FLAG_ARGUMENT = /
+      (?<![\w-])--(?!no-)(?<name>[A-Za-z][\w-]*+)[ \t]++
+      (?:(?<quote>["'])(?<value>[^\s"'`$<>\\#%{~.\/][^"'`$\\]*?)\k<quote>
+        |(?<value>[^\s"'`$<>\\()\[\]{},;&|#%=~.\/-][^\s"'`$<>\\()\[\]{},;&|]*+))
+    /x
+
+    # An HTTP auth scheme says the word after it is a credential (`Bearer <token>`, `Basic <base64>`,
+    # `Token <token>`), under an Authorization key, in a curl line or a cassette alike. "Authorization"
+    # is no secret word and the value has a space, so no key rule reads it; the credential alone goes,
+    # wherever it sits, when it is shaped like one (scheme_credential?). `Bearer #{token}`,
+    # `Basic realm=...` and `Bearer YOUR_TOKEN` hold none.
+    AUTH_CREDENTIALS = %r{\b(?:Bearer|Basic|Token)[ \t]++(?<credentials>[\w.~+/-]++=*+)(?![\w.~+/=-])}i
 
     # YAML writes a string unquoted, so there a secret-named key's plain
     # scalar is a literal too.
-    YAML_SCALAR = /\A(?<head>\s*["']?(?<name>#{KEY_NAME})["']?:[ \t]+)(?<value>[^\s#][^#]*?)(?<tail>\s+#.*)?\z/
+    # A Ruby library's YAML may write its keys as symbols (`:password: ...` in config/sidekiq.yml).
+    YAML_SCALAR = /\A(?<head>\s*:?["']?(?<name>#{KEY_NAME})["']?:[ \t]+)(?<value>[^\s#][^#]*?)(?<tail>\s+#.*)?\z/
+
+    # A mapping a secret's name names holds the secret in its `value`. Heroku's app.json writes
+    # `"STRIPE_SECRET_KEY": { "value": "..." }` on one line or across several, a YAML file
+    # `STRIPE_SECRET_KEY:` over `value: ...`, and render.yaml and a Kubernetes manifest name a
+    # list entry by a sibling (`- key: CLIENT_SECRET`, `- name: API_TOKEN`) over its `value:`.
+    NAMED_OBJECT = /"(?<name>#{DASHED_KEY_NAME})"[ \t]*:[ \t]*\{[^{}]*\}/
+    NAMED_VALUE_PAIR = /(?<head>"value"[ \t]*:[ \t]*")(?<value>[^"]*)"/
+    NAMING_LINE = /\A(?<indent>[ \t]*)(?:-[ \t]+(?:key|name)[ \t]*:[ \t]+["']?(?<name>#{KEY_NAME})["']?|["']?(?<name>#{KEY_NAME})["']?[ \t]*:[ \t]*\{?)[ \t]*\z/
+    VALUE_LINE = /\A(?<head>[ \t]*["']?value["']?[ \t]*:[ \t]*)(?:(?<quote>["'])(?<value>[^"']*)\k<quote>|(?<value>[^\s"'#,{\[][^#,]*?))(?<tail>[ \t]*,?[ \t]*(?:#.*)?)\z/
+    STRUCTURED_FILE = /#{YAML_FILE}|\.json(?:\.(?:#{PLACEHOLDER_NAMES}))*\z/
 
     class << self
       # Source slices and config values.
@@ -196,16 +276,35 @@ module RailsAiContext
 
             "#{match[:name]}=#{FILTERED}"
           end
+          result = result.gsub(FLAG_ARGUMENT) { |m| filter_flag(m, Regexp.last_match, example) }
+          result = result.gsub(NAMED_OBJECT) { |m| filter_named_object(m, Regexp.last_match, example) }
         end
         result = result.gsub(STRING_LITERAL) { |lit| credential?(lit[1..-2]) ? "#{lit[0]}#{FILTERED}#{lit[0]}" : lit }
         result = CREDENTIAL_TOKENS.reduce(result) { |text, pattern| text.gsub(pattern, FILTERED) }
+        result = scheme_credentials(result)
+        # A log shown as a file (a tracked log's diff) gets what rails_read_logs filters too.
+        return redact_log_line(result) if path.to_s.match?(LOG_FILE)
+
         path.to_s.match?(YAML_FILE) && !locale ? yaml_scalar(result, example) : result
       end
 
-      # Consecutive lines, so a PEM key across them is filtered whole; the line
-      # count is kept, since callers number the lines.
+      # Consecutive lines, so a PEM key across them is filtered whole, and in a
+      # YAML or JSON file a `value` under a mapping a secret's name names; the
+      # line count is kept, since callers number the lines.
       def redact_source_lines(lines, path: nil)
-        outside_key_bodies(lines) { |line| redact_source_line(line, path: path) }
+        redacted = outside_key_bodies(lines) { |line| redact_source_line(line, path: path) }
+        return redacted unless path.to_s.match?(STRUCTURED_FILE) && !path.to_s.match?(%r{(?:\A|/)locales?/})
+
+        named_values(redacted, path.to_s.match?(EXAMPLE_FILE))
+      end
+
+      # A slice of the app's source - a method body, a template - as a tool
+      # prints it: the same lines, each secret filtered.
+      def redact_source(text, path: nil)
+        return text unless text.is_a?(String)
+
+        trailing = text.end_with?("\n") ? "\n" : ""
+        redact_source_lines(text.lines.map(&:chomp), path: path).join("\n") + trailing
       end
 
       # A config value arrives without its context, so the setting's name is
@@ -241,7 +340,7 @@ module RailsAiContext
         return true if path.match?(SECRET_PATH)
 
         leaf = path.split(".").last.to_s
-        leaf.match?(/\A#{SECRET_NAME}\z/) && !leaf.match?(DESCRIPTOR_SUFFIX)
+        leaf.match?(WHOLE_SECRET_NAME) && !leaf.match?(DESCRIPTOR_SUFFIX)
       end
 
       # Redaction and shortening are one operation because their order is the
@@ -267,21 +366,24 @@ module RailsAiContext
           name = Regexp.last_match(:name)
           log_secret?(name, Regexp.last_match(:value)) ? "#{name}=#{FILTERED}" : m
         end
-        result.gsub!(EMAIL_PATTERN, EMAIL)
+        result.gsub!(FLAG_ARGUMENT) { |m| filter_flag(m, Regexp.last_match, false) }
+        result.gsub!(result.encoding == Encoding::UTF_8 ? EMAIL_PATTERN : ASCII_EMAIL_PATTERN, EMAIL)
 
         result.gsub!(LOG_SECRET_ASSIGNMENT) { filter_assignment(Regexp.last_match) }
 
         LOG_PATTERNS.each do |pattern, replacement|
           next result.gsub!(pattern, replacement) unless replacement == :value
 
+          # A value pattern ends with its value. A group's offset is counted
+          # from the line's start, so reading one per match made a line of
+          # many matches cost the square of its length.
           result.gsub!(pattern) do
             match = Regexp.last_match
-            from = match.begin(:value) - match.begin(0)
-            match[0][0, from] + filtered_like(match[:value]) + match[0][(from + match[:value].length)..]
+            match[0].delete_suffix(match[:value]) + filtered_like(match[:value])
           end
         end
 
-        result
+        scheme_credentials(result)
       end
 
       # The one place a name and value pair leaves the process. Normally the
@@ -298,7 +400,7 @@ module RailsAiContext
         return FILTERED if credential?(stripped)
 
         name = name.to_s
-        return FILTERED if name.match?(/\A(?:#{KEY_NAME})\z/) && keyed_secret?(name, stripped, placeholder_ok)
+        return FILTERED if name.match?(WHOLE_KEY_NAME) && keyed_secret?(name, stripped, placeholder_ok)
 
         stripped.gsub(URI_USERINFO) { |m| placeholder?(m) ? m : "#{Regexp.last_match(1)}#{FILTERED}@" }
       end
@@ -319,12 +421,103 @@ module RailsAiContext
 
       # A matched name and literal, with the literal filtered when it holds a secret.
       def filter_literal(text, match, example)
-        return text unless keyed_secret?(match[:name], match[:literal][1..-2], example)
+        name = key_name(match[:name])
+        return text unless name && keyed_secret?(name, match[:literal][1..-2], example)
 
         quote = match[:literal][0]
         text.delete_suffix(match[:literal]) + "#{quote}#{FILTERED}#{quote}"
       end
 
+      # Compiled once. A pattern built inside a method is compiled again on every call, 23
+      # microseconds each, which was most of what a line of many keys or flags cost to filter.
+      WHOLE_KEY_NAME = /\A(?:#{KEY_NAME})\z/
+      WHOLE_SECRET_NAME = /\A#{SECRET_NAME}\z/
+      WHOLE_PASSWORD_NAME = /\A#{PASSWORD_NAME}\z/
+      WHOLE_KEYISH_NAME = /\A(?:#{KEYISH_NAME})\z/
+      # A name with a secret word in it, in any spelling: a `_KEY` name with one is no mere key.
+      WHOLE_SECRET_OR_PASSWORD_NAME = /\A(?:#{SECRET_NAME}|#{PASSWORD_NAME}|#{CAMEL_SECRET_NAME})\z/
+      WHOLE_SECRET_WORD = /\A(?:#{SECRET_WORD})\z/
+
+      # The name a matched key reads as. A dashed one reads with underscores, so `X-Api-Key` is
+      # `X_Api_Key`, an API key's name; one that then spells no key name (`X-Key-Id`) is none.
+      def key_name(name)
+        spelled = name.tr("-", "_")
+        spelled if spelled.match?(WHOLE_KEY_NAME)
+      end
+
+      # A one-line object a secret's name names, with its `"value"` filtered when it is that secret.
+      def filter_named_object(text, match, example)
+        name = key_name(match[:name])
+        return text unless name
+
+        text.sub(NAMED_VALUE_PAIR) do |pair|
+          value = Regexp.last_match(:value)
+          keyed_secret?(name, value, example) ? %(#{Regexp.last_match(:head)}#{FILTERED}") : pair
+        end
+      end
+
+      # The `value` lines of each mapping a secret's name names (NAMING_LINE), up to the line
+      # that leaves it: one no deeper than the name. A boolean or null is no secret.
+      def named_values(lines, example)
+        named = nil
+        lines.map do |line|
+          if (naming = line.match(NAMING_LINE))
+            named = { name: naming[:name], indent: naming[:indent].size }
+            next line
+          end
+          next line if line.strip.empty?
+
+          named = nil if named && line[/\A[ \t]*/].size <= named[:indent]
+          value = named && line.match(VALUE_LINE)
+          next line unless value
+
+          scalar = value[:value].to_s
+          next line if scalar.empty? || scalar.start_with?(FILTERED) || scalar.match?(/\A(?:true|false|yes|no|null|~)\z/i)
+          next line unless keyed_secret?(named[:name], scalar, example)
+
+          "#{value[:head]}#{value[:quote]}#{FILTERED}#{value[:quote]}#{value[:tail]}"
+        end
+      end
+
+      # A matched flag and the word after it, with the word filtered when it is the flag's secret.
+      def filter_flag(text, match, example)
+        name = key_name(match[:name])
+        value = match[:value]
+        return text unless name && flag_secret?(name, value, example)
+
+        quote = match[:quote].to_s
+        text.delete_suffix("#{quote}#{value}#{quote}") + "#{quote}#{FILTERED}#{quote}"
+      end
+
+      # A word after a flag is as often prose as the flag's value, so it needs a digit as well as
+      # what keyed_secret? asks of a value: a word is no secret, and a generated one has digits.
+      # A `name=value` list (BuildKit's `--secret id=...,env=...`) and a relative path
+      # (`keys/deploy.pem`) name where a secret is, not what it is.
+      def flag_secret?(name, value, example)
+        return false if value.match?(/\A[A-Za-z][\w-]*=[^=]/) || object_path?(value)
+
+        value.match?(/\d/) && keyed_secret?(name, value, example)
+      end
+
+      # The credential after an auth scheme goes; the scheme stays, so the line still reads.
+      def scheme_credentials(text)
+        text.gsub(AUTH_CREDENTIALS) do |m|
+          credentials = Regexp.last_match(:credentials)
+          scheme_credential?(credentials) ? m.delete_suffix(credentials) + FILTERED : m
+        end
+      end
+
+      # After a scheme, key_credential?'s 16+ letters and digits, both, read past the separators a
+      # credential is written with: a UUID's dashes, base64's `+`, `/` and `=`. A word or a
+      # placeholder has no digits to count.
+      def scheme_credential?(value)
+        return true if CREDENTIAL_TOKENS.any? { |pattern| value.match?(pattern) }
+        return false if placeholder?(value)
+
+        alnum = value.delete("^A-Za-z0-9")
+        alnum.length >= 16 && alnum.match?(/[A-Za-z]/) && alnum.match?(/\d/)
+      end
+
       # The one verdict on a name and value in a log line, whichever pattern found the pair.
       def log_secret?(name, value)
         !descriptor_name?(name) && !(keyish_only?(name) && !key_credential?(value))
@@ -371,18 +564,26 @@ module RailsAiContext
       end
 
       # A secret-named key whose value describes the secret: `TOKEN_USE`,
-      # `DEAD_TOKEN_ERROR`, `token_url`, besides the config descriptors.
-      SOURCE_DESCRIPTOR = /_(?:use|scope|kind|label|prefix|suffix|errors?|message|url|uri|endpoint|path|header)\z/i
-
+      # `DEAD_TOKEN_ERROR`, `token_url`, besides the config descriptors. A
+      # Stimulus target, action, controller, outlet or class names an element
+      # or a method (`"password-visibility-target": "input"`); a value may be a token.
+      # A name for a file, a directory or an identifier says where a secret is or which one
+      # (`token_file`, `secret_id`, AWS's `--secret-id`), not what it is.
+      SOURCE_DESCRIPTOR = /_(?:use|scope|kind|label|prefix|suffix|errors?|message|url|uri|endpoint|path|header|
+                             target|action|controller|outlet|class(?:es)?|files?|filename|dir|directory|ids?)\z/xi
+
+      # A camel-cased name is read with its words joined by underscores (`tokenType` is `token_type`).
       def descriptor_name?(name)
-        name.match?(DESCRIPTOR_SUFFIX) || name.match?(SOURCE_DESCRIPTOR)
+        snake = name.gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        snake.match?(DESCRIPTOR_SUFFIX) || snake.match?(SOURCE_DESCRIPTOR)
       end
 
       # Under a secret-named key a value is a secret unless it is clearly not
       # one (docs/TOOLS.md lists the shapes): a leak costs more than a hidden line.
       NOT_A_SECRET = [
-        # A path has two slashes and no base64 padding or `+`.
-        %r{\A(?:[a-z][a-z0-9+.-]*://|/[^+=]*/[^+=]*\z)}i,
+        # A path has two slashes and no base64 padding or `+`. Its first segment is taken whole, so
+        # a slash-filled value ending in `=` is one pass, not a retry from every slash.
+        %r{\A(?:[a-z][a-z0-9+.-]*://|/[^+=/]*+/[^+=]*+\z)}i,
         /\A[?&][\w-]+=/,
         /\A(?:[vV]\d+(?:[.-]\d+)*|\d+(?:\.\d+){1,3})\z/,
         /\A\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2})?)?\z/,
@@ -395,10 +596,15 @@ module RailsAiContext
       # `HTTP_` or naming a secret word (`_DISCOURSE_API`, `HTTP_API_KEY`).
       ENV_NAME = /\A_?[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\z/
 
+      # A switch's value (`showPassword=false`), not a credential, under any name.
+      NOT_A_SECRET_WORD = /\A(?:true|false|yes|no|on|off|null|nil|none|undefined)\z/i
+
       def secret_literal?(value, key)
-        password = key.match?(/\A#{PASSWORD_NAME}\z/)
+        password = key.match?(WHOLE_PASSWORD_NAME)
         return false if value.length < (password ? 4 : 8) || !value.ascii_only? || placeholder?(value)
-        return false if value.downcase.tr("-", "_") == key.downcase.tr("-", "_")
+        return false if value.match?(NOT_A_SECRET_WORD)
+        # The key's own name, in any case (`currentPassword: "current_password"`, an enum's `password: 'password'`).
+        return false if snake_name(value) == snake_name(key)
         # Whitespace makes a message, except in a passphrase.
         return false if value.match?(/\s/) && !key.match?(/passphrase/i)
         # Under a password key a word-joined value is the password itself.
@@ -409,6 +615,10 @@ module RailsAiContext
         (password ? NOT_A_SECRET - [ HEADER_NAME, ADDRESS, HOSTNAME ] : NOT_A_SECRET).none? { |shape| value.match?(shape) }
       end
 
+      def snake_name(name)
+        name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.tr("-", "_")
+      end
+
       # Letter-only words, one a secret word, spell a name (`user_api_key`).
       # ponytail: `super-secret-password` reads as a name; score entropy per word if that leaks.
       def names_a_secret?(value)
@@ -420,7 +630,7 @@ module RailsAiContext
       def secret_words?(value)
         words = value.gsub(/([A-Z]+)([A-Z][a-z])/, '\\1_\\2').gsub(/([a-z])([A-Z])/, '\\1_\\2')
                      .downcase.split(/[_.-]+/).reject(&:empty?)
-        (words + words.each_cons(2).map { |pair| pair.join("_") }).any? { |word| word.match?(/\A(?:#{SECRET_WORD})\z/) }
+        (words + words.each_cons(2).map { |pair| pair.join("_") }).any? { |word| word.match?(WHOLE_SECRET_WORD) }
       end
 
       def yaml_scalar(line, example)
@@ -441,7 +651,7 @@ module RailsAiContext
 
       # Named only by `_KEY`, and not by a secret word.
       def keyish_only?(name)
-        name.match?(/\A(?:#{KEYISH_NAME})\z/) && !name.match?(/\A(?:#{SECRET_NAME}|#{PASSWORD_NAME})\z/)
+        name.match?(WHOLE_KEYISH_NAME) && !name.match?(WHOLE_SECRET_OR_PASSWORD_NAME)
       end
 
       # A 16+ character run mixing letters and digits, or a known token format; a cache or i18n
@@ -523,7 +733,8 @@ module RailsAiContext
       # `password_length: 8` is policy, not a credential, so it survives.
       def filter_assignment(match)
         quote, key, assign = match[1], match[2], match[3]
-        return match[0] unless log_secret?(key, match[4] || match[5] || match[6])
+        name = key_name(key)
+        return match[0] unless name && log_secret?(name, match[4] || match[5] || match[6])
 
         value_quote = match[4] ? '"' : (match[5] ? "'" : "")
         "#{quote}#{key}#{quote}#{assign}#{value_quote}#{FILTERED}#{value_quote}"

data/lib/rails_ai_context/resources.rb

@@ -84,11 +84,13 @@ module RailsAiContext
       mime_type: "application/json"
     ).freeze
 
+    # No mime_type: the spec has a template carry one only when every
+    # resource it matches shares it, and a views directory holds ERB, HAML,
+    # jbuilder and more. Each read names its own.
     VIEW_TEMPLATE = MCP::ResourceTemplate.new(
       uri_template: "rails-ai-context://views/{path}",
       name: "View Template",
-      description: "View template content for a specific path relative to app/views",
-      mime_type: "text/html"
+      description: "View template source for a specific path relative to app/views"
     ).freeze
 
     ROUTES_TEMPLATE = MCP::ResourceTemplate.new(
@@ -98,6 +100,8 @@ module RailsAiContext
       mime_type: "application/json"
     ).freeze
 
+    INVALID_PARAMS = -32602
+
     class << self
       def static_resources
         STATIC_RESOURCES.map do |uri, meta|
@@ -114,6 +118,11 @@ module RailsAiContext
         [ MODEL_TEMPLATE, CONTROLLER_TEMPLATE, CONTROLLER_ACTION_TEMPLATE, VIEW_TEMPLATE, ROUTES_TEMPLATE ]
       end
 
+      # What a read can name: each static resource, then each template.
+      def served_uris
+        STATIC_RESOURCES.keys + resource_templates.map { |template| template.to_h[:uriTemplate] }
+      end
+
       def register(server)
         require "json"
 
@@ -122,30 +131,58 @@ module RailsAiContext
         server.resources_read_handler do |params|
           handle_read(params)
         rescue RailsAiContext::Error => e
-          # handle_read / VFS raise RailsAiContext::Error for unknown URIs and
-          # blocked paths (traversal, sensitive files). Left unhandled, the MCP
-          # SDK collapses them into a generic "-32603 Internal error" that hides
-          # the URI. On mcp >= 0.20 re-raise as the SDK's ResourceNotFoundError
-          # so the client gets a proper "-32602 Resource not found: <uri>" with
-          # the URI in error data (the uniform message also avoids leaking why a
-          # blocked path was rejected). That class doesn't exist on older but
-          # still-supported mcp (gemspec allows >= 0.13), so fall back to the
-          # original error there - same behavior as before this wrapper.
-          raise e unless defined?(MCP::Server::ResourceNotFoundError)
-
-          raise MCP::Server::ResourceNotFoundError.new(params[:uri])
+          raise read_error(params, e)
         end
       end
 
       private
 
+      # handle_read / VFS raise RailsAiContext::Error for unknown URIs and
+      # blocked paths (traversal, sensitive files). Left unhandled, the MCP
+      # SDK collapses them into a generic "-32603 Internal error" that hides
+      # the URI. On mcp >= 0.20 they become the SDK's ResourceNotFoundError,
+      # so the client gets a proper "-32602 Resource not found: <uri>" with
+      # the URI in error data (the uniform message also avoids leaking why a
+      # blocked path was rejected). That class doesn't exist on older but
+      # still-supported mcp (gemspec allows >= 0.13), so the original error
+      # goes through there - same behavior as before this wrapper.
+      #
+      # A name the app does not have, or a file over the cap, is no secret: it
+      # fails with its own reason and the names the client can use instead,
+      # where it used to succeed with an `{"error": ...}` body a client could
+      # not tell from data.
+      # The URI is echoed shortened, as a tool echoes an argument: a 100 KB
+      # one came back whole, in the message and again in the data.
+      def read_error(params, error)
+        uri = Tools::BaseTool.echo_input(params[:uri])
+        if error.is_a?(RailsAiContext::ResourceUnavailable) && handler_error_data?
+          return MCP::Server::RequestHandlerError.new(
+            error.message, params,
+            error_type: :invalid_params, error_code: INVALID_PARAMS, error_data: { uri: uri }.merge(error.data)
+          )
+        end
+        return error unless defined?(MCP::Server::ResourceNotFoundError)
+
+        MCP::Server::ResourceNotFoundError.new(uri)
+      end
+
+      # error_code and error_data arrived together with ResourceNotFoundError,
+      # which is built on them.
+      def handler_error_data?
+        MCP::Server::RequestHandlerError.instance_method(:initialize).parameters.any? { |_, name| name == :error_data }
+      end
+
       # Content hashes use MCP-spec camelCase keys (mimeType): the SDK places
       # the handler's return value into the JSON-RPC response without renaming
       # keys, so snake_case would leak to clients as-is.
       def handle_read(params)
+        # A read introspects afresh, but the booted tier reads reflection,
+        # which only a code reload brings up to date after an edit.
+        Tools::BaseTool.refresh_if_files_changed!
         # Resource reads introspect just like tool calls do, and they bypassed
-        # SafeCall entirely - so a live reload could unload constants while one
-        # was reading them and hand back a short list with nothing raised.
+        # SafeCall entirely - so a reload on another thread could unload
+        # constants while one was reading them and hand back a short list
+        # with nothing raised.
         RailsAiContext::CodeReloader.with_app_code { read_resource(params) }
       end
 
@@ -169,11 +206,9 @@ module RailsAiContext
         context = RailsAiContext.introspect
 
         if STATIC_RESOURCES.key?(uri)
-          key = STATIC_RESOURCES[uri][:key]
-          content = JsonBudget.for_resource(context[key] || {})
-          [ { uri: uri, mimeType: "application/json", text: content } ]
+          [ VFS.json_content(uri, context[STATIC_RESOURCES[uri][:key]] || {}) ]
         else
-          raise RailsAiContext::Error, "Unknown resource: #{uri}"
+          raise ResourceUnavailable.new("Resource not found: #{Tools::BaseTool.echo_input(uri)}", available: served_uris)
         end
       end
     end

data/lib/rails_ai_context/route_coverage.rb

@@ -39,6 +39,14 @@ module RailsAiContext
       CountPhrase.call(app_controllers(routes).size, "routed controller")
     end
 
+    # The count as every generated file states it, so CLAUDE.md and the rule
+    # files beside it cannot give one app two numbers: "12 app routes
+    # across 3 routed controllers (39 total incl. framework)".
+    def summary(routes)
+      "#{CountPhrase.call(app_route_count(routes), 'app route')} across #{controller_phrase(routes)} " \
+        "(#{routes[:total_routes]} total incl. framework#{suffix(routes)})"
+    end
+
     def framework_route_count(routes)
       by_controller(routes)
         .select { |name, _| framework_controller?(name) }

data/lib/rails_ai_context/safe_file.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 require "fileutils"
-require "securerandom"
+
+# securerandom is a gem an app's bundle pins, and this file loads before the
+# app boots: required here, our copy loaded first and the app's then loaded
+# over it ("already initialized constant"). It loads when first named.
+autoload :SecureRandom, "securerandom"
 
 module RailsAiContext
   # Safe file reading with size limits and error handling.
@@ -23,6 +27,15 @@ module RailsAiContext
       raise
     end
 
+    # A file the gem rewrites in part, as UTF-8 whatever the locale says. One
+    # that is not valid UTF-8 stays as bytes: what is looked for in it is
+    # ASCII, and what is not replaced is written back as it came.
+    def self.read_text(path)
+      content = File.binread(path)
+      utf8 = content.dup.force_encoding(Encoding::UTF_8)
+      utf8.valid_encoding? ? utf8 : content
+    end
+
     def self.read(path, max_size: nil)
       return nil unless path