arian 0.5.0__py3-none-any.whl

arian/__init__.py

@@ -0,0 +1,7 @@
+"""Arian - repository intelligence and context planning engine."""
+
+from arian.controller.cli import app
+
+__all__ = [
+    "app",
+]

arian/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python -m arian`."""
+
+from arian.main import main
+
+main()

arian/bootstrap/__init__.py

@@ -0,0 +1,5 @@
+"""Bootstrap layer for Arian — startup wiring (logging)."""
+
+from arian.bootstrap.logging import configure_logging
+
+__all__ = ["configure_logging"]

arian/bootstrap/logging.py

@@ -0,0 +1,278 @@
+"""Logging initialization — configures stdlib logging for Arian.
+
+Project rule
+------------
+Never instantiate, attach, or reconfigure handlers outside this module.
+Business code must only call ``logging.getLogger(__name__)`` and emit records.
+All wiring (handlers, formatters, filters, QueueListener) lives here.
+
+Invariants
+----------
+1. Only the **root** logger owns output handlers.
+2. Named loggers set level, clear handlers, and **propagate** to root.
+3. ``configure_logging()`` is called **once** per process at startup.
+   A second call with ``async_logging=True`` would start another
+   QueueListener without stopping the first.
+
+Formatting policy
+-----------------
+Logging format is selected internally by severity:
+
+    Diagnostic (< INFO):  LEVEL WHEN WHERE RESOURCE : MESSAGE
+    Operational (>= INFO): LEVEL WHEN RESOURCE : MESSAGE
+
+WHERE = filename:lineno (diagnostic only)
+WHEN = UTC ISO-8601 timestamp
+RESOURCE = optional extra field (e.g. ``resource="model_id=bert"``)
+
+File logging
+------------
+When ``LoggingConfig.log_dir`` is set, logs are written to:
+    <log_dir>/arian.log
+
+Files rotate at ``max_bytes`` with ``backup_count`` backups.
+Log directory is created automatically if it does not exist.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC
+from datetime import datetime
+import logging
+import logging.config
+import logging.handlers
+from pathlib import Path
+import queue
+from typing import Any
+
+from arian.infrastructure.config import LoggingConfig
+
+APPLICATION_LOGGER_NAME = "arian"
+
+_PROPAGATING_LOGGERS = (APPLICATION_LOGGER_NAME,)
+
+_MODULE = "arian.bootstrap.logging"
+
+
+def _format_utc_timestamp(a_epoch_seconds: float) -> str:
+    """Format Unix epoch seconds as canonical UTC ISO-8601 (microseconds + Z).
+
+    Args:
+        a_epoch_seconds: Unix epoch timestamp.
+
+    Returns:
+        Formatted string like ``2026-07-18T23:45:12.345678Z``.
+    """
+    dt: datetime = datetime.fromtimestamp(a_epoch_seconds, tz=UTC)
+    return dt.astimezone(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+
+class IsoUtcFormatter(logging.Formatter):
+    """UTC ISO-8601 timestamp formatter."""
+
+    def formatTime(  # a-prefix-ignore: stdlib Formatter.signature  # noqa: N802
+        self,
+        record: logging.LogRecord,
+        datefmt: str | None = None,  # noqa: ARG002 — required by Formatter API
+    ) -> str:
+        """Format record creation time as canonical UTC ISO form.
+
+        Args:
+            record: Log record to format.
+            datefmt: Unused, required by Formatter API.
+
+        Returns:
+            UTC ISO-8601 timestamp string.
+        """
+        return _format_utc_timestamp(record.created)
+
+
+class ResourceFilter(logging.Filter):
+    """Inject format-safe ``resource`` attribute; always admit the record."""
+
+    def filter(self, record: logging.LogRecord) -> bool:  # a-prefix-ignore: stdlib Filter.signature
+        """Attach a format-safe ``resource`` attribute; always admit the record.
+
+        Args:
+            record: Log record to filter.
+
+        Returns:
+            Always True.
+        """
+        resource = getattr(record, "resource", None)
+        if resource:
+            record.resource = f" {resource}"
+        else:
+            record.resource = ""
+        return True
+
+
+class DiagnosticLevelFilter(logging.Filter):
+    """Admit Diagnostic (< INFO) records only."""
+
+    def filter(self, record: logging.LogRecord) -> bool:  # a-prefix-ignore: stdlib Filter.signature
+        """Return True for Diagnostic (< INFO) levels only.
+
+        Args:
+            record: Log record to filter.
+
+        Returns:
+            True if record level is below INFO.
+        """
+        return record.levelno < logging.INFO
+
+
+def _build_logging_config(a_config: LoggingConfig) -> dict[str, Any]:
+    """Build dictConfig: named loggers propagate to root; root owns handlers.
+
+    Handlers:
+        console_debug: diagnostic (< INFO) to stderr
+        console_ops: operational (>= INFO) to stderr
+        file: all levels to rotating file (if log_dir is set)
+
+    Args:
+        a_config: Validated logging configuration.
+
+    Returns:
+        Dictionary suitable for logging.config.dictConfig.
+    """
+    level: str = a_config.level
+
+    handlers: dict[str, dict[str, Any]] = {
+        "console_debug": {
+            "class": "logging.StreamHandler",
+            "level": "NOTSET",
+            "formatter": "diagnostic",
+            "filters": ["diagnostic_level", "resource"],
+            "stream": "ext://sys.stderr",
+        },
+        "console_ops": {
+            "class": "logging.StreamHandler",
+            "level": "INFO",
+            "formatter": "operational",
+            "filters": ["resource"],
+            "stream": "ext://sys.stderr",
+        },
+    }
+
+    root_handlers: list[str] = ["console_debug", "console_ops"]
+
+    if a_config.log_dir is not None:
+        log_dir: Path = Path(a_config.log_dir).expanduser()
+        log_dir.mkdir(parents=True, exist_ok=True)
+        log_file: Path = log_dir / "arian.log"
+
+        handlers["file"] = {
+            "class": "logging.handlers.RotatingFileHandler",
+            "level": "NOTSET",
+            "formatter": "file",
+            "filters": ["resource"],
+            "filename": str(log_file),
+            "maxBytes": a_config.max_bytes,
+            "backupCount": a_config.backup_count,
+            "encoding": "utf-8",
+        }
+        root_handlers.append("file")
+
+    return {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "filters": {
+            "resource": {
+                "()": f"{_MODULE}.ResourceFilter",
+            },
+            "diagnostic_level": {
+                "()": f"{_MODULE}.DiagnosticLevelFilter",
+            },
+        },
+        "formatters": {
+            "diagnostic": {
+                "()": f"{_MODULE}.IsoUtcFormatter",
+                "format": "%(levelname)s %(asctime)s %(filename)s:%(lineno)d%(resource)s : %(message)s",
+            },
+            "operational": {
+                "()": f"{_MODULE}.IsoUtcFormatter",
+                "format": "%(levelname)s %(asctime)s%(resource)s : %(message)s",
+            },
+            "file": {
+                "()": f"{_MODULE}.IsoUtcFormatter",
+                "format": "%(levelname)s %(asctime)s %(filename)s:%(lineno)d%(resource)s : %(message)s",
+            },
+        },
+        "handlers": handlers,
+        "loggers": {
+            name: {
+                "level": level,
+                "handlers": [],
+                "propagate": True,
+            }
+            for name in _PROPAGATING_LOGGERS
+        },
+        "root": {
+            "level": "WARNING",
+            "handlers": root_handlers,
+        },
+    }
+
+
+def _replace_handlers(a_logger: logging.Logger, a_handler: logging.Handler) -> None:
+    """Replace all handlers on *a_logger* with *a_handler*.
+
+    Args:
+        a_logger: Logger to modify.
+        a_handler: Handler to install.
+    """
+    a_logger.handlers.clear()
+    a_logger.addHandler(a_handler)
+
+
+def _enable_async_logging() -> logging.handlers.QueueListener:
+    """Route root handlers through QueueHandler → QueueListener for non-blocking I/O.
+
+    Returns:
+        Running QueueListener instance.
+
+    Raises:
+        RuntimeError: If root logger has no handlers to wrap.
+    """
+    root: logging.Logger = logging.getLogger()
+    targets: list[logging.Handler] = [
+        handler for handler in root.handlers if not isinstance(handler, logging.handlers.QueueHandler)
+    ]
+    if not targets:
+        msg = "Cannot enable async logging: root logger has no handlers"
+        raise RuntimeError(msg)
+
+    log_queue: queue.SimpleQueue[logging.LogRecord] = queue.SimpleQueue()
+    queue_handler: logging.handlers.QueueHandler = logging.handlers.QueueHandler(log_queue)
+    _replace_handlers(root, queue_handler)
+
+    listener: logging.handlers.QueueListener = logging.handlers.QueueListener(
+        log_queue,
+        *targets,
+        respect_handler_level=True,
+    )
+    listener.start()
+    return listener
+
+
+def configure_logging(a_config: LoggingConfig | None = None) -> logging.handlers.QueueListener | None:
+    """Apply dictConfig + captureWarnings once at process startup.
+
+    Returns a running ``QueueListener`` when async logging is enabled, else ``None``.
+
+    Args:
+        a_config: Logging configuration. Uses defaults if None.
+
+    Returns:
+        Running QueueListener if async_logging is enabled, None otherwise.
+    """
+    config: LoggingConfig = a_config or LoggingConfig()
+
+    logging.config.dictConfig(_build_logging_config(config))
+    logging.captureWarnings(True)
+
+    listener: logging.handlers.QueueListener | None = None
+    if config.async_logging:
+        listener = _enable_async_logging()
+    return listener

arian/controller/__init__.py

@@ -0,0 +1,7 @@
+"""Controller layer for Arian."""
+
+from arian.controller.cli import app
+
+__all__ = [
+    "app",
+]

arian/controller/cli/__init__.py

@@ -0,0 +1,7 @@
+"""CLI controller for Arian."""
+
+from arian.controller.cli.app import app
+
+__all__ = [
+    "app",
+]

arian/controller/cli/app.py

@@ -0,0 +1,330 @@
+"""Typer CLI application for Arian."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import logging.handlers
+from pathlib import Path
+
+import typer
+
+from arian.bootstrap.logging import configure_logging
+from arian.domain.context.models import ContextPlan
+from arian.domain.context.models import ContextTask
+from arian.domain.shared.enums import TokenBudget
+from arian.infrastructure.config import LoggingConfig
+from arian.infrastructure.ignore.default_patterns import DEFAULT_EXCLUDES
+from arian.infrastructure.output_path_resolver import resolve_output_path
+from arian.renderer.markdown.renderer import MarkdownRenderer
+from arian.repository.filesystem.collector import FileCollector
+from arian.repository.index.memory_repository import MemoryRepositoryIndex
+from arian.service.analyzer.python_analyzer import PythonAnalyzer
+from arian.service.builder.context_builder import ContextBuilder
+from arian.service.classifier.file_classifier import FileClassifier
+from arian.service.context.materializer import ContextMaterializer
+from arian.service.planner.context_planner import ContextPlanner
+
+app: typer.Typer = typer.Typer(help="Repository intelligence and context planning engine.", add_completion=False)
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+def _parse_budget(a_value: str | None) -> int | None:
+    """Parse budget string into token count or None for unlimited.
+
+    Args:
+        a_value: Raw budget string from CLI. None, "none", or a positive integer.
+
+    Returns:
+        Parsed budget as int, or None for unlimited.
+
+    Raises:
+        typer.Exit: If value is not a valid number or is non-positive.
+    """
+    budget_value: int | None = None
+    if a_value is not None:
+        if a_value.lower() == "none":
+            budget_value = None
+        else:
+            try:
+                budget_value = int(a_value)
+            except ValueError:
+                logger.exception("Invalid budget: %s. Must be a number or 'none'.", a_value)
+                raise typer.Exit(code=1) from None
+            if budget_value <= 0:
+                logger.error("Budget must be > 0, got: %d", budget_value)
+                raise typer.Exit(code=1) from None
+    return budget_value
+
+
+_DEFAULT_EXTENSIONS: frozenset[str] = frozenset({".py", ".md", ".txt", ".rst", ".toml", ".yaml", ".yml", ".json"})
+
+
+def _run_separate(
+    a_builder: ContextBuilder,
+    a_input_paths: list[Path],
+    a_task: ContextTask,
+    a_budget: TokenBudget,
+    a_query: str | None,
+    a_root: Path,
+    a_output_path: Path,
+    a_scope: str,
+) -> None:
+    """Build and write separate context files for each path.
+
+    Args:
+        a_builder: Context builder instance.
+        a_input_paths: Paths to process individually.
+        a_task: Task type.
+        a_budget: Token budget.
+        a_query: Optional query.
+        a_root: Repository root.
+        a_output_path: Base output path.
+        a_scope: Scope mode string.
+    """
+    for input_path in a_input_paths:
+        if not input_path.exists():
+            logger.error("Path does not exist: %s", input_path)
+            raise typer.Exit(code=1) from None
+        plan = asyncio.run(
+            a_builder.build(a_path=input_path, a_task=a_task, a_budget=a_budget, a_query=a_query, a_root=a_root)
+        )
+        input_name: str = str(input_path.relative_to(a_root)) if input_path != a_root else "."
+        plan = ContextPlan(
+            chunks=plan.chunks,
+            total_tokens=plan.total_tokens,
+            total_files=plan.total_files,
+            task=plan.task,
+            query=plan.query,
+            metadata={
+                "repository": a_root.name,
+                "paths": [input_name],
+                "budget": {"max": a_budget.max_tokens},
+                "scope": a_scope,
+            },
+            repository_files=plan.repository_files,
+        )
+        content_map = asyncio.run(a_builder.load_content(a_plan=plan, a_root=a_root))
+        materialized = a_builder.materialize(plan, content_map)
+        renderer: MarkdownRenderer = MarkdownRenderer()
+        rendered: str = renderer.render(materialized, plan)
+        if input_path == a_root:
+            sep_output = a_output_path.parent / "root_context.md"
+        else:
+            rel_name: Path = input_path.relative_to(a_root)
+            sep_output = a_output_path.parent / f"{rel_name}_context.md"
+        sep_output.parent.mkdir(parents=True, exist_ok=True)
+        sep_output.write_text(rendered, encoding="utf-8")
+        logger.info("Output: %s", sep_output)
+
+
+def _run_merged(
+    a_builder: ContextBuilder,
+    a_input_paths: list[Path],
+    a_task: ContextTask,
+    a_budget: TokenBudget,
+    a_query: str | None,
+    a_root: Path,
+    a_output_path: Path,
+    a_scope: str,
+    a_paths_provided: bool,
+) -> None:
+    """Build and write a single merged context file.
+
+    Args:
+        a_builder: Context builder instance.
+        a_input_paths: All input paths.
+        a_task: Task type.
+        a_budget: Token budget.
+        a_query: Optional query.
+        a_root: Repository root.
+        a_output_path: Output file path.
+        a_scope: Scope mode string.
+        a_paths_provided: Whether user provided explicit paths.
+    """
+    plan = asyncio.run(
+        a_builder.build(
+            a_path=a_root,
+            a_task=a_task,
+            a_budget=a_budget,
+            a_query=a_query,
+            a_root=a_root,
+            a_input_paths=a_input_paths if a_paths_provided else None,
+        )
+    )
+
+    input_names = [str(p.relative_to(a_root)) if p != a_root else "." for p in a_input_paths]
+    plan = ContextPlan(
+        chunks=plan.chunks,
+        total_tokens=plan.total_tokens,
+        total_files=plan.total_files,
+        task=plan.task,
+        query=plan.query,
+        metadata={
+            "repository": a_root.name,
+            "paths": input_names,
+            "budget": {"max": a_budget.max_tokens},
+            "scope": a_scope,
+        },
+        repository_files=plan.repository_files,
+    )
+
+    content_map = asyncio.run(a_builder.load_content(a_plan=plan, a_root=a_root))
+    materialized = a_builder.materialize(plan, content_map)
+    renderer_final: MarkdownRenderer = MarkdownRenderer()
+    rendered_final: str = renderer_final.render(materialized, plan)
+    a_output_path.parent.mkdir(parents=True, exist_ok=True)
+    a_output_path.write_text(rendered_final, encoding="utf-8")
+
+    logger.info(
+        "Context generated: %d files, %d tokens, %d chunks",
+        plan.total_files,
+        plan.total_tokens,
+        len(plan.chunks),
+    )
+    logger.info("Output: %s", a_output_path)
+
+
+def _run_group(
+    a_builder: ContextBuilder,
+    a_group_paths: list[Path],
+    a_task: ContextTask,
+    a_budget: TokenBudget,
+    a_query: str | None,
+    a_root: Path,
+    a_output_path: Path,
+) -> None:
+    """Build and write context for a single group of paths.
+
+    Args:
+        a_builder: Context builder instance.
+        a_group_paths: Paths belonging to this group.
+        a_task: Task type.
+        a_budget: Token budget.
+        a_query: Optional query.
+        a_root: Repository root.
+        a_output_path: Base output path.
+    """
+    plan = asyncio.run(
+        a_builder.build(
+            a_path=a_root,
+            a_task=a_task,
+            a_budget=a_budget,
+            a_query=a_query,
+            a_root=a_root,
+            a_input_paths=a_group_paths,
+        )
+    )
+    group_names: list[str] = [p.name for p in a_group_paths]
+    group_label: str = "_".join(group_names) if len(group_names) > 1 else group_names[0]
+    group_output = a_output_path.parent / f"{group_label}_context.md"
+    group_output.parent.mkdir(parents=True, exist_ok=True)
+
+    input_names = [str(p.relative_to(a_root)) for p in a_group_paths]
+    plan = ContextPlan(
+        chunks=plan.chunks,
+        total_tokens=plan.total_tokens,
+        total_files=plan.total_files,
+        task=plan.task,
+        query=plan.query,
+        metadata={
+            "repository": a_root.name,
+            "paths": input_names,
+            "budget": {"max": a_budget.max_tokens},
+            "scope": "group",
+        },
+        repository_files=plan.repository_files,
+    )
+
+    content_map = asyncio.run(a_builder.load_content(a_plan=plan, a_root=a_root))
+    materialized = a_builder.materialize(plan, content_map)
+    renderer: MarkdownRenderer = MarkdownRenderer()
+    rendered: str = renderer.render(materialized, plan)
+    group_output.write_text(rendered, encoding="utf-8")
+    logger.info("Output: %s", group_output)
+
+
+@app.command()  # a-prefix-ignore: Typer CLI public names
+def context(  # a-prefix-ignore: Typer CLI public names
+    task: str = typer.Option(
+        "general",
+        "--task",
+        case_sensitive=False,
+        help="Task type: bug_fix, feature, review, onboarding, refactor, document, general",
+    ),
+    query: str | None = typer.Option(
+        None, "--query", "-q", help="Query for relevance matching (reserved, not yet implemented)"
+    ),
+    output: str = typer.Option("~/.arian/output/context.md", "-o", "--output", help="Output file path"),
+    budget: str | None = typer.Option(None, "--budget", help="Maximum tokens for context (default: unlimited)"),
+    scope: str = typer.Option("merged", "--scope", help="Scope mode: merged (default) or separate"),
+    group: list[str] | None = typer.Option(
+        None,
+        "--group",
+        help="Group paths into one context file. Comma-separated. Repeatable: --group src/,lib/ --group docs/",
+    ),
+    verbose: bool = typer.Option(False, "-v", "--verbose", help="Enable debug logging"),
+    paths: list[str] = typer.Argument(default=None, help="Directories or files to include (default: cwd)"),
+) -> None:
+    """Generate task-aware context from a repository."""
+    listener: logging.handlers.QueueListener | None = configure_logging(
+        LoggingConfig(level="DEBUG" if verbose else "INFO")
+    )
+
+    try:
+        logger.info("Generating context for task=%s", task)
+
+        try:
+            task_enum: ContextTask = ContextTask(task.lower())
+        except ValueError:
+            msg = f"Invalid task: {task}. Valid tasks: {', '.join(t.value for t in ContextTask)}"
+            logger.exception(msg)
+            raise typer.Exit(code=1) from None
+
+        if scope not in ("merged", "separate"):
+            msg = f"Invalid scope: {scope}. Valid scopes: merged, separate"
+            logger.error(msg)
+            raise typer.Exit(code=1) from None
+
+        token_budget: TokenBudget = TokenBudget(max_tokens=_parse_budget(budget))
+        root: Path = Path.cwd()
+        output_path: Path = resolve_output_path(output)
+
+        input_paths: list[Path] = [root / p for p in paths] if paths else [root]
+
+        classifier: FileClassifier = FileClassifier()
+        collector: FileCollector = FileCollector(
+            a_extensions=_DEFAULT_EXTENSIONS,
+            a_exclude=DEFAULT_EXCLUDES,
+            a_classifier=classifier,
+        )
+        index: MemoryRepositoryIndex = MemoryRepositoryIndex()
+        analyzer: PythonAnalyzer = PythonAnalyzer()
+        planner: ContextPlanner = ContextPlanner(a_classifier=classifier)
+        materializer: ContextMaterializer = ContextMaterializer(a_analyzer=analyzer)
+        builder: ContextBuilder = ContextBuilder(
+            a_collector=collector,
+            a_index=index,
+            a_planner=planner,
+            a_materializer=materializer,
+        )
+
+        if group:
+            if scope != "merged":
+                logger.warning("--scope is ignored when --group is used")
+            for group_spec in group:
+                group_paths: list[Path] = [root / p.strip() for p in group_spec.split(",")]
+                for gp in group_paths:
+                    if not gp.exists():
+                        logger.error("Path does not exist: %s", gp)
+                        raise typer.Exit(code=1) from None
+                _run_group(builder, group_paths, task_enum, token_budget, query, root, output_path)
+
+        elif scope == "separate":
+            _run_separate(builder, input_paths, task_enum, token_budget, query, root, output_path, scope)
+        else:
+            _run_merged(builder, input_paths, task_enum, token_budget, query, root, output_path, scope, bool(paths))
+    finally:
+        if listener is not None:
+            listener.stop()

arian/domain/__init__.py

@@ -0,0 +1,51 @@
+"""Domain layer for Arian.
+
+Provides domain entities, enums, and exceptions.
+Zero external dependencies — only stdlib imports.
+"""
+
+from arian.domain.context import ContextChunk
+from arian.domain.context import ContextPlan
+from arian.domain.context import ContextResult
+from arian.domain.context import ContextTask
+from arian.domain.context import PlannedFile
+from arian.domain.exceptions import ContextBuilderError
+from arian.domain.exceptions import InputNotFoundError
+from arian.domain.exceptions import NoDocumentsError
+from arian.domain.exceptions import ProjectBaseError
+from arian.domain.protocols import LanguageAnalyzerProtocol
+from arian.domain.repository import Dependency
+from arian.domain.repository import FileContent
+from arian.domain.repository import Module
+from arian.domain.repository import Repository
+from arian.domain.repository import RepositoryFile
+from arian.domain.repository import Symbol
+from arian.domain.shared import CompressionLevel
+from arian.domain.shared import DependencyKind
+from arian.domain.shared import FileRole
+from arian.domain.shared import SymbolKind
+from arian.domain.shared import TokenBudget
+
+__all__ = [
+    "CompressionLevel",
+    "ContextBuilderError",
+    "ContextChunk",
+    "ContextPlan",
+    "ContextResult",
+    "ContextTask",
+    "Dependency",
+    "DependencyKind",
+    "FileContent",
+    "FileRole",
+    "InputNotFoundError",
+    "LanguageAnalyzerProtocol",
+    "Module",
+    "NoDocumentsError",
+    "PlannedFile",
+    "ProjectBaseError",
+    "Repository",
+    "RepositoryFile",
+    "Symbol",
+    "SymbolKind",
+    "TokenBudget",
+]