troml-dev-status 0.1.0__py3-none-any.whl

troml_dev_status/__about__.py

@@ -0,0 +1,17 @@
+"""Metadata for troml_dev_status."""
+
+__all__ = [
+    "__title__",
+    "__version__",
+    "__description__",
+    "__readme__",
+    "__requires_python__",
+    "__status__",
+]
+
+__title__ = "troml-dev-status"
+__version__ = "0.1.0"
+__description__ = "Objectively infer PyPI Development Status classifiers from code and release artifacts."
+__readme__ = "README.md"
+__requires_python__ = ">=3.9"
+__status__ = "1 - Planning"

troml_dev_status/__main__.py

@@ -0,0 +1,6 @@
+# troml_dev_status/__main__.py
+
+from troml_dev_status.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

troml_dev_status/analysis/bureaucracy.py

@@ -0,0 +1,375 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Iterable, Iterator, List, Mapping, Pattern, Set, Tuple
+
+import pathspec
+
+# ---- categories we recognize -------------------------------------------------
+
+# Keep these stable so users can filter reliably.
+CATEGORIES: Tuple[str, ...] = (
+    "contributing",  # how to contribute
+    "code_of_conduct",
+    "security",
+    "governance",
+    "support",
+    "funding",
+    "legal",  # license/notice/trademark
+    "citation",  # research citation formats
+    "templates",  # issue/PR templates
+    "release_notes",  # changelog/news/history
+    "roadmap",
+    "style",  # style guides / testing guides
+    "meta",  # repo meta like CODEOWNERS, MAINTAINERS, AUTHORS
+    "automation",  # config for bots/tools that shape contribution process
+)
+
+# Extensions to consider, including "no extension" via empty string.
+DEFAULT_EXTS: Tuple[str, ...] = ("", ".md", ".markdown", ".rst", ".txt", ".adoc")
+
+
+# Utility to build filename variants like "code-of-conduct", "code_of_conduct", "code of conduct"
+def _variants(base: str) -> List[str]:
+    parts = re.split(r"[\s_\-\.\+]+", base.strip())
+    if not parts:
+        return []
+    joins = ["-".join(parts), "_".join(parts), " ".join(parts), "".join(parts)]
+    return list(dict.fromkeys([base] + joins))  # dedupe, preserve order
+
+
+# Spec for one pattern family
+@dataclass(frozen=True)
+class PatternSpec:
+    # Match against full POSIX path (e.g., ".github/FUNDING.yml") OR filename
+    # Provide either filename variants or explicit path regexes.
+    filename_bases: Tuple[str, ...] = ()
+    path_regexes: Tuple[str, ...] = ()
+    exts: Tuple[str, ...] = DEFAULT_EXTS
+
+    def compile(self) -> Tuple[List[Pattern[str]], List[Pattern[str]]]:
+        # Build case-insensitive regexes for filenames and full paths.
+        fname_regexes: List[Pattern[str]] = []
+        path_regexes: List[Pattern[str]] = []
+
+        # Filename patterns: cover hyphen/underscore/space/concat variants + extensions.
+        for base in self.filename_bases:
+            for name_variant in _variants(base):
+                # Allow optional extension from allowed set.
+                # Example: r"^code[-_ ]?of[-_ ]?conduct(?:\.(md|rst|txt|adoc|markdown))?$" but faster to inject list
+                if self.exts and any(self.exts):
+                    exts_pattern = "|".join(
+                        re.escape(e.lstrip(".")) for e in self.exts if e
+                    )
+                    # Either no extension or one of the listed (if "" present)
+                    allow_no_ext = "" in self.exts
+                    if exts_pattern:
+                        if allow_no_ext:
+                            ext_regex = rf"(?:\.(?:{exts_pattern}))?"
+                        else:
+                            ext_regex = rf"\.(?:{exts_pattern})"
+                    else:
+                        ext_regex = ""  # only no-ext
+                else:
+                    ext_regex = ""  # only no-ext
+                rx = re.compile(
+                    rf"^{re.escape(name_variant)}{ext_regex}$", re.IGNORECASE
+                )
+                fname_regexes.append(rx)
+
+        # Explicit path regexes (already regex, we just compile case-insensitively).
+        for pr in self.path_regexes:
+            path_regexes.append(re.compile(pr, re.IGNORECASE))
+
+        return fname_regexes, path_regexes
+
+
+# Master registry mapping categories to one or more PatternSpecs.
+PATTERNS: Mapping[str, Tuple[PatternSpec, ...]] = {
+    "contributing": (PatternSpec(filename_bases=("contributing", "contribute")),),
+    "code_of_conduct": (
+        PatternSpec(
+            filename_bases=("code_of_conduct", "code-of-conduct", "code of conduct")
+        ),
+    ),
+    "security": (PatternSpec(filename_bases=("security", "security policy")),),
+    "governance": (PatternSpec(filename_bases=("governance", "governance policy")),),
+    "support": (PatternSpec(filename_bases=("support", "getting help")),),
+    "funding": (
+        # Common: .github/FUNDING.yml; also accept FUNDING.* elsewhere
+        PatternSpec(
+            filename_bases=("funding",),
+            path_regexes=(r"/\.github/(?:.*/)?funding\.ya?ml$",),
+            exts=("", ".yml", ".yaml", ".md", ".rst", ".txt"),
+        ),
+    ),
+    "legal": (
+        PatternSpec(filename_bases=("license", "licence")),
+        PatternSpec(filename_bases=("notice", "notices")),
+        PatternSpec(filename_bases=("patent", "patents", "trademark", "copyright")),
+    ),
+    "citation": (
+        PatternSpec(filename_bases=("citation",), exts=("", ".cff", ".md", ".txt")),
+        PatternSpec(path_regexes=(r"/citation\.cff$",)),
+    ),
+    "templates": (
+        # Issue/PR templates in .github or root
+        PatternSpec(filename_bases=("pull_request_template", "pr_template")),
+        PatternSpec(filename_bases=("issue_template",)),
+        PatternSpec(
+            path_regexes=(r"/\.github/(?:.*/)?pull_request_template\.(?:md|rst|txt)$",)
+        ),
+        PatternSpec(
+            path_regexes=(
+                r"/\.github/(?:.*/)?issue_template(?:s)?/.*\.(?:md|rst|txt)$",
+            )
+        ),
+    ),
+    "release_notes": (
+        PatternSpec(
+            filename_bases=("changelog", "changes", "history", "news", "release_notes")
+        ),
+    ),
+    "roadmap": (PatternSpec(filename_bases=("roadmap",)),),
+    "style": (
+        PatternSpec(
+            filename_bases=(
+                "styleguide",
+                "style guide",
+                "style",
+                "testing",
+                "test guide",
+            )
+        ),
+    ),
+    "meta": (
+        PatternSpec(filename_bases=("authors", "maintainers", "contributors")),
+        PatternSpec(
+            filename_bases=("codeowners",), exts=("",)
+        ),  # CODEOWNERS usually no ext
+        PatternSpec(path_regexes=(r"/\.github/CODEOWNERS$",)),
+    ),
+    "automation": (
+        # Things that strongly influence contribution/maintenance process
+        PatternSpec(filename_bases=(".editorconfig",), exts=("",)),
+        PatternSpec(filename_bases=(".gitattributes",), exts=("",)),
+        PatternSpec(filename_bases=(".pre-commit-config",), exts=("", ".yaml", ".yml")),
+        PatternSpec(filename_bases=("dependabot",), exts=(".yml", ".yaml")),
+        PatternSpec(
+            filename_bases=("renovate",), exts=(".json", ".json5", ".yaml", ".yml")
+        ),
+        PatternSpec(
+            path_regexes=(r"/\.github/dependabot\.ya?ml$", r"/renovate\.json5?$")
+        ),
+        # Python tooling that often encodes “policy” for contributions
+        PatternSpec(filename_bases=("pyproject",), exts=(".toml",)),
+        PatternSpec(filename_bases=("setup",), exts=(".cfg",)),
+        PatternSpec(filename_bases=("mypy",), exts=(".ini", ".cfg")),
+        PatternSpec(filename_bases=("ruff",), exts=(".toml", ".cfg")),
+    ),
+}
+
+# ---- core scanning helpers ---------------------------------------------------
+
+
+def _compile_registry(
+    include_categories: Iterable[str] | None,
+    exclude_categories: Iterable[str] | None,
+) -> Dict[str, Tuple[List[Pattern[str]], List[Pattern[str]]]]:
+    include: Set[str] = set(include_categories or CATEGORIES)
+    exclude: Set[str] = set(exclude_categories or ())
+    active = sorted((include - exclude) & set(CATEGORIES))
+
+    compiled: Dict[str, Tuple[List[Pattern[str]], List[Pattern[str]]]] = {}
+    for cat in active:
+        fname_list: List[Pattern[str]] = []
+        path_list: List[Pattern[str]] = []
+        for spec in PATTERNS.get(cat, ()):
+            f, p = spec.compile()
+            fname_list.extend(f)
+            path_list.extend(p)
+        compiled[cat] = (fname_list, path_list)
+    return compiled
+
+
+def _match_category(
+    cat: str,
+    compiled: Mapping[str, Tuple[List[Pattern[str]], List[Pattern[str]]]],
+    path: Path,
+) -> bool:
+    fname = path.name
+    posix = path.as_posix()
+    fname_regexes, path_regexes = compiled[cat]
+    return any(rx.search(fname) for rx in fname_regexes) or any(
+        rx.search(posix) for rx in path_regexes
+    )
+
+
+def scan_bureaucracy(
+    repo_path: Path,
+    include_categories: Iterable[str] | None = None,
+    exclude_categories: Iterable[str] | None = None,
+    follow_symlinks: bool = False,
+) -> Dict[str, List[Path]]:
+    """
+    Return a mapping of category -> list of Paths found.
+
+    - Case-insensitive filename matching with multiple stylistic variants.
+    - Matches also on full POSIX path for special locations (e.g., .github/FUNDING.yml).
+    - Deduplicates paths per category and overall (no duplicates across categories for the same file).
+      (If a file matches multiple categories, it is assigned to the first category in CATEGORIES order.)
+    """
+    # compiled = _compile_registry(include_categories, exclude_categories)
+    # found_by_cat: MutableMapping[str, List[Path]] = {cat: [] for cat in compiled.keys()}
+    # seen: Set[Path] = set()
+    #
+    # # rglob all files (not directories); filter with our compiled patterns.
+    # for p in repo_path.rglob("*"):
+    #     try:
+    #         is_file = p.is_file() if not follow_symlinks else p.is_file() or p.is_symlink()
+    #     except OSError:
+    #         continue  # permissions/broken links
+    #     if not is_file:
+    #         continue
+    #
+    #     # Assign to first matching category in our canonical category order
+    #     for cat in (c for c in CATEGORIES if c in compiled):
+    #         if _match_category(cat, compiled, p):
+    #             if p not in seen:
+    #                 found_by_cat[cat].append(p)
+    #                 seen.add(p)
+    #             break
+    # Sort paths within each category (stable, user friendly)
+    # for cat in found_by_cat:
+    #     found_by_cat[cat].sort(key=lambda x: x.as_posix().lower())
+    #
+    # return dict(found_by_cat)
+
+    compiled = _compile_registry(include_categories, exclude_categories)
+    found_by_cat: dict[str, list[Path]] = {cat: [] for cat in compiled}
+    seen: set[Path] = set()
+
+    for p in iter_repo_files(repo_path, follow_symlinks=follow_symlinks):
+        for cat in (c for c in CATEGORIES if c in compiled):
+            if _match_category(cat, compiled, p):
+                if p not in seen:
+                    found_by_cat[cat].append(p)
+                    seen.add(p)
+                break
+
+    # sort results
+    for cat in found_by_cat:
+        found_by_cat[cat].sort(key=lambda x: x.as_posix().lower())
+    return found_by_cat
+
+
+# ---- public APIs -------------------------------------------------------------
+
+
+def get_bureaucracy_files(
+    repo_path: Path,
+    categories: Iterable[str] | None = None,
+    exclude_categories: Iterable[str] | None = None,
+) -> List[Path]:
+    """
+    Drop-in replacement for your original function but expansive:
+    returns a flat, deduped list of matching files.
+
+    Args:
+        repo_path: root of the repo.
+        categories: include only these categories (default: all known).
+        exclude_categories: skip these categories.
+    """
+    mapping = scan_bureaucracy(
+        repo_path, include_categories=categories, exclude_categories=exclude_categories
+    )
+    # Preserve deterministic order: category order then path order.
+    ordered: List[Path] = []
+    for cat in CATEGORIES:
+        if cat in mapping:
+            ordered.extend(mapping[cat])
+    print(ordered)
+    return ordered
+
+
+def summarize_bureaucracy(
+    repo_path: Path,
+    categories: Iterable[str] | None = None,
+    exclude_categories: Iterable[str] | None = None,
+) -> Dict[str, int]:
+    """
+    Convenience: category -> count.
+    """
+    mapping = scan_bureaucracy(
+        repo_path, include_categories=categories, exclude_categories=exclude_categories
+    )
+    return {k: len(v) for k, v in mapping.items()}
+
+
+# --- utility: load .gitignore -----------------------------------------------
+
+
+def load_gitignore(repo_path: Path) -> pathspec.PathSpec | None:
+    gitignore = repo_path / ".gitignore"
+    if not gitignore.is_file():
+        return None
+    spec = pathspec.PathSpec.from_lines(
+        "gitwildmatch", gitignore.read_text().splitlines()
+    )
+    return spec
+
+
+# --- utility: walk with exclusions ------------------------------------------
+
+
+def iter_repo_files(repo_path: Path, follow_symlinks: bool = False) -> Iterator[Path]:
+    """
+    Yield all files in repo_path, excluding:
+      - .git, .venv, venv, node_modules, __pycache__, etc.
+      - Anything ignored by .gitignore (if present).
+    """
+    skip_dirs: Set[str] = {
+        ".git",
+        ".hg",
+        ".svn",
+        ".venv",
+        "venv",
+        "__pycache__",
+        "node_modules",
+        ".mypy_cache",
+    }
+
+    gitignore_spec = load_gitignore(repo_path)
+
+    for path in repo_path.rglob("*"):
+        # Cheap directory pruning
+        parts = set(path.parts)
+        if parts & skip_dirs:
+            continue
+
+        # Only consider files
+        try:
+            if not (path.is_file() or (follow_symlinks and path.is_symlink())):
+                continue
+        except OSError:
+            continue
+
+        # Respect .gitignore
+        if gitignore_spec:
+            rel = str(path.relative_to(repo_path))
+            if gitignore_spec.match_file(rel):
+                continue
+
+        yield path
+
+
+# ---- quick extension guide ---------------------------------------------------
+# To add a new doc kind:
+# 1) Pick a category (or add a new one to CATEGORIES).
+# 2) Add a PatternSpec to PATTERNS[category] with `filename_bases` and/or `path_regexes`.
+#    - filename_bases are human names; variants (-/_/space/concat) are generated automatically.
+#    - exts controls which extensions are accepted (include "" to allow no extension).
+#    - path_regexes are matched against full POSIX path (e.g., r"/\.github/somefile\.yml$").
+# 3) Done. The scanner will include it automatically.

