python-dependency-linter 0.2.0__tar.gz → 0.4.0__tar.gz

python_dependency_linter-0.4.0/.claude/skills/commit/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: commit
+description: Create a git commit following the project's commit convention
+---
+
+Create a git commit following the project's commit convention defined in [CONTRIBUTING.md](../../../CONTRIBUTING.md).
+
+## Steps
+
+1. Read `CONTRIBUTING.md` to check the commit convention.
+2. Run `git status` and `git diff` to review all changes.
+3. Draft a commit message following the convention.
+4. Stage only relevant files (do NOT use `git add -A`). Exclude secrets and unrelated files.
+5. Commit using a HEREDOC for proper formatting:
+   ```bash
+   git commit -m "$(cat <<'EOF'
+   <commit message here>
+
+   Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+   EOF
+   )"
+   ```
+6. Run `git status` to verify success.
+7. If pre-commit hook fails, fix the issue and create a **new** commit (never amend).

python_dependency_linter-0.4.0/.claude/skills/release/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: release
+description: Create a new release by calculating the next version from conventional commits and pushing a git tag
+---
+
+Create a new release following the project's release process defined in [CONTRIBUTING.md](../../../CONTRIBUTING.md).
+
+The release workflow is defined in [.github/workflows/publish.yaml](../../../.github/workflows/publish.yaml).
+
+## Steps
+
+1. Read `CONTRIBUTING.md` to check the release process.
+2. Follow the steps described in the Release section.
+3. Ask the user to confirm the version before creating and pushing the tag.

python_dependency_linter-0.4.0/.github/pull_request_template.md

@@ -0,0 +1,27 @@
+<!--
+  ⚠️ PR Title Convention
+  PRs are squash merged, so the PR title becomes the final commit message.
+  Please use the following format:
+
+    <gitmoji> <type>: <Description>
+
+  Examples:
+    ✨ feat: Add support for relative imports
+    🐛 fix: Use exit code 2 for config file not found
+
+  See CONTRIBUTING.md for the full list of types.
+-->
+
+## What does this PR do?
+
+<!-- A brief description of the change. -->
+
+## Related issue
+
+<!-- Link to the issue this PR addresses, e.g., Closes #123 -->
+
+## Checklist
+
+- [ ] Tests added / updated
+- [ ] `pdl check` runs without errors on the example config
+- [ ] Documentation updated (if applicable)

