ansede-static 1.2.0__py3-none-any.whl

ansede_static/__init__.py

@@ -0,0 +1,90 @@
+"""
+ansede_static
+─────────────
+Zero-dependency SAST security scanner for Python and JavaScript.
+
+Quick start:
+    from ansede_static import scan_file, scan_code
+
+    result = scan_file("myapp.py")
+    for finding in result.sorted_findings():
+        print(finding.severity.value, finding.title, finding.line)
+"""
+from __future__ import annotations
+
+from ansede_static._types import AnalysisResult, Finding, Severity
+from ansede_static.config import AnsedeConfig, apply_config_to_results, temporary_analyzer_config
+from ansede_static.engine_version import SCHEMA_VERSION, get_engine_version
+from ansede_static.python_analyzer import analyze_python, analyze_file as _py_file
+from ansede_static.js_engine.backends import list_js_backends, run_js_analysis
+
+from pathlib import Path
+
+
+__all__ = [
+    "scan_file",
+    "scan_code",
+    "AnalysisResult",
+    "AnsedeConfig",
+    "Finding",
+    "Severity",
+    "SCHEMA_VERSION",
+    "list_js_backends",
+]
+
+__version__ = get_engine_version()
+
+
+_PYTHON_EXTS = frozenset({".py", ".pyi", ".pyw"})
+_JS_EXTS     = frozenset({".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"})
+
+
+def scan_file(path: str | Path, config: AnsedeConfig | None = None, *, js_backend: str = "auto") -> AnalysisResult:
+    """
+    Scan a file and return an AnalysisResult.
+
+    Language is detected from the file extension.
+    Raises ValueError for unsupported file types.
+    """
+    p = Path(path)
+    ext = p.suffix.lower()
+    with temporary_analyzer_config(config):
+        if ext in _PYTHON_EXTS:
+            result = _py_file(p)
+        elif ext in _JS_EXTS:
+            code = p.read_text(encoding="utf-8", errors="replace")
+            result, _ = run_js_analysis(code, filename=str(p), requested_backend=js_backend)
+        else:
+            raise ValueError(f"Unsupported file extension: {ext!r}. Supported: .py, .js, .ts (and variants).")
+    apply_config_to_results([result], config)
+    return result
+
+
+def scan_code(
+    code: str,
+    language: str,
+    filename: str = "",
+    config: AnsedeConfig | None = None,
+    *,
+    js_backend: str = "auto",
+) -> AnalysisResult:
+    """
+    Scan source code provided as a string.
+
+    Args:
+        code:     Source code.
+        language: "python" or "javascript".
+        filename: Optional file name for error messages.
+
+    Raises:
+        ValueError: if language is not supported.
+    """
+    with temporary_analyzer_config(config):
+        if language == "python":
+            result = analyze_python(code, filename=filename)
+        elif language in ("javascript", "typescript", "js", "ts"):
+            result, _ = run_js_analysis(code, filename=filename, requested_backend=js_backend)
+        else:
+            raise ValueError(f"Unsupported language: {language!r}. Must be 'python' or 'javascript'.")
+    apply_config_to_results([result], config)
+    return result

ansede_static/_types.py

