Skip to content

feat: resolve lists of component references - #176

Open
pesap wants to merge 4 commits into
mainfrom
feat/list-component-references
Open

pesap wants to merge 4 commits into
mainfrom
feat/list-component-references

Conversation

@pesap

@pesap pesap commented Nov 3, 2026

Copy link
Copy Markdown
Collaborator

Summary

Add ComponentReference.resolve_as so parser rules can resolve a source field containing multiple names to the existing components in a system. The default component mode resolves one name. The opt-in list mode resolves an ordered list without requiring individual references in configuration.

The parser guide now shows how to aggregate names in a table mapping and resolve them in parser rules. The public API docstring and r2x-core ingestion reference describe the result shapes and failure behavior.

Acceptance criteria

  • Resolve one name by default or explicitly with resolve_as: "component".
  • Resolve a list of names with resolve_as: "list", preserving order, duplicates, and component identity.
  • Reject invalid shapes, invalid names, missing fields, unresolved components, and unsupported modes.
  • Allow target models to validate empty lists and list-versus-scalar field shapes.
  • Exercise CSV reading, table aggregation, configured parsing, shared references, and system serialization.
  • Document the configuration and provide an executable example.

Deviations from the original plan

  • RESOLVE parser migration and full raw-fixture table assembly are outside this change. A separate smoke check used real RESOLVE models and manually prepared rows from the 2035 fixture.
  • The full Astro documentation build was not run locally because the worktree has no installed Node dependencies. The Sphinx JSON API build passed with external inventories disabled.

Testing Strategy

  • uv run --locked --no-sync pytest -q --no-cov tests/test_ingestion.py tests/test_table_mapping.py -k 'list_reference or scalar_reference or component_reference_schema_describes_result_shapes or component_reference_rejects_invalid_resolve_as or empty_reference_list or grouped_names'
  • uv run --locked --no-sync pytest -q --no-cov tests/test_docs_doctest.py -k build-parsers
  • uv run --locked --no-sync pytest -q --no-cov tests/test_docs_tutorial.py::CsvTutorialTest::test_marked_examples_have_checked_expectations tests/test_docs_doctest.py::test_documentation_expectations_are_copyable
  • uv run --locked --no-sync pytest -q --no-cov tests/test_docs_generate_api.py
  • uv run --locked --no-sync ruff format --check src/r2x_core/ingestion.py src/r2x_core/models.py tests/fixtures/ingestion_models.py tests/test_ingestion.py tests/test_table_mapping.py
  • mise run --skip-tools lint
  • mise run --skip-tools type

References

  • src/r2x_core/ingestion.py
  • docs/src/content/docs/how-tos/build-parsers.md

Allow parser instructions to resolve a list of component names to existing system objects. Document the result shapes and validate list, scalar, and serialization behavior.
Copilot AI balanced review requested due to automatic review settings November 3, 2026 16:52
@codecov-commenter

codecov-commenter commented Nov 3, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.05%. Comparing base (d090584) to head (dd11bf2).

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #176      +/-   ##
==========================================
+ Coverage   98.04%   98.05%   +0.01%     
==========================================
  Files          58       58              
  Lines        6597     6638      +41     
==========================================
+ Hits         6468     6509      +41     
  Misses        129      129              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the opt-in component list-resolution change.

No open issues 🎉

What changed in this PR

Adds opt-in list resolution to ComponentReference, allowing parser rules to link multiple existing components from one source field while preserving the default single-component behavior.

Changes:

  • Adds resolve_as="list" with shape validation and preservation of order, duplicates, and component identity.
  • Adds coverage for invalid inputs, target-model validation, CSV/table aggregation, shared references, and serialization.
  • Documents configuration and failure behavior with an executable parser example.
File Description
tests/​test_table_mapping.py Tests aggregated name resolution and serialization round trips.
tests/​test_ingestion.py Tests list and scalar resolution, validation, and identity preservation.
tests/​fixtures/​ingestion_models.py Adds bus-group models with optional and required membership.
src/​r2x_core/​models.py Defines and documents the resolve_as configuration field.
src/​r2x_core/​ingestion.py Validates name lists and resolves them to existing components.
skills/​r2x-core/​references/​INGESTION.md Documents list-reference configuration and behavior.
docs/​src/​content/​docs/​how-tos/​build-parsers.md Adds table-mapping guidance and an executable list-resolution example.
docs/​source/​references/​parser.md Links to the reference API and list-resolution guide.

Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings November 3, 2026 16:55

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

There are no active review issues for the list-valued component reference changes.

No open issues 🎉

Review effort: Balanced

Handle scalar and list references in separate branches and document why the validated modes allow this structure.
Copilot AI balanced review requested due to automatic review settings November 3, 2026 17:01

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the opt-in list-resolution change.

No open issues 🎉

Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings November 3, 2026 20:34

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the list-valued component reference resolution change.

No open issues 🎉

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants