morphex 0.0.0-stage → 1.0.0

package/BENCHMARKS.md

@@ -0,0 +1,95 @@
+# Benchmarks and bundle sizes
+
+These are **Node.js/V8 micro-benchmarks** for the TypeScript port. They are measured with a
+different runtime and harness from the Java JMH results on the main site and are not comparable
+with them. Nothing here is a cross-language speed claim.
+
+## Method
+
+- Harness: `morphex-ts/scripts/bench.ts` (`npm run bench`), no external benchmark dependency.
+- Machine used for the recorded run: 12th Gen Intel Core i5-12500H, Windows 11 (10.0.26300).
+- Runtime: Node.js 24.20.0 (the package targets Node 18+).
+- Each workload warms up for one full pass, then takes seven timed samples and reports the
+  median. The first timed sample is discarded while V8 finishes optimizing.
+- Repeated workloads run 1,000,000 calls. Distinct-word workloads run ten passes over 4,000
+  unique lemmas (40,000 calls per timed sample) taken from the committed P1 fixture.
+- Five runs were recorded on the same machine to show the spread; ranges below are the
+  minimum and maximum medians, not a confidence interval.
+- Provider construction was measured separately with a tsx harness on the same machine: one
+  warm-up, then twelve samples per run, with the median of each of two runs reported.
+
+Reproduce with:
+
+```bash
+cd morphex-ts
+npm install
+npm run build:data   # writes the generated lexicons and dist/sizes.json
+npm run bench        # writes bench-results.json and prints the table
+```
+
+## Latency (ns/op, lower is better)
+
+| Workload | Delta engine | Full engine | Rules-only |
+| --- | ---: | ---: | ---: |
+| Repeated lexical word (`child`) | 111–119 | 269–280 | 130–139 |
+| Repeated rule word (`cat`) | 112–118 | 174–188 | 104–116 |
+| Repeated compound (`mother-in-law`) | 258–289 | 434–457 | 358–378 |
+| Distinct fixture lemmas (4,000 words) | 354–432 | 1,006–1,057 | 327–355 |
+| `analyze()` repeated (`die`) | 258–278 | 421–441 | 221–228 |
+
+Reading the table:
+
+- The **delta** engine answers `pluralize()` from the shipped artifact. At load time it parses
+  the four artifact sections and inserts them directly into an open-addressed hash index over
+  the 124,883 keys, so a rule-only word such as `cat` costs one hash and a short probe before
+  the rules run. The original four-section implementation measured 673–678 ns; a merged-sort
+  binary search measured 286–293 ns; the hash index measures 112–118 ns. That is about 5.7–6.0×
+  faster than the original and 2.4–2.6× faster than the merged binary search, in the same
+  harness.
+- The **full** engine is opt-in (`morphex/full`) and adds alternatives, ambiguity and
+  countability. It performs one binary search over its own 147,338-key array, so it is now slower
+  than the delta engine on these paths (182–189 ns for `cat`), but it carries the metadata the
+  diagnostics need.
+- The **rules-only** engine (`morphex/rules`, or `withoutBundledLexicon()`) uses no data files and
+  loses irregular forms by design.
+
+The hash index costs 1 MiB of slot storage (262,144 × 4 bytes) and is built once, when the
+provider is created (lazily, on first use). Creating the delta provider now measures 50.3–50.8
+ms median over two runs; parsing the artifact accounts for 32.0–33.1 ms and building the index
+roughly 17–19 ms. Before these changes, construction measured 77–81 ms and parsing 58–65 ms.
+The reduction comes from inserting each section directly into the table instead of merging the
+four lists first, dropping the cross-section duplicate `Set` and the intermediate body copy,
+and sharing one frozen empty alternatives array. The index is still the smaller half of
+construction; nothing is computed at module import.
+- Distinct-word timings include cache misses over a 4,000-word working set and are naturally
+  slower than repeated lookups; the spread between runs is largest there.
+
+## Artifact and bundle sizes
+
+Measured by `scripts/build-lexicon.ts` and `scripts/build-site.ts` and written to
+`dist/sizes.json` / `dist/site/sizes.json`.
+
+| Artifact | Raw | Gzip |
+| --- | ---: | ---: |
+| Source lexicon TSV (shared with Java, not shipped) | 7,553,688 B | — |
+| Delta artifact for `pluralize()` (124,883 entries) | 1,962,900 B | 562,893 B |
+| Full artifact for `analyze()` (147,338 entries) | 3,707,556 B | 785,131 B |
+| Membership sidecar (340,726 hashes, base64) | 1,817,208 B | 1,333,152 B |
+| Browser demo bundle (full lexicon, minified ESM) | 3,735,241 B | 794,191 B |
+
+The delta artifact is 26.0% of the source TSV's size and 84.8% of the full artifact's entries:
+85% of the lexicon is already reproduced by the three productive rules plus the identity lists,
+so only the differing entries and the mass/plural-only/invariant key lists are stored.
+
+The published `dist/lexicon-delta.txt` is the same 1,962,900-byte artifact the site links beside
+the demo; browsers download it gzipped at 562,893 B.
+
+## Notes
+
+- The browser demo loads the **full lexicon without the membership sidecar**: 794,191 B gzip
+  including the engine. Membership is only needed for unknown-uppercase initialism inference, so
+  the demo behaves like a rules-only build for that one policy and says so on the page.
+- The `morphex/rules` entry point replaces the generated delta module at build time; it contains
+  zero lexicon data and therefore no CC BY-SA 3.0 material.
+- Generated data and bundles live under `morphex-ts/dist/` and are gitignored; only the sizes in
+  this file and on the site are committed.

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Justin Baker
+
+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.
+
+The lexical data bundled with this package is not covered by this MIT licence.
+It is licensed under CC BY-SA 3.0; see NOTICE in this directory and the
+repository's data/LICENSE-DATA.md.

