commiter-cli 0.3.0__py3-none-any.whl

commiter/cli.py

@@ -0,0 +1,667 @@
+"""Click CLI entry point for the commiter CLI."""
+
+
+
+from __future__ import annotations
+
+
+
+import os
+
+from pathlib import Path
+
+
+
+import click
+
+from rich.console import Console
+
+
+
+from commiter.scanner import scan_repos
+
+from commiter.models import RepoDocumentation, APIEndpoint, APICall, DBOperation, Dependency
+
+
+
+# Markers that indicate a repository root directory
+
+_REPO_ROOT_MARKERS = {
+
+    ".git", "package.json", "pyproject.toml", "go.mod",
+
+    "Cargo.toml", "Gemfile", "composer.json", "pom.xml",
+
+}
+
+
+
+
+
+class OptionalQuery(click.ParamType):
+
+    """Click parameter type that accepts a flag with an optional query string.
+
+
+
+    --endpoints          → value = "" (show all)
+
+    --endpoints users    → value = "users" (filter by query)
+
+    (not passed)         → value = None (don't show this section)
+
+    """
+
+    name = "query"
+
+
+
+    def convert(self, value, param, ctx):
+
+        return value
+
+
+
+
+
+@click.command()
+
+@click.argument("repo_paths", nargs=-1, required=False, type=click.Path(exists=True))
+
+@click.option("--format", "output_format", type=click.Choice(["console", "markdown", "json", "ai", "architecture"]), default="console", help="Output format.")
+
+@click.option("--output", "-o", "output_path", type=click.Path(), default=None, help="Output file or directory.")
+
+@click.option("--file", "-f", "file_filter", type=str, default=None, help="Show results only for this file.")
+
+@click.option("--endpoints", "-e", "endpoints_query", type=str, default=None, help="Show only endpoints. Pass 'all' or a search query (e.g. --endpoints users).")
+
+@click.option("--calls", "-c", "calls_query", type=str, default=None, help="Show only API calls. Pass 'all' or a search query.")
+
+@click.option("--db", "-d", "db_query", type=str, default=None, help="Show only DB operations. Pass 'all' or a search query.")
+
+@click.option("--deps", "deps_query", type=str, default=None, help="Show only dependencies. Pass 'all' or a search query.")
+
+@click.option("--api-guide", "api_guide_query", type=str, default=None, help="Generate curl commands for endpoints. Pass 'all' or a search query.")
+
+@click.option("--exclude", multiple=True, help="Path patterns to exclude.")
+
+@click.option("--verbose", "-v", is_flag=True, help="Show detailed progress.")
+
+@click.option("--enrich", is_flag=True, default=False, help="Upload architecture to commiter.dev for AI-generated descriptions.")
+
+@click.option("--token", "api_token", type=str, default=None, envvar="COMMITER_TOKEN", help="Auth token override (or set COMMITER_TOKEN env var).")
+
+@click.option("--login", "do_login", is_flag=True, default=False, help="Log in to commiter.dev via browser.")
+
+@click.option("--logout", "do_logout", is_flag=True, default=False, help="Log out and remove saved credentials.")
+
+def main(repo_paths: tuple[str, ...], output_format: str, output_path: str | None,
+
+         file_filter: str | None, endpoints_query: str | None, calls_query: str | None,
+
+         db_query: str | None, deps_query: str | None, api_guide_query: str | None,
+
+         exclude: tuple[str, ...], verbose: bool, enrich: bool, api_token: str | None,
+
+         do_login: bool, do_logout: bool) -> None:
+
+    """Scan repositories and generate documentation.
+
+
+
+    Pass one or more REPO_PATHS to analyze, or use --file to focus on a single file.
+
+
+
+    \b
+
+    Category flags (show specific sections, optional query to filter):
+
+      --endpoints [QUERY]   Show API endpoints
+
+      --calls [QUERY]       Show frontend API calls
+
+      --db [QUERY]          Show database operations
+
+      --deps [QUERY]        Show dependencies
+
+    """
+
+    console = Console()
+
+    # Handle --login / --logout before anything else
+    if do_login:
+        from commiter.auth import login
+        login()
+        return
+
+    if do_logout:
+        from commiter.auth import logout
+        logout()
+        return
+
+    # Auto-load saved token if no explicit --token given
+    if not api_token:
+        from commiter.auth import get_saved_token
+        api_token = get_saved_token()
+
+
+
+    # Handle --file without repo paths: auto-detect repo root
+
+    if file_filter and not repo_paths:
+
+        file_abs = os.path.abspath(file_filter)
+
+        if not os.path.isfile(file_abs):
+
+            console.print(f"[red]File not found: {file_filter}[/red]")
+
+            raise SystemExit(1)
+
+        repo_root = _detect_repo_root(file_abs)
+
+        if not repo_root:
+
+            console.print(f"[red]Could not detect repository root for {file_filter}. Pass the repo path explicitly.[/red]")
+
+            raise SystemExit(1)
+
+        repo_paths = (repo_root,)
+
+        if verbose:
+
+            console.print(f"[dim]Auto-detected repo root: {repo_root}[/dim]")
+
+
+
+    if not repo_paths:
+
+        console.print("[red]Please provide at least one REPO_PATH or use --file.[/red]")
+
+        raise SystemExit(1)
+
+
+
+    if verbose:
+
+        console.print(f"[dim]Scanning {len(repo_paths)} repo(s)...[/dim]")
+
+
+
+    extra_excludes = list(exclude) if exclude else None
+
+
+
+    # Architecture format needs full scan results (with indexes)
+
+    if output_format == "architecture":
+
+        from commiter.scanner import scan_repos_full
+
+        from commiter.report.architecture import generate_architecture
+
+
+
+        scan_results = scan_repos_full(list(repo_paths), extra_excludes=extra_excludes)
+
+        json_str = generate_architecture(scan_results)
+
+
+
+        if output_path:
+
+            with open(output_path, "w", encoding="utf-8") as f:
+
+                f.write(json_str)
+
+            console.print(f"[green]Architecture JSON written to {output_path}[/green]")
+
+
+
+        if enrich:
+
+            from commiter.uploader import upload_architecture
+
+            console.print("[dim]Uploading to commiter.dev for AI enrichment...[/dim]")
+
+            result = upload_architecture(json_str, api_token=api_token)
+
+            if "error" in result:
+
+                console.print(f"[red]Upload failed: {result['error']}[/red]")
+
+            else:
+                workspace = result.get("workspace")
+                if workspace and workspace.get("name") and workspace.get("version") is not None:
+                    ws_name = workspace["name"]
+                    ws_version = workspace["version"]
+                    verb = "Cached" if result.get("cached") else "Uploaded"
+                    console.print(
+                        f"[green]{verb} to workspace \"{ws_name}\" as version {ws_version}[/green]"
+                    )
+                    console.print(f"[green]View at: {result['url']}[/green]")
+                elif result.get("cached"):
+                    console.print(f"[green]Cached! View at: {result['url']}[/green]")
+                else:
+                    console.print(f"[green]View at: {result['url']}[/green]")
+
+                tier = result.get("tier", "anonymous")
+
+                if tier == "anonymous" and not result.get("cached"):
+                    console.print("[dim]Tip: run commiter enrich --login for full AI enrichment[/dim]")
+                elif tier == "authenticated" and not workspace:
+                    console.print(
+                        "[dim]Tip: connect this repo to a workspace at commiter.dev "
+                        "to enable versioning and roadmap navigation[/dim]"
+                    )
+
+                console.print(f"[dim]Status: {result.get('status', 'unknown')} - descriptions will be ready in ~30 seconds[/dim]")
+
+        elif not output_path:
+
+            click.echo(json_str)
+
+        return
+
+
+
+    docs = scan_repos(list(repo_paths), extra_excludes=extra_excludes)
+
+
+
+    # Apply file filter if specified
+
+    if file_filter:
+
+        docs = _filter_docs_by_file(docs, file_filter)
+
+
+
+    # Determine which sections to show
+
+    has_category_flags = any(x is not None for x in (endpoints_query, calls_query, db_query, deps_query))
+
+
+
+    # Build sections config: which sections to show + query filters
+
+    # None = don't show, "" = show all, "query" = show filtered
+
+    if has_category_flags:
+
+        # Normalize "all" to empty string (show everything in that category)
+
+        sections = {
+
+            "endpoints": ("" if endpoints_query and endpoints_query.lower() == "all" else endpoints_query),
+
+            "calls": ("" if calls_query and calls_query.lower() == "all" else calls_query),
+
+            "db": ("" if db_query and db_query.lower() == "all" else db_query),
+
+            "deps": ("" if deps_query and deps_query.lower() == "all" else deps_query),
+
+        }
+
+    else:
+
+        sections = {"endpoints": "", "calls": "", "db": "", "deps": ""}
+
+
+
+    # Apply query filters to the data
+
+    if has_category_flags:
+
+        docs = _apply_query_filters(docs, sections)
+
+
+
+    # --api-guide overrides format output: generates curl commands
+
+    if api_guide_query is not None:
+
+        from commiter.report.api_guide import generate_api_guide
+
+        from commiter.utils.env_reader import load_env_files
+
+
+
+        # Filter endpoints by query
+
+        query = "" if api_guide_query.lower() == "all" else api_guide_query
+
+        if query:
+
+            for doc in docs:
+
+                doc.endpoints = [ep for ep in doc.endpoints if _endpoint_matches(ep, query)]
+
+
+
+        env_vars = load_env_files(list(repo_paths)[0]) if repo_paths else {}
+
+        guide = generate_api_guide(docs, env_vars=env_vars)
+
+        if output_path:
+
+            with open(output_path, "w", encoding="utf-8") as f:
+
+                f.write(guide)
+
+            console.print(f"[green]API guide written to {output_path}[/green]")
+
+        else:
+
+            click.echo(guide)
+
+        return
+
+
+
+    if output_format == "console":
+
+        from commiter.report.console import print_report
+
+        print_report(docs, console, sections=sections)
+
+
+
+    elif output_format == "markdown":
+
+        from commiter.report.markdown import generate_markdown
+
+        md = generate_markdown(docs, sections=sections)
+
+        if output_path:
+
+            with open(output_path, "w", encoding="utf-8") as f:
+
+                f.write(md)
+
+            console.print(f"[green]Documentation written to {output_path}[/green]")
+
+        else:
+
+            console.print(md)
+
+
+
+    elif output_format == "json":
+
+        from commiter.report.json_output import generate_json
+
+        json_str = generate_json(docs, sections=sections)
+
+        if output_path:
+
+            with open(output_path, "w", encoding="utf-8") as f:
+
+                f.write(json_str)
+
+            console.print(f"[green]JSON written to {output_path}[/green]")
+
+        else:
+
+            console.print(json_str)
+
+
+
+    elif output_format == "ai":
+
+        from commiter.report.ai import generate_ai
+
+        ai_output = generate_ai(docs, sections=sections)
+
+        if output_path:
+
+            with open(output_path, "w", encoding="utf-8") as f:
+
+                f.write(ai_output)
+
+            console.print(f"[green]AI output written to {output_path}[/green]")
+
+        else:
+
+            click.echo(ai_output)
+
+
+
+
+
+def _apply_query_filters(docs: list[RepoDocumentation], sections: dict[str, str | None]) -> list[RepoDocumentation]:
+
+    """Apply query-based filtering to each section's data."""
+
+    for doc in docs:
+
+        # Filter endpoints
+
+        if sections.get("endpoints") is None:
+
+            doc.endpoints = []
+
+        elif sections["endpoints"]:
+
+            doc.endpoints = [ep for ep in doc.endpoints if _endpoint_matches(ep, sections["endpoints"])]
+
+
+
+        # Filter API calls
+
+        if sections.get("calls") is None:
+
+            doc.api_calls = []
+
+        elif sections["calls"]:
+
+            doc.api_calls = [c for c in doc.api_calls if _api_call_matches(c, sections["calls"])]
+
+
+
+        # Filter DB operations
+
+        if sections.get("db") is None:
+
+            doc.db_operations = []
+
+        elif sections["db"]:
+
+            doc.db_operations = [op for op in doc.db_operations if _db_op_matches(op, sections["db"])]
+
+
+
+        # Filter dependencies
+
+        if sections.get("deps") is None:
+
+            doc.dependencies = []
+
+        elif sections["deps"]:
+
+            doc.dependencies = [d for d in doc.dependencies if _dep_matches(d, sections["deps"])]
+
+
+
+    return docs
+
+
+
+
+
+def _endpoint_matches(ep: APIEndpoint, query: str) -> bool:
+
+    """Check if an endpoint matches a search query across all its fields."""
+
+    q = query.lower()
+
+    searchable = [
+
+        ep.http_method,
+
+        ep.route_pattern,
+
+        ep.handler_name,
+
+        ep.framework,
+
+        ep.request_body_type or "",
+
+        ep.response_type or "",
+
+    ]
+
+    searchable.extend(ep.request_body_fields)
+
+    searchable.extend(ep.response_fields)
+
+    searchable.extend(ep.auth_decorators)
+
+    searchable.extend(ep.middleware)
+
+    searchable.extend(ep.db_tables)
+
+    searchable.extend(p.name for p in ep.parameters)
+
+
+
+    return any(q in field.lower() for field in searchable)
+
+
+
+
+
+def _api_call_matches(call: APICall, query: str) -> bool:
+
+    """Check if an API call matches a search query."""
+
+    q = query.lower()
+
+    searchable = [
+
+        call.http_method,
+
+        call.url_pattern,
+
+        call.component_or_page,
+
+        call.client_library,
+
+        call.traced_from or "",
+
+        call.response_type or "",
+
+        call.body_type or "",
+
+    ]
+
+    return any(q in field.lower() for field in searchable)
+
+
+
+
+
+def _db_op_matches(op: DBOperation, query: str) -> bool:
+
+    """Check if a DB operation matches a search query."""
+
+    q = query.lower()
+
+    searchable = [
+
+        op.operation_type,
+
+        op.table_name,
+
+        op.orm_library,
+
+    ]
+
+    searchable.extend(op.filters)
+
+    return any(q in field.lower() for field in searchable)
+
+
+
+
+
+def _dep_matches(dep: Dependency, query: str) -> bool:
+
+    """Check if a dependency matches a search query."""
+
+    q = query.lower()
+
+    return q in dep.name.lower() or q in dep.version_constraint.lower()
+
+
+
+
+
+def _filter_docs_by_file(docs: list[RepoDocumentation], file_filter: str) -> list[RepoDocumentation]:
+
+    """Filter scan results to only show artifacts from a specific file."""
+
+    filter_normalized = file_filter.replace("\\", "/").rstrip("/")
+
+
+
+    def _matches(file_path: str) -> bool:
+
+        normalized = file_path.replace("\\", "/")
+
+        return normalized.endswith(filter_normalized) or normalized.endswith("/" + filter_normalized)
+
+
+
+    for doc in docs:
+
+        doc.endpoints = [ep for ep in doc.endpoints if _matches(ep.file_path)]
+
+        doc.api_calls = [c for c in doc.api_calls if _matches(c.file_path)]
+
+        doc.db_operations = [op for op in doc.db_operations if _matches(op.file_path)]
+
+        doc.file_classifications = [fc for fc in doc.file_classifications if _matches(fc.file_path)]
+
+
+
+    return docs
+
+
+
+
+
+def _detect_repo_root(file_path: str) -> str | None:
+
+    """Walk up from a file path to find the repository root."""
+
+    current = Path(file_path).parent
+
+    for _ in range(20):
+
+        for marker in _REPO_ROOT_MARKERS:
+
+            if (current / marker).exists():
+
+                return str(current)
+
+        parent = current.parent
+
+        if parent == current:
+
+            break
+
+        current = parent
+
+    return None
+
+
+
+
+
+if __name__ == "__main__":
+
+    main()
+