arc-cloud 0.1.0__py3-none-any.whl

arc_cloud/__init__.py

@@ -0,0 +1,4 @@
+"""ARC CLOUD CLI - Local, deterministic Software X-Ray scanner and Software Blueprint generator."""
+
+__version__ = "0.1.0"
+__app_name__ = "arc"

arc_cloud/blueprint/__init__.py

@@ -0,0 +1,35 @@
+"""Software Blueprint module for ARC CLOUD."""
+
+from arc_cloud.blueprint.generator import BlueprintGenerator
+from arc_cloud.blueprint.models import (
+    ArchitectureSummary,
+    Blueprint,
+    ConfigFileInfo,
+    DependencyInfo,
+    FrameworkMetric,
+    LanguageMetric,
+    PlatformInfo,
+    PlatformType,
+    ProjectInfo,
+    ProjectType,
+    ScannerMetadata,
+    StructureArea,
+    StructureInfo,
+)
+
+__all__ = [
+    "ArchitectureSummary",
+    "Blueprint",
+    "BlueprintGenerator",
+    "ConfigFileInfo",
+    "DependencyInfo",
+    "FrameworkMetric",
+    "LanguageMetric",
+    "PlatformInfo",
+    "PlatformType",
+    "ProjectInfo",
+    "ProjectType",
+    "ScannerMetadata",
+    "StructureArea",
+    "StructureInfo",
+]

arc_cloud/blueprint/generator.py

