feat(scripts): hold v3 method names against a portal's own OpenAPI document

[IgorShevchik]

Closes #463. Closes #464 — see Why both below.

The gap

The discovery page calls rest.documentation.openapi "the source of truth the SDK relies on
instead of a hardcoded allowlist", and nothing compared anything to it. The one gate that
looks at v3 drift said so in its own NOTE: the method layer went out with the allowlist in
2.0.0, and #206 was closed without the snapshot it asked for.

The check

scripts/data/openapi-cloud-2026-09-05.json is a reduction of a real portal's document —
method name, module, operations. A name used in a v3 method position that no snapshot
publishes fails with file:line.

Three properties are load-bearing, each a decision rather than a default:

• A snapshot is a baseline, not a catalogue. Portals differ — two cloud portals measured a
  day apart disagreed on 28 methods; every on-premise method exists in the cloud, 98 cloud
  ones do not exist on the box. So one snapshot publishing a name is enough, and a portal
  method we never document is informational (237 of 245 today). A check that is red by design
  gets switched off.
• It audits prose, never runtime. b24pysdk keeps a 70-name list and silently downgrades
  an unlisted v3 call to v2. Not repeating that.
• It never calls a portal. --refresh is local, and a plain POST rather than an SDK
  import — every other script here is dependency-free node, and importing the package would
  drag the Pull client's protobuf modules into a lint script.

What counts as a method position is the whole difficulty, because this repo writes
result.items and crm.item.list in backticks identically. Four positions, each taken from a
real occurrence: a method: literal, a v3 batch tuple, a parameter-table row whose first cell
is method, and a JSDoc bullet documenting the method option. The last is why
packages/jssdk/src/ joined the walk — five of the defects were JSDoc, not docs.

What it found

The eight sites #463 predicted, at the predicted lines — and a ninth it did not:
5.umd.md offers a newcomer actions.v3.call.make({ method: 'crm.item.list' }) as their
first copy-paste, and v3 publishes no crm.item.* on any portal.

Why both issues

All ten occurrences are fixed here rather than marked, because a check that cannot be switched
on is not a deliverable. That is #464's scope, so it closes too. The substantive one was
5.filtering.md's "same query in v2 and v3" section: it cannot be the same method, so the
v3 half now asks the same shape of question of tasks.task.list, with field names read
from tasks.task.field.list rather than guessed.

Two findings from building it

A shared escape hatch is not an escape hatch. Two fences already carried
// @check-ignore: top-level return in error-handling illustration, written for the typecheck
gate about something else — and my first version let them silence this gate too. The marker's
reason must now name the method it excuses, so an exemption granted for one reason cannot
acquire a second by sitting in the right place.

The anti-example in b24jssdk-rest/SKILL.md was silent by accident, not intent: its
neighbourhood mentions both actions.v2. and actions.v3., so the dialect is ambiguous and
the line is skipped. Defensible as a rule; not something to rely on. Marked.

Tests

Eight new cases in scripts/__tests__/check-v3-method-refs.test.mjs (12 total), one per arm.
Confirmed by mutation, including the fence-tag rule — which at first no test could
distinguish from its own fallback, so a case was added where it is the only signal.

mutation	red
marker no longer has to name the method	1
fence [v2]/[v3] tag ignored	1

Coverage

pnpm run lint:v3-coverage, always exit 0 — the number a docs PR quotes:

publishes 245, documented here 8, never named 237
  humanresources  0 / 33      mail  0 / 24      bizprocdesigner  0 / 16
  tasks           4 / 22      main  2 / 37      rest             1 / 55

The snapshot

33 KB of the 215 KB on the wire. Carries a portal kind, never a domain, a scope or a
credential; the Russian summary fields are dropped. Verified: no host, no token, no URL in
the file. Refresh is documented in .github/contributing/documentation.md.

Checks

• pnpm typecheck, pnpm lint, pnpm lint:md — clean
• docs-lint --strict — 0/0 (the @check-ignore threshold is raised 51 → 57 with the reason
  written where the previous raises are)
• docs:lint:test — 155 pass
• all four block gates, docs:lint-api-index — clean
• pnpm vitest run --project jsSdk:unit — 609 passed

🤖 Generated with Claude Code

https://claude.ai/code/session_01F22e2ft66y7nuBJjzdThBr

---

Generated by Claude Code