troml_dev_status/analysis/filesystem.py

@@ -0,0 +1,174 @@
+# troml_dev_status/analysis/filesystem.py
+
+from __future__ import annotations
+
+import ast
+
+# Use tomllib for Python 3.11+, fallback to tomli for older versions
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib  # type: ignore[no-redef,import-not-found]
+
+from pathlib import Path
+
+import yaml
+
+
+def get_project_name(repo_path: Path) -> str | None:
+    """Parses pyproject.toml to find the project name."""
+    toml_path = repo_path / "pyproject.toml"
+    if not toml_path.exists():
+        return None
+    try:
+        with toml_path.open("rb") as f:
+            data = tomllib.load(f)
+        return data.get("project", {}).get("name")
+    except tomllib.TOMLDecodeError:
+        return None
+
+
+def get_analysis_mode(repo_path: Path) -> str:
+    """
+    Parses pyproject.toml to find the analysis mode from [tool.troml-dev-status].
+    Defaults to 'library' if not specified or invalid.
+    """
+    toml_path = repo_path / "pyproject.toml"
+    if not toml_path.exists():
+        return "library"  # Default if no pyproject.toml
+    try:
+        with toml_path.open("rb") as f:
+            data = tomllib.load(f)
+        # Look in [tool.troml-dev-status].mode
+        tool_config = data.get("tool", {}).get("troml-dev-status", {})
+        mode = tool_config.get("mode", "library")
+        if mode not in ["library", "application"]:
+            return "library"  # Fallback for invalid value
+        return mode
+    except tomllib.TOMLDecodeError:
+        return "library"  # Default on parse error
+
+
+def get_project_dependencies(repo_path: Path) -> list[str] | None:
+    """Parses pyproject.toml to get the list of runtime dependencies."""
+    toml_path = repo_path / "pyproject.toml"
+    if not toml_path.exists():
+        return None
+    try:
+        with toml_path.open("rb") as f:
+            data = tomllib.load(f)
+        # PEP 621 specifies dependencies are in [project].dependencies
+        return data.get("project", {}).get("dependencies")
+    except tomllib.TOMLDecodeError:
+        return None
+
+
+def find_src_dir(repo_path: Path) -> Path | None:
+    """Finds the primary source directory (e.g., 'src/', or the package dir)."""
+    if (repo_path / "src").is_dir():
+        return repo_path / "src"
+
+    name = get_project_name(repo_path)
+    if name and (repo_path / name).is_dir():
+        return repo_path / name
+    if name and (repo_path / name.replace("-", "_")).is_dir():
+        return repo_path / name.replace("-", "_")
+    return None
+
+
+def count_test_files(repo_path: Path) -> int:
+    """Counts files matching test patterns."""
+    total = 0
+    for dir_name in ["test", "tests"]:
+        tests_dir = repo_path / dir_name
+        if not tests_dir.is_dir():
+            continue
+        found = len(list(tests_dir.glob("**/test_*.py"))) + len(
+            list(tests_dir.glob("**/*_test.py"))
+        )
+        total += found
+    return total
+
+
+def count_source_modules(src_path: Path) -> int:
+    """Counts non-__init__.py Python modules in the source directory."""
+    if not src_path or not src_path.is_dir():
+        return 0
+    return sum(
+        1 for f in src_path.rglob("*.py") if f.is_file() and f.name != "__init__.py"
+    )
+
+
+def get_ci_config_files(repo_path: Path) -> list[Path]:
+    """Finds common CI configuration files."""
+    patterns = [".github/workflows/*.yml", ".github/workflows/*.yaml", ".gitlab-ci.yml"]
+    files = []
+    for pattern in patterns:
+        files.extend(list(repo_path.glob(pattern)))
+    return files
+
+
+def has_multi_python_in_ci(ci_files: list[Path]) -> bool:
+    """A simple check to see if CI files mention multiple Python versions."""
+    py_versions = set()
+    for file_path in ci_files:
+        try:
+            with file_path.open("r", encoding="utf-8") as f:
+                content = f.read()
+                # Simple string search, not a full parse. Good enough for an objective signal.
+                if "3.9" in content:
+                    py_versions.add("3.9")
+                if "3.10" in content:
+                    py_versions.add("3.10")
+                if "3.11" in content:
+                    py_versions.add("3.11")
+                if "3.12" in content:
+                    py_versions.add("3.12")
+                if "3.13" in content:
+                    py_versions.add("3.13")
+        except (IOError, yaml.YAMLError):
+            continue
+    return len(py_versions) >= 2
+
+
+def analyze_type_hint_coverage(src_path: Path) -> tuple[float, int]:
+    """
+    Calculates the percentage of public functions/methods with type hints.
+    Returns (coverage_percentage, total_public_symbols).
+    """
+    if not src_path or not src_path.is_dir():
+        return 0.0, 0
+
+    total_symbols = 0
+    annotated_symbols = 0
+
+    for py_file in src_path.rglob("*.py"):
+        try:
+            with py_file.open("r", encoding="utf-8") as f:
+                tree = ast.parse(f.read(), filename=str(py_file))
+        except (SyntaxError, UnicodeDecodeError):
+            continue
+
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                # Is it public? (not starting with _)
+                if not node.name.startswith("_"):
+                    total_symbols += 1
+                    # Is it annotated? (return annotation is sufficient)
+                    if node.returns is not None:
+                        annotated_symbols += 1
+
+    if total_symbols == 0:
+        return 0.0, 0
+
+    coverage = (annotated_symbols / total_symbols) * 100
+    return coverage, total_symbols
+
+
+def get_bureaucracy_files(repo_path: Path):
+    # could be in any case, could be with or without extension, could
+    patterns = ["security.md", "contributing.md", "code_of_conduct.md"]
+    files = []
+    for pattern in patterns:
+        files.extend(list(repo_path.glob(pattern)))
+    return files