package/NOTICE

@@ -0,0 +1,23 @@
+morphex-ts — TypeScript port of morphex
+======================================
+
+Code: MIT (see LICENSE in this directory).
+Lexical data: CC BY-SA 3.0.
+
+The generated lexicon artifacts (dist/lexicon-delta.txt, dist/lexicon-full.txt, the membership
+table, and the browser demo bundle that embeds the full lexicon) are derived from the same
+permitted corpus as the Java library's resources:
+
+    inflector-core/src/main/resources/io/github/slayyyyer/morphex/inflector/lexicon-v2.tsv
+    inflector-core/src/main/resources/io/github/slayyyyer/morphex/inflector/lexicon-membership-v2.bin
+
+That data is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported licence
+(CC BY-SA 3.0): https://creativecommons.org/licenses/by-sa/3.0/
+
+Attribution: Wiktionary contributors, via Kaikki.org / Wiktextract.
+
+The authoritative attribution and data-licence statements for the whole repository are the root
+NOTICE and data/LICENSE-DATA.md; this file is a pointer, not a replacement. If you redistribute a
+build of this package, keep this NOTICE, the root attribution, and the CC BY-SA 3.0 terms with it.
+
+The `morphex/rules` entry point contains no lexicon data and therefore no CC BY-SA 3.0 material.

package/README.md

