Repository navigation
ci: check package layering with import-linter - #5168
Conversation
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
7736e18 to
73dd99f
Compare
7fe8c49 to
c046caa
Compare
c046caa to
b912a64
Compare
b912a64 to
8c0f809
Compare
svcnvidia-nemo-ci
left a comment
There was a problem hiding this comment.
SHIP
LGTM — no concerns found.
Reviewed both changed files, including the hook configuration, layer contract and exceptions, and affected CI, package initialization, compatibility, and import paths. The existing lint entrypoint runs all hooks, and container hook-cache seeding includes the new dependency.
Static review only; tests and lint were not executed. Import-linter implementation source was unavailable, so its runtime semantics were not independently verified.
Note: formal approval is not available for this request, so this review is posted as a comment only.
Review generated by codex. This was a full review. Request a full review with /review reset=true.
8c0f809 to
9ed186e
Compare
4099dc2 to
8515f8e
Compare
8515f8e to
7199668
Compare
7199668 to
02b4520
Compare
02b4520 to
10df41f
Compare
yaoyu-33
left a comment
There was a problem hiding this comment.
Thanks for this. A layering ratchet in front of the moves is the right way to keep the cycle from growing while the stack lands, and the contract reads clearly next to the plan in #5166.
What we checked and found working
lint-importsreports the contract KEPT at this head, and the Lint check on this head ran the hook ("Check package layering (import-linter)...Passed"). The offline image seeds hook environments withpre-commit install-hooksfrom the same config, so the new hook needs nothing extra there.- Upward imports are caught at module level, inside functions, under
if TYPE_CHECKING:, and as relative imports. Indirect chains through unlayered modules are caught too. - A stale
ignore_importsentry and a missing layer module both fail the check.:keeps modules in one group free to import each other. All 26 exceptions are exact module pairs that point up today, and they match the table in the description. - The new tests pass in the core unit-test job. The red unit-test checks on this head are Docker Hub pull-rate limits (HTTP 429 in the Harbor image tests and the skillsbench agent tests). #5167's head shows the same failures, so this PR did not cause them.
Inline (two NOTEs)
- New modules inside the five packages that the contract lists by submodule (
cli,sandbox,_checkpoint,observability,tasks) land in no layer, and the coverage test cannot see them. Each package's move PR would surface them later, but the description promises they are checked now. The inline comment has a replacement test that we ran. - Imports through the lazy exports of the unlayered
nemo_gymandnemo_gym.cliroots never reach the graph.
Not blocking
- Order of
artifacts/: the contract puts it just belowserver_runtime/, while the plan in #5166 puts it just abovecore/. The contract's order is the one the code supports, because exporters importatif_export. It may be worth updating the issue so CODEOWNERS and reviewers work from the same order. - "This list may only shrink": the tool enforces this only for stale entries. Nothing stops a PR from adding an entry, and an entry that still matches an import but no longer points up stays silently. #5206 adds
client.server_client -> _checkpoint.settingseven as it removes others. Review ofpyproject.tomlis the real gate, which the comment could say. - Later in the stack (#5189 / #5195): once a module moves, an import through its old path has no file behind it, so grimp drops the edge. On #5195's head,
from nemo_gym.path_utils import ...insidenemo_gym/config/secret_utils.pystays KEPT, while the same import throughnemo_gym.utils.path_utilsis flagged. A test that rejects_moved_pathskeys insidenemo_gym/would close this. It fits best in #5189, the first move, and could go with the lazy-name test from the inline NOTE. - Validation list: the description lists the
lint-importsand hook runs. It could also list the new unit tests and the fullpre-commit run --all-files, which CI ran green.
Verdict: SHIP. The contract works as described for every module that is in a layer. Both notes are about modules and import routes outside the layers. Taking the suggested test and correcting the description's coverage sentence would make the guarantee match what is checked.
yaoyu-33
left a comment
There was a problem hiding this comment.
Approving. The rebased head (1c15aac) carries the same commit as the one we reviewed (43c1b6b); only the #5167 base under it moved. The Lint check on this head runs the new hook and passes ("Check package layering (import-linter)...Passed").
The two inline notes from the earlier review are not blocking. The failing server suite shard 0 is the Docker Hub pull-rate limit (toomanyrequests), not this change.
|
On the review's other notes:
|
yaoyu-33
left a comment
There was a problem hiding this comment.
Re-approving at 91efec2. The new coverage test closes the split-package gap: every module under nemo_gym/ must be in a layer, and an import through an unlayered package's re-export or through an old path now fails. The three sandbox imports now name the modules that define those names. The failing checks are the non-blocking harness conformance job.
Add an import-linter layers contract that orders today's nemo_gym modules by the package each one moves to, so CI rejects any new import that points up the target order, including imports inside functions. The 26 imports that point up the order today are listed as exceptions. Each goes away with the split or move that resolves it, and the list may only shrink. The check runs as a pre-commit hook, which the lint job already runs. A unit test checks that every top-level module and package of nemo_gym is in a layer of the contract, or listed with the reason it stays outside, so a new top-level module cannot go unchecked. Signed-off-by: Ananth Subramaniam <ansubramania@nvidia.com>
What and why
Adds an import-linter
layerscontract topyproject.tomland runs it as a pre-commit hook, which the lint job already runs. Today 52 of the top-level modules and packages innemo_gym/sit in one import cycle; the contract stops new code from adding to it while the moves land.Where this PR sits
The stack lands bottom-up; each PR's base is the branch of the PR before it, so each diff shows only that PR's change.
What the contract enforces
The contract lists today's modules grouped by the package each one moves to, in this order. An import may only point down.
An arrow means "imports"; each package imports only packages below it.
flowchart LR P["A PR adds an import"] --> L{"lint-imports"} L -->|"points down the order"| OK["Pass"] L -->|"points up the order"| E{"Listed in ignore_imports?"} E -->|"no"| F["Fail the lint job"] E -->|"yes"| OK M["Each move PR"] -->|"removes the entries it resolves"| E classDef this fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#1f2937 class L,E thisignore_importsentry that matches no import fails the check. A new entry does not, nor one whose import no longer points up, so review of the list is what keeps it from growing.__init__.pyofcli,sandbox,_checkpoint,observability, andtasksis unchecked until their moves land. Each new module inside them is checked.The 26 starting exceptions
openai_utils(trajectory, server, and verifier modules)core/global_configimports checkpoint settings, exporters, the sidecar config, the sandbox registry, telemetry setupjudgeand two sandbox providers import the HTTP client fromserver_utilsclient/sandbox/tasks/harbor/cli.pyimports the CLI and rollout collectioncli/tasks/harbor/run_summary.pyimports the health file namesartifacts/rollout_correlationimportsepisode_typescore/episode.pytelemetry/setup.pyimportssandbox.observabilitysandboxreads the rollout ID fromcore/artifacts/comparison/loading.pyimportsdid_you_meanfromcli/utils.pyutils/text.py(#5195)Keeping the contract complete
A module outside every layer is not checked at all, and two kinds of import go around the contract. Unit tests read the contract from
pyproject.tomland check three things:nemo_gym/is in a layer, or on a short list kept outside on purpose, each with its reason: the package root,package_info, the compatibility table_moved_paths, andverifiers, the standard-library-only package sandbox verifiers import by name. A new module, at the top level or inside a package the contract lists by submodule, has to join a layer before it merges.nemo_gym/imports no name through a package that is in no layer itself, such as the root,cli, orsandbox, unless the package defines the name. The contract records such an import as an import of the package alone. The test found four imports throughnemo_gym.sandbox, insandbox/shell.py,sandbox/transfer.py, andagent_utils/supervisor_client.py, which now import from the submodules that define the names.nemo_gym/imports nothing through an old path in_moved_paths.py, which has no file behind it. The table is empty here, so this check starts to apply in refactor(config): move config modules into nemo_gym/config #5189.Validation
lint-importsandpre-commit run import-linter --all-filespass.nemo_gym.rollout_collectioninside a function innemo_gym/failure_kinds.pyfails the contract.__init__.py, and forfrom nemo_gym import ServerClientorfrom nemo_gym.cli import RunHelperinsidenemo_gym/.pyteston the coverage tests and the sandbox tests, andpre-commit run --all-files.scripts/migrate_imports.pyrenames the contract's modules and the contract keeps passing.Rollout evidence: N/A. A CI check only.
Compatibility
No user-visible change. A contributor whose change adds an upward import gets a pre-commit failure.
Issue
Part of #5166.