@@ -0,0 +1,89 @@
+"""Blueprint generator and serializer for ARC CLOUD CLI."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from arc_cloud.blueprint.models import (
+    ArchitectureSummary,
+    Blueprint,
+    ConfigFileInfo,
+    DependencyInfo,
+    FrameworkMetric,
+    LanguageMetric,
+    PlatformInfo,
+    ProjectInfo,
+    ProjectType,
+    ScannerMetadata,
+    StructureInfo,
+)
+
+
+class BlueprintGenerator:
+    """Generates a standardized Software Blueprint v1.0."""
+
+    @staticmethod
+    def create(
+        project_name: str,
+        project_type: ProjectType,
+        root_path: str,
+        languages: List[LanguageMetric],
+        frameworks: List[FrameworkMetric],
+        platforms: List[PlatformInfo],
+        dependencies: List[DependencyInfo],
+        configuration_files: List[ConfigFileInfo],
+        structure: StructureInfo,
+        architecture: ArchitectureSummary,
+        warnings: List[str],
+        duration_seconds: float,
+        files_scanned: int,
+        scanner_version: str = "0.1.0",
+        description: Optional[str] = None,
+    ) -> Blueprint:
+        scanner = ScannerMetadata(
+            name="ARC CLOUD CLI",
+            version=scanner_version,
+            duration_seconds=round(duration_seconds, 3),
+            files_scanned=files_scanned,
+        )
+
+        project = ProjectInfo(
+            name=project_name,
+            type=project_type,
+            root_path=root_path,
+            description=description,
+        )
+
+        return Blueprint(
+            schema_version="1.0",
+            scanner=scanner,
+            project=project,
+            languages=languages,
+            frameworks=frameworks,
+            platforms=platforms,
+            dependencies=dependencies,
+            configuration_files=configuration_files,
+            structure=structure,
+            architecture=architecture,
+            warnings=warnings,
+        )
+
+    @staticmethod
+    def to_json(blueprint: Blueprint, indent: int = 2) -> str:
+        """Serialize the blueprint model to a formatted JSON string."""
+        return blueprint.model_dump_json(indent=indent)
+
+    @staticmethod
+    def to_dict(blueprint: Blueprint) -> Dict[str, Any]:
+        """Serialize the blueprint model to a Python dictionary."""
+        return blueprint.model_dump(mode="json")
+
+    @staticmethod
+    def save_to_file(blueprint: Blueprint, output_path: str | Path) -> Path:
+        """Write the blueprint JSON to a specified file path."""
+        path = Path(output_path).resolve()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(BlueprintGenerator.to_json(blueprint), encoding="utf-8")
+        return path

arc_cloud/blueprint/models.py

@@ -0,0 +1,108 @@
+"""Pydantic data models for ARC CLOUD Software Blueprint schema v1.0."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class ProjectType(str, Enum):
+    MOBILE = "Mobile Application"
+    WEB = "Web Application"
+    BACKEND = "Backend"
+    FULL_STACK = "Full Stack"
+    DESKTOP = "Desktop Application"
+    LIBRARY = "Library"
+    CLI = "CLI Application"
+    UNKNOWN = "Unknown"
+
+
+class PlatformType(str, Enum):
+    ANDROID = "Android"
+    IOS = "iOS"
+    WEB = "Web"
+    WINDOWS = "Windows"
+    MACOS = "macOS"
+    LINUX = "Linux"
+
+
+class ProjectInfo(BaseModel):
+    name: str = Field(description="Name of the analyzed project")
+    type: ProjectType = Field(default=ProjectType.UNKNOWN, description="Classified project type")
+    root_path: Optional[str] = Field(default=None, description="Absolute or relative root path of the project")
+    description: Optional[str] = Field(default=None, description="Optional project description from manifest")
+
+
+class LanguageMetric(BaseModel):
+    name: str = Field(description="Programming language name")
+    files: int = Field(ge=0, description="Total number of files identified for this language")
+    percentage: float = Field(ge=0.0, le=100.0, description="Percentage of total code files")
+
+
+class FrameworkMetric(BaseModel):
+    name: str = Field(description="Framework name (e.g. Flutter, React, FastAPI)")
+    version: Optional[str] = Field(default=None, description="Detected framework version, if available")
+    category: Optional[str] = Field(default=None, description="Frontend, Backend, Mobile, Fullstack, etc.")
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0, description="Detection confidence score")
+
+
+class PlatformInfo(BaseModel):
+    name: PlatformType = Field(description="Target platform name")
+    source: Optional[str] = Field(default=None, description="Directory or configuration that confirmed the platform")
+
+
+class DependencyInfo(BaseModel):
+    name: str = Field(description="Dependency package name")
+    version: Optional[str] = Field(default=None, description="Version specifier or pinned version")
+    source: str = Field(description="Manifest file source (e.g. package.json, requirements.txt)")
+    type: Optional[str] = Field(default="runtime", description="Dependency type: runtime, dev, peer, test")
+
+
+class ConfigFileInfo(BaseModel):
+    path: str = Field(description="Relative path to configuration file")
+    name: str = Field(description="Filename of the configuration")
+    type: str = Field(description="Category of config, e.g. package, docker, build, git, documentation")
+
+
+class StructureArea(BaseModel):
+    name: str = Field(description="Functional area, e.g. source, tests, assets, platform, docs, config")
+    paths: List[str] = Field(default_factory=list, description="Relative paths belonging to this area")
+
+
+class StructureInfo(BaseModel):
+    areas: List[StructureArea] = Field(default_factory=list, description="Classified functional directory areas")
+    total_files: int = Field(default=0, ge=0, description="Total scanned files considered")
+    total_directories: int = Field(default=0, ge=0, description="Total directories visited")
+    ignored_directories: List[str] = Field(default_factory=list, description="Ignored directory names detected")
+
+
+class ArchitectureSummary(BaseModel):
+    patterns: List[str] = Field(default_factory=list, description="Detected architectural patterns or indicators")
+    details: Dict[str, Any] = Field(default_factory=dict, description="Structural indicators and metadata")
+
+
+class ScannerMetadata(BaseModel):
+    name: str = Field(default="ARC CLOUD CLI", description="Name of the scanner engine")
+    version: str = Field(default="0.1.0", description="Scanner CLI version")
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Scan completion timestamp in UTC"
+    )
+    duration_seconds: float = Field(default=0.0, ge=0.0, description="Total scan execution duration in seconds")
+    files_scanned: int = Field(default=0, ge=0, description="Count of files analyzed")
+
+
+class Blueprint(BaseModel):
+    schema_version: str = Field(default="1.0", description="Software Blueprint schema version")
+    scanner: ScannerMetadata = Field(default_factory=ScannerMetadata)
+    project: ProjectInfo
+    languages: List[LanguageMetric] = Field(default_factory=list)
+    frameworks: List[FrameworkMetric] = Field(default_factory=list)
+    platforms: List[PlatformInfo] = Field(default_factory=list)
+    dependencies: List[DependencyInfo] = Field(default_factory=list)
+    configuration_files: List[ConfigFileInfo] = Field(default_factory=list)
+    structure: StructureInfo = Field(default_factory=StructureInfo)
+    architecture: ArchitectureSummary = Field(default_factory=ArchitectureSummary)
+    warnings: List[str] = Field(default_factory=list)