python_dependency_linter-0.4.0/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.3.0] - 2026-03-30
+
+### Bug Fixes
+
+- Use exit code 2 for config file not found (#11)
+
+### Documentation
+
+- Add CONTRIBUTING.md and CLAUDE.md
+- Add PR title convention to template and CONTRIBUTING.md
+- Add release process to CONTRIBUTING.md and /release skill
+
+### Features
+
+- Resolve relative imports to absolute module names (#10)
+- Add include/exclude file filtering options (#12)
+
+### Miscellaneous
+
+- Add /commit skill for Claude Code
+- Add uv.lock for reproducible builds
+## [0.2.0] - 2026-03-30
+
+### Documentation
+
+- Remove design spec and implementation plan docs
+- Add GitHub issue and PR templates
+- Add example for omitted category behavior in allow rules
+- Add architecture examples to README
+- Add pre-commit hook custom options example
+- Expand pyproject.toml examples with multiple rules and deny
+- Add "What It Does" section to README
+
+### Features
+
+- Support `**` glob pattern for matching nested submodules (#6)
+- Add undocumented features to README
+
+### Miscellaneous
+
+- Use hatch-vcs for dynamic versioning from git tags
+- Add gitmoji preprocessor to git-cliff config
+- Move git-cliff config from cliff.toml to pyproject.toml
+- Skip CHANGELOG update commits in git-cliff output
+
+### Testing
+
+- Limit CI to source and test file changes
+
+### Build
+
+- Bump actions/checkout from 4 to 6 (#3)
+- Bump actions/setup-python from 5 to 6 (#2)
+## [0.1.0] - 2026-03-30
+
+### Bug Fixes
+
+- Add isort config and fix plan typo
+- Add tomli fallback for Python 3.10 compatibility
+- Add import content to fixture files
+
+### CI/CD
+
+- Add GitHub Actions for CI, PyPI publish, and Dependabot
+- Add git-cliff changelog generation on release
+- Add GitHub Release creation on tag
+
+### Documentation
+
+- Add design spec for python-dependency-linter
+- Add implementation plan
+- Add README
+- Add MIT LICENSE
+
+### Features
+
+- Add config loading for YAML and pyproject.toml
+- Add AST-based import parser
+- Add import resolver for classification
+- Add wildcard matcher and rule merging
+- Add dependency checker with allow/deny logic
+- Add violation reporter
+- Add CLI with check command
+- Add pre-commit hook definition
+
+### Miscellaneous
+
+- Initialize project scaffolding
+- Add license, readme, and classifiers to pyproject.toml
+- Add .gitignore

python_dependency_linter-0.4.0/CLAUDE.md

@@ -0,0 +1,9 @@
+# CLAUDE.md
+
+## Project Overview
+
+Python dependency linter (`pdl`) - A CLI tool that lints layer dependency rules in Python projects.
+
+## Contributing
+
+Follow the conventions in [CONTRIBUTING.md](./CONTRIBUTING.md).

python_dependency_linter-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing
+
+## Commit Convention
+
+Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/) with [gitmoji](https://gitmoji.dev/) prefix.
+
+### Format
+
+```
+<gitmoji> <type>: <description>
+```
+
+- The first letter after the colon must be **capitalized**.
+- The description must be in **English**.
+
+### Types
+
+| Gitmoji | Type       | Description              |
+|---------|------------|--------------------------|
+| ✨      | `feat`     | New feature              |
+| 🐛      | `fix`      | Bug fix                  |
+| ♻️      | `refactor` | Code refactoring         |
+| 📝      | `docs`     | Documentation            |
+| ✅      | `test`     | Adding or updating tests |
+| 🔧      | `chore`    | Maintenance tasks        |
+| 👷      | `ci`       | CI/CD changes            |
+| ⚡      | `perf`     | Performance improvement  |
+
+### Examples
+
+```
+✨ feat: Add support for relative imports
+🐛 fix: Use exit code 2 for config file not found
+♻️ refactor: Simplify module resolver logic
+```
+
+## Pull Request Convention
+
+- PRs are always **squash merged**, so the PR title becomes the final commit message.
+- PR titles must follow the same format as commit messages (`<gitmoji> <type>: <description>`).
+- PR descriptions must be written in **English**.
+
+## Pre-commit Hooks
+
+This project uses [pre-commit](https://pre-commit.com/) with [ruff](https://docs.astral.sh/ruff/) for linting and formatting.
+
+```bash
+# Install pre-commit hooks
+pre-commit install
+
+# Run manually
+pre-commit run --all-files
+```
+
+All commits must pass the pre-commit hooks before being accepted.
+
+## Release
+
+Releases are automated via GitHub Actions. You only need to create and push a version tag.
+
+### Steps
+
+1. Calculate the next version based on conventional commits:
+   ```bash
+   uvx git-cliff --bumped-version
+   ```
+2. Review the commits since the last tag:
+   ```bash
+   git log $(git describe --tags --abbrev=0)..HEAD --oneline
+   ```
+3. Push the latest commits to `main`:
+   ```bash
+   git push origin main
+   ```
+4. Create and push the tag:
+   ```bash
+   git tag <version>
+   git push origin <version>
+   ```
+
+The GitHub Actions workflow will then automatically:
+- Generate `CHANGELOG.md` and commit it to `main`
+- Create a GitHub Release with release notes
+- Publish the package to PyPI

{python_dependency_linter-0.2.0 → python_dependency_linter-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-dependency-linter
-Version: 0.2.0
+Version: 0.4.0
 Summary: A dependency linter for Python projects
 License-Expression: MIT
 License-File: LICENSE
@@ -148,6 +148,35 @@ rules:
 
 ## Configuration
 
+### Include / Exclude
+
+Control which files are scanned using `include` and `exclude`:
+
+```yaml
+include:
+  - src
+exclude:
+  - src/generated/**
+
+rules:
+  - name: ...
+```
+
+- **No `include` or `exclude`** — All `.py` files under the project root are scanned
+- **`include` only** — Only files matching the given paths are scanned
+- **`exclude` only** — All files except those matching the given paths are scanned
+- **Both** — `include` is applied first, then `exclude` filters within that result
+
+Bare directory names (e.g., `src`) and trailing-slash forms (e.g., `src/`) are treated the same as `src/**`.
+
+In `pyproject.toml`:
+
+```toml
+[tool.python-dependency-linter]
+include = ["src"]
+exclude = ["src/generated/**"]
+```
+
 ### Rule Structure
 
 Each rule has:
@@ -177,6 +206,8 @@ Dependencies are classified into three categories (per PEP 8):
 - `third_party` — Installed packages (`pydantic`, `sqlalchemy`, ...)
 - `local` — Modules in your project
 
+Both absolute imports (`from contexts.boards.domain import models`) and relative imports (`from ..domain import models`) are analyzed. Relative imports are resolved to absolute module names based on the file's location.
+
 ### Behavior
 
 - **No rule** — Everything is allowed
@@ -278,20 +309,24 @@ third_party = ["boto3"]
 ## CLI
 
 ```bash
-# Check with default config (.python-dependency-linter.yaml)
+# Check with auto-discovered config (searches upward from cwd)
 pdl check
 
-# Specify config file
+# Specify config file (project root = config file's parent directory)
 pdl check --config path/to/config.yaml
-
-# Specify project root
-pdl check --project-root path/to/project
 ```
 
 Exit codes:
 
 - `0` — No violations
 - `1` — Violations found
+- `2` — Config file not found
+
+If no `--config` is given, the tool searches upward from the current directory for `.python-dependency-linter.yaml` or `pyproject.toml` (with `[tool.python-dependency-linter]`). The config file's parent directory is used as the project root. If no config file is found, the tool prints an error and exits with code `2`:
+
+```
+Error: Config file not found. Create .python-dependency-linter.yaml or configure [tool.python-dependency-linter] in pyproject.toml.
+```
 
 ## Pre-commit
 
@@ -304,14 +339,14 @@ Add to `.pre-commit-config.yaml`:
     - id: python-dependency-linter
 ```
 
-To pass custom options (e.g., a different config file or project root):
+To pass custom options (e.g., a different config file):
 
 ```yaml
 - repo: https://github.com/heumsi/python-dependency-linter
   rev: v0.1.0
   hooks:
     - id: python-dependency-linter
-      args: [--config, custom-config.yaml, --project-root, src]
+      args: [--config, custom-config.yaml]
 ```
 
 ## License

{python_dependency_linter-0.2.0 → python_dependency_linter-0.4.0}/README.md

@@ -123,6 +123,35 @@ rules:
 
 ## Configuration
 
+### Include / Exclude
+
+Control which files are scanned using `include` and `exclude`:
+
+```yaml
+include:
+  - src
+exclude:
+  - src/generated/**
+
+rules:
+  - name: ...
+```
+
+- **No `include` or `exclude`** — All `.py` files under the project root are scanned
+- **`include` only** — Only files matching the given paths are scanned
+- **`exclude` only** — All files except those matching the given paths are scanned
+- **Both** — `include` is applied first, then `exclude` filters within that result
+
+Bare directory names (e.g., `src`) and trailing-slash forms (e.g., `src/`) are treated the same as `src/**`.
+
+In `pyproject.toml`:
+
+```toml
+[tool.python-dependency-linter]
+include = ["src"]
+exclude = ["src/generated/**"]
+```
+
 ### Rule Structure
 
 Each rule has:
@@ -152,6 +181,8 @@ Dependencies are classified into three categories (per PEP 8):
 - `third_party` — Installed packages (`pydantic`, `sqlalchemy`, ...)
 - `local` — Modules in your project
 
+Both absolute imports (`from contexts.boards.domain import models`) and relative imports (`from ..domain import models`) are analyzed. Relative imports are resolved to absolute module names based on the file's location.
+
 ### Behavior
 
 - **No rule** — Everything is allowed
@@ -253,20 +284,24 @@ third_party = ["boto3"]
 ## CLI
 
 ```bash
-# Check with default config (.python-dependency-linter.yaml)
+# Check with auto-discovered config (searches upward from cwd)
 pdl check
 
-# Specify config file
+# Specify config file (project root = config file's parent directory)
 pdl check --config path/to/config.yaml
-
-# Specify project root
-pdl check --project-root path/to/project
 ```
 
 Exit codes:
 
 - `0` — No violations
 - `1` — Violations found
+- `2` — Config file not found
+
+If no `--config` is given, the tool searches upward from the current directory for `.python-dependency-linter.yaml` or `pyproject.toml` (with `[tool.python-dependency-linter]`). The config file's parent directory is used as the project root. If no config file is found, the tool prints an error and exits with code `2`:
+
+```
+Error: Config file not found. Create .python-dependency-linter.yaml or configure [tool.python-dependency-linter] in pyproject.toml.
+```
 
 ## Pre-commit
 
@@ -279,14 +314,14 @@ Add to `.pre-commit-config.yaml`:
     - id: python-dependency-linter
 ```
 
-To pass custom options (e.g., a different config file or project root):
+To pass custom options (e.g., a different config file):
 
 ```yaml
 - repo: https://github.com/heumsi/python-dependency-linter
   rev: v0.1.0
   hooks:
     - id: python-dependency-linter
-      args: [--config, custom-config.yaml, --project-root, src]
+      args: [--config, custom-config.yaml]
 ```
 
 ## License

{python_dependency_linter-0.2.0 → python_dependency_linter-0.4.0}/python_dependency_linter/cli.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
+import fnmatch
 from pathlib import Path
 
 import click
 
 from python_dependency_linter.checker import check_import
-from python_dependency_linter.config import load_config
+from python_dependency_linter.config import find_config, load_config
 from python_dependency_linter.matcher import find_matching_rules, merge_rules
 from python_dependency_linter.parser import parse_imports
 from python_dependency_linter.reporter import format_violations
@@ -36,8 +37,43 @@ def _package_module(file_path: Path, project_root: Path) -> str:
     return ".".join(parts)
 
 
-def _find_python_files(project_root: Path) -> list[Path]:
-    return sorted(project_root.rglob("*.py"))
+def _normalize_pattern(pattern: str, project_root: Path) -> str:
+    """Normalize a pattern so that bare directory names match all files within."""
+    clean = pattern.rstrip("/")
+    candidate = project_root / clean
+    if candidate.is_dir() or not any(c in clean for c in ("*", "?")):
+        clean = f"{clean}/**"
+    return clean
+
+
+def _matches_any(path: Path, patterns: list[str]) -> bool:
+    return any(fnmatch.fnmatch(str(path), p) for p in patterns)
+
+
+def _find_python_files(
+    project_root: Path,
+    include: list[str] | None = None,
+    exclude: list[str] | None = None,
+) -> list[Path]:
+    all_files = sorted(project_root.rglob("*.py"))
+
+    if include is not None:
+        normalized = [_normalize_pattern(p, project_root) for p in include]
+        all_files = [
+            f
+            for f in all_files
+            if _matches_any(f.relative_to(project_root), normalized)
+        ]
+
+    if exclude is not None:
+        normalized = [_normalize_pattern(p, project_root) for p in exclude]
+        all_files = [
+            f
+            for f in all_files
+            if not _matches_any(f.relative_to(project_root), normalized)
+        ]
+
+    return all_files
 
 
 @click.group()
@@ -49,22 +85,32 @@ def main():
 @click.option(
     "--config",
     "config_path",
-    default=".python-dependency-linter.yaml",
+    default=None,
     help="Path to config file.",
 )
-@click.option("--project-root", default=".", help="Project root directory.")
-def check(config_path: str, project_root: str):
-    root = Path(project_root).resolve()
-    config_file = Path(config_path)
-
-    try:
-        config = load_config(config_file)
-    except FileNotFoundError as e:
-        click.echo(f"Error: {e}", err=True)
-        raise SystemExit(1)
+def check(config_path: str | None):
+    if config_path is not None:
+        config_file = Path(config_path)
+        if not config_file.exists():
+            click.echo(f"Error: Config file not found: {config_file}", err=True)
+            raise SystemExit(2)
+        root = config_file.resolve().parent
+    else:
+        config_file = find_config()
+        if config_file is None:
+            click.echo(
+                "Error: Config file not found. "
+                "Create .python-dependency-linter.yaml or configure "
+                "[tool.python-dependency-linter] in pyproject.toml.",
+                err=True,
+            )
+            raise SystemExit(2)
+        root = config_file.resolve().parent
+
+    config = load_config(config_file)
 
     all_violations = []
-    python_files = _find_python_files(root)
+    python_files = _find_python_files(root, config.include, config.exclude)
 
     for file_path in python_files:
         module = _file_to_module(file_path, root)
@@ -74,7 +120,7 @@ def check(config_path: str, project_root: str):
             continue
 
         merged_rule = merge_rules(matching_rules)
-        imports = parse_imports(file_path)
+        imports = parse_imports(file_path, root)
 
         file_violations = []
         for imp in imports:

{python_dependency_linter-0.2.0 → python_dependency_linter-0.4.0}/python_dependency_linter/config.py

@@ -24,6 +24,8 @@ class Rule:
 @dataclass
 class Config:
     rules: list[Rule]
+    include: list[str] | None = None
+    exclude: list[str] | None = None
 
 
 def _parse_allow_deny(data: dict | None) -> AllowDeny | None:
@@ -53,19 +55,56 @@ def _parse_rules(rules_data: list[dict]) -> list[Rule]:
 def _load_yaml(path: Path) -> Config:
     with open(path) as f:
         data = yaml.safe_load(f)
-    return Config(rules=_parse_rules(data["rules"]))
+    return Config(
+        rules=_parse_rules(data["rules"]),
+        include=data.get("include"),
+        exclude=data.get("exclude"),
+    )
 
 
-def _load_pyproject_toml(path: Path) -> Config:
+def _load_toml(path: Path) -> dict:
     try:
         import tomllib
     except ImportError:
         import tomli as tomllib  # type: ignore[no-redef]
 
     with open(path, "rb") as f:
-        data = tomllib.load(f)
+        return tomllib.load(f)
+
+
+def _load_pyproject_toml(path: Path) -> Config:
+    data = _load_toml(path)
     tool_config = data["tool"]["python-dependency-linter"]
-    return Config(rules=_parse_rules(tool_config["rules"]))
+    return Config(
+        rules=_parse_rules(tool_config["rules"]),
+        include=tool_config.get("include"),
+        exclude=tool_config.get("exclude"),
+    )
+
+
+def _has_pdl_section(path: Path) -> bool:
+    """Check if a pyproject.toml contains [tool.python-dependency-linter]."""
+    data = _load_toml(path)
+    return "python-dependency-linter" in data.get("tool", {})
+
+
+_CONFIG_FILENAMES = [".python-dependency-linter.yaml", "pyproject.toml"]
+
+
+def find_config() -> Path | None:
+    """Search upward from cwd for a config file. Returns None if not found."""
+    current = Path.cwd().resolve()
+    while True:
+        for name in _CONFIG_FILENAMES:
+            candidate = current / name
+            if candidate.is_file():
+                if name == "pyproject.toml" and not _has_pdl_section(candidate):
+                    continue
+                return candidate
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
 
 
 def load_config(path: Path) -> Config:

python_dependency_linter-0.4.0/python_dependency_linter/parser.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ImportInfo:
+    module: str
+    lineno: int
+
+
+def _resolve_relative_import(
+    file_path: Path,
+    project_root: Path,
+    level: int,
+    module: str | None,
+) -> str | None:
+    """Resolve a relative import to an absolute module name.
+
+    Returns ``None`` when *level* exceeds the package depth (i.e. the
+    import would escape *project_root*).
+    """
+    relative = file_path.relative_to(project_root)
+    parts = list(relative.with_suffix("").parts)
+    parts = parts[:-1]
+
+    # level=1 means current package, level=2 means parent package, etc.
+    go_up = level - 1
+    if go_up >= len(parts):
+        return None
+
+    base_parts = parts[: len(parts) - go_up]
+    resolved = ".".join(base_parts)
+    if module:
+        resolved = f"{resolved}.{module}" if resolved else module
+    return resolved or None
+
+
+def parse_imports(file_path: Path, project_root: Path) -> list[ImportInfo]:
+    source = file_path.read_text()
+    tree = ast.parse(source, filename=str(file_path))
+
+    imports = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                imports.append(ImportInfo(module=alias.name, lineno=node.lineno))
+        elif isinstance(node, ast.ImportFrom):
+            if node.level and node.level > 0:
+                resolved = _resolve_relative_import(
+                    file_path, project_root, node.level, node.module
+                )
+                if resolved is not None:
+                    imports.append(ImportInfo(module=resolved, lineno=node.lineno))
+            elif node.module is not None:
+                imports.append(ImportInfo(module=node.module, lineno=node.lineno))
+
+    return imports

python_dependency_linter-0.4.0/tests/fixtures/sample_project/contexts/boards/__init__.py

@@ -0,0 +1 @@
+from .domain import models  # noqa: F401