scout-essentials 1.8.7 → 1.9.0

data/doc/IndiferentHash.md

@@ -1,240 +0,0 @@
-# IndiferentHash
-
-IndiferentHash provides Hash utilities and a mixin that makes hash access indifferent to String vs Symbol keys. It also includes a set of helper utilities for parsing, merging and transforming option hashes used across the framework.
-
-Two main pieces:
-- IndiferentHash mixin (extend any Hash instance with IndiferentHash to get indifferent access behavior and extra hash helpers).
-- CaseInsensitiveHash mixin (separate mixin to allow case-insensitive string keys).
-
----
-
-## Quick usage
-
-Make a Hash indifferent (string/symbol interchangeable):
-
-```ruby
-h = { a: 1, "b" => 2 }
-IndiferentHash.setup(h)   # returns h extended with IndiferentHash
-
-h[:a]      # => 1
-h["a"]     # => 1
-h[:b]      # => 2
-h["b"]     # => 2
-```
-
-Make a Hash case-insensitive (string keys compared case-insensitively):
-
-```ruby
-h = { a: 1, "b" => 2 }
-CaseInsensitiveHash.setup(h)
-
-h[:a]      # => 1
-h["A"]     # => 1
-h[:A]      # => 1
-h["B"]     # => 2
-```
-
----
-
-## IndiferentHash mixin (methods added to a Hash)
-
-Call IndiferentHash.setup(hash) to extend a hash instance.
-
-Behavior highlights:
-- Access by Symbol or String: h[:k] and h["k"] resolve to the same entry when possible.
-- Nested hashes returned from [] are automatically set up with IndiferentHash.
-- Values are stored normally, but deletion and inclusion checks accept Symbol/String interchangeably.
-
-Methods and behaviors:
-
-- IndiferentHash.setup(hash)
-  - Extends the given hash with IndiferentHash and returns it.
-
-- merge(other)
-  - Returns a new IndiferentHash with keys from self merged with other (other wins). The result is an IndiferentHash.
-
-- deep_merge(other)
-  - Recursively merges nested hashes: if both have same key and values are hash-like, merges them deeply (preserving IndiferentHash behavior on nested hashes).
-
-- [](key)
-  - Returns value for key. If not found directly, attempts the alternate form:
-    - If given Symbol/Module, will try the String key.
-    - If given String, will try the Symbol key.
-  - If the value is itself a Hash, it will be extended with IndiferentHash before returning.
-  - Note: behavior pays attention to hash default/default_proc. If a default exists and the key isn't explicitly present in keys, it returns the default without attempting alternative forms.
-
-- []=(key, value)
-  - Deletes any existing matching key (either symbol or string) before setting the new one. This avoids duplicate representations of the same logical key.
-
-- values_at(*keys)
-  - Returns an array of values for the provided keys (indifferent to symbol/string form).
-
-- include?(key)
-  - Returns true if either symbol or string form exists.
-
-- delete(key)
-  - Deletes by key; will try symbol and string form and return deleted value if found.
-
-- clean_version
-  - Produces a plain Ruby hash where keys are strings (stringified keys), preferring the first occurrence.
-
-- slice(*keys)
-  - Returns a new IndiferentHash containing only the requested keys. Accepts symbol or string forms; ensures both forms are considered.
-
-- keys_to_sym! and keys_to_sym
-  - keys_to_sym! converts string keys in-place to symbols (best-effort; rescue on any failed conversion).
-  - keys_to_sym returns a new IndiferentHash with keys converted to symbols.
-
-- prety_print
-  - A convenience wrapper that calls Misc.format_definition_list(self, sep: "\n") (keeps existing behavior/name `prety_print` as in code).
-
-- except(*list)
-  - Returns a hash copy excluding provided keys. Accepts symbol/string forms; returns a result consistent with Hash#except but extended to be indifferent.
-
-Notes:
-- The implementation ensures nested hashes returned from [] or merges are set up with IndiferentHash automatically.
-- Some method names are intentionally spelled as in the implementation (`prety_print`).
-
----
-
-## CaseInsensitiveHash
-
-A separate mixin to make key lookup case-insensitive (for string keys). Use CaseInsensitiveHash.setup(hash) to extend a hash.
-
-Behavior:
-- On lookup, it first tries the provided key directly. If no value, it converts the key to lowercase string and looks up a precomputed map (original_key_by_downcase) to find the actual stored key. This permits "A" and "a" to refer to the same entry.
-- values_at returns values for provided keys using the case-insensitive lookup.
-
-Example:
-
-```ruby
-h = { a: 1, "b" => 2 }
-CaseInsensitiveHash.setup(h)
-
-h["A"]  # => 1
-h[:A]   # => 1
-h["B"]  # => 2
-```
-
----
-
-## Options helpers (IndiferentHash::Options functions)
-
-These utilities are useful for parsing and handling option hashes and strings.
-
-- add_defaults(options, defaults = {})
-  - Ensures options is an IndiferentHash, accepts defaults as Hash or string (string gets parsed). Adds defaults only for keys not present in options.
-  - Returns the options (modified/extended).
-
-- process_options(hash, *keys)
-  - Sets up IndiferentHash on hash.
-  - If the last argument is a Hash, it is used as defaults (added first).
-  - If a single key passed, returns and removes that key from hash (prefers symbol then string).
-  - If multiple keys passed, returns array of removed values for each key.
-  - Example: IndiferentHash.process_options(h, :limit) or IndiferentHash.process_options(h, :a, :b, default: 1)
-
-- pull_keys(hash, prefix)
-  - Pulls keys with prefix_... from hash and returns a new IndiferentHash with the suffixes as keys.
-  - Also consumes "#{prefix}_options" if present and merges into result.
-  - Example: given { foo_bar: 1, "foo_x" => 2 }, pull_keys(h, :foo) => { bar: 1, x: 2 } (keys matched as string/symbol appropriately).
-
-- zip2hash(list1, list2)
-  - Zips two lists into a hash (keys from list1, values from list2) and sets it up as IndiferentHash.
-
-- positional2hash(keys, *values)
-  - Converts positional values into a hash keyed by keys.
-  - Supports the common pattern where the last argument is a Hash of extra/defaults. In that case:
-    - Combines given values into a hash, removes nil/empty values, adds defaults from the extras, and prunes keys not in the original keys set.
-  - Example: IndiferentHash.positional2hash([:one,:two], 1, two: 2, extra: 4) => { one: 1, two: 2 }
-
-- array2hash(array, default = nil)
-  - Accepts an array of [key, value] pairs and builds an IndiferentHash.
-  - If value is nil and default provided, uses a dup of default for that key.
-
-- process_to_hash(list) { |list| ... }
-  - Yields list to block, expects a result list; zips original list with returned list into an IndiferentHash.
-
-- hash2string(hash)
-  - Serializes a simple hash into a string representation (sorted by key). Only handles values of certain simple classes; others are omitted. Uses ":" prefix for symbol keys/values in output.
-  - Output format is key=value pairs joined with "#".
-
-- string2hash(string, sep = "#")
-  - Parses the string produced by hash2string (or similar) and converts back into an IndiferentHash. Supports:
-    - :symbol keys/values (leading ":")
-    - quoted strings, integers, floats, booleans, regexps (/.../)
-    - empty values treated as true
-  - Example roundtrip: IndiferentHash.string2hash(IndiferentHash.hash2string(h)) == h (for supported types).
-
-- parse_options(str)
-  - Parses a shell-like option string of key=value pairs, supporting quoted values and comma-separated lists (preserving quoted items with spaces).
-  - Returns an IndiferentHash.
-  - Example: IndiferentHash.parse_options('blueberries=true title="This is a title" list=one,two,"and three"')
-
-- print_options(options)
-  - Serializes an options hash into a space-separated string of key=value pairs; array values become CSV (properly quoted if containing spaces).
-
----
-
-## Examples (from tests and usage)
-
-Indifferent access:
-
-```ruby
-h = { a: 1, "b" => 2 }
-IndiferentHash.setup(h)
-h[:a]  # => 1
-h["a"] # => 1
-h["b"] # => 2
-h[:b]  # => 2
-```
-
-Deep merge:
-
-```ruby
-o = { h: { a: 1, b: 2 } }
-n = { h: { c: 3 } }
-IndiferentHash.setup(o)
-o2 = o.deep_merge(n)
-o2[:h]["a"]  # => 1
-o2[:h]["c"]  # => 3
-```
-
-Options parsing:
-
-```ruby
-opts = IndiferentHash.parse_options('blueberries=true title="A title" list=one,two,"and three"')
-opts["title"]                # => "A title"
-opts["list"]                 # => ["one", "two", "and three"]
-```
-
-String <-> hash roundtrip:
-
-```ruby
-h = { a: 1, b: :sym, c: true }
-s = IndiferentHash.hash2string(h)
-h2 = IndiferentHash.string2hash(s)
-# h2 should equal h for the supported/simple types
-```
-
-pull_keys example:
-
-```ruby
-h = { "foo_bar" => 1, :foo_baz => 2, "other" => 3 }
-IndiferentHash.setup(h)
-prefixed = IndiferentHash.pull_keys(h, :foo)
-# prefixed => { "bar" => 1, :baz => 2 } (returned as IndiferentHash)
-# and h no longer contains those entries
-```
-
----
-
-## Implementation notes / caveats
-
-- IndiferentHash.setup extends a single hash instance (not the Hash class). Use it on any hash instance you want to treat indifferently.
-- Nested hashes returned from [] or created by zip/positional helpers get extended automatically with IndiferentHash.
-- The [] lookup has special handling with Hash defaults: if the hash has a default or default_proc
-  and the requested key is not present in keys, it will return the default without trying the alternate symbol/string form.
-- CaseInsensitiveHash is independent of IndiferentHash; you can mix both if needed, but their behaviors are separate.
-- Some helper names are spelled as in the codebase (e.g., prety_print), used for compatibility.
-
-This module covers common patterns required for flexible option handling in the framework: indifferent access, easy merging and defaulting, parsing/printing option strings, and extracting prefixed option subsets.

