Skip to content

docs: narrow the configuration normalization guarantee to JSON-shaped input - #53

Merged
quantizor merged 1 commit into
mainfrom
docs/narrow-configuration-normalization-claim
Nov 20, 2026
Merged

quantizor merged 1 commit into
mainfrom
docs/narrow-configuration-normalization-claim

Conversation

@usercao

@usercao usercao commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator

Summary

docs/architecture.md said PluginConfigurationManager "normalizes any input shape and never throws". That only holds for the JSON that tsconfig and configurePlugin send, 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.md passes.

Copilot AI balanced review requested due to automatic review settings November 19, 2026 06:30
@changeset-bot

changeset-bot Bot commented Nov 19, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 0ff0228

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 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

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ 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.md from 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.

Pullfrog  | Fix it ➔ | View workflow run | Using big-pickle (free) | 𝕏

@usercao

usercao commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator Author

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.

@quantizor
quantizor merged commit 7db0262 into main Nov 20, 2026
13 checks passed
@quantizor
quantizor deleted the docs/narrow-configuration-normalization-claim branch November 20, 2026 05:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants