deproc-core 0.1.0__py3-none-any.whl

deproc/core/__init__.py

@@ -0,0 +1,5 @@
+from .discovery import find_source_files
+
+__all__ = [
+    "find_source_files",
+]

deproc/core/context.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .interfaces.linker import Linker
+    from .interfaces.parser import SourceParser
+    from .interfaces.resolver import Resolver
+    from .interfaces.symbol_cache import SymbolCache
+
+from .runtime import EntityRegistry
+
+logger = logging.getLogger(__name__)
+
+class Context:
+    def __init__(self, base_path: str = "", copy_from: Context | None = None):
+        if copy_from:
+            self.base_path = copy_from.base_path
+            self.entity_registry = copy_from.entity_registry
+            self._language_aliases = dict(copy_from._language_aliases)
+            self._language_extensions = dict(copy_from._language_extensions)
+            self._all_languages = set(copy_from._all_languages)
+            self._all_file_extensions = set(copy_from._all_file_extensions)
+            self._selected_languages = set(copy_from._selected_languages)
+            self._selected_file_extensions = set(copy_from._selected_file_extensions)
+            self._parsers = dict(copy_from._parsers)
+            self._resolvers = dict(copy_from._resolvers)
+            self._linkers = dict(copy_from._linkers)
+            self.symbol_caches = dict(copy_from.symbol_caches)
+            self._skip_paths = set(copy_from._skip_paths)
+        else:
+            self.base_path = base_path
+            self.entity_registry = EntityRegistry()
+            self._language_aliases: dict[str, list[str]] = {}
+            self._language_extensions: dict[str, list[str]] = {}
+            self._all_languages: set[str] = set()
+            self._all_file_extensions: set[str] = set()
+            self._selected_languages: set[str] = set()
+            self._selected_file_extensions: set[str] = set()
+            self._skip_paths: set[str] = set()
+            self._parsers: dict[str, SourceParser] = {}
+            self._resolvers: dict[str, Resolver] = {}
+            self._linkers: dict[str, Linker] = {}
+            self.symbol_caches: dict[str, SymbolCache] = {}
+
+    def set_language(
+        self,
+        language: str,
+        file_extensions: list[str],
+        aliases: list[str] | None = None,
+    ) -> None:
+        normalized = language.strip().lower()
+        normalized_extensions: list[str] = []
+        for ext in file_extensions:
+            e = ext.strip().lower()
+            if not e.startswith("."):
+                e = f".{e}"
+                logger.warning("Normalized file extension '%s' to '%s' for language '%s'", ext, e, normalized)
+            normalized_extensions.append(e)
+        self._language_extensions[normalized] = normalized_extensions
+        if aliases:
+            self._language_aliases[normalized] = [a.strip().lower() for a in aliases]
+        else:
+            self._language_aliases[normalized] = []
+        self._all_languages.add(normalized)
+        self._selected_languages.add(normalized)
+        self._all_file_extensions.update(normalized_extensions)
+        self._selected_file_extensions.update(normalized_extensions)
+
+    @property
+    def selected_languages(self) -> set[str]:
+        return self._selected_languages
+
+    @property
+    def selected_file_extensions(self) -> set[str]:
+        return self._selected_file_extensions
+
+    @property
+    def skip_paths(self) -> set[str]:
+        return self._skip_paths
+
+    def set_skip_paths(self, paths: set[str]) -> None:
+        self._skip_paths = set(paths)
+
+    def _normalize_language(self, language: str) -> str:
+        normalized = language.strip().lower()
+        for canonical, aliases in self._language_aliases.items():
+            if normalized == canonical or normalized in aliases:
+                return canonical
+        return normalized
+
+    def _normalize_extension(self, extension: str) -> str:
+        normalized = extension.strip().lower()
+        if not normalized.startswith("."):
+            normalized = f".{normalized}"
+        return normalized
+
+    def select_languages(self, languages: list[str]) -> None:
+        for lang in languages:
+            normalized = self._normalize_language(lang)
+            exclude = normalized.startswith("!")
+            if exclude:
+                normalized = normalized[1:]
+            if normalized in self._all_languages:
+                if exclude:
+                    self._selected_languages.discard(normalized)
+                else:
+                    self._selected_languages.add(normalized)
+
+    def select_file_extensions(self, extensions: list[str]) -> None:
+        for ext in extensions:
+            raw = ext.strip().lower()
+            exclude = raw.startswith("!")
+            if exclude:
+                raw = raw[1:]
+            normalized = self._normalize_extension(raw)
+            if normalized in self._all_file_extensions:
+                if exclude:
+                    self._selected_file_extensions.discard(normalized)
+                else:
+                    self._selected_file_extensions.add(normalized)
+
+    def _require_language(self, language: str) -> None:
+        if language not in self._all_languages:
+            raise KeyError(f"Language '{language}' is not registered. Call set_language() first.")
+
+    def _warn_if_language_missing(self, language: str) -> None:
+        if language not in self._all_languages:
+            logger.warning("Language '%s' is not registered. Did you forget to call set_language()?", language)
+
+    def set_parser(self, language: str, parser: SourceParser) -> None:
+        self._require_language(language)
+        self._parsers[language] = parser
+
+    def get_parser(self, language: str) -> SourceParser | None:
+        self._warn_if_language_missing(language)
+        return self._parsers.get(language)
+
+    def has_parser(self, language: str) -> bool:
+        self._warn_if_language_missing(language)
+        return language in self._parsers
+
+    def remove_parser(self, language: str) -> None:
+        self._warn_if_language_missing(language)
+        self._parsers.pop(language, None)
+
+    def set_resolver(self, language: str, resolver: Resolver) -> None:
+        self._require_language(language)
+        self._resolvers[language] = resolver
+
+    def get_resolver(self, language: str) -> Resolver | None:
+        self._warn_if_language_missing(language)
+        return self._resolvers.get(language)
+
+    def has_resolver(self, language: str) -> bool:
+        self._warn_if_language_missing(language)
+        return language in self._resolvers
+
+    def remove_resolver(self, language: str) -> None:
+        self._warn_if_language_missing(language)
+        self._resolvers.pop(language, None)
+
+    def set_linker(self, language: str, linker: Linker) -> None:
+        self._require_language(language)
+        self._linkers[language] = linker
+
+    def get_linker(self, language: str) -> Linker | None:
+        self._warn_if_language_missing(language)
+        return self._linkers.get(language)
+
+    def has_linker(self, language: str) -> bool:
+        self._warn_if_language_missing(language)
+        return language in self._linkers
+
+    def remove_linker(self, language: str) -> None:
+        self._warn_if_language_missing(language)
+        self._linkers.pop(language, None)
+
+    def set_symbol_cache(self, cache: SymbolCache) -> None:
+        self._require_language(cache.language)
+        self.symbol_caches[cache.language] = cache
+
+    def get_symbol_cache(self, language: str) -> SymbolCache | None:
+        self._warn_if_language_missing(language)
+        return self.symbol_caches.get(language)
+
+    def has_symbol_cache(self, language: str) -> bool:
+        self._warn_if_language_missing(language)
+        return language in self.symbol_caches
+
+    def remove_symbol_cache(self, language: str) -> None:
+        self._warn_if_language_missing(language)
+        self.symbol_caches.pop(language, None)
+
+    def reset(
+        self,
+        include_languages: bool = True,
+        include_file_extensions: bool = True,
+        include_symbol_caches: bool = True,
+    ) -> None:
+        if include_languages:
+            self._selected_languages = set(self._all_languages)
+        if include_file_extensions:
+            self._selected_file_extensions = set(self._all_file_extensions)
+        if include_symbol_caches:
+            self.symbol_caches = {}

