forgedock 1.27.0 → 1.28.0

package/scripts/symbol-index.mjs

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// symbol-index.mjs: JS/TS twin of scripts/symbol-index.py (forge#4208), same output schema.
+// No new dependencies: the `typescript` package is loaded from the target repo (resolved from the target path, then
+// cwd; NODE_PATH is honoured), else the TypeScript bundled with ts-morph (forge#4212). When neither is installed the
+// run prints only {"unsupported":"ts"|"js","reason":"no-parser"} and exits 0.
+// .py targets are handed to symbol-index.py. Never emits source text or literal values.
+//
+// Usage: node scripts/symbol-index.mjs <file | dir>...
+// Output: {"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|interface|type|enum. public = exported (methods: exported class
+//   and not private/#private). One file: bare names; otherwise `file` on entries and "<module>:<symbol>" edge ends,
+//   module = path relative to its root without extension (index files name their directory). cycles = strongly
+//   connected components of the relative-import graph between indexed modules (`import type` ignored).
+// Exit: 0 ok or unsupported | 2 usage or missing path.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TS_EXT = [".ts", ".tsx", ".mts", ".cts"];
+const JS_EXT = [".js", ".jsx", ".mjs", ".cjs"];
+const SKIP_DIRS = new Set(["node_modules", "dist", "build", "coverage"]);
+const OTHER = { ".go": "go", ".rs": "rust", ".rb": "ruby", ".java": "java", ".sh": "shell", ".php": "php" };
+
+const emit = (o) => process.stdout.write(JSON.stringify(sortKeys(o)) + "\n");
+function sortKeys(v) {
+  if (Array.isArray(v)) return v.map(sortKeys);
+  if (v && typeof v === "object") return Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeys(v[k])]));
+  return v;
+}
+const langOf = (ext) => (TS_EXT.includes(ext) ? "ts" : JS_EXT.includes(ext) ? "js" : ext === ".py" ? "python" : OTHER[ext] || ext.slice(1) || "unknown");
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+function loadTs(targets) {
+  const bases = [...targets.map((t) => path.resolve(statSync(t).isDirectory() ? t : path.dirname(t))), process.cwd()];
+  for (const b of bases) {
+    // typescript >= 7 (native port) ships no in-process compiler API at the package root: skip it.
+    try { const ts = createRequire(path.join(b, "noop.js"))("typescript"); if (typeof ts?.createSourceFile === "function") return ts; } catch { /* try next */ }
+  }
+  // forge#4212: a repo with only ts-morph (the refactor:split TS mover) has TypeScript bundled in @ts-morph/common.
+  for (const b of bases) {
+    try { const ts = createRequire(path.join(b, "noop.js"))("ts-morph").ts; if (typeof ts?.createSourceFile === "function") return ts; } catch { /* try next */ }
+  }
+  return null;
+}
+
+function collect(roots) {
+  const found = [];
+  for (const root of roots) {
+    if (statSync(root).isFile()) {
+      const ext = path.extname(root).toLowerCase();
+      found.push({ file: root, module: path.basename(root, path.extname(root)), ext });
+      continue;
+    }
+    const walk = (dir) => {
+      for (const ent of readdirSync(dir, { withFileTypes: true }).sort((a, b) => cmp(a.name, b.name))) {
+        const p = path.join(dir, ent.name);
+        if (ent.isDirectory()) { if (!ent.name.startsWith(".") && !SKIP_DIRS.has(ent.name)) walk(p); continue; }
+        const ext = path.extname(ent.name).toLowerCase();
+        if (![...TS_EXT, ...JS_EXT].includes(ext) || /\.d\.[cm]?ts$/.test(ent.name)) continue;
+        let mod = path.relative(root, p).slice(0, -ext.length).split(path.sep).join("/");
+        if (mod === "index" || mod.endsWith("/index")) mod = mod.slice(0, -"index".length).replace(/\/$/, "") || ".";
+        found.push({ file: p, module: mod, ext });
+      }
+    };
+    walk(root);
+  }
+  return found.sort((a, b) => cmp(a.file, b.file));
+}
+
+function tarjan(graph) {
+  let i = 0;
+  const index = new Map(), low = new Map(), on = new Set(), stack = [], comps = [];
+  const visit = (v) => {
+    index.set(v, i); low.set(v, i); i++; stack.push(v); on.add(v);
+    for (const w of [...(graph.get(v) || [])].sort()) {
+      if (!index.has(w)) { visit(w); low.set(v, Math.min(low.get(v), low.get(w))); }
+      else if (on.has(w)) low.set(v, Math.min(low.get(v), index.get(w)));
+    }
+    if (low.get(v) === index.get(v)) {
+      const comp = [];
+      let w;
+      do { w = stack.pop(); on.delete(w); comp.push(w); } while (w !== v);
+      comps.push(comp.sort());
+    }
+  };
+  for (const v of [...graph.keys()].sort()) if (!index.has(v)) visit(v);
+  return comps;
+}
+
+function index(ts, entries, multi) {
+  const K = ts.SyntaxKind;
+  const byFile = new Map(entries.map((e) => [path.resolve(e.file), e]));
+  const symbols = [], imports = [], edges = new Set(), graph = new Map(entries.map((e) => [e.module, new Set()]));
+  const tables = new Map(); // module -> Map(name -> node)
+  const parsed = entries.map((e) => {
+    const src = ts.createSourceFile(e.file, readFileSync(e.file, "utf8"), ts.ScriptTarget.Latest, true,
+      e.ext.endsWith("x") ? ts.ScriptKind.TSX : undefined);
+    if (src.parseDiagnostics?.length) throw { lang: langOf(e.ext), reason: `parse-error: ${e.file}` };
+    return { e, src };
+  });
+  const line = (src, pos) => src.getLineAndCharacterOfPosition(pos).line + 1;
+  const exported = (n) => (ts.getCombinedModifierFlags?.(n) ?? 0) & ts.ModifierFlags.Export;
+  const ref = (e, name) => (multi ? `${e.module}:${name}` : name);
+
+  for (const { e, src } of parsed) {
+    const table = new Map();
+    tables.set(e.module, table);
+    const add = (name, kind, node, pub, owner = null) => {
+      const start = line(src, node.getStart(src)), end = line(src, node.getEnd());
+      symbols.push({ name, kind, start, end, lines: end - start + 1, public: !!pub, ...(multi ? { file: e.file } : {}) });
+      table.set(name, { node, owner });
+    };
+    const exportNames = new Set();
+    for (const st of src.statements) {
+      if (ts.isExportDeclaration(st) && !st.moduleSpecifier && st.exportClause && ts.isNamedExports(st.exportClause)) {
+        for (const el of st.exportClause.elements) exportNames.add((el.propertyName || el.name).text);
+      } else if (ts.isExportAssignment(st) && ts.isIdentifier(st.expression)) exportNames.add(st.expression.text);
+    }
+    const pub = (n, name) => exported(n) || exportNames.has(name);
+    for (const st of src.statements) {
+      if (ts.isFunctionDeclaration(st) && st.name) {
+        const isAsync = (st.modifiers || []).some((m) => m.kind === K.AsyncKeyword);
+        add(st.name.text, isAsync ? "async_function" : "function", st, pub(st, st.name.text));
+      } else if (ts.isClassDeclaration(st) && st.name) {
+        const cname = st.name.text, cpub = pub(st, cname);
+        add(cname, "class", st, cpub);
+        for (const m of st.members) {
+          if (!(ts.isMethodDeclaration(m) || ts.isGetAccessor(m) || ts.isSetAccessor(m) || ts.isConstructorDeclaration(m))) continue;
+          const mname = ts.isConstructorDeclaration(m) ? "constructor" : m.name && (m.name.text ?? m.name.getText(src));
+          if (!mname || table.has(`${cname}.${mname}`)) continue;
+          const priv = (m.modifiers || []).some((x) => x.kind === K.PrivateKeyword) || String(mname).startsWith("#");
+          add(`${cname}.${mname}`, "method", m, cpub && !priv, cname);
+        }
+      } else if (ts.isVariableStatement(st)) {
+        for (const d of st.declarationList.declarations) {
+          if (ts.isIdentifier(d.name)) add(d.name.text, "const", d, exported(st) || exportNames.has(d.name.text));
+        }
+      } else if (ts.isInterfaceDeclaration(st)) add(st.name.text, "interface", st, pub(st, st.name.text));
+      else if (ts.isTypeAliasDeclaration(st)) add(st.name.text, "type", st, pub(st, st.name.text));
+      else if (ts.isEnumDeclaration(st)) add(st.name.text, "enum", st, pub(st, st.name.text));
+    }
+  }
+
+  const resolveSpec = (fromFile, spec) => {
+    if (!spec.startsWith(".")) return null;
+    const base = path.resolve(path.dirname(fromFile), spec);
+    const stem = base.replace(/\.(m|c)?js$/, "");
+    const cands = [base, ...[...TS_EXT, ...JS_EXT].flatMap((x) => [stem + x, path.join(base, "index" + x)])];
+    for (const c of cands) if (byFile.has(c)) return byFile.get(c).module;
+    return null;
+  };
+
+  for (const { e, src } of parsed) {
+    const table = tables.get(e.module), bindings = new Map();
+    for (const st of src.statements) {
+      const isImp = ts.isImportDeclaration(st), isRe = ts.isExportDeclaration(st) && st.moduleSpecifier;
+      if (!isImp && !isRe) continue;
+      const spec = st.moduleSpecifier.text, names = [];
+      const typeOnly = isImp ? !!st.importClause?.isTypeOnly : !!st.isTypeOnly;
+      const target = resolveSpec(e.file, spec);
+      const clause = isImp ? st.importClause : null;
+      if (clause?.name) { names.push("default"); bindings.set(clause.name.text, [target, "default"]); }
+      const nb = isImp ? clause?.namedBindings : st.exportClause;
+      if (nb && ts.isNamespaceImport(nb)) { names.push("*"); bindings.set(nb.name.text, [target, null]); }
+      else if (nb && (ts.isNamedImports(nb) || ts.isNamedExports(nb))) {
+        for (const el of nb.elements) {
+          const orig = (el.propertyName || el.name).text;
+          names.push(orig);
+          if (isImp) bindings.set(el.name.text, [target, orig]);
+        }
+      }
+      imports.push({ module: target ?? spec, names: names.sort(), line: line(src, st.getStart(src)), ...(multi ? { file: e.file } : {}) });
+      if (target !== null && !typeOnly) graph.get(e.module).add(target);
+    }
+    for (const [name, { node, owner }] of table) {
+      const from = ref(e, name);
+      const roots = ts.isClassDeclaration(node)
+        ? [...(node.heritageClauses || []), ...node.members.filter((m) => !(ts.isMethodDeclaration(m) || ts.isGetAccessor(m) || ts.isSetAccessor(m) || ts.isConstructorDeclaration(m)))]
+        : [node];
+      const visit = (n) => {
+        let to = null;
+        if (ts.isPropertyAccessExpression(n) && ts.isIdentifier(n.name)) {
+          const obj = n.expression;
+          if (owner && obj.kind === K.ThisKeyword && table.has(`${owner}.${n.name.text}`)) to = ref(e, `${owner}.${n.name.text}`);
+          else if (ts.isIdentifier(obj) && bindings.has(obj.text) && bindings.get(obj.text)[1] === null) {
+            const [mod] = bindings.get(obj.text);
+            if (mod !== null && tables.get(mod)?.has(n.name.text)) to = `${mod}:${n.name.text}`;
+          }
+        } else if (ts.isIdentifier(n) && !(n.parent && ts.isPropertyAccessExpression(n.parent) && n.parent.name === n)) {
+          if (n !== node.name && table.has(n.text)) to = ref(e, n.text);
+          else if (bindings.has(n.text)) {
+            const [mod, sym] = bindings.get(n.text);
+            if (mod !== null && sym !== null && tables.get(mod)?.has(sym)) to = `${mod}:${sym}`;
+          }
+        }
+        if (to && to !== from) edges.add(JSON.stringify([from, to]));
+        ts.forEachChild(n, visit);
+      };
+      for (const r of roots) visit(r);
+    }
+  }
+
+  const cycles = tarjan(graph).filter((c) => c.length > 1 || graph.get(c[0]).has(c[0])).sort((a, b) => cmp(a.join("\0"), b.join("\0")));
+  symbols.sort((a, b) => cmp(a.file || "", b.file || "") || a.start - b.start || cmp(a.name, b.name));
+  imports.sort((a, b) => cmp(a.file || "", b.file || "") || a.line - b.line || cmp(a.module, b.module));
+  return {
+    symbols,
+    edges: [...edges].sort().map((s) => { const [from, to] = JSON.parse(s); return { from, to }; }),
+    imports,
+    cycles,
+  };
+}
+
+function main(argv) {
+  if (!argv.length || argv[0] === "-h" || argv[0] === "--help") {
+    process.stderr.write("usage: symbol-index.mjs <file | dir>...\n");
+    return 2;
+  }
+  for (const p of argv) if (!existsSync(p)) { process.stderr.write(`symbol-index: no such path: ${p}\n`); return 2; }
+  const files = argv.filter((p) => statSync(p).isFile());
+  const exts = files.map((f) => path.extname(f).toLowerCase());
+  if (exts.includes(".py")) {
+    if (exts.some((x) => x !== ".py")) return emit({ unsupported: "mixed", reason: "mixed-languages" }), 0;
+    const py = path.join(path.dirname(fileURLToPath(import.meta.url)), "symbol-index.py");
+    const r = spawnSync("python3", [py, ...argv], { stdio: "inherit" });
+    if (r.error) return emit({ unsupported: "python", reason: "no-python3" }), 0;
+    return r.status ?? 2;
+  }
+  const bad = exts.find((x) => ![...TS_EXT, ...JS_EXT].includes(x));
+  if (bad !== undefined) return emit({ unsupported: langOf(bad), reason: "unknown-language" }), 0;
+  const entries = collect(argv);
+  if (!entries.length) return emit({ unsupported: "unknown", reason: "no-js-ts-files" }), 0;
+  const lang = entries.some((e) => TS_EXT.includes(e.ext)) ? "ts" : "js";
+  const ts = loadTs(argv);
+  if (!ts) return emit({ unsupported: lang, reason: "no-parser" }), 0;
+  const multi = !(argv.length === 1 && files.length === 1);
+  let out;
+  try { out = index(ts, entries, multi); } catch (err) {
+    if (err && err.reason) return emit({ unsupported: err.lang, reason: err.reason }), 0;
+    throw err;
+  }
+  emit(out);
+  return 0;
+}
+
+process.exitCode = main(process.argv.slice(2));

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:]))