Skip to content

lint: enforce aitools package layering with depguard - #7829

Merged
anton-107 merged 4 commits into
mainfrom
aitools-depguard-layering
Nov 20, 2026
Merged

anton-107 merged 4 commits into
mainfrom
aitools-depguard-layering

Conversation

@anton-107

Copy link
Copy Markdown
Contributor

Changes

Adds four depguard rules to .golangci.yaml that pin down which packages the aitools code may import:

  • aitools-libs-no-commands: nothing under libs/aitools/ may import github.com/databricks/cli/cmd or any package below it.
  • aitools-commands-only-root: cmd/aitools/ may import only cmd/root and cmd/aitools from the cmd/ tree. External test packages in cmd/aitools can still import the package they test.
  • libs-no-aitools: other packages under libs/ may not import libs/aitools.
  • root-aitools-hooks-in-root-go: in cmd/root/, only root.go may import libs/aitools. That is where the root pre-run and post-run call the aitools user-agent, hint and auto-install hooks. Test files are exempt so they can stub those hooks.

The config has no other changes.

Why

The aitools code is layered: the cobra commands in cmd/aitools sit on top of libs/aitools, which sits on top of the shared libraries. Right now nothing stops a lower layer from importing a higher one, or another command group from coupling to aitools. These rules turn the intended direction into a lint error, so a wrong import fails CI and the error message points to where the code should go. They also keep the aitools hooks in the root command limited to a single file.

Tests

  • golangci-lint run --enable-only depguard ./... reports 0 issues on this branch, so existing code already follows the rules.
  • Only .golangci.yaml changes. No Go code or behavior changes.

## Changes

Adds four depguard rules to `.golangci.yaml` that pin down which packages the aitools code may import:

- `aitools-libs-no-commands`: nothing under `libs/aitools/` may import `github.com/databricks/cli/cmd` or any package below it.
- `aitools-commands-only-root`: `cmd/aitools/` may import only `cmd/root` and `cmd/aitools` from the `cmd/` tree. External test packages in `cmd/aitools` can still import the package they test.
- `libs-no-aitools`: other packages under `libs/` may not import `libs/aitools`.
- `root-aitools-hooks-in-root-go`: in `cmd/root/`, only `root.go` may import `libs/aitools`. That is where the root pre-run and post-run call the aitools user-agent, hint and auto-install hooks. Test files are exempt so they can stub those hooks.

The config has no other changes.

## Why

The aitools code is layered: the cobra commands in `cmd/aitools` sit on top of `libs/aitools`, which sits on top of the shared libraries. Right now nothing stops a lower layer from importing a higher one, or another command group from coupling to aitools. These rules turn the intended direction into a lint error, so a wrong import fails CI and the error message points to where the code should go. They also keep the aitools hooks in the root command limited to a single file.

## Tests

- `golangci-lint run --enable-only depguard ./...` reports 0 issues on this branch, so existing code already follows the rules.
- Only `.golangci.yaml` changes. No Go code or behavior changes.

Co-authored-by: Isaac <no-reply@databricks.com>
@anton-107
anton-107 requested a review from a team as a code owner November 19, 2026 20:50

@review-oss-bot review-oss-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Automated review at ee40ffa. Each finding was verified against the code.

No blocking issues found.

This PR adds four depguard rules to .golangci.yaml that enforce the intended layering of the aitools packages: libs/aitools cannot import cmd/, cmd/aitools can only import cmd/root and itself, other libs/ packages cannot import libs/aitools, and only cmd/root/root.go (plus tests) may import libs/aitools from cmd/root. The rules are syntactically correct, the glob patterns and package matchers are well-formed, and the configuration follows the existing depguard conventions in the file. I found no concrete defects that would warrant blocking or improving the change.

Co-authored-by: Isaac <no-reply@databricks.com>
@eng-dev-ecosystem-bot

eng-dev-ecosystem-bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

✅ Integration test report

Commit: 3801369

Run: 44645107285

Env 💚​RECOVERED ✅​pass 🙈​skip Time
💚​ aws linux-2core-8gb 1 272 19 3:33
💚​ aws-windows-latest-4core-16gb 1 274 17 4:20
💚​ azure linux-2core-8gb 1 271 19 3:36
💚​ azure-windows-latest-4core-16gb 1 273 17 3:21
💚​ gcp linux-2core-8gb 1 272 19 4:10
💚​ gcp-windows-latest-4core-16gb 1 274 17 4:12
Test Name aws linux-2core-8gb aws-windows-latest-4core-16gb azure linux-2core-8gb azure-windows-latest-4core-16gb gcp linux-2core-8gb gcp-windows-latest-4core-16gb
💚​ TestAccept 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
Top 3 slowest tests (at least 2 minutes):
duration env testname
4:18 aws-windows-latest-4core-16gb TestAccept
4:10 gcp-windows-latest-4core-16gb TestAccept
3:19 azure-windows-latest-4core-16gb TestAccept

