feat: warn on unknown concept metadata keys at load time#116
Merged
Conversation
Adds an optional custom_metadata_keys list to RuleModule, populated from module.toml. This will be used by the load-time metadata key validator to suppress warnings for domain-specific keys that are intentional but not part of the library's structural vocabulary.
Previously, typos or undeclared keys in concept TOML silently had no
effect — the library ignored them without any feedback. This made it
easy to author broken config that appeared correct.
Now, `load/1` calls `warn_unknown_metadata_keys/3` after building the
concept_metadata map. Any key not in the allowed set emits a
Logger.warning grouped by {key, type_id} to avoid one warning per
concept. The warning names the system slug and lists the affected
concept IDs (first 5, then "+ N more").
Allowed keys are the union of four sources:
1. The structural vocabulary (@structural_metadata_keys) — the 18 keys
the library reads by name from concept metadata.
2. metadata_contributions from_field and label_filters.filter_field
values, which the loader expands into effects at load time.
3. inventory_rules dynamic keys (mode_field, pool_field,
always_prepared_metadata_key, class_filter_field) — read by the
evaluator at runtime from the InventoryRules config.
4. custom_metadata_keys declared in module.toml — the escape hatch for
system authors who use domain-specific metadata keys that the
library never reads (e.g. display metadata like "school",
"casting_time", "description").
The dnd_5e_srd custom_metadata_keys list was built empirically by
running the integration test and iterating until zero warnings
remained, rather than enumerating by hand.
Warnings rather than errors to allow a smooth rollout. A future
breaking release can elevate these to errors once authors have had time
to migrate.
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
custom_metadata_keystoRuleModule/module.toml— the escape hatch for system authors to declare intentional domain keys (display metadata likeschool,casting_time, etc.) without triggering warningsLoader.load/1now callswarn_unknown_metadata_keys/3after building theconcept_metadatamap; any key not in the allowed set emits a groupedLogger.warning(one per{key, type_id}, listing affected concept IDs)metadata_contributionsfrom_field/label_filters.filter_field,inventory_rulesdynamic field names, andcustom_metadata_keysdnd_5e_srd/module.tomlgets acustom_metadata_keyslist (38 domain keys) built empirically via the integration test; loading the system now produces zero warningsCloses the "Add load-time validation for metadata keys" todo from the over-configurability cleanup list. Warnings now rather than errors — a future breaking release can elevate them once authors have migrated.
Test plan
dnd_5e_srd loads with no unknown metadata key warningsasserts zero log output when loading the full D&D 5e SRDmetadata_contributions.from_fieldkeys don't warn;custom_metadata_keyssuppresses warnings; multi-concept warnings group into one per{key, type_id}Summary by Bito