fix: drift AST scanners miscount coverage (#113)

[juemerson-at-purestorage]

fix: drift AST scanners miscount coverage (#113)

Closes #113.

The drift report's two AST scanners each had a defect that moved coverage numbers in the wrong
direction. Both are in tools/lib/PfbApiDriftTools.ps1; no cmdlet source changes.

1. Variable-keyed central injection was invisible

Get-PfbCentralInjectionSites only recognised a literal index — $QueryParams['names'] = .... The
real context_names injection is written as $QueryParams[$script:PfbContextNamesKey] = ..., with
the key held in a $script: constant in a different file from its use site, so the scanner saw
nothing and the report claimed a 269-endpoint context_names gap for a feature that shipped in
Phase 1.

New helper Get-PfbPrivateScriptConstant maps $script:Name = '<literal>' across Private/, built
once for the whole directory because the definition and the use site cannot be resolved per-file.
Deliberately narrow, and the header says why:

• keys are VariablePath.UserPath, which retains the script: prefix, so definition and use
  produce identical strings;
• only $script:-scoped targets, and only single string literals;
• a name assigned two different literals resolves to nothing — order-independence, the same defect
  class as Report generators emit in filesystem order: a 10k-line phantom diff blocks the capability-map auto-PR #85;
• it scans definitions only, so a defined-but-unused constant yields no injection site.

Injection records now carry KeySource (literal or constant) so the two paths stay
distinguishable in tests and in triage.

That last point is load-bearing and is asserted directly: context_names is detected in the real
tree via its constant, and allow_errors — defined as a constant but not centrally injected — is
still correctly absent. Getting either direction wrong is a regression, so both are pinned.

2. Private helpers were credited as public surface

Get-PfbModuleCalledEndpoints walked Public/ and Private/ into one list with no provenance, so
a private helper that issues a request (Resolve-PfbAdminLocality) was attributed as a cmdlet
covering that endpoint. The file walk now carries IsPublic, and
Get-PfbParameterCoverageGaps filters the cmdlet attribution list on it.

Two scoping decisions, both commented in place:

• the filter is -ne $false, not -eq $true, so hand-built records predating the field are not
  silently reclassified as private;
• it applies to the cmdlet list only, not to the endpoint grouping —
  Get-PfbEndpointCoverageGaps still counts both, because an endpoint the module calls from a
  private helper is genuinely covered. Only the "which cmdlet" answer was wrong.

Effect on the committed report

	before	after
systemicGaps	241	240 (context_names gone; allow_errors intact at 118)
parameterGaps	439	358 (81 endpoints whose only gap was context_names)
confidence = partial	61	58
GET /admins gap cmdlets	Get-PfbAdmin, Resolve-PfbAdminLocality	Get-PfbAdmin

GET /admins stays out of uncoveredEndpoints, which is the point of the endpoint/cmdlet split
above.

The context_names entry in docs/drift-annotations.json is deleted — it existed only to explain
away this defect, and an annotation that survives its cause becomes a permanent excuse. Four tests
hardcoded context_names as a live systemic gap; each now asserts the corrected state rather than
merely dropping the name, and tools/README.md and the generator header use allow_errors as the
running "architectural gap, zero cmdletCount" example, with context_names retained as a worked
example of the failure mode itself.

Tests/coverage-baseline.psd1 re-pins PfbApiDriftTools.Tests.ps1 8 → 12 for the new PS7-gated
tests (per-file ExpectedSkips, from PR #135).

The Task 6 aggregation-ratio invariant moved 55.72% → 39.97%, inside its existing >0.30 / <0.60
bounds. That is a re-verify, not a re-tune: the bounds were not touched.

Verification

• Dual-edition scoped Pester over the 16 drift / dead-key / derived-artifact / coverage-gate test
  files: pwsh 7 — 492 passed, 0 failed; Windows PowerShell 5.1 — 342 passed, 0 failed, 150
  skipped. Containers healthy under both.
• scripts/Assert-PfbDerivedArtifacts.ps1: all 11 checked artifacts up to date. Only the
  drift-report pair moved.
• Live-FlashBlade verification does not apply to this PR. The diff is tools/, Tests/,
  docs/ and Reports/ only — nothing in Public/, Private/,
  PureStorageFlashBladePowerShell.psd1 or .psm1 — so it cannot change what goes on the wire.

Related

Filed while measuring the same accounting question from the other scanner
(tools/lib/PfbCmdletParamTools.ps1), and not fixed here: #141 (the wire-name resolver misses
three assignment shapes, leaving 126 parameters skipped rather than measured) and #142 (two
genuine dead keys those skips were hiding). Same question, different file, no shared code — which is
why they are separate issues rather than part of this one.