deproc/core/discovery.py

@@ -0,0 +1,23 @@
+import fnmatch
+import os
+from .context import Context
+
+def _match_any(name: str, patterns: set[str]) -> bool:
+    return any(fnmatch.fnmatch(name, p) for p in patterns)
+
+def find_source_files(context: Context) -> list[str]:
+    root = context.base_path
+    extension_set = set(context.selected_file_extensions)
+    skip_dirs = context.skip_paths
+    if not extension_set:
+        return []
+
+    matches: list[str] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if not _match_any(d, skip_dirs)]
+        for f in filenames:
+            if any(f.lower().endswith(ext) for ext in extension_set):
+                matches.append(os.path.join(dirpath, f))
+
+    matches.sort()
+    return matches

deproc/core/interfaces/__init__.py

@@ -0,0 +1,11 @@
+from .linker import Linker
+from .parser import SourceParser
+from .resolver import Resolver
+from .symbol_cache import SymbolCache
+
+__all__ = [
+    "Linker",
+    "Resolver",
+	"SourceParser",
+    "SymbolCache",
+]

deproc/core/interfaces/linker.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING, Protocol, TypeVar, runtime_checkable
+
+if TYPE_CHECKING:
+    from ..context import Context
+
+from .parser.models import SourceFile, Node
+
+T_In = TypeVar("T_In", bound=list[SourceFile])
+T_Out = TypeVar("T_Out", bound=list[Node])
+
+@runtime_checkable
+class Linker(Protocol[T_In, T_Out]):
+    def link_files(self, nodes: T_In, context: Context) -> T_Out:
+        ...