troml_dev_status/analysis/git.py

@@ -0,0 +1,58 @@
+# troml_dev_status/analysis/git.py
+from __future__ import annotations
+
+import subprocess  # nosec
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def _run_git_command(cwd: Path, *args: str) -> str | None:
+    """Helper to run a git command and return its output."""
+    try:
+        result = subprocess.run(  # nosec
+            ["git", "-C", str(cwd), *args],
+            capture_output=True,
+            text=True,
+            check=True,
+            encoding="utf-8",
+        )
+        return result.stdout.strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+
+def get_latest_commit_date(repo_path: Path, sub_path: str = "src") -> datetime | None:
+    """Finds the timestamp of the last commit to touch a specific subdirectory."""
+    path_spec = (repo_path / sub_path).relative_to(repo_path)
+    output = _run_git_command(
+        repo_path, "log", "-1", "--format=%ct", "--", str(path_spec)
+    )
+    if output and output.isdigit():
+        return datetime.fromtimestamp(int(output), tz=timezone.utc)
+    return None
+
+
+def is_tag_signed(repo_path: Path, tag_name: str) -> bool:
+    """Checks if a given Git tag is GPG signed and valid."""
+    # `git tag -v` returns 0 if signed and valid, non-zero otherwise.
+    # We capture stderr to prevent it from printing to the console on failure.
+    try:
+        subprocess.run(  # nosec
+            ["git", "-C", str(repo_path), "tag", "-v", tag_name],
+            check=True,
+            capture_output=True,
+        )
+        return True
+    except subprocess.CalledProcessError:
+        return False
+
+
+def get_tags_by_date(repo_path: Path) -> list[str]:
+    """Returns a list of all tags, sorted by date (newest first)."""
+    output = _run_git_command(repo_path, "tag", "--sort=-creatordate")
+    return output.splitlines() if output else []
+
+
+def get_file_content_at_tag(repo_path: Path, tag: str, file_path: str) -> str | None:
+    """Retrieves the content of a file at a specific Git tag."""
+    return _run_git_command(repo_path, "show", f"{tag}:{file_path}")

troml_dev_status/analysis/pypi.py

@@ -0,0 +1,32 @@
+# troml_dev_status/analysis/pypi.py
+
+from __future__ import annotations
+
+import httpx
+from packaging.version import InvalidVersion, Version
+
+
+def get_project_data(project_name: str) -> dict | None:
+    """Fetches the full JSON metadata for a project from PyPI."""
+    url = f"https://pypi.org/pypi/{project_name}/json"
+    try:
+        with httpx.Client() as client:
+            response = client.get(url, follow_redirects=True)
+            if response.status_code == 404:
+                return None
+            response.raise_for_status()
+            return response.json()
+    except httpx.RequestError:
+        # Handle network-related errors
+        return None
+
+
+def get_sorted_versions(pypi_data: dict) -> list[Version]:
+    """Extracts, validates, and sorts all release versions from PyPI data."""
+    versions = []
+    for v_str in pypi_data.get("releases", {}):
+        try:
+            versions.append(Version(v_str))
+        except InvalidVersion:
+            continue  # Ignore invalid versions
+    return sorted(versions, reverse=True)