docs(comment-policy): add loaded-term taxonomy (SD-2923)#3103
Merged
Conversation
…e script (SD-2923) Define five loaded-term categories so words like "legacy" and "deprecated" stop carrying three different meanings inside the same package, and add a report-only Node script that surfaces the existing damage: .ts/.d.ts sibling divergences (tracked under SD-2922), orphan TODO/FIXME/HACK/XXX without an issue id, undated @deprecated, and AIDEV-NOTE candidate locations. The script always exits 0; flipping it to blocking is gated on the taxonomy being adopted across the codebase.
…ript (SD-2923) Brings the new content in line with the project writing style (no em-dashes).
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ef5320ebbf
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
…itely (SD-2923) The deprecation check used OR across all three keywords, which would have suppressed a comment that only had `replaceWith` set. The taxonomy added in the same patch requires `replaceWith` AND either `removeIn` or `compat-indefinitely`. Switch to AND so the script enforces what the policy says. Current baseline counts are unchanged (no comment in the repo has only one keyword today), but the script will now correctly flag partial annotations as they appear.
… 0 (SD-2923) The script promises "always exits 0" but `process.stdout.write` throws on a closed pipe (e.g. `node scripts/comment-hygiene-report.mjs | head`), which Node turns into a non-zero exit and a stack trace. Add an EPIPE handler on stdout so early pipe closure exits cleanly.
The script is transitional audit tooling, not product or CI behavior. It's heuristic by design and would need ownership, tests, and clear CI intent the moment it lands in scripts/. Phase 1 only needs the policy change; the script comes back in the enforcement PR with the deprecation rule properly enforcing replaceWith AND a removal decision, and with the export extractor rewritten on top of a TypeScript AST (tracked on SD-2922).
caio-pizzol
changed the title
This was referenced May 4, 2026
caio-pizzol
added a commit
that referenced
this pull request
May 4, 2026
…agmentIndex (SD-2923) (#3112) The four `fragmentIndex` fields on ResolvedFragmentItem / Table / Image / Drawing previously used the word "legacy" with three different shades across the layout-engine - older path, current fallback, and removed code - all conflated. In this file, "legacy" actually means the *current load-bearing fallback* the painter uses to read inner content from Fragment until ResolvedFragmentItem carries full content directly. Apply the compat-fallback term from comment-policy.md uniformly: each fragmentIndex field now carries an AIDEV-NOTE: compat-fallback anchor naming what triggers the fallback (ResolvedFragmentItem missing content) and the retirement condition (paint items become self-describing). Drop "legacy content lookup" trailer from ResolvedFragmentItem.blockId and rewrite the type-level docstring to reference the per-field anchor instead of "legacy fragment renderers". This is the first in-the-wild use of the loaded-term taxonomy added in #3103. No behavior change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a five-term taxonomy to comment-policy.md (legacy-public, compat-fallback, removed-dead, deprecated, temporary) so loaded words like "legacy" and "deprecated" stop carrying three different meanings inside the same package. Each term comes with a required annotation - replacement, removal version, fallback trigger, or issue id - so future readers can tell what the comment actually constrains.
The accompanying audit and the report-only hygiene script that surfaced the existing damage (14 .ts/.d.ts divergences, 52 orphan TODO/FIXME, ~68 undated @deprecated) are kept local until enforcement lands. Committing transitional audit tooling alongside the policy change creates a half-owned script with known heuristic gaps; it returns in the enforcement PR rewritten on a TypeScript AST extractor (tracked on SD-2922) and with proper CI behavior then.