@redocly/recheck 0.1.0 → 0.2.0

package/dist/types/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/types/rules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7D,MAAM,MAAM,SAAS,GACjB,KAAK,GACL,SAAS,GACT,UAAU,GACV,WAAW,GACX,MAAM,GACN,SAAS,GACT,KAAK,GACL,MAAM,GACN,MAAM,EAAE,CAAC;AAEb,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE;QACX,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IACF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE;QACX,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IACF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC;CACzB"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/types/rules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7D,MAAM,MAAM,SAAS,GACjB,KAAK,GACL,SAAS,GACT,UAAU,GACV,WAAW,GACX,MAAM,GACN,SAAS,GACT,KAAK,GACL,MAAM,GACN,MAAM,EAAE,CAAC;AAEb,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,YAAY,CAAC;IASvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE;QACX,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IACF,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,YAAY,CAAC;IAEvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE;QACX,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IACF,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC;CACzB"}

package/examples/appendices/google.appendix.yaml

@@ -0,0 +1,91 @@
+# ==============================================================================
+# Appendix — candidates NOT shipped by recheck/google (hand-maintained)
+# ==============================================================================
+# This file is appended verbatim to the generated example above by
+# `pnpm examples:generate` (see scripts/generate-examples.mjs). Editing it
+# makes examples/google.yaml stale until you regenerate — the drift test's
+# failure message says so, so this doesn't read as a generator bug.
+#
+# Full detail, every candidate, and why: packages/recheck/presets/google/PROVENANCE.md
+#
+# ------------------------------------------------------------------------------
+# NOISY — real, guide-confirmed content, judged too broad to enforce
+# mechanically. Shown here as the rule it WOULD be if shipped, commented out,
+# so you can see the shape being avoided rather than just a name.
+# ------------------------------------------------------------------------------
+
+# NOISY: a heading starting with an "-ing" word would also flag ordinary
+# tech-noun headings used as topics, not verb-form imperatives (Networking,
+# Logging, Caching, Monitoring, Testing) — Google names only two exceptions
+# (Billing, Pricing), itself evidence this needs more context than a
+# heading's first word.
+# google/no-gerund-headings:
+#   severity: warn
+#   scope: heading
+#   message: 'Avoid starting a heading with a gerund (Google).'
+#   assertions:
+#     pattern:
+#       ignoreCase: true
+#       tokens: ['^\w*ing\b']
+
+# NOISY: table cells often legitimately contain short labels, proper nouns,
+# or numeric/code values that don't fit sentence-case cleanly.
+# google/table-sentence-case:
+#   severity: warn
+#   scope: table.cell
+#   message: 'Use sentence case for table cells (Google).'
+#   assertions:
+#     capitalization:
+#       match: $sentence
+
+# NOISY: slashes appear constantly in dates, paths, fractions, and URLs — a
+# blind "avoid slashes" pattern would flag nearly all of them.
+# google/no-slashes-general:
+#   severity: warn
+#   message: 'Avoid using slashes, except in code (Google).'
+#   assertions:
+#     pattern:
+#       tokens: ['(?<!\/)\/(?!\/)']
+
+# NOISY: confirmed guide content ("don't put code in quotes or angle
+# brackets"), but the draft that fed this preset already flagged both as
+# NOISY and they were never re-litigated — no safe anchor was found that
+# doesn't also match ordinary quoted/angle-bracketed prose unrelated to code.
+# google/no-quotes-around-code:
+#   severity: warn
+#   message: "Don't wrap code terms in quotation marks (Google)."
+#   assertions:
+#     pattern:
+#       tokens: ['"`[^`]+`"']
+# google/no-angle-brackets-around-code:
+#   severity: warn
+#   message: "Don't wrap code terms in angle brackets (Google)."
+#   assertions:
+#     pattern:
+#       tokens: ['<`[^`]+`>']
+
+# ------------------------------------------------------------------------------
+# NEEDS HUMAN REVIEW — real guide content with no safe mechanical detection
+# (NOT-ENFORCEABLE). Recheck cannot check these; review them yourself:
+# ------------------------------------------------------------------------------
+#   [ ] "Optional:" prefix on genuinely optional sections (requires knowing
+#       whether a section is actually optional)
+#   [ ] Text before a colon must be a complete sentence
+#   [ ] Oxford comma (missing-comma detection needs real clause parsing)
+#   [ ] Acronyms used as verbs ("ping the server") — needs POS tagging
+#   [ ] Spell out an abbreviation on first mention (needs unbounded
+#       first-mention tracking across the document)
+#   [ ] Avoid linking the same destination from different link text (the
+#       guide's own exceptions — different section, long page, multiple
+#       entry points — need judgment a token rule can't apply)
+#   [ ] External link icon (a rendered visual/CSS concern, not markdown text)
+#   [ ] Drop "..." when quoting a UI element name (risks over- and
+#       under-firing with a regex)
+#   [ ] Directional language (above/below/right-hand side) as a spatial UI
+#       reference vs. its equally common non-directional use
+#   [ ] "A link isn't a button" — requires knowing what a referenced UI
+#       element actually is
+#   [ ] Generic he/him/his/she/her — requires knowing whether a pronoun
+#       names a specific person or is used generically
+#   [ ] Active voice, metaphor avoidance, and the "what belongs in code
+#       font" table — all require holistic judgment about content/structure

