Repository navigation
feat(arch): adoption guide + Python import-linter preset - #81
Merged
Merged
Conversation
Add presets/arch/SETUP.md, a dual-audience (human + agent) walkthrough for adopting architecture fitness on all three stacks, with a deep ArchUnit section (dependency, test placement, freeze store + archunit.properties, .gitattributes LF, refreeze escape hatch, changed-scope exclusion). Add the Python stack: presets/arch/importlinter.ini (hexagonal default + the four example maps) and an opt-in tier-c arch task in mise/python.toml, with import-linter pinned into the project .venv via setup:pytools (version + stamp). import-linter keeps its baseline inline, so pruning rides a ruleset-change PR; unmatched_ignore_imports_alerting=error (the default) prevents stale-ignore rot. Fix pre-restructure designs/ -> docs/designs/ path drift in the arch preset headers and the ts arch task comment; point the dep-cruiser baseline example at the root .dependency-cruiser.cjs the task actually uses; update the design doc's Implemented/Not-yet with the Python preset and the ratchet divergence.
Address review of the adoption guide: - setup:pytools installs import-linter only when arch is adopted (.importlinter / [tool.importlinter] present), the same three-way test the arch task uses, folded into the version stamp so adding config triggers a reinstall. Non-adopters no longer install or pip-audit it. (import-linter 2.15 + grimp verified clean under pip-audit; the preset's four acceptance scenarios verified live against 2.15.) - SETUP.md Java: seed the freeze store with allowStoreCreation=true, then remove it and commit, so a deleted store fails the test loudly (ruleset-guard's lines kind cannot see a deletion). allowStoreUpdate stays default-true, so new rules still freeze and fixed violations still prune. Spell out refreeze/delete as ruleset-change. - Bump the ArchUnit template + doc pin 1.3.0 -> 1.5.1 (current). CHANGELOG is release-please-generated from conventional commits (no Unreleased section), so these feat/fix messages feed it; no manual edit.
The adoption guide claims .importlinter / dep-cruiser / ArchUnit configs ride the ruleset-file watch; make that true. Extend the default ruleset_paths regex in _guards.yml and security.yml to cover .dependency-cruiser.cjs, .dependency-cruiser-known-violations.json, .importlinter and archunit_store/, and add two shrink-check cases to the guard loop: the dep-cruiser baseline reuses the snooze kind and the ArchUnit store the lines kind, so pruning either stays label-free while adding an entry (or editing a rule config) needs ruleset-change. Consumer-specific ArchUnit rule-class paths and monorepo-prefixed baselines are documented in SETUP.md as a ruleset_paths extension. Regex + YAML verified.
… .importlinter - ruleset_guard.py lines kind now skips '#' comment lines: ArchUnit's stored.rules is a Java Properties file with a changing '#<timestamp>' comment that would otherwise read as an added line on every legitimate prune. Add a test (21 pass). - Steer adopters to the standalone .importlinter in the preset header and SETUP.md: only that file is in the guard's default ruleset_paths, so an inlined [tool.importlinter]/[importlinter] config is unguarded unless added explicitly. - SETUP.md: note that a ruleset_paths override REPLACES the default (must re-list the arch paths), and that adding a new rule freezes new debt so expects the label.
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.
Adds a dual-audience (human + agent) walkthrough for adopting architecture fitness, fills the Python stack gap, and wires the arch configs into the ruleset-guard so the guide's CI claims are real.
What's here
presets/arch/SETUP.md— adoption guide for all three stacks. Deep ArchUnit section (dependency, test placement, freeze store +archunit.properties,.gitattributesLF, theallowStoreCreation/allowStoreUpdate/refreezesemantics, changed-scope exclusion); TS and Python walkthroughs; a "For agents" block with exact commands and the safe-vs-label matrix.presets/arch/importlinter.ini— Python preset: hexagonal default + the same four example maps as the TS/Java presets. Verified live against import-linter 2.15 (clean→pass, violation→fail, +ignore_imports→pass, fixed-but-ignore-kept→fail on unmatched, framework-freedom fires onpydanticindomain).mise/python.toml— opt-in tier-carchtask;import-linterpinned (Renovate-tracked) and installed into the project.venvbysetup:pytoolsonly when arch is adopted..dependency-cruiser.cjs,.dependency-cruiser-known-violations.json,.importlinter,archunit_store/added to the defaultruleset_paths; dep-cruiser baseline reuses thesnoozekind and the ArchUnit store thelineskind, so pruning stays label-free while adding an entry / editing a rule config needsruleset-change.Reviewer disclosures (scope grew past "a guide")
_guards.yml,security.ymldefaultruleset_paths). Consumers who pass their ownruleset_pathsoverride the default and won't get the arch paths unless they re-list them — documented in SETUP.md.setup:pytoolsstamp format changed (adds ano-arch/version token) → every existing Python consumer rebuilds its.venvonce on the nextmise install. Benign.ruleset_guard.py'slineskind now skips#comment lines so ArchUnit'sstored.rulesProperties timestamp can't read as an added line — but the first real Java adopter should confirm the store contents against thelinesmultiset.ruleset_guard.pytests: 21 pass.Design:
docs/designs/arch-fitness.md(Implemented/Not-yet + Python ratchet note updated).