Skip to content

Commit 905dd17

Browse files
Copilotnathanjmcdougall
Copilot
and
nathanjmcdougall
authored
Add sync framework for inheriting content into AGENTS.md (#1581)
* Initial plan * Add check-doc-sync prek hook and sync AGENTS.md with docs/module-tree.txt Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/fe83eae1-2e6d-4e23-926b-9f9fdb6fdf37 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> * Move sync markers outside codeblock and strip codeblock fences in comparison Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/fe83eae1-2e6d-4e23-926b-9f9fdb6fdf37 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
1 parent 5ec237a commit 905dd17

3 files changed

Lines changed: 319 additions & 0 deletions

File tree

‎.pre-commit-config.yaml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,16 @@ repos:
7878
always_run: true
7979
pass_filenames: false
8080
priority: 0
81+
- repo: local
82+
hooks:
83+
- id: check-doc-sync
84+
name: check-doc-sync
85+
entry: uv run --frozen --offline hooks/check-doc-sync.py
86+
args: ["AGENTS.md"]
87+
language: system
88+
always_run: true
89+
pass_filenames: false
90+
priority: 0
8191
- repo: local
8292
hooks:
8393
- id: export-module-tree

‎AGENTS.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,201 @@ External skills can be installed if they are not present — see the `usethis-sk
5757
is complete, always run this skill to check for any issues before finishing.
5858
- ALWAYS mention which skills you've used after completing any task, in PR descriptions, and comments.
5959

60+
## Module Structure
61+
62+
<!-- sync:docs/module-tree.txt -->
63+
64+
```text
65+
usethis # usethis: Automate Python project setup and development tasks that are otherwise performed manually.
66+
├── __main__ # The CLI application for usethis.
67+
├── _config # Global configuration state for usethis.
68+
├── _config_file # Context managers for coordinated configuration file I/O.
69+
├── _console # Console output helpers for styled and structured printing.
70+
├── _deps # Dependency management operations for project dependency groups.
71+
├── _fallback # Central module for hard-coded fallback version constants.
72+
├── _init # Project initialization and build system setup.
73+
├── _subprocess # Subprocess invocation utilities.
74+
├── _test # Test utilities and fixtures for the usethis test suite.
75+
├── errors # Custom errors for the usethis package.
76+
├── _backend # Backend dispatch and tool-specific backend implementations.
77+
│ ├── dispatch # Backend selection and dispatch logic.
78+
│ ├── poetry # Poetry backend implementation.
79+
│ │ └── detect # Detection of Poetry usage in a project.
80+
│ └── uv # uv backend implementation.
81+
│ ├── available # Check whether the uv CLI is available.
82+
│ ├── call # Subprocess wrappers for invoking uv commands.
83+
│ ├── deps # Dependency group operations via the uv backend.
84+
│ ├── detect # Detection of uv usage in a project.
85+
│ ├── errors # Error types for the uv backend.
86+
│ ├── init # Project initialization via uv.
87+
│ ├── link_mode # Symlink link-mode configuration for uv.
88+
│ ├── lockfile # Lock file creation and management for uv.
89+
│ ├── python # Python version queries via uv.
90+
│ ├── toml # Manager for the uv.toml configuration file.
91+
│ └── version # Retrieve the installed uv version.
92+
├── _core # Core business logic for usethis commands.
93+
│ ├── author # Author metadata management for pyproject.toml.
94+
│ ├── badge # README badge generation and management.
95+
│ ├── browse # Open project-related URLs in a browser.
96+
│ ├── docstyle # Docstring style configuration.
97+
│ ├── list # List tools and their usage status.
98+
│ ├── readme # README file creation and management.
99+
│ ├── rule # Linter rule selection and configuration.
100+
│ ├── show # Display project information.
101+
│ ├── status # Development status classifier management.
102+
│ └── tool # Tool functions to add/remove tools to/from the project.
103+
├── _detect # The detections module.
104+
│ ├── pre_commit # Detection of pre-commit usage in a project.
105+
│ └── readme # Detection of README file presence.
106+
├── _file # Configuration file reading, writing, and merging.
107+
│ ├── dir # Project directory name utilities.
108+
│ ├── manager # Base file manager classes for configuration file I/O.
109+
│ ├── merge # Deep merge utilities for nested mappings.
110+
│ ├── print_ # Pretty-printing helpers for configuration file keys.
111+
│ ├── types_ # Shared type aliases for file operations.
112+
│ ├── ini # INI file reading and writing.
113+
│ │ ├── errors # Error types for INI file operations.
114+
│ │ └── io_ # INI file I/O manager.
115+
│ ├── pyproject_toml # pyproject.toml file reading and writing.
116+
│ │ ├── errors # Error types for pyproject.toml operations.
117+
│ │ ├── io_ # pyproject.toml file I/O manager.
118+
│ │ ├── name # Project name and description extraction from pyproject.toml.
119+
│ │ ├── project # Access the [project] section of pyproject.toml.
120+
│ │ ├── remove # Removal of the pyproject.toml file.
121+
│ │ ├── requires_python # Python version requirement queries from pyproject.toml.
122+
│ │ └── valid # Validation and repair of pyproject.toml structure.
123+
│ ├── setup_cfg # setup.cfg file reading and writing.
124+
│ │ ├── errors # Error types for setup.cfg operations.
125+
│ │ └── io_ # setup.cfg file I/O manager.
126+
│ ├── toml # TOML file reading and writing.
127+
│ │ ├── errors # Error types for TOML file operations.
128+
│ │ └── io_ # TOML file I/O manager.
129+
│ └── yaml # YAML file reading and writing.
130+
│ ├── errors # Error types for YAML file operations.
131+
│ ├── io_ # YAML file I/O manager.
132+
│ ├── typing_ # Type aliases for YAML document values.
133+
│ └── update # Smart update strategies for YAML sequences and mappings.
134+
├── _integrations # Third-party tool integrations.
135+
│ ├── ci # CI platform integrations.
136+
│ │ └── github # GitHub CI integration.
137+
│ │ ├── errors # Error types for GitHub CI operations.
138+
│ │ └── tags # GitHub repository tag fetching.
139+
│ ├── environ # Environment detection utilities.
140+
│ │ └── python # Python version environment queries.
141+
│ ├── mkdocs # MkDocs documentation integration.
142+
│ │ └── core # MkDocs project setup and configuration.
143+
│ ├── pre_commit # Pre-commit hook framework integration.
144+
│ │ ├── cmd_ # Pre-commit command constants.
145+
│ │ ├── core # Core pre-commit setup and teardown operations.
146+
│ │ ├── errors # Error types for pre-commit operations.
147+
│ │ ├── hooks # Pre-commit hook addition and removal.
148+
│ │ ├── init # Initialization of the pre-commit configuration file.
149+
│ │ ├── language # Pre-commit language keyword resolution.
150+
│ │ ├── schema # Pydantic models for the pre-commit configuration schema.
151+
│ │ ├── version # Pre-commit version inference.
152+
│ │ └── yaml # YAML file manager for the pre-commit configuration.
153+
│ ├── project # Project structure and metadata integration.
154+
│ │ ├── build # Build system detection for the project.
155+
│ │ ├── errors # Error types for project integration operations.
156+
│ │ ├── imports # Import graph analysis for the project.
157+
│ │ ├── layout # Project source directory layout detection.
158+
│ │ ├── name # Project name resolution with fallback heuristics.
159+
│ │ └── packages # Importable package discovery.
160+
│ ├── pydantic # Pydantic model utilities.
161+
│ │ ├── dump # Pydantic model serialization helpers.
162+
│ │ └── typing_ # Type aliases for Pydantic model representations.
163+
│ ├── pytest # pytest test framework integration.
164+
│ │ └── core # pytest directory and configuration setup.
165+
│ ├── readme # README file integration.
166+
│ │ └── path # README file path resolution.
167+
│ └── sonarqube # SonarQube integration.
168+
│ ├── config # SonarQube project configuration management.
169+
│ └── errors # Error types for SonarQube operations.
170+
├── _pipeweld # Pipeline welding algorithm for dependency-aware ordering.
171+
│ ├── containers # Container data structures for pipeline compositions.
172+
│ ├── func # Pipeline welding functions.
173+
│ ├── ops # Operation and instruction types for pipeline welding.
174+
│ └── result # Result types for pipeline welding.
175+
├── _python # Python language utilities.
176+
│ └── version # Utilities for Python version information.
177+
├── _tool # Tool management framework.
178+
│ ├── all_ # Registry of all available tools.
179+
│ ├── base # Base classes for tool implementations.
180+
│ ├── config # Configuration specification types for tools.
181+
│ ├── heuristics # Heuristic fallbacks for tool configuration.
182+
│ ├── pre_commit # Pre-commit hook specification types for tools.
183+
│ ├── rule # Lint rule specification types for tools.
184+
│ ├── spec # Abstract tool specification base classes.
185+
│ └── impl # Concrete tool implementations.
186+
│ ├── base # Tool base implementations with side effects.
187+
│ │ ├── codespell # Codespell tool implementation.
188+
│ │ ├── coverage_py # Coverage.py tool implementation.
189+
│ │ ├── deptry # deptry tool implementation.
190+
│ │ ├── import_linter # Import Linter tool implementation.
191+
│ │ ├── mkdocs # MkDocs tool implementation.
192+
│ │ ├── pre_commit # pre-commit tool implementation.
193+
│ │ ├── pyproject_fmt # pyproject-fmt tool implementation.
194+
│ │ ├── pyproject_toml # pyproject.toml as a managed tool.
195+
│ │ ├── pytest # pytest tool implementation.
196+
│ │ ├── requirements_txt # requirements.txt tool implementation.
197+
│ │ ├── ruff # Ruff tool implementation.
198+
│ │ └── ty # ty tool implementation.
199+
│ └── spec # Tool specification implementations.
200+
│ ├── codespell # Codespell tool specification.
201+
│ ├── coverage_py # Coverage.py tool specification.
202+
│ ├── deptry # deptry tool specification.
203+
│ ├── import_linter # Import Linter tool specification.
204+
│ ├── mkdocs # MkDocs tool specification.
205+
│ ├── pre_commit # pre-commit tool specification.
206+
│ ├── pyproject_fmt # pyproject-fmt tool specification.
207+
│ ├── pyproject_toml # pyproject.toml tool specification.
208+
│ ├── pytest # pytest tool specification.
209+
│ ├── requirements_txt # requirements.txt tool specification.
210+
│ ├── ruff # Ruff tool specification.
211+
│ └── ty # ty tool specification.
212+
├── _toolset # Predefined groups of related tools.
213+
│ ├── arch # Architecture enforcement toolset.
214+
│ ├── doc # Documentation toolset.
215+
│ ├── format_ # Code formatting toolset.
216+
│ ├── hook # Git hook framework toolset.
217+
│ ├── lint # Linting toolset.
218+
│ ├── spellcheck # Spell checking toolset.
219+
│ ├── test # Testing toolset.
220+
│ └── typecheck # Type checking toolset.
221+
├── _types # Shared type definitions and enumerations.
222+
│ ├── backend # Backend enumeration for package manager selection.
223+
│ ├── build_backend # Build backend enumeration for packaging tool selection.
224+
│ ├── deps # Dependency model definitions.
225+
│ ├── docstyle # Docstring style enumeration.
226+
│ └── status # Development status enumeration for classifiers.
227+
└── _ui # User interface layer for the CLI.
228+
├── app # The Typer application for usethis.
229+
├── options # Shared Typer option definitions.
230+
└── interface # Typer command interface modules.
231+
├── arch # CLI commands for architecture enforcement tools.
232+
├── author # CLI commands for managing project authors.
233+
├── badge # CLI commands for managing README badges.
234+
├── browse # CLI commands for browsing project resources.
235+
├── doc # CLI commands for documentation tools.
236+
├── docstyle # CLI commands for docstring style configuration.
237+
├── format_ # CLI commands for code formatting tools.
238+
├── hook # CLI commands for git hook framework tools.
239+
├── init # CLI commands for project initialization.
240+
├── lint # CLI commands for linting tools.
241+
├── list # CLI commands for showing out the full usage table.
242+
├── readme # CLI commands for README management.
243+
├── rule # CLI commands for linter rule management.
244+
├── show # CLI commands for showing project information.
245+
├── spellcheck # CLI commands for spell checking tools.
246+
├── status # CLI commands for development status configuration.
247+
├── test # CLI commands for testing tools.
248+
├── tool # CLI commands for individual tool management.
249+
├── typecheck # CLI commands for type checking tools.
250+
└── version # CLI commands for displaying version information.
251+
```
252+
253+
<!-- /sync:docs/module-tree.txt -->
254+
60255
## Lessons
61256

62257
When you are working on a problem, you are almost always going to encounter a difficulty. This is great - it's an opportunity for learning. ALWAYS make a note explicitly of what lessons you are drawing as you complete a task or when receiving user feedback. Try and keep this structured: consider the root cause of the difficulty, and how you overcame it. After finishing work on a task, report back all your lessons. Finally, try and update the relevant skills with any new insights you've drawn, to help future agents, and/or create a new skill.

0 commit comments

Comments
 (0)