forgedock 1.26.0 → 1.28.0

package/scripts/symbol-index.py

@@ -0,0 +1,354 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# symbol-index.py: deterministic Python symbol index + module import-cycle detector for refactor:split (forge#4208).
+# stdlib only (ast). No LLM, no network. Never emits source text, docstrings or literal values.
+#
+# Usage: python3 scripts/symbol-index.py <file.py | dir>...
+# Output (stdout, one JSON object):
+#   {"symbols":[{name,kind,start,end,lines,public[,file]}], "edges":[{from,to}],
+#    "imports":[{module,names,line[,file]}], "cycles":[[module,...],...]}
+#   kind: function|async_function|class|method|const. Methods (and nested classes) are named Class.method.
+#   start includes decorators; lines = end - start + 1. public = no leading underscore (method dunders count as
+#   public), and listed in a static __all__ when the module defines one.
+#   One .py file: names are bare. Otherwise (a directory or several files) each entry carries `file` and edge ends
+#   are "<module>:<symbol>"; module names are dotted paths relative to each root (a root that has __init__.py is
+#   itself the top package, so root .../pkg yields pkg.a). edges = references from one indexed symbol to another.
+#   cycles = strongly connected components (size > 1, or a self-import) of the module-level import graph between
+#   indexed modules; function-local and `if TYPE_CHECKING:` imports are ignored. Everything is sorted, so a
+#   before/after pair of runs can be diffed for new cycles.
+# Unsupported input (non-.py file, no .py files, a file that does not parse) prints only
+#   {"unsupported":"<lang>","reason":"..."} and exits 0: never partial output.
+# Exit: 0 ok or unsupported | 2 usage or missing path.
+
+import ast
+import json
+import os
+import sys
+
+LANGS = {
+    ".ts": "ts", ".tsx": "ts", ".mts": "ts", ".cts": "ts",
+    ".js": "js", ".jsx": "js", ".mjs": "js", ".cjs": "js",
+    ".go": "go", ".rs": "rust", ".rb": "ruby", ".java": "java", ".kt": "kotlin",
+    ".c": "c", ".h": "c", ".cc": "cpp", ".cpp": "cpp", ".hpp": "cpp", ".cs": "csharp",
+    ".php": "php", ".swift": "swift", ".sh": "shell", ".bash": "shell",
+}
+SKIP_DIRS = {"__pycache__", "node_modules", "site-packages", "venv", "env"}
+
+
+class Unsupported(Exception):
+    def __init__(self, lang, reason):
+        super().__init__(reason)
+        self.lang, self.reason = lang, reason
+
+
+def lang_of(path):
+    ext = os.path.splitext(path)[1].lower()
+    return LANGS.get(ext, ext[1:] if ext else "unknown")
+
+
+def is_private(name):
+    return name.startswith("_")
+
+
+def is_dunder(name):
+    return len(name) > 4 and name.startswith("__") and name.endswith("__")
+
+
+def static_all(tree):
+    """Names in a statically readable module-level __all__, or None when absent or not static."""
+    names, seen = [], False
+    for node in tree.body:
+        if isinstance(node, ast.Assign) and any(isinstance(t, ast.Name) and t.id == "__all__" for t in node.targets):
+            value, seen, names = node.value, True, []
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.target.id == "__all__":
+            value, seen, names = node.value, True, []
+        elif isinstance(node, ast.AugAssign) and isinstance(node.target, ast.Name) and node.target.id == "__all__":
+            value = node.value
+        else:
+            continue
+        if not isinstance(value, (ast.List, ast.Tuple)):
+            return None
+        for elt in value.elts:
+            if not (isinstance(elt, ast.Constant) and isinstance(elt.value, str)):
+                return None
+            names.append(elt.value)
+    return set(names) if seen else None
+
+
+def def_start(node):
+    decos = getattr(node, "decorator_list", None) or []
+    return min([node.lineno] + [d.lineno for d in decos])
+
+
+def is_type_checking(test):
+    return (isinstance(test, ast.Name) and test.id == "TYPE_CHECKING") or (
+        isinstance(test, ast.Attribute) and test.attr == "TYPE_CHECKING")
+
+
+def module_imports(body):
+    """Import statements at module level (descending into if/try/with, never into def/class or TYPE_CHECKING)."""
+    out = []
+    for node in body:
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            out.append(node)
+        elif isinstance(node, ast.If):
+            if not is_type_checking(node.test):
+                out.extend(module_imports(node.body))
+            out.extend(module_imports(node.orelse))
+        elif isinstance(node, (ast.Try, getattr(ast, "TryStar", ast.Try))):
+            out.extend(module_imports(node.body))
+            for h in node.handlers:
+                out.extend(module_imports(h.body))
+            out.extend(module_imports(node.orelse))
+            out.extend(module_imports(node.finalbody))
+        elif isinstance(node, (ast.With, ast.AsyncWith)):
+            out.extend(module_imports(node.body))
+    return out
+
+
+class Module:
+    def __init__(self, path, name, is_pkg):
+        self.path, self.name, self.is_pkg = path, name, is_pkg
+        self.symbols = []      # dicts without file
+        self.nodes = {}        # symbol name -> (ast node, owning class name or None)
+        self.imports = []      # (ast import node)
+        self.tree = None
+
+    def parse(self):
+        try:
+            with open(self.path, "rb") as fh:
+                self.tree = ast.parse(fh.read(), filename=self.path)
+        except SyntaxError as e:
+            raise Unsupported("python", "parse-error: %s:%s" % (self.path, e.lineno or 0))
+        except (ValueError, UnicodeDecodeError, OSError):
+            raise Unsupported("python", "parse-error: %s:0" % self.path)
+        exported = static_all(self.tree)
+
+        def top_public(name):
+            return not is_private(name) and (exported is None or name in exported)
+
+        def add(name, kind, node, public, owner=None):
+            start, end = def_start(node), node.end_lineno or node.lineno
+            self.symbols.append({"name": name, "kind": kind, "start": start, "end": end,
+                                 "lines": end - start + 1, "public": public})
+            self.nodes[name] = (node, owner)
+
+        def add_class(node, prefix, public):
+            name = prefix + node.name
+            add(name, "class", node, public)
+            for item in node.body:
+                if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    mpub = public and (not is_private(item.name) or is_dunder(item.name))
+                    add(name + "." + item.name, "method", item, mpub, owner=name)
+                elif isinstance(item, ast.ClassDef):
+                    add_class(item, name + ".", public and not is_private(item.name))
+
+        for node in self.tree.body:
+            if isinstance(node, ast.FunctionDef):
+                add(node.name, "function", node, top_public(node.name))
+            elif isinstance(node, ast.AsyncFunctionDef):
+                add(node.name, "async_function", node, top_public(node.name))
+            elif isinstance(node, ast.ClassDef):
+                add_class(node, "", top_public(node.name))
+            elif isinstance(node, (ast.Assign, ast.AnnAssign)):
+                targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+                for t in targets:
+                    for n in ([t] if isinstance(t, ast.Name) else getattr(t, "elts", [])):
+                        if isinstance(n, ast.Name) and n.id not in self.nodes:
+                            add(n.id, "const", node, top_public(n.id))
+        self.imports = module_imports(self.tree.body)
+
+    def package(self):
+        return self.name if self.is_pkg else self.name.rpartition(".")[0]
+
+    def resolve(self, node):
+        """Absolute module named by an ImportFrom (relative levels resolved), or None when it climbs past the root."""
+        if node.level == 0:
+            return node.module or ""
+        parts = self.package().split(".") if self.package() else []
+        if node.level - 1 > len(parts):
+            return None
+        base = parts[:len(parts) - (node.level - 1)]
+        if node.module:
+            base = base + node.module.split(".")
+        return ".".join(base)
+
+
+def walk_roots(paths):
+    """[(path, module name, is_pkg)] for every .py file under the given roots, sorted."""
+    found = []
+    for root in paths:
+        root = os.path.normpath(root)
+        if os.path.isfile(root):
+            if not root.endswith(".py"):
+                raise Unsupported(lang_of(root), "unsupported-language")
+            stem = os.path.splitext(os.path.basename(root))[0]
+            found.append((root, stem, False))
+            continue
+        prefix = os.path.basename(os.path.abspath(root)) if os.path.isfile(os.path.join(root, "__init__.py")) else ""
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = sorted(d for d in dirnames if not d.startswith(".") and d not in SKIP_DIRS)
+            for fn in sorted(filenames):
+                if not fn.endswith(".py"):
+                    continue
+                path = os.path.join(dirpath, fn)
+                rel = os.path.relpath(path, root)[:-3].split(os.sep)
+                is_pkg = rel[-1] == "__init__"
+                if is_pkg:
+                    rel = rel[:-1]
+                name = ".".join(([prefix] if prefix else []) + rel)
+                found.append((path, name, is_pkg))
+    if not found:
+        raise Unsupported("unknown", "no-python-files")
+    return sorted(found)
+
+
+def tarjan(graph):
+    """Strongly connected components, iterative (no recursion limit on large packages)."""
+    index, low, on, stack, comps, counter = {}, {}, set(), [], [], [0]
+    for start in sorted(graph):
+        if start in index:
+            continue
+        work = [(start, iter(sorted(graph[start])))]
+        index[start] = low[start] = counter[0]; counter[0] += 1
+        stack.append(start); on.add(start)
+        while work:
+            v, it = work[-1]
+            advanced = False
+            for w in it:
+                if w not in index:
+                    index[w] = low[w] = counter[0]; counter[0] += 1
+                    stack.append(w); on.add(w)
+                    work.append((w, iter(sorted(graph.get(w, ())))))
+                    advanced = True
+                    break
+                if w in on:
+                    low[v] = min(low[v], index[w])
+            if advanced:
+                continue
+            work.pop()
+            if work:
+                low[work[-1][0]] = min(low[work[-1][0]], low[v])
+            if low[v] == index[v]:
+                comp = []
+                while True:
+                    w = stack.pop(); on.discard(w); comp.append(w)
+                    if w == v:
+                        break
+                comps.append(sorted(comp))
+    return comps
+
+
+def build(paths):
+    entries = walk_roots(paths)
+    multi = not (len(entries) == 1 and os.path.isfile(paths[0]) and len(paths) == 1)
+    modules, by_name = [], {}
+    for path, name, is_pkg in entries:
+        m = Module(path, name, is_pkg)
+        m.parse()
+        modules.append(m)
+        by_name.setdefault(name, m)
+
+    def ref(m, sym):
+        return "%s:%s" % (m.name, sym) if multi else sym
+
+    symbols, imports, edges, graph = [], [], set(), {m.name: set() for m in modules}
+    for m in modules:
+        rel = os.path.relpath(m.path)
+        for s in m.symbols:
+            symbols.append(dict(s, file=rel) if multi else s)
+        # bindings: local name -> (module, symbol or None for a module object)
+        bindings, first_import = {}, len(imports)
+        for node in m.imports:
+            if isinstance(node, ast.Import):
+                for a in node.names:
+                    imports.append({"module": a.name, "names": [], "line": node.lineno})
+                    if a.name in by_name:
+                        graph[m.name].add(a.name)
+                    if a.asname:
+                        bindings[a.asname] = (a.name, None)
+                    else:
+                        bindings[a.name.split(".")[0]] = (a.name.split(".")[0], None)
+            else:
+                target = m.resolve(node)
+                shown = target if target is not None else "." * node.level + (node.module or "")
+                imports.append({"module": shown, "names": [a.name for a in node.names], "line": node.lineno})
+                if target is None:
+                    continue
+                for a in node.names:
+                    sub = (target + "." + a.name) if target else a.name
+                    if sub in by_name:
+                        graph[m.name].add(sub)
+                        bindings[a.asname or a.name] = (sub, None)
+                    elif target in by_name:
+                        graph[m.name].add(target)
+                        bindings[a.asname or a.name] = (target, a.name)
+        local = set(m.nodes)
+        for name, (node, owner) in m.nodes.items():
+            src = ref(m, name)
+            first_arg = None
+            if owner and isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.args.args:
+                first_arg = node.args.args[0].arg
+            body = [node]
+            if isinstance(node, ast.ClassDef):  # methods and nested classes are their own symbols
+                body = node.decorator_list + node.bases + [k.value for k in node.keywords] + [
+                    b for b in node.body if not isinstance(b, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef))]
+            elif isinstance(node, (ast.Assign, ast.AnnAssign)):
+                body = [node.value] if node.value is not None else []
+            for root in body:
+                for n in ast.walk(root):
+                    to = None
+                    if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Load):
+                        if n.id in local:
+                            to = ref(m, n.id)
+                        elif n.id in bindings:
+                            mod, sym = bindings[n.id]
+                            if sym is not None and sym in by_name[mod].nodes:
+                                to = "%s:%s" % (mod, sym)
+                    elif isinstance(n, ast.Attribute) and isinstance(n.value, ast.Name):
+                        base = n.value.id
+                        if owner and base == first_arg and (owner + "." + n.attr) in local:
+                            to = ref(m, owner + "." + n.attr)
+                        elif base in local and (base + "." + n.attr) in local:
+                            to = ref(m, base + "." + n.attr)
+                        elif base in bindings and bindings[base][1] is None:
+                            mod = bindings[base][0]
+                            if mod in by_name and n.attr in by_name[mod].nodes:
+                                to = "%s:%s" % (mod, n.attr)
+                    if to is not None and to != src:
+                        edges.add((src, to))
+        if multi:
+            for imp in imports[first_import:]:
+                imp["file"] = rel
+
+    cycles = sorted(c for c in tarjan(graph) if len(c) > 1 or c[0] in graph[c[0]])
+    if multi:
+        symbols.sort(key=lambda s: (s["file"], s["start"], s["name"]))
+        imports.sort(key=lambda i: (i["file"], i["line"], i["module"]))
+    else:
+        symbols.sort(key=lambda s: (s["start"], s["name"]))
+        imports.sort(key=lambda i: (i["line"], i["module"]))
+    return {"symbols": symbols, "edges": [{"from": f, "to": t} for f, t in sorted(edges)],
+            "imports": imports, "cycles": cycles}
+
+
+def main(argv):
+    if not argv or argv[0] in ("-h", "--help"):
+        sys.stderr.write("usage: symbol-index.py <file.py | dir>...\n")
+        return 2
+    for p in argv:
+        if not os.path.exists(p):
+            sys.stderr.write("symbol-index: no such path: %s\n" % p)
+            return 2
+    try:
+        out = build(argv)
+    except Unsupported as u:
+        out = {"unsupported": u.lang, "reason": u.reason}
+    sys.stdout.write(json.dumps(out, sort_keys=True, separators=(",", ":")) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/symbol-index.test.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# symbol-index.test.sh — cases for scripts/symbol-index.{py,mjs} (forge#4208).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Optional: SYMBOL_INDEX_TS_NODE_MODULES=<node_modules holding typescript@5> also runs the TS-parser cases.
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PY="$HERE/symbol-index.py"; MJS="$HERE/symbol-index.mjs"; FX="$HERE/fixtures/symbol-index"
+PASS=0; FAILN=0
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/symbol-index-test.XXXXXX")"; trap 'rm -rf "$TMP"' EXIT
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+eq() { if [ "$2" = "$3" ]; then ok; else bad "$1 (got: $2 want: $3)"; fi }
+q() { printf '%s' "$OUT" | jq -c "$1"; }
+run() { OUT="$("$@" 2>"$TMP/err")"; RC=$?; }
+
+# ---- 1. Python file: schema, symbols, spans, public flags ----
+run python3 "$PY" "$FX/py/sample.py"
+eq "py file rc" "$RC" 0
+eq "py top-level keys" "$(q 'keys')" '["cycles","edges","imports","symbols"]'
+eq "symbol keys" "$(q '[.symbols[]|keys]|unique')" '[["end","kind","lines","name","public","start"]]'
+eq "symbol names" "$(q '[.symbols[].name]')" \
+  '["__all__","LIMIT","_cache","_normalise","greet","fetch","helper","Greeter","Greeter.__init__","Greeter.text","Greeter._shout","Greeter.shout"]'
+eq "kinds" "$(q '[.symbols[]|select(.name=="LIMIT" or .name=="greet" or .name=="fetch" or .name=="Greeter" or .name=="Greeter.shout")|.kind]')" \
+  '["const","function","async_function","class","method"]'
+eq "greet span" "$(q '.symbols[]|select(.name=="greet")|[.start,.end,.lines]')" '[15,16,2]'
+eq "class span" "$(q '.symbols[]|select(.name=="Greeter")|[.start,.end,.lines]')" '[27,41,15]'
+eq "decorator in span" "$(q '.symbols[]|select(.name=="Greeter.text")|[.start,.end,.lines]')" '[33,35,3]'
+eq "public set" "$(q '[.symbols[]|select(.public)|.name]')" \
+  '["LIMIT","greet","fetch","Greeter","Greeter.__init__","Greeter.text","Greeter.shout"]'
+eq "helper not in __all__" "$(q '.symbols[]|select(.name=="helper")|.public')" 'false'
+
+# ---- 2. edges and imports ----
+eq "edges" "$(q '[.edges[]|"\(.from)>\(.to)"]')" \
+  '["Greeter._shout>Greeter.text","Greeter.shout>Greeter._shout","Greeter.text>greet","fetch>LIMIT","fetch>_cache","greet>_normalise"]'
+eq "imports" "$(q '.imports')" \
+  '[{"line":2,"module":"os","names":[]},{"line":3,"module":"collections","names":["OrderedDict"]}]'
+eq "single file has no cycles" "$(q '.cycles')" '[]'
+
+# ---- 3. never includes file bodies ----
+for needle in SECRET_DOCSTRING_MARKER SECRET_CLASS_DOC_MARKER 'hi ' 'strip()' 'getcwd' 'return'; do
+  case "$OUT" in *"$needle"*) bad "output leaks source text: $needle" ;; *) ok ;; esac
+done
+
+# ---- 4. import cycles across modules ----
+run python3 "$PY" "$FX/py/pkg"
+eq "pkg rc" "$RC" 0
+eq "pkg cycles (TYPE_CHECKING + function-local imports ignored)" "$(q '.cycles')" '[["pkg.a","pkg.b"]]'
+eq "pkg relative import resolved" "$(q '[.imports[]|select(.file|endswith("b.py"))|.module]')" '["typing","pkg","pkg.a"]'
+eq "pkg cross-module edges" "$(q '[.edges[]|"\(.from)>\(.to)"]')" '["pkg.a:run>pkg.b:step","pkg.b:step>pkg.c:value"]'
+eq "pkg symbols carry file" "$(q '[.symbols[]|has("file")]|unique')" '[true]'
+BEFORE="$(q '.cycles')"
+cp -R "$FX/py/pkg" "$TMP/pkg"
+printf 'from . import a\n' > "$TMP/pkg/d.py"
+printf 'from . import d\n' >> "$TMP/pkg/c.py"
+run python3 "$PY" "$TMP/pkg"
+AFTER="$(q '.cycles')"
+eq "after: cycle set grows" "$AFTER" '[["pkg.a","pkg.b","pkg.c","pkg.d"]]'
+eq "before/after diff finds the new cycle" \
+  "$(jq -nc --argjson b "$BEFORE" --argjson a "$AFTER" '$a - $b')" '[["pkg.a","pkg.b","pkg.c","pkg.d"]]'
+printf 'import pkg.e\n' > "$TMP/pkg/e.py"
+run python3 "$PY" "$TMP/pkg"
+eq "self-import is a cycle" "$(q '.cycles|map(select(.==["pkg.e"]))|length')" '1'
+
+# ---- 5. deterministic ----
+A1="$(python3 "$PY" "$FX/py/pkg")"; A2="$(python3 "$PY" "$FX/py/pkg")"
+eq "byte-identical reruns" "$([ "$A1" = "$A2" ] && echo same)" same
+
+# ---- 6. unsupported: exit 0, only {unsupported, reason} ----
+for t in "$FX/other/sample.rb" "$FX/ts/sample.ts"; do
+  run python3 "$PY" "$t"
+  eq "py unsupported rc $(basename "$t")" "$RC" 0
+  eq "py unsupported keys $(basename "$t")" "$(q 'keys')" '["reason","unsupported"]'
+done
+eq "py unsupported lang" "$(python3 "$PY" "$FX/other/sample.rb" | jq -r .unsupported)" ruby
+run python3 "$PY" "$FX/py/sample.py" "$FX/other/sample.rb"
+eq "mixed input: no partial output" "$(q 'keys')" '["reason","unsupported"]'
+mkdir -p "$TMP/empty"; run python3 "$PY" "$TMP/empty"
+eq "dir without .py" "$(q '.')" '{"reason":"no-python-files","unsupported":"unknown"}'
+mkdir -p "$TMP/broken"; printf 'def ok():\n    return 1\n' > "$TMP/broken/good.py"; printf 'def broken(:\n' > "$TMP/broken/bad.py"
+run python3 "$PY" "$TMP/broken"
+eq "parse error rc" "$RC" 0
+eq "parse error: no partial symbols" "$(q 'keys')" '["reason","unsupported"]'
+eq "parse error reason" "$(q '.reason|startswith("parse-error: ")')" 'true'
+
+run node "$MJS" "$FX/other/sample.rb"
+eq "mjs ruby rc" "$RC" 0
+eq "mjs ruby" "$(q '.')" '{"reason":"unknown-language","unsupported":"ruby"}'
+mkdir -p "$TMP/ts"; cp "$FX/ts/sample.ts" "$TMP/ts/"
+run node "$MJS" "$TMP/ts/sample.ts"
+eq "mjs ts without parser rc" "$RC" 0
+eq "mjs ts without parser" "$(q '.')" '{"reason":"no-parser","unsupported":"ts"}'
+run node "$MJS" "$FX/py/sample.py"
+eq "mjs delegates .py" "$(q '.symbols|length')" '12'
+
+# ---- 7. usage ----
+python3 "$PY" >/dev/null 2>&1; eq "py no args" "$?" 2
+python3 "$PY" "$TMP/missing.py" >/dev/null 2>&1; eq "py missing path" "$?" 2
+node "$MJS" >/dev/null 2>&1; eq "mjs no args" "$?" 2
+
+# ---- 8. optional: TS parser path ----
+if [ -n "${SYMBOL_INDEX_TS_NODE_MODULES:-}" ] && [ -d "$SYMBOL_INDEX_TS_NODE_MODULES/typescript" ]; then
+  ln -s "$SYMBOL_INDEX_TS_NODE_MODULES" "$TMP/ts/node_modules"
+  run node "$MJS" "$TMP/ts/sample.ts"
+  eq "ts symbols" "$(q '[.symbols[]|"\(.kind):\(.name):\(.start)-\(.end):\(.public)"]')" \
+    '["const:LIMIT:3-3:true","function:load:5-7:true","class:Loader:9-13:true","method:Loader.read:10-12:true"]'
+  eq "ts edges" "$(q '[.edges[]|"\(.from)>\(.to)"]')" '["Loader.read>load","load>LIMIT"]'
+  mkdir -p "$TMP/ts/lib"
+  printf 'import { b } from "./b";\nimport type { T } from "./c";\nexport function a(): number { return b(); }\n' > "$TMP/ts/lib/a.ts"
+  printf 'import * as A from "./a.js";\nexport const b = () => 2;\nexport function useA() { return A.a(); }\n' > "$TMP/ts/lib/b.ts"
+  printf 'import { a } from "./a";\nexport type T = number;\n' > "$TMP/ts/lib/c.ts"
+  run node "$MJS" "$TMP/ts/lib"
+  eq "ts cycles (import type ignored)" "$(q '.cycles')" '[["a","b"]]'
+else
+  echo "symbol-index.test.sh: TS-parser cases skipped (set SYMBOL_INDEX_TS_NODE_MODULES)"
+fi
+
+echo "symbol-index.test.sh: $PASS passed, $FAILN failed"
+[ "$FAILN" -eq 0 ]

