Repository navigation
feat(compile)!: require a description on every named resource - #917
Merged
Merged
Conversation
kvlonge
enabled auto-merge (squash)
October 3, 2026 00:22
Missing descriptions are a P010 compile error for models, scenarios, seeds, sources, SQL and Python functions, named SQL and Python hooks, loaders, tasks, assets, checks and providers. Each finding points at the declaration and shows the exact header, YAML or decorator snippet to add. FUNCTION headers and @udf accept a new description (docstring fallback for Python UDFs), and @loader accepts description= with a docstring fallback. format --check and format now fault on missing MODEL, SCENARIO, FUNCTION and HOOK header descriptions, resolving [defaults], [path_defaults] and model_schema descriptions exactly as compile does. SQBRTEST105 is retired in favour of the compiler requirement. BREAKING CHANGE: projects with undescribed resources no longer compile. SQBRTEST105 was replaced by P010 and must be removed from [rules] select and ignore selectors, which otherwise fail with C000.
Add neutral generated descriptions (for example "Test model orders.") to the inline and on-disk test, script and performance-project fixtures so they compile under the P010 description requirement: MODEL, SCENARIO, FUNCTION, HOOK and SCHEMA headers, seed and source YAML entries (including dlt resources), and docstrings on Python tasks, assets, checks, loaders, hooks and UDFs. Generated benchmark projects now emit descriptions too, so their fingerprints change for this reason only. Diagnostic line expectations that moved with inserted lines are updated.
Describe the P010 requirement, where each resource kind declares its description, the new FUNCTION and @udf description fields, loader and provider docstrings, dlt resource descriptions and the format --check fault. Add descriptions to every documentation and README example and regenerate the agent skill references.
…rator The same-runner compile ratio job generated one project with head's generator and compiled it with both builds, so any change that adds syntax to the generators (such as FUNCTION descriptions) made the base build reject the project. compare_compile_performance now accepts --base-root: the base project is written by the base checkout's own write_benchmark_project (run with the head interpreter and the base root on PYTHONPATH), head's project by head's generator, and each build compiles its own project. Base generation failures stop the comparison with the generator's stderr tail, and the report notes per-side generation. Without --base-root the single-project behaviour is kept.
kvlonge
force-pushed
the
feat/chi-390-required-descriptions
branch
from
October 3, 2026 00:51
5c0a30d to
aeeb41b
Compare
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
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.
Why
Resources without descriptions ship to catalogues and docs with nothing to explain them, and the old SQBRTEST105 check only covered scenarios as a rule finding (CHI-390).
Changes
descriptionkey), Python UDFs (@udf(description=)or a docstring), named SQL hooks, Python hooks, loaders, tasks, assets, checks and providers. Model descriptions resolve from the header,[defaults]/[path_defaults], ormodel_schema.[rules]select/ignore.sqb formatreports a missing description as a fault, using the same resolution as compile and SQL-only discovery.Verification
make test,make check-ci.