package/examples/appendices/inclusive-language.appendix.yaml

@@ -0,0 +1,61 @@
+# ==============================================================================
+# Appendix — candidates NOT shipped by recheck/inclusive-language (hand-maintained)
+# ==============================================================================
+# This file is appended verbatim to the generated example above by
+# `pnpm examples:generate` (see scripts/generate-examples.mjs). Editing it
+# makes examples/inclusive-language.yaml stale until you regenerate — the
+# drift test's failure message says so, so this doesn't read as a generator bug.
+#
+# Full detail, every candidate, and why:
+# packages/recheck/presets/inclusive-language/PROVENANCE.md
+#
+# This preset ships only terms CONFIRMED independently by both
+# recheck/google and recheck/microsoft (the intersection). Most exclusions
+# here are single-guide coverage, not false-positive risk — listed in the
+# "needs a second source" checklist below rather than as commented rule
+# blocks, since most were never actually rule-shaped candidates.
+#
+# ------------------------------------------------------------------------------
+# NOISY — real content on BOTH guides' broader word lists, still excluded
+# from an inclusive-language framing because of an unrelated-sense collision.
+# ------------------------------------------------------------------------------
+
+# NOISY: "hang"/"hung" and "healthy" (of a system) are general word-choice
+# content on both sides, not sourced from either guide's bias-free/
+# accessibility pages — and both collide constantly with unrelated correct
+# senses ("hung the picture", "hung jury", "a healthy amount of caution").
+# inclusive-language/hang-healthy:
+#   severity: warn
+#   message: 'Avoid "%s" as a system-state metaphor; consider a precise term.'
+#   assertions:
+#     pattern:
+#       ignoreCase: true
+#       tokens: ['\bhang(s|ing)?\b', '\bhealthy\b']
+
+# NOISY: "disable"/"disabled" (of a broken system) has a narrow ableist-
+# metaphor sense on both guides, but the bare word is core, ubiquitous,
+# entirely correct API-documentation vocabulary ("disable this feature",
+# "the API is disabled") — a bare-word rule would misfire on nearly every
+# document describing a feature flag.
+# inclusive-language/disable-disabled:
+#   severity: warn
+#   message: 'Avoid "%s" as a system-state metaphor; consider "turn off"/"deactivate".'
+#   assertions:
+#     pattern:
+#       ignoreCase: true
+#       tokens: ['\bdisabled?\b']
+
+# ------------------------------------------------------------------------------
+# NEEDS A SECOND SOURCE — real content on exactly ONE guide's side. Shipping
+# these here would make this preset silently guide-specific, defeating the
+# point of an intersection. Full term lists are in PROVENANCE.md; a sample:
+# ------------------------------------------------------------------------------
+#   [ ] Google-only: blackhat/whitehat, black-box/white-box testing, white
+#       label, grandfathered, ninja, guru, man hours, male/female adapter,
+#       man-in-the-middle, the disabled, a quadriplegic, wheelchair-bound
+#   [ ] Microsoft-only: chairman/chairwoman, mankind, manpower, salesman,
+#       screened subnet, dumb, mute, non-verbal, an epileptic, Asperger's,
+#       lame (already excluded on Microsoft's own preset for the same reason)
+#   [ ] Either term needing a live re-check against the OTHER guide before
+#       it could ever be added here — this is the only path to growing this
+#       preset beyond its current 11 rules

package/examples/appendices/microsoft.appendix.yaml