@@ -1,3 +1,198 @@
-# Temporary Holding Version
+# morphex (TypeScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Deterministic English noun pluralization for TypeScript and JavaScript. This is a native port of
+the Java [morphex](../README.md) library: same precedence pipeline, same lexicon, same compound
+table. No runtime dependencies, no network calls, no model downloads.
+
+```ts
+import { EnglishInflector } from 'morphex';
+
+const inflector = EnglishInflector.standard();
+
+inflector.pluralize('child'); // 'children'
+inflector.pluralize('CHILD'); // 'CHILDREN'
+inflector.pluralize('UFO'); // 'UFOs'
+inflector.pluralize('mother-in-law'); // 'mothers-in-law'
+inflector.pluralize('cat', 1); // 'cat'  (count === 1 keeps the source)
+inflector.pluralize('cat', 3); // 'cats'
+
+const result = inflector.analyze('die');
+result.plural; // 'dice'
+result.alternatives; // ['dies']
+result.ambiguous; // true
+result.stage; // 'LEXICON'
+result.source; // 'lex:die'
+result.countability; // 'COUNTABLE'
+```
+
+Node 18+ and browsers. Zero runtime dependencies. Immutable instances: configuration is fixed at
+build time, so an instance can be shared freely.
+
+## Install
+
+```bash
+npm install morphex
+```
+
+To build from a checkout instead: `cd morphex-ts && npm install && npm run build`.
+
+Entry points:
+
+| Import          | Lexicon                      | Use                                                                           |
+| --------------- | ---------------------------- | ----------------------------------------------------------------------------- |
+| `morphex`       | 124,883-entry delta artifact | `pluralize()`; `analyze()` reports rule/compound stages without full metadata |
+| `morphex/full`  | 147,338-entry full artifact  | Java-identical `analyze()`: alternatives, ambiguity, countability             |
+| `morphex/rules` | none                         | rules-only build with no data files and no CC BY-SA material                  |
+
+The full artifact is opt-in so the common case does not pay for diagnostics it never reads:
+
+```ts
+import { EnglishInflector, createBundledFullLexicon } from 'morphex/full';
+
+const diagnostics = EnglishInflector.builder().withLexicon(createBundledFullLexicon()).build();
+
+diagnostics.analyze('die').alternatives; // ['dies']
+```
+
+## API
+
+### `pluralize(word, count?)`
+
+`pluralize(word, 1)` returns the input unchanged, including its original casing. Any other count
+pluralizes. Both are pure functions of the configured instance.
+
+### `analyze(word): Inflection`
+
+Every field is always present; nothing is optional.
+
+```ts
+interface Inflection {
+  readonly input: string;
+  readonly plural: string;
+  readonly alternatives: readonly string[];
+  readonly ambiguous: boolean;
+  readonly stage: 'OVERRIDE' | 'LEXICON' | 'INFERRED' | 'COMPOUND' | 'RULE' | 'FALLBACK';
+  readonly source: string; // stable id, e.g. 'lex:child', 'rule:default-s'
+  readonly countability: 'COUNTABLE' | 'MASS' | 'MIXED' | 'PLURAL_ONLY' | 'UNKNOWN';
+  readonly invariant: boolean;
+  readonly note: string;
+  readonly diagnostics: boolean; // false when the provider cannot supply full metadata
+  isAccepted(form: string): boolean;
+}
+```
+
+`stage` follows the Java `DecisionSource`; `source` is the Java `Inflection.id()`.
+
+### Configuration
+
+```ts
+const custom = EnglishInflector.builder()
+  .withOverride('goose', 'geese') // exact, case-sensitive whole-input match
+  .withOverride('API', 'APIs')
+  .withInitialism('ABC') // suffix policy for a declared acronym
+  .withMode('CLASSICAL') // prefer attested classical forms
+  .withCasePolicy('LOWERCASE') // render the whole result in one casing
+  .withoutBundledLexicon() // rules-only: no data files at all
+  .build();
+```
+
+Overrides win over everything else and are returned literally. The builder is fluent and typed;
+`build()` returns an `EnglishInflector`. Instances are immutable.
+
+### Custom lexicons
+
+Every data source implements the same provider interface, so bundled, opt-in, rules-only and
+caller-supplied data are interchangeable:
+
+```ts
+import { EnglishInflector, createLexicon } from 'morphex';
+
+const provider = createLexicon([
+  { lemma: 'cactus', plural: 'cactuses', classical: 'cacti', alternatives: ['cacti'] },
+]);
+
+const inflector = EnglishInflector.builder().withLexicon(provider).build();
+```
+
+`createFullLexicon`, `createDeltaLexicon` and `RULES_ONLY_LEXICON` are exported for the same
+purpose. A malformed artifact, duplicate key, unsorted file or unknown flag throws at construction
+time; the loaders never guess.
+
+## Precedence
+
+First match wins, exactly as in the Java library:
+
+1. **Caller override** — exact, case-sensitive whole-input match.
+2. **Exact lexicon entry** — case-insensitive lookup, with case-sensitive entries where needed.
+3. **Declared initialism** — configured acronym suffix policy.
+4. **Supported compound** — bounded table: exact entries, free tails and curated postposed heads.
+   Unmatched input is left alone, not guessed.
+5. **Three productive rules** — `+es` after sibilants, consonant + `y` → `ies`, default `+s`.
+6. **Documented fallback** — unsupported shapes are returned unchanged and reported by `analyze`.
+
+Lookup normalisation is separate from output case restoration, so `CHILD → CHILDREN` and
+`UFO → UFOs` are both correct.
+
+## Rules-only vs bundled lexicon
+
+| Build           |                     Data shipped | `pluralize('child')`  | `analyze()` metadata                            |
+| --------------- | -------------------------------: | --------------------- | ----------------------------------------------- |
+| `morphex/rules` |                              0 B | `childs` (rules only) | rules/compound stages, `diagnostics: false`     |
+| `morphex`       | 1,962,900 B raw / 562,893 B gzip | `children`            | rule/compound stages; partial lexical metadata  |
+| `morphex/full`  | 3,707,556 B raw / 785,131 B gzip | `children`            | complete: alternatives, ambiguity, countability |
+
+A rules-only build is a plain `EnglishInflector.builder().withoutBundledLexicon().build()` and
+needs no data files. The delta engine parses its four artifact sections and builds a 1 MiB
+open-addressed hash index at construction (roughly 50 ms end to end on the measured machine,
+with 17–19 ms of that building the index), so lookups do not scan the sorted keys; nothing is
+built at module import. The full artifact also has a
+1,817,208 B (1,333,152 B gzip) membership sidecar used only for uppercase-initialism inference.
+
+## Building data
+
+The lexicons are generated from the repository's authoritative artifact, not copied:
+
+```bash
+npm run build:data
+```
+
+Reads `inflector-core/src/main/resources/io/github/slayyyyer/morphex/inflector/lexicon-v2.tsv`
+and `lexicon-membership-v2.bin`, and writes gitignored modules under `src/generated/` plus
+`dist/lexicon-delta.txt`, `dist/lexicon-full.txt` and `dist/sizes.json`.
+
+The delta artifact stores only entries whose answer differs from the productive rules, plus
+sorted key lists for mass, plural-only and invariant nouns. Hyphenated and spaced lemmas are kept
+even when the rules would reproduce them, because the rules are unreachable behind the compound
+policy.
+
+## Conformance
+
+Both ports are tested against fixtures exported from the Java engine:
+
+- `test-fixtures/p1.json` — all 50,978 frozen P1 cases, tuple-typed in
+  `test-fixtures/schema.ts`.
+- `test-fixtures/upstream-probe.json` — the `docs/upstream-probe.md` table.
+- `site/catalog.json` — the verified catalog used by the Java site demo.
+
+Vitest runs every case through both the delta and full engines and compares the plural, accepted
+forms, primary flag, countability, invariant flag, stage and source id. CI regenerates the
+fixtures with Java and fails on any diff, so the ports cannot drift silently.
+
+```bash
+npm test             # typecheck-friendly Vitest suite
+npm run typecheck    # strict tsc, no emit
+npm run lint         # typescript-eslint + Prettier
+npm run build        # ESM + CJS + .d.ts/.d.cts via tsup
+npm run check:package # publint + arethetypeswrong
+```
+
+## Benchmarks
+
+See [BENCHMARKS.md](BENCHMARKS.md) for measured Node timings and bundle sizes. The numbers are
+Node/V8 micro-benchmarks and are deliberately separate from the Java JMH results.
+
+## Licence
+
+Code: MIT (see `LICENSE`). Bundled lexicon data: CC BY-SA 3.0, Wiktionary contributors via
+Kaikki.org / Wiktextract — see `NOTICE` and the repository's root `NOTICE` and
+`data/LICENSE-DATA.md`. The `morphex/rules` entry point contains no lexicon data.