deproc/core/interfaces/parser/__init__.py

@@ -0,0 +1,5 @@
+from .base import SourceParser
+
+__all__ = [
+    "SourceParser"
+]

deproc/core/interfaces/parser/base.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .models import SourceFile
+    from ...context import Context
+
+@runtime_checkable
+class SourceParser(Protocol):
+    def parse_file(self, file_path: str, context: Context) -> SourceFile:
+        ...

deproc/core/interfaces/parser/models.py

@@ -0,0 +1,142 @@
+"""
+Provisional data models for the parser interface.
+Please use these models either directly in the plugin implementations or as a reference for defining plugin-specific models.
+"""
+import hashlib
+from dataclasses import dataclass, field
+from uuid import NAMESPACE_URL, UUID, uuid4, uuid5
+
+type SymbolID = str
+
+def generate_id() -> SymbolID:
+    return uuid4().hex
+
+@dataclass(kw_only=True)
+class Entity:
+    id: str | None = None
+    parent_id: str | None = None
+
+    def __post_init__(self):
+        if self.id is not None:
+            return
+        self.id = self._compute_id()
+
+    def _compute_id(self) -> str:
+        parent_id = getattr(self, "parent_id", None)
+        source_range = getattr(self, "source_range", None)
+        if parent_id and source_range:
+            namespace = UUID(hex=parent_id)
+            name = f"{type(self).__qualname__}:{source_range.lineno}:{source_range.end_lineno}:{source_range.col_offset}:{source_range.end_col_offset}"
+            return uuid5(namespace, name).hex
+        return uuid4().hex
+
+@dataclass(kw_only=True)
+class SourceRange:
+    lineno: int
+    end_lineno: int
+    col_offset: int
+    end_col_offset: int
+    source_id: str | None = None
+
+@dataclass
+class Docstring:
+    docstring_range: SourceRange | None
+
+@dataclass
+class Signature:
+    signature_range: SourceRange
+    arguments_range: SourceRange | None
+    return_type_range: SourceRange | None
+
+@dataclass
+class Annotation:
+    source_range: SourceRange
+    name: str
+
+@dataclass
+class ImportStatement(Entity):
+    source_range: SourceRange
+    type: str
+
+@dataclass
+class Argument:
+    name: str
+    source_range: SourceRange
+    default_value: str | None
+    type_annotation: str | None
+
+@dataclass(kw_only=True)
+class FunctionLike(Docstring, Entity):
+    name: str
+    fqn: str
+    source_range: SourceRange
+    type: str = field(default="FUNCTION")
+    signature: Signature
+
+@dataclass
+class SimpleBinding:
+    name: str
+    fqn: str
+
+@dataclass
+class ComplexBinding:
+    source_range: SourceRange | None
+
+@dataclass(kw_only=True)
+class VariableDeclaration(Entity):
+    type: str = field(default="VARIABLE")
+    source_range: SourceRange
+    variable_binding: SimpleBinding | ComplexBinding
+    value_range: SourceRange | None
+    type_annotation: SourceRange | None
+    modifiers: list[str] = field(default_factory=list)
+
+@dataclass(kw_only=True)
+class TypeDefinition(Docstring, Entity):
+    name: str
+    fqn: str
+    source_range: SourceRange
+    type: str = field(default="TYPE_DEFINITION")
+    annotations: list[Annotation] = field(default_factory=list)
+    inherits: list[str] = field(default_factory=list)
+    method_ids: list[str] = field(default_factory=list)
+    inner_type_ids: list[str] = field(default_factory=list)
+    property_ids: list[str] = field(default_factory=list)
+    visibility: str | None
+
+@dataclass
+class ControlFlowBlock(Entity):
+    branch: str
+    source_range: SourceRange
+    condition_range: SourceRange | None
+    import_stmt_ids: list[SymbolID] = field(default_factory=list)
+    type_ids: list[SymbolID] = field(default_factory=list)
+    function_ids: list[SymbolID] = field(default_factory=list)
+    variable_ids: list[SymbolID] = field(default_factory=list)
+    nested_group_ids: list[SymbolID] = field(default_factory=list)
+
+@dataclass
+class ControlFlowGroup(Entity):
+    group_type: str
+    source_range: SourceRange
+    block_ids: list[SymbolID] = field(default_factory=list)
+
+@dataclass
+class Node(Entity):
+    path: str
+
+    def _compute_id(self) -> str:
+        return uuid5(NAMESPACE_URL, f"file://{self.path}").hex
+
+@dataclass(kw_only=True)
+class SourceFile(Docstring, Node):
+    import_stmt_ids: list[SymbolID] = field(default_factory=list)
+    type_ids: list[SymbolID] = field(default_factory=list)
+    function_ids: list[SymbolID] = field(default_factory=list)
+    variable_ids: list[SymbolID] = field(default_factory=list)
+    control_flow_group_ids: list[SymbolID] = field(default_factory=list)
+    source: str
+
+    def _compute_id(self) -> str:
+        h = hashlib.sha256(self.source.encode()).hexdigest()[:16]
+        return uuid5(NAMESPACE_URL, f"file://{self.path}#{h}").hex