package/scripts/symbol-move-ts.test.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# symbol-move-ts.test.sh — cases for scripts/symbol-move.mjs, the ts-morph mover (forge#4212).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Builds a throwaway git repo from scripts/fixtures/symbol-move-ts/gen_big.mjs (~700-line src/big.ts + node:test
+# suite), moves four symbol groups into src/big_parts/ and proves the move with scripts/refactor-verify.sh; then
+# checks the refusals, the --extend chain step and the no-ts-morph refusal (no partial edits).
+# ts-morph: SYMBOL_MOVE_TS_NODE_MODULES=<node_modules holding ts-morph> (put on NODE_PATH for the mover, the symbol
+# index and refactor-verify). Without it the ts-morph cases are skipped; SYMBOL_MOVE_REQUIRE_TS_MORPH=1 turns that
+# skip into a failure.
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SM="$HERE/symbol-move.mjs"; RV="$HERE/refactor-verify.sh"; GEN="$HERE/fixtures/symbol-move-ts/gen_big.mjs"
+PASS=0; FAILN=0
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/symbol-move-ts-test.XXXXXX")"; trap 'rm -rf "$TMP"' EXIT
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+eq() { if [ "$2" = "$3" ]; then ok; else bad "$1 (got: $2 want: $3)"; fi }
+has() { if grep -qF -- "$2" "$3"; then ok; else bad "$1 (no '$2' in $3)"; fi }
+q() { printf '%s' "$OUT" | jq -c "$1"; }
+TSM="${SYMBOL_MOVE_TS_NODE_MODULES:-}"
+[ -n "$TSM" ] && [ -d "$TSM/ts-morph" ] || TSM=""
+# without: no NODE_PATH and a HOME holding no node_modules, so ts-morph cannot resolve from anywhere
+without() { OUT="$(cd "$R" && env -u NODE_PATH HOME="$TMP/home" node "$SM" "$@" 2>"$TMP/err")"; RC=$?; }
+mover() { OUT="$(cd "$R" && NODE_PATH="$TSM" node "$SM" "$@" 2>"$TMP/err")"; RC=$?; }
+mkdir -p "$TMP/home"
+
+R="$TMP/repo"; B="$TMP/baseline.json"; P="$TMP/plan.json"
+TEST_CMD='node --test test/big.test.ts'
+g() { git -C "$R" -c user.name=t -c user.email=t@example.invalid "$@"; }
+mkdir -p "$R"; git init -q "$R"
+node "$GEN" "$R" || bad "generator failed"
+g add -A && g commit -qm base && g tag base
+eq "fixture size >= 600 lines" "$([ "$(wc -l < "$R/src/big.ts")" -ge 600 ] && echo yes || echo no)" yes
+SHA0="$(git -C "$R" hash-object src/big.ts)"
+reset() { g reset -q --hard base; g clean -fdq; }
+
+seqp() { local f="$1" s=""; for i in $(seq -w 0 19); do s="$s\"$(printf "$f" "$i")\","; done; printf '%s' "${s%,}"; }
+plan() { printf '%s' "$1" | jq -c . > "$2" || bad "bad plan json"; }
+CONSTS="[$(seqp 'LIMIT_%s')]"
+HELPERS="[$(for i in $(seq -w 0 19); do printf '"_scale_%s","compute_%s",' "$i" "$i"; done | sed 's/,$//')]"
+MODELS="[$(seqp 'Item_%s'),$(seqp 'Store_%s')]"
+AIO="[$(seqp 'fetch_%s')]"
+FULL="{\"consts\":$CONSTS,\"helpers\":$HELPERS,\"models\":$MODELS,\"aio\":$AIO}"
+plan "$FULL" "$P"
+
+# refused <label>: rc 3, status refused, a reason, and nothing changed in the repo
+refused() {
+  eq "$1: rc" "$RC" 3
+  eq "$1: status" "$(q '.status')" '"refused"'
+  eq "$1: has reason" "$(q '.reason|length>0')" true
+  eq "$1: tree untouched" "$(git -C "$R" status --porcelain)" ""
+  eq "$1: barrel untouched" "$(git -C "$R" hash-object src/big.ts)" "$SHA0"
+}
+
+# ---- 1. no codemod tool: ts-morph unresolvable -> clean refusal before anything is read or written ----
+without --src src/big.ts --plan "$P"
+refused "no ts-morph"
+eq "no ts-morph: reason" "$(q '.reason|startswith("no codemod tool for ts: ts-morph is not resolvable")')" true
+without --probe --src src/big.ts
+eq "no ts-morph probe: rc" "$RC" 3
+eq "no ts-morph probe: reason" "$(q '.reason|startswith("no codemod tool for ts:")')" true
+eq "no ts-morph: no package dir" "$([ -e "$R/src/big_parts" ] && echo yes || echo no)" no
+
+# ---- 2. usage ----
+OUT="$(node "$SM" --plan "$P" 2>/dev/null)"; eq "usage: rc" "$?" 2
+OUT="$(node "$SM" --src "$R/src/nope.ts" --plan "$P" 2>/dev/null)"; eq "missing src: rc" "$?" 2
+
+if [ -z "$TSM" ]; then
+  if [ "${SYMBOL_MOVE_REQUIRE_TS_MORPH:-0}" = "1" ]; then bad "ts-morph required (SYMBOL_MOVE_REQUIRE_TS_MORPH=1) but SYMBOL_MOVE_TS_NODE_MODULES has no ts-morph"; fi
+  echo "symbol-move-ts.test.sh: ts-morph cases skipped (set SYMBOL_MOVE_TS_NODE_MODULES)"
+  echo "symbol-move-ts.test.sh: $PASS passed, $FAILN failed"
+  [ "$FAILN" -eq 0 ]; exit
+fi
+export NODE_PATH="$TSM"
+
+# ---- 3. probe and dry run ----
+mover --probe --src src/big.ts
+eq "probe: rc" "$RC" 0
+eq "probe: tool" "$(q '.tool')" '"ts-morph"'
+mover --src src/big.ts --plan "$P" --dry-run
+eq "dry-run: rc" "$RC" 0
+eq "dry-run: tree untouched" "$(git -C "$R" status --porcelain)" ""
+
+# ---- 4. the move: four groups into src/big_parts/, barrel at the old path, refactor-verify ok ----
+bash "$RV" baseline --root "$R" --target src/big.ts --test-cmd "$TEST_CMD" --out "$B" >/dev/null 2>"$TMP/err" || { cat "$TMP/err"; bad "baseline failed"; }
+eq "baseline counts" "$(jq -c .test "$B")" '{"exit":0,"passed":5,"skipped":1}'
+eq "baseline flags erased types" "$(jq -c '[.symbols[]|select(.type)]|length' "$B")" 20
+mover --src src/big.ts --plan "$P"
+eq "move: rc" "$RC" 0
+eq "move: status" "$(q '.status')" '"ok"'
+eq "move: package" "$(q '.package')" '"src/big_parts"'
+eq "move: modules" "$(q '.modules|keys')" '["aio","consts","helpers","models"]'
+for m in consts helpers models aio; do
+  eq "module $m exists" "$([ -f "$R/src/big_parts/$m.ts" ] && echo yes || echo no)" yes
+  has "barrel re-exports $m" "} from \"./big_parts/$m.ts\";" "$R/src/big.ts"
+done
+has "barrel re-exports types with type" 'export { type Item_00, Store_00,' "$R/src/big.ts"
+has "barrel imports names kept code uses" 'import { compute_00 } from "./big_parts/helpers.ts";' "$R/src/big.ts"
+has "barrel keeps unmoved code" 'function _shared(x: number): number {' "$R/src/big.ts"
+has "barrel keeps the header" '// SPDX-License-Identifier: MIT' "$R/src/big.ts"
+has "relative import re-based" 'import { clamp } from "../util.ts";' "$R/src/big_parts/helpers.ts"
+has "type import pruned and re-based" 'import { type Unit } from "../util.ts";' "$R/src/big_parts/models.ts"
+has "sibling import" 'import { compute_00, compute_01,' "$R/src/big_parts/models.ts"
+has "private helper moved verbatim" 'function _scale_07(x: number): number {' "$R/src/big_parts/helpers.ts"
+has "doc comment moved" '/** compute 7: scaled and clamped. */' "$R/src/big_parts/helpers.ts"
+eq "no moved declaration left" "$(grep -c '^export function compute_\|^function _scale_\|^export class Store_\|^export interface Item_' "$R/src/big.ts")" 0
+g add -A && g commit -qm move
+OUT="$(bash "$RV" verify --baseline "$B" --base base 2>"$TMP/err")"; RC=$?
+eq "verify: rc" "$RC" 0
+eq "verify: ok" "$(q '.ok')" true
+# a dropped type re-export is caught statically
+sed -i.bak 's/export { type Item_00, Store_00, /export { Store_00, /' "$R/src/big.ts"; rm -f "$R/src/big.ts.bak"
+g commit -qam drop-type
+OUT="$(bash "$RV" verify --baseline "$B" --base base 2>"$TMP/err")"; RC=$?
+eq "dropped type: rc" "$RC" 1
+eq "dropped type: missing" "$(q '[.failures[]|select(.kind=="missing-symbol")|.name]')" '["Item_00"]'
+reset
+
+# ---- 5. refusals: nothing touched ----
+plan '{"a":["nope"]}' "$P"; mover --src src/big.ts --plan "$P"; refused "unknown symbol"
+plan '{"a":["LIMIT_00"],"b":["LIMIT_00"]}' "$P"; mover --src src/big.ts --plan "$P"; refused "listed twice"
+plan '{"a":["Store_00.add"]}' "$P"; mover --src src/big.ts --plan "$P"; refused "method"
+plan '{"index":["LIMIT_00"]}' "$P"; mover --src src/big.ts --plan "$P"; refused "bad module name"
+plan '{"a":["compute_00"]}' "$P"; mover --src src/big.ts --plan "$P"; refused "needs a kept name"
+eq "needs a kept name: reason" "$(q '.reason|test("needs \"_scale_00\", which stays")')" true
+plan '{"a":["_shared"]}' "$P"; mover --src src/big.ts --plan "$P"; refused "private used by kept code"
+eq "private used by kept code: reason" "$(q '.reason|test("not exported but kept code uses it")')" true
+plan '{"a":["_scale_00","LIMIT_00"],"b":["compute_00"]}' "$P"; mover --src src/big.ts --plan "$P"; refused "private used by a sibling"
+eq "private used by a sibling: reason" "$(q '.reason|test("not exported")')" true
+plan '{"a":["ping"],"b":["pong"]}' "$P"; mover --src src/big.ts --plan "$P"; refused "cycle"
+eq "cycle: reason" "$(q '.reason|test("import cycle")')" true
+mkdir -p "$R/src/big_parts"; plan "{\"consts\":$CONSTS}" "$P"; mover --src src/big.ts --plan "$P"
+eq "existing package: rc" "$RC" 3
+eq "existing package: reason" "$(q '.reason|test("already exists")')" true
+rmdir "$R/src/big_parts"
+printf 'export default function main(): number {\n  return 1;\n}\n' >> "$R/src/big.ts"; g commit -qam default; SHA0="$(git -C "$R" hash-object src/big.ts)"
+plan '{"a":["main"]}' "$P"; mover --src src/big.ts --plan "$P"; refused "export default"
+printf 'export const HERE = import.meta.url;\n' >> "$R/src/big.ts"; g commit -qam meta; SHA0="$(git -C "$R" hash-object src/big.ts)"
+plan '{"a":["HERE"]}' "$P"; mover --src src/big.ts --plan "$P"; refused "import.meta"
+reset; SHA0="$(git -C "$R" hash-object src/big.ts)"
+
+# ---- 6. chain: a second step adds modules to the existing package with --extend ----
+plan "{\"consts\":$CONSTS,\"helpers\":$HELPERS}" "$P"; mover --src src/big.ts --plan "$P"
+eq "chain step 1: rc" "$RC" 0
+g add -A && g commit -qm step1
+plan "{\"models\":$MODELS}" "$P"; mover --src src/big.ts --plan "$P" --package big_parts
+eq "chain without --extend: rc" "$RC" 3
+plan "{\"models\":$MODELS}" "$P"; mover --src src/big.ts --plan "$P" --package big_parts --extend
+eq "chain step 2: rc" "$RC" 0
+has "chain step 2: barrel" '} from "./big_parts/models.ts";' "$R/src/big.ts"
+has "chain step 2: earlier module imported in-package" '} from "./helpers.ts";' "$R/src/big_parts/models.ts"
+g add -A && g commit -qm step2
+OUT="$(bash "$RV" verify --baseline "$B" --base base 2>"$TMP/err")"; RC=$?
+eq "chain verify: ok" "$(q '.ok')" true
+plan "{\"models\":[\"fetch_00\"]}" "$P"; mover --src src/big.ts --plan "$P" --package big_parts --extend
+eq "chain existing module: rc" "$RC" 3
+eq "chain existing module: reason" "$(q '.reason|test("module already exists")')" true
+
+echo "symbol-move-ts.test.sh: $PASS passed, $FAILN failed"
+[ "$FAILN" -eq 0 ]