adl-toolkit 0.0.0-stage → 0.1.1

package/adl_drift/utils/types.py

@@ -0,0 +1,345 @@
+"""Core dataclasses shared across the ADL Drift pipeline."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+# Exceptions a single bad file may raise during parse/extract/detect (P2.5).
+# Scanners catch these per file and report them; anything else is a bug in
+# Drift itself and should propagate.
+SCAN_FILE_ERRORS = (UnicodeDecodeError, OSError, ValueError, RuntimeError)
+
+# P1.10 step 2: scope-chain segment inserted after every *function* segment,
+# mirroring CPython's __qualname__ semantics. Separates a class's method
+# (`m.Foo.bar`) from a closure inside a same-named function
+# (`m.Foo.<locals>.bar`).
+LOCALS_MARKER = "<locals>"
+
+
+class PatternCategory(Enum):
+    ROUTES = auto()
+    ERRORS = auto()
+    DATA_ACCESS = auto()
+    DECORATORS = auto()
+    ASYNC = auto()
+    IMPORTS = auto()
+    SECURITY = auto()
+    TESTS = auto()
+    CONFIG = auto()
+    LOGGING = auto()
+    TYPES = auto()
+    DYNAMIC = auto()  # P2.12: dynamic dispatch / reflection patterns
+    TAINT = auto()    # P2.19: source→sink taint paths (confirmed injection)
+
+
+class ConfidenceLevel(float, Enum):
+    LOW = 0.3
+    MEDIUM = 0.6
+    HIGH = 0.9
+
+
+@dataclass
+class SourcePosition:
+    line: int
+    column: int
+    end_line: int = 0
+    end_column: int = 0
+
+    def to_lsp_range(self) -> Dict[str, Dict[str, int]]:
+        return {
+            "start": {"line": max(self.line - 1, 0), "character": self.column},
+            "end": {"line": max(self.end_line - 1, 0), "character": self.end_column},
+        }
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "line": self.line,
+            "column": self.column,
+            "end_line": self.end_line,
+            "end_column": self.end_column,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "SourcePosition":
+        return cls(
+            line=d["line"],
+            column=d["column"],
+            end_line=d.get("end_line", 0),
+            end_column=d.get("end_column", 0),
+        )
+
+
+@dataclass
+class Symbol:
+    name: str
+    kind: str  # "function", "class", "method", "variable"
+    file_path: Path
+    position: SourcePosition
+    decorators: List[str] = field(default_factory=list)
+    docstring: Optional[str] = None
+    signature: Optional[str] = None
+    is_async: bool = False
+    parent: Optional[str] = None  # qualified name of enclosing class
+    superclasses: List[str] = field(default_factory=list)  # raw base class names for classes
+    param_types: Dict[str, str] = field(default_factory=dict)  # param name -> annotation text
+    return_type: Optional[str] = None  # function return annotation text
+    is_test: bool = False  # pytest/unittest test function or fixture
+    metadata: Dict[str, Any] = field(default_factory=dict)  # arbitrary per-symbol tags (e.g. synthetic=exec)
+    # P2.17/P1.10: full lexical scope chain — all enclosing class/function names,
+    # outermost first, with LOCALS_MARKER ("<locals>") inserted after every
+    # *function* segment. Mirrors CPython's __qualname__ minus the module prefix.
+    # e.g. for `def outer(): def inner():`, inner.scope_chain = ["outer", "<locals>"]
+    # e.g. for `class Foo: def bar(): def inner():`,
+    #      inner.scope_chain = ["Foo", "bar", "<locals>"]
+    scope_chain: List[str] = field(default_factory=list)
+    implements: List[str] = field(default_factory=list)  # raw interface names for classes
+    throws: List[str] = field(default_factory=list)  # declared exception types for callables
+    modifiers: List[str] = field(default_factory=list)  # language declaration modifiers
+    signature_key: Optional[str] = None  # overload discriminator, e.g. "(String,int)"
+
+    @property
+    def qualified_name(self) -> str:
+        return f"{self.parent}.{self.name}" if self.parent else self.name
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "kind": self.kind,
+            "file_path": str(self.file_path),
+            "position": self.position.to_dict(),
+            "decorators": self.decorators,
+            "docstring": self.docstring,
+            "signature": self.signature,
+            "is_async": self.is_async,
+            "parent": self.parent,
+            "superclasses": self.superclasses,
+            "implements": self.implements,
+            "throws": self.throws,
+            "modifiers": self.modifiers,
+            "signature_key": self.signature_key,
+            "param_types": self.param_types,
+            "return_type": self.return_type,
+            "is_test": self.is_test,
+            "metadata": self.metadata,
+            "scope_chain": self.scope_chain,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Symbol":
+        return cls(
+            name=d["name"],
+            kind=d["kind"],
+            file_path=Path(d["file_path"]),
+            position=SourcePosition.from_dict(d["position"]),
+            decorators=d.get("decorators", []),
+            docstring=d.get("docstring"),
+            signature=d.get("signature"),
+            is_async=d.get("is_async", False),
+            parent=d.get("parent"),
+            superclasses=d.get("superclasses", []),
+            implements=d.get("implements", []),
+            throws=d.get("throws", []),
+            modifiers=d.get("modifiers", []),
+            signature_key=d.get("signature_key"),
+            param_types=d.get("param_types", {}),
+            return_type=d.get("return_type"),
+            is_test=d.get("is_test", False),
+            metadata=d.get("metadata", {}),
+            scope_chain=d.get("scope_chain", []),
+        )
+
+
+@dataclass
+class ImportRecord:
+    """Structured import binding (P2.1). One record per imported name.
+
+    Examples:
+        import a.b              → module="a.b", name=None             (binds "a")
+        import a.b as c         → module="a.b", name=None, alias="c"
+        from x.y import z       → module="x.y", name="z"
+        from x import z as q    → module="x",   name="z", alias="q"
+        from . import m         → module="",    name="m", level=1
+        from ..utils import h   → module="utils", name="h", level=2
+        from x import *         → module="x",   name="*", is_wildcard=True
+    """
+    module: str
+    name: Optional[str] = None
+    alias: Optional[str] = None
+    level: int = 0  # number of leading dots for relative imports
+    is_wildcard: bool = False
+    is_static: bool = False
+
+    @property
+    def binding(self) -> Optional[str]:
+        """Local name this import introduces (None for wildcard)."""
+        if self.is_wildcard:
+            return None
+        if self.alias:
+            return self.alias
+        if self.name:
+            return self.name
+        # plain `import a.b` binds the leftmost segment
+        return self.module.split(".")[0] if self.module else None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "module": self.module,
+            "name": self.name,
+            "alias": self.alias,
+            "level": self.level,
+            "is_wildcard": self.is_wildcard,
+            "is_static": self.is_static,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "ImportRecord":
+        return cls(
+            module=d.get("module", ""),
+            name=d.get("name"),
+            alias=d.get("alias"),
+            level=d.get("level", 0),
+            is_wildcard=d.get("is_wildcard", False),
+            is_static=d.get("is_static", False),
+        )
+
+
+@dataclass
+class Pattern:
+    category: PatternCategory
+    name: str
+    description: str
+    position: SourcePosition
+    file_path: Path
+    confidence: float = 0.5
+    symbol: Optional[Symbol] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    is_approved: bool = False
+
+    # Metadata keys that name the pattern's symbolic object, in priority
+    # order (same list the CLI scan table's Object column resolves from).
+    _HASH_OBJECT_KEYS = (
+        "handler", "function", "decorator", "name", "class",
+        "key", "key_name", "route_path", "module", "type", "role",
+    )
+
+    def compute_hash(self) -> str:
+        """Structural identity hash (P2.4).
+
+        Identity is `category:name:anchor` where the anchor is the symbolic
+        object the pattern is about — the enclosing symbol (`Class.method`)
+        when present, else the most specific metadata object, else the
+        filename stem. Line numbers and directory paths never participate,
+        so a pattern keeps its identity (and approval status) when code
+        moves to a different line or the file is relocated.
+        """
+        if self.symbol is not None:
+            anchor = (
+                f"{self.symbol.parent}.{self.symbol.name}"
+                if self.symbol.parent else self.symbol.name
+            )
+        else:
+            anchor = ""
+            for k in self._HASH_OBJECT_KEYS:
+                v = self.metadata.get(k)
+                if v:
+                    anchor = str(v)
+                    break
+            if not anchor:
+                anchor = Path(self.file_path).stem
+        key = f"{self.category.name}:{self.name}:{anchor}"
+        return hashlib.sha256(key.encode()).hexdigest()[:16]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "category": self.category.name,
+            "name": self.name,
+            "description": self.description,
+            "position": self.position.to_dict(),
+            "file_path": str(self.file_path),
+            "confidence": self.confidence,
+            "metadata": self.metadata,
+            "is_approved": self.is_approved,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Pattern":
+        return cls(
+            category=PatternCategory[d["category"]],
+            name=d["name"],
+            description=d["description"],
+            position=SourcePosition.from_dict(d["position"]),
+            file_path=Path(d["file_path"]),
+            confidence=d.get("confidence", 0.5),
+            metadata=d.get("metadata", {}),
+            is_approved=d.get("is_approved", False),
+        )
+
+
+@dataclass
+class AnalysisResult:
+    file_path: Path
+    symbols: List[Symbol] = field(default_factory=list)
+    patterns: List[Pattern] = field(default_factory=list)
+    imports: List[str] = field(default_factory=list)
+    import_records: List[ImportRecord] = field(default_factory=list)
+    errors: List[str] = field(default_factory=list)
+    parse_time_ms: float = 0.0
+    language: str = "python"
+    module_name: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "file_path": str(self.file_path),
+            "symbols": [s.to_dict() for s in self.symbols],
+            "patterns": [p.to_dict() for p in self.patterns],
+            "imports": self.imports,
+            "import_records": [r.to_dict() for r in self.import_records],
+            "errors": self.errors,
+            "parse_time_ms": self.parse_time_ms,
+            "language": self.language,
+            "module_name": self.module_name,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "AnalysisResult":
+        return cls(
+            file_path=Path(d["file_path"]),
+            symbols=[Symbol.from_dict(s) for s in d.get("symbols", [])],
+            patterns=[Pattern.from_dict(p) for p in d.get("patterns", [])],
+            imports=d.get("imports", []),
+            import_records=[ImportRecord.from_dict(r) for r in d.get("import_records", [])],
+            errors=d.get("errors", []),
+            parse_time_ms=d.get("parse_time_ms", 0.0),
+            language=d.get("language", "python"),
+            module_name=d.get("module_name"),
+        )
+
+
+@dataclass
+class ProjectContext:
+    root_path: Path
+    files_analyzed: int = 0
+    total_symbols: int = 0
+    total_patterns: int = 0
+    frameworks: List[str] = field(default_factory=list)
+    naming_convention: Optional[str] = None
+    # Project-size baseline metrics (P3.15 follow-up).
+    lines_of_code: int = 0          # total physical lines across scanned files
+    non_blank_lines: int = 0        # non-empty / non-whitespace lines
+    total_functions: int = 0
+    total_classes: int = 0
+    total_variables: int = 0
+    total_modules: int = 0
+    entry_points: int = 0
+    calls_edges: int = 0
+    patterns_by_category: Dict[str, int] = field(default_factory=dict)
+    # Files that exist on disk but were correctly out of scope for this
+    # scan (a Maven module not in the active reactor, a resources
+    # directory), each `{"path", "reason", "detail"}` — see
+    # `JavaProjectConfig.excluded_source_files`. Empty for non-Java projects.
+    excluded_files: List[Dict[str, Any]] = field(default_factory=list)

package/bin/adl-drift.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir, constants } from 'node:os';
+import { spawn } from 'node:child_process';
+
+const args = process.argv.slice(2);
+let projectArgument;
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '-p' || args[i] === '--project') projectArgument = args[++i];
+  else if (args[i].startsWith('--project=')) projectArgument = args[i].slice('--project='.length);
+}
+const expand = path => path === '~' ? homedir() : path.startsWith('~/') || path.startsWith('~\\') ? join(homedir(), path.slice(2)) : path;
+let project = resolve(expand(projectArgument || process.cwd()));
+const executableFor = path => join(path, '.adl-toolkit', 'venv', process.platform === 'win32' ? 'Scripts' : 'bin', process.platform === 'win32' ? 'adl-drift.exe' : 'adl-drift');
+while (!existsSync(executableFor(project)) && !projectArgument && dirname(project) !== project) project = dirname(project);
+const executable = executableFor(project);
+if (!existsSync(executable)) {
+  console.error('No managed ADL-Drift runtime found. Run adl-toolkit install in this project first.');
+  process.exitCode = 1;
+} else {
+  const child = spawn(executable, projectArgument ? args : ['-p', project, ...args], { stdio: 'inherit' });
+  const interrupt = () => child.kill('SIGINT');
+  process.on('SIGINT', interrupt);
+  child.on('error', error => {
+    console.error(`Cannot run ADL-Drift: ${error.message}`);
+    process.exitCode = 1;
+    process.off('SIGINT', interrupt);
+  });
+  child.on('close', (code, signal) => {
+    process.off('SIGINT', interrupt);
+    process.exitCode = signal ? 128 + (constants.signals[signal] || 0) : code ?? 1;
+  });
+}