PDX-486: feat(mcp) — strict validator unknown-key detection (Thread A, PR 1/3)

[mrdailey99]

Context

A user typed testCases (plural) instead of testCase (singular) in a
provardx-properties.json file. provar_properties_validate accepted it
(the validator only checked required fields and enum values — unknown keys
were silently ignored). The subsequent provar_automation_testrun exited 0
with zero tests executed and falsely reported "tests run successfully." Two
safety nets failed in series.

This PR is VALIDATE-TYPO-A — the first half of the fix. It plugs the
validator gap.

The companion VALIDATE-TYPO-B (Thread B) adds the RUN-001 zero-tests
guard on provar_automation_testrun, and a final small Thread B commit
will wire validateProperties into provar_automation_config_load so
SCHEMA-001 surfaces before the shared sf config is written. See the umbrella
ticket PDX-486 for the full story.

This is Thread A, PR 1 of 3 in the parallel sequencing from
.claude/plans/file-c-users-mrdai-git-provar-manager-re-compressed-thunder.md.
The next two Thread A PRs (PDX-488 PROVARHOME-001 and PDX-494 PARALLEL-001)
will extend the canonical key sets exported here.

Depends on #182 (PDX-485 thread-prep: shared src/mcp/utils/warningCodes.ts).

Why

• The validator was the first safety net that failed. Strict unknown-key
  detection closes it without breaking older clients (warning, not error).
• The exported canonical key sets give sibling Thread A PRs a clean
  extension point — six threads referencing the same enum names converge
  cleanly; six threads inventing their own do not.
• A "Did you mean ..." suggestion (Levenshtein ≤ 2, no new dependency)
  turns a silent failure into an obvious one for both humans and agents.

What changed

• src/mcp/tools/propertiesTools.ts
  • Exports CANONICAL_TOP_LEVEL_KEYS, CANONICAL_METADATA_KEYS,
    CANONICAL_ENVIRONMENT_KEYS sourced from the existing required-field
    constants plus the documented optional fields and template defaults.
  • Adds inline levenshtein() and closestCanonicalKey() helpers.
  • validateProperties now emits SCHEMA-001 warnings for any unknown
    key at top-level, metadata.*, or environment.*.
  • provar_properties_validate tool description updated to call out the
    testCases → testCase example explicitly.
• test/unit/mcp/propertiesTools.test.ts — 7 new test cases (top-level,
  metadata, environment, no-near-match, is_valid stays true, fixture round-trip).
• test/fixtures/properties/testcases-typo.json — shared regression fixture
  with the testCases typo (Thread B and the smoke harness will reference it).
• docs/mcp.md — provar_properties_validate section updated with SCHEMA-001
  description, classic-typo example, and clarified output shape (errors
  vs warnings arrays; is_valid only flips on errors).

Out of scope (sibling PRs)

• RUN-001 zero-tests guard on provar_automation_testrun — VALIDATE-TYPO-B (Thread B).
• validateProperties wired into provar_automation_config_load — final Thread B commit.
• Smoke-harness assertion for the typo fixture — VALIDATE-TYPO-B.
• PROVARHOME-001 — PDX-488 (Thread A, PR 2).
• PARALLEL-001 — PDX-494 (Thread A, PR 3).
• package.json / server.json beta bump — sweeper PR after the batch lands.

Test plan

• yarn compile clean (TypeScript)
• yarn lint clean (ESLint + script-name lint)
• node_modules/.bin/nyc node_modules/.bin/mocha "test/**/*.test.ts" — 1166 passing, 1 pending (unchanged from baseline)
• 37 propertiesTools.test.ts tests pass, including the 7 new SCHEMA-001 cases
• Husky commit-msg hook passes (RCA + Fix sections in body)
• Reviewer: confirm canonical key sets cover everything in docs/mcp.md provar_properties_set schema (cross-reference lines 1082–1097)
• Reviewer: confirm extension point is suitable for PDX-488 / PDX-494 (the exported CANONICAL_* constants)

Risk

Low. Warning-only behaviour — is_valid stays true on files that have
unknown keys, so no existing-caller breakage. Canonical sets are additive
(future Provar versions that add keys produce one extra warning until those
keys are added to the canonical set; no test run breakage).

[github-actions]

Quality Orchestrator

🟢 LOW · 14 / 100 · Touches: utils. All changed files have mapped tests.

---

🧪 Tests to Run · Running 2 of 52 tests

• unit/mcp/propertiesTools.test.ts
• unit/mcp/utils/warningCodes.test.ts

▶ Run command

npx vitest run \
  unit/mcp/propertiesTools.test.ts \
  unit/mcp/utils/warningCodes.test.ts

---

_{⚡ quality-orchestrator  ·  /qo stub <file>  ·  qo analyze-local}

[Copilot]

Pull request overview

Adds strict unknown-key detection to provar_properties_validate (SCHEMA-001) so schema typos like testCases vs testCase are surfaced as warnings with “Did you mean …?” suggestions, preventing silent no-op test runs later in the workflow.

Changes:

• Introduces shared WARNING_CODES + formatWarning() utility and documents warning codes in docs/mcp.md.
• Exports canonical properties key sets and adds Levenshtein-based “closest key” suggestion + SCHEMA-001 warning emission for unknown keys in provardx-properties.json.
• Adds unit tests and a regression fixture covering SCHEMA-001 behavior and suggestion/no-suggestion cases.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/mcp/utils/warningCodes.ts	Adds canonical warning codes + standardized warning formatter used by validators/tools.
src/mcp/tools/propertiesTools.ts	Implements canonical key sets + SCHEMA-001 unknown-key detection with Levenshtein suggestions.
test/unit/mcp/utils/warningCodes.test.ts	Unit coverage for warning codes mapping and formatter behavior.
test/unit/mcp/propertiesTools.test.ts	Adds SCHEMA-001 validation test cases (top-level/metadata/environment, suggestion threshold, fixture).
test/fixtures/properties/testcases-typo.json	Regression fixture containing the testCases typo for shared reuse.
docs/mcp.md	Documents warning codes + updates provar_properties_validate docs for SCHEMA-001 and output shape.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.