data/doc/Log.md

@@ -1,235 +0,0 @@
-# Log
-
-The Log module is the framework-wide logging and progress utility. It provides:
-- leveled logging (DEBUG, LOW, MEDIUM, HIGH, INFO, WARN, ERROR, NONE)
-- colored output and utilities for color manipulation and gradients
-- fingerprinting for compact object summaries
-- a rich ProgressBar facility with multi-bar, ETA and history support
-- helpers to trap and ignore stdout/stderr and to direct logs to a logfile
-- convenience debug/inspect helpers
-
-Files / components:
-- log.rb — core logging API, level handling, formatting, logfile control
-- log/color.rb — integration with Term::ANSIColor and concept color mapping
-- log/color_class.rb — Color class for hex color parsing, blending, lightening/darkening
-- log/fingerprint.rb — compact fingerprint representations for many object types
-- log/progress{.rb, /util, /report} — ProgressBar implementation and helpers
-- log/trap.rb — utilities to trap/ignore STDOUT/STDERR
-
----
-
-## Configuration & Environment
-
-- Log.severity (module attribute): current logging level threshold. Messages below this level are ignored.
-- SEVERITY constants: DEBUG, LOW, MEDIUM, HIGH, INFO, WARN, ERROR, NONE (assigned 0..7).
-  - Use Log.get_level(value) to convert numeric/string/symbol into numeric level.
-- Default severity:
-  - Determined by environment variable `SCOUT_LOG` if set to one of the level names.
-  - Otherwise read from `~/.scout/etc/log_severity` if present, else INFO.
-- Color disabled if `ENV["SCOUT_NOCOLOR"] == 'true'` or SOPT.nocolor set.
-- Log.tty_size returns terminal rows (uses IO.console.winsize or `tput li`), falls back to ENV["TTY_SIZE"] or 80.
-- Log.logfile(file_or_io) — set logfile target:
-  - Passing a String opens the file in append mode, sync=true.
-  - Passing an IO or File sets that as the logfile.
-  - If not set, logging writes to STDERR.
-- Thread-safety: Log.log_write and Log.log_puts synchronize writes via MUTEX.
-
----
-
-## Coloring & Color utilities
-
-- Log extends Term::ANSIColor and exposes helpers:
-  - Log.color(color, str = nil, reset = false)
-    - color can be:
-      - Symbol naming an ansi color (e.g. :green)
-      - Integer index into SEVERITY_COLOR
-      - Concept color name (Log.CONCEPT_COLORS map keys like :title, :path, :value)
-      - A Color/hex handled by Color class (indirectly via Colorize)
-    - If str is nil, returns only the color control string (unless nocolor true).
-    - If nocolor is true, returns str unchanged.
-  - Log.highlight(str = nil): returns HIGHLIGHT sequence or wraps string.
-  - Log.uncolor(str) — strips ANSI color sequences.
-
-- Color utilities:
-  - Color class (log/color_class.rb) handles hex parsing, lighten/darken/blend and returns hex strings.
-  - Colorize module (log/color.rb) provides:
-    - Color selection by name (Colorize.from_name),
-    - continuous gradient generation (Colorize.continuous),
-    - gradient/rank mapping and distinct color mapping for categorical values,
-    - TSV coloring helpers.
-
-- Concept color map:
-  - Log.CONCEPT_COLORS (IndiferentHash) maps logical concepts to ANSI colors (e.g. :title => magenta).
-
----
-
-## Basic Logging API
-
-Main functions:
-
-- Log.log(message = nil, severity = MEDIUM, &block)
-  - Adds newline (if missing) and delegates to Log.logn.
-  - Skips if severity < Log.severity.
-
-- Log.logn(message = nil, severity = MEDIUM, &block)
-  - Emits formatted message without appending newline.
-  - Prefix includes timestamp and severity tag inside color.
-  - Uses Log.color to color the line. Messages with severity >= INFO are wrapped in Log.highlight.
-  - Writes via Log.log_write (synchronized).
-
-- Convenience wrappers:
-  - Log.debug(msg), Log.low(msg), Log.medium(msg), Log.high(msg), Log.info(msg), Log.warn(msg), Log.error(msg)
-    - Each calls Log.log with the corresponding severity.
-
-- Log.exception(e)
-  - Nicely logs an exception: formats message and backtrace using Log.fingerprint for very long messages and Log.color_stack for colored backtrace output. Honors environment `SCOUT_ORIGINAL_STACK` for ordering.
-
-- Log.get_level(level)
-  - Accepts Numeric, String (case-insensitive), or Symbol and returns numeric level or 0/nil.
-
-- Log.with_severity(level) { ... }
-  - Temporarily sets Log.severity for the block.
-
-- Log.log_obj_inspect(obj, level, file = $stdout)
-  - Logs caller location and obj.inspect at given level.
-
-- Log.log_obj_fingerprint(obj, level, file = $stdout)
-  - Logs caller location and Log.fingerprint(obj) for compact summary.
-
-- Line/terminal helpers:
-  - Log.up_lines(n), Log.down_lines(n), Log.return_line, Log.clear_line(out = STDOUT)
-
----
-
-## Fingerprinting
-
-- Log.fingerprint(obj) produces a compact human-readable representation useful in logs:
-  - Strings are truncated with an MD5 snippet if longer than FP_MAX_STRING (150).
-  - Arrays and Hashes are truncated beyond FP_MAX_ARRAY / FP_MAX_HASH.
-  - Special handling for IO/File, Float formatting, Thread names, Symbol, nil/true/false etc.
-  - Used by other logging helpers to keep outputs concise.
-
----
-
-## Progress bars
-
-The ProgressBar is a full-featured facility for reporting progress from concurrent tasks.
-
-Key pieces:
-- Use Log::ProgressBar.with_bar(max_or_options, options = {}) {|bar| ... } to create a managed bar.
-  - new_bar(max, options) creates a bar; with_bar ensures removal on exit unless KeepBar is raised.
-- ProgressBar instance attributes:
-  - max, ticks, frequency, depth, desc, file, bytes, process, callback, severity
-- Behavior:
-  - bar.init — initialize and print first state.
-  - bar.tick(step = 1) — increment ticks and possibly report (depending on frequency and percent progress).
-  - bar.pos(position) — set bar to a specific position (pos - ticks).
-  - bar.process(elem) — calls `process` callback and interprets return to tick/pos based on type.
-  - bar.percent — computes percent (0..100).
-  - Bars are managed centrally in ProgressBar::BARS with concurrency via BAR_MUTEX.
-  - Bars can be nested (depth management), silenced, removed, persisted via `file` (save/load YAML state).
-  - ProgressBar.report and ProgressBar.report_msg produce formatted output lines including per-second rate, ETA, used time and ticks.
-
-Helpers:
-- ProgressBar.get_obj_bar(obj, bar) — helper to create a meaningful bar given an object (TSV, File, Array, Path, etc.) — guesses max records by inspecting file/TSV length if possible.
-- ProgressBar.with_obj_bar(obj, bar = true) — convenience wrapper around with_bar using a guessed max.
-
-Notes:
-- Progress printing will skip if Log.no_bar is true (set via environment SCOUT_NO_PROGRESS or Log.no_bar=).
-- ProgressBar persistence: if `file` option provided, the bar saves state to YAML.
-
----
-
-## Trapping / ignoring STDOUT and STDERR
-
-- Log.trap_std(msg = "STDOUT", msge = "STDERR", severity = 0, severity_err = nil) { ... }
-  - Redirects STDOUT/STDERR into pipes; background threads read and call Log.logn on captured lines with provided severity and prefix.
-  - Useful to capture external command output or to consolidate prints into the log.
-
-- Log.trap_stderr(msg = "STDERR", severity = 0) { ... }
-  - Captures only STDERR and logs it.
-
-- Log.ignore_stderr { ... } / Log.ignore_stdout { ... }
-  - Redirects respective stream to /dev/null for the block (silences output). Safe fallback if /dev/null missing.
-
-These functions restore original streams when the block ends even if exceptions occur.
-
----
-
-## Convenience debug/inspect helpers
-
-Global helper methods (defined outside Log) for quick debugging:
-
-- ppp(message) — pretty print (with color) and file/line location
-- fff(object) — debug printing fingerprint (using Log.debug)
-- ddd(obj, file = $stdout) — Log.log_obj_inspect(obj, :debug)
-- lll(obj, file = $stdout) — low-level inspect wrapper
-- mmm, iii, wwww, eee — wrappers for different severities (medium, info, warn, error)
-- ddf/mmf/llf/iif/wwwf/eef — wrappers calling log_obj_fingerprint at different severities
-- sss(level) { } — temporarily set severity or set it if no block
-- ccc(obj=nil) — conditional debug printing based on $scout_debug_log (used as ad-hoc toggle)
-
-These are small helpers used in tests (e.g., iif :foo writes INFO lines).
-
----
-
-## Examples
-
-Basic logging:
-```ruby
-Log.severity = Log::DEBUG
-Log.info "Starting task"
-Log.debug { "Expensive debug only evaluated when level allows" }
-Log.error "Something failed"
-```
-
-Exception handling:
-```ruby
-begin
-  raise "boom"
-rescue => e
-  Log.exception(e)
-end
-```
-
-Progress bar:
-```ruby
-Log::ProgressBar.with_bar(100, desc: "Processing") do |bar|
-  100.times do
-    bar.tick
-    # work...
-  end
-end
-```
-
-Trap STDOUT/STDERR block:
-```ruby
-Log.trap_std("OUT", "ERR", Log::INFO, Log::WARN) do
-  system("some_command")
-end
-```
-
-Set logfile:
-```ruby
-Log.logfile("/tmp/mylog.txt")
-Log.info "Wrote to logfile"
-```
-
-Fingerprint:
-```ruby
-s = "a very long string..."
-Log.debug Log.fingerprint(s)   # compact representation for logs
-```
-
----
-
-## Implementation notes & caveats
-
-- Colors: if nocolor is enabled (env or Log.nocolor), color helpers return raw strings.
-- Log.log_write and Log.log_puts are synchronized to avoid interleaved writes from threads.
-- Log.logn uses caller and Log.last_caller to attempt to find meaningful source location for messages in stack traces.
-- Fingerprint logic truncates long strings and large arrays/hashes to keep logs readable.
-- ProgressBar uses a central registry (BARS) and a mutex for concurrency; nested bars are supported.
-- The Log module depends on utility modules (Misc, IndiferentHash, TSV, Path, etc.) for some features — when used in isolation, those parts may not be available.
-
-This document summarizes the Log module capabilities and usage. Use Log for all script-level diagnostic output, and use ProgressBar for long running operations where periodic status and ETA are useful.

