@dev-pi2pie/word-counter 0.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dev-pi2pie
+
+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,222 @@
+# Word Counter
+
+Locale-aware word counting powered by the Web API [`Intl.Segmenter`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter). The script automatically detects the primary writing system for each portion of the input, segments the text with the matching locale, and reports word totals per language.
+
+## How It Works
+
+- The runtime inspects each character's Unicode script to infer its likely locale (e.g., `und-Latn`, `zh-Hans`, `ja`).
+- Adjacent characters that share the same locale are grouped into a chunk.
+- Each chunk is counted with `Intl.Segmenter` at `granularity: "word"`, caching segmenters to avoid re-instantiation.
+- Per-locale counts are summed into a overall total and printed to stdout.
+
+## Installation
+
+### For Development
+
+Clone the repository and set up locally:
+
+```bash
+git clone https://github.com/dev-pi2pie/word-counter.git
+cd word-counter
+bun install
+bun run build
+npm link
+```
+
+After linking, you can use the `word-counter` command globally:
+
+```bash
+word-counter "Hello 世界 안녕"
+```
+
+To use the linked package inside another project:
+
+```bash
+npm link @dev-pi2pie/word-counter
+```
+
+To uninstall the global link:
+
+```bash
+npm unlink --global @dev-pi2pie/word-counter
+```
+
+### From npm Registry (npmjs.com)
+
+```bash
+npm install -g @dev-pi2pie/word-counter@latest
+```
+
+### From GitHub Packages
+
+If your scope is configured to use GitHub Packages:
+
+```bash
+# ~/.npmrc
+@dev-pi2pie:registry=https://npm.pkg.github.com
+```
+
+```bash
+npm install -g @dev-pi2pie/word-counter@latest
+```
+
+If your scope is configured to use npmjs instead, the same scoped package name
+will resolve from npmjs.com (see the npm registry section above).
+
+> [!note]
+> **npm** may show newer releases (for example, `v0.0.6`) while GitHub Packages still lists `v0.0.5`.
+> This is historical; releases kept in sync starting with `v0.0.6`.
+
+## Usage
+
+Once installed (via `npm link`, npm registry, or GitHub Packages), you can use the CLI directly:
+
+```bash
+word-counter "Hello 世界 안녕"
+```
+
+Alternatively, run the built CLI with Node:
+
+```bash
+node dist/esm/bin.mjs "Hello 世界 안녕"
+```
+
+You can also pipe text:
+
+```bash
+echo "こんにちは world مرحبا" | word-counter
+```
+
+Or read from a file:
+
+```bash
+word-counter --path ./fixtures/sample.txt
+```
+
+## Library Usage
+
+The package exports can be used after installing from GitHub Packages or linking locally with `npm link`.
+
+### ESM
+
+```js
+import wordCounter, { countWordsForLocale, segmentTextByLocale } from "@dev-pi2pie/word-counter";
+```
+
+### CJS
+
+```js
+const wordCounter = require("@dev-pi2pie/word-counter");
+const { countWordsForLocale, segmentTextByLocale, showSingularOrPluralWord } = wordCounter;
+```
+
+### Display Modes
+
+Choose a breakdown style with `--mode` (or `-m`):
+
+- `chunk` (default) – list each contiguous locale block in order of appearance.
+- `segments` – show the actual wordlike segments used for counting.
+- `collector` – aggregate counts per locale regardless of text position.
+
+Examples:
+
+```bash
+# chunk mode (default)
+word-counter "飛鳥 bird 貓 cat; how do you do?"
+
+# show captured segments
+word-counter --mode segments "飛鳥 bird 貓 cat; how do you do?"
+
+# aggregate per locale
+word-counter -m collector "飛鳥 bird 貓 cat; how do you do?"
+```
+
+### Section Modes (Frontmatter)
+
+Use `--section` to control which parts of a markdown document are counted:
+
+- `all` (default) – count the whole file (fast path, no section split).
+- `split` – count frontmatter and content separately.
+- `frontmatter` – count frontmatter only.
+- `content` – count content only.
+- `per-key` – count frontmatter per key (frontmatter only).
+- `split-per-key` – per-key frontmatter counts plus a content total.
+
+Supported frontmatter formats:
+
+- YAML fenced with `---`
+- TOML fenced with `+++`
+- JSON fenced with `;;;` or a top-of-file JSON object (`{ ... }`)
+
+Examples:
+
+```bash
+word-counter --section split -p examples/yaml-basic.md
+word-counter --section per-key -p examples/yaml-basic.md
+word-counter --section split-per-key -p examples/yaml-basic.md
+```
+
+JSON output includes a `source` field (`frontmatter` or `content`) to avoid key collisions:
+
+```bash
+word-counter --section split-per-key --format json -p examples/yaml-content-key.md
+```
+
+Example (trimmed):
+
+```json
+{
+  "section": "split-per-key",
+  "frontmatterType": "yaml",
+  "total": 7,
+  "items": [
+    { "name": "content", "source": "frontmatter", "result": { "total": 3 } },
+    { "name": "content", "source": "content", "result": { "total": 4 } }
+  ]
+}
+```
+
+### Output Formats
+
+Select how results are printed with `--format`:
+
+- `standard` (default) – total plus per-locale breakdown.
+- `raw` – only the total count (single number).
+- `json` – machine-readable output; add `--pretty` for indentation.
+
+Examples:
+
+```bash
+word-counter --format raw "Hello world"
+word-counter --format json --pretty "Hello world"
+```
+
+## Locale Detection Notes (Migration)
+
+- Ambiguous Latin text now uses `und-Latn` instead of defaulting to `en`.
+- Use `--mode chunk`/`--mode segments` or `--format json` to see the exact locale assigned to each chunk.
+- Regex/script-only detection cannot reliably identify English vs. other Latin-script languages; 100% certainty requires explicit metadata (document language tags, user-provided locale, headers) or a language-ID model.
+
+## Testing
+
+Run the build before tests so the CJS interop test can load the emitted
+`dist/cjs/index.cjs` bundle:
+
+```bash
+bun run build
+bun test
+```
+
+## Sample Inputs
+
+Try the following mixed-locale phrases to see how detection behaves:
+
+- `"Hello world 你好世界"`
+- `"Bonjour le monde こんにちは 세계"`
+- `"¡Hola! مرحبا Hello"`
+
+Each run prints the total word count plus a per-locale breakdown, helping you understand how multilingual text is segmented.
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.