arc_cloud/commands/__init__.py

@@ -0,0 +1,5 @@
+"""CLI command modules for ARC CLOUD."""
+
+from arc_cloud.commands.scan import scan_command
+
+__all__ = ["scan_command"]

arc_cloud/commands/scan.py

@@ -0,0 +1,177 @@
+"""The 'scan' command for ARC CLOUD CLI."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from arc_cloud.blueprint.generator import BlueprintGenerator
+from arc_cloud.blueprint.models import Blueprint
+from arc_cloud.scanner.engine import ScannerEngine
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def scan_command(
+    path: Optional[str] = typer.Argument(
+        None,
+        help="Path to the software project to analyze (defaults to current working directory).",
+        show_default=False,
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Output the normalized Software Blueprint as raw JSON to stdout.",
+    ),
+    output_file: Optional[str] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Save the normalized Software Blueprint JSON to a specified file.",
+    ),
+    max_files: int = typer.Option(
+        20_000,
+        "--max-files",
+        help="Maximum number of files to inspect before stopping.",
+    ),
+    max_depth: int = typer.Option(
+        20,
+        "--max-depth",
+        help="Maximum directory recursion depth to traverse.",
+    ),
+) -> None:
+    """Analyze a software project statically and generate a Software Blueprint."""
+    target_path = Path(path).resolve() if path else Path.cwd()
+
+    # Pre-flight path validations
+    if not target_path.exists():
+        err_console.print(f"[bold red]✗ Error:[/bold red] Project path does not exist: '{target_path}'")
+        raise typer.Exit(code=1)
+
+    if not target_path.is_dir():
+        err_console.print(f"[bold red]✗ Error:[/bold red] Project path is not a directory: '{target_path}'")
+        raise typer.Exit(code=1)
+
+    engine = ScannerEngine(max_files=max_files, max_depth=max_depth)
+
+    try:
+        blueprint = engine.scan(target_path)
+    except PermissionError as exc:
+        err_console.print(f"[bold red]✗ Permission Error:[/bold red] Unable to read project directory: {exc}")
+        raise typer.Exit(code=1)
+    except Exception as exc:
+        err_console.print(f"[bold red]✗ Scan Failed:[/bold red] An unexpected error occurred: {exc}")
+        raise typer.Exit(code=1)
+
+    # Save to file if requested
+    if output_file:
+        try:
+            saved_path = BlueprintGenerator.save_to_file(blueprint, output_file)
+            if not json_output:
+                console.print(f"[bold green]✓[/bold green] Blueprint written to [cyan]{output_file}[/cyan]\n")
+        except Exception as exc:
+            err_console.print(f"[bold red]✗ Error saving blueprint:[/bold red] {exc}")
+            raise typer.Exit(code=1)
+
+    # Handle raw JSON output
+    if json_output:
+        print(BlueprintGenerator.to_json(blueprint))
+        return
+
+    # Render professional Rich Terminal UI
+    _render_rich_report(blueprint)
+
+
+def _render_rich_report(blueprint: Blueprint) -> None:
+    """Renders the Software X-Ray report using Rich."""
+    console.print()
+    console.rule("[bold cyan]ARC CLOUD SOFTWARE X-RAY[/bold cyan]", style="cyan")
+    console.print()
+
+    # 1. Project Summary
+    summary_table = Table(box=None, show_header=False, padding=(0, 2))
+    summary_table.add_column("Key", style="bold white", width=12)
+    summary_table.add_column("Value", style="cyan")
+    summary_table.add_row("Name:", f"[bold white]{blueprint.project.name}[/bold white]")
+    summary_table.add_row("Type:", f"[bold green]{blueprint.project.type.value}[/bold green]")
+    summary_table.add_row("Files:", f"{blueprint.scanner.files_scanned:,}")
+    if blueprint.scanner.duration_seconds > 0:
+        summary_table.add_row("Duration:", f"{blueprint.scanner.duration_seconds:.2f}s")
+    console.print(Panel(summary_table, title="[bold]Project Summary[/bold]", border_style="dim"))
+
+    # 2. Languages & Frameworks Side-by-Side or Sequential
+    lang_table = Table(title="Languages", title_style="bold magenta", box=None, padding=(0, 2))
+    lang_table.add_column("Language", style="bold")
+    lang_table.add_column("Files", justify="right", style="dim")
+    lang_table.add_column("Share", justify="right", style="magenta")
+
+    if blueprint.languages:
+        for lang in blueprint.languages[:7]:  # Top 7 languages
+            lang_table.add_row(lang.name, str(lang.files), f"{lang.percentage}%")
+    else:
+        lang_table.add_row("[dim]None detected[/dim]", "-", "-")
+
+    console.print(lang_table)
+    console.print()
+
+    # 3. Frameworks & Platforms
+    fw_plat_table = Table(box=None, show_header=False, padding=(0, 2))
+    fw_plat_table.add_column("Category", style="bold yellow", width=14)
+    fw_plat_table.add_column("Details", style="white")
+
+    if blueprint.frameworks:
+        fw_list = ", ".join(f"{f.name}" + (f" ({f.version})" if f.version else "") for f in blueprint.frameworks)
+        fw_plat_table.add_row("Frameworks:", fw_list)
+    else:
+        fw_plat_table.add_row("Frameworks:", "[dim]None detected[/dim]")
+
+    if blueprint.platforms:
+        plat_list = ", ".join(p.name.value for p in blueprint.platforms)
+        fw_plat_table.add_row("Platforms:", plat_list)
+    else:
+        fw_plat_table.add_row("Platforms:", "[dim]Generic / Agnostic[/dim]")
+
+    dep_count = len(blueprint.dependencies)
+    fw_plat_table.add_row("Dependencies:", f"[bold]{dep_count}[/bold] identified")
+
+    console.print(Panel(fw_plat_table, title="[bold]Ecosystem & Stack[/bold]", border_style="dim"))
+
+    # 4. Structure Areas
+    if blueprint.structure.areas:
+        struct_table = Table(title="Structure Classification", title_style="bold blue", box=None, padding=(0, 2))
+        struct_table.add_column("Area", style="bold")
+        struct_table.add_column("Directories", style="dim")
+        for area in blueprint.structure.areas:
+            display_paths = ", ".join(area.paths[:4])
+            if len(area.paths) > 4:
+                display_paths += f" (+{len(area.paths) - 4} more)"
+            struct_table.add_row(area.name.capitalize(), display_paths)
+        console.print(struct_table)
+        console.print()
+
+    # 5. Architecture Summary
+    if blueprint.architecture.patterns:
+        arch_text = Text(", ".join(blueprint.architecture.patterns), style="green")
+        console.print(f"[bold]Architecture Patterns:[/bold] {arch_text}\n")
+
+    # 6. Warnings
+    if blueprint.warnings:
+        console.print("[bold yellow]Warnings:[/bold yellow]")
+        for warn in blueprint.warnings:
+            console.print(f"  [yellow]{warn}[/yellow]")
+        console.print()
+
+    # Footer rule
+    console.rule(
+        f"[bold green]✓ Scan completed in {blueprint.scanner.duration_seconds:.2f} seconds[/bold green]",
+        style="green",
+    )
+    console.print()

arc_cloud/main.py

@@ -0,0 +1,48 @@
+"""Main entry point for ARC CLOUD CLI."""
+
+from __future__ import annotations
+
+from typing import Optional
+import typer
+from rich.console import Console
+
+from arc_cloud import __app_name__, __version__
+from arc_cloud.commands.scan import scan_command
+
+console = Console()
+
+app = typer.Typer(
+    name=__app_name__,
+    help="ARC CLOUD CLI — Local, deterministic Software X-Ray scanner and Software Blueprint generator.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+# Register primary command
+app.command(name="scan", help="Analyze a software project statically and generate a Software Blueprint.")(scan_command)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"[bold cyan]{__app_name__}[/bold cyan] version [green]{__version__}[/green]")
+        raise typer.Exit()
+
+
+
+@app.callback()
+def main(
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version",
+        "-v",
+        help="Show ARC CLOUD CLI version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    )
+) -> None:
+    """ARC CLOUD — Software X-Ray platform."""
+    pass
+
+
+if __name__ == "__main__":
+    app()

arc_cloud/scanner/__init__.py

@@ -0,0 +1,41 @@
+"""Scanner engine and detector modules for ARC CLOUD CLI."""
+
+from arc_cloud.scanner.config_detector import ConfigDetector
+from arc_cloud.scanner.dependencies import DependencyDetector
+from arc_cloud.scanner.engine import ScannerEngine
+from arc_cloud.scanner.frameworks import (
+    BaseFrameworkDetector,
+    DjangoDetector,
+    DotNetDetector,
+    FastAPIDetector,
+    FlutterDetector,
+    FrameworkRegistry,
+    NextJsDetector,
+    NodeJsDetector,
+    ReactDetector,
+    ScanContext,
+    SpringBootDetector,
+)
+from arc_cloud.scanner.languages import LanguageDetector
+from arc_cloud.scanner.platforms import PlatformDetector
+from arc_cloud.scanner.structure import StructureAnalyzer
+
+__all__ = [
+    "BaseFrameworkDetector",
+    "ConfigDetector",
+    "DependencyDetector",
+    "DjangoDetector",
+    "DotNetDetector",
+    "FastAPIDetector",
+    "FlutterDetector",
+    "FrameworkRegistry",
+    "LanguageDetector",
+    "NextJsDetector",
+    "NodeJsDetector",
+    "PlatformDetector",
+    "ReactDetector",
+    "ScanContext",
+    "ScannerEngine",
+    "SpringBootDetector",
+    "StructureAnalyzer",
+]

arc_cloud/scanner/config_detector.py

@@ -0,0 +1,54 @@
+"""Configuration file detector for ARC CLOUD CLI."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import List
+
+from arc_cloud.blueprint.models import ConfigFileInfo
+
+# Recognized configuration patterns and categories
+KNOWN_CONFIG_PATTERNS = [
+    (r"^pubspec\.ya?ml$", "package", "Dart/Flutter Package Spec"),
+    (r"^package\.json$", "package", "Node.js Package Manifest"),
+    (r"^tsconfig.*\.json$", "build", "TypeScript Configuration"),
+    (r"^next\.config\.[mc]?[jt]s$", "framework", "Next.js Configuration"),
+    (r"^vite\.config\.[mc]?[jt]s$", "build", "Vite Configuration"),
+    (r"^requirements.*\.txt$", "package", "Python Requirements"),
+    (r"^pyproject\.toml$", "package", "Python Project Configuration"),
+    (r"^Pipfile(\.lock)?$", "package", "Pipenv Manifest"),
+    (r"^pom\.xml$", "build", "Maven Build Descriptor"),
+    (r"^(build|settings)\.gradle(\.kts)?$", "build", "Gradle Build Script"),
+    (r"^.*\.csproj$", "build", "C# Project Configuration"),
+    (r"^.*\.sln$", "build", ".NET Solution File"),
+    (r"^(Dockerfile.*|docker-compose.*\.ya?ml)$", "container", "Docker Configuration"),
+    (r"^\.gitignore$", "git", "Git Ignore Rules"),
+    (r"^README(\.md|\.rst|\.txt)?$", "documentation", "Project Documentation"),
+]
+
+
+class ConfigDetector:
+    """Detects important configuration and manifest files in the project."""
+
+    @staticmethod
+    def detect(relative_files: List[str]) -> List[ConfigFileInfo]:
+        detected: List[ConfigFileInfo] = []
+        seen_paths = set()
+
+        for rel_file in relative_files:
+            file_name = Path(rel_file).name
+            for pattern, cat, _desc in KNOWN_CONFIG_PATTERNS:
+                if re.match(pattern, file_name, re.IGNORECASE):
+                    if rel_file not in seen_paths:
+                        seen_paths.add(rel_file)
+                        detected.append(
+                            ConfigFileInfo(
+                                path=rel_file,
+                                name=file_name,
+                                type=cat,
+                            )
+                        )
+                    break
+
+        return sorted(detected, key=lambda c: (c.type, c.path))