@simonfaltum simonfaltum left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

🤖 Automated review from simonfaltum's review agent (pr-review skill) at ee40ffa. Each finding was verified against the code; simonfaltum may follow up.

No blocking issues found, approving. 5 non-blocking comment(s) and 3 question(s) below.

This PR adds four depguard rules that enforce the aitools package layering. Checked against the pinned depguard and golangci-lint source, the rules work as described: list-mode: lax, the longest-match allow/deny resolution, the cmd$ exact match and the !$test exclusion all behave correctly, and the full-repo lint in CI passes with 0 issues. Nothing is blocking. The main suggestion is to anchor the new files globs with ${config-path}, so a checkout under a libs directory doesn't produce false lint failures. The rest are nits on matching precision and on comments that describe more than the rules enforce, plus three non-blocking questions: whether other command groups should be restricted, the file pin in cmd/root, and negative checks for the rules.

Questions

  1. The Why section says these rules stop "another command group from coupling to aitools", but they only limit what cmd/aitools itself imports. Today cmd/apps/init.go, cmd/version/version.go and cmd/air/image.go import libs/aitools, experimental/aitools/cmd/aitools.go imports cmd/aitools, and nothing stops a new command group from doing the same. Should the description just change, or did you mean to add a rule on **/cmd/** that denies github.com/databricks/cli/cmd/aitools (exempting cmd/cmd.go, main.go and experimental/aitools/cmd)? (non-blocking)
  2. root-aitools-hooks-in-root-go pins which file in cmd/root may call aitools, but cmd/root still depends on libs/aitools as a package. cmd/root splits user-agent code into user_agent_*.go files, so moving the installer.With*InUserAgent calls into a user_agent_aitools.go would fail lint even though the dependency is the same. Did you consider registering these hooks from main.go, the way autoinstall.Run already is (main.go:29), so a plain "cmd/root must not import libs/aitools" rule could apply? Or is the file pin worth its friction? (non-blocking)
  3. The Tests section shows only that the rules raise no false errors today. A mistyped glob or pkg would also report 0 issues and leave a rule silently dead. Could you add a one-off negative check per rule to the description, for example temporarily importing cmd/auth from cmd/aitools and libs/aitools/installer from cmd/root/auth.go, and confirm depguard reports each with the expected message? (non-blocking)

Comment thread .golangci.yaml Resolved
Comment thread .golangci.yaml Resolved
Comment thread .golangci.yaml Resolved
Comment thread .golangci.yaml Resolved
Comment thread .golangci.yaml Resolved
…n matches

Anchor the aitools rules' files patterns at ${config-path} so a libs or cmd
directory above the checkout does not match. Deny the top-level cmd package
from cmd/aitools and match cmd/root, cmd/aitools and libs/aitools exactly or
by subpackage, so similarly named packages are not caught. Narrow the layering
comment to the boundaries the rules check and explain the lax list mode.

Co-authored-by: Isaac <no-reply@databricks.com>
Co-authored-by: Isaac <no-reply@databricks.com>
@anton-107
anton-107 added this pull request to the merge queue Nov 20, 2026
Merged via the queue into main with commit 3e563c9 Nov 20, 2026
27 checks passed
@anton-107
anton-107 deleted the aitools-depguard-layering branch November 20, 2026 01:04
@eng-dev-ecosystem-bot

Copy link
Copy Markdown
Collaborator

❌ Integration test report

Commit: 3e563c9

Run: 44650891032

Env 🔄​flaky 💚​RECOVERED ✅​pass 🙈​skip Time
💚​ aws linux-2core-8gb 27 1619 1419 179:29
🔄​ azure linux-2core-8gb 4 23 1599 1427 188:11
💚​ gcp linux-2core-8gb 27 1606 1425 184:30
27 interesting tests: 23 RECOVERED, 4 flaky
Test Name aws linux-2core-8gb azure linux-2core-8gb gcp linux-2core-8gb
💚​ TestAccept 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/deployment/bind/alert 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/deployment/bind/alert/DMS= 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/deployment/bind/alert/DMS=true 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/generate/alert 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/generate/alert/DMS= 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/generate/alert/DMS=true 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/alerts/basic 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/alerts/basic/DMS= 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/alerts/basic/DMS=true 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/alerts/with_file 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/alerts/with_file/DMS= 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/alerts/with_file/DMS=true 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started-omitted 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started-omitted/DMS= 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started-omitted/DMS=true 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started-toggle 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started-toggle/DMS= 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/apps/lifecycle-started-toggle/DMS=true 💚​R 💚​R 💚​R
🔄​ TestAccept/bundle/resources/apps/lifecycle-started/DMS= 💚​R 🔄​f 💚​R
🔄​ TestAccept/bundle/resources/apps/lifecycle-started/DMS=true 💚​R 🔄​f 💚​R
💚​ TestAccept/bundle/resources/postgres_synced_tables/basic 💚​R 💚​R 💚​R
💚​ TestAccept/bundle/resources/postgres_synced_tables/basic/DMS= 💚​R 💚​R 💚​R
🔄​ TestAccept/bundle/resources/postgres_synced_tables/recreate 💚​R 🔄​f 💚​R
🔄​ TestAccept/bundle/resources/postgres_synced_tables/recreate/DMS= 💚​R 🔄​f 💚​R
💚​ TestAccept/bundle/resources/postgres_synced_tables/recreate/DMS=true 💚​R 💚​R 💚​R
Top 50 slowest tests (at least 2 minutes):
duration env testname
11:15 gcp linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
9:32 azure linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=true
9:10 aws linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
8:31 aws linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
8:20 gcp linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
7:54 aws linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=true
7:50 azure linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=true
7:24 azure linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started/DMS=
6:48 gcp linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=
6:44 aws linux-2core-8gb TestAccept/bundle/config-remote-sync/multiple_resources/DMS=true
6:43 gcp linux-2core-8gb TestAccept/bundle/resources/clusters/deploy/local_ssd_count/DMS=
6:38 azure linux-2core-8gb TestAccept/bundle/config-remote-sync/multiple_resources/DMS=
6:31 gcp linux-2core-8gb TestAccept/bundle/invariant/no_drift/DMS=/INPUT_CONFIG=cluster_libraries.yml.tmpl/READPLAN=1
6:30 gcp linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=true
6:26 aws linux-2core-8gb TestAccept/bundle/config-remote-sync/multiple_resources/DMS=
6:14 gcp linux-2core-8gb TestAccept/bundle/invariant/no_drift/DMS=/INPUT_CONFIG=cluster_libraries.yml.tmpl/READPLAN=
6:14 azure linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=
6:14 gcp linux-2core-8gb TestAccept/bundle/invariant/no_drift/DMS=/INPUT_CONFIG=cluster_apply_policy_default_values.yml.tmpl/READPLAN=1
6:13 azure linux-2core-8gb TestAccept/bundle/config-remote-sync/multiple_resources/DMS=true
5:58 gcp linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=true
5:54 gcp linux-2core-8gb TestAccept/bundle/resources/clusters/deploy/local_ssd_count/DMS=true
5:48 gcp linux-2core-8gb TestAccept/bundle/config-remote-sync/multiple_resources/DMS=
5:47 aws linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started/DMS=
5:07 aws linux-2core-8gb TestAccept/bundle/deploy/spark-jar-task/DMS=
4:50 gcp linux-2core-8gb TestAccept/pipelines/run/refresh-flags
4:43 azure linux-2core-8gb TestAccept/pipelines/run/refresh-flags
4:35 gcp linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=
4:31 gcp linux-2core-8gb TestAccept/bundle/resources/apps/inline_config/DMS=true
4:29 gcp linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started-toggle/DMS=true
4:15 aws linux-2core-8gb TestAccept/pipelines/run/refresh-flags
4:15 aws linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=true
4:14 azure linux-2core-8gb TestAccept/bundle/deploy/spark-jar-task/DMS=true
4:07 azure linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started-omitted/DMS=true
4:06 aws linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=
3:47 azure linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started-toggle/DMS=true
3:46 gcp linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started-toggle/DMS=
3:41 gcp linux-2core-8gb TestAccept/bundle/deploy/spark-jar-task/DMS=true
3:41 aws linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started-toggle/DMS=true
3:37 azure linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=true
3:32 azure linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started-toggle/DMS=
3:29 azure linux-2core-8gb TestAccept/bundle/resources/clusters/lifecycle-started-toggle/DMS=
3:25 gcp linux-2core-8gb TestAccept/bundle/invariant/delete_idempotent/DMS=/INPUT_CONFIG=cluster_libraries.yml.tmpl/READPLAN=
3:15 aws linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started-toggle/DMS=
3:15 gcp linux-2core-8gb TestAccept/bundle/invariant/no_drift/DMS=true/INPUT_CONFIG=cluster_libraries.yml.tmpl/READPLAN=
3:11 gcp linux-2core-8gb TestAccept/bundle/invariant/no_drift/DMS=/INPUT_CONFIG=vector_search_index.yml.tmpl/READPLAN=
3:11 gcp linux-2core-8gb TestAccept/bundle/deploy/spark-jar-task/DMS=
3:10 gcp linux-2core-8gb TestAccept/bundle/resources/clusters/deploy/update-after-create/DMS=
3:10 aws linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started-omitted/DMS=
3:10 azure linux-2core-8gb TestAccept/bundle/resources/apps/lifecycle-started-omitted/DMS=
3:08 aws linux-2core-8gb TestAccept/bundle/deploy/spark-jar-task/DMS=true

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants