iridium-core 0.1.0__tar.gz

iridium_core-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Iridium local state
+.iridium/
+
+# Test / tooling
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+uv.lock
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+
+# Env secrets
+.env
+!.env.example

iridium_core-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: iridium-core
+Version: 0.1.0
+Summary: Local AST extraction, graph assembly, and cache for Iridium security scanning
+Project-URL: Homepage, https://github.com/mziqudhd92/Iridium
+Project-URL: Repository, https://github.com/mziqudhd92/Iridium
+Project-URL: Documentation, https://github.com/mziqudhd92/Iridium#readme
+Author: Iridium Contributors
+License: Apache-2.0
+Keywords: dependency-analysis,reachability,sast,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: pathspec>=0.12
+Requires-Dist: pydantic>=2.0
+Provides-Extra: msgpack
+Requires-Dist: msgpack>=1.0; extra == 'msgpack'
+Description-Content-Type: text/markdown
+
+# iridium-core
+
+Local AST extraction, dependency graph assembly, SQLite cache, and payload models for Iridium security scanning.
+
+**No network I/O.** No httpx dependency.
+
+## Install
+
+```bash
+pip install iridium-core
+```
+
+## Library API
+
+### `WorkspaceIndexer`
+
+Primary entry point — indexes a repository into a `ClientScanPayload`:
+
+```python
+from pathlib import Path
+from iridium_core import WorkspaceIndexer
+
+indexer = WorkspaceIndexer(Path("/path/to/repo"))
+payload = indexer.index()
+
+print(payload.dependency_count, payload.entrypoint_count)
+print(payload.languages)
+print(payload.to_json())
+```
+
+Options:
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `use_cache` | `True` | SQLite AST cache (WAL, cross-mount fallback to `~/.cache/iridium`) |
+| `use_process_pool` | `True` | ProcessPool batches for large repos (disable for small targets) |
+| `extractors` | `DEFAULT_EXTRACTORS` | Custom `LanguageExtractor` plugins |
+
+### Payload validation
+
+```python
+from iridium_core.models.payload import ClientScanPayload
+
+validated = ClientScanPayload.model_validate(payload.model_dump())
+api_dict = validated.to_api_dict()  # ready for POST /api/v1/client/scan
+```
+
+### Modules
+
+| Module | Purpose |
+| --- | --- |
+| `iridium_core.extract` | Python/JavaScript `LanguageExtractor` plugins |
+| `iridium_core.graph` | Tarjan SCC, bounded BFS, adjacency |
+| `iridium_core.deps` | Lockfile parsing (pip, npm, etc.) |
+| `iridium_core.sanitize` | Pre-AST scrubbing (PEM, JWT, API keys) |
+| `iridium_core.cache` | Content-addressed AST cache |
+| `iridium_core.git` | Tree hash / commit fingerprint |
+
+## Development
+
+Part of the [Iridium monorepo](https://github.com/mziqudhd92/Iridium). From repo root:
+
+```bash
+uv sync
+uv run pytest packages/iridium-core/tests -v
+```

iridium_core-0.1.0/README.md

@@ -0,0 +1,66 @@
+# iridium-core
+
+Local AST extraction, dependency graph assembly, SQLite cache, and payload models for Iridium security scanning.
+
+**No network I/O.** No httpx dependency.
+
+## Install
+
+```bash
+pip install iridium-core
+```
+
+## Library API
+
+### `WorkspaceIndexer`
+
+Primary entry point — indexes a repository into a `ClientScanPayload`:
+
+```python
+from pathlib import Path
+from iridium_core import WorkspaceIndexer
+
+indexer = WorkspaceIndexer(Path("/path/to/repo"))
+payload = indexer.index()
+
+print(payload.dependency_count, payload.entrypoint_count)
+print(payload.languages)
+print(payload.to_json())
+```
+
+Options:
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `use_cache` | `True` | SQLite AST cache (WAL, cross-mount fallback to `~/.cache/iridium`) |
+| `use_process_pool` | `True` | ProcessPool batches for large repos (disable for small targets) |
+| `extractors` | `DEFAULT_EXTRACTORS` | Custom `LanguageExtractor` plugins |
+
+### Payload validation
+
+```python
+from iridium_core.models.payload import ClientScanPayload
+
+validated = ClientScanPayload.model_validate(payload.model_dump())
+api_dict = validated.to_api_dict()  # ready for POST /api/v1/client/scan
+```
+
+### Modules
+
+| Module | Purpose |
+| --- | --- |
+| `iridium_core.extract` | Python/JavaScript `LanguageExtractor` plugins |
+| `iridium_core.graph` | Tarjan SCC, bounded BFS, adjacency |
+| `iridium_core.deps` | Lockfile parsing (pip, npm, etc.) |
+| `iridium_core.sanitize` | Pre-AST scrubbing (PEM, JWT, API keys) |
+| `iridium_core.cache` | Content-addressed AST cache |
+| `iridium_core.git` | Tree hash / commit fingerprint |
+
+## Development
+
+Part of the [Iridium monorepo](https://github.com/mziqudhd92/Iridium). From repo root:
+
+```bash
+uv sync
+uv run pytest packages/iridium-core/tests -v
+```

iridium_core-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "iridium-core"
+version = "0.1.0"
+description = "Local AST extraction, graph assembly, and cache for Iridium security scanning"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.11"
+authors = [{ name = "Iridium Contributors" }]
+keywords = ["security", "sast", "reachability", "dependency-analysis"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+]
+dependencies = [
+    "pydantic>=2.0",
+    "pathspec>=0.12",
+]
+
+[project.optional-dependencies]
+msgpack = ["msgpack>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/mziqudhd92/Iridium"
+Repository = "https://github.com/mziqudhd92/Iridium"
+Documentation = "https://github.com/mziqudhd92/Iridium#readme"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/iridium_core"]

iridium_core-0.1.0/src/iridium_core/__init__.py

@@ -0,0 +1,6 @@
+"""Iridium core — local extraction, graph assembly, and caching."""
+
+from iridium_core.workspace.indexer import WorkspaceIndexer
+
+__all__ = ["WorkspaceIndexer"]
+__version__ = "0.1.0"

iridium_core-0.1.0/src/iridium_core/cache/__init__.py

@@ -0,0 +1,5 @@
+"""AST cache."""
+
+from iridium_core.cache.ast_cache import AstCache, content_hash, resolve_cache_path
+
+__all__ = ["AstCache", "content_hash", "resolve_cache_path"]

iridium_core-0.1.0/src/iridium_core/cache/ast_cache.py

@@ -0,0 +1,109 @@
+"""SQLite AST cache with WAL and cross-mount fallback."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import sqlite3
+from pathlib import Path
+
+WAL_PRAGMAS = (
+    "PRAGMA journal_mode=WAL",
+    "PRAGMA busy_timeout=5000",
+    "PRAGMA mmap_size=268435456",
+)
+
+CREATE_TABLE = """
+CREATE TABLE IF NOT EXISTS ast_cache (
+    git_tree_hash TEXT NOT NULL,
+    file_path TEXT NOT NULL,
+    content_hash TEXT NOT NULL,
+    commit_hash TEXT,
+    fragment_json TEXT NOT NULL,
+    updated_at TEXT DEFAULT (datetime('now')),
+    PRIMARY KEY (git_tree_hash, file_path, content_hash)
+)
+"""
+
+
+def content_hash(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _is_cross_mount(path: Path) -> bool:
+    """Heuristic: repo on /mnt/ (WSL) or common Docker bind mounts."""
+    posix = path.as_posix()
+    if posix.startswith("/mnt/"):
+        return True
+    home = Path.home().as_posix()
+    if not posix.startswith(home) and posix.startswith("/Users/"):
+        return False
+    # On Linux docker bind mounts often under /workspace or /repo
+    for prefix in ("/workspace", "/repo", "/host_mnt"):
+        if posix.startswith(prefix):
+            return True
+    return False
+
+
+def resolve_cache_path(repo: Path) -> Path:
+    """Return active cache.db path; fallback to ~/.cache/iridium on cross-mount."""
+    local = repo / ".iridium" / "cache.db"
+    if not _is_cross_mount(repo.resolve()):
+        local.parent.mkdir(parents=True, exist_ok=True)
+        return local
+
+    repo_hash = hashlib.sha256(str(repo.resolve()).encode()).hexdigest()[:16]
+    fallback = Path.home() / ".cache" / "iridium" / f"{repo_hash}" / "cache.db"
+    fallback.parent.mkdir(parents=True, exist_ok=True)
+    return fallback
+
+
+class AstCache:
+    """WAL-backed AST fragment cache keyed by git tree hash."""
+
+    def __init__(self, db_path: Path) -> None:
+        self.db_path = db_path
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(str(db_path), timeout=5.0)
+        for pragma in WAL_PRAGMAS:
+            self._conn.execute(pragma)
+        self._conn.execute(CREATE_TABLE)
+        self._conn.commit()
+
+    def get(
+        self,
+        git_tree_hash: str,
+        file_path: str,
+        file_content_hash: str,
+    ) -> str | None:
+        row = self._conn.execute(
+            "SELECT fragment_json FROM ast_cache "
+            "WHERE git_tree_hash=? AND file_path=? AND content_hash=?",
+            (git_tree_hash, file_path, file_content_hash),
+        ).fetchone()
+        return row[0] if row else None
+
+    def put(
+        self,
+        git_tree_hash: str,
+        file_path: str,
+        file_content_hash: str,
+        fragment_json: str,
+        commit_hash: str | None = None,
+    ) -> None:
+        self._conn.execute(
+            "INSERT OR REPLACE INTO ast_cache "
+            "(git_tree_hash, file_path, content_hash, commit_hash, fragment_json) "
+            "VALUES (?, ?, ?, ?, ?)",
+            (git_tree_hash, file_path, file_content_hash, commit_hash, fragment_json),
+        )
+        self._conn.commit()
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def __enter__(self) -> AstCache:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

iridium_core-0.1.0/src/iridium_core/deps/__init__.py

@@ -0,0 +1,5 @@
+"""Dependency lockfile parsing."""
+
+from iridium_core.deps.lockfiles import parse_all_lockfiles, parse_package_lock, parse_uv_lock
+
+__all__ = ["parse_all_lockfiles", "parse_package_lock", "parse_uv_lock"]

iridium_core-0.1.0/src/iridium_core/deps/lockfiles.py

@@ -0,0 +1,100 @@
+"""Lockfile parsers for dependency resolution."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from iridium_core.models.payload import DependencyNode
+
+DETERMINISM_PATTERNS = (r"\*", r"latest", r"^$")
+
+
+def parse_uv_lock(repo: Path) -> tuple[list[DependencyNode], list[str]]:
+    """Parse uv.lock TOML-like format (basic)."""
+    lock_path = repo / "uv.lock"
+    if not lock_path.is_file():
+        return [], []
+
+    warnings: list[str] = []
+    deps: list[DependencyNode] = []
+    try:
+        text = lock_path.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return [], []
+
+    current_name: str | None = None
+    current_version: str | None = None
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("name ="):
+            current_name = stripped.split("=", 1)[1].strip().strip('"')
+        elif stripped.startswith("version =") and current_name:
+            current_version = stripped.split("=", 1)[1].strip().strip('"')
+            deps.append(
+                DependencyNode(name=current_name, version=current_version, ecosystem="pypi")
+            )
+            current_name = None
+            current_version = None
+
+    for dep in deps:
+        if dep.version and any(re.search(p, dep.version, re.I) for p in DETERMINISM_PATTERNS):
+            warnings.append(f"DETERMINISM_WARNING: unpinned {dep.name}={dep.version} in uv.lock")
+
+    return deps, warnings
+
+
+def parse_package_lock(repo: Path) -> tuple[list[DependencyNode], list[str]]:
+    """Parse package-lock.json v2/v3 dependencies (basic)."""
+    lock_path = repo / "package-lock.json"
+    if not lock_path.is_file():
+        return [], []
+
+    warnings: list[str] = []
+    try:
+        payload = json.loads(lock_path.read_text(encoding="utf-8", errors="ignore"))
+    except (OSError, json.JSONDecodeError):
+        return [], []
+
+    packages = payload.get("packages") or {}
+    deps: list[DependencyNode] = []
+    for pkg_path, meta in packages.items():
+        if not isinstance(meta, dict):
+            continue
+        name = meta.get("name") or (pkg_path.split("node_modules/")[-1] if pkg_path else "")
+        if not name or name.startswith("node_modules"):
+            continue
+        version = meta.get("version")
+        resolved = meta.get("resolved")
+        if version:
+            deps.append(
+                DependencyNode(
+                    name=name,
+                    version=version,
+                    ecosystem="npm",
+                    resolved_url=resolved,
+                )
+            )
+            if any(re.search(p, str(version), re.I) for p in DETERMINISM_PATTERNS):
+                warnings.append(
+                    f"DETERMINISM_WARNING: unpinned {name}={version} in package-lock.json"
+                )
+
+    return deps, warnings
+
+
+def parse_all_lockfiles(repo: Path) -> tuple[list[DependencyNode], list[str]]:
+    """Parse available lockfiles; uv.lock takes precedence over manifests."""
+    all_deps: list[DependencyNode] = []
+    all_warnings: list[str] = []
+
+    uv_deps, uv_warn = parse_uv_lock(repo)
+    all_deps.extend(uv_deps)
+    all_warnings.extend(uv_warn)
+
+    npm_deps, npm_warn = parse_package_lock(repo)
+    all_deps.extend(npm_deps)
+    all_warnings.extend(npm_warn)
+
+    return all_deps, all_warnings

iridium_core-0.1.0/src/iridium_core/extract/__init__.py

@@ -0,0 +1,17 @@
+"""Extractor plugins."""
+
+from iridium_core.extract.base import ImportMap, LanguageExtractor
+from iridium_core.extract.javascript_extractor import JavaScriptExtractor
+from iridium_core.extract.python_extractor import PythonExtractor
+
+__all__ = [
+    "ImportMap",
+    "JavaScriptExtractor",
+    "LanguageExtractor",
+    "PythonExtractor",
+]
+
+DEFAULT_EXTRACTORS: list[LanguageExtractor] = [
+    PythonExtractor(),
+    JavaScriptExtractor(),
+]

iridium_core-0.1.0/src/iridium_core/extract/base.py

@@ -0,0 +1,29 @@
+"""Language extractor plugin interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from iridium_core.models.fragment import GraphFragment
+
+
+class ImportMap(dict[str, str]):
+    """Maps import specifier → resolved file path."""
+
+
+class LanguageExtractor(ABC):
+    language: str
+
+    @abstractmethod
+    def parse_batch_safe(self, paths: list[Path]) -> list[GraphFragment]:
+        """Parse a batch of source files into graph fragments."""
+
+    @abstractmethod
+    def resolve_imports(self, repo: Path) -> ImportMap:
+        """Build import resolution map for the repository."""
+
+    def supported_extensions(self) -> set[str]:
+        return set()