@@ -0,0 +1,99 @@
+# ==============================================================================
+# Appendix — candidates NOT shipped by recheck/microsoft (hand-maintained)
+# ==============================================================================
+# This file is appended verbatim to the generated example above by
+# `pnpm examples:generate` (see scripts/generate-examples.mjs). Editing it
+# makes examples/microsoft.yaml stale until you regenerate — the drift
+# test's failure message says so, so this doesn't read as a generator bug.
+#
+# Full detail, every candidate, and why: packages/recheck/presets/microsoft/PROVENANCE.md
+#
+# ------------------------------------------------------------------------------
+# TOO-RISKY / NOISY — real, guide-confirmed content, judged too broad or too
+# audience-conditional to enforce mechanically. Shown here as the rule it
+# WOULD be if shipped, commented out, so you can see the shape being avoided.
+# ------------------------------------------------------------------------------
+
+# TOO-RISKY: "deprecated" is confirmed guide content ("avoid in content for a
+# technical audience"), but it's itself load-bearing OpenAPI vocabulary (the
+# `deprecated: true` field) — shipping this would misfire on Redocly's own
+# API-documentation domain.
+# microsoft/deprecated-obsolete:
+#   severity: warn
+#   message: 'Use "%s" instead of "%s" (Microsoft).'
+#   assertions:
+#     swap:
+#       ignoreCase: true
+#       wordBoundary: true
+#       pairs: { deprecated: obsolete }
+
+# TOO-RISKY: Microsoft's own page carves out exactly Redocly's audience —
+# "it's OK to use header as a short form of file header, as in HTML header"
+# — the standard, correct term for an HTTP/API header throughout API docs.
+# microsoft/header-heading:
+#   severity: warn
+#   message: 'Use "%s" instead of "%s" (Microsoft) — except in developer content.'
+#   assertions:
+#     swap:
+#       ignoreCase: true
+#       wordBoundary: true
+#       pairs: { header: heading }
+
+# TOO-RISKY: "context menu" is developer-audience-conditional per Microsoft's
+# own page ("use context menu only in content for developers") — Redocly's
+# docs ARE developer content, so this would misfire if shipped unconditionally.
+# microsoft/context-menu:
+#   severity: warn
+#   message: 'Use "%s" instead of "%s" (Microsoft) — except in developer content.'
+#   assertions:
+#     swap:
+#       ignoreCase: true
+#       wordBoundary: true
+#       pairs: { context menu: shortcut menu }
+
+# TOO-RISKY: "that" referring to people is one of the most common words in
+# English; only a small fraction of occurrences refer to people at all, so a
+# literal swap toward "who" would be extraordinarily noisy.
+# microsoft/that-who:
+#   severity: warn
+#   message: 'Consider "%s" instead of "%s" when referring to a person (Microsoft).'
+#   assertions:
+#     pattern:
+#       tokens: ['\bthat\b']
+
+# TOO-RISKY: "star" is an ordinary English word (star rating, star
+# performer) with a narrow, Microsoft-documented exception (OK for a
+# phone-keypad key) a blanket swap would miss in both directions.
+# microsoft/star-asterisk:
+#   severity: warn
+#   message: 'Use "%s" instead of "%s" (Microsoft), except for the phone-keypad key.'
+#   assertions:
+#     swap:
+#       ignoreCase: true
+#       wordBoundary: true
+#       pairs: { star: asterisk }
+
+# ------------------------------------------------------------------------------
+# NEEDS HUMAN REVIEW — real guide content with no safe mechanical detection
+# (NOT-ENFORCEABLE). Recheck cannot check these; review them yourself:
+# ------------------------------------------------------------------------------
+#   [ ] Active voice, subjunctive mood, verb-first sentences, modifier
+#       stacks, that/who omission — all require POS tagging or grammatical-
+#       role judgment beyond regex/AST primitives
+#   [ ] Table cells in sentence case — reference tables are dense with
+#       identifiers and proper nouns that don't fit cleanly
+#   [ ] "Name" as a column header — genuinely correct in many API reference
+#       tables; Microsoft's own objection needs context this preset doesn't have
+#   [ ] Second-level headings need at least two siblings; no two headings in
+#       a row; list-item parallelism
+#   [ ] En dash for a minus sign; "from"/"through" ranges; closing-quote
+#       placement; mid-sentence colon rules
+#   [ ] Spell out single-digit numbers; no sentence-initial numerals; no
+#       K/M/B abbreviations; spell out months
+#   [ ] Bare-URL/link-formatting rules (available generically via
+#       `recheck/markdown`'s `no-bare-urls` if you want them, just not
+#       attributed to Microsoft specifically here)
+#   [ ] House-rule structural conventions (link fragments, fenced-code
+#       language, single H1, consistent bullet/fence/emphasis style) — real
+#       and worth having, but the guide itself never states them, so they
+#       don't ship under a Microsoft attribution

