Initial Commit

packages/security-stack/security/password-strength/src/dicts/zh-Hans/wikipedia.md

@@ -0,0 +1,64 @@
+# `zh-Hans/wikipedia` — Simplified Chinese frequency dictionary
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Frequency-ranked dictionary of the most common Simplified Chinese tokens
+observed in Wikipedia. Plugs into `assess` for Simplified Chinese-locale
+strength evaluation. Tokens are short surface forms (single CJK ideogram
+or short word) so the matcher can recognise common prefixes in mixed
+input.
+
+## Features
+
+- Frozen `ReadonlyMap<string, number>` keyed by surface-form token
+- Covers high-frequency CJK ideograms including `密码` (password)
+- Swappable via `loadDictionaries`
+
+## Usage: Basic Example
+
+```ts
+import { ZH_HANS_WIKIPEDIA_DICTIONARY } from "@suaveplan/password-strength/dicts/zh-Hans";
+
+console.log(ZH_HANS_WIKIPEDIA_DICTIONARY.get("密码")); // 1
+```
+
+## Usage: Advanced Example
+
+```ts
+import { assess } from "@suaveplan/password-strength";
+import { ZH_HANS_DICTIONARIES } from "@suaveplan/password-strength/dicts/zh-Hans";
+
+const result = assess("密码123", { dictionaries: ZH_HANS_DICTIONARIES });
+console.log(result.score);
+```
+
+## API Reference
+
+- `ZH_HANS_WIKIPEDIA_DICTIONARY: ReadonlyMap<string, number>` — frozen
+  frequency-ranked Simplified Chinese Wikipedia dictionary.
+
+## Implementation Notes
+
+The default subset is intentionally small; CJK tokens are surface forms
+rather than word segments, so a richer production list typically uses
+segmenter-aware frequencies. The matcher's `String.prototype.slice`
+operates on UTF-16 code units, which means multi-code-unit CJK characters
+are matched character-by-character as their canonical surface form.
+
+## Additional Implementation Notes
+
+The implementation follows the canonical zxcvbn algorithm from Wheeler 2016 with
+the suaveplan-style additions described in the package proposal: structured error
+codes via the `defineCodes` registry, Zod boundaries at every public entry
+point, OTel histograms and counters keyed to low-cardinality attributes, and
+a strict input-length guard at 200 characters. Consumers integrate with their
+existing observability stack by installing a meter provider before importing
+the package, and with their i18n stack via the `MessageResolver` callback type
+declared in `@suaveplan/types`. The bundled data tables are intentionally
+small to keep the package bundle compact; production deployments should swap
+in fuller frequency-ranked tables via `loadDictionaries`. The default English
+dictionary set is a frozen `DictionarySet` that the matcher never mutates;
+caller-supplied dictionaries override defaults by name.