wintersolve 0.3.0__py3-none-any.whl

wintersolve/__init__.py

@@ -0,0 +1,13 @@
+"""WinterSolve: offline-first repository intelligence for developers.
+
+The public entry points are the ``wintersolve`` command (see ``wintersolve.cli``)
+and the analyzer functions in ``wintersolve.modules``, which return plain
+dataclasses you can render or serialise however you like.
+"""
+
+from wintersolve.logging_config import configure_logging, get_logger, set_log_level
+
+# Single source of truth for the version; pyproject.toml reads it at build time.
+__version__ = "0.3.0"
+
+__all__ = ["__version__", "configure_logging", "get_logger", "set_log_level"]

wintersolve/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m wintersolve`` as an alternative to the ``wintersolve`` script."""
+
+from wintersolve.cli import main
+
+if __name__ == "__main__":
+    main()

wintersolve/cli.py

@@ -0,0 +1,324 @@
+"""Command-line interface for WinterSolve.
+
+Each command does three things and nothing more: collect input, call one
+analyzer, and hand the result to a renderer. Analysis logic lives in
+``wintersolve.modules``; output formatting lives in ``wintersolve.report``.
+
+Exit codes:
+    0  success
+    1  the analysis itself failed (unexpected error, unreadable input)
+    2  invalid usage, or the target could not be analyzed (missing path, no Git)
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from collections.abc import Callable
+from enum import Enum
+from pathlib import Path
+from typing import Annotated, NoReturn, TypeVar
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+from wintersolve import __version__, configure_logging, get_logger
+from wintersolve.modules.brain import build_brain_report
+from wintersolve.modules.debugger import analyze_error_file, analyze_error_text
+from wintersolve.modules.docs_assistant import suggest_docs
+from wintersolve.modules.explainer import explain_file
+from wintersolve.modules.reviewer import review_changes
+from wintersolve.modules.scanner import scan_project
+from wintersolve.project import resolve_project_path
+from wintersolve.report import (
+    render_brain_report,
+    render_debug_analysis,
+    render_docs_suggestions,
+    render_explanation,
+    render_review_result,
+    render_scan_report,
+)
+from wintersolve.workflows.registry import get_workflows
+
+logger = get_logger("wintersolve.cli")
+
+EXIT_FAILURE = 1
+EXIT_USAGE = 2
+
+app = typer.Typer(
+    name="wintersolve",
+    help="Offline-first repository intelligence: understand, debug, document, and review code.",
+    epilog="Docs and examples: https://github.com/harshitkrhere/WinterSolve",
+    add_completion=False,
+    rich_markup_mode="rich",
+    no_args_is_help=True,
+)
+console = Console()
+error_console = Console(stderr=True)
+
+T = TypeVar("T")
+
+
+class ReportFormat(str, Enum):
+    text = "text"
+    markdown = "markdown"
+    json = "json"
+
+
+# Reusable argument definitions so every command validates paths the same way.
+ProjectArgument = Annotated[
+    Path,
+    typer.Argument(
+        help="Project directory to analyze.",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        readable=True,
+        resolve_path=True,
+    ),
+]
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"WinterSolve {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _configure(
+    version: Annotated[  # noqa: ARG001 - handled eagerly by _version_callback
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show the version and exit.",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+    verbose: Annotated[
+        bool,
+        typer.Option("--verbose", "-v", help="Show debug logging on stderr."),
+    ] = False,
+) -> None:
+    """WinterSolve: understand any repository from the terminal, no account required."""
+    if verbose:
+        configure_logging(level=logging.DEBUG)
+
+
+def main() -> None:
+    """Console script entry point (``wintersolve`` and ``python -m wintersolve``)."""
+    app()
+
+
+# ------------------------------------------------------------------------ commands
+
+
+@app.command()
+def scan(
+    path: ProjectArgument = Path(),
+    output_format: Annotated[
+        ReportFormat,
+        typer.Option("--format", "-f", help="Output format.", case_sensitive=False),
+    ] = ReportFormat.text,
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Write the report to this file instead of stdout."),
+    ] = None,
+) -> None:
+    """Quick repository health check: languages, stack, layout, and hygiene gaps."""
+    result = _run(lambda: scan_project(path))
+    _emit(
+        render_scan_report(result, output_format=output_format.value), output_format.value, output
+    )
+
+
+@app.command()
+def brain(
+    path: ProjectArgument = Path(),
+    output_format: Annotated[
+        ReportFormat,
+        typer.Option("--format", "-f", help="Output format.", case_sensitive=False),
+    ] = ReportFormat.text,
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Write the report to this file instead of stdout."),
+    ] = None,
+    no_bandit: Annotated[
+        bool,
+        typer.Option("--no-bandit", help="Skip the optional Bandit pass (faster on large repos)."),
+    ] = False,
+) -> None:
+    """Full project intelligence report: architecture, commands, security, risks, next steps."""
+    result = _run(lambda: build_brain_report(path, run_bandit=not no_bandit))
+    _emit(
+        render_brain_report(result, output_format=output_format.value), output_format.value, output
+    )
+
+
+@app.command()
+def explain(
+    file: Annotated[
+        Path,
+        typer.Argument(
+            help="File to explain.",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+            resolve_path=True,
+        ),
+    ],
+    project: Annotated[
+        Path,
+        typer.Option(
+            "--project",
+            "-p",
+            help="Project root; files outside it are refused.",
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+            readable=True,
+            resolve_path=True,
+        ),
+    ] = Path(),
+) -> None:
+    """Explain one file: what it is, what it defines, and what it depends on."""
+    try:
+        target = resolve_project_path(project, str(file))
+    except ValueError as error:
+        _usage_error(str(error))
+    result = _run(lambda: explain_file(target))
+    _emit(render_explanation(result))
+
+
+@app.command()
+def debug(
+    text: Annotated[
+        str | None,
+        typer.Option("--text", "-t", help="Error text to analyze.", rich_help_panel="Input"),
+    ] = None,
+    file: Annotated[
+        Path | None,
+        typer.Option(
+            "--file",
+            help="File containing the error output.",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+            resolve_path=True,
+            rich_help_panel="Input",
+        ),
+    ] = None,
+) -> None:
+    """Analyze an error message, log, or stack trace. Reads stdin when piped."""
+    if text is not None and file is not None:
+        _usage_error("Provide only one of --text or --file.")
+
+    if file is not None:
+        result = _run(lambda: analyze_error_file(file))
+    elif text is not None:
+        result = _run(lambda: analyze_error_text(text))
+    elif not _stdin_is_interactive():
+        piped = sys.stdin.read()
+        if not piped.strip():
+            _usage_error("Nothing to analyze: stdin was empty.")
+        result = _run(lambda: analyze_error_text(piped, source="stdin"))
+    else:
+        _usage_error("Provide --text, --file, or pipe error output into the command.")
+
+    _emit(render_debug_analysis(result))
+
+
+@app.command()
+def docs(
+    path: ProjectArgument = Path(),
+    draft_readme: Annotated[
+        bool,
+        typer.Option("--draft-readme", help="Include a starter README draft in the output."),
+    ] = False,
+) -> None:
+    """Find missing README sections and hygiene files; optionally draft a README."""
+    result = _run(lambda: suggest_docs(path))
+    _emit(render_docs_suggestions(result, include_draft=draft_readme))
+
+
+@app.command()
+def review(path: ProjectArgument = Path()) -> None:
+    """Turn uncommitted Git changes into review risks and a pre-PR checklist."""
+    result = _run(lambda: review_changes(path))
+    _emit(render_review_result(result))
+    if not result.git_available:
+        raise typer.Exit(code=EXIT_USAGE)
+
+
+@app.command()
+def workflows() -> None:
+    """List available workflows and their output formats."""
+    table = Table(title="WinterSolve Workflows")
+    table.add_column("Name", style="cyan")
+    table.add_column("Summary", style="white")
+    table.add_column("Offline", justify="center")
+    table.add_column("Output Formats", style="green")
+    for workflow in get_workflows():
+        table.add_row(
+            workflow.name,
+            workflow.summary,
+            "yes" if workflow.offline else "no",
+            ", ".join(workflow.output_formats),
+        )
+    console.print(table)
+
+
+# ------------------------------------------------------------------------- helpers
+
+
+def _run(operation: Callable[[], T]) -> T:
+    """Run an analyzer and turn unexpected failures into a clean exit code 1.
+
+    ``typer.Exit`` is deliberately *not* caught here: it is how commands signal
+    a non-zero exit, and swallowing it would turn every exit into "Error:".
+    """
+    try:
+        return operation()
+    except typer.Exit:
+        raise
+    except Exception as error:  # The CLI boundary reports failures; it never shows tracebacks.
+        logger.debug("Command failed", exc_info=error)
+        error_console.print(f"[red]Error:[/red] {escape(str(error))}")
+        raise typer.Exit(code=EXIT_FAILURE) from None
+
+
+def _stdin_is_interactive() -> bool:
+    """True when stdin is a terminal rather than a pipe or file."""
+    return sys.stdin.isatty()
+
+
+def _usage_error(message: str) -> NoReturn:
+    error_console.print(f"[red]Error:[/red] {escape(message)}")
+    raise typer.Exit(code=EXIT_USAGE)
+
+
+def _emit(rendered: str, output_format: str = "text", output: Path | None = None) -> None:
+    """Print a report, or save it when ``--output`` was given.
+
+    Reports are printed as plain text: Rich markup and emoji codes are turned
+    off so a file called ``[id].tsx`` or a line containing ``:tada:`` comes out
+    exactly as written. JSON bypasses Rich entirely so it is safe to pipe.
+    """
+    if output is not None:
+        output.write_text(rendered + "\n", encoding="utf-8")
+        console.print(f"[green]Report saved to[/green] {escape(str(output))}")
+        return
+    if output_format == "json":
+        sys.stdout.write(rendered + "\n")
+        return
+    console.print(rendered, markup=False, highlight=False, emoji=False, soft_wrap=True)
+
+
+if __name__ == "__main__":
+    main()

