langgenius / langgenius/dify

[Refactor/Chore] Add a baseline gate for incremental import-linter adoption

Open
#38,346 0 comments 1 reaction 1 assignee Claimed by @QuantumGhost View on GitHub
project#dify python refactor status: accepting prs
Dominant language
TypeScript
Stars
156k
Forks
24.6k
Avg merge
22h 9m
Merged PRs (30d)
610

Description

**AI disclosure**: This issue was drafted and analyzed with Codex using GPT-5.4. I have reviewed the analysis, and I am responsible for the content.

## Self Checks

- [x] I have read the [Contributing Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) and [Language Policy](https://github.com/langgenius/dify/issues/1542).
- [x] This is only for refactors or chores; if you would like to ask a question, please head to [Discussions](https://github.com/langgenius/dify/discussions/categories/general).
- [x] I have searched for existing issues, including closed ones.
- [x] I confirm that I am using English to submit this report, otherwise it will be closed.
- [x] 【中文用户 & Non English User】请使用英语提交,否则会被关闭 :)
- [x] Please do not modify this template :) and fill in all the required fields.

## Description

When a codebase already has many import-layer violations, `import-linter` is good at defining architectural contracts but it is not enough on its own to support incremental cleanup.

The practical problem is that once a layers or forbidden contract starts failing, the repository needs a second gate that prevents the violation set from getting worse while the refactor is still in progress.

A useful rule for that migration phase is:

- existing import violations may stay temporarily
- the baseline may shrink over time
- new violating imports must not be introduced

Without that second gate, teams either postpone contract adoption until the refactor is complete or accept that other contributors can keep adding new cross-layer imports during the cleanup.

## Motivation

This would make `import-linter` much more usable for legacy-to-layered refactors.

Today the common options are both weak:

- enable strict contracts immediately and fail on all existing violations, which is often too disruptive for a large legacy package
- postpone the contracts entirely, which leaves the refactor unprotected and allows the architecture to keep drifting

A baseline-aware wrapper solves the migration problem without changing the architectural source of truth:

- `import-linter` still defines what is illegal
- a small baseline file stores the currently known violating direct-import edges
- CI fails only when the current violation snapshot is no longer a subset of the baseline, or when the configured count threshold grows

This gives teams a monotonic cleanup path: violations can go down, but not up.

## Additional Context

A small implementation path is:

1. Run `import-linter` normally and inspect the broken contract metadata.
2. Normalize the broken direct-import edges into a stable JSON snapshot such as `contract -> importer -> imported modules`.
3. Commit that snapshot as a baseline file.
4. In CI, compare the current snapshot with the baseline.
5. Fail when the current snapshot introduces new violating edges.

A stricter and safer default is subset comparison instead of pure count comparison, because count-only gating can miss bad replacements where one legacy violation disappears but a different new one is introduced.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.