Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,14 @@ Files in [`ai/contributing/standards/`](ai/contributing/standards/README.md) are
- **Natural-language legibility wins:** Judge every method and signature by how clearly it reads aloud at the callsite (`today().plus(2, 'days').at('9am').in('Europe/Berlin')`).
- **Zero runtime dependencies:** `native-dates` installs nothing. Fork and copy only minimal needed helpers from `@semantic-ui/utils` into `src/helpers/` rather than adding dependencies or inventing ad-hoc names.
- **Comment voice:** Comment only non-obvious constraints, invariants, or gotchas (`npm run comments`). Start with a lowercase word, avoid em-dashes, prose semicolons, and unicode arrows, and omit trailing periods on single-line comments.
- **Commit format:** `Category: Description` (both capitalized, without a trailing period or `Co-Authored-By` trailer). Categories: `Feat`, `Bug`, `Docs`, `Chore`, `Harness`, `Test`, `Perf`, `Refactor`, `Build`, `Bench`, `BREAKING`. Git hooks in `tools/hooks/` enforce this format and block agent commits directly to `main`.
- **Commit and PR format:** Single-line commit subject only: `Category: Description` (both capitalized, without a body, trailing period, `Co-Authored-By`, or session trailer). Leave pull request descriptions blank (`--body ""`) for human authorship. Categories: `Feat`, `Bug`, `Docs`, `Chore`, `Harness`, `Test`, `Perf`, `Refactor`, `Build`, `Bench`, `BREAKING`. Git hooks in `tools/hooks/` enforce this format and block agent commits directly to `main`.
- **Hand-authored maintainer files (`README.md`, `ai/contributing/north-star.md`, `ai/contributing/standards/lessons/naming-lessons.md`):** Written by the maintainer in his own voice. Leave them untouched and never edit or polish them unless explicitly asked; keep READMEs under `packages/` as brief factual descriptions until the maintainer authors them.
- **Bespoke homepage:** `docs/src/views/Home.astro` is custom-built around `native-dates`'s specific value proposition with interactive demos verified at build time.
- **Bundle size budget:** Run `npm run size` after editing `src/` or `packages/`. Bug fixes aim for 0 added bytes, features declare expected bytes up front, and unused headroom is not a justification (`ai/contributing/budget.md`).
- **Structured errors:** Build every error via `refuse()` or `refuseType()` in `src/helpers/errors.js` (`dates refused [code] at`). Explanations are gated behind `isDevelopment` (`NODE_ENV !== 'production'`) so production builds omit diagnostic prose (`ai/contributing/standards/legibility/errors-and-logs.md`, checked by `npm run errors` and `npm run size`).
- **Behavioral tests and environments:** Assert `error.code` and `error.at` rather than matching prose sentences (`ai/contributing/standards/legibility/tests-and-test-names.md`). Each package's tests live with it (`test/` for `native-dates` and `packages/<name>/test/` for the others) and import packages by their public names; repo and CI tooling tests live under `tools/`. Place pure Node tests in `test/` (core nouns at the top, cross-cutting suites in subfolders like `test/format/` and `test/helpers/`), DOM tests in `test/dom/`, and real Chromium Playwright tests in `test/browser/` (`vitest.config.js`).
- **Category-grouped helpers:** Group free functions by domain in `src/helpers/` (`intl.js`, `zones.js`, `parse.js`, `format.js`, `errors.js`, `utils.js`, `environment.js`).
- **Decision records:** Record package behavior decisions in `ai/contributing/decisions.md` and repository process decisions in `ai/contributing/project-decisions.md`, each dated with the maintainer's confidence score and a reopen condition.
- **Decision records:** Record package behavior decisions in `ai/contributing/decisions.md` and repository process decisions in `ai/contributing/project-decisions.md`, each dated with a reopen condition and an optional maintainer confidence score.
- **Scratch directory:** Put temporary plans and notes in git-ignored `ai/workspace/`.

## Undecided
Expand All @@ -59,7 +59,8 @@ Ask the maintainer rather than inventing conventions for:
- `npm run types`: Type-check `.d.ts` declarations via `tsc --noEmit` under NodeNext and `bundler` resolution (`test/types.ts`)
- `npm run errors`: Check error and log prose register (`tools/gates/errors.js`)
- `npm run comments`: Check comment density, overlap, and banned jargon (`tools/gates/comments.js`)
- `npm run ai`: Validate markdown links, `#anchors`, GFM tables, `ai/` paths, and `AGENTS.md` symlinks (`tools/gates/ai.js`)
- `npm run ai`: Validate markdown links, `#anchors`, GFM tables, `ai/` paths, `decisions-index.md`, and `AGENTS.md` symlinks (`tools/gates/ai.js`)
- `npm run ai:index`: Regenerate `ai/contributing/decisions-index.md` from `ai/contributing/decisions.md` (`tools/gates/decisions-index.js`)
- `npm run size`: Measure minified and Brotli-11 sizes for `native-dates` and every plugin in `@native-dates/plugins`, and check `ai/contributing/budget.md` ([`tools/ci/bundle/README.md`](tools/ci/bundle/README.md))
- `npm run docs`: Start the Astro docs dev server (`docs/`, see [`docs/README.md`](docs/README.md))
- `npm run format`: Format files with `dprint`
Expand Down
4 changes: 2 additions & 2 deletions ai/contributing/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Internal records and workflows for developing `native-dates`. Application develo
| Task | Reading order |
|---|---|
| Fix a bug, add a feature, or file a bug report | [`CONTRIBUTING.md`](../../CONTRIBUTING.md), then [`workflows/contribute.md`](workflows/contribute.md) |
| Check design or process rulings | [`decisions.md`](decisions.md) for package behavior and [`project-decisions.md`](project-decisions.md) for repo process |
| Check design or process rulings | [`decisions-index.md`](decisions-index.md) and [`decisions.md`](decisions.md) for package behavior, [`project-decisions.md`](project-decisions.md) for repo process |
| Check bundle size limits | [`budget.md`](budget.md), checked by `npm run size` |
| Configure GitHub secrets, bots, and Vercel deploys | [`reference/setup.md`](reference/setup.md) |
| View pending and completed launch tasks | [`plan/roadmap.md`](plan/roadmap.md) and [`plan/landed.md`](plan/landed.md) |
Expand All @@ -25,7 +25,7 @@ Internal records and workflows for developing `native-dates`. Application develo
| Record | Path | Policy |
|---|---|---|
| North star | [`north-star.md`](north-star.md) | Hand-authored by the maintainer on project goals, the Golden Rule, call-site SNR, lowercase-"c" correctness, conciseness, and Bayesian rulings (do not edit or polish) |
| Package decisions | [`decisions.md`](decisions.md) | Append-only dated entries with maintainer confidence score and reopen condition |
| Package decisions | [`decisions.md`](decisions.md), [`decisions-index.md`](decisions-index.md) | Append-only dated entries with reopen conditions and optional maintainer confidence scores (`npm run ai:index` updates the index) |
| Project decisions | [`project-decisions.md`](project-decisions.md) | Append-only dated entries for repo process, CI, and docs conventions |
| Size budget | [`budget.md`](budget.md) | Entry bundles, Brotli ceilings, and per-PR growth rules, updated only by the maintainer |
| Launch plan | [`plan/`](plan/roadmap.md) | Pending rows in `roadmap.md`, completed rows in `landed.md`, and briefs in `plan/scopes/` |
Expand Down
104 changes: 104 additions & 0 deletions ai/contributing/decisions-index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
# Decisions Index

> Generated from [`decisions.md`](decisions.md) by `npm run ai:index` and checked by `npm run ai`. Do not edit by hand.

## By Topic

Active decisions grouped by area, newest first.

### Zones, Offsets, and Serialization

