first commit

docs/security-stack/security/password-strength/src/feedback/feedback.md

@@ -0,0 +1,69 @@
+# `feedback` — keyed-string feedback generator
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Renders a structured `{ warning, suggestions[] }` value from a
+`StrengthResult`'s longest-cover pattern. The warning string is selected
+by message key from a built-in English map; consumers integrate with
+their existing i18n stack by passing a `resolver` callback that receives
+the key and an optional params bag.
+
+## Features
+
+- Built-in English message map (no runtime i18n dependency)
+- Resolver bridge accepts any function `(key, params?) => string`
+- Resolver throws bubble up as `PWSTRENGTH.RESOLVER_FAILED` with `cause`
+- Warning key is selected from the longest-cover pattern in the sequence
+- Suggestion keys are emitted for `score < 3` (omitted at 3 / 4)
+- `personalInfo` key surfaces when the longest match is a `user_inputs` hit
+
+## Usage: Basic Example
+
+```ts
+import { feedback } from "@suaveplan/password-strength";
+
+const result = {
+ password: "password",
+ guesses: 1,
+ guessesLog10: 0,
+ score: 0,
+ sequence: [{ pattern: "dictionary", i: 0, j: 7, token: "password", matchedWord: "password", rank: 1, dictionaryName: "passwords", reversed: false, l33t: false }],
+} as const;
+
+const fb = feedback(result);
+console.log(fb.warning);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { feedback } from "@suaveplan/password-strength";
+
+const fb = feedback(result, {
+ resolver: (key) => myI18nLib.translate(key, { locale: "fr" }),
+});
+console.log(fb.warning);
+```
+
+## API Reference
+
+- `feedback(result: FeedbackResult, opts?: FeedbackOptions): Feedback`
+  - Throws `PasswordStrengthError(PWSTRENGTH.INVALID_OPTIONS)` on Zod failure.
+  - Throws `PasswordStrengthError(PWSTRENGTH.RESOLVER_FAILED)` when the
+    caller-supplied resolver throws.
+- `Feedback`: `{ warning: string; suggestions: string[] }`.
+- `FeedbackOptions`: `{ resolver?: MessageResolver; locale?: string }`.
+- `FeedbackResult` — subset of `StrengthResult` consumed by `feedback`.
+
+## Implementation Notes
+
+The warning key is selected by walking the sequence to find the match with
+the longest span; if the sequence is empty the empty warning key is used.
+For dictionary matches, the key suffix reflects the bucket the rank falls
+into (`top10`, `top100`, `common`, `word`). The English map covers every
+emitted key so unresolved keys never produce empty strings; resolver
+implementations are free to return undefined for unknown keys and the
+package will substitute the English string.