deproc/core/interfaces/resolver.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+from typing import (
+    Any,
+    Protocol,
+    TypeVar,
+    runtime_checkable
+)
+
+TOut = TypeVar("TOut")
+
+@runtime_checkable
+class Resolver(Protocol[TOut]):
+    def resolve(self, *args: Any, **kwargs: Any) -> TOut:
+        ...
+
+__all__ = ["Resolver"]

deproc/core/interfaces/symbol_cache.py

@@ -0,0 +1,20 @@
+from typing import(
+    Any,
+    Protocol, 
+    TypeVar, 
+    runtime_checkable
+)
+
+TCache = TypeVar("TCache")
+TReturn = TypeVar("TReturn")
+
+@runtime_checkable
+class SymbolCache(Protocol[TCache, TReturn]):
+    language: str
+    cache: TCache
+
+    def get(self, *args: Any, **kwargs: Any) -> TReturn:
+        ...
+
+    def set(self, *args: Any, **kwargs: Any) -> None:
+        ...

deproc/core/runtime/__init__.py

@@ -0,0 +1,7 @@
+from .registries import (
+    EntityRegistry
+)
+
+__all__ = [
+    "EntityRegistry"
+]

deproc/core/runtime/registries/__init__.py

@@ -0,0 +1,5 @@
+from .entity import EntityRegistry
+
+__all__ = [
+    "EntityRegistry"
+]

deproc/core/runtime/registries/entity.py