data/doc/NamedArray.md

@@ -1,174 +0,0 @@
-# NamedArray
-
-NamedArray is a small utility mixin built on top of the Annotation system that gives arrays named fields and name-based accessors. It lets you treat an Array like a record/tuple where elements can be accessed by name (symbol or string), supports fuzzy name matching, conversion to a hash (indifferent to string/symbol keys), and provides helpers for zipping/combining lists of named values.
-
-NamedArray extends Annotation and declares two annotation attributes:
-- fields — an ordered list of names for each position in the array
-- key — an optional primary key field name
-
-Since NamedArray extends Annotation, you can apply it to an array via NamedArray.setup(array, fields, key: ...), or by extending an instance.
-
-Examples:
-```ruby
-a = NamedArray.setup([1,2], [:a, :b])
-a[:a]    # => 1
-a["b"]   # => 2
-a.a      # => 1   # method_missing lookup
-a.to_hash  # => IndiferentHash { a: 1, b: 2 }
-```
-
-## Core instance API
-
-- fields, key
-  - Provided by Annotation (accessors). fields is an Array of field names associated with array positions.
-
-- all_fields
-  - Returns [key, fields].compact.flatten — useful if you want the key included with other fields.
-
-- [](name_or_index)
-  - Accepts a field name (symbol or string) or numeric index. Name is resolved to a numeric position via identify_name; if unresolved returns nil.
-  - Example: a[:a], a["a"], a[0]
-
-- []=(name_or_index, value)
-  - Sets element by name (resolved to a position) or index; returns nil if name not found.
-
-- positions(fields)
-  - Resolve one or many fields to their positions (delegates to NamedArray.identify_name).
-
-- values_at(*positions)
-  - Accepts named fields or positions; it will translate names to indices before calling Array#values_at.
-
-- concat(other)
-  - If other is a Hash: appends values of the hash in iteration order and adds the hash keys to this array's fields list.
-    Example:
-      a.concat({c: 3, d: 4})  # adds 3 and 4 to array and [:c, :d] to fields
-  - If other is another NamedArray: standard concat and fields from other are appended.
-  - Otherwise behaves like Array#concat.
-
-- to_hash
-  - Returns a hash mapping fields => value for each field position. The returned hash is extended with IndiferentHash (so both string and symbol lookups work).
-  - Example: a.to_hash[:a] => 1
-
-- prety_print
-  - Convenience pretty-print wrapper: uses Misc.format_definition_list(self.to_hash, sep: "\n").
-
-- method_missing(name, *args)
-  - If name resolves to a field (via identify_name) returns self[name]; otherwise calls super. This gives quick accessors like a.foo
-
-## Name resolution and matching
-
-NamedArray provides flexible name resolution via:
-
-- NamedArray.identify_name(names, selected, strict: false)
-  - names: array of field names (usually the NamedArray#fields)
-  - selected: value to resolve — may be nil, Range, Integer, Symbol, or String
-  - Returns:
-    - Integer index (position) for a single field selection
-    - Range (unchanged) if a Range is passed
-    - 0 for nil (treat nil as first field)
-    - :key for Symbol :key (special sentinel)
-    - nil if unresolved
-
-Resolution rules:
-- nil => 0
-- Range => returned as-is
-- Integer => returned as-is
-- Symbol:
-  - if :key => returns :key
-  - otherwise finds first field whose to_s equals the symbol name
-- String:
-  - exact string match first
-  - if string is numeric (^\d+$) it is treated as an index
-  - unless strict: fuzzy match using NamedArray.field_match
-    - field_match returns true if:
-      - exact equality
-      - one contains the other inside parentheses
-      - one starts with the other followed by a space
-  - returns the index found or nil if none
-
-Instance helper identify_name(selected) delegates to the class method using this NamedArray's fields.
-
-Note: identify_name accepts arrays for selected (returns an array of resolved positions), so values_at and other helpers can pass multiple names.
-
-## Class-level helpers for lists
-
-- NamedArray.field_match(field, name)
-  - Helper used by identify_name for fuzzy matching of two strings (parentheses and prefix matching).
-
-- NamedArray._zip_fields(array, max = nil)
-  - Internal helper to zip together an array of lists, expanding single-element lists to match `max`.
-
-- NamedArray.zip_fields(array)
-  - Zips a list-of-lists into per-position combined lists. Optimized to slice large inputs when array length is huge.
-
-  Example:
-  ```ruby
-  NamedArray.zip_fields([ %w(a b), %w(1 1) ]) # => [["a","1"], ["b","1"]]
-  ```
-
-- NamedArray.add_zipped(source, new)
-  - Given two zipped-lists (source and new), concatenates each corresponding sub-array from `new` into `source` (skips nil entries).
-  - Useful to merge results incrementally.
-
-## Concatenation with Hash
-
-Calling concat with a Hash behaves like:
-```ruby
-a = NamedArray.setup([1,2], [:a, :b])
-a.concat({c: 3, d: 4})
-# resulting array becomes [1,2,3,4] and fields => [:a, :b, :c, :d]
-```
-
-This is handy when building named rows incrementally from keyed data.
-
-## Integration with Annotation
-
-Because NamedArray extends Annotation:
-- You can call NamedArray.setup(array, fields) to set the `@fields` annotation on the array and extend it with NamedArray behavior.
-- NamedArray.setup delegates to the Annotation::AnnotationModule.setup implementation for assigning @fields/@key values to the array.
-
-Example:
-```ruby
-a = NamedArray.setup([1,2], [:a, :b])
-a.fields  # => [:a, :b]
-```
-
-## Examples (from tests)
-
-Identify names:
-```ruby
-names = ["ValueA", "ValueB (Entity type)", "15"]
-NamedArray.identify_name(names, "ValueA")    # => 0
-NamedArray.identify_name(names, :key)        # => :key
-NamedArray.identify_name(names, nil)         # => 0
-NamedArray.identify_name(names, "ValueB")    # => 1  (fuzzy match)
-NamedArray.identify_name(names, 1)           # => 1
-```
-
-Basic named array usage:
-```ruby
-a = NamedArray.setup([1,2], [:a, :b])
-a[:a]      # => 1
-a[:c]      # => nil
-a.a        # => 1   (method_missing provides a getter)
-a.to_hash  # => IndiferentHash { a: 1, b: 2 }
-```
-
-Zipping and adding zipped:
-```ruby
-NamedArray.zip_fields([ %w(a b), %w(1 1) ]) # => [["a","1"], ["b","1"]]
-
-a = [%w(a b), %w(1 1)]
-NamedArray.add_zipped(a, [%w(c), %w(1)])
-NamedArray.add_zipped(a, [%w(d), %w(1)])
-# a => [%w(a b c d), %w(1 1 1 1)]
-```
-
-## Notes & caveats
-
-- Name matching is intentionally forgiving (parentheses and space-prefix checks). Use `identify_name(..., strict: true)` to force exact matches only.
-- The `fields` annotation must correspond to element positions in the array. If fields and array lengths differ, name resolution may return nil or indices outside current array bounds.
-- to_hash returns an IndiferentHash (so consumers can use either string or symbol keys).
-- method_missing exposes field getters only; it does not create setters (use []= to assign by name).
-
-NamedArray is small but convenient when treating Arrays as records/rows with named columns and needing flexible lookup and composition tools.