@@ -0,0 +1,178 @@
+"""
+ansede_static._types
+────────────────────
+Shared data types for the Ansede Static analyzer.
+Zero external dependencies — pure stdlib only.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+    @property
+    def sort_key(self) -> int:
+        return {"critical": 0, "high": 1, "medium": 2, "low": 3, "info": 4}[self.value]
+
+    @property
+    def badge(self) -> str:
+        return {"critical": "[CRIT]", "high": "[HIGH]", "medium": "[MEDI]",
+                "low": "[LOW ]", "info": "[INFO]"}[self.value]
+
+
+@dataclass(frozen=True)
+class TraceFrame:
+    """A single source/propagation/sink step for a finding trace."""
+    kind: str
+    label: str
+    line: int | None = None
+    start_column: int = 1
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "label": self.label,
+            "line": self.line,
+            "start_column": self.start_column,
+        }
+
+
+@dataclass
+class Finding:
+    """A single security or quality finding."""
+    category: str         # "security" | "bug" | "error-handling" | "architecture"
+    severity: Severity
+    title: str            # one-line summary
+    description: str      # detailed explanation
+    line: int | None = None
+    suggestion: str = ""  # concrete fix
+    rule_id: str = ""     # stable analyzer-specific rule id, e.g. "PY-004"
+    cwe: str = ""         # e.g. "CWE-89"
+    agent: str = ""       # "python-analyzer" | "js-analyzer"
+    confidence: float = 1.0
+    auto_fix: str = ""    # before→after code suggestion
+    explanation: str = "" # educational markdown tutorial
+    trace: tuple[TraceFrame, ...] = ()
+    analysis_kind: str = "pattern"
+    triggering_code: str = ""  # source line that triggered the finding
+
+    @property
+    def finding_class(self) -> str:
+        """Coarse-grained class used to separate security from quality findings."""
+        if self.cwe or self.category == "security":
+            return "security"
+        return "quality"
+
+    @property
+    def effective_rule_id(self) -> str:
+        """Return the best available stable rule identifier for downstream tooling."""
+        return self.rule_id or self.cwe or self.title
+
+    def as_dict(self, *, language: str | None = None) -> dict[str, Any]:
+        from ansede_static.rules import rule_record_for_finding
+
+        return {
+            "severity": self.severity.value,
+            "title": self.title,
+            "description": self.description,
+            "line": self.line,
+            "suggestion": self.suggestion,
+            "rule_id": self.rule_id,
+            "cwe": self.cwe,
+            "category": self.category,
+            "finding_class": self.finding_class,
+            "agent": self.agent,
+            "confidence": self.confidence,
+            "auto_fix": self.auto_fix,
+            "explanation": self.explanation,
+            "analysis_kind": self.analysis_kind,
+            "trace": [frame.as_dict() for frame in self.trace],
+            "rule": rule_record_for_finding(
+                self.rule_id,
+                cwe=self.cwe,
+                title=self.title,
+                category=self.category,
+                severity=self.severity.value,
+                language=language,
+            ),
+        }
+
+
+@dataclass
+class AnalysisResult:
+    """Complete output from scanning a single file."""
+    file_path: str
+    language: str             # "python" | "javascript"
+    findings: list[Finding] = field(default_factory=list)
+    lines_scanned: int = 0
+    parse_error: str = ""
+
+    @property
+    def critical_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.CRITICAL)
+
+    @property
+    def high_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.HIGH)
+
+    @property
+    def medium_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.MEDIUM)
+
+    @property
+    def low_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.LOW)
+
+    @property
+    def info_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.INFO)
+
+    @property
+    def security_count(self) -> int:
+        return sum(1 for f in self.findings if f.finding_class == "security")
+
+    @property
+    def quality_count(self) -> int:
+        return sum(1 for f in self.findings if f.finding_class == "quality")
+
+    def sorted_findings(self) -> list[Finding]:
+        return sorted(self.findings, key=lambda f: f.severity.sort_key)
+
+    def category_counts(self) -> dict[str, int]:
+        counts: dict[str, int] = {}
+        for finding in self.findings:
+            counts[finding.category] = counts.get(finding.category, 0) + 1
+        return dict(sorted(counts.items()))
+
+    def summary_dict(self) -> dict[str, Any]:
+        return {
+            "critical": self.critical_count,
+            "high": self.high_count,
+            "medium": self.medium_count,
+            "low": self.low_count,
+            "info": self.info_count,
+            "security_findings": self.security_count,
+            "quality_findings": self.quality_count,
+            "by_category": self.category_counts(),
+            "total": len(self.findings),
+        }
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "file": self.file_path,
+            "file_path": self.file_path,
+            "language": self.language,
+            "lines": self.lines_scanned,
+            "lines_scanned": self.lines_scanned,
+            "parse_error": self.parse_error,
+            "findings": [f.as_dict(language=self.language) for f in self.sorted_findings()],
+            "summary": self.summary_dict(),
+        }

ansede_static/cache/__init__.py

@@ -0,0 +1,9 @@
+"""
+ansede_static.cache
+───────────────────
+Zero-dependency cache helpers.
+"""
+from ansede_static.cache.sqlite_store import SQLiteStore, stable_hash
+
+
+__all__ = ["SQLiteStore", "stable_hash"]

ansede_static/cache/sqlite_store.py

@@ -0,0 +1,126 @@
+"""
+ansede_static.cache.sqlite_store
+────────────────────────────────
+Tiny SQLite-backed JSON key-value store for incremental scan state.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+
+def stable_hash(value: str | bytes) -> str:
+    """Return a stable SHA-256 hex digest for content-addressing."""
+    payload = value.encode("utf-8") if isinstance(value, str) else value
+    return hashlib.sha256(payload).hexdigest()
+
+
+class SQLiteStore:
+    """Simple bucketed JSON store backed by sqlite3."""
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self._connection: sqlite3.Connection | None = None
+
+    def connect(self) -> sqlite3.Connection:
+        """Open the backing database and initialise the schema if needed."""
+        if self._connection is None:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self._connection = sqlite3.connect(self.path)
+            self._connection.row_factory = sqlite3.Row
+            self._initialise()
+        return self._connection
+
+    def close(self) -> None:
+        """Close the database connection if one is open."""
+        if self._connection is not None:
+            self._connection.close()
+            self._connection = None
+
+    def _initialise(self) -> None:
+        conn = self.connect_raw()
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS cache_entries (
+                bucket TEXT NOT NULL,
+                cache_key TEXT NOT NULL,
+                value_json TEXT NOT NULL,
+                updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                PRIMARY KEY (bucket, cache_key)
+            )
+            """
+        )
+        conn.commit()
+
+    def connect_raw(self) -> sqlite3.Connection:
+        if self._connection is None:
+            raise RuntimeError("SQLiteStore is not connected")
+        return self._connection
+
+    def set_json(self, bucket: str, key: str, value: Any) -> None:
+        """Store a JSON-serialisable value under ``bucket``/``key``."""
+        payload = json.dumps(value, sort_keys=True)
+        conn = self.connect()
+        conn.execute(
+            """
+            INSERT INTO cache_entries(bucket, cache_key, value_json)
+            VALUES(?, ?, ?)
+            ON CONFLICT(bucket, cache_key)
+            DO UPDATE SET value_json = excluded.value_json, updated_at = CURRENT_TIMESTAMP
+            """,
+            (bucket, key, payload),
+        )
+        conn.commit()
+
+    def get_json(self, bucket: str, key: str) -> Any | None:
+        """Load a stored JSON value, returning ``None`` when absent."""
+        conn = self.connect()
+        row = conn.execute(
+            "SELECT value_json FROM cache_entries WHERE bucket = ? AND cache_key = ?",
+            (bucket, key),
+        ).fetchone()
+        if row is None:
+            return None
+        return json.loads(row[0])
+
+    def delete(self, bucket: str, key: str) -> None:
+        """Delete a cache entry if it exists."""
+        conn = self.connect()
+        conn.execute(
+            "DELETE FROM cache_entries WHERE bucket = ? AND cache_key = ?",
+            (bucket, key),
+        )
+        conn.commit()
+
+    def keys(self, bucket: str) -> list[str]:
+        """Return all keys stored in a bucket."""
+        conn = self.connect()
+        rows = conn.execute(
+            "SELECT cache_key FROM cache_entries WHERE bucket = ? ORDER BY cache_key",
+            (bucket,),
+        ).fetchall()
+        return [str(row[0]) for row in rows]
+
+    def evict_older_than(self, bucket: str, days: int) -> int:
+        """Delete entries in *bucket* not updated within the last *days* days.
+
+        Returns the number of rows deleted.  Keeps the cache bounded on
+        long-running incremental installations.
+        """
+        conn = self.connect()
+        cursor = conn.execute(
+            "DELETE FROM cache_entries WHERE bucket = ? AND updated_at < datetime('now', ? || ' days')",
+            (bucket, f"-{days}"),
+        )
+        conn.commit()
+        return cursor.rowcount
+
+    def __enter__(self) -> SQLiteStore:
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self.close()