[transceiver][test-plan][attribute_parser]: restructure per-category attribute JSONs into scope-rooted shards

[mihirpat1]

Description of PR

Summary:
Restructure the per-category transceiver attribute JSONs under ansible/files/transceiver/inventory/attributes/ from a single flat <category>.json file into a sharded, scope-rooted layout. Every non-category shard (platform / HWSKU / vendor / per-PN) carries only its scope's body; the scope is encoded entirely in the directory path. The loader grafts each body into the correct slot of the merged in-memory tree before priority resolution.

attributes/<category>/
  <category>.json                                              # mandatory / defaults / dut / deployment_configurations
  platforms/<PLATFORM>/<category>.json                         # platform body
  platforms/<PLATFORM>/hwskus/<HWSKU>.json                     # HWSKU body
  transceivers/vendors/<V>/<category>.json                     # vendor `defaults` body
  transceivers/vendors/<V>/part_numbers/<PN>/<category>.json   # per-PN body (attrs + optional firmware_overrides / platform_hwsku_overrides)

Because each shard owns a disjoint subtree of the merged tree, two shards can never write the same key path - the directory IS the schema. Path/payload mismatch and duplicate-leaf checks are no longer needed; the layout makes them structurally impossible.

Fixes # (issue) — ADO PBI link will be added in a comment.

Type of change

• Bug fix
• Testbed and Framework(new/improvement)
• New Test case
  • Skipped for non-supported platforms
• Test case improvement

Back port request

• 202205
• 202305
• 202311
• 202405
• 202411
• 202505
• 202511

Approach

What is the motivation for this PR?

The previous single-file-per-category layout did not scale to vendor onboarding and per-PN tuning. Every vendor or PN-specific tweak had to be edited into the same shared JSON, creating merge friction and making it easy to mis-place attributes. A path-mismatch or duplicate-leaf required custom loader checks to catch.

The sharded layout isolates each ownership level into its own file and uses the directory structure itself as the schema - vendor onboarding adds a vendor directory, PN-specific tuning adds a PN directory, and no two shards can collide.

How did you do it?

Loader (tests/transceiver/attribute_parser/attribute_manager.py)

• Discovers shards from the directory tree and grafts each body into the right slot.
• Validation reduced from 5 checks to 4:
  1. Category top-key whitelist — only mandatory, defaults, dut, and transceivers.deployment_configurations allowed at category-level.
  2. Body-shape sanity — every shard body must be an object; per-PN firmware_overrides / platform_hwsku_overrides must be dict-of-dict.
  3. Normalization check — vendor/PN directory names must appear in normalization_mappings.json when the vendor/PN owns a shard.
  4. Mandatory-field resolution — after merge + priority resolution, every port resolves each mandatory field somewhere in the hierarchy.

Tests (tests/transceiver/attribute_parser/transceiver_attribute_infra_test.py)

• _shard_category helper rewritten to emit scope-rooted bodies.
• Removed: path/payload mismatch (both vendor + per-PN), vendor-shard extra slot, duplicate-leaf detection — all structurally impossible now.
• Rewritten: slot-whitelist and normalization-check tests use raw bodies.
• Added: test_loader_pn_reserved_subslot_shape covers the dict-of-dict check.

HLD updates in docs/testplan/transceiver/:

• test_plan.md — File Organization (tree + shard contracts table), Loader Validation (5 → 4 checks), JSON Schema Structure (scope-rooted examples).
• diagrams/file_organization.md and diagrams/data_flow.md — trees + Mermaid graphs updated; priority hierarchy 8 → 9 levels (firmware_overrides reserved slot).
• eeprom_test_plan.md, system_test_plan.md, dom_test_plan.md — pre-req / attributes sections link to the shard layout and validation rules.
• Example inventory under docs/testplan/transceiver/examples/inventory/attributes/eeprom/ — flat eeprom.json replaced by a full scope-rooted shard tree exercising platform / HWSKU / two vendors / two per-PN files.

How did you verify/test it?

python3 tests/transceiver/attribute_parser/transceiver_attribute_infra_test.py
…
Test Summary: 25 passed, 0 failed out of 25 tests
All tests passed!

Any platform specific information?

None — this is framework / HLD work; no DUT runtime behavior is affected. Loader changes are exercised by the standalone unit-test runner.

Supported testbed topology if it's a new test case?

N/A — no new test cases. Framework + documentation only.

Documentation

The HLD documents in docs/testplan/transceiver/ are part of this PR. The example inventory tree under docs/testplan/transceiver/examples/inventory/ is updated to match the new layout.

[mssonicbld]

/azp run