jscontact 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2b5fd75452d4b1982b14996be3513fef5543d65f36e026b75ab0fb320a7d5f16
+  data.tar.gz: 0f938551f087628168cb7a5fe896acf1f339fb5034355305da5c2175b6deada2
+SHA512:
+  metadata.gz: 053177fa21d75e63a1a4434ba7418aef8096d0a3399a315bd80bc393c05f79ed6509a77202be8197f773172079580fc0e75b75738af1c5f6e57285c5702afaa9
+  data.tar.gz: bd31c7364dca93a41ceb9dd11585b89e584df900d1e722598b5b43b65eec08d23f0324d43bc9eb1cbac5ecf99e3b963b48acec9b7ff10e0bdf3ef105a05e8440

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-10-12
+
+Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+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,212 @@
+# JSContact
+
+[![Ruby](https://github.com/ydah/jscontact/actions/workflows/main.yml/badge.svg)](https://github.com/ydah/jscontact/actions/workflows/main.yml)
+
+Parse, validate, build, and convert JSContact contact cards in Ruby. Supports
+[RFC 9553](https://www.rfc-editor.org/rfc/rfc9553),
+[RFC 9555](https://www.rfc-editor.org/rfc/rfc9555), and
+[RFC 9982](https://www.rfc-editor.org/rfc/rfc9982).
+
+Unknown properties, vendor extensions, and map identifiers survive JSON round
+trips. New cards use JSContact 2.0; reading a 1.0 card keeps its version until you
+explicitly upgrade it.
+
+## Installation
+
+Requires Ruby 3.3 or later. CI also tests JRuby and TruffleRuby on Linux and macOS.
+
+```ruby
+gem "jscontact"
+# Add only when using the optional vCard converter:
+gem "jcard_jcal", "~> 0.1.0"
+```
+
+The JSON API depends on `json` and `tzinfo`. On systems without a zoneinfo database
+(such as Windows), also install `tzinfo-data` for time zone and country validation.
+
+## Read and build cards
+
+```ruby
+require "jscontact"
+
+card = JSContact::Card.build do |contact|
+  contact.name = { full: "Mina Sample" }
+  contact.add_email(address: "mina@example.test", contexts: { work: true })
+  contact["example.test:customer"] = { "number" => 42 }
+end
+
+card.name.full                    # => "Mina Sample"
+card.emails["e1"].address         # => "mina@example.test"
+card.emails["e1"].label = "Desk" # updates the parent card
+card.to_h                        # independent, deep copy
+json = card.to_json              # validates before serializing
+copy = JSContact.parse(json)
+```
+
+`JSContact` and `Jscontact` refer to the same module. The schema defines typed
+classes such as `Name`, `Address`, and `EmailAddress`; nested accessors return typed
+views. `[]` and `[]=` also accept unknown property names. Camel-case property
+accessors have snake-case aliases, for example `preferred_languages`.
+
+`Card.new(hash)` copies the input and permits incomplete data while building a
+card. Use `strict: true` to validate immediately. Constructors accept symbol keys
+and normalize them to strings; duplicate normalized keys are rejected.
+
+`to_h` preserves absent default properties; accessors expose their defaults.
+`Card.build(explicit_types: true)` includes optional nested `@type` members when
+exporting. Nested objects serialized on their own include their required `@type`.
+Instances are mutable; give each concurrent worker its own card.
+
+## Validation and versions
+
+```ruby
+card = JSContact.parse(json, strict: false)
+card.valid?
+card.warnings.each { |violation| puts "#{violation.pointer}: #{violation.message}" }
+card.validate! # raises JSContact::ValidationError if invalid
+
+upgraded = JSContact.upgrade(card) # validates, copies, and sets version to "2.0"
+```
+
+`parse` is strict by default. Lenient parsing retains schema violations in
+`errors` (also available as `warnings`); malformed JSON, duplicate keys, unsupported
+Ruby values, and resource-limit violations still raise. Serialization is always
+strict. `ValidationError#errors` contains every collected `Violation`, with a JSON
+Pointer and message; the empty pointer identifies the document root.
+
+Version 1.0 requires `uid`; version 2.0 permits it to be absent. Upgrading changes
+only the version, without inventing a UID or renumbering map identifiers. Unknown
+properties with valid names are preserved. Unknown enum values are reported as
+violations unless they use the vendor extension syntax.
+
+## Patches and localizations
+
+```ruby
+card.localizations = { "ja" => { "name/full" => "サンプル ミナ" } }
+japanese = card.localized("ja")
+
+patched = JSContact::PatchObject.new({ "name/full" => "Mina Updated" }).apply(card.to_h)
+```
+
+Patch keys are JSON Pointers without the leading slash. `nil` deletes an object
+member; array entries can be replaced but cannot be inserted or removed. Escapes,
+parent paths, overlapping paths, resulting types, and required properties are
+checked before returning a result. Neither the patch nor its target is modified.
+Schema validation applies when the target has a recognized `@type`; untyped
+objects receive JSON structure validation.
+
+`localized` matches language tags without case sensitivity, applies the selected
+patch to a copy, removes its localization map, and sets its language. If no patch
+matches, it returns an unchanged copy. Patches cannot modify `localizations` itself.
+
+## vCard conversion
+
+```ruby
+require "jscontact/vcard"
+
+text = JSContact::VCard.from_jscontact(card)
+restored = JSContact::VCard.to_jscontact(text) # JSContact 2.0
+```
+
+Only the optional entrypoint loads `jcard_jcal`. Conversion accepts exactly one
+vCard 4.0. A missing UID stays absent when converting to JSContact 2.0. Requesting
+`version: "1.0"` emits a deprecation warning and supplies a stable UID if necessary.
+
+| RFC 9555 rules | Support |
+| --- | --- |
+| Sections 2.2–2.3: value types and parameters | Both directions, including PROP-ID, ALTID, LANGUAGE, and JSCOMPS |
+| Sections 2.4–2.6: general properties, identification, delivery addresses | Both directions, including phonetic values |
+| Sections 2.7–2.10: communication, geography, organizations, personal information | Both directions |
+| Sections 2.11–2.14: explanatory, security, calendar, and extended properties | Both directions |
+| Section 2.15: unmatched properties and parameters | Retained as `vCardProps`, `vCardParams`, and `vCardName` |
+| Section 3: JSContact to vCard | Native properties plus JSPROP/JSPTR for otherwise unrepresentable data |
+
+Conversion preserves data, rather than the original text's property order,
+folding, or choice of equivalent representation. Date forms without a JSContact
+equivalent and unmatched birth/death place properties are retained in `vCardProps`.
+
+JSContact date fields use the Gregorian calendar even when `calendarScale` names
+another calendar. The converter preserves non-Gregorian vCard CALSCALE properties
+in `vCardProps`; it does not perform calendar arithmetic. In the other direction,
+it emits a Gregorian native date and retains non-Gregorian metadata through JSPROP.
+The underlying vCard parser checks Gregorian date validity, so dates from an
+unsupported calendar that fail those checks raise `ConversionError`.
+
+A top-level unknown property whose value is JSON `null` cannot be represented by
+JSPROP: its PatchObject semantics mean deletion. Conversion raises
+`ConversionError` with the property pointer instead of dropping it. Nested nulls
+inside a retained object or array are supported. Ordinary JSON round trips retain
+all null values.
+
+## Supported scope
+
+| Feature | Status |
+| --- | --- |
+| RFC 9553 object models, validation, JSON generation | Supported |
+| RFC 9982 JSContact 2.0 and optional UID | Supported; 1.0 is retained when read |
+| PatchObject and localizations | Supported |
+| RFC 9555 and RFC 9554 vCard 4.0 conversion | Supported as described above |
+| Unknown properties and vendor JSON | Preserved, subject to valid names and I-JSON constraints |
+| JMAP for Contacts | Card data supported; protocol operations are outside scope |
+| vCard 2.1/3.0, CardDAV sync, RDAP profiles, locale-specific display formatting | Outside scope |
+
+## Resource limits
+
+These options apply to `parse` and model constructors. Exceeding a limit raises
+`LimitError`, including in lenient mode.
+
+| Option | Default | Applies to |
+| --- | --- | --- |
+| `max_input_size` | 16 MiB | JSON input bytes in `parse` |
+| `max_depth` | 32 | Nested JSON objects and arrays, including vendor values |
+| `max_map_size` | 10,000 | Schema-defined maps and arrays |
+| `max_data_uri_size` | 1 MiB | Estimated decoded data URI size |
+| `max_patches` | 1,000 | Total localization patches, or entries in a PatchObject |
+
+```ruby
+JSContact.parse(json, max_input_size: 1_048_576, max_depth: 16, max_map_size: 500)
+```
+
+The gem never fetches resource URIs or resolves linked contacts. vCard text parsing
+also uses `jcard_jcal`'s own parser limits. See [SECURITY.md](SECURITY.md) for reporting
+vulnerabilities.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake                      # fetch and verify external RFC inputs, then test
+COVERAGE=1 bundle exec rake            # minimum 90% line coverage
+bundle exec rubocop
+bundle exec rbs -I sig validate
+bundle exec ruby script/interop.rb     # requires stable Rust; pinned calcard comparison
+bundle exec ruby script/benchmark.rb   # time, allocation and RSS measurements at limits
+bundle exec ruby script/update_registry.rb           # verify pinned IANA registry coverage
+bundle exec ruby script/update_registry.rb --refresh # audit current IANA data and update pins
+```
+
+The suite checks 97 generated RFC examples, both directions of 54 vCard conversion
+pairs, malformed input, patches, limits, and deterministic random round trips.
+See [conformance notes](docs/conformance.md) for extraction corrections, reported
+errata, and the two precisely checked upstream interoperability differences.
+The [boundary measurements](docs/performance.md) explain the default limits.
+
+RFC originals, extracted examples, IANA downloads, and external comparison sources
+live only in ignored `tmp/` directories. Downloads retain their applicable notices;
+RFC source hashes and the generated corpus fingerprint are checked before testing.
+The packaged gem contains library code, original schema metadata, RBS, and user
+documentation, excluding test corpora and third-party source code.
+
+## Release
+
+Configure RubyGems Trusted Publishing for owner `ydah`, repository `jscontact`,
+workflow `release.yml`, and GitHub environment `release`. After checks pass, update
+the gem version and CHANGELOG, then push the matching `vVERSION` tag. The workflow
+tests, builds, publishes through OIDC, and creates a GitHub release from that
+version's CHANGELOG entry. A version already on RubyGems is not published again.
+
+## License
+
+The Ruby library is available under the [MIT License](LICENSE.txt). External test
+inputs and comparison dependencies retain their own licenses and are not included
+in the gem.

data/SECURITY.md

@@ -0,0 +1,6 @@
+# Security
+
+Report vulnerabilities through [GitHub private vulnerability reporting](https://github.com/ydah/jscontact/security/advisories/new).
+Please include a minimal reproducer and the affected gem and Ruby versions.
+
+The library treats documents as data. It does not retrieve contact URIs or execute embedded content.

data/data/enums.yml

@@ -0,0 +1,356 @@
+# Original validation metadata; names are protocol identifiers, not copied examples.
+---
+cardKind:
+- individual
+- group
+- org
+- location
+- device
+- application
+phoneticSystem:
+- ipa
+- jyut
+- piny
+context:
+- private
+- work
+addressContext:
+- private
+- work
+- billing
+- delivery
+relation:
+- acquaintance
+- agent
+- child
+- co-resident
+- co-worker
+- colleague
+- contact
+- crush
+- date
+- emergency
+- friend
+- kin
+- me
+- met
+- muse
+- neighbor
+- parent
+- sibling
+- spouse
+- sweetheart
+nameKind:
+- title
+- given
+- given2
+- surname
+- surname2
+- credential
+- generation
+- separator
+gender:
+- animate
+- common
+- feminine
+- inanimate
+- masculine
+- neuter
+titleKind:
+- title
+- role
+phoneFeature:
+- mobile
+- voice
+- text
+- video
+- main-number
+- textphone
+- fax
+- pager
+calendarKind:
+- calendar
+- freeBusy
+addressKind:
+- room
+- apartment
+- floor
+- building
+- number
+- name
+- block
+- subdistrict
+- district
+- locality
+- region
+- postcode
+- country
+- direction
+- landmark
+- postOfficeBox
+- separator
+directoryKind:
+- directory
+- entry
+linkKind:
+- contact
+mediaKind:
+- photo
+- sound
+- logo
+anniversaryKind:
+- birth
+- death
+- wedding
+personalKind:
+- expertise
+- hobby
+- interest
+level:
+- high
+- medium
+- low
+calendarScale:
+- gregorian
+- buddhist
+- chinese
+- coptic
+- dangi
+- ethiopic
+- ethiopic-amete-alem
+- hebrew
+- indian
+- islamic
+- islamic-civil
+- islamic-rgsa
+- islamic-tbla
+- islamic-umalqura
+- iso8601
+- japanese
+- persian
+- roc
+script:
+- Adlm
+- Afak
+- Aghb
+- Ahom
+- Arab
+- Aran
+- Armi
+- Armn
+- Avst
+- Bali
+- Bamu
+- Bass
+- Batk
+- Beng
+- Berf
+- Bhks
+- Blis
+- Bopo
+- Brah
+- Brai
+- Bugi
+- Buhd
+- Cakm
+- Cans
+- Cari
+- Cham
+- Cher
+- Chis
+- Chrs
+- Cirt
+- Copt
+- Cpmn
+- Cprt
+- Cyrl
+- Cyrs
+- Deva
+- Diak
+- Dogr
+- Dsrt
+- Dupl
+- Egyd
+- Egyh
+- Egyp
+- Elba
+- Elym
+- Ethi
+- Gara
+- Geok
+- Geor
+- Glag
+- Gong
+- Gonm
+- Goth
+- Gran
+- Grek
+- Gujr
+- Gukh
+- Guru
+- Hanb
+- Hang
+- Hani
+- Hano
+- Hans
+- Hant
+- Hatr
+- Hebr
+- Hira
+- Hluw
+- Hmng
+- Hmnp
+- Hntl
+- Hrkt
+- Hung
+- Inds
+- Ital
+- Jamo
+- Java
+- Jpan
+- Jurc
+- Kali
+- Kana
+- Kawi
+- Khar
+- Khmr
+- Khoj
+- Kitl
+- Kits
+- Knda
+- Kore
+- Kpel
+- Krai
+- Kthi
+- Lana
+- Laoo
+- Latf
+- Latg
+- Latn
+- Leke
+- Lepc
+- Limb
+- Lina
+- Linb
+- Lisu
+- Loma
+- Lyci
+- Lydi
+- Mahj
+- Maka
+- Mand
+- Mani
+- Marc
+- Maya
+- Medf
+- Mend
+- Merc
+- Mero
+- Mlym
+- Modi
+- Mong
+- Moon
+- Mroo
+- Mtei
+- Mult
+- Mymr
+- Nagm
+- Nand
+- Narb
+- Nbat
+- Newa
+- Nkdb
+- Nkgb
+- Nkoo
+- Nshu
+- Ogam
+- Olck
+- Onao
+- Orkh
+- Orya
+- Osge
+- Osma
+- Ougr
+- Palm
+- Pauc
+- Pcun
+- Pelm
+- Perm
+- Phag
+- Phli
+- Phlp
+- Phlv
+- Phnx
+- Piqd
+- Plrd
+- Prti
+- Psin
+- Ranj
+- Rjng
+- Rohg
+- Roro
+- Runr
+- Samr
+- Sara
+- Sarb
+- Saur
+- Seal
+- Sgnw
+- Shaw
+- Shrd
+- Shui
+- Sidd
+- Sidt
+- Sind
+- Sinh
+- Sogd
+- Sogo
+- Sora
+- Soyo
+- Sund
+- Sunu
+- Sylo
+- Syrc
+- Syre
+- Syrj
+- Syrn
+- Tagb
+- Takr
+- Tale
+- Talu
+- Taml
+- Tang
+- Tavt
+- Tayo
+- Telu
+- Teng
+- Tfng
+- Tglg
+- Thaa
+- Thai
+- Tibt
+- Tirh
+- Tnsa
+- Todr
+- Tols
+- Toto
+- Tutg
+- Ugar
+- Vaii
+- Visp
+- Vith
+- Wara
+- Wcho
+- Wole
+- Xpeo
+- Xsux
+- Yezi
+- Yiii
+- Zanb
+- Zinh
+- Zmth
+- Zsye
+- Zsym
+- Zxxx
+- Zyyy
+- Zzzz