archapi 0.3.0__tar.gz

archapi-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohith Chikkala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files, to deal in the Software
+without restriction, including without limitation the rights to use, copy,
+modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

archapi-0.3.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: archapi
+Version: 0.3.0
+Summary: Architecture-preserving REST API synthesis library
+Author: ArchAPI Research Team
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rohith5005/archapi
+Project-URL: Repository, https://github.com/rohith5005/archapi
+Project-URL: Issues, https://github.com/rohith5005/archapi/issues
+Keywords: rest-api,code-generation,architecture,express,fastapi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ArchAPI
+
+ArchAPI is a Python library for architecture-preserving REST API generation.
+
+It scans an existing backend project, detects the framework, understands the project structure, plans a REST API, generates framework-specific files, validates the output, and writes files only when explicitly requested.
+
+---
+
+## Current Status
+
+Current checkpoint: **Phase 3 complete**
+
+Completed:
+
+- Functional Python package
+- Express TypeScript adapter
+- FastAPI adapter
+- Generic fallback adapter
+- Framework detection
+- Project scanning
+- API architecture model
+- Confidence scoring
+- Low-confidence blocking
+- Strict config mode
+- REST intent planner
+- Code generation
+- Dry-run generation
+- Safe apply
+- Overwrite protection
+- Cache and changed-file detection
+- Secret scanner
+- Context redaction
+- Policy gate
+- Architecture consistency score
+- Command validation
+- Unified regression test suite
+
+---
+
+## Supported Frameworks
+
+Dedicated generation support currently exists for:
+
+- Express TypeScript
+- FastAPI
+
+Other frameworks may be detected, but they currently use the generic fallback adapter.
+
+---
+
+## Installation
+
+From the project root:
+
+```bash
+pip install -e .

archapi-0.3.0/README.md

@@ -0,0 +1,56 @@
+# ArchAPI
+
+ArchAPI is a Python library for architecture-preserving REST API generation.
+
+It scans an existing backend project, detects the framework, understands the project structure, plans a REST API, generates framework-specific files, validates the output, and writes files only when explicitly requested.
+
+---
+
+## Current Status
+
+Current checkpoint: **Phase 3 complete**
+
+Completed:
+
+- Functional Python package
+- Express TypeScript adapter
+- FastAPI adapter
+- Generic fallback adapter
+- Framework detection
+- Project scanning
+- API architecture model
+- Confidence scoring
+- Low-confidence blocking
+- Strict config mode
+- REST intent planner
+- Code generation
+- Dry-run generation
+- Safe apply
+- Overwrite protection
+- Cache and changed-file detection
+- Secret scanner
+- Context redaction
+- Policy gate
+- Architecture consistency score
+- Command validation
+- Unified regression test suite
+
+---
+
+## Supported Frameworks
+
+Dedicated generation support currently exists for:
+
+- Express TypeScript
+- FastAPI
+
+Other frameworks may be detected, but they currently use the generic fallback adapter.
+
+---
+
+## Installation
+
+From the project root:
+
+```bash
+pip install -e .

archapi-0.3.0/archapi/__init__.py

@@ -0,0 +1,3 @@
+from archapi.core import ArchAPI
+
+__all__ = ["ArchAPI"]