package/examples/appendices/plain-language.appendix.yaml

@@ -0,0 +1,88 @@
+# ==============================================================================
+# Appendix — candidates NOT shipped by recheck/plain-language (hand-maintained)
+# ==============================================================================
+# This file is appended verbatim to the generated example above by
+# `pnpm examples:generate` (see scripts/generate-examples.mjs). Editing it
+# makes examples/plain-language.yaml stale until you regenerate — the drift
+# test's failure message says so, so this doesn't read as a generator bug.
+#
+# Full detail, every candidate, and why:
+# packages/recheck/presets/plain-language/PROVENANCE.md
+#
+# ------------------------------------------------------------------------------
+# NOISY — live, verbatim guide content, judged too broad or too domain-risky
+# to enforce mechanically. Shown here as the rule it WOULD be if shipped,
+# commented out, so you can see the shape being avoided.
+# ------------------------------------------------------------------------------
+
+# NOISY: live on the guide's own table, but this 1:1 substitution misreads
+# ordinary, correct accountability language ("the team is responsible for
+# the migration") as wordiness — no textual signal separates that from padding.
+# plain-language/be-responsible-for:
+#   severity: warn
+#   message: 'Consider "%s" instead of "%s" (plain language).'
+#   assertions:
+#     swap:
+#       ignoreCase: true
+#       wordBoundary: true
+#       pairs: { be responsible for: must }
+
+# NOISY, HIGH-RISK FOR THIS DOMAIN: "implement" is live guide content, but in
+# software/API documentation "implement an interface", "implement this
+# endpoint", "implement the spec" is ordinary, correct technical vocabulary,
+# not wordiness. Flagging it would misfire across nearly every technical
+# document Recheck targets.
+# plain-language/implement:
+#   severity: warn
+#   message: 'Consider "%s" instead of "%s" (plain language).'
+#   assertions:
+#     swap:
+#       ignoreCase: true
+#       wordBoundary: true
+#       pairs: { implement: carry out }
+
+# NOISY: this row is itself a garbled pairing on the live page, and
+# separately "command" has a strong, unrelated, extremely common technical
+# sense (CLI command, terminal command) — core developer-docs vocabulary.
+# plain-language/this-activity-command:
+#   severity: warn
+#   message: 'Consider "%s" instead of "%s" (plain language).'
+#   assertions:
+#     swap:
+#       ignoreCase: true
+#       wordBoundary: true
+#       pairs: { this activity, command: us, we }
+
+# NOT SHIPPED, ANY DIRECTION, EVER: "shall" is live guide content ("use
+# 'must' not 'shall'"), but SHALL is a defined RFC 2119 normative keyword
+# (alongside MUST/SHOULD/MAY/MUST NOT) used throughout specifications and
+# API/interface documentation — exactly Recheck's target content. This is
+# the single highest-risk exclusion in this preset: a rule flagging it would
+# be actively wrong for that whole document class, not an edge case to
+# carve out.
+# plain-language/shall-must:
+#   severity: warn
+#   message: 'Consider "%s" instead of "%s" (plain language) — never for RFC 2119 usage.'
+#   assertions:
+#     swap:
+#       ignoreCase: true
+#       wordBoundary: true
+#       pairs: { shall: must }
+
+# ------------------------------------------------------------------------------
+# NEEDS HUMAN REVIEW — real guide content with no safe mechanical detection
+# (NOT-ENFORCEABLE). Recheck cannot check these; review them yourself:
+# ------------------------------------------------------------------------------
+#   [ ] Nominalizations ("hidden verbs") — the guide's own suffix pattern
+#       (-ment/-tion/-sion/-ance + a link verb) false-positives constantly on
+#       ordinary correct nouns ("chance", "information", "assurance")
+#   [ ] Sentence-length — no word count is stated anywhere on the live site,
+#       only "write short sentences"
+#   [ ] Grade-level/readability score — no number is stated anywhere on the
+#       live site (see PROVENANCE.md "THE NUMBER"); `metric` stays a
+#       documented opt-in, not something this preset can source from the guide
+#   [ ] Abbreviation count per document ("no more than three, preferably
+#       two") — counts DISTINCT abbreviation TYPES, which neither `occurrence`
+#       nor `length` can express; an engine gap, not a judgment call
+#   [ ] Paraphrase-testing sample size / testing iteration count — user-
+#       testing methodology, not document content a linter can ever evaluate