Repository navigation
docs: narrow the configuration normalization guarantee to JSON-shaped input - #53
Conversation
|
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues are reported for this documentation-only clarification of the JSON-shaped configuration contract.
No open issues 🎉
What changed in this PR
Clarifies the documented configuration contract for PluginConfigurationManager, distinguishing editor-supplied JSON from arbitrary JavaScript objects discussed in #49. No runtime behavior changes.
Changes:
- Narrows the normalization and no-throw guarantee to JSON-shaped input from tsconfig and
configurePlugin, while retaining the logger-failure guarantee.
| File | Description |
|---|---|
docs/architecture.md |
Limits the configuration guarantee to JSON-shaped input. |
Review effort: Balanced
There was a problem hiding this comment.
ℹ️ No blocking issues — one coordination note before merging.
Approach: sound — for supported tsserver hosts the input is JSON-shaped, so the narrowed sentence is more accurate than the old one; the only open question is which PR owns this line.
Reviewed changes
- Narrowed the normalization guarantee in
docs/architecture.mdfrom any input shape to JSON-shaped tsserver input, retaining the logger-failure carve-out. - Confirmed no source, test, or changeset changes.
ℹ️ Same doc sentence is rewritten by open PR #49
PR #49 replaces this exact sentence as part of its normalization fix, so the two PRs edit the same line. If both land, the later one conflicts at that hunk; if #49's code lands without reconciling the docs, this PR's sentence would understate the manager's behavior. Decide which PR owns the sentence before merging.
Technical details
# Overlapping documentation hunk with PR #49
## Affected sites
- `docs/architecture.md:153` — PR #53 replaces this sentence; PR #49's diff replaces the same line with wording about reset-to-defaults for arbitrary JS input and adds a following bullet.
- PR #49 is open, based on `c2f1511`, and also changes `src/configuration/plugin-configuration.ts` and `test/unit/plugin-configuration.test.ts`.
## Required outcome
- One PR should own this sentence. The other should drop its hunk or be reworded as a complementary statement.
- If #53 lands first, #49 needs a rebase that keeps the JSON-shaped tsserver sentence and adds the direct-API behavior separately.
## Open questions for the human
- Is #49 expected to land? If so, folding this wording into #49 or closing #53 avoids two overlapping doc PRs.big-pickle (free) | 𝕏
|
Just a note: #43 also rewrites this same "Source" bullet, so the two will conflict on that line. If it works for you, merging #53 first might be simplest since it's a one-line change. I'll then rebase #43 and keep the JSON-shaped wording in its rewritten text. Happy to go the other way too if you'd prefer. |

Summary
docs/architecture.mdsaidPluginConfigurationManager"normalizes any input shape and never throws". That only holds for the JSON that tsconfig andconfigurePluginsend, not for arbitrary objects from direct API callers (see #49). This narrows the sentence to match. No behavior change.Testing
Docs only.
oxfmt --check docs/architecture.mdpasses.