project-detector

Project Detector Skill

Intelligent detection of project types, build tools, test frameworks, and CI requirements. Used by /craft:ci:detect and related commands.

Detection Priority

Detection runs in priority order (first match wins for primary type):

Detection Algorithm

from pathlib import Path
from dataclasses import dataclass
from typing import Optional

@dataclass
class ProjectInfo:
    """Detected project information."""
    type: str              # Primary type (python, node, r, etc.)
    variant: str           # Specific variant (uv, poetry, npm, etc.)
    test_framework: str    # pytest, jest, testthat, etc.
    build_tool: str        # uv, npm, cargo, etc.
    ci_template: str       # Recommended CI template
    python_versions: list  # For Python projects
    node_versions: list    # For Node projects
    has_docs: bool         # Has documentation setup
    has_ci: bool           # Already has CI configured

DETECTORS = [
    # (type, variant, required_files, optional_files)
    # Priority 1-5: Specialized/hybrid projects
    ("plugin", "claude", [".claude-plugin/plugin.json"], []),
    ("mcp", "server", ["package.json"], []),  # Check for mcp in name/deps
    ("tauri", "app", ["src-tauri/tauri.conf.json"], ["src-tauri/Cargo.toml"]),
    ("swift", "package", ["Package.swift"], ["Sources/"]),
    ("swift", "xcode", [], []),  # Special: glob for *.xcodeproj
    # Priority 6-7: R ecosystem
    ("r", "package", ["DESCRIPTION", "NAMESPACE"], ["R/", "tests/"]),
    ("r", "quarto", ["_quarto.yml"], ["*.qmd"]),
    # Priority 8-10: Python ecosystem
    ("python", "uv", ["pyproject.toml", "uv.lock"], ["src/"]),
    ("python", "poetry", ["pyproject.toml", "poetry.lock"], ["src/"]),
    ("python", "pip", ["pyproject.toml"], ["requirements.txt"]),
    ("python", "setuptools", ["setup.py"], ["setup.cfg"]),
    # Priority 11-14: Tooling projects (check BEFORE Node to catch hybrids)
    ("homebrew", "tap", [], []),  # Special: glob for Formula/*.rb
    ("zsh", "plugin", [], []),  # Special: glob for *.plugin.zsh
    ("elisp", "package", [], []),  # Special: glob for *-pkg.el
    # Priority 15-18: Node ecosystem (requires real Node project, not just tooling)
    ("node", "bun", ["package.json", "bun.lock"], []),
    ("node", "pnpm", ["package.json", "pnpm-lock.yaml"], []),
    ("node", "yarn", ["package.json", "yarn.lock"], []),
    ("node", "npm", ["package.json"], ["package-lock.json"]),
    # Priority 19-20: Other compiled languages
    ("rust", "cargo", ["Cargo.toml"], ["Cargo.lock"]),
    ("go", "mod", ["go.mod"], ["go.sum"]),
    ("java", "maven", ["pom.xml"], []),
    ("java", "gradle", ["build.gradle"], ["build.gradle.kts"]),
    # Priority 21: Fallback
    ("shell", "script", [], []),  # Fallback for *.sh
]


def is_real_node_project(path: Path) -> bool:
    """Check if package.json indicates a real Node.js project vs just tooling.

    A real Node.js project has at least one of:
    - 'main' field (library entry point)
    - 'bin' field (CLI commands)
    - 'dependencies' (not just devDependencies)
    - 'type': 'module' with actual source files

    Projects with only devDependencies (ESLint, Prettier, etc.) are
    just using Node tooling, not actual Node.js projects.
    """
    pkg = path / "package.json"
    if not pkg.exists():
        return False

    import json
    try:
        data = json.loads(pkg.read_text())
    except json.JSONDecodeError:
        return False

    # Has entry point = real Node project
    if data.get("main"):
        return True

    # Has CLI commands = real Node project
    if data.get("bin"):
        return True

    # Has real dependencies (not just devDependencies) = real Node project
    if data.get("dependencies") and len(data["dependencies"]) > 0:
        return True

    # Has exports field = real Node project (modern ESM)
    if data.get("exports"):
        return True

    # Only has devDependencies = just tooling, not a Node project
    return False


def detect_project(path: Path) -> Optional[ProjectInfo]:
    """Detect project type from directory contents."""
    for proj_type, variant, required, optional in DETECTORS:
        if all((path / f).exists() for f in required):
            # Special handling for Node.js - skip if only tooling
            if proj_type == "node" and not is_real_node_project(path):
                continue  # Skip Node detection, try next detector

            return ProjectInfo(
                type=proj_type,
                variant=variant,
                test_framework=detect_test_framework(path, proj_type),
                build_tool=variant,
                ci_template=f"{proj_type}-{variant}",
                python_versions=detect_python_versions(path) if proj_type == "python" else [],
                node_versions=detect_node_versions(path) if proj_type == "node" else [],
                has_docs=detect_docs(path),
                has_ci=(path / ".github/workflows").exists(),
            )
    return None