archapi-0.3.0/archapi/core.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+from archapi.frameworks.detector import FrameworkDetector
+from archapi.frameworks.registry import FrameworkRegistry
+from archapi.indexing.cache import CacheManager
+from archapi.security.secret_scanner import SecretScanner
+from archapi.security.context_redactor import ContextRedactor
+from archapi.security.policy_gate import PolicyGate
+from archapi.validation.architecture_score import ArchitectureConsistencyScorer
+from archapi.validation.command_validator import CommandValidator
+from archapi.types import (
+    APIGenome,
+    APIPlan,
+    DetectionResult,
+    GenerationResult,
+    ScanResult,
+)
+
+
+class ArchAPI:
+    def __init__(self, project_path: Union[str, Path], framework: Optional[str] = None, config: Optional[Dict[str, Any]] = None):
+        self.project_path = Path(project_path).resolve()
+        if not self.project_path.exists():
+            raise FileNotFoundError(f"Project path does not exist: {self.project_path}")
+
+        self._framework_override = framework
+        self._config = config or {}
+        self._detector = FrameworkDetector()
+        self._registry = FrameworkRegistry()
+        self._cache = CacheManager(self.project_path)
+        self._secret_scanner = SecretScanner(self.project_path)
+        self._context_redactor = ContextRedactor()
+        self._policy_gate = PolicyGate()
+        self._architecture_scorer = ArchitectureConsistencyScorer()
+        self._command_validator = CommandValidator(self.project_path)
+
+        self._detection: Optional[DetectionResult] = None
+        self._scan: Optional[ScanResult] = None
+        self._maps: Optional[Dict[str, Any]] = None
+        self._genome: Optional[APIGenome] = None
+
+    def detect_framework(self) -> DetectionResult:
+        if self._framework_override:
+            self._detection = DetectionResult(
+                framework=self._framework_override,
+                confidence=1.0,
+                reasons=["Framework explicitly provided"],
+            )
+            return self._detection
+
+        self._detection = self._detector.detect(self.project_path)
+        return self._detection
+
+    def _adapter(self):
+        detection = self._detection or self.detect_framework()
+        return self._registry.get(detection.framework)
+
+    def _has_config_hints(self) -> bool:
+        hint_keys = {
+            "route_dir",
+            "controller_dir",
+            "service_dir",
+            "model_dir",
+            "schema_dir",
+            "middleware_dir",
+            "test_dir",
+        }
+        return any(key in self._config for key in hint_keys)
+
+    def scan(self) -> ScanResult:
+        detection = self._detection or self.detect_framework()
+
+        # Strict config mode:
+        # If user provides architecture hints, scan ONLY those hinted directories.
+        # This prevents accidental scanning of the library repo, sample projects,
+        # caches, or unrelated test files.
+        if self._has_config_hints():
+            self._scan = ScanResult(
+                framework=detection.framework,
+                project_path=self.project_path,
+            )
+            self._apply_config_hints_to_scan(self._scan)
+            return self._scan
+
+        adapter = self._adapter()
+        self._scan = adapter.scan(self.project_path)
+        self._scan.framework = detection.framework
+        return self._scan
+
+    def _apply_config_hints_to_scan(self, scan: ScanResult) -> None:
+        """
+        Applies user-provided architecture hints.
+
+        Supported config keys:
+        - route_dir
+        - controller_dir
+        - service_dir
+        - model_dir
+        - schema_dir
+        - middleware_dir
+        - test_dir
+        """
+
+        hint_map = {
+            "route_dir": scan.routes,
+            "controller_dir": scan.controllers,
+            "service_dir": scan.services,
+            "model_dir": scan.models,
+            "schema_dir": scan.schemas,
+            "middleware_dir": scan.middleware,
+            "test_dir": scan.tests,
+        }
+
+        ignored_parts = {
+            ".git",
+            ".venv",
+            "node_modules",
+            "dist",
+            "build",
+            "coverage",
+            "__pycache__",
+            ".archapi",
+            "archapi.egg-info",
+        }
+
+        for config_key, target_list in hint_map.items():
+            raw_dir = self._config.get(config_key)
+            if not raw_dir:
+                continue
+
+            hint_path = (self.project_path / raw_dir).resolve()
+
+            if not hint_path.exists() or not hint_path.is_dir():
+                continue
+
+            for file_path in hint_path.rglob("*"):
+                if not file_path.is_file():
+                    continue
+
+                try:
+                    rel_parts = file_path.relative_to(self.project_path).parts
+                except ValueError:
+                    rel_parts = file_path.parts
+
+                if any(part in ignored_parts for part in rel_parts):
+                    continue
+
+                if file_path not in target_list:
+                    target_list.append(file_path)
+
+    def config(self) -> Dict[str, Any]:
+        return dict(self._config)
+
+    def build_maps(self) -> Dict[str, Any]:
+        scan = self._scan or self.scan()
+        adapter = self._adapter()
+        self._maps = adapter.build_maps(scan)
+        return self._maps
+
+    def extract_genome(self) -> APIGenome:
+        scan = self._scan or self.scan()
+        maps = self._maps or self.build_maps()
+        adapter = self._adapter()
+        self._genome = adapter.extract_genome(maps, scan)
+        self._genome.framework = (self._detection or self.detect_framework()).framework
+        return self._genome
+
+    def compute_confidence(self) -> Dict[str, Any]:
+        detection = self._detection or self.detect_framework()
+        genome = self._genome or self.extract_genome()
+
+        missing = []
+
+        if genome.route_style == "unknown":
+            missing.append("route style")
+        if genome.controller_style == "unknown":
+            missing.append("controller style")
+        if genome.service_style == "unknown":
+            missing.append("service style")
+        if genome.schema_style == "unknown":
+            missing.append("schema style")
+
+        # Overall confidence should consider BOTH:
+        # 1. framework detection confidence
+        # 2. API architecture/genome confidence
+        #
+        # This prevents generic/unknown projects from being treated as safe
+        # just because some folders accidentally look like routes/services.
+        overall = round(min(detection.confidence, genome.confidence), 2)
+
+        mode = "generate"
+
+        if detection.framework in {"generic", "node-unknown"}:
+            mode = "blocked"
+        elif overall < 0.30:
+            mode = "blocked"
+        elif overall < 0.55:
+            mode = "plan_only"
+        elif overall < 0.75:
+            mode = "generate_with_warnings"
+
+        return {
+            "overall": overall,
+            "detection_confidence": detection.confidence,
+            "genome_confidence": genome.confidence,
+            "mode": mode,
+            "missing": missing,
+            "framework": genome.framework,
+        }
+
+    def plan_api(self, request: str) -> APIPlan:
+        maps = self._maps or self.build_maps()
+        genome = self._genome or self.extract_genome()
+        adapter = self._adapter()
+
+        plan = adapter.plan_api(request, genome, maps)
+        confidence = self.compute_confidence()
+
+        if confidence["mode"] in {"blocked", "plan_only"}:
+            plan.generation_allowed = False
+
+            if confidence["framework"] in {"generic", "node-unknown"}:
+                plan.reason = (
+                    "Framework could not be confidently detected. "
+                    "Provide framework or config before generation."
+                )
+            else:
+                plan.reason = (
+                    "Architecture confidence too low for code generation. "
+                    f"Missing: {', '.join(confidence['missing']) or 'unknown'}"
+                )
+
+        return plan
+
+    def save_cache(self) -> Dict[str, Path]:
+        detection = self._detection or self.detect_framework()
+        scan = self._scan or self.scan()
+        maps = self._maps or self.build_maps()
+        genome = self._genome or self.extract_genome()
+
+        return self._cache.save_snapshot(
+            detection=detection,
+            scan=scan,
+            maps=maps,
+            genome=genome,
+        )
+
+    def changed_files(self) -> list:
+        return self._cache.changed_files()
+
+    def scan_secrets(self):
+        return self._secret_scanner.scan()
+
+    def redact_context(self, text: str) -> str:
+        return self._context_redactor.redact(text)
+
+    def validate_policy(self, result: GenerationResult):
+        return self._policy_gate.validate_result(result)
+
+    def score_architecture(self, result: GenerationResult):
+        genome = self._genome or self.extract_genome()
+        return self._architecture_scorer.score(result.files, genome)
+
+    def validate_project_commands(self):
+        detection = self._detection or self.detect_framework()
+
+        if detection.framework in {"express-typescript", "nestjs", "node-unknown"}:
+            return self._command_validator.validate_node_project()
+
+        return self._command_validator.validate_node_project()
+
+    def generate_api(self, request: str, dry_run: bool = True) -> GenerationResult:
+        maps = self._maps or self.build_maps()
+        genome = self._genome or self.extract_genome()
+        plan = self.plan_api(request)
+
+        adapter = self._adapter()
+        files = adapter.generate_code(plan, genome, maps)
+        report = adapter.validate_generated_code(files, plan, genome)
+
+        result = GenerationResult(
+            project_path=self.project_path,
+            plan=plan,
+            files=files,
+            validation_report=report,
+            warnings=report.warnings,
+        )
+
+        if not dry_run and report.success:
+            result.apply()
+
+        return result