@@ -0,0 +1,42 @@
+from collections import defaultdict
+from dataclasses import dataclass, field
+from ...interfaces.parser.models import (
+    Entity,
+    SymbolID,
+)
+
+@dataclass
+class EntityRegistry:
+    entities: dict[SymbolID, Entity] = field(default_factory=dict)
+    fqn_to_ids: dict[str, set[SymbolID]] = field(default_factory=lambda: defaultdict(set))
+
+    def add(self, entity: Entity) -> None:
+        self.entities[entity.id] = entity
+        fqn = getattr(entity, "fqn", None)
+        if fqn:
+            self.fqn_to_ids[fqn].add(entity.id)
+
+    def add_all(self, entities: list[Entity]) -> None:
+        for entity in entities:
+            self.add(entity)
+
+    def remove(self, entity_id: SymbolID) -> None:
+        entity = self.entities.pop(entity_id, None)
+        if entity is not None:
+            fqn = getattr(entity, "fqn", None)
+            if fqn and entity_id in self.fqn_to_ids.get(fqn, set()):
+                self.fqn_to_ids[fqn].discard(entity_id)
+                if not self.fqn_to_ids[fqn]:
+                    del self.fqn_to_ids[fqn]
+
+    def get_ids_by_fqn(self, fqn: str) -> set[SymbolID]:
+        return set(self.fqn_to_ids.get(fqn, set()))
+
+    def values(self):
+        return self.entities.values()
+
+    def get(self, entity_id: SymbolID, default=None):
+        return self.entities.get(entity_id, default)
+
+    def __contains__(self, entity_id: SymbolID) -> bool:
+        return entity_id in self.entities

deproc_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: deproc-core
+Version: 0.1.0
+Summary: Language-agnostic core contracts and runtime for deproc plugins.
+Author-email: Gurveer Singh Virk <gurveervirk.15517@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/gurveervirk/deproc
+Project-URL: Repository, https://github.com/gurveervirk/deproc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10

deproc_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+deproc/core/__init__.py,sha256=byQSoqypO46cce6J7ykiEgVLzy90xdMvU38k_qigrA0,81
+deproc/core/context.py,sha256=oNRBB2OzXLpYLahe3IyAi2_G4Uu0VSfuiPocBJEoYmU,8283
+deproc/core/discovery.py,sha256=GUxOqSby7tzwGOHhjMN52rPg7gVDEkHMuZMZvSab0PE,743
+deproc/core/interfaces/__init__.py,sha256=fAScn456-iPQ8jhNMV5GcDcM4Hx80R5YJfMR8FQjsPA,209
+deproc/core/interfaces/linker.py,sha256=N1aRQp2L9Alks4_eygKXyxc091atoddt5bJ1wrMzILM,429
+deproc/core/interfaces/resolver.py,sha256=MuAX16ylFqnC12DzjmXglo6NfZZXIEHR3uB--eDlIuo,285
+deproc/core/interfaces/symbol_cache.py,sha256=Ah-FCeAs84OfbgGUm1H5fcBuzQZbnZBOHXEbBz5sfVE,377
+deproc/core/interfaces/parser/__init__.py,sha256=muqAf12npvewkM4cmK38oLyO6SQrn8SCwBjkIatE2jI,64
+deproc/core/interfaces/parser/base.py,sha256=PsbcKn9acd8oa7FR_K_dSJiFUANdITzbHzTLTWwfx18,321
+deproc/core/interfaces/parser/models.py,sha256=kDbbFxBVSjFs-m1_S5uIX4GoxJTjPEpyGS93P6sOnyQ,4147
+deproc/core/runtime/__init__.py,sha256=OQycEB3UA8DMZ2_OBIvjDzxGJubYe48fQAJ2KuqajJM,83
+deproc/core/runtime/registries/__init__.py,sha256=N4VQvTpcvzQTnKM7XvYhnzGqLVONQ69EImfD8K-hX-A,70
+deproc/core/runtime/registries/entity.py,sha256=fMbpIRkJ--t7ig_Q3RP1akQSWw2mHP1e-VMLLQJizgg,1425
+deproc_core-0.1.0.dist-info/METADATA,sha256=y0emwcdJGseLvbkbRBVCOd39aYIYoK37baNfnx_cRtg,870
+deproc_core-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+deproc_core-0.1.0.dist-info/top_level.txt,sha256=qyPIAnJVTLaewuAbLpShmn-777EtCI7b1b5sGgkzO10,7
+deproc_core-0.1.0.dist-info/RECORD,,

deproc_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

deproc_core-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+deproc