iriq 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d1f6ebe248ed57192adc8f5c9600dfe14d9d0c85160dd5d6588d7fbfd7995e72
+  data.tar.gz: d80356a646effb078ebe78b62417534746ded550fd4145faa53998aa35866bde
+SHA512:
+  metadata.gz: d355eef90433cef5cd807d9c68d6259ad49d79dd87d842770fded377a535ed39e4d24228594b24ce96015f8c9e7246bdc96d7bcfa58f3cdf3350bb389bff211f
+  data.tar.gz: b0e1ddf1c6bcebadbe2578fe0760076a8401fd4fc2cd9a5f345b651371cf2fb47ebaf302565df61b05a389e0253f3febdbccc4e2389cf7d2e810abc8e4156a40

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+###  0.0.1  (2026-05-24)
+ - prototype

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,97 @@
+PATH
+  remote: .
+  specs:
+    iriq (0.0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    date (3.5.1)
+    debug (1.11.1)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    erb (6.0.4)
+    io-console (0.8.2)
+    irb (1.17.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    psych (5.3.1)
+      date
+      stringio
+    rdoc (7.2.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-debugging (0.0.4)
+      rspec-expectations (>= 3)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    stringio (3.2.0)
+    tsort (0.2.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  debug (>= 1)
+  iriq!
+  rspec (>= 3.10)
+  rspec-debugging
+  simplecov (>= 0.22)
+
+CHECKSUMS
+  date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
+  debug (1.11.1) sha256=2e0b0ac6119f2207a6f8ac7d4a73ca8eb4e440f64da0a3136c30343146e952b6
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
+  erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
+  io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
+  irb (1.17.0) sha256=168c4ddb93d8a361a045c41d92b2952c7a118fa73f23fe14e55609eb7a863aae
+  iriq (0.0.1)
+  pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
+  prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  psych (5.3.1) sha256=eb7a57cef10c9d70173ff74e739d843ac3b2c019a003de48447b2963d81b1974
+  rdoc (7.2.0) sha256=8650f76cd4009c3b54955eb5d7e3a075c60a57276766ebf36f9085e8c9f23192
+  reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-debugging (0.0.4) sha256=7a8e2dc240c140f0ed27b452a5661a56474ee8cf7b84c5bcbefd827ad36f0a6f
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+  simplecov (0.22.0) sha256=fe2622c7834ff23b98066bb0a854284b2729a569ac659f82621fc22ef36213a5
+  simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
+  simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
+  stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+
+BUNDLED WITH
+  4.0.9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Daniel Pepper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,171 @@
+Iriq
+======
+![Gem](https://img.shields.io/gem/dt/iriq?style=plastic)
+[![codecov](https://codecov.io/gh/dpep/iriq/branch/main/graph/badge.svg)](https://codecov.io/gh/dpep/iriq)
+
+Semantic IRI / URI / URL / URN normalization and clustering for Ruby.
+
+Iriq parses resource identifiers, normalizes them into canonical IRI-like
+forms, classifies path and query components, clusters similar identifiers,
+and explains which parts are stable vs. unique.
+
+```ruby
+require "iriq"
+```
+
+## Quick start
+
+```ruby
+iri = Iriq.parse("https://foo.com/users/123")
+iri.scheme         # => "https"
+iri.host           # => "foo.com"
+iri.path_segments  # => ["users", "123"]
+iri.canonical      # => "https://foo.com/users/123"
+
+Iriq.normalize("https://foo.com/users/123")
+# => "https://foo.com/users/{integer_id}"
+
+Iriq.explain("https://foo.com/users/123/orders/456")
+# => [
+#      { value: "users",  type: :literal,    variable: false },
+#      { value: "123",    type: :integer_id, variable: true  },
+#      { value: "orders", type: :literal,    variable: false },
+#      { value: "456",    type: :integer_id, variable: true  },
+#    ]
+```
+
+## Supported inputs
+
+| Input                                | Notes                                            |
+| ------------------------------------ | ------------------------------------------------ |
+| `https://foo.com/users/123`          | Standard URL                                     |
+| `foo.com/users/456`                  | Scheme-less; `https://` is assumed               |
+| `urn:isbn:0451450523`                | URN — `scheme` and `nss` are populated           |
+| `https://例え.テスト/こんにちは`         | Unicode IRI — display form preserved             |
+| `HTTPS://Foo.com:443/A`              | Scheme + host lowercased; default port dropped   |
+| `https://foo.com/a/./b/../c`         | Dot segments normalized                          |
+
+## Segment classification
+
+`Iriq::SegmentClassifier` returns one of:
+
+- `:literal` — plain word (`users`, `orders`, `Profile`, `こんにちは`)
+- `:integer_id` — pure digits below the timestamp range (`1`, `123`, `42`)
+- `:uuid` — `f47ac10b-58cc-4372-a567-0e02b2c3d479`
+- `:date` — `2024-05-23`
+- `:timestamp` — ISO 8601, or 10/13-digit UNIX epoch
+- `:hash` — 32+ hex chars (md5 / sha)
+- `:slug` — `my-cool-post`, `my_cool_post`
+- `:opaque_id` — short alphanumeric mix that doesn't fit elsewhere
+
+Heuristics are deterministic and ordered — the first matching rule wins.
+
+## Clustering
+
+```ruby
+clusterer = Iriq::Clusterer.new
+clusterer.add("https://foo.com/users/123")
+clusterer.add("https://foo.com/users/456")
+clusterer.add("https://foo.com/users/789/orders/1")
+
+clusterer.clusters.map(&:shape)
+# => ["/users/{integer_id}", "/users/{integer_id}/orders/{integer_id}"]
+
+clusterer.clusters.first.segment_stats
+# => [
+#      { position: 0, stable: true,  values: { "users" => 2 } },
+#      { position: 1, stable: false, values: { "123" => 1, "456" => 1 } },
+#    ]
+
+clusterer.explain("https://foo.com/users/999")
+# => [
+#      { value: "users", type: :literal,    variable: false, stable: true  },
+#      { value: "999",   type: :integer_id, variable: true,  stable: false },
+#    ]
+```
+
+The clusterer combines classifier output with what it has actually observed:
+a position the classifier *would* call variable but that is empirically
+constant across all members of the cluster will be reported with
+`stable: true, variable: false`.
+
+## Object model
+
+| Class                       | Responsibility                                       |
+| --------------------------- | ---------------------------------------------------- |
+| `Iriq::Parser`              | String → `Identifier`                                |
+| `Iriq::Identifier`          | Structured fields + `canonical` reconstruction       |
+| `Iriq::SegmentClassifier`   | Single segment → type symbol                         |
+| `Iriq::PathShape`           | Segments → `/users/{integer_id}` route shape         |
+| `Iriq::Normalizer`          | Identifier → canonical, shape-aware string           |
+| `Iriq::Explanation`         | Per-segment `{value, type, variable}` annotations    |
+| `Iriq::Cluster`             | One host + shape group, with examples & stats        |
+| `Iriq::Clusterer`           | Many identifiers → `Cluster` set + explain          |
+
+## CLI
+
+Installing the gem also installs an `iriq` executable.
+
+```
+$ iriq parse https://foo.com/users/123
+original:      https://foo.com/users/123
+kind:          url
+scheme:        https
+host:          foo.com
+path_segments: ["users", "123"]
+canonical:     https://foo.com/users/123
+
+$ iriq normalize foo.com/posts/2024-05-23/hello-world
+https://foo.com/posts/{date}/{slug}
+
+$ iriq explain https://foo.com/users/123/orders/456
+  literal      users
+* integer_id   123
+  literal      orders
+* integer_id   456
+
+$ iriq classify f47ac10b-58cc-4372-a567-0e02b2c3d479
+uuid
+
+$ cat urls.txt | iriq cluster
+[2] foo.com  /users/{integer_id}
+    https://foo.com/users/1
+    https://foo.com/users/2
+[1] foo.com  /posts/{slug}/edit
+    https://foo.com/posts/abc-123/edit
+```
+
+Add `--json` to any command for machine-readable output. `iriq cluster` reads
+identifiers (one per line) from a file argument or stdin; lines that fail to
+parse are skipped with a warning on stderr.
+
+Exit codes: `0` success, `1` usage error, `2` parse error.
+
+## Limitations (intentional)
+
+This is an MVP. Iriq does **not**:
+
+- Implement RFC 3986, RFC 3987, or the WHATWG URL standard fully.
+- Convert between Unicode (IRI) and punycode (URI) — the display form is
+  preserved as-is.
+- Percent-encode or decode path/query bytes. Bytes are kept as written.
+- Validate scheme-specific structure beyond URL vs. URN.
+- Resolve relative references against a base URL.
+- Round-trip `canonical` back to the exact original byte-for-byte (whitespace
+  is stripped, default ports are dropped, dot segments are collapsed).
+
+For richer IRI handling, see `addressable`. Iriq's focus is the analysis
+side: classification, normalization, and clustering — not a complete URL
+implementation.
+
+----
+## Contributing
+
+Yes please  :)
+
+1. Fork it
+1. Create your feature branch (`git checkout -b my-feature`)
+1. Ensure the tests pass (`bundle exec rspec`)
+1. Commit your changes (`git commit -am 'awesome new feature'`)
+1. Push your branch (`git push origin my-feature`)
+1. Create a Pull Request

data/exe/iriq

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require "iriq"
+
+exit Iriq::CLI.new.run(ARGV)

data/iriq.gemspec

@@ -0,0 +1,21 @@
+require_relative "lib/iriq/version"
+
+Gem::Specification.new do |s|
+  s.name        = "iriq"
+  s.version     = Iriq::VERSION
+  s.authors     = ["Daniel Pepper"]
+  s.description = "Semantic IRI/URI/URL/URN parsing, normalization, classification, and clustering."
+  s.files       = `git ls-files * ':!:spec'`.split("\n")
+  s.bindir      = "exe"
+  s.executables = ["iriq"]
+  s.homepage    = "https://github.com/dpep/iriq"
+  s.license     = "MIT"
+  s.summary     = "Semantic IRI normalization and clustering."
+
+  s.required_ruby_version = ">= 3.2"
+
+  s.add_development_dependency 'debug', '>= 1'
+  s.add_development_dependency 'rspec', '>= 3.10'
+  s.add_development_dependency 'rspec-debugging'
+  s.add_development_dependency 'simplecov', '>= 0.22'
+end

data/lib/iriq/cli.rb

@@ -0,0 +1,205 @@
+require "json"
+require "optparse"
+
+module Iriq
+  # Tiny CLI wrapper around the public API. Construct with explicit IO so
+  # specs can run it without shelling out.
+  class CLI
+    COMMANDS = %w[parse normalize explain classify cluster help version].freeze
+
+    USAGE = <<~TXT
+      Usage: iriq <command> [options] [args]
+
+      Commands:
+        parse <input>          Parse an identifier and print its fields
+        normalize <input>      Print the shape-normalized form
+        explain <input>        Annotate each path segment
+        classify <segment>     Classify a single segment
+        cluster [file]         Cluster identifiers from FILE or stdin (one per line)
+        help                   Show this message
+        version                Print version
+
+      Options:
+        -j, --json             Emit JSON instead of human-readable output
+        -h, --help             Show this message
+
+      Examples:
+        iriq parse https://foo.com/users/123
+        iriq normalize foo.com/users/456
+        echo "https://foo.com/users/1\\nhttps://foo.com/users/2" | iriq cluster
+    TXT
+
+    attr_reader :stdin, :stdout, :stderr
+
+    def initialize(stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      @stdin  = stdin
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    # Returns an integer exit code.
+    def run(argv)
+      args, opts = parse_options(argv)
+
+      cmd = args.shift
+      return print_usage(stdout, 0) if cmd.nil? || cmd == "help" || opts[:help]
+
+      unless COMMANDS.include?(cmd)
+        stderr.puts "iriq: unknown command #{cmd.inspect}"
+        print_usage(stderr, 1)
+        return 1
+      end
+
+      send("cmd_#{cmd}", args, opts)
+    rescue Iriq::ParseError => e
+      stderr.puts "iriq: parse error: #{e.message}"
+      2
+    rescue OptionParser::ParseError => e
+      stderr.puts "iriq: #{e.message}"
+      1
+    end
+
+    private
+
+    def parse_options(argv)
+      opts = { json: false, help: false }
+      parser = OptionParser.new do |o|
+        o.on("-j", "--json") { opts[:json] = true }
+        o.on("-h", "--help") { opts[:help] = true }
+      end
+      args = parser.parse(argv)
+      [args, opts]
+    end
+
+    def print_usage(io, code)
+      io.puts USAGE
+      code
+    end
+
+    def require_arg!(args, name)
+      return args.first if args.first
+
+      stderr.puts "iriq: missing argument <#{name}>"
+      throw :missing_arg, 1
+    end
+
+    def cmd_version(_args, _opts)
+      stdout.puts Iriq::VERSION
+      0
+    end
+
+    def cmd_parse(args, opts)
+      input = args.first or return missing(:input)
+      iri   = Iriq.parse(input)
+      emit_parse(iri, opts)
+      0
+    end
+
+    def cmd_normalize(args, opts)
+      input = args.first or return missing(:input)
+      out   = Iriq.normalize(input)
+      opts[:json] ? stdout.puts(JSON.generate(normalized: out)) : stdout.puts(out)
+      0
+    end
+
+    def cmd_explain(args, opts)
+      input = args.first or return missing(:input)
+      rows  = Iriq.explain(input)
+      if opts[:json]
+        stdout.puts JSON.generate(rows)
+      else
+        rows.each do |r|
+          mark = r[:variable] ? "*" : " "
+          stdout.printf("%s %-12s %s\n", mark, r[:type], r[:value])
+        end
+      end
+      0
+    end
+
+    def cmd_classify(args, opts)
+      seg  = args.first or return missing(:segment)
+      type = SegmentClassifier.new.classify(seg)
+      opts[:json] ? stdout.puts(JSON.generate(value: seg, type: type)) : stdout.puts(type)
+      0
+    end
+
+    def cmd_cluster(args, opts)
+      lines = read_input(args.first)
+      clusterer = Clusterer.new
+      lines.each do |line|
+        line = line.strip
+        next if line.empty?
+
+        begin
+          clusterer.add(line)
+        rescue Iriq::ParseError => e
+          stderr.puts "iriq: skipped #{line.inspect}: #{e.message}"
+        end
+      end
+      emit_clusters(clusterer.clusters, opts)
+      0
+    end
+
+    def cmd_help(_args, _opts)
+      print_usage(stdout, 0)
+    end
+
+    def missing(name)
+      stderr.puts "iriq: missing argument <#{name}>"
+      1
+    end
+
+    def read_input(path)
+      if path.nil? || path == "-"
+        stdin.read.lines
+      else
+        File.readlines(path)
+      end
+    end
+
+    def emit_parse(iri, opts)
+      if opts[:json]
+        stdout.puts JSON.generate(
+          original:      iri.original,
+          kind:          iri.kind,
+          scheme:        iri.scheme,
+          host:          iri.host,
+          port:          iri.port,
+          path_segments: iri.path_segments,
+          query_params:  iri.query_params,
+          fragment:      iri.fragment,
+          nss:           iri.nss,
+          canonical:     iri.canonical,
+        )
+      else
+        stdout.puts "original:      #{iri.original}"
+        stdout.puts "kind:          #{iri.kind}"
+        stdout.puts "scheme:        #{iri.scheme}" if iri.scheme
+        stdout.puts "host:          #{iri.host}"   if iri.host
+        stdout.puts "port:          #{iri.port}"   if iri.port
+        stdout.puts "path_segments: #{iri.path_segments.inspect}" if iri.url?
+        unless iri.query_params.empty?
+          stdout.puts "query_params:  #{iri.query_params.inspect}"
+        end
+        stdout.puts "fragment:      #{iri.fragment}" if iri.fragment
+        stdout.puts "nss:           #{iri.nss}"      if iri.nss
+        stdout.puts "canonical:     #{iri.canonical}"
+      end
+    end
+
+    def emit_clusters(clusters, opts)
+      sorted = clusters.sort_by { |c| -c.count }
+
+      if opts[:json]
+        stdout.puts JSON.generate(sorted.map(&:to_h))
+      else
+        sorted.each do |c|
+          host = c.host || "(urn)"
+          stdout.puts "[#{c.count}] #{host}  #{c.shape}"
+          c.examples.first(3).each { |e| stdout.puts "    #{e.canonical}" }
+          stdout.puts "    + #{c.count - 3} more" if c.count > 3
+        end
+      end
+    end
+  end
+end

data/lib/iriq/cluster.rb

@@ -0,0 +1,58 @@
+module Iriq
+  # A group of identifiers that share a host + shape key. Tracks examples and
+  # per-position segment statistics so callers can ask which positions are
+  # actually stable in practice (e.g. /users/ always literal, /{integer_id}
+  # always variable).
+  class Cluster
+    attr_reader :key, :host, :scheme, :shape, :examples, :count
+
+    MAX_EXAMPLES = 10
+
+    def initialize(key:, host:, scheme:, shape:)
+      @key            = key
+      @host           = host
+      @scheme         = scheme
+      @shape          = shape
+      @examples       = []
+      @count          = 0
+      @segment_counts = []
+    end
+
+    def add(identifier)
+      @count += 1
+      @examples << identifier if @examples.size < MAX_EXAMPLES
+
+      identifier.path_segments.each_with_index do |seg, i|
+        @segment_counts[i] ||= Hash.new(0)
+        @segment_counts[i][seg] += 1
+      end
+    end
+
+    # Per-position summary:
+    #   [
+    #     { position: 0, stable: true,  values: { "users" => 3 } },
+    #     { position: 1, stable: false, values: { "1" => 1, "2" => 1, "3" => 1 } },
+    #   ]
+    def segment_stats
+      @segment_counts.each_with_index.map do |counts, i|
+        {
+          position: i,
+          stable:   counts.size == 1,
+          values:   counts.dup,
+        }
+      end
+    end
+
+    def to_h
+      {
+        key:      key,
+        host:     host,
+        scheme:   scheme,
+        shape:    shape,
+        count:    count,
+        examples: examples.map(&:canonical),
+        segments: segment_stats,
+      }
+    end
+  end
+end

data/lib/iriq/clusterer.rb

@@ -0,0 +1,77 @@
+module Iriq
+  # Groups many identifiers by host + path shape. Use `add` to feed inputs and
+  # `clusters` to read out the groups. `explain` annotates a single identifier
+  # against the cluster it would fall into, including which positions are
+  # stable across all observed members.
+  class Clusterer
+    def initialize(classifier: SegmentClassifier.new)
+      @classifier = classifier
+      @clusters   = {}
+    end
+
+    def add(input)
+      iri = coerce(input)
+      key, host, scheme, shape = cluster_key(iri)
+      cluster = @clusters[key] ||= Cluster.new(
+        key:    key,
+        host:   host,
+        scheme: scheme,
+        shape:  shape,
+      )
+      cluster.add(iri)
+      cluster
+    end
+
+    def clusters
+      @clusters.values
+    end
+
+    def size
+      @clusters.size
+    end
+
+    # Returns a per-segment explanation for the input, merging classifier
+    # output with what we've observed in its cluster (i.e. positions that
+    # are factually stable get marked variable: false even if classifier
+    # would otherwise call them variable).
+    def explain(input)
+      iri = coerce(input)
+      key, * = cluster_key(iri)
+      cluster = @clusters[key]
+      stats   = cluster ? cluster.segment_stats : []
+
+      iri.path_segments.each_with_index.map do |seg, i|
+        type   = @classifier.classify(seg)
+        stable = stats[i] && stats[i][:stable]
+        {
+          value:    seg,
+          type:     type,
+          variable: !stable && @classifier.variable?(type),
+          stable:   !!stable,
+        }
+      end
+    end
+
+    private
+
+    def coerce(input)
+      input.is_a?(Identifier) ? input : Parser.parse(input)
+    end
+
+    def cluster_key(iri)
+      if iri.urn?
+        ns, value = (iri.nss || "").split(":", 2)
+        shape = if value
+          type = @classifier.classify(value)
+          @classifier.variable?(type) ? "{#{type}}" : value
+        end
+        key = "urn:#{ns}:#{shape}"
+        [key, nil, "urn", key]
+      else
+        shape = PathShape.new(classifier: @classifier).for(iri.path_segments)
+        key   = "#{iri.scheme}://#{iri.host}#{shape}"
+        [key, iri.host, iri.scheme, shape]
+      end
+    end
+  end
+end

data/lib/iriq/errors.rb

@@ -0,0 +1,4 @@
+module Iriq
+  class Error < StandardError; end
+  class ParseError < Error; end
+end

data/lib/iriq/explanation.rb

@@ -0,0 +1,45 @@
+module Iriq
+  # Builds a per-segment explanation for a single identifier.
+  #
+  #   Explanation.explain("https://foo.com/users/123")
+  #   # => [
+  #   #      { value: "users", type: :literal,    variable: false },
+  #   #      { value: "123",   type: :integer_id, variable: true },
+  #   #    ]
+  module Explanation
+    module_function
+
+    def explain(input, classifier: SegmentClassifier.new)
+      iri = input.is_a?(Identifier) ? input : Parser.parse(input)
+
+      if iri.urn?
+        explain_urn(iri, classifier)
+      else
+        iri.path_segments.map { |s| segment_entry(s, classifier) }
+      end
+    end
+
+    def segment_entry(segment, classifier)
+      type = classifier.classify(segment)
+      {
+        value:    segment,
+        type:     type,
+        variable: classifier.variable?(type),
+      }
+    end
+
+    def explain_urn(iri, classifier)
+      return [] unless iri.nss
+
+      if iri.nss.include?(":")
+        ns, value = iri.nss.split(":", 2)
+        [
+          { value: ns, type: :literal, variable: false },
+          segment_entry(value, classifier),
+        ]
+      else
+        [segment_entry(iri.nss, classifier)]
+      end
+    end
+  end
+end

data/lib/iriq/identifier.rb

@@ -0,0 +1,64 @@
+module Iriq
+  # Parsed identifier. Stores the original input alongside the structured fields
+  # extracted by the parser.
+  #
+  # For URN-style inputs (`urn:isbn:0451450523`) only `scheme` and `nss` (the
+  # Namespace Specific String) are populated; host/path are nil.
+  class Identifier
+    attr_reader :original, :scheme, :host, :port, :path,
+                :path_segments, :query, :query_params, :fragment,
+                :nss, :kind
+
+    def initialize(original:, scheme: nil, host: nil, port: nil, path: nil,
+                   path_segments: [], query: nil, query_params: {},
+                   fragment: nil, nss: nil, kind: :url)
+      @original      = original
+      @scheme        = scheme
+      @host          = host
+      @port          = port
+      @path          = path
+      @path_segments = path_segments
+      @query         = query
+      @query_params  = query_params
+      @fragment      = fragment
+      @nss           = nss
+      @kind          = kind
+    end
+
+    def urn?
+      kind == :urn
+    end
+
+    def url?
+      kind == :url
+    end
+
+    # Rebuild a canonical IRI-like string from the parsed fields. Preserves
+    # Unicode display form (no punycode / percent-encoding pass).
+    def canonical
+      if urn?
+        "urn:#{nss}"
+      else
+        out = +""
+        out << "#{scheme}://" if scheme
+        out << host if host
+        out << ":#{port}" if port
+        out << "/" + path_segments.join("/") if path_segments.any?
+        out << "?#{query}" if query && !query.empty?
+        out << "##{fragment}" if fragment && !fragment.empty?
+        out
+      end
+    end
+
+    alias to_s canonical
+
+    def ==(other)
+      other.is_a?(Identifier) && other.canonical == canonical
+    end
+    alias eql? ==
+
+    def hash
+      canonical.hash
+    end
+  end
+end

data/lib/iriq/normalizer.rb

@@ -0,0 +1,49 @@
+module Iriq
+  # Produces a canonical, shape-aware string for an identifier.
+  #
+  #   Normalizer.normalize("https://Foo.com:443/users/123")
+  #   # => "https://foo.com/users/{integer_id}"
+  #
+  # The form is intended for grouping/diffing — it is not a round-trippable URL.
+  module Normalizer
+    module_function
+
+    def normalize(input, classifier: SegmentClassifier.new)
+      iri = input.is_a?(Identifier) ? input : Parser.parse(input)
+      normalize_identifier(iri, classifier: classifier)
+    end
+
+    def normalize_identifier(iri, classifier: SegmentClassifier.new)
+      if iri.urn?
+        # urn:isbn:0451450523 -> urn:isbn:{integer_id}
+        if iri.scheme == "urn" && iri.nss && iri.nss.include?(":")
+          ns, value = iri.nss.split(":", 2)
+          type      = classifier.classify(value)
+          shaped    = classifier.variable?(type) ? "{#{type}}" : value
+          "urn:#{ns}:#{shaped}"
+        else
+          iri.canonical
+        end
+      else
+        out = +""
+        out << "#{iri.scheme}://" if iri.scheme
+        out << iri.host if iri.host
+        out << ":#{iri.port}" if iri.port
+        out << PathShape.new(classifier: classifier).for(iri.path_segments)
+        if iri.query_params && !iri.query_params.empty?
+          out << "?" + shape_query(iri.query_params, classifier)
+        end
+        out
+      end
+    end
+
+    def shape_query(params, classifier)
+      params.keys.sort.map do |k|
+        v    = params[k]
+        type = classifier.classify(v.to_s)
+        shaped = classifier.variable?(type) ? "{#{type}}" : v
+        "#{k}=#{shaped}"
+      end.join("&")
+    end
+  end
+end

data/lib/iriq/parser.rb

@@ -0,0 +1,141 @@
+module Iriq
+  # Lightweight, Unicode-aware parser for URL/IRI/URN inputs.
+  #
+  # Intentionally NOT a full RFC 3986 / 3987 / WHATWG URL implementation. We
+  # accept enough of the common shapes (URLs, scheme-less hosts, URNs, raw
+  # Unicode hosts and paths) to support normalization and clustering.
+  module Parser
+    SCHEME_RE = /\A([a-zA-Z][a-zA-Z0-9+\-.]*):/.freeze
+
+    # Matches a host-ish first token before the first slash. We deliberately
+    # allow any non-ASCII character so IRIs work without punycode.
+    HOSTISH_RE = %r{
+      \A
+      (?<host>[^/?#\s:]+\.[^/?#\s:]+|localhost)  # something.something or localhost
+      (?::(?<port>\d+))?
+      (?<rest>[/?#].*)?
+      \z
+    }x.freeze
+
+    DEFAULT_PORTS = {
+      "http"  => 80,
+      "https" => 443,
+      "ftp"   => 21,
+      "ws"    => 80,
+      "wss"   => 443,
+    }.freeze
+
+    module_function
+
+    def parse(input)
+      raise ParseError, "input is nil" if input.nil?
+      raise ParseError, "input must be a String" unless input.is_a?(String)
+
+      stripped = input.strip
+      raise ParseError, "input is empty" if stripped.empty?
+
+      if (m = stripped.match(SCHEME_RE))
+        scheme = m[1].downcase
+        rest   = stripped[m[0].length..]
+
+        if scheme == "urn"
+          parse_urn(input, rest)
+        elsif rest.start_with?("//")
+          parse_authority_url(input, scheme, rest[2..])
+        else
+          # opaque scheme like mailto:foo@bar — keep nss, mark as urn-ish so we
+          # don't pretend we know its host/path layout.
+          Identifier.new(original: input, scheme: scheme, nss: rest, kind: :urn)
+        end
+      else
+        # No scheme. If it looks like a hostname, assume https.
+        if HOSTISH_RE.match?(stripped)
+          parse_authority_url(input, "https", stripped)
+        else
+          raise ParseError, "cannot parse #{input.inspect}: no scheme and no host-like prefix"
+        end
+      end
+    end
+
+    def parse_urn(original, rest)
+      raise ParseError, "urn missing namespace" if rest.nil? || rest.empty?
+
+      Identifier.new(original: original, scheme: "urn", nss: rest, kind: :urn)
+    end
+
+    def parse_authority_url(original, scheme, remainder)
+      m = remainder.match(HOSTISH_RE) || remainder.match(%r{\A(?<host>[^/?#]+?)(?::(?<port>\d+))?(?<rest>[/?#].*)?\z})
+      raise ParseError, "cannot parse authority from #{original.inspect}" unless m
+
+      host = m[:host].downcase
+      port = m[:port]&.to_i
+      port = nil if port && DEFAULT_PORTS[scheme] == port
+
+      rest = m[:rest] || ""
+      path, query, fragment = split_path_query_fragment(rest)
+      segments = path_segments(path)
+
+      Identifier.new(
+        original:      original,
+        scheme:        scheme,
+        host:          host,
+        port:          port,
+        path:          "/" + segments.join("/"),
+        path_segments: segments,
+        query:         query,
+        query_params:  parse_query(query),
+        fragment:      fragment,
+        kind:          :url,
+      )
+    end
+
+    def split_path_query_fragment(rest)
+      path     = rest
+      query    = nil
+      fragment = nil
+
+      if (idx = path.index("#"))
+        fragment = path[(idx + 1)..]
+        path     = path[0...idx]
+      end
+
+      if (idx = path.index("?"))
+        query = path[(idx + 1)..]
+        path  = path[0...idx]
+      end
+
+      [path, query, fragment]
+    end
+
+    # Apply dot-segment normalization (RFC 3986 §5.2.4, lightweight version)
+    # and drop empty segments from leading/trailing/duplicate slashes.
+    def path_segments(path)
+      return [] if path.nil? || path.empty? || path == "/"
+
+      raw = path.sub(%r{\A/}, "").split("/")
+      out = []
+      raw.each do |seg|
+        case seg
+        when "", "."
+          next
+        when ".."
+          out.pop
+        else
+          out << seg
+        end
+      end
+      out
+    end
+
+    def parse_query(query)
+      return {} if query.nil? || query.empty?
+
+      query.split("&").each_with_object({}) do |pair, acc|
+        k, v = pair.split("=", 2)
+        next if k.nil? || k.empty?
+
+        acc[k] = v
+      end
+    end
+  end
+end

data/lib/iriq/path_shape.rb

@@ -0,0 +1,27 @@
+module Iriq
+  # Converts a sequence of path segments into a route-shape string by
+  # replacing variable segments with `{type}` placeholders.
+  #
+  #   PathShape.for(["users", "123", "orders", "456"])
+  #   # => "/users/{integer_id}/orders/{integer_id}"
+  class PathShape
+    def initialize(classifier: SegmentClassifier.new)
+      @classifier = classifier
+    end
+
+    def for(segments)
+      return "/" if segments.nil? || segments.empty?
+
+      "/" + segments.map { |s| shape_segment(s) }.join("/")
+    end
+
+    def shape_segment(segment)
+      type = @classifier.classify(segment)
+      @classifier.variable?(type) ? "{#{type}}" : segment
+    end
+
+    def self.for(segments, classifier: SegmentClassifier.new)
+      new(classifier: classifier).for(segments)
+    end
+  end
+end

data/lib/iriq/segment_classifier.rb

@@ -0,0 +1,54 @@
+module Iriq
+  # Heuristic classifier for individual path segments and query values.
+  #
+  # Returns a symbol from the known TYPES set. Order matters: the first
+  # matching rule wins.
+  class SegmentClassifier
+    TYPES = %i[literal integer_id uuid date timestamp hash slug opaque_id].freeze
+
+    UUID_RE      = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/.freeze
+    INTEGER_RE   = /\A\d+\z/.freeze
+    DATE_RE      = /\A\d{4}-\d{2}-\d{2}\z/.freeze
+    ISO_TIME_RE  = /\A\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+\-]\d{2}:?\d{2})?\z/.freeze
+    HASH_RE      = /\A\h{32,}\z/.freeze
+    SLUG_RE      = /\A[a-z0-9]+(?:[-_][a-z0-9]+)+\z/.freeze
+    LITERAL_RE   = /\A[\p{L}][\p{L}\p{M}_]*\z/u.freeze
+    OPAQUE_RE    = /\A[A-Za-z0-9_\-.~]{4,}\z/.freeze
+
+    # Plausible UNIX timestamps (10 digit seconds or 13 digit ms) from
+    # roughly 2001 onward.
+    TS_SECONDS_RANGE = 1_000_000_000..9_999_999_999
+    TS_MILLIS_RANGE  = 1_000_000_000_000..9_999_999_999_999
+
+    def classify(segment)
+      return :literal if segment.nil? || segment.empty?
+
+      case segment
+      when UUID_RE     then :uuid
+      when DATE_RE     then :date
+      when ISO_TIME_RE then :timestamp
+      when INTEGER_RE  then classify_integer(segment)
+      when HASH_RE     then :hash
+      when SLUG_RE     then :slug
+      when LITERAL_RE  then :literal
+      when OPAQUE_RE   then :opaque_id
+      else :literal
+      end
+    end
+
+    # Anything except :literal is considered variable for shape/explain.
+    def variable?(type)
+      type != :literal
+    end
+
+    private
+
+    def classify_integer(segment)
+      n = segment.to_i
+      return :timestamp if TS_MILLIS_RANGE.cover?(n)
+      return :timestamp if TS_SECONDS_RANGE.cover?(n)
+
+      :integer_id
+    end
+  end
+end

data/lib/iriq/version.rb

@@ -0,0 +1,3 @@
+module Iriq
+  VERSION = "0.0.1"
+end

data/lib/iriq.rb

@@ -0,0 +1,27 @@
+require "iriq/version"
+require "iriq/errors"
+require "iriq/identifier"
+require "iriq/parser"
+require "iriq/segment_classifier"
+require "iriq/path_shape"
+require "iriq/normalizer"
+require "iriq/explanation"
+require "iriq/cluster"
+require "iriq/clusterer"
+require "iriq/cli"
+
+module Iriq
+  class << self
+    def parse(input)
+      Parser.parse(input)
+    end
+
+    def normalize(input)
+      Normalizer.normalize(input)
+    end
+
+    def explain(input)
+      Explanation.explain(input)
+    end
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: iriq
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Daniel Pepper
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: rspec-debugging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: Semantic IRI/URI/URL/URN parsing, normalization, classification, and
+  clustering.
+executables:
+- iriq
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- exe/iriq
+- iriq.gemspec
+- lib/iriq.rb
+- lib/iriq/cli.rb
+- lib/iriq/cluster.rb
+- lib/iriq/clusterer.rb
+- lib/iriq/errors.rb
+- lib/iriq/explanation.rb
+- lib/iriq/identifier.rb
+- lib/iriq/normalizer.rb
+- lib/iriq/parser.rb
+- lib/iriq/path_shape.rb
+- lib/iriq/segment_classifier.rb
+- lib/iriq/version.rb
+homepage: https://github.com/dpep/iriq
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Semantic IRI normalization and clustering.
+test_files: []