substratum-cli 0.1.0__py3-none-any.whl

substratum_cli/langscan.py

@@ -0,0 +1,110 @@
+"""Multi-language declaration scanner -- every language Substratum services, no gaps, no deps.
+
+Grain: name the top-level definitions (functions / methods / classes / structs / interfaces / types
+/ enums) per file, so the `summarize` surface describes a codebase in ANY serviced language, not just
+Python. Stdlib-only (air-gapped): Python is exact via `ast`; Go and TS/JS use closed-class declaration
+regexes. NOT a full parser -- summarize needs symbol NAMES + kind, which regex resolves faithfully at
+this grain. Returns a flat list of {name, kind} declarations; the caller aggregates + glosses.
+"""
+from __future__ import annotations
+
+import ast
+import re
+from typing import Dict, List
+
+# every extension we service -> language bucket
+LANGS: Dict[str, str] = {
+    ".py": "py", ".pyi": "py",
+    ".go": "go",
+    ".ts": "ts", ".tsx": "ts", ".mts": "ts", ".cts": "ts",
+    ".js": "js", ".jsx": "js", ".mjs": "js", ".cjs": "js",
+}
+
+_IDENT = r"[A-Za-z_$][\w$]*"
+
+
+def scan(text: str, ext: str) -> List[dict]:
+    """[{name, kind}] for one file. kind in {function, method, class, struct, interface, type, enum}."""
+    lang = LANGS.get(ext)
+    if lang == "py":
+        return _scan_py(text)
+    if lang == "go":
+        return _scan_go(text)
+    if lang in ("ts", "js"):
+        return _scan_ts(text)
+    return []
+
+
+def _scan_py(text: str) -> List[dict]:
+    out: List[dict] = []
+    try:
+        tree = ast.parse(text)
+    except Exception:
+        return out
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            out.append({"name": node.name, "kind": "function"})
+        elif isinstance(node, ast.ClassDef):
+            out.append({"name": node.name, "kind": "class"})
+            for m in node.body:
+                if isinstance(m, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    out.append({"name": m.name, "kind": "method"})
+    return out
+
+
+_GO_FUNC = re.compile(r"^func\s+(" + _IDENT + r")\s*\(", re.M)
+_GO_METHOD = re.compile(r"^func\s+\([^)]*\)\s+(" + _IDENT + r")\s*\(", re.M)
+_GO_TYPE = re.compile(r"^type\s+(" + _IDENT + r")\s+(struct|interface)\b", re.M)
+_GO_TYPE_OTHER = re.compile(r"^type\s+(" + _IDENT + r")\s+(?!struct|interface)\S", re.M)
+
+
+def _scan_go(text: str) -> List[dict]:
+    out: List[dict] = []
+    for m in _GO_FUNC.finditer(text):
+        out.append({"name": m.group(1), "kind": "function"})
+    for m in _GO_METHOD.finditer(text):
+        out.append({"name": m.group(1), "kind": "method"})
+    for m in _GO_TYPE.finditer(text):
+        out.append({"name": m.group(1), "kind": "struct" if m.group(2) == "struct" else "interface"})
+    for m in _GO_TYPE_OTHER.finditer(text):
+        out.append({"name": m.group(1), "kind": "type"})
+    return out
+
+
+_TS_FUNC = re.compile(
+    r"^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s*\*?\s*(" + _IDENT + r")", re.M)
+_TS_ARROW = re.compile(
+    r"^\s*(?:export\s+)?(?:default\s+)?(?:const|let|var)\s+(" + _IDENT +
+    r")\s*(?::[^=]+)?=\s*(?:async\s*)?(?:<[^>]*>\s*)?\([^)]*\)\s*(?::[^=]+?)?=>", re.M)
+_TS_CLASS = re.compile(r"^\s*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+(" + _IDENT + r")", re.M)
+_TS_IFACE = re.compile(r"^\s*(?:export\s+)?interface\s+(" + _IDENT + r")", re.M)
+_TS_TYPE = re.compile(r"^\s*(?:export\s+)?type\s+(" + _IDENT + r")\s*[=<]", re.M)
+_TS_ENUM = re.compile(r"^\s*(?:export\s+)?(?:const\s+)?enum\s+(" + _IDENT + r")", re.M)
+# a class-body member method: indented `name(args) {` or `name(args):` (not a control keyword)
+_TS_METHOD = re.compile(
+    r"^\s+(?:public\s+|private\s+|protected\s+|static\s+|async\s+|readonly\s+|get\s+|set\s+|\*\s*)*"
+    r"(" + _IDENT + r")\s*\([^)]*\)\s*[:{]", re.M)
+_TS_KEYWORDS = frozenset({"if", "for", "while", "switch", "catch", "return", "function",
+                          "constructor", "super", "await", "yield", "typeof", "case", "do", "else"})
+
+
+def _scan_ts(text: str) -> List[dict]:
+    out: List[dict] = []
+    top_fn = set()
+    for m in _TS_FUNC.finditer(text):
+        out.append({"name": m.group(1), "kind": "function"}); top_fn.add(m.group(1))
+    for m in _TS_ARROW.finditer(text):
+        out.append({"name": m.group(1), "kind": "function"}); top_fn.add(m.group(1))
+    for m in _TS_CLASS.finditer(text):
+        out.append({"name": m.group(1), "kind": "class"})
+    for m in _TS_IFACE.finditer(text):
+        out.append({"name": m.group(1), "kind": "interface"})
+    for m in _TS_TYPE.finditer(text):
+        out.append({"name": m.group(1), "kind": "type"})
+    for m in _TS_ENUM.finditer(text):
+        out.append({"name": m.group(1), "kind": "enum"})
+    for m in _TS_METHOD.finditer(text):     # best-effort class methods (indented members)
+        nm = m.group(1)
+        if nm not in _TS_KEYWORDS and nm not in top_fn:
+            out.append({"name": nm, "kind": "method"})
+    return out