vicary 0.2.15 → 0.2.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9a6c30ad9946f8263d26b94e52b3d5d05db3d2ac0629425d992d5cebb1a7981
-  data.tar.gz: 8102ad087d3e7d1e3e4ce63a459de3d8598efb96f584e6c5ba02c815ac663611
+  metadata.gz: 4e78fbd85fa4dde2e481bbf8b5349ceda35e4ab98fbf9ad0b336761be3f6379d
+  data.tar.gz: b9ad9cd2ebeaffa8b438c4b051d378edb47cfc86f1117cce68732f6cd3f2cdd3
 SHA512:
-  metadata.gz: 1956a3e47dc351c62ac4a58266ed48fbf936745ed6d6cf72b2abfc35df0f50b19ae2b4f603b80248e330153c866312ade9017777cbdf0f46c211ab2abeccb1fb
-  data.tar.gz: 42fa8950725aa8c58efa07462aec67843e671eef013c211a9025655df09970ddba05c54d92c524a3f244241d8bc1d147ee8acea9bd62f01b6b3e1c6d5eed8e15
+  metadata.gz: 9ef2a213c75f9cf539620a393b20e7f2521173fb14a2bfbc2d6753654a8a19f19875b143a6b4240cc4ce09b01667cccc4d1da8d2e4c52d774bc9678c52eb13cb
+  data.tar.gz: 7102716c3687292aff85bc8191e0fbbe65ef457930f9fcce2c5b78e58ed3134a8e69d5b07f728a09438f0aeda84f97753a82419e91478ebd401ba99df5c2dd47

data/README.md

@@ -45,6 +45,19 @@ replaced. A map that is absent, or that covers only some of the placeholders in
 the text, yields **no** spans and translates as the identity — a caller can
 handle "no spans" and cannot detect a wrong offset.
 
+Before a reader sees it, check that no placeholder the host did not restore
+survived — echoed by a model, or paraphrased as `[NAME_1]`, `{Name_1}` or a bare
+`NAME_1`:
+
+```ruby
+show(Vicary.assert_no_placeholders(feedback))    # raises PlaceholderLeakError
+show(Vicary.scrub_placeholders(feedback).text)   # or drop each sentence carrying one
+```
+
+The error names the kinds and the count, never the text.
+`Vicary.find_placeholders` and `Vicary.has_placeholders?` answer without raising;
+`scrub_placeholders(text, quote: true)` elides instead, for a verbatim quote.
+
 ## Checking it
 
 Three layers, because each catches what the one above it cannot.

data/lib/vicary/conformance.rb

@@ -181,6 +181,23 @@ module Vicary
         raw
       end
 
+      # The placeholder guard's contract: the pattern source, the cases and the
+      # reference's answers. Absent is an error, as for `spans.json`: a guard
+      # checked against nothing reports the same green as one that agrees.
+      def load_placeholders(dir = nil)
+        dir = Pathname.new(dir || directory)
+        path = dir.join("placeholders.json")
+        unless path.file?
+          raise SpecError,
+                "no placeholders.json at #{path}. The ports would check their " \
+                "placeholder guard against nothing."
+        end
+
+        raw = JSON.parse(path.read)
+        require_version(raw["document_version"], "placeholders.json")
+        raw
+      end
+
       # Score an implementation against every frame.
       #
       # The block receives (sentence, identity) — the same input every Python arm