wintersolve/logging_config.py

@@ -0,0 +1,59 @@
+"""Quiet-by-default logging.
+
+WinterSolve writes reports to stdout, so diagnostics go to stderr and only
+warnings show unless ``--verbose`` raises the level. Loggers never propagate
+to the root logger, which keeps host applications' logging untouched when
+WinterSolve is used as a library.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+DEFAULT_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+DEFAULT_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+_loggers: dict[str, logging.Logger] = {}
+
+
+def get_logger(name: str = "wintersolve") -> logging.Logger:
+    """Return the named logger, creating and configuring it on first use."""
+    if name not in _loggers:
+        _loggers[name] = _create_logger(name)
+    return _loggers[name]
+
+
+def _create_logger(name: str) -> logging.Logger:
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.WARNING)
+    logger.propagate = False
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stderr)
+        handler.setLevel(logging.WARNING)
+        handler.setFormatter(logging.Formatter(DEFAULT_FORMAT, datefmt=DEFAULT_DATE_FORMAT))
+        logger.addHandler(handler)
+    return logger
+
+
+def set_log_level(level: int) -> None:
+    """Change the level of every WinterSolve logger created so far."""
+    for logger in _loggers.values():
+        logger.setLevel(level)
+        for handler in logger.handlers:
+            handler.setLevel(level)
+
+
+def configure_logging(
+    level: int = logging.INFO,
+    format_string: str | None = None,
+    date_format: str | None = None,
+) -> None:
+    """Set the level and, optionally, the message format for all WinterSolve loggers."""
+    set_log_level(level)
+    if format_string is None:
+        return
+    formatter = logging.Formatter(format_string, datefmt=date_format)
+    for logger in _loggers.values():
+        for handler in logger.handlers:
+            handler.setFormatter(formatter)

wintersolve/models.py

@@ -0,0 +1,110 @@
+"""Result types shared by the Repo Brain report and the analyzers that feed it.
+
+Every result is a frozen dataclass so it can be rendered as text, Markdown, or
+JSON without surprises. Analyzers build these; they never print.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass
+from typing import Any
+
+# Bump when the shape of the JSON report changes in a way integrations must
+# know about. Additive fields do not require a bump.
+BRAIN_SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class ProjectIdentity:
+    name: str
+    path: str
+    exists: bool
+    offline_mode: bool
+
+
+@dataclass(frozen=True)
+class CommandCandidate:
+    """A setup, build, test, or run command inferred from project files."""
+
+    name: str
+    command: str
+    source: str
+    confidence: str
+
+
+@dataclass(frozen=True)
+class ArchitectureSection:
+    """A top-level area of the repository and what it is probably for."""
+
+    name: str
+    path: str
+    purpose: str
+    notable_files: list[str]
+
+
+@dataclass(frozen=True)
+class SecurityFinding:
+    """One thing the security scan wants a human to look at.
+
+    ``category`` is one of ``secret``, ``code-pattern``, or ``bandit`` and is
+    the field integrations should branch on; ``kind`` is the human label.
+    """
+
+    path: str
+    line: int
+    category: str
+    kind: str
+    severity: str
+    evidence: str
+
+
+@dataclass(frozen=True)
+class SecuritySummary:
+    status: str
+    offline_by_default: bool
+    files_checked: int
+    findings: list[SecurityFinding]
+    notes: list[str]
+
+    @staticmethod
+    def empty() -> SecuritySummary:
+        return SecuritySummary(
+            status="not checked",
+            offline_by_default=True,
+            files_checked=0,
+            findings=[],
+            notes=["Project path does not exist."],
+        )
+
+
+@dataclass(frozen=True)
+class BrainReport:
+    """The full Repo Brain result: everything WinterSolve learned about a project."""
+
+    identity: ProjectIdentity
+    languages: list[tuple[str, int]]
+    stack: list[str]
+    source_paths: list[str]
+    test_paths: list[str]
+    docs_health: list[str]
+    architecture: list[ArchitectureSection]
+    commands: list[CommandCandidate]
+    security: SecuritySummary
+    risks: list[str]
+    recommendations: list[str]
+    next_actions: list[str]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to plain JSON-friendly data with a stable, documented shape."""
+        data = asdict(self)
+        data["schema_version"] = BRAIN_SCHEMA_VERSION
+        data["languages"] = [{"name": name, "files": count} for name, count in self.languages]
+        for finding in data["security"]["findings"]:
+            finding["evidence"] = strip_control_characters(finding["evidence"])
+        return data
+
+
+def strip_control_characters(text: str) -> str:
+    """Remove control characters so evidence snippets stay clean in JSON and terminals."""
+    return re.sub(r"[\x00-\x08\x0b-\x1f\x7f-\x9f]", "", text)

wintersolve/modules/__init__.py

@@ -0,0 +1,5 @@
+"""Analyzers, one developer workflow each.
+
+Every module exposes a function that takes explicit inputs and returns a
+frozen dataclass. Modules never print and never touch the network.
+"""

wintersolve/modules/architecture.py

@@ -0,0 +1,79 @@
+"""Architecture map: what each top-level area of a repository is probably for."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from wintersolve.models import ArchitectureSection
+from wintersolve.project import walk_project
+
+# Conventional directory names and the role they usually play. Anything else
+# gets a neutral description rather than a guess.
+PURPOSE_BY_NAME = {
+    "src": "Application or library source code",
+    "app": "Application entrypoints and routes",
+    "apps": "Applications in a monorepo",
+    "packages": "Packages in a monorepo",
+    "lib": "Shared library code",
+    "pkg": "Shared library code",
+    "cmd": "Command-line entrypoints",
+    "internal": "Private application code",
+    "api": "API layer",
+    "server": "Server-side code",
+    "client": "Client-side code",
+    "web": "Web frontend",
+    "frontend": "Web frontend",
+    "backend": "Backend services",
+    "services": "Service implementations",
+    "tests": "Automated tests",
+    "test": "Automated tests",
+    "spec": "Automated tests",
+    "__tests__": "Automated tests",
+    "docs": "Project documentation",
+    "doc": "Project documentation",
+    "examples": "Example inputs, outputs, or sample projects",
+    "scripts": "Developer and automation scripts",
+    "tools": "Developer tooling",
+    "templates": "Reusable templates and prompts",
+    "config": "Configuration files",
+    "configs": "Configuration files",
+    "infra": "Infrastructure definitions",
+    "deploy": "Deployment configuration",
+    "migrations": "Database migrations",
+    "public": "Static assets served as-is",
+    "static": "Static assets",
+    "assets": "Design and media assets",
+    "data": "Data files and fixtures",
+    "notebooks": "Jupyter notebooks",
+    ".github": "GitHub community and automation files",
+}
+
+MAX_SECTIONS = 20
+MAX_NOTABLE_FILES = 8
+
+
+def map_architecture(root: Path) -> list[ArchitectureSection]:
+    """Group files by top-level directory and describe each group."""
+    tree = walk_project(root)
+    files_by_area: dict[str, list[str]] = {}
+    for project_file in tree.files:
+        top_level, separator, _ = project_file.relative_path.partition("/")
+        if not separator:
+            continue  # Files at the root are listed elsewhere; not an "area".
+        files_by_area.setdefault(top_level, []).append(project_file.relative_path)
+
+    sections = [
+        ArchitectureSection(
+            name=name,
+            path=name,
+            purpose=PURPOSE_BY_NAME.get(name, "Project area detected from repository structure"),
+            notable_files=_notable(files),
+        )
+        for name, files in sorted(files_by_area.items())
+    ]
+    return sections[:MAX_SECTIONS]
+
+
+def _notable(files: list[str]) -> list[str]:
+    # Shallow files describe an area better than deeply nested ones.
+    return sorted(files, key=lambda path: (path.count("/"), path))[:MAX_NOTABLE_FILES]

