devdoctor-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{devdoctor_cli-0.1.0 → devdoctor_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devdoctor-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Deterministic developer machine and project diagnostic doctor.
 Author: Souran Jash
 License-Expression: MIT
@@ -65,7 +65,7 @@ devdoctor scan
 ```text
 $ devdoctor scan
 
-DevDoctor 0.1.0
+DevDoctor 0.1.1
 Project: Django + PostgreSQL + Docker
 ────────────────────────────
 
@@ -128,7 +128,8 @@ Run with `--verbose` to view the comprehensive breakdown:
 ```text
 $ devdoctor scan --verbose
 
-❌ Pydantic installation problem
+DevDoctor 0.1.1 (Detailed Diagnostic Report)
+────────────────────────────────────────────────────────
 
 PROBLEM:
 Incompatible version of pydantic-core installed for Python runtime.

{devdoctor_cli-0.1.0 → devdoctor_cli-0.1.1}/README.md

@@ -38,7 +38,7 @@ devdoctor scan
 ```text
 $ devdoctor scan
 
-DevDoctor 0.1.0
+DevDoctor 0.1.1
 Project: Django + PostgreSQL + Docker
 ────────────────────────────
 
@@ -101,7 +101,8 @@ Run with `--verbose` to view the comprehensive breakdown:
 ```text
 $ devdoctor scan --verbose
 
-❌ Pydantic installation problem
+DevDoctor 0.1.1 (Detailed Diagnostic Report)
+────────────────────────────────────────────────────────
 
 PROBLEM:
 Incompatible version of pydantic-core installed for Python runtime.

{devdoctor_cli-0.1.0 → devdoctor_cli-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devdoctor-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "Deterministic developer machine and project diagnostic doctor."
 readme = "README.md"
 requires-python = ">=3.10"

{devdoctor_cli-0.1.0 → devdoctor_cli-0.1.1}/src/devdoctor/__init__.py

@@ -1,5 +1,4 @@
-"""DevDoctor: Deterministic developer machine and project diagnostic doctor."""
-
+from devdoctor._version import __version__
 from devdoctor.api import DevDoctor
 from devdoctor.checks.base import Check, check, get_registered_checks, register_check
 from devdoctor.fixer import FixAction, FixPlan, FixResult, Fixer
@@ -15,8 +14,6 @@ from devdoctor.project import detect_project
 from devdoctor.reporter import Reporter
 from devdoctor.scanner import Scanner
 
-__version__ = "0.1.0"
-
 __all__ = [
     "DevDoctor",
     "Diagnostic",

devdoctor_cli-0.1.1/src/devdoctor/_version.py

@@ -0,0 +1,3 @@
+"""Version definition for DevDoctor."""
+
+__version__ = "0.1.1"

{devdoctor_cli-0.1.0 → devdoctor_cli-0.1.1}/src/devdoctor/checks/imports.py

@@ -6,7 +6,7 @@ from typing import List
 
 from devdoctor.checks.base import Check, register_check
 from devdoctor.models import Confidence, Diagnostic, FixAction, ScanContext, Severity
-from devdoctor.utils.ast_imports import find_missing_installed_imports
+from devdoctor.utils.ast_imports import find_missing_installed_imports, get_distribution_name
 
 
 @register_check
@@ -26,22 +26,25 @@ class BrokenImportsCheck(Check):
             except Exception:
                 rel_path = file_path.name
 
+            dist_name = get_distribution_name(mod)
+            pip_cmd = f"pip install {dist_name}"
+
             diagnostics.append(Diagnostic(
                 title=f"Missing module '{mod}'",
                 severity=Severity.ERROR,
                 message=f"Module '{mod}' is imported but not installed in current environment.",
                 why=f"Code in {rel_path} requires '{mod}', but the package is not found in site-packages.",
                 evidence=f"Found in:\n     {rel_path} (line {line_no})",
-                fix=f"Install {mod} via pip:\n     pip install {mod}",
-                command=f"pip install {mod}",
+                fix=f"Install {dist_name} via pip:\n     {pip_cmd}",
+                command=pip_cmd,
                 confidence=Confidence.HIGH,
                 fix_action=FixAction(
-                    description=f"Install {mod}",
-                    command=f"pip install {mod}",
+                    description=f"Install {dist_name}",
+                    command=pip_cmd,
                     safe=False,
                 ),
                 check_id=f"{self.name}_{mod}",
-                metadata={"module": mod, "file": str(rel_path), "line": line_no},
+                metadata={"module": mod, "file": str(rel_path), "line": line_no, "distribution": dist_name},
             ))
 
         return diagnostics

{devdoctor_cli-0.1.0 → devdoctor_cli-0.1.1}/src/devdoctor/cli.py

@@ -9,7 +9,7 @@ from typing import List, Optional
 
 from rich.console import Console
 
-from devdoctor import __version__
+from devdoctor._version import __version__
 from devdoctor.fixer import Fixer
 from devdoctor.project import detect_project
 from devdoctor.reporter import Reporter

{devdoctor_cli-0.1.0 → devdoctor_cli-0.1.1}/src/devdoctor/models.py

@@ -239,7 +239,7 @@ class DiagnosticReport:
 
     def to_dict(self) -> Dict[str, Any]:
         return {
-            "version": "0.1.0",
+            "version": "0.1.1",
             "timestamp": self.timestamp.isoformat(),
             "duration_ms": round(self.duration_ms, 2),
             "score": self.score,

{devdoctor_cli-0.1.0 → devdoctor_cli-0.1.1}/src/devdoctor/reporter.py

@@ -8,6 +8,8 @@ from typing import Optional
 
 from rich.console import Console
 
+from devdoctor._version import __version__
+
 # Ensure UTF-8 output on Windows terminals
 if sys.stdout and hasattr(sys.stdout, "reconfigure"):
     try:
@@ -51,7 +53,7 @@ class Reporter:
             return
 
         # Header
-        self.console.print("[bold cyan]DevDoctor 0.1.0[/bold cyan]")
+        self.console.print(f"[bold cyan]DevDoctor {__version__}[/bold cyan]")
         if report.project_info and report.project_info.summary_stack:
             self.console.print(f"[dim]Project: {report.project_info.summary_stack}[/dim]")
         self.console.print(f"{SYM_DIV}\n")
@@ -101,7 +103,7 @@ class Reporter:
 
     def _render_verbose(self, report: DiagnosticReport) -> None:
         """Render full diagnostic detail with WHY, EVIDENCE, SAFE FIX, COMMAND, and Confidence."""
-        self.console.print("[bold cyan]DevDoctor 0.1.0 (Detailed Diagnostic Report)[/bold cyan]")
+        self.console.print(f"[bold cyan]DevDoctor {__version__} (Detailed Diagnostic Report)[/bold cyan]")
         self.console.print(f"{SYM_DIV * 2}\n")
 
         if report.passed:

{devdoctor_cli-0.1.0 → devdoctor_cli-0.1.1}/src/devdoctor/utils/ast_imports.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import ast
+import importlib.metadata
 import importlib.util
 import os
 import sys
@@ -18,10 +19,80 @@ SYSTEM_ENV_VARS = {
 
 IGNORE_DIRS = {
     ".venv", "venv", "env", ".env_dir", ".git", ".tox", ".pytest_cache",
-    "__pycache__", "node_modules", "dist", "build", ".eggs", ".mypy_cache"
+    "__pycache__", "node_modules", "dist", "build", ".eggs", ".mypy_cache",
+    ".idea", ".vscode", ".ruff_cache", ".coverage", "htmlcov", "site-packages",
 }
 
 
+def is_ignored_dir(path: Path) -> bool:
+    """Check if directory is an ignored directory or a virtual environment."""
+    name = path.name
+    if name.startswith(".") or name in IGNORE_DIRS:
+        return True
+    if (path / "pyvenv.cfg").is_file():
+        return True
+    if (path / "Scripts" / "python.exe").is_file() or (path / "bin" / "python").is_file():
+        return True
+    return False
+
+
+def should_skip_path(path: Path) -> bool:
+    """Check if the path is within an ignored directory or a virtual environment."""
+    for part in path.parts:
+        if part.startswith(".") and part != "." and part != "..":
+            return True
+        if part in IGNORE_DIRS:
+            return True
+    curr = path if path.is_dir() else path.parent
+    while curr and curr != curr.parent:
+        if (curr / "pyvenv.cfg").is_file():
+            return True
+        curr = curr.parent
+    return False
+
+
+def has_python_files(dir_path: Path) -> bool:
+    """Check if dir_path contains at least one Python file directly or in a non-ignored subdirectory."""
+    if not dir_path.is_dir() or is_ignored_dir(dir_path):
+        return False
+
+    # Check immediate files first for performance
+    try:
+        with os.scandir(dir_path) as it:
+            for entry in it:
+                if entry.is_file() and entry.name.endswith((".py", ".pyw", ".pyd", ".so")):
+                    return True
+    except Exception:
+        return False
+
+    # Check subdirectories recursively, pruning ignored folders
+    try:
+        for root, dirs, files in os.walk(dir_path):
+            dirs[:] = [d for d in dirs if not is_ignored_dir(Path(root) / d)]
+            for file in files:
+                if file.endswith((".py", ".pyw", ".pyd", ".so")):
+                    return True
+    except Exception:
+        pass
+
+    return False
+
+
+def is_package_dir(dir_path: Path) -> bool:
+    """Check if a directory is a valid local package (regular with __init__.py or PEP 420 namespace package)."""
+    if not dir_path.is_dir():
+        return False
+    if not dir_path.name.isidentifier():
+        return False
+    if is_ignored_dir(dir_path):
+        return False
+    # Regular package has __init__.py
+    if (dir_path / "__init__.py").is_file():
+        return True
+    # Namespace package contains at least one Python source file
+    return has_python_files(dir_path)
+
+
 @dataclass
 class ImportUsage:
     """Record of a module import in a Python file."""
@@ -40,22 +111,14 @@ class EnvVarUsage:
     is_required: bool  # True if subscript like os.environ['VAR']
 
 
-def should_skip_path(path: Path) -> bool:
-    """Check if the path is within an ignored directory."""
-    for part in path.parts:
-        if part in IGNORE_DIRS:
-            return True
-    return False
-
-
 def collect_python_files(project_path: Path, max_files: int = 500) -> List[Path]:
     """Find Python source files in the project, ignoring virtualenvs and caches."""
     py_files: List[Path] = []
     try:
         for root, dirs, files in os.walk(project_path):
-            dirs[:] = [d for d in dirs if d not in IGNORE_DIRS]
+            dirs[:] = [d for d in dirs if not is_ignored_dir(Path(root) / d)]
             for file in files:
-                if file.endswith(".py"):
+                if file.endswith((".py", ".pyw")):
                     full_path = Path(root) / file
                     py_files.append(full_path)
                     if len(py_files) >= max_files:
@@ -80,6 +143,8 @@ class SourceVisitor(ast.NodeVisitor):
         self.generic_visit(node)
 
     def visit_ImportFrom(self, node: ast.ImportFrom):
+        # node.level > 0 indicates relative imports (e.g. from . import X or from ..core import Y)
+        # Relative imports are project-internal and are never third-party PyPI dependencies.
         if node.level == 0 and node.module:
             top_level = node.module.split(".")[0]
             self.imports.append(ImportUsage(module_name=top_level, file_path=self.file_path, line_number=node.lineno))
@@ -159,18 +224,65 @@ def scan_project_ast(project_path: Path) -> Tuple[List[ImportUsage], List[EnvVar
     return all_imports, all_env_vars
 
 
-def is_local_module(module_name: str, project_path: Path) -> bool:
-    """Check if the module corresponds to a local file or package within the project."""
-    if (project_path / f"{module_name}.py").is_file():
-        return True
-    if (project_path / module_name / "__init__.py").is_file():
-        return True
-    src_dir = project_path / "src"
-    if src_dir.is_dir():
-        if (src_dir / f"{module_name}.py").is_file():
-            return True
-        if (src_dir / module_name / "__init__.py").is_file():
+def is_local_module(
+    module_name: str,
+    project_path: Path,
+    file_path: Optional[Path] = None,
+) -> bool:
+    """Check if the module corresponds to a local file, regular package, or namespace package within the project."""
+    if not module_name or not module_name.isidentifier():
+        return False
+
+    project_root = project_path.resolve()
+
+    # Collect source roots to check
+    source_roots: List[Path] = [project_root]
+
+    # Standard layout directories: src/, lib/
+    for sub in ("src", "lib"):
+        sub_dir = project_root / sub
+        if sub_dir.is_dir() and not is_ignored_dir(sub_dir):
+            source_roots.append(sub_dir)
+
+    # If file_path is given, also check its parent directory and ancestors up to project_root
+    if file_path is not None:
+        try:
+            curr = file_path.resolve().parent
+            while curr != project_root and curr.is_relative_to(project_root):
+                if curr not in source_roots and not is_ignored_dir(curr):
+                    source_roots.append(curr)
+                curr = curr.parent
+        except Exception:
+            pass
+
+    # Check each candidate source root
+    for root in source_roots:
+        # 1. Single-file module: root / module_name.py (or .pyw, .pyd, .so)
+        for ext in (".py", ".pyw", ".pyd", ".so"):
+            mod_file = root / f"{module_name}{ext}"
+            if mod_file.is_file():
+                return True
+
+        # 2. Package directory: root / module_name (with __init__.py or namespace package)
+        pkg_dir = root / module_name
+        if is_package_dir(pkg_dir):
             return True
+
+    # Also check if module_name exists as a module or package inside any top-level source package in project_root or src/
+    for base in (project_root, project_root / "src"):
+        if not base.is_dir():
+            continue
+        try:
+            for entry in base.iterdir():
+                if entry.is_dir() and not is_ignored_dir(entry) and entry.name.isidentifier():
+                    for ext in (".py", ".pyw", ".pyd", ".so"):
+                        if (entry / f"{module_name}{ext}").is_file():
+                            return True
+                    if is_package_dir(entry / module_name):
+                        return True
+        except Exception:
+            pass
+
     return False
 
 
@@ -181,6 +293,51 @@ def is_stdlib_module(module_name: str) -> bool:
     return module_name in sys.builtin_module_names
 
 
+def is_installed_package(module_name: str) -> bool:
+    """Check if a module is installed in the active Python environment."""
+    try:
+        spec = importlib.util.find_spec(module_name)
+        if spec is not None:
+            return True
+    except Exception:
+        pass
+
+    try:
+        dist_map = importlib.metadata.packages_distributions()
+        if module_name in dist_map:
+            return True
+    except Exception:
+        pass
+
+    return False
+
+
+def get_distribution_name(module_name: str) -> str:
+    """Map top-level import name to its standard PyPI distribution name if different."""
+    known_mappings = {
+        "PIL": "pillow",
+        "cv2": "opencv-python",
+        "sklearn": "scikit-learn",
+        "bs4": "beautifulsoup4",
+        "yaml": "PyYAML",
+        "dotenv": "python-dotenv",
+        "dateutil": "python-dateutil",
+        "serial": "pyserial",
+        "jwt": "PyJWT",
+        "jose": "python-jose",
+        "magic": "python-magic",
+        "fitz": "PyMuPDF",
+        "docx": "python-docx",
+        "pptx": "python-pptx",
+        "git": "GitPython",
+        "github": "PyGithub",
+        "websocket": "websocket-client",
+        "OpenGL": "PyOpenGL",
+        "attr": "attrs",
+    }
+    return known_mappings.get(module_name, module_name)
+
+
 def find_missing_installed_imports(project_path: Path) -> List[Tuple[str, Path, int]]:
     """Identify third-party imports in project code that are not installed in the active environment."""
     imports, _ = scan_project_ast(project_path)
@@ -191,15 +348,11 @@ def find_missing_installed_imports(project_path: Path) -> List[Tuple[str, Path,
         mod = item.module_name
         if mod in checked:
             continue
-        if is_stdlib_module(mod) or is_local_module(mod, project_path):
+        if is_stdlib_module(mod) or is_local_module(mod, project_path, item.file_path):
             continue
 
         checked.add(mod)
-        try:
-            spec = importlib.util.find_spec(mod)
-            if spec is None:
-                missing.append((mod, item.file_path, item.line_number))
-        except Exception:
+        if not is_installed_package(mod):
             missing.append((mod, item.file_path, item.line_number))
 
     return missing

{devdoctor_cli-0.1.0 → devdoctor_cli-0.1.1}/src/devdoctor_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devdoctor-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Deterministic developer machine and project diagnostic doctor.
 Author: Souran Jash
 License-Expression: MIT
@@ -65,7 +65,7 @@ devdoctor scan
 ```text
 $ devdoctor scan
 
-DevDoctor 0.1.0
+DevDoctor 0.1.1
 Project: Django + PostgreSQL + Docker
 ────────────────────────────
 
@@ -128,7 +128,8 @@ Run with `--verbose` to view the comprehensive breakdown:
 ```text
 $ devdoctor scan --verbose
 
-❌ Pydantic installation problem
+DevDoctor 0.1.1 (Detailed Diagnostic Report)
+────────────────────────────────────────────────────────
 
 PROBLEM:
 Incompatible version of pydantic-core installed for Python runtime.

{devdoctor_cli-0.1.0 → devdoctor_cli-0.1.1}/src/devdoctor_cli.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 src/devdoctor/__init__.py
 src/devdoctor/__main__.py
+src/devdoctor/_version.py
 src/devdoctor/api.py
 src/devdoctor/cli.py
 src/devdoctor/fixer.py
@@ -42,6 +43,7 @@ tests/test_checks.py
 tests/test_cli.py
 tests/test_env_and_ast.py
 tests/test_fixer.py
+tests/test_import_checker.py
 tests/test_models.py
 tests/test_plugins_api.py
 tests/test_project.py

{devdoctor_cli-0.1.0 → devdoctor_cli-0.1.1}/tests/test_cli.py

@@ -13,7 +13,7 @@ def test_cli_scan_json(tmp_path: Path, capsys):
     ret = main(["scan", str(tmp_path), "--json"])
     assert ret in (0, 1)
     captured = capsys.readouterr()
-    assert '"version": "0.1.0"' in captured.out
+    assert '"version": "0.1.1"' in captured.out
     assert '"score":' in captured.out
 
 

devdoctor_cli-0.1.1/tests/test_import_checker.py

@@ -0,0 +1,191 @@
+"""Regression tests for DevDoctor's import detection and namespace package handling."""
+
+from pathlib import Path
+from devdoctor.checks.imports import BrokenImportsCheck
+from devdoctor.models import ScanContext, Severity
+from devdoctor.utils.ast_imports import (
+    find_missing_installed_imports,
+    get_distribution_name,
+    is_installed_package,
+    is_local_module,
+)
+
+
+def test_a_local_namespace_packages(tmp_path: Path):
+    """Test A — Local namespace packages:
+    Create a project with core/, ui/, and utils/ without __init__.py.
+    Verify that importing these local namespace packages is NOT reported as missing dependencies.
+    """
+    # Create structure:
+    # project/
+    # ├── app.py
+    # ├── core/
+    # │   └── example.py
+    # ├── ui/
+    # │   └── example.py
+    # └── utils/
+    #     └── example.py
+    (tmp_path / "core").mkdir()
+    (tmp_path / "core" / "example.py").write_text("def run_core(): pass\n", encoding="utf-8")
+
+    (tmp_path / "ui").mkdir()
+    (tmp_path / "ui" / "example.py").write_text("def run_ui(): pass\n", encoding="utf-8")
+
+    (tmp_path / "utils").mkdir()
+    (tmp_path / "utils" / "example.py").write_text("def run_utils(): pass\n", encoding="utf-8")
+
+    app_py = tmp_path / "app.py"
+    app_py.write_text(
+        """
+import core
+from core import example as core_example
+import ui
+from ui.example import run_ui
+import utils
+from utils import example as utils_example
+""",
+        encoding="utf-8",
+    )
+
+    chk = BrokenImportsCheck()
+    ctx = ScanContext(project_path=tmp_path)
+    diagnostics = chk.run(ctx)
+
+    # None of core, ui, utils should be flagged as missing
+    flagged = [d.metadata.get("module") for d in diagnostics]
+    assert "core" not in flagged
+    assert "ui" not in flagged
+    assert "utils" not in flagged
+    assert len(diagnostics) == 0
+
+
+def test_b_local_regular_packages(tmp_path: Path):
+    """Test B — Local regular packages:
+    Verify that local packages with __init__.py are recognized as local packages.
+    """
+    pkg_dir = tmp_path / "mypackage"
+    pkg_dir.mkdir()
+    (pkg_dir / "__init__.py").write_text("# regular package\n", encoding="utf-8")
+    (pkg_dir / "service.py").write_text("def serve(): pass\n", encoding="utf-8")
+
+    (tmp_path / "main.py").write_text("import mypackage\nfrom mypackage import service\n", encoding="utf-8")
+
+    chk = BrokenImportsCheck()
+    ctx = ScanContext(project_path=tmp_path)
+    diagnostics = chk.run(ctx)
+
+    flagged = [d.metadata.get("module") for d in diagnostics]
+    assert "mypackage" not in flagged
+    assert len(diagnostics) == 0
+
+
+def test_c_genuine_missing_dependency(tmp_path: Path):
+    """Test C — Genuine missing dependency:
+    Import a deliberately nonexistent third-party module and verify DevDoctor reports it appropriately.
+    """
+    (tmp_path / "app.py").write_text("import deliberately_nonexistent_pypi_pkg_98765\n", encoding="utf-8")
+
+    chk = BrokenImportsCheck()
+    ctx = ScanContext(project_path=tmp_path)
+    diagnostics = chk.run(ctx)
+
+    assert len(diagnostics) == 1
+    diag = diagnostics[0]
+    assert diag.severity == Severity.ERROR
+    assert "deliberately_nonexistent_pypi_pkg_98765" in diag.title
+    assert "pip install deliberately_nonexistent_pypi_pkg_98765" in diag.command
+
+
+def test_d_installed_third_party_dependency(tmp_path: Path):
+    """Test D — Installed third-party dependency:
+    Verify that a dependency installed in the active environment (e.g. rich, packaging) is not reported as missing.
+    """
+    (tmp_path / "app.py").write_text("import rich\nimport packaging\n", encoding="utf-8")
+
+    chk = BrokenImportsCheck()
+    ctx = ScanContext(project_path=tmp_path)
+    diagnostics = chk.run(ctx)
+
+    assert len(diagnostics) == 0
+
+
+def test_e_nested_local_imports(tmp_path: Path):
+    """Test E — Nested local imports:
+    Verify that modules and subpackages in nested project directories are handled correctly.
+    """
+    # project/
+    # ├── app.py
+    # └── core/
+    #     ├── tracker.py
+    #     └── detector/
+    #         └── model.py
+    core_dir = tmp_path / "core"
+    detector_dir = core_dir / "detector"
+    detector_dir.mkdir(parents=True)
+
+    (detector_dir / "model.py").write_text("class Model: pass\n", encoding="utf-8")
+    (core_dir / "tracker.py").write_text("from detector.model import Model\n", encoding="utf-8")
+    (tmp_path / "app.py").write_text("from core.detector import model\nimport core.tracker\n", encoding="utf-8")
+
+    chk = BrokenImportsCheck()
+    ctx = ScanContext(project_path=tmp_path)
+    diagnostics = chk.run(ctx)
+
+    flagged = [d.metadata.get("module") for d in diagnostics]
+    assert "core" not in flagged
+    assert "detector" not in flagged
+    assert len(diagnostics) == 0
+
+
+def test_f_src_layout(tmp_path: Path):
+    """Test F — src/ layout:
+    Verify that modules under the project's src/ directory are recognized.
+    """
+    # project/
+    # ├── pyproject.toml
+    # └── src/
+    #     └── myproject/
+    #         ├── engine.py
+    #         └── worker.py
+    src_pkg = tmp_path / "src" / "myproject"
+    src_pkg.mkdir(parents=True)
+
+    (src_pkg / "engine.py").write_text("def start_engine(): pass\n", encoding="utf-8")
+    (src_pkg / "worker.py").write_text("from myproject.engine import start_engine\n", encoding="utf-8")
+    (tmp_path / "main.py").write_text("import myproject.worker\n", encoding="utf-8")
+
+    chk = BrokenImportsCheck()
+    ctx = ScanContext(project_path=tmp_path)
+    diagnostics = chk.run(ctx)
+
+    flagged = [d.metadata.get("module") for d in diagnostics]
+    assert "myproject" not in flagged
+    assert len(diagnostics) == 0
+
+
+def test_arbitrary_directory_not_treated_as_package(tmp_path: Path):
+    """Verify that arbitrary non-Python directories (e.g. templates/ with only html)
+    are NOT treated as local packages.
+    """
+    templates_dir = tmp_path / "templates"
+    templates_dir.mkdir()
+    (templates_dir / "index.html").write_text("<h1>Hello</h1>\n", encoding="utf-8")
+
+    (tmp_path / "app.py").write_text("import templates\n", encoding="utf-8")
+
+    # templates should not be considered a local package because it contains no Python files
+    assert not is_local_module("templates", tmp_path)
+
+    chk = BrokenImportsCheck()
+    ctx = ScanContext(project_path=tmp_path)
+    diagnostics = chk.run(ctx)
+    assert any("templates" in d.title for d in diagnostics)
+
+
+def test_distribution_name_mapping():
+    """Verify that known import names map to their correct PyPI distribution names."""
+    assert get_distribution_name("PIL") == "pillow"
+    assert get_distribution_name("cv2") == "opencv-python"
+    assert get_distribution_name("yaml") == "PyYAML"
+    assert get_distribution_name("sklearn") == "scikit-learn"
+    assert get_distribution_name("unknown_pkg") == "unknown_pkg"