📦 deps(thirdparty): update snapshots

2026-07-18 00:02:59 +00:00
parent 82f7c6e56a
commit 47ce7f78dc
1446 changed files with 141041 additions and 6442 deletions
@@ -0,0 +1,46 @@
+# Docs Guard — Code Sample Rules
+
+A code sample is the most-trusted part of any documentation: readers paste it. That trust makes a broken sample worse than no sample.
+
+## Contents
+
+- Shippable sample checklist
+- Realistic data
+- Secrets and credentials
+- Error-path examples
+- Language and environment tags
+- Sample drift
+
+## Shippable sample checklist
+
+Every sample must pass all of these:
+
+1. **Imports resolve** — every import/require/use names a real module at the documented version.
+2. **APIs are real** — every call verified per [verification.md](verification.md): name, argument order, defaults, return shape.
+3. **Self-contained or explicit** — runs on a clean machine, or states its prerequisites immediately above the block ("requires the client from the previous step").
+4. **No local residue** — no `/Users/yourname/`, no `C:\Dev\`, no machine-specific ports or hostnames; use placeholder conventions the project already uses.
+5. **Syntactically valid** — parse it mentally line by line; when the runtime allows, actually run or lint it.
+6. **Output shown is output produced** — if the sample shows a result, that result must be what the code yields, not an idealized version.
+
+## Realistic data
+
+Use data that exposes the API's shape honestly: realistic field names, plausible values, at least one non-ASCII string where text handling matters. `foo`/`bar` hides bugs that `"Café Münster"` reveals — especially for the i18n-aware audience.
+
+## Secrets and credentials
+
+- Placeholders that cannot be mistaken for real values: `YOUR_API_KEY`, `example.com`, RFC 5737 IPs (`192.0.2.x`), `sk_test_…` style markers only when the provider defines them.
+- Never paste real-looking tokens — even invented ones train readers to paste theirs, and secret scanners will flag the repo.
+- Auth setup goes in one place and is linked, not repeated with variations in every sample.
+
+## Error-path examples
+
+For any API that can fail in normal operation, show one failure: what the error object/exception/status looks like and the minimal correct response to it — using the error types the code actually raises (verify the raise site). Happy-path-only documentation produces catch-all error swallowing downstream, the exact failure clean-code-guard exists to stop.
+
+## Language and environment tags
+
+- Fenced blocks carry the correct language tag — broken highlighting is a trust signal readers notice.
+- State the environment when it changes behavior: shell prompts (`$` vs `#`), OS-specific paths, version-gated syntax.
+
+## Sample drift
+
+Samples drift faster than prose because nobody re-runs them. On any code change touching a documented API, grep the docs for the old symbol (SKILL.md Rule 6) — samples are where the stale hits hide. Projects with executable-docs tooling (doctest and kin): prefer it; this skill's manual verification is the floor, not the ceiling.
@@ -0,0 +1,60 @@
+# Docs Guard — Docstring, PHPDoc, and JSDoc Rules
+
+In-code documentation has one extra constraint the other surfaces lack: it sits next to the truth. There is no excuse for a docstring that disagrees with the signature three lines below it.
+
+## Contents
+
+- When a docstring is justified
+- The paraphrase test
+- What a good docstring contains
+- Tag accuracy (PHPDoc/JSDoc)
+- Generated-docs hygiene
+
+## When a docstring is justified
+
+- Public API surface: always — it feeds IDEs, generated references, and agents.
+- Internal helpers: only when the contract is not expressible in the signature (units, invariants, side effects, "why"). An internal one-liner with an intention-revealing name usually needs nothing — and clean-code-guard's comment rules apply.
+
+## The paraphrase test
+
+Delete any docstring whose entire information content is recoverable from the signature:
+
+```php
+// Fails the test — restates the obvious, documents nothing.
+/**
+ * Gets the user by ID.
+ *
+ * @param int $user_id The user ID.
+ * @return WP_User The user.
+ */
+function get_user_by_id( $user_id ) { /* … */ }
+```
+
+AI generators emit these by the thousand; they are comment pollution wearing a suit. Either say something the signature cannot, or say nothing.
+
+## What a good docstring contains
+
+The contract the types cannot express:
+
+- Units and ranges (`$timeout` in seconds? milliseconds? what happens at 0?)
+- Error behavior: which exceptions/returns on failure, and when (verify the raise/return sites)
+- Side effects: writes, cache invalidation, events fired, global state touched
+- Null/empty semantics: what `null` means here, what an empty array does
+- Ordering, idempotency, concurrency guarantees when callers depend on them
+- The "why" for surprising design ("returns 1.0 on API failure so prices never disappear")
+
+## Tag accuracy (PHPDoc/JSDoc)
+
+- `@param` names and order match the signature exactly — drift here actively lies to IDEs.
+- `@param` and `@return` types match the real types, including nullability (`int|WP_Error`, `?string`) and generics where the project uses them.
+- `@throws` lists what the body actually throws — verify each raise site; remove what no longer throws.
+- `@since` matches the changelog/tag where the project versions its API.
+- `@deprecated` always names the replacement.
+
+## Generated-docs hygiene
+
+When docstrings feed a generated reference (phpDocumentor, JSDoc, Sphinx, TypeDoc):
+
+- A wrong docstring becomes a published wrong reference page — Rule 1 severity applies as if it were the README.
+- Check that examples inside docstrings obey [code-samples.md](code-samples.md) — they are the least-reviewed samples in any codebase.
+- Markup must be valid for the generator in use; broken tags silently truncate published pages.
@@ -0,0 +1,45 @@
+# Docs Guard — Review Checklist
+
+Structured walk for review mode. Findings first, file:line evidence always. Priorities: false claims → drift → substance → navigation.
+
+## Contents
+
+- Pass 1: Claim verification
+- Pass 2: Code samples
+- Pass 3: Drift scan
+- Pass 4: Substance
+- Pass 5: Navigation
+- Reporting
+
+## Pass 1: Claim verification (must fix)
+
+Run the full procedure in [verification.md](verification.md):
+
+- Extract every symbol, flag, endpoint, config key, path, version, and behavioral claim.
+- Verify each against its source of truth (definition site, parser, route table, changelog).
+- Every unverified or contradicted claim is a Rule 1/3 finding with the contradicting file:line.
+- Numbers and superlatives without a repo source are Rule 4 findings.
+
+## Pass 2: Code samples (must fix)
+
+For every fenced block, run the [code-samples.md](code-samples.md) checklist: imports, signatures, self-containment, local residue, secrets, shown output. Samples in docstrings count.
+
+## Pass 3: Drift scan (should fix)
+
+- Take the public API surface (or the diff, when reviewing a change) and grep the docs for renamed/removed symbols, old defaults, and dead flags.
+- Check the changelog mentions what the docs claim is new, and versions agree (Rule 5).
+- Cross-surface consistency: README vs reference vs docstrings vs config samples — one claim per fact, surfaces agreeing (Rule 6).
+
+## Pass 4: Substance (should fix)
+
+- Paraphrase docstrings, heading-restating sections, marketing adjectives, intro padding (Rule 7).
+- Paraphrased upstream documentation that should be a link (Rule 8).
+- Happy-path-only tutorials and API examples (Rule 9).
+
+## Pass 5: Navigation (worth noting)
+
+- TOC vs actual headings; internal links and anchors resolve; no TODO stubs or "coming soon" in published docs (Rule 10).
+
+## Reporting
+
+Use the SKILL.md reporting format (Claim / Reality / Fix). Lead with the count: "N claims checked, M false, K unverifiable." End with a verdict — publish / fix first / do not publish — and at most three things the docs do well. A review that verifies 40 claims and finds 2 false is a *good* result; say so.
@@ -0,0 +1,22 @@
+# Docs Guard — Sources
+
+Central bibliography. Operational guidance lives in the other references; read this file only when a source URL is needed.
+
+## Contents
+
+- Research on AI-generated documentation defects
+- Documentation craft references
+
+## Research on AI-generated documentation defects
+
+- Kabir et al., "Is Stack Overflow Obsolete? An Empirical Study of the Characteristics of ChatGPT Answers to Stack Overflow Questions", CHI 2024 — 52% of answers contained incorrect information; evaluators missed AI errors 39% of the time: https://dl.acm.org/doi/10.1145/3613904.3642596
+- CloudAPIBench, "On Mitigating Code LLM Hallucinations with API Documentation" (AWS, 2024) — 38.58% valid invocations for low-frequency APIs: https://arxiv.org/abs/2407.09726
+- De-Hallucinator (2024) — LLMs routinely invent non-existent APIs; project-API grounding fixed 63.2% of hallucination-caused failures: https://arxiv.org/abs/2401.01701
+- Spracklen et al., "We Have a Package for You!" (USENIX Security 2025) — package hallucination averages 19.6% across 16 models: https://www.usenix.org/conference/usenixsecurity25/presentation/spracklen
+
+## Documentation craft references
+
+- Diátaxis — the four documentation modes (tutorial, how-to, reference, explanation): https://diataxis.fr/
+- Write the Docs — style guide collection: https://www.writethedocs.org/guide/writing/style-guides/
+- RFC 5737 — IPv4 address blocks reserved for documentation: https://www.rfc-editor.org/rfc/rfc5737
+- Google developer documentation style guide: https://developers.google.com/style
@@ -0,0 +1,51 @@
+# Docs Guard — Verification Procedure
+
+The mechanical heart of this skill: turn a document into a list of claims, then check each claim against the source of truth.
+
+## Contents
+
+- Step 1: Extract the claims
+- Step 2: Verify each claim type
+- Step 3: Record what you verified
+- When you cannot verify
+
+## Step 1: Extract the claims
+
+Scan the doc and list every:
+
+- Function, method, class, constant, hook, event name
+- CLI command, subcommand, flag, default value
+- HTTP endpoint, method, status code, request/response field
+- Config key, env var, file path, directory layout claim
+- Version number, compatibility statement, dependency requirement
+- Behavioral claim ("retries three times", "case-insensitive", "idempotent")
+
+Inline code spans and code blocks are claim-dense; prose hides claims in verbs ("automatically reconnects" is a claim).
+
+## Step 2: Verify each claim type
+
+| Claim type | Source of truth | How |
+|---|---|---|
+| Symbol exists | The codebase | Grep definition (`function name`, `class Name`, `def name`, export) — not usages, the definition |
+| Signature | The definition site | Read parameters, defaults, return; compare name-by-name with the doc |
+| CLI flag | The argument parser source, or `--help` output if runnable | Read the parser registration; flags in README but not in the parser are hallucinations |
+| Endpoint | Route registration (router file, `register_rest_route`, annotations) | Match path, method, and handler |
+| Config key | The code that reads it (`getenv`, config schema, `get_option`) | A documented key nothing reads is dead documentation |
+| Default value | The definition, not the docs of the definition | Defaults drift silently; read the current line |
+| Version claim | Changelog, git tags, dependency manifests | "Since 2.3" must appear in the 2.3 changelog or tag diff |
+| Behavioral claim | The implementation path | Read the function; trace the claimed behavior (retry loop, case fold, guard clause) |
+| Internal link/anchor | The target file/heading | Resolve the relative path; slugify the heading and compare |
+
+## Step 3: Record what you verified
+
+In write-time mode, keep a short verification trail in your working notes (not in the doc): claim → file:line where confirmed. In review mode, this trail becomes your evidence — every finding cites the definition site that contradicts the doc.
+
+When the runtime allows execution, prefer executable checks: run `--help`, run the sample, run a link checker. When it does not, source-reading is the standard — never skip to "it looks right."
+
+## When you cannot verify
+
+If the source of truth is unavailable (private dependency, external service, missing schema):
+
+1. Say so explicitly rather than guessing.
+2. Downgrade the claim to what you can verify ("the client calls the `/v2/orders` endpoint" → verified in client code, even if the server is unreachable).
+3. Never decorate an unverified claim with confident language. "Should", "appears to", or a direct question to the user beats a fluent hallucination.