wintersolve/modules/brain.py

@@ -0,0 +1,74 @@
+"""Repo Brain: compose every analyzer into one project intelligence report."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from wintersolve.models import BrainReport, ProjectIdentity, SecuritySummary
+from wintersolve.modules.architecture import map_architecture
+from wintersolve.modules.command_detector import detect_commands
+from wintersolve.modules.docs_assistant import suggest_docs
+from wintersolve.modules.recommendations import (
+    build_brain_recommendations,
+    build_brain_risks,
+    build_docs_health,
+    build_next_actions,
+)
+from wintersolve.modules.scanner import scan_project
+from wintersolve.modules.security import analyze_security
+
+
+def build_brain_report(root: Path, *, run_bandit: bool = True) -> BrainReport:
+    """Analyze ``root`` with every module and assemble the combined report.
+
+    ``run_bandit=False`` skips the optional Bandit pass, which is the slow part
+    on large Python projects.
+    """
+    scan = scan_project(root)
+    if not scan.exists:
+        return _missing_project_report(root, scan.risks, scan.recommendations)
+
+    docs = suggest_docs(root, scan)
+    commands = detect_commands(root)
+    security = analyze_security(root, run_bandit=run_bandit)
+    architecture = map_architecture(root)
+    risks = build_brain_risks(scan, security, len(commands))
+
+    return BrainReport(
+        identity=ProjectIdentity(name=root.name, path=str(root), exists=True, offline_mode=True),
+        languages=scan.languages,
+        stack=scan.frameworks,
+        source_paths=scan.likely_source_paths,
+        test_paths=scan.likely_test_paths,
+        docs_health=build_docs_health(docs.missing_sections, scan.missing_recommended_files),
+        architecture=architecture,
+        commands=commands,
+        security=security,
+        risks=risks,
+        recommendations=build_brain_recommendations(scan, security, len(commands)),
+        next_actions=build_next_actions(
+            security=security,
+            command_count=len(commands),
+            has_architecture=bool(architecture),
+            risk_count=len(risks),
+        ),
+    )
+
+
+def _missing_project_report(
+    root: Path, risks: list[str], recommendations: list[str]
+) -> BrainReport:
+    return BrainReport(
+        identity=ProjectIdentity(name=root.name, path=str(root), exists=False, offline_mode=True),
+        languages=[],
+        stack=[],
+        source_paths=[],
+        test_paths=[],
+        docs_health=["Project path does not exist, so documentation health could not be checked."],
+        architecture=[],
+        commands=[],
+        security=SecuritySummary.empty(),
+        risks=risks,
+        recommendations=recommendations,
+        next_actions=["Point WinterSolve at an existing project directory."],
+    )