jscalendar 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fdf3b15b894e49f349876787d56ce76102b83822e622c079dfc7966804eab2bf
+  data.tar.gz: 23259294ec16d3a2420c1af9ad97ce72aaa0df6502a7328b19d27bb7c427f158
+SHA512:
+  metadata.gz: 5ff2aeaa9fb416f63ede56b7d018f6db8e671bb35c71badec0a76a142bf75c9aac6ac8d9ca4e850b832168105d65e06fa970196a06848da135045994092d5065
+  data.tar.gz: 1cb88675b31c5d4d7fb2609e399dc667e57212d44893d96e6114a5037eca727ccc6d4c418f0803f7bc4d3f681cd0c5e36586a4db44706ebfa5e3d1b10d58e7f2

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,100 @@
+# JSCalendar
+
+Read, validate, build and expand calendar events and tasks using [RFC 8984](https://www.rfc-editor.org/rfc/rfc8984).
+
+```ruby
+require "jscalendar"
+
+meeting = JSCalendar::Event.build do |event|
+  event.title = "Weekly review"
+  event.start = "2026-10-12T10:00:00"
+  event.time_zone = "Asia/Tokyo"
+  event.duration = "PT1H"
+  event.add_recurrence_rule(frequency: "weekly", by_day: [{ day: "mo" }])
+end
+
+json = meeting.to_json
+copy = JSCalendar.parse(json)
+copy.start_time # => 2026-10-12 01:00:00 UTC
+
+instances = copy.occurrences(from: Time.utc(2026, 10, 1), to: Time.utc(2026, 11, 1), limit: 100)
+instances.each { |instance| puts [instance.recurrence_id, instance.start_time, instance.event.title] }
+instances.truncated?
+```
+
+Install with `gem install jscalendar`. Ruby 3.3 or newer is required. CI checks maintained CRuby versions, Ruby head, JRuby and TruffleRuby on Linux and macOS, and json 2 and 3. Runtime dependencies are `json`, `tzinfo` and `rrule`. Install `tzinfo-data` on systems without a zoneinfo database, including Windows. No other Gem from this format family is required.
+
+## Scope
+
+| Feature | Support |
+| --- | --- |
+| Event, Task, Group and every RFC 8984 object type | Parsing, validation, building, serialization and RBS |
+| Unknown and vendor fields | Preserved; unknown Group entries and trigger types remain opaque |
+| PatchObject | Atomic object patches, pointer escaping and overlap checks; array traversal is invalid in JSCalendar 1.0 |
+| Localizations | Permitted text patches with locale selection |
+| IANA and custom time zones | Floating time, Group inheritance and pre-transition offsets at gaps and folds |
+| Gregorian recurrence | All frequencies and BY fields, union, exclusions, additions and overrides |
+| Non-Gregorian calendars, `skip: backward/forward`, leap-second recurrence | Preserved and validated; expansion raises `UnsupportedError` |
+| JSCalendar 2.0 | Awaiting a published RFC |
+| iCalendar conversion, invitations, free/busy services and alert delivery | Outside this release |
+
+`Jscalendar` is an alias of `JSCalendar`. Wire names are camelCase; Ruby accessors also accept snake_case. `Event.build` and `Task.build` generate `uid` and `updated`. Nested typed views update their owning object; `to_h` returns an independent copy. `Group#entries` contains typed Event/Task views and preserved unknown entries.
+
+## Validation and patches
+
+```ruby
+calendar = JSCalendar.parse(json, strict: false)
+calendar.warnings.each { |violation| warn "#{violation.pointer}: #{violation.message}" }
+JSCalendar.validate(json) # array of violations
+calendar.localize("ja")  # a localized copy; source stays unchanged
+
+patch = JSCalendar::PatchObject.new("title" => "New title", "description" => nil)
+patched = patch.apply(calendar.to_h)
+```
+
+Strict parsing raises `ValidationError` with `errors` and a JSON Pointer in `pointer`. Lenient parsing preserves invalid fields with diagnostics. Serialization always validates. Unknown root types and malformed JSON raise `ParseError`; resource bounds raise `LimitError`, including in lenient mode. Duplicate keys are rejected with both supported json major versions.
+
+Recurrence overrides ignore the protected property prefixes specified by RFC 8984 §4.3.5. An `excluded: true` override can contain no other change. Localizations ignore disallowed paths. Patches never partially modify their target.
+
+## Time and recurrence
+
+`start` and `due` return `LocalDateTime` values; `duration` returns a `Duration`. `Duration#to_seconds` is the nominal elapsed time, while `add_to` and `Event#end_time` honor calendar days across DST. `SignedDuration` supports positive and negative offsets. JSON and typed values preserve fractional seconds. Conversion to Ruby `Time` raises `UnsupportedError` for leap seconds or precision the runtime cannot retain (for example, subnanosecond fractions on TruffleRuby). Rational seconds must have a finite decimal representation.
+
+Floating date-times require an explicit zone for an instant: `event.start_time(time_zone: "Europe/London")`. Occurrence windows use `Time` values, include `from`, and exclude `to`. Without a zone, floating recurrence windows are interpreted as UTC-shaped wall times, and each occurrence still needs a reference zone for `start_time`.
+
+An occurrence inherits the base object and applies its override. `recurrence_id` identifies its original wall time, even if an override moves its start. DTSTART is always an included first instance and consumes one COUNT, as specified by JSCalendar. Exclusion rules include DTSTART only when it matches the rule. The result reports `truncated?` when the output/candidate bound cuts off the requested expansion.
+
+Time-zone results follow the installed TZInfo data. Its explicit future transition horizon can be shorter than other timezone databases (for example, the current Ruby data ends New York transitions in 2076); do not use the last known offset as a guarantee about distant-future civil time. Custom `timeZones` definitions can express application-owned transition rules.
+
+## Resource bounds
+
+| Option | Default |
+| --- | --- |
+| `max_input_size` | 16 MiB |
+| `max_depth` | 32 |
+| `max_map_size` | 10,000 members per collection |
+| `max_data_uri_size` | 1 MiB decoded |
+| `max_patches` | 1,000 |
+| `max_occurrences` | 10,000 candidates per rule |
+| `max_rules` | 100 combined inclusion/exclusion rules |
+| `max_occurrence_bytes` | 32 MiB of expanded calendar data |
+
+Pass these keyword options to `parse` or model constructors. `occurrences` additionally requires `to`, defaults to `limit: 1000`, and enforces `timeout: 2.0` seconds over the entire expansion. An exclusion set larger than the candidate budget fails instead of returning an incorrect partial subtraction. Impossible recurrence rules also time out. URIs are data and are never fetched.
+
+## Development and references
+
+```sh
+bundle install
+bundle exec rake test
+COVERAGE=1 bundle exec rake test
+bundle exec rubocop
+bundle exec rbs -I sig validate
+bundle exec ruby script/interop.rb
+bundle exec ruby script/benchmark.rb
+```
+
+RFC source documents and 52 generated examples are fetched into ignored `tmp/` with pinned checksums and a generated-fixture fingerprint. Original text, correction notes and the applicable test-source license notice remain there. RFC material, IANA downloads, external implementations, tests and build artifacts are excluded from the Gem. Authored implementation and validation metadata are MIT licensed.
+
+`script/update_registry.rb` checks property and enum identifiers against pinned IANA registries, CLDR calendar names and CSS Level 3 color names. Downloaded sources remain in ignored `tmp/registry/`; only identifiers needed for validation are present in the authored metadata. Updating a checksum requires reviewing the corresponding metadata differences. Source terms are available from [IANA](https://www.iana.org/help/licensing-terms), [Unicode](https://www.unicode.org/license.txt) and [W3C](https://www.w3.org/copyright/document-license/).
+
+The interoperability job compares all 42 RFC 5545 recurrence examples with Stalwart's `calcard` 0.3.2. It records one exact upstream UTC UNTIL discrepancy and compares dates before 2050, within the shared time-zone transition horizon. RFC 8984's ten examples all round trip. See [specification decisions](docs/specification.md) for errata and extraction corrections.

data/SECURITY.md

@@ -0,0 +1,9 @@
+# Security
+
+Report vulnerabilities through [GitHub private vulnerability reporting](https://github.com/ydah/jscalendar/security/advisories/new).
+Include a minimal reproducer and the affected gem and Ruby versions.
+
+Calendar data can include private locations and contact details. Applications control authentication, sharing, storage and logging.
+Parsing never fetches calendar URIs, executes content, schedules invitations or sends alerts.
+Input size, depth, collection sizes and recurrence work are bounded. Resource limits are hard failures even with `strict: false`.
+Recurrence expansion requires an end time, caps its output and interrupts work after a configurable time budget.

data/data/enums.yml

@@ -0,0 +1,450 @@
+# RFC 8984 enum identifiers.
+---
+relation:
+- first
+- next
+- child
+- parent
+display:
+- badge
+- graphic
+- fullsize
+- thumbnail
+relativeTo:
+- start
+- end
+feature:
+- audio
+- chat
+- feed
+- moderator
+- phone
+- screen
+- video
+frequency:
+- yearly
+- monthly
+- weekly
+- daily
+- hourly
+- minutely
+- secondly
+skip:
+- omit
+- backward
+- forward
+day:
+- mo
+- tu
+- we
+- th
+- fr
+- sa
+- su
+freeBusyStatus:
+- free
+- busy
+privacy:
+- public
+- private
+- secret
+kind:
+- individual
+- group
+- location
+- resource
+role:
+- owner
+- attendee
+- optional
+- informational
+- chair
+- contact
+participationStatus:
+- needs-action
+- accepted
+- declined
+- tentative
+- delegated
+scheduleAgent:
+- server
+- client
+- none
+action:
+- display
+- email
+status:
+- confirmed
+- cancelled
+- tentative
+progress:
+- needs-action
+- in-process
+- completed
+- failed
+- cancelled
+rel:
+- about
+- acl
+- alternate
+- amphtml
+- api-catalog
+- appendix
+- apple-touch-icon
+- apple-touch-startup-image
+- archives
+- author
+- blocked-by
+- bookmark
+- c2pa-manifest
+- canonical
+- chapter
+- cite-as
+- collection
+- compression-dictionary
+- contents
+- convertedfrom
+- copyright
+- create-form
+- current
+- deprecation
+- describedby
+- describes
+- disclosure
+- dns-prefetch
+- dpp
+- duplicate
+- edit
+- edit-form
+- edit-media
+- enclosure
+- external
+- first
+- geofeed
+- glossary
+- help
+- hosts
+- hub
+- ice-server
+- icon
+- index
+- intervalafter
+- intervalbefore
+- intervalcontains
+- intervaldisjoint
+- intervalduring
+- intervalequals
+- intervalfinishedby
+- intervalfinishes
+- intervalin
+- intervalmeets
+- intervalmetby
+- intervaloverlappedby
+- intervaloverlaps
+- intervalstartedby
+- intervalstarts
+- item
+- last
+- latest-version
+- license
+- linkset
+- lrdd
+- manifest
+- mask-icon
+- me
+- media-feed
+- memento
+- micropub
+- modulepreload
+- monitor
+- monitor-group
+- next
+- next-archive
+- nofollow
+- noopener
+- noreferrer
+- opener
+- openid2.local_id
+- openid2.provider
+- original
+- p3pv1
+- payment
+- pingback
+- preconnect
+- predecessor-version
+- prefetch
+- preload
+- prerender
+- prev
+- prev-archive
+- preview
+- previous
+- privacy-policy
+- profile
+- publication
+- rdap-active
+- rdap-bottom
+- rdap-down
+- rdap-top
+- rdap-up
+- related
+- replies
+- restconf
+- ruleinput
+- search
+- section
+- self
+- service
+- service-desc
+- service-doc
+- service-meta
+- sip-trunking-capability
+- sponsored
+- start
+- status
+- stylesheet
+- subsection
+- successor-version
+- sunset
+- tag
+- terms-of-service
+- timegate
+- timemap
+- type
+- ugc
+- up
+- version-history
+- via
+- webmention
+- working-copy
+- working-copy-of
+locationType:
+- aircraft
+- airport
+- arena
+- automobile
+- bank
+- bar
+- bicycle
+- bus
+- bus-station
+- cafe
+- campground
+- care-facility
+- classroom
+- club
+- construction
+- convention-center
+- detached-unit
+- fire-station
+- government
+- hospital
+- hotel
+- industrial
+- landmark-address
+- library
+- motorcycle
+- municipal-garage
+- museum
+- office
+- other
+- outdoors
+- parking
+- phone-box
+- place-of-worship
+- post-office
+- prison
+- public
+- public-transport
+- residence
+- restaurant
+- school
+- shopping-area
+- stadium
+- store
+- street
+- theater
+- toll-booth
+- town-hall
+- train
+- train-station
+- truck
+- underway
+- unknown
+- utilitybox
+- warehouse
+- waste-transfer-facility
+- water
+- water-facility
+- watercraft
+- youth-camp
+rscale:
+- buddhist
+- chinese
+- coptic
+- dangi
+- ethioaa
+- ethiopic
+- ethiopic-amete-alem
+- gregorian
+- gregory
+- hebrew
+- indian
+- islamic
+- islamic-civil
+- islamic-rgsa
+- islamic-tbla
+- islamic-umalqura
+- islamicc
+- iso8601
+- japanese
+- persian
+- roc
+color:
+- aliceblue
+- antiquewhite
+- aqua
+- aquamarine
+- azure
+- beige
+- bisque
+- black
+- blanchedalmond
+- blue
+- blueviolet
+- brown
+- burlywood
+- cadetblue
+- chartreuse
+- chocolate
+- coral
+- cornflowerblue
+- cornsilk
+- crimson
+- cyan
+- darkblue
+- darkcyan
+- darkgoldenrod
+- darkgray
+- darkgreen
+- darkgrey
+- darkkhaki
+- darkmagenta
+- darkolivegreen
+- darkorange
+- darkorchid
+- darkred
+- darksalmon
+- darkseagreen
+- darkslateblue
+- darkslategray
+- darkslategrey
+- darkturquoise
+- darkviolet
+- deeppink
+- deepskyblue
+- dimgray
+- dimgrey
+- dodgerblue
+- firebrick
+- floralwhite
+- forestgreen
+- fuchsia
+- gainsboro
+- ghostwhite
+- gold
+- goldenrod
+- gray
+- green
+- greenyellow
+- grey
+- honeydew
+- hotpink
+- indianred
+- indigo
+- ivory
+- khaki
+- lavender
+- lavenderblush
+- lawngreen
+- lemonchiffon
+- lightblue
+- lightcoral
+- lightcyan
+- lightgoldenrodyellow
+- lightgray
+- lightgreen
+- lightgrey
+- lightpink
+- lightsalmon
+- lightseagreen
+- lightskyblue
+- lightslategray
+- lightslategrey
+- lightsteelblue
+- lightyellow
+- lime
+- limegreen
+- linen
+- magenta
+- maroon
+- mediumaquamarine
+- mediumblue
+- mediumorchid
+- mediumpurple
+- mediumseagreen
+- mediumslateblue
+- mediumspringgreen
+- mediumturquoise
+- mediumvioletred
+- midnightblue
+- mintcream
+- mistyrose
+- moccasin
+- navajowhite
+- navy
+- oldlace
+- olive
+- olivedrab
+- orange
+- orangered
+- orchid
+- palegoldenrod
+- palegreen
+- paleturquoise
+- palevioletred
+- papayawhip
+- peachpuff
+- peru
+- pink
+- plum
+- powderblue
+- purple
+- red
+- rosybrown
+- royalblue
+- saddlebrown
+- salmon
+- sandybrown
+- seagreen
+- seashell
+- sienna
+- silver
+- skyblue
+- slateblue
+- slategray
+- slategrey
+- snow
+- springgreen
+- steelblue
+- tan
+- teal
+- thistle
+- tomato
+- turquoise
+- violet
+- wheat
+- white
+- whitesmoke
+- yellow
+- yellowgreen