synset 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 king8fisher
+
+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.

package/README.md

@@ -0,0 +1,190 @@
+# synset
+
+WordNet dictionary parser with Zod validation, query utilities, and CLI.
+
+## Install
+
+```bash
+npm install synset
+# or
+bun add synset
+```
+
+## Usage
+
+### Library
+
+```ts
+import {
+  fetchWordNet,
+  loadWordNet,
+  buildIndex,
+  getDefinitions,
+  getSynonyms,
+  getHypernyms,
+  findSynsets,
+} from 'synset'
+
+// Fetch WordNet data (auto-discovers latest version, downloads & caches ~100MB XML)
+const { lexicon, version } = await fetchWordNet()
+console.log(`Loaded WordNet ${version}`)
+
+// Or load from local file
+const lexicon = await loadWordNet('./path/to/english-wordnet-{YEAR}.xml')
+
+// Or request specific version
+const { lexicon } = await fetchWordNet({ version: '2024' })
+
+// Build index for fast lookups
+const index = buildIndex(lexicon)
+
+// Query
+getDefinitions(index, 'dog')
+// [{ text: "a member of the genus Canis...", synset, partOfSpeech: "n" }, ...]
+
+getSynonyms(index, 'happy')
+// [{ word: "glad", entry, synset }, ...]
+
+getHypernyms(index, 'dog')
+// [Synset for "canine", Synset for "domestic animal", ...]
+
+findSynsets(index, 'bank')
+// [Synset for "financial institution", Synset for "river bank", ...]
+```
+
+### CLI
+
+```bash
+# Show definitions
+synset define dog
+
+# List synonyms
+synset synonyms happy
+
+# Show hypernyms (more general terms)
+synset hypernyms dog
+
+# Show all relations
+synset related computer
+
+# Pre-download WordNet data
+synset fetch
+
+# Use local file instead of cache
+synset define dog --file ./path/to/english-wordnet-{YEAR}.xml
+```
+
+### Exports
+
+```ts
+// Zod schemas (runtime validation)
+import { Lexicon, Synset, Sense, LexicalEntry } from 'synset'
+
+// TypeScript types
+import type { LexiconType, SynsetType, SenseType } from 'synset'
+
+// Human-readable labels
+import { PartsOfSpeechLabels, SynsetRelationLabels } from 'synset'
+```
+
+## Runtime
+
+- **Bun**: Full support (recommended)
+- **Node.js 18+**: Supported for remote fetching. Local file parsing requires Bun due to `file://` URL fetch limitations.
+
+## Development
+
+```bash
+bun install
+bun test
+bun run check  # typecheck
+bun run build  # build dist/
+```
+
+## Dictionary Module
+
+- WordNet
+  - Format:
+    - https://globalwordnet.github.io/schemas/
+      - XML file source:
+        - https://github.com/globalwordnet/english-wordnet
+          - Latest version auto-discovered and downloaded by tests
+        - XML format:
+          [DTD](https://globalwordnet.github.io/schemas/WN-LMF-1.3.dtd)
+          - Manually copied over to
+            - `WN-LMF-1.3.dtd`
+
+### WordNet XML Source Structure
+
+(Originally created with `xmlstarlet` against the 2023 xml file).
+
+`$ xmlstarlet el data/english-wordnet-2023.xml | sort | uniq | sort`
+(with unicode symbols added manually)
+
+```
+📂 LexicalResource               root node
+   📂 Lexicon                    desc of the database: id prefix, language, version, ...
+      📂 LexicalEntry            an id for grouping children that can be refed by a Synset.
+         📄 Form
+         📂 Lemma
+            📄 Pronunciation
+         📂 Sense
+            📄 SenseRelation
+      📂 Synset
+         📄 Definition
+         📄 Example
+         📄 ILIDefinition
+         📄 SynsetRelation
+      📄 SyntacticBehaviour
+```
+
+### Schema Verification
+
+Stats accumulated with:
+* `$ xmlstarlet el data/english-wordnet-2023.xml | sort | uniq -c | sort -n`
+* `$ grep -oE '<[A-Za-z]+' data/english-wordnet-2024.xml | sed 's/<//g' | sort | uniq -c | sort -n`
+
+Element counts comparison (schema unchanged between releases):
+
+| Element            |   2023 |   2024 |
+| ------------------ | -----: | -----: |
+| LexicalResource    |      1 |      1 |
+| Lexicon            |      1 |      1 |
+| SyntacticBehaviour |     39 |     39 |
+| ILIDefinition      |   2700 |   3216 |
+| Form               |   4474 |   4474 |
+| Pronunciation      |  44671 |  44669 |
+| Example            |  49638 |  49723 |
+| Synset             | 120135 | 120630 |
+| Definition         | 120141 | 120635 |
+| SenseRelation      | 122041 | 122018 |
+| LexicalEntry       | 161338 | 161705 |
+| Lemma              | 161338 | 161705 |
+| Sense              | 212071 | 212478 |
+| SynsetRelation     | 293864 | 297150 |
+
+## Zod Test Coverage
+
+```
+📂 LexicalResource                  [-] (basic test for a parent)
+   📂 Lexicon                       [-] (basic test for a parent)
+      📂 LexicalEntry               [x]
+         📄 Form                    [x]
+         📂 Lemma                   [x]
+            📄 Pronunciation        [x]
+         📂 Sense                   [x]
+            📄 SenseRelation        [x]
+      📂 Synset                     [x]
+         📄 Definition              [x]
+         📄 Example                 [x]
+         📄 ILIDefinition           [x]
+         📄 SynsetRelation          [x]
+      📄 SyntacticBehaviour         [x]
+```
+
+## TODO
+
+- [ ] Support [Open English Namenet](https://en-word.net/) - proper nouns (people, places, etc.) were moved to a separate resource starting with 2025 release
+- [ ] Option to fetch "2025+" edition which includes curated proper nouns from Namenet
+- [ ] CLI `--json` flag for JSON output
+- [ ] CLI colored output (disable with `--no-color`)