data/lib/vicary/placeholders.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Vicary
+  # Text bound for a reader still carries a redaction placeholder.
+  #
+  # Names the kinds and the count, never the text around them: the message is
+  # going to a log, and the text is exactly what was not supposed to leave.
+  class PlaceholderLeakError < ArgumentError
+    attr_reader :kinds, :count
+
+    def initialize(kinds, count)
+      @kinds = kinds.freeze
+      @count = count
+      noun = count == 1 ? "placeholder" : "placeholders"
+      super("#{count} redaction #{noun} would reach a reader " \
+            "(kinds: #{kinds.join(', ')})")
+    end
+  end
+
+  # The host boundary: assert that no placeholder reaches a reader — the Ruby
+  # port of `python/src/vicary/placeholders.py`.
+  #
+  # vicary masks what it redacts as typed placeholders (`{NAME_1}`,
+  # `{LOCATION_2}`, `{EMAIL}`) and a host restores the ones a reader may see.
+  # Everything else must never be displayed, and two ways one gets out anyway
+  # are invisible to the masker: a model echoes a placeholder the host's restore
+  # map does not cover, or paraphrases one — `[NAME_1]`, `{Name_1}`,
+  # `{ NAME_1 }`, a bare `NAME_1`.
+  #
+  # {assert_no_placeholders} raises before the text is shown;
+  # {scrub_placeholders} removes them (a prose sentence carrying one is dropped,
+  # a quote elides it with `…`). Nothing is rewritten back into a word here.
+  #
+  # The pattern source is byte-identical in all three front doors, written in
+  # the dialect the engines share — ASCII classes rather than `\b`/`\w`/`\s`,
+  # and `\A`/`\z` rather than `^`/`$`, which anchor per line in Ruby.
+  # `test/placeholders_test.rb` compares it with `conformance/placeholders.json`.
+  module Placeholders
+    KINDS = %w[
+      ADDRESS AGE AWS_ACCESS_KEY AWS_SECRET_KEY
+      CREDIT_DEBIT_CARD_CVV CREDIT_DEBIT_CARD_EXPIRY
+      CREDIT_DEBIT_CARD_NUMBER DATE_OF_BIRTH DRIVER_ID EMAIL
+      IP_ADDRESS LICENSE_PLATE LOCATION MAC_ADDRESS NAME
+      ORGANIZATION PASSWORD PERSON PHONE PIN SCHOOL URL
+      US_BANK_ACCOUNT_NUMBER US_BANK_ROUTING_NUMBER US_PASSPORT_NUMBER
+      US_SOCIAL_SECURITY_NUMBER USERNAME ZIP_CODE
+    ].freeze
+    private_constant :KINDS
+
+    # Every placeholder kind vicary or its Guardrail arm can mint, plus
+    # `PERSON`, which is what a model writes when it paraphrases `NAME`.
+    # Longest first, so a match reports the whole kind.
+    PLACEHOLDER_KINDS = KINDS.sort_by { |kind| [-kind.length, kind] }.freeze
+
+    # The kind reported for a `{UPPER_CASE}` token that names no known kind.
+    OTHER_KIND = "OTHER"
+
+    WORD = "[A-Za-z0-9_]"
+    private_constant :WORD
+
+    # `NAME` -> `[Nn][Aa][Mm][Ee]`: case-insensitive in every dialect.
+    def self.fold(kind)
+      kind.chars.map { |c| c.match?(/[A-Z]/) ? "[#{c}#{c.downcase}]" : c }.join
+    end
+    private_class_method :fold
+
+    # Anything placeholder-shaped: vicary's own `{KIND}` / `{KIND_n}` for any
+    # upper-case kind; a known kind in any case inside `{}`, `[]` or `<>` with
+    # stray spaces or tabs; or a bare upper-case `KIND_n` as a whole word.
+    PLACEHOLDER_LIKE = Regexp.new(
+      "\\{[A-Z][A-Z_]*(?:_[0-9]+)?\\}" \
+      "|[{\\[<][ \\t]*(?:#{PLACEHOLDER_KINDS.map { |k| fold(k) }.join('|')})" \
+      "(?:_[0-9]+)?[ \\t]*[}\\]>]" \
+      "|(?<!#{WORD})(?:#{PLACEHOLDER_KINDS.join('|')})_[0-9]+(?!#{WORD})"
+    )
+
+    # A sentence ends at `.`, `!` or `?` followed by whitespace — but not after
+    # an honorific, an initial, `e.g.`, `i.e.` or `vs.`.
+    SENTENCE_END = Regexp.new(
+      "(?<![A-Z][a-z]\\.)" \
+      "(?<!(?<!#{WORD})[A-Z][a-z][a-z]\\.)" \
+      "(?<!(?<!#{WORD})[A-Z]\\.)" \
+      "(?<!(?<!#{WORD})e\\.g\\.)" \
+      "(?<!(?<!#{WORD})i\\.e\\.)" \
+      "(?<!(?<!#{WORD})vs\\.)" \
+      "(?<=[.!?])[ \\t\\n\\r\\f\\v]+"
+    )
+
+    # What stands in for a placeholder when every sentence of a prose field
+    # carries one. Any other kind reads "this".
+    GENERIC_STAND_INS = {
+      "NAME" => "someone",
+      "PERSON" => "someone",
+      "LOCATION" => "a place",
+      "SCHOOL" => "the school",
+      "ORGANIZATION" => "an organization"
+    }.freeze
+
+    TRIM = /\A[ \t\n\r\f\v]+|[ \t\n\r\f\v]+\z/
+    TRIM_TOKEN = /\A[{}\[\]<> \t\n\r\f\v]+|[{}\[\]<> \t\n\r\f\v]+\z/
+    ELISION = /[ \t\n\r\f\v]*…[ \t\n\r\f\v]*/
+    ELISION_BEFORE_PUNCT = / … ([.,;:!?])/
+    NUMBER_SUFFIX = /_[0-9]+\z/
+    private_constant :TRIM, :TRIM_TOKEN, :ELISION, :ELISION_BEFORE_PUNCT,
+                     :NUMBER_SUFFIX
+
+    # One placeholder found in text. `start`/`end` count characters.
+    Match = Struct.new(:text, :kind, :start, :end) do
+      def to_h
+        { "text" => text, "kind" => kind, "start" => start, "end" => self.end }
+      end
+    end
+
+    # Text with every placeholder removed, and how many were.
+    ScrubResult = Struct.new(:text, :removed)
+
+    class << self
+      # The kind a placeholder token names: `[ Name_2 ]` -> `NAME`; else
+      # {OTHER_KIND}.
+      def kind_of(token)
+        kind = token.gsub(TRIM_TOKEN, "").upcase.sub(NUMBER_SUFFIX, "")
+        PLACEHOLDER_KINDS.include?(kind) ? kind : OTHER_KIND
+      end
+
+      # Every placeholder in `text`, in order.
+      def find(text)
+        return [] if text.nil? || text.empty?
+
+        text.to_enum(:scan, PLACEHOLDER_LIKE).map do
+          m = Regexp.last_match
+          Match.new(m[0], kind_of(m[0]), m.begin(0), m.end(0))
+        end
+      end
+
+      # Whether `text` carries any placeholder.
+      def any?(text)
+        !text.nil? && !text.empty? && PLACEHOLDER_LIKE.match?(text)
+      end
+
+      # Return `text` unchanged, or raise {Vicary::PlaceholderLeakError}. Call
+      # it on the last string a host builds before a reader sees it.
+      def assert_none(text)
+        found = find(text)
+        unless found.empty?
+          raise PlaceholderLeakError.new(found.map(&:kind).uniq.sort, found.length)
+        end
+
+        text
+      end
+
+      # Remove every placeholder from `text`. Prose (the default) drops each
+      # sentence carrying one, or — when every sentence does — replaces each
+      # with its {GENERIC_STAND_INS} entry; `quote: true` elides each as `…`.
+      def scrub(text, quote: false)
+        return ScrubResult.new(text, 0) unless any?(text)
+
+        removed = text.scan(PLACEHOLDER_LIKE).length
+        if quote
+          out = text.gsub(PLACEHOLDER_LIKE, "…").gsub(ELISION, " … ")
+                    .gsub(ELISION_BEFORE_PUNCT, ' …\1').gsub(TRIM, "")
+          return ScrubResult.new(out, removed)
+        end
+
+        kept = text.gsub(TRIM, "").split(SENTENCE_END).reject { |s| any?(s) }
+        return ScrubResult.new(kept.join(" "), removed) unless kept.empty?
+
+        out = text.gsub(PLACEHOLDER_LIKE) do |token|
+          GENERIC_STAND_INS.fetch(kind_of(token), "this")
+        end
+        ScrubResult.new(out, removed)
+      end
+    end
+  end
+
+  class << self
+    # Every placeholder in `text` — see {Vicary::Placeholders}.
+    def find_placeholders(text)
+      Placeholders.find(text)
+    end
+
+    # Whether `text` carries any placeholder.
+    def has_placeholders?(text)
+      Placeholders.any?(text)
+    end
+
+    # Return `text`, or raise {Vicary::PlaceholderLeakError}.
+    def assert_no_placeholders(text)
+      Placeholders.assert_none(text)
+    end
+
+    # Remove every placeholder from `text`.
+    def scrub_placeholders(text, quote: false)
+      Placeholders.scrub(text, quote: quote)
+    end
+  end
+end

data/lib/vicary/version.rb

@@ -6,5 +6,5 @@ module Vicary
   # Shared across all three front doors on purpose: one detector, one number. A
   # gem 0.3.0 that corresponds to nothing on PyPI cannot be reasoned about, and
   # the parity claim is between *versions*, not between package names.
-  VERSION = "0.2.15"
+  VERSION = "0.2.16"
 end

data/lib/vicary.rb

@@ -44,3 +44,4 @@ require_relative "vicary/corpus"
 require_relative "vicary/latency_baseline"
 require_relative "vicary/redact"
 require_relative "vicary/spans"
+require_relative "vicary/placeholders"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vicary
 version: !ruby/object:Gem::Version
-  version: 0.2.15
+  version: 0.2.16
 platform: ruby
 authors:
 - Blake Thomas
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-13 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies: []
 description: |
   Finds the names a student writes about — classmates, teachers, relatives — and
@@ -38,6 +38,7 @@ files:
 - lib/vicary/latency_baseline.rb
 - lib/vicary/lexicon.rb
 - lib/vicary/minter.rb
+- lib/vicary/placeholders.rb
 - lib/vicary/redact.rb
 - lib/vicary/spans.rb
 - lib/vicary/structured.rb