archapi-0.3.0/archapi/frameworks/base.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, List
+
+from archapi.types import (
+    APIPlan,
+    APIGenome,
+    DetectionResult,
+    GeneratedFile,
+    ScanResult,
+    ValidationReport,
+)
+
+
+class FrameworkAdapter(ABC):
+    name: str = "unknown"
+
+    @abstractmethod
+    def detect(self, project_path: Path) -> DetectionResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def scan(self, project_path: Path) -> ScanResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def build_maps(self, scan_result: ScanResult) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def extract_genome(self, maps: Dict[str, Any], scan_result: ScanResult) -> APIGenome:
+        raise NotImplementedError
+
+    @abstractmethod
+    def plan_api(self, request: str, genome: APIGenome, maps: Dict[str, Any]) -> APIPlan:
+        raise NotImplementedError
+
+    @abstractmethod
+    def generate_code(
+        self,
+        plan: APIPlan,
+        genome: APIGenome,
+        maps: Dict[str, Any],
+    ) -> List[GeneratedFile]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def validate_generated_code(
+        self,
+        files: List[GeneratedFile],
+        plan: APIPlan,
+        genome: APIGenome,
+    ) -> ValidationReport:
+        raise NotImplementedError

archapi-0.3.0/archapi/frameworks/detector.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import List
+
+from archapi.types import DetectionResult
+
+
+class FrameworkDetector:
+    def detect(self, project_path: Path) -> DetectionResult:
+        candidates: List[DetectionResult] = []
+
+        package_json = project_path / "package.json"
+        if package_json.exists():
+            try:
+                data = json.loads(package_json.read_text(encoding="utf-8"))
+                deps = {}
+                deps.update(data.get("dependencies", {}))
+                deps.update(data.get("devDependencies", {}))
+
+                if "@nestjs/core" in deps:
+                    candidates.append(
+                        DetectionResult("nestjs", 0.95, ["package.json contains @nestjs/core"])
+                    )
+
+                if "express" in deps:
+                    candidates.append(
+                        DetectionResult("express-typescript", 0.85, ["package.json contains express"])
+                    )
+            except Exception:
+                candidates.append(
+                    DetectionResult("node-unknown", 0.30, ["package.json exists but could not be parsed"])
+                )
+
+        if (project_path / "manage.py").exists():
+            candidates.append(
+                DetectionResult("django-drf", 0.75, ["manage.py detected"])
+            )
+
+        py_text = ""
+        pyproject = project_path / "pyproject.toml"
+        requirements = project_path / "requirements.txt"
+
+        if pyproject.exists():
+            py_text += pyproject.read_text(encoding="utf-8", errors="ignore").lower()
+
+        if requirements.exists():
+            py_text += requirements.read_text(encoding="utf-8", errors="ignore").lower()
+
+        if "fastapi" in py_text:
+            candidates.append(
+                DetectionResult("fastapi", 0.90, ["fastapi dependency detected"])
+            )
+
+        if "flask" in py_text:
+            candidates.append(
+                DetectionResult("flask", 0.85, ["flask dependency detected"])
+            )
+
+        if (project_path / "pom.xml").exists() or (project_path / "build.gradle").exists():
+            candidates.append(
+                DetectionResult("spring-boot", 0.70, ["Java build file detected"])
+            )
+
+        if list(project_path.glob("*.csproj")):
+            candidates.append(
+                DetectionResult("dotnet-core", 0.75, [".csproj file detected"])
+            )
+
+        if (project_path / "composer.json").exists():
+            composer = (project_path / "composer.json").read_text(
+                encoding="utf-8",
+                errors="ignore",
+            ).lower()
+            if "laravel" in composer:
+                candidates.append(
+                    DetectionResult("laravel", 0.90, ["composer.json contains laravel"])
+                )
+
+        if (project_path / "Gemfile").exists():
+            gemfile = (project_path / "Gemfile").read_text(
+                encoding="utf-8",
+                errors="ignore",
+            ).lower()
+            if "rails" in gemfile:
+                candidates.append(
+                    DetectionResult("rails", 0.90, ["Gemfile contains rails"])
+                )
+
+        if (project_path / "go.mod").exists():
+            go_mod = (project_path / "go.mod").read_text(
+                encoding="utf-8",
+                errors="ignore",
+            ).lower()
+
+            if "gin-gonic/gin" in go_mod or "gofiber/fiber" in go_mod:
+                candidates.append(
+                    DetectionResult("go-api", 0.85, ["go.mod contains Gin or Fiber"])
+                )
+            else:
+                candidates.append(
+                    DetectionResult("go-api", 0.55, ["go.mod detected"])
+                )
+
+        if not candidates:
+            return DetectionResult(
+                framework="generic",
+                confidence=0.10,
+                reasons=["No known framework markers detected"],
+            )
+
+        return sorted(candidates, key=lambda item: item.confidence, reverse=True)[0]