- [L27](decisions.md#datetime-serializes-to-iso-8601-utc-rather-than-temporals-bracketed-zone-string-2026-11-05) · `DateTime` serializes to ISO 8601 UTC rather than Temporal's bracketed `[Zone]` string (2026-11-05)
- Reopen: RFC 9557 bracketed zone strings gain broad database and parser support and callers request round-tripping `.zone` through JSON.
- [L21](decisions.md#trailing-z-and-numeric-offsets-in-datetime-set-the-instant-not-zone-2026-11-05) · Trailing `Z` and numeric offsets in `datetime()` set the instant, not `.zone` (2026-11-05)
- Reopen: downstream bug reports show callers passing `Z` strings expecting `.hour` and `.zone` to default to `'UTC'`.

### Ranges

- [L111](decisions.md#ranges-accept-for-for-durations-alongside-to-and-only-calendardate-has-through-2026-11-17) · Ranges accept `.for()` for durations alongside `.to()`, and only `CalendarDate` has `.through()` (2026-11-17)
- Reopen: callers pass endpoints to `.for()` expecting runtime rejection, or expect `.through()` on `DateTime` with inclusive end semantics.
- [L45](decisions.md#daterange-includes-its-end-date-while-datetimerange-and-timerange-are-half-open-2026-11-12) · `DateRange` includes its end date while `DateTimeRange` and `TimeRange` are half-open (2026-11-12)
- Reopen: bug reports show callers frequently off by one day when converting between `DateRange` and `DateTimeRange`.

### Durations

- [L105](decisions.md#duration-uses-balance-without-a-normalize-alias-and-totalunit-instead-of-inunit-2026-11-17) · `Duration` uses `balance()` without a `normalize()` alias, and `total(unit)` instead of `in(unit)` (2026-11-17)
- Reopen: cold-reader studies or user issues show callers repeatedly reaching for `duration.in(unit)` or `duration.normalize()`.

### Arithmetic, Boundaries, and Weekdays

- [L117](decisions.md#adjacent-unit-boundaries-use-startofnext-and-startofprevious-instead-of-overloading-next-and-previous-2026-11-19) · Adjacent unit boundaries use `startOfNext()` and `startOfPrevious()` instead of overloading `next()` and `previous()` (2026-11-19)
- Reopen: callers consistently try unit names in `next()` and `previous()`, or expect numeric weekdays in `startOfNext()`.
- [L99](decisions.md#numeric-day-of-the-week-is-dayofweek-1-7-while-token-d-keeps-moments-0-6-2026-11-17) · Numeric day of the week is `dayOfWeek` (`1`-`7`) while token `d` keeps Moment's `0`-`6` (2026-11-17)
- Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` returns `7`, or request the `E` token.
- [L57](decisions.md#default-week-boundaries-follow-the-locale-while-weekofyear-stays-iso-monday-2026-11-14) · Default week boundaries follow the locale while `weekOfYear` stays ISO Monday (2026-11-14)
- Reopen: server code accidentally partitions stored weekly aggregates differently across requests carrying different `.locale()` tags.

### Formatting, Tokens, and Locales

- [L81](decisions.md#custom-weekdaynames-ordinals-and-named-formats-live-in-configure-instead-of-locale-plugins-2026-11-16) · Custom `weekdayNames`, `ordinals`, and named `formats` live in `configure()` instead of locale plugins (2026-11-16)
- Reopen: multiple downstream apps duplicate the same locale ordinal or `dd` overrides and warrant a shared community table.
- [L63](decisions.md#format-tokens-output-ascii-digits-and-gregorian-years-while-presets-localize-the-calendar-2026-11-14) · Format tokens output ASCII digits and Gregorian years while presets localize the calendar (2026-11-14)
- Reopen: native speakers request an opt-in localized-numeral token mode or non-Gregorian partial dates.
- [L51](decisions.md#locale-attaches-a-formatting-locale-to-values-without-affecting-equality-or-json-2026-11-14) · `.locale()` attaches a formatting locale to values without affecting equality or JSON (2026-11-14)
- Reopen: callers hit assertion bugs because two `.equals()` values in different locales have different `.text` own properties under deep-object equality.

### Parsing, Inputs, and Comparisons

- [L87](decisions.md#core-parses-unambiguous-non-iso-inputs-and-refuses-inputs-with-two-readings-2026-11-16) · Core parses unambiguous non-ISO inputs and refuses inputs with two readings (2026-11-16)
- Reopen: a non-ISO form accepted in core misparses real input, or callers repeatedly hit one of the remaining refusals where an explicit option could disambiguate.

### Nouns, Instances, and Epoch

- [L93](decisions.md#unix-timestamp-properties-include-their-unit-epochseconds-epochmilliseconds-epochnanoseconds-with-no-bare-epoch-2026-11-17) · Unix timestamp properties include their unit (`epochSeconds`, `epochMilliseconds`, `epochNanoseconds`) with no bare `.epoch` (2026-11-17)
- Reopen: migration feedback shows omitting `.epoch` causes widespread friction without preventing real seconds-vs-milliseconds bugs.
- [L33](decisions.md#instances-freeze-on-construction-with-text-as-an-eager-own-property-2026-11-05) · Instances freeze on construction with `text` as an eager own property (2026-11-05)
- Reopen: benchmark profiles in `bench/` show eager `text` construction dominating hot arithmetic or `range.points()` loops.

### Plugins, Errors, and Dependencies

- [L75](decisions.md#error-explanations-use-inline-isdevelopment-checks-and--loose-true--still-throws-on-bad-options-2026-11-16) · Error explanations use inline `isDevelopment` checks, and `{ loose: true }` still throws on bad options (2026-11-16)
- Reopen: callers building dynamic zone or format inputs from untrusted user text need a non-throwing validation helper.
- [L69](decisions.md#core-has-zero-runtime-dependencies-and-trims-forked-semantic-uiutils-helpers-to-used-branches-2026-11-16) · Core has zero runtime dependencies and trims forked `@semantic-ui/utils` helpers to used branches (2026-11-16)
- Reopen: `@semantic-ui/utils` publishes tree-shakeable single-branch entrypoints with zero unreached bytes and consumers favor cross-package deduplication over zero dependencies.
- [L39](decisions.md#plugins-attach-on-subpath-import-instead-of-requiring-use-or-extend-2026-11-08) · Plugins attach on subpath import instead of requiring `use()` or `extend()` (2026-11-08)
- Reopen: a standard bundler configuration tree-shakes an imported `@native-dates/plugins/*` module despite `"sideEffects": ["./src/*.js"]`.

## Chronological

Every entry in file order.

- [L21](decisions.md#trailing-z-and-numeric-offsets-in-datetime-set-the-instant-not-zone-2026-11-05) · Trailing `Z` and numeric offsets in `datetime()` set the instant, not `.zone` (2026-11-05)
- Reopen: downstream bug reports show callers passing `Z` strings expecting `.hour` and `.zone` to default to `'UTC'`.
- [L27](decisions.md#datetime-serializes-to-iso-8601-utc-rather-than-temporals-bracketed-zone-string-2026-11-05) · `DateTime` serializes to ISO 8601 UTC rather than Temporal's bracketed `[Zone]` string (2026-11-05)
- Reopen: RFC 9557 bracketed zone strings gain broad database and parser support and callers request round-tripping `.zone` through JSON.
- [L33](decisions.md#instances-freeze-on-construction-with-text-as-an-eager-own-property-2026-11-05) · Instances freeze on construction with `text` as an eager own property (2026-11-05)
- Reopen: benchmark profiles in `bench/` show eager `text` construction dominating hot arithmetic or `range.points()` loops.
- [L39](decisions.md#plugins-attach-on-subpath-import-instead-of-requiring-use-or-extend-2026-11-08) · Plugins attach on subpath import instead of requiring `use()` or `extend()` (2026-11-08)
- Reopen: a standard bundler configuration tree-shakes an imported `@native-dates/plugins/*` module despite `"sideEffects": ["./src/*.js"]`.
- [L45](decisions.md#daterange-includes-its-end-date-while-datetimerange-and-timerange-are-half-open-2026-11-12) · `DateRange` includes its end date while `DateTimeRange` and `TimeRange` are half-open (2026-11-12)
- Reopen: bug reports show callers frequently off by one day when converting between `DateRange` and `DateTimeRange`.
- [L51](decisions.md#locale-attaches-a-formatting-locale-to-values-without-affecting-equality-or-json-2026-11-14) · `.locale()` attaches a formatting locale to values without affecting equality or JSON (2026-11-14)
- Reopen: callers hit assertion bugs because two `.equals()` values in different locales have different `.text` own properties under deep-object equality.
- [L57](decisions.md#default-week-boundaries-follow-the-locale-while-weekofyear-stays-iso-monday-2026-11-14) · Default week boundaries follow the locale while `weekOfYear` stays ISO Monday (2026-11-14)
- Reopen: server code accidentally partitions stored weekly aggregates differently across requests carrying different `.locale()` tags.
- [L63](decisions.md#format-tokens-output-ascii-digits-and-gregorian-years-while-presets-localize-the-calendar-2026-11-14) · Format tokens output ASCII digits and Gregorian years while presets localize the calendar (2026-11-14)
- Reopen: native speakers request an opt-in localized-numeral token mode or non-Gregorian partial dates.
- [L69](decisions.md#core-has-zero-runtime-dependencies-and-trims-forked-semantic-uiutils-helpers-to-used-branches-2026-11-16) · Core has zero runtime dependencies and trims forked `@semantic-ui/utils` helpers to used branches (2026-11-16)
- Reopen: `@semantic-ui/utils` publishes tree-shakeable single-branch entrypoints with zero unreached bytes and consumers favor cross-package deduplication over zero dependencies.
- [L75](decisions.md#error-explanations-use-inline-isdevelopment-checks-and--loose-true--still-throws-on-bad-options-2026-11-16) · Error explanations use inline `isDevelopment` checks, and `{ loose: true }` still throws on bad options (2026-11-16)
- Reopen: callers building dynamic zone or format inputs from untrusted user text need a non-throwing validation helper.
- [L81](decisions.md#custom-weekdaynames-ordinals-and-named-formats-live-in-configure-instead-of-locale-plugins-2026-11-16) · Custom `weekdayNames`, `ordinals`, and named `formats` live in `configure()` instead of locale plugins (2026-11-16)
- Reopen: multiple downstream apps duplicate the same locale ordinal or `dd` overrides and warrant a shared community table.
- [L87](decisions.md#core-parses-unambiguous-non-iso-inputs-and-refuses-inputs-with-two-readings-2026-11-16) · Core parses unambiguous non-ISO inputs and refuses inputs with two readings (2026-11-16)
- Reopen: a non-ISO form accepted in core misparses real input, or callers repeatedly hit one of the remaining refusals where an explicit option could disambiguate.
- [L93](decisions.md#unix-timestamp-properties-include-their-unit-epochseconds-epochmilliseconds-epochnanoseconds-with-no-bare-epoch-2026-11-17) · Unix timestamp properties include their unit (`epochSeconds`, `epochMilliseconds`, `epochNanoseconds`) with no bare `.epoch` (2026-11-17)
- Reopen: migration feedback shows omitting `.epoch` causes widespread friction without preventing real seconds-vs-milliseconds bugs.
- [L99](decisions.md#numeric-day-of-the-week-is-dayofweek-1-7-while-token-d-keeps-moments-0-6-2026-11-17) · Numeric day of the week is `dayOfWeek` (`1`-`7`) while token `d` keeps Moment's `0`-`6` (2026-11-17)
- Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` returns `7`, or request the `E` token.
- [L105](decisions.md#duration-uses-balance-without-a-normalize-alias-and-totalunit-instead-of-inunit-2026-11-17) · `Duration` uses `balance()` without a `normalize()` alias, and `total(unit)` instead of `in(unit)` (2026-11-17)
- Reopen: cold-reader studies or user issues show callers repeatedly reaching for `duration.in(unit)` or `duration.normalize()`.
- [L111](decisions.md#ranges-accept-for-for-durations-alongside-to-and-only-calendardate-has-through-2026-11-17) · Ranges accept `.for()` for durations alongside `.to()`, and only `CalendarDate` has `.through()` (2026-11-17)
- Reopen: callers pass endpoints to `.for()` expecting runtime rejection, or expect `.through()` on `DateTime` with inclusive end semantics.
- [L117](decisions.md#adjacent-unit-boundaries-use-startofnext-and-startofprevious-instead-of-overloading-next-and-previous-2026-11-19) · Adjacent unit boundaries use `startOfNext()` and `startOfPrevious()` instead of overloading `next()` and `previous()` (2026-11-19)
- Reopen: callers consistently try unit names in `next()` and `previous()`, or expect numeric weekdays in `startOfNext()`.
Loading