abbu 0.4.0 → 0.8.1

data/docs/API_STABILITY.md

@@ -0,0 +1,189 @@
+<!-- docs/API_STABILITY.md -->
+
+# Pre-1.0 API Stability Gate
+
+This is the acceptance checklist for [issue #47](https://github.com/scarver2/abbu/issues/47),
+not a declaration that ABBU is stable or authorization to release 1.0. The baseline
+inventory below describes the accepted 0.4.0 interfaces. Proposed features join
+this inventory only after review and integration.
+
+## Public surface inventory
+
+The following are consumer-facing contracts even while the gem is pre-1.0:
+
+| Surface | Contract to document and test before 1.0 |
+| --- | --- |
+| Entry points | `Abbu.open(path, strict:)`, `Abbu.open_live(path = nil, strict:)`, `Abbu::VERSION` |
+| `Archive` | Construction, `path`, `contacts`, `diagnostics`, `sqlite?`, `query`, `where`, `search`, `find_by_email`, `find_by_phone`, `schema_report`, `extract_images` |
+| `LiveStore` | Construction, `path`, `contacts`, `diagnostics`, `database_paths`, `.default_path`; discovery, caching, read-only and permission boundaries |
+| `Contact` | Mutable accessors listed below, collection defaults, nil behavior, `full_name`, `to_s`, `inspect`; sensitive-data implications of inspection |
+| `Query` | Construction from contacts, Enumerable/`each`, `to_a`, `where`, `search`, exact email/phone lookup; ordering, defensive arrays, original contact identity |
+| Exporters | `CsvExporter`, `JsonExporter`, `VcardExporter`: construction, `to_file`, `to_stdout`, output encoding and file behavior |
+| Diagnostics | `Diagnostic` fields and `to_h`; `ParseError#diagnostic`; tolerant recovery versus strict failure |
+| Identity suggestions | `Utils::Deduplicator#duplicates`, `#matches`/`#identity_matches`; `Match` readers, `sources`, `ambiguous?`, explicit `merge(policy:)`; `MergePolicyRequired` |
+| Image extraction | `ImageExtractor#extract` and `Result#files`/`#diagnostics`, also exposed through Archive; no-overwrite behavior and privacy-sensitive metadata |
+| Schema evidence | `SchemaInspector#report`, also exposed through Archive; deterministic reports, no inferred Apple semantics |
+| CLI and tasks | `bin/abbu` flags, stdout/stderr/exit codes; `abbu:export`, `abbu:dedupe`, `abbu:stats` task arguments |
+
+Contact accessor inventory:
+
+- Names: `first_name`, `middle_name`, `last_name`, `nickname`, `prefix`, `suffix`,
+  `maiden_name`, `phonetic_first_name`, `phonetic_middle_name`, `phonetic_last_name`.
+- Organization: `company`, `job_title`, `department`, `phonetic_company`.
+- Collections: `emails`, `phones`, `addresses`, `groups`, `urls`, `notes`,
+  `related_names`, `social_profiles`, `dates`, `instant_messages`.
+- Other observed fields: `pronouns`, `ringtone`, `texttone`, `birthday`,
+  `anniversary`, `verification_code`, `lunar_birthday`, `image_uri`, `image_path`,
+  `created_at`, `modified_at`, `source`.
+
+Record the keys, value types, raw evidence, optionality, ordering, and source/version
+limits for every collection and hash. A Ruby accessor does not guarantee that every
+parser or exporter supports the field. Contact fields and exported JSON are not
+identical schemas: the current JSON exporter omits nil top-level values, retains
+empty collections, serializes timestamps as ISO 8601, and adds the display `name`.
+Do not generate a JSON schema simply by enumerating Contact accessors.
+
+### Source extension (0.6.0 development)
+
+Add `Archive#sources`, `LiveStore#sources`, and `Source` construction/readers,
+`provider`, and `to_h` to the public inventory. Source JSON and `--sources` are
+public contracts; see the [source API](../README.md#sources). `SourceCatalog`
+is an internal adapter, not an extension point. File/container provenance must
+remain distinct, and provider inference is unsupported. Contacts remain mutable
+even though source metadata and membership snapshots are frozen.
+
+## Internal and experimental boundaries
+
+The 0.8.0 development vCard fidelity extension retains the exporter signatures
+and adds their RBS contract. Wire output now uses CRLF, escapes/folding and grouped
+raw labels; custom TYPE injection and fabricated preferences are removed. See
+the [export migration](../README.md#export) and [evidence audit](ABBU.md#vcard-serialization-evidence).
+`VcardDocument` and `VcardEncoding` are internal serialization helpers, not
+public extension points. No claim of a complete Apple import round-trip is made.
+
+The 0.7.0 development extension adds `Group` construction/readers, `include?`,
+`to_h`, `Contact#group_memberships`, `Source#groups`, input `groups`, source/input
+`groups_for`, `Query#in_group`, and `--groups`. See the [group API](../README.md#groups)
+for snapshot identity, JSON schema, ordering, and unsupported group boundaries.
+`GroupCatalog` is internal. Existing `Contact#groups` and contact exporter schemas
+are unchanged; raw membership keys are available in the model and group listings.
+
+Parser SQL/plist mappings, image-resolution heuristics, identity weights,
+schema-inspection constants, private helpers, and `Utils::ContactIdentity` are
+implementation details, not supported extension points. Prefer the entry points
+and public results above over calling `Parsers::*` directly. Being a reachable
+Ruby constant is not sufficient evidence of a supported extension contract.
+Audit previously documented direct usage before hiding or removing any such API;
+this classification does not authorize an immediate compatibility break.
+
+Pre-1.0 does not mean disposable: documented behavior remains review-sensitive.
+Live consistency, identity scoring/thresholds, private Apple schema coverage,
+alternate-calendar interpretation, and Apple-specific vCard conventions remain
+evidence-limited. Match scores are suggestions, not probabilities or proof of
+identity. Raw labels/provenance must survive normalization and interchange.
+
+## CLI and machine-output compatibility
+
+The 0.4.0 CLI inventory is `--format` (`csv`, `json`, `vcard`), `--output`,
+`--extract-images`, `--stats`, `--dedupe`, `--search`, `--email`, `--phone`,
+`--json`, `--schema`, `--strict`, `--live`, `--live-path`, `--version`, and `--help`,
+including documented short forms. Search returns status 0 for matches and 1 for
+no matches; JSON no-match output is `[]`. Strict parser failures return 2.
+Live input failures return 1. Other usage/error combinations need a complete
+matrix before 1.0; do not claim that every existing path already follows one
+unified exit-code scheme.
+
+Treat JSON keys, types, omission/null behavior, ordering promises, diagnostic codes,
+CLI flags, and exit statuses as public API. Renames/removals/type changes need
+explicit compatibility review and migration guidance. Machine-mode stdout must
+contain only the requested payload; warnings and errors belong on stderr. Clients
+must not parse human presentation text. [Issue #39](https://github.com/scarver2/abbu/issues/39)
+tracks remaining structured output and schema work. Freeze and version the schema
+contract before 1.0; an unimplemented schema version must not be advertised today.
+
+CSV headers/order and vCard version, CRLF, escaping, folding, Unicode, repeated
+properties, raw labels, and photo behavior also need golden/round-trip coverage.
+Portable SQLite and iCalendar are proposed formats, not current guarantees.
+
+## Deprecation and versioning policy
+
+For an intentional public change, document the old behavior, replacement, affected
+consumers, migration example, and planned removal version before removal. Keep a
+replacement available for at least one published minor release during pre-1.0;
+once 1.x is stable, incompatible removals wait for a major release. Security or
+data-loss emergencies require an explicitly approved, documented exception.
+Runtime warnings, when appropriate, must be controllable and never pollute JSON
+stdout or disclose contact values. No warning machinery is claimed to exist yet.
+
+Follow Stan's release grouping rule: completed features receive minor bumps and
+bug-fix-only releases receive patch bumps. A patch must not silently remove a
+documented contract. Review incompatible pre-1.0 changes explicitly rather than
+hiding them under a bug-fix label. Version bumps, green CI, and completed checklists
+do not authorize tagging, merging, or publication; see [releasing](RELEASING.md).
+
+## Required evidence before 1.0
+
+- [ ] Audit and approve this inventory against the exact candidate commit, including
+  new features integrated since 0.4.0; identify supported constructors and errors.
+- [ ] Publish YARD/API documentation for every supported public method and result:
+  arguments, returns, errors, mutation/caching, I/O, privacy, and runnable examples.
+- [ ] Keep public RBS contracts synchronized with implementation and validate them;
+  maintain tests for both documented success and failure behavior.
+- [ ] Freeze CLI/JSON schemas and exit-code matrix with empty/error/Unicode fixtures;
+  document migration and deprecation policy in release notes.
+- [ ] Verify parser → model → interchange preservation of raw labels, timestamps,
+  source evidence and images, including malformed and unsupported cases.
+- [ ] Run supported Ruby CI (currently 3.3, 3.4, 4.0), 100% full-suite line coverage,
+  lint, package inspection and isolated install against the candidate.
+- [ ] Publish an evidence matrix: Ruby/SQLite versions, OS, Contacts build, storage
+  layout, archive/live mode, tested fields, fixture provenance and known gaps.
+  Synthetic fixtures with unknown Apple versions are not macOS certification.
+- [ ] Complete the benchmark below and explicitly disposition performance gaps.
+- [ ] Review sensitive-data exposure in exports, diagnostics, exception messages,
+  `inspect`, absolute paths, image extraction, permissions, and future agent tools.
+  Do not log real contacts, photos, verification codes, or provider identifiers in CI.
+- [ ] Disposition each remaining backlog item as required, deferred, or unsupported
+  with rationale; do not substitute feature count for a stability decision.
+- [ ] Obtain Deputy exact-head review and separate Sheriff authorization for any
+  1.0 tag/publication. This checklist itself does not authorize either.
+
+## 10k+ performance acceptance
+
+Before 1.0, provide a deterministic, non-personal 10,000-contact benchmark with
+multiple sources, multivalues, Unicode, missing optional data, and a repeatable seed.
+Measure archive and live-style synthetic parsing, query, CSV/JSON/vCard export,
+and identity suggestions separately. Include a 100,000-contact scaling run for
+streaming work in [#40](https://github.com/scarver2/abbu/issues/40).
+
+Record exact commit, Ruby/SQLite versions, hardware/OS, fixture recipe, command,
+wall time, peak RSS, output count/checksum, warmup, and at least three measured
+runs. Report cold versus cached reads separately. Proposed gate: no unexplained
+greater-than-20% median time or peak-RSS regression against the recorded baseline
+on the same runner; any exception requires reviewer rationale. Establish absolute
+budgets from measured evidence before approving 1.0, not invented timings here.
+Streaming must demonstrate bounded contact-memory overhead at both scales;
+materializing `contacts` is not a streaming benchmark. The current all-pairs
+identity matcher needs its own scaling assessment, not a linear-memory promise.
+
+## Linked gaps and adoption
+
+See the [complete backlog](TODO.md#pre-10-backlog--not-included-in-040).
+Important dependencies include WAL evidence [#28](https://github.com/scarver2/abbu/issues/28),
+vCard fidelity/photos [#29](https://github.com/scarver2/abbu/issues/29) /
+[#30](https://github.com/scarver2/abbu/issues/30), sources/groups
+[#31](https://github.com/scarver2/abbu/issues/31) / [#32](https://github.com/scarver2/abbu/issues/32),
+My Card/history/calendar research [#33](https://github.com/scarver2/abbu/issues/33) /
+[#35](https://github.com/scarver2/abbu/issues/35) / [#36](https://github.com/scarver2/abbu/issues/36),
+machine output [#39](https://github.com/scarver2/abbu/issues/39), streaming
+[#40](https://github.com/scarver2/abbu/issues/40), and safe-writer research
+[#46](https://github.com/scarver2/abbu/issues/46). Deferral may be acceptable if the
+released support boundary is explicit. Never infer unsupported Apple semantics
+to check off a gate.
+
+Return to the [README](../README.md), [format evidence](ABBU.md), or
+[contribution workflow](CONTRIBUTING.md).
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/CHANGELOG.md

@@ -11,6 +11,59 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-10-01
+
+### Fixed
+
+- Package verification reuses Bundler-installed dependency paths in CI while
+  loading the built ABBU gem from an isolated installation. CI now exercises
+  this check before a release tag is created.
+
+## [0.8.0] - 2026-10-01
+
+This release includes the previously unreleased 0.5.0–0.7.0 development milestones.
+
+### Added — vCard fidelity
+
+- vCard fidelity layer with raw-label-preserving grouped repeated properties,
+  public exporter RBS, and deterministic SQLite/plist-to-vCard regression tests.
+
+### Changed — vCard fidelity
+
+- vCard output now uses CRLF, escaped TEXT/structured components, UTF-8-safe
+  75-octet folding, and URI-specific encoding. Consumers must unfold and decode
+  rather than parse ungrouped literal output lines.
+- Custom labels use grouped `X-ABLABEL` rather than arbitrary TYPE parameters;
+  only standard exact ASCII labels become TYPE. Removed invented anniversary
+  preference and unlabeled-address HOME. Existing method signatures remain.
+- Invalid text/control bytes and unsafe service tokens/schemes fail before
+  output rather than emitting malformed records. Apple-specific support limits
+  and migration guidance are explicit; no Contacts import certification claimed.
+
+### Added — groups
+
+- First-class observed groups scoped by file provenance and SQLite record key,
+  with source/input enumeration, reverse membership lookup, and chainable
+  `Query#in_group` filtering without merging same-name groups.
+- Lossless `Contact#group_memberships` evidence alongside unchanged legacy group
+  labels and contact exports; immutable group snapshots and public RBS.
+- JSON-only `--groups` listing for archives and read-only live stores, preserving
+  raw names, nulls, diagnostics, and explicit unsupported empty/plist-group boundaries.
+
+### Added — sources
+
+- Read-only source containers through `Archive#sources` and `LiveStore#sources`,
+  preserving raw file provenance, unknown providers, queryable contacts, and
+  observed group membership labels without conflating source-local identifiers.
+- JSON-only `--sources` listing for archive/live inputs, including empty sources;
+  public RBS, immutable metadata and deterministic source/file ordering.
+
+### Added — timestamp queries
+
+- Chainable created/modified-since and half-open timestamp range queries with
+  timezone-explicit ISO 8601 bounds, missing-timestamp exclusion, and Query RBS.
+- Archive CLI timestamp filters with existing TSV/JSON results and exit contracts.
+
 ## [0.4.0] - 2026-09-30
 
 ### Fixed

data/docs/CONTRIBUTING.md

@@ -26,6 +26,12 @@ This runs RSpec and RuboCop automatically on file changes.
 bin/spec
 ```
 
+Keep the [format compatibility matrix](FORMAT_COMPATIBILITY.md) passing when
+changing parsers, discovery, models or exporters. Add evidence-backed synthetic
+variations without replacing legacy fixtures. Run the focused matrix with
+`bin/spec spec/abbu/archive_compatibility_spec.rb`; the full suite remains
+authoritative for the 100% coverage gate.
+
 ## Linting
 
 ```bash
@@ -43,6 +49,12 @@ This builds the current gem, verifies its metadata, installs it into an isolated
 gem home, and loads that installed copy. A successful package check is evidence
 only; it does not authorize a release tag or RubyGems publication.
 
+Run `bundle install` through the project toolchain first. Package verification
+installs ABBU without resolving dependencies again, then loads that installed
+copy using Bundler's dependency search paths. Missing runtime dependencies still
+fail the load check. Only ABBU is isolated, not the dependency set. The CI Ruby
+matrix runs this same command with its Bundler-managed installation paths.
+
 ## Pull Request Guidelines
 
 - Base branch: `main`

data/docs/FORMAT_COMPATIBILITY.md

@@ -0,0 +1,97 @@
+<!-- docs/FORMAT_COMPATIBILITY.md -->
+
+# ABBU Compatibility Regression Matrix
+
+Legacy support is a tested behavior, not a filename/version guess. The suite
+must keep the older supported shapes passing as newer fields and layouts are
+added. This matrix is run by ordinary `bin/spec` and therefore by every current
+CI Ruby job (3.3, 3.4, 4.0); it needs no macOS services or personal contacts.
+
+## Evidence and scope
+
+All profiles below are **synthetic**, with **unknown macOS and Contacts build**.
+Their evidence is the repository's existing XML fixture keys, SQLite fixture
+generator, and parser schema-variance tests. They are not collected exports from
+eight Apple releases. In particular, `v1` and `v99` are filename-dispatch probes
+using the known schema; they do not establish support for real schemas with
+those version numbers. Do not report the Ruby CI matrix as a macOS matrix.
+
+`spec/support/compatibility_fixtures.rb` rebuilds each profile inside a fresh
+temporary directory. It reuses only the non-destructive schema/seed methods of
+the existing fixture generator, not its bundle-reset command. No committed
+binary is regenerated or overwritten by these tests.
+
+## Always-on end-to-end profiles
+
+| Profile | Structure / variation | Expected boundary |
+| --- | --- | --- |
+| `xml_records` | XML `.abcdp` under `Records/` | Plist fallback, raw labels, absent SQLite-only timestamps/groups |
+| `xml_nested` | XML records below `Sources/Équipe/Records/` | Recursive archive discovery and source provenance |
+| `sqlite_sparse` | Synthetic `AddressBook-v1.abcddb`; absent timestamp/image/name-extension columns and most relationship tables | Preserve core contact/email; nil absent fields, empty collections, tolerant diagnostics; strict mode raises |
+| `sqlite_root` | Root `AddressBook-v22.abcddb` with all currently queried relationship tables | Strict-mode success, timestamps, original group membership |
+| `sqlite_source_only` | Database only under `Sources/Équipe/` | Root database is not required |
+| `sqlite_empty_root` | Empty root plus two source databases with colliding contact/group keys | Empty source remains listed; every source's contact/group remains distinct |
+| `sqlite_mixed_schemas` | Sparse root plus complete nested database, different filename suffixes | Optional-table state is file-local, not cached globally across schemas |
+| `mixed_formats` | Both SQLite and XML records | Preserve current SQLite-first policy; plist records are intentionally not combined |
+
+Each profile independently asserts expected record counts and file provenance,
+raw versus normalized email labels, query results, timestamp availability, group
+traversal, source enumeration, and strict/tolerant outcomes. JSON retains labels
+and provenance; CSV and vCard retain the core email/contact counts. Export tests
+compare SHA-256 of every input file before and after parsing/exporting and detect
+new or missing files as well as changed bytes. These archive tests do not claim
+byte-for-byte immutability of live WAL shared-memory state.
+
+Additional matrix regressions prevent an unknown required SQLite schema from
+silently falling back to XML, and keep valid XML siblings recoverable when one
+record is malformed. They test public `Abbu.open` behavior without parser mocks.
+The matrix does not freeze vCard whitespace or property spelling; the dedicated
+exporter tests own those contracts.
+
+## Complementary existing coverage
+
+| Variation | Regression location |
+| --- | --- |
+| Full relational fields; absent/invalid timestamps; missing tables vs missing columns | `spec/abbu/parsers/sqlite_parser_spec.rb` |
+| Rich/minimal XML; malformed records; dates; raw anniversary labels | `spec/abbu/parsers/plist_parser_spec.rb` |
+| Empty/multiple files, source collisions, SQLite-first precedence | `spec/abbu/source_spec.rb` |
+| Same-name groups, duplicate joins, null/Unicode labels | `spec/abbu/group_spec.rb` |
+| Duplicate image stems, source-local resolution, missing images | `spec/abbu/utils/image_resolver_spec.rb`, `spec/abbu/archive_spec.rb` |
+| JPEG/PNG/GIF/HEIC signatures, unknown bytes, safe extraction | `spec/abbu/image_extractor_spec.rb` |
+| WAL visibility, concurrent commits and cache limits | `spec/abbu/live_store_wal_spec.rb` |
+| Unknown tables/columns and schema drift without inferred mappings | `spec/abbu/schema_inspector_spec.rb` |
+
+## Unverified historical boundaries
+
+There is no release-attributed real-archive corpus in this repository. Binary
+plist `.abcdp`, alternate private table/column/entity mappings, and exports from
+specific historical macOS/Contacts builds are **not certified by this matrix**.
+XML support must not be generalized to every plist encoding. Existing recovery
+tests likewise do not prove all corruption forms recover safely.
+
+To add a genuine historical variation:
+
+1. Record the export's macOS version, Contacts build, export method and storage
+   encoding; mark any unavailable metadata unknown.
+2. Inspect the relevant behavior privately. Never commit a real address book,
+   photo, account identifier, or unsanitized schema/data dump.
+3. Reproduce only the necessary structure with deterministic invented data,
+   recording the observed keys/columns/relationships and source evidence.
+4. Add a named matrix profile or focused regression with explicit expected
+   fields, provenance, raw evidence, exports, diagnostics and strict behavior.
+5. Fix supported behavior only after the regression demonstrates the gap. Keep
+   older fixtures/tests; do not replace them with the newest schema. Unknown
+   formats should remain explicit gaps, not guessed adapters or silent fallback.
+6. Record the evidence and limits in [ABBU.md](ABBU.md) and this matrix, and run
+   the full suite/lint/CI before review.
+
+This test-only expansion changes neither runtime behavior nor the gem version.
+Future behavior fixes use patch bumps; newly completed features use minor bumps.
+
+Return to [README](../README.md), [format evidence](ABBU.md), or
+[contributing](CONTRIBUTING.md).
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/RELEASING.md

@@ -0,0 +1,75 @@
+<!-- docs/RELEASING.md -->
+
+# RubyGems Trusted Publishing
+
+ABBU publishes RubyGems releases from GitHub Actions using RubyGems.org Trusted
+Publishing. The release workflow intentionally contains no long-lived RubyGems
+API key.
+
+Workflow-level permissions default to `{}`. The release job grants only
+`contents: read` for checkout/source inspection and `id-token: write` for OIDC.
+It has no GitHub repository write permission; the version tag must already exist.
+
+## One-time RubyGems.org setup
+
+As a RubyGems owner for `abbu`, configure a Trusted Publisher with:
+
+- GitHub repository owner: `scarver2`
+- GitHub repository: `abbu`
+- workflow filename: `release.yml`
+- GitHub environment: `release`
+
+Create the GitHub environment named `release` with `scarver2` as a required
+reviewer and administrator bypass disabled. Only tags matching `v*` may deploy.
+The Sheriff may approve a release they initiated; approval is still explicit.
+Verify these settings before the first automated publication. Merely naming an
+environment in YAML does not protect it.
+
+Official RubyGems guidance:
+https://guides.rubygems.org/trusted-publishing/
+
+## Release flow
+
+1. Prepare and review the release on `main`.
+2. Run the canonical spec, lint, and package gates.
+3. Obtain explicit Sheriff authorization for the specific version.
+4. Push only the authorized `vMAJOR.MINOR.PATCH` tag.
+5. GitHub Actions runs `.github/workflows/release.yml`.
+6. The Sheriff reviews the exact tag target and approves the `release` environment.
+   The workflow requires a stable version tag reachable from `origin/main`, checks
+   that it matches `Abbu::VERSION`, and reruns the package gates before publishing
+   with `rubygems/release-gem@v1` using OIDC.
+7. Verify the RubyGems release and provenance against the accepted source.
+
+The workflow does not bump versions, create tags, or grant release authority.
+
+For repeatable candidate verification, run:
+
+```bash
+SOURCE_DATE_EPOCH=$(git show -s --format=%ct HEAD) bin/package
+```
+
+The workflow sets that same value for
+both verification and the action's `bundle exec rake release` build. Compare the
+published gem with the accepted source; never move a release tag or republish a
+version to recover from a failed run. A failed run after upload requires checking
+RubyGems before retrying. Do not replay the already published `v0.4.0` tag.
+
+Normal PR CI remains the Ruby 3.3/3.4/4.0 review gate; the release job repeats
+spec/lint/package checks on the Ruby 3.3 compatibility floor. Local/manual pushes
+are not the default path. No API key secret is needed, and Trusted Publisher
+registration is not itself permission to publish a new version.
+
+## Repository standard
+
+Use this pattern by default for our other GitHub-hosted RubyGems: OIDC Trusted
+Publishing, a protected `release` environment, exact version-tag verification,
+canonical repository checks, and no long-lived RubyGems publishing secret.
+
+See [AGENTS.md](../AGENTS.md), [contribution workflows](CONTRIBUTING.md), and
+[README](../README.md). This infrastructure PR does not authorize a release.
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/TODO.md

@@ -166,6 +166,9 @@ Contacts databases is not part of the roadmap.
 
 ## v1.0.0 — Future Stable API
 
+The [API stability gate](API_STABILITY.md) defines the evidence required below;
+its existence does not mean those checks are complete or authorize a 1.0 release.
+
 - [ ] Complete the API-stability checklist and acceptance evidence before promising stability
 - [ ] Comprehensive public API documentation
 - [ ] Benchmarks for large archives (10k+ contacts)

data/lib/abbu/archive.rb

@@ -9,6 +9,7 @@ require_relative 'parsers/plist_parser'
 require_relative 'parsers/sqlite_parser'
 require_relative 'query'
 require_relative 'schema_inspector'
+require_relative 'source_catalog'
 require_relative 'utils/image_resolver'
 
 module Abbu
@@ -58,6 +59,19 @@ module Abbu
       SchemaInspector.new(db_paths, root_path: @path).report
     end
 
+    # Enumerate only the files selected by this archive's existing parser mode.
+    def sources
+      @sources ||= SourceCatalog.new(sqlite? ? db_paths : plist_paths, root_path: @path, contacts: contacts).sources
+    end
+
+    def groups
+      @groups ||= sources.flat_map(&:groups).freeze
+    end
+
+    def groups_for(contact)
+      groups.select { |group| group.include?(contact) }
+    end
+
     private
 
     def validate!

data/lib/abbu/contact.rb

@@ -4,7 +4,7 @@
 module Abbu
   class Contact
     attr_accessor :first_name, :middle_name, :last_name, :emails,
-                  :phones, :company, :addresses, :groups, :nickname,
+                  :phones, :company, :addresses, :groups, :group_memberships, :nickname,
                   :prefix, :suffix, :job_title, :department, :maiden_name,
                   :phonetic_first_name, :phonetic_middle_name, :phonetic_last_name,
                   :phonetic_company, :pronouns, :ringtone, :texttone,
@@ -14,11 +14,12 @@ module Abbu
                   :image_uri, :image_path,
                   :created_at, :modified_at, :source
 
-    def initialize
+    def initialize # rubocop:disable Metrics/MethodLength
       @emails = []
       @phones = []
       @addresses = []
       @groups = []
+      @group_memberships = []
       @urls = []
       @notes = []
       @related_names = []

data/lib/abbu/exporters/vcard_document.rb

@@ -0,0 +1,54 @@
+# lib/abbu/exporters/vcard_document.rb
+# frozen_string_literal: true
+
+require_relative 'vcard_encoding'
+
+module Abbu
+  module Exporters
+    # Per-card grouping avoids ambiguous associations between repeated labels.
+    class VcardDocument
+      TYPES = {
+        'EMAIL' => %w[INTERNET X400 PREF],
+        'TEL' => %w[HOME WORK PREF VOICE FAX MSG CELL PAGER BBS MODEM CAR ISDN VIDEO PCS],
+        'ADR' => %w[DOM INTL POSTAL PARCEL HOME WORK PREF],
+        'IMPP' => %w[PERSONAL BUSINESS HOME WORK MOBILE PREF]
+      }.transform_values(&:freeze).freeze
+
+      def initialize
+        @lines = ['BEGIN:VCARD', 'VERSION:3.0']
+        @group_number = 0
+      end
+
+      def <<(line)
+        @lines << line
+      end
+
+      def labeled(property, value, entry, default_type: nil)
+        type = standard_type(property, entry[:label]) || default_type
+        header = type ? "#{property};TYPE=#{type}" : property
+        label = entry[:raw_label] || entry[:label]
+        return self << "#{header}:#{value}" if label.nil?
+
+        @group_number += 1
+        self << "item#{@group_number}.#{header}:#{value}"
+        self << "item#{@group_number}.X-ABLABEL:#{VcardEncoding.text(label)}"
+      end
+
+      def to_s
+        lines = (@lines + ['END:VCARD']).map { |line| VcardEncoding.fold(line) }
+        "#{lines.join("\r\n")}\r\n"
+      end
+
+      private
+
+      def standard_type(property, label)
+        return unless label.to_s.match?(/\A[A-Za-z0-9-]+\z/)
+
+        type = label.upcase
+        return 'INTERNET,PREF' if property == 'EMAIL' && type == 'PREF'
+
+        type if TYPES.fetch(property, []).include?(type)
+      end
+    end
+  end
+end

data/lib/abbu/exporters/vcard_encoding.rb

@@ -0,0 +1,54 @@
+# lib/abbu/exporters/vcard_encoding.rb
+# frozen_string_literal: true
+
+require 'uri'
+
+module Abbu
+  module Exporters
+    # Internal wire encoding; URI values and TEXT values have different grammars.
+    module VcardEncoding
+      module_function
+
+      def text(value)
+        utf8(value).gsub(/\\|;|,|\r\n|\r|\n/) do |character|
+          character.match?(/[\r\n]/) ? '\\n' : "\\#{character}"
+        end
+      end
+
+      def structured(values)
+        values.map { |value| text(value) }.join(';')
+      end
+
+      def uri(value)
+        URI::DEFAULT_PARSER.escape(utf8(value), %r{[^A-Za-z0-9\-._~:/?#\[\]@!$&'()*+,;=%]})
+      end
+
+      def token(value)
+        string = utf8(value)
+        raise ArgumentError, 'vCard parameter must be an ASCII token' unless string.match?(/\A[A-Za-z0-9-]+\z/)
+
+        string
+      end
+
+      def fold(line)
+        parts = [+'']
+        utf8(line).each_char do |character|
+          parts << +' ' if parts.last.bytesize + character.bytesize > 75
+          parts.last << character
+        end
+        parts.join("\r\n")
+      end
+
+      def utf8(value)
+        string = value.to_s.encode(Encoding::UTF_8)
+        raise ArgumentError, 'vCard text has invalid encoding' unless string.valid_encoding?
+        if string.match?(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/)
+          raise ArgumentError,
+                'vCard text contains an unsupported control character'
+        end
+
+        string
+      end
+    end
+  end
+end