codeboarding 0.15.0__tar.gz → 0.15.1__tar.gz

{codeboarding-0.15.0 → codeboarding-0.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.15.0
+Version: 0.15.1
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT

{codeboarding-0.15.0 → codeboarding-0.15.1}/codeboarding.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.15.0
+Version: 0.15.1
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT

{codeboarding-0.15.0 → codeboarding-0.15.1}/codeboarding.egg-info/SOURCES.txt

@@ -140,6 +140,7 @@ static_analyzer/node.py
 static_analyzer/programming_language.py
 static_analyzer/scanner.py
 static_analyzer/typescript_config_scanner.py
+static_analyzer/typescript_workspace.py
 static_analyzer/workspace_dependencies.py
 static_analyzer/cfg/__init__.py
 static_analyzer/cfg/call_graph.py
@@ -184,6 +185,8 @@ static_analyzer/engine/adapters/rust_adapter.py
 static_analyzer/engine/adapters/typescript_adapter.py
 static_analyzer/lsp_client/__init__.py
 static_analyzer/lsp_client/diagnostics.py
+static_analyzer/typescript_plugin/node_modules/codeboarding-workspace-sources/index.js
+static_analyzer/typescript_plugin/node_modules/codeboarding-workspace-sources/package.json
 tests/test_persisted_analysis_artifacts.py
 tests/test_pyproject_packages.py
 tests/test_view_instructions.py

{codeboarding-0.15.0 → codeboarding-0.15.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codeboarding"
-version = "0.15.0"
+version = "0.15.1"
 description = "Interactive Diagrams for Code"
 readme = "PYPI.md"
 license = "MIT"
@@ -106,6 +106,10 @@ packages = [
 ]
 include-package-data = true
 
+[tool.setuptools.package-data]
+# tsserver loads a plugin only from <location>/node_modules/<name>.
+static_analyzer = ["typescript_plugin/node_modules/codeboarding-workspace-sources/*"]
+
 [project.scripts]
 codeboarding = "codeboarding_cli.main:main"
 codeboarding-setup = "infra.install:main"

{codeboarding-0.15.0 → codeboarding-0.15.1}/static_analyzer/__init__.py

@@ -363,6 +363,10 @@ class StaticAnalyzer:
                 continue
             try:
                 started.append((engine_config, self._spawn_engine_client(engine_config)))
+            except StaticAnalysisFatalError:
+                for _, client in started:  # never handed to ``stop_clients``
+                    client.shutdown()
+                raise
             except Exception as exc:
                 logger.exception(
                     f"Failed to start engine LSP client for {adapter.language}; "
@@ -500,6 +504,7 @@ class StaticAnalyzer:
             extra_client_capabilities=getattr(adapter, "extra_client_capabilities", {}) or {},
             error_verdict=adapter.error_verdict,
             workspace_folders=workspace_folders,
+            commands=adapter.get_lsp_commands(project_path),
         )
         try:
             engine_client.start()
@@ -918,6 +923,12 @@ class StaticAnalyzer:
             adapter, project_path = engine_config.adapter, engine_config.project_path
             language = adapter.results_language
             changed_files = self._changed_files_for_language(project_path, cached_sha, adapter.language)
+            if changed_files is not None and adapter.rebuilds_for(changed_files, project_path):
+                logger.info(f"warmstart {adapter.language}: a change alters how imports resolve; rebuilding")
+                changed_files = None
+                if resident_client is not None:
+                    # Why: a server resolves imports as the project was when it started; a stopped one is replaced.
+                    resident_client.shutdown()
             # A full re-analysis is the full pass's, so a split config runs as its parts. Changed files stay on the
             # config's own server: tsserver loads only the projects of the files it opens.
             if changed_files is None:

{codeboarding-0.15.0 → codeboarding-0.15.1}/static_analyzer/analysis_cache.py

@@ -74,8 +74,9 @@ _LEGACY_CACHE_SUBDIR = "cache"
 # v11: every language builds its call edges from definitions at the call site.
 # v12: a large TypeScript monorepo runs one server per tsconfig project, so a graph one out-of-memory
 # server left without edges is rebuilt; bases, implementations and edge-only declarations link across engines.
+# v13: a TypeScript call into a sibling workspace package resolves to its sources without an install or build.
 # Older pickles are treated as cache misses and re-run.
-_TAG_VERSION = "v12"
+_TAG_VERSION = "v13"
 
 
 class StaticAnalysisCache:

{codeboarding-0.15.0 → codeboarding-0.15.1}/static_analyzer/engine/adapters/typescript_adapter.py

@@ -2,11 +2,18 @@
 
 from __future__ import annotations
 
+import logging
+import re
+from collections.abc import Collection
 from pathlib import Path
 
 from infra.repo_utils.ignore import RepoIgnoreManager
 from static_analyzer.config import Language
 from static_analyzer.engine.language_adapter import LanguageAdapter
+from static_analyzer.exceptions import WorkspaceSetupError
+from static_analyzer.typescript_workspace import PLUGIN_LOCATION, PLUGIN_NAME, workspace_members
+
+logger = logging.getLogger(__name__)
 
 
 class TypeScriptAdapter(LanguageAdapter):
@@ -34,7 +41,30 @@ class TypeScriptAdapter(LanguageAdapter):
     def get_lsp_init_options(self, ignore_manager: RepoIgnoreManager | None = None) -> dict:
         # Why: by default a syntax-only server answers while the project still loads, and a definition
         # that needs an inferred type -- ``.then(t => t.serialize())`` -- comes back empty on a cold start.
-        return {"tsserver": {"useSyntaxServer": "never"}}
+        # Why the plugin: a call into a sibling workspace package of an uninstalled, unbuilt checkout resolves nowhere;
+        # the plugin resolves it to the member's sources (see ``typescript_workspace``).
+        return {
+            "tsserver": {"useSyntaxServer": "never"},
+            "plugins": [{"name": PLUGIN_NAME, "location": str(PLUGIN_LOCATION)}],
+        }
+
+    def get_lsp_commands(self, project_root: Path) -> list[dict]:
+        """Hands the workspace members to the plugin; tsserver gives the configuration to each project it loads."""
+        members = workspace_members(project_root)
+        if not members:
+            return []
+        if not (PLUGIN_LOCATION / "node_modules" / PLUGIN_NAME / "index.js").is_file():
+            raise WorkspaceSetupError(f"{PLUGIN_NAME} is missing from this install; reinstall CodeBoarding")
+        logger.info(f"tsserver resolves {len(members)} workspace members of {project_root} to their sources")
+        configuration = {"root": str(project_root), "members": {name: str(path) for name, path in members.items()}}
+        return [{"command": "_typescript.configurePlugin", "arguments": [PLUGIN_NAME, configuration]}]
+
+    def rebuilds_for(self, changed_files: Collection[Path], project_root: Path) -> bool:
+        """Whether a change alters how imports resolve: a tsconfig, a workspace declaration, or a workspace's manifest."""
+        names = {path.name for path in changed_files}
+        if "pnpm-workspace.yaml" in names or any(re.fullmatch(r"[tj]sconfig.*\.json", name) for name in names):
+            return True
+        return "package.json" in names and bool(workspace_members(project_root))
 
     def get_lsp_heap_options(self, heap_bytes: int) -> dict:
         # Why: at Node's default heap tsserver runs out of memory on a large tsconfig project and answers nothing.

{codeboarding-0.15.0 → codeboarding-0.15.1}/static_analyzer/engine/language_adapter.py

@@ -271,6 +271,14 @@ class LanguageAdapter(ABC):
         """
         return {}
 
+    def get_lsp_commands(self, project_root: Path) -> list[dict]:
+        """``workspace/executeCommand`` params the server is sent once initialized, and again on a restart."""
+        return []
+
+    def rebuilds_for(self, changed_files: Collection[Path], project_root: Path) -> bool:
+        """Whether a warm start over *changed_files* must re-analyse the whole project on a fresh server."""
+        return False
+
     def workspace_folders(self, project_root: Path, source_files: Sequence[Path]) -> list[Path]:
         """Workspace folders to announce to the server in place of the project, or none."""
         return []

{codeboarding-0.15.0 → codeboarding-0.15.1}/static_analyzer/engine/lsp_client.py

@@ -21,7 +21,7 @@ from pathlib import Path
 from static_analyzer.config import LANGUAGE_ID_BY_SUFFIX
 from static_analyzer.engine.lsp_constants import REQUEST_BATCH_SIZE
 from static_analyzer.engine.utils import uri_to_path
-from static_analyzer.exceptions import LanguageServerStalledError, StaticAnalysisFatalError
+from static_analyzer.exceptions import LanguageServerStalledError, StaticAnalysisFatalError, WorkspaceSetupError
 from static_analyzer.lsp_client.diagnostics import FileDiagnosticsMap, LSPDiagnostic
 
 logger = logging.getLogger(__name__)
@@ -113,6 +113,7 @@ class LSPClient:
         extra_client_capabilities: dict | None = None,
         error_verdict: Callable[[dict], ErrorVerdict] | None = None,
         workspace_folders: list[Path] | None = None,
+        commands: list[dict] | None = None,
     ) -> None:
         self._command = command
         self._project_root = project_root
@@ -129,6 +130,7 @@ class LSPClient:
         self._error_verdict = error_verdict
         # Announced in place of the project folder, for a server handed a workspace described apart from it.
         self._workspace_folders = workspace_folders or []
+        self._commands = commands or []
         self._process: subprocess.Popen | None = None  # type: ignore[type-arg]
         self._stdout_fd: int | None = None
         self._request_id = 0
@@ -257,6 +259,8 @@ class LSPClient:
         if isinstance(init_result, dict):
             self._server_capabilities = init_result.get("capabilities") or {}
         self._send_notification("initialized", {})
+        for command in self._commands:
+            self._send_request("workspace/executeCommand", command, timeout=self._default_timeout, required=True)
 
         # LSP servers receive configuration through three mechanisms:
         #   1. initializationOptions  — sent in the initialize request above.
@@ -706,8 +710,10 @@ class LSPClient:
             answers.append(BatchAnswer(parsed, req_id not in unserved, req_id in retryable))
         return answers
 
-    def _send_request(self, method: str, params: dict | list | None, timeout: int) -> dict | list | None:
-        """Send a JSON-RPC request and wait for the response."""
+    def _send_request(
+        self, method: str, params: dict | list | None, timeout: int, required: bool = False
+    ) -> dict | list | None:
+        """Send a JSON-RPC request and wait for the response; a *required* one that does not succeed is fatal."""
         if self.server_failure:
             self.check_alive()
         self._request_id += 1
@@ -731,6 +737,8 @@ class LSPClient:
 
             if "error" in msg:
                 error = msg["error"]
+                if required:
+                    raise WorkspaceSetupError(f"The language server rejected {method} {params}: {error}")
                 if isinstance(error, dict) and error.get("code") == LSP_METHOD_NOT_FOUND:
                     raise MethodNotFoundError(error.get("message", "Method not found"))
                 logger.warning("LSP error for request %d (%s): %s", req_id, method, error)
@@ -742,6 +750,8 @@ class LSPClient:
                 return None
             return msg.get("result")
 
+        if required:
+            raise WorkspaceSetupError(f"The language server did not answer {method} {params} within {timeout}s")
         raise TimeoutError(f"Timeout waiting for LSP response to request {req_id}")
 
     def _send_notification(self, method: str, params: dict | list | None) -> None:

{codeboarding-0.15.0 → codeboarding-0.15.1}/static_analyzer/exceptions.py

@@ -5,5 +5,9 @@ class StaticAnalysisFatalError(RuntimeError):
     """Raised when continuing would produce misleading cached analysis."""
 
 
+class WorkspaceSetupError(StaticAnalysisFatalError):
+    """Raised when the workspace a language server must be set up with cannot be, so its answers would miss edges."""
+
+
 class LanguageServerStalledError(StaticAnalysisFatalError):
     """Raised when a language server stays up but the backend that answers for it has died."""

codeboarding-0.15.1/static_analyzer/typescript_plugin/node_modules/codeboarding-workspace-sources/index.js

@@ -0,0 +1,132 @@
+// tsserver plugin: a call into a sibling workspace package resolves to its sources in a checkout neither installed nor
+// built. Core hands it {root, members} through `_typescript.configurePlugin` (static_analyzer/typescript_workspace.py).
+//  1. Links: a lookup under <dir>/node_modules/<member> answers from the member's folder, as an install links it.
+//  2. References: a project references the configs of each member it imports, so TypeScript's own
+//     source-of-project-reference redirect maps the member's missing build output (outDir) back to its sources.
+//  3. An entry no config emits (a bundler builds it) is read as its source under src/, as Knip maps it.
+"use strict";
+const fs = require("fs");
+const path = require("path");
+
+const HOOKED = Symbol("codeboarding-workspace-sources");
+// <before>/node_modules/<package name><rest>, the last node_modules segment.
+const NODE_MODULES_PATH = /^(.*)\/node_modules\/((?:@[^/]+\/)?[^/@][^/]*)(\/.*)?$/;
+// The package a module specifier names: `from "x"`, `import "x"`, `import("x")`, `require("x")`.
+const SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|\bimport\s+)["'`]((?:@[^/"'`]+\/)?[^./"'`@][^/"'`]*)/g;
+const ENTRY_FIELDS = ["main", "module", "types", "typings", "exports"];
+const SOURCE_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+
+// Forward slashes and a lower-case drive letter, as tsserver spells a path.
+const norm = (file) => file.replace(/\\/g, "/").replace(/^[A-Z]:/, (drive) => drive.toLowerCase());
+
+function linkMembers(host, root, members) {
+  const linked = (file) => {
+    const match = typeof file === "string" && norm(file).startsWith(`${root}/`) && NODE_MODULES_PATH.exec(norm(file));
+    const folder = match && members.get(match[2]);
+    return folder ? folder + (match[3] || "") : null;
+  };
+  // Why: module resolution skips a node_modules folder that is not on disk; an install hoists the links to the root.
+  const scopes = [...members.keys()].filter((name) => name.startsWith("@")).map((name) => name.split("/")[0]);
+  const linkParents = new Set([`${root}/node_modules`, ...scopes.map((scope) => `${root}/node_modules/${scope}`)]);
+  const manifests = new Map([...members.values()].map((folder) => [`${folder}/package.json`, folder]));
+  for (const name of ["fileExists", "realpath"]) {
+    const original = host[name];
+    if (typeof original === "function") host[name] = (file, ...rest) => original.call(host, linked(file) || file, ...rest);
+  }
+  const { readFile, directoryExists } = host;
+  host.readFile = (file, ...rest) => {
+    const target = linked(file) || file;
+    const text = readFile.call(host, target, ...rest);
+    const folder = text !== undefined && typeof target === "string" && manifests.get(norm(target));
+    return folder ? withSources(text, folder) : text;
+  };
+  host.directoryExists = (dir) => {
+    const target = linked(dir);
+    if (target) return directoryExists.call(host, target);
+    return directoryExists.call(host, dir) || (typeof dir === "string" && linkParents.has(norm(dir)));
+  };
+}
+
+// *text*, a member's package.json, with each entry missing from disk read as its source under src/ when there is one.
+function withSources(text, folder) {
+  let manifest;
+  try {
+    manifest = JSON.parse(text);
+  } catch (error) {
+    return text;
+  }
+  const source = (entry) => {
+    if (fs.existsSync(path.resolve(folder, entry))) return entry;
+    const stem = entry.replace(/^(\.\/)?[^/]+\//, "src/").replace(/(\.d)?\.[cm]?[jt]sx?$/, "");
+    const found = SOURCE_EXTENSIONS.map((extension) => stem + extension).find((file) => fs.existsSync(path.resolve(folder, file)));
+    return found ? `./${found}` : entry;
+  };
+  const replace = (value) => {
+    if (typeof value === "string") return source(value);
+    if (Array.isArray(value)) return value.map(replace);
+    if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, replace(nested)]));
+    return value;
+  };
+  for (const field of ENTRY_FIELDS) if (field in manifest) manifest[field] = replace(manifest[field]);
+  return JSON.stringify(manifest);
+}
+
+function referenceMembers(project, host, members, configured) {
+  const own = configured ? norm(project.getProjectName()) : null;
+  const original = host.getProjectReferences;
+  const scanned = new Set();
+  const used = new Set();
+  let added = [];
+  // Why scanned as files join, not at create: tsserver enables plugins before it adds a project's root files.
+  host.getProjectReferences = () => {
+    const declared = (typeof original === "function" && original.call(host)) || [];
+    const files = project.getRootFiles().filter((file) => !scanned.has(file));
+    if (files.length) {
+      for (const file of files) {
+        scanned.add(file);
+        try {
+          for (const match of fs.readFileSync(file, "utf8").matchAll(SPECIFIER)) used.add(match[1]);
+        } catch (error) {
+          continue;
+        }
+      }
+      // Every tsconfig and jsconfig of each member. Why every one: the redirect then finds whichever emits an entry.
+      const have = new Set(declared.map((reference) => norm(path.resolve(reference.path))));
+      const folders = [...used].map((name) => members.get(name)).filter((folder) => folder && !have.has(folder));
+      added = folders
+        .flatMap((folder) => fs.readdirSync(folder).filter((file) => /^[tj]sconfig.*\.json$/.test(file)).sort().map((file) => `${folder}/${file}`))
+        .filter((config) => config !== own && !have.has(config))
+        .map((config) => ({ path: config }));
+    }
+    return declared.length || added.length ? [...declared, ...added] : undefined;
+  };
+  if (!configured && typeof host.getCompilerHost !== "function") {
+    // An inferred project has no references of its own, so tsserver gives it neither the redirect nor the compiler
+    // host the redirect answers module resolution through. Both as a configured project has them.
+    let compilerHost;
+    host.setCompilerHost = (created) => {
+      compilerHost = created;
+    };
+    host.getCompilerHost = () => compilerHost;
+    host.useSourceOfProjectReferenceRedirect = () => added.length > 0;
+  }
+}
+
+module.exports = function init({ typescript: ts }) {
+  return {
+    create(info) {
+      const host = info.languageServiceHost;
+      const { root, members } = info.config || {};
+      if (!root || !members || host[HOOKED]) return info.languageService;
+      host[HOOKED] = true;
+      const folders = new Map(Object.entries(members).map(([name, folder]) => [name, norm(folder)]));
+      linkMembers(host, norm(root), folders);
+      const kind = info.project.projectKind;
+      if (kind === ts.server.ProjectKind.Configured || kind === ts.server.ProjectKind.Inferred) {
+        referenceMembers(info.project, host, folders, kind === ts.server.ProjectKind.Configured);
+      }
+      info.project.projectService.logger.info(`codeboarding-workspace-sources: ${folders.size} members under ${root}`);
+      return info.languageService;
+    },
+  };
+};

codeboarding-0.15.1/static_analyzer/typescript_plugin/node_modules/codeboarding-workspace-sources/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "codeboarding-workspace-sources",
+  "version": "1.0.0",
+  "private": true,
+  "main": "index.js"
+}

codeboarding-0.15.1/static_analyzer/typescript_workspace.py

@@ -0,0 +1,81 @@
+"""A JavaScript workspace's members, for the tsserver plugin (``typescript_plugin/``) that resolves calls into them.
+
+Why: in a checkout neither installed nor built, ``import { f } from "@acme/core"`` resolves nowhere: there is no
+``node_modules/@acme/core`` link, and the member's ``main``/``types``/``exports`` name a ``dist/`` that does not exist.
+"""
+
+import json
+import re
+from pathlib import Path
+
+import yaml
+
+from static_analyzer.exceptions import WorkspaceSetupError
+
+PLUGIN_NAME = "codeboarding-workspace-sources"
+PLUGIN_LOCATION = Path(__file__).resolve().parent / "typescript_plugin"
+"""tsserver loads a plugin from ``<location>/node_modules/<name>``."""
+
+
+def workspace_members(repo: Path) -> dict[str, Path]:
+    """Each declared member's package name and folder, the first by path winning; empty when *repo* declares none.
+
+    Why pnpm-workspace.yaml alone when present: pnpm reads no ``workspaces`` from package.json.
+    """
+    pnpm = repo / "pnpm-workspace.yaml"
+    try:
+        if pnpm.is_file():
+            patterns = (yaml.safe_load(pnpm.read_text(encoding="utf-8")) or {}).get("packages")
+        elif (repo / "package.json").is_file():
+            patterns = json.loads((repo / "package.json").read_text(encoding="utf-8")).get("workspaces")
+            patterns = patterns.get("packages") if isinstance(patterns, dict) else patterns
+        else:
+            return {}
+        patterns = patterns or []
+        if not isinstance(patterns, list) or not all(isinstance(pattern, str) for pattern in patterns):
+            raise ValueError(f"the member patterns are no list of strings: {patterns!r}")
+        expanded = [
+            (pattern.startswith("!"), alternative.removeprefix("./").strip("/"))
+            for pattern in patterns
+            for alternative in expand_braces(pattern.removeprefix("!"))
+        ]
+        excluded = [glob_regex(pattern) for negated, pattern in expanded if negated]
+        members: dict[str, Path] = {}
+        for negated, pattern in expanded:
+            if negated or pattern in ("", "."):
+                continue
+            for manifest in sorted(repo.glob(f"{pattern}/package.json")):
+                folder = manifest.parent.relative_to(repo)
+                if "node_modules" in folder.parts or any(
+                    regex.fullmatch(f"{folder.as_posix()}/") for regex in excluded
+                ):
+                    continue
+                name = json.loads(manifest.read_text(encoding="utf-8")).get("name")
+                if isinstance(name, str) and name:
+                    members.setdefault(name, manifest.parent)
+    except (OSError, ValueError, AttributeError, yaml.YAMLError) as error:
+        raise WorkspaceSetupError(f"Cannot read the workspace {repo} declares: {error}") from error
+    return members
+
+
+def expand_braces(pattern: str) -> list[str]:
+    """*pattern* with each ``{a,b}`` group spelled out, as the package managers' globs do."""
+    group = re.search(r"\{([^{}]*,[^{}]*)\}", pattern)
+    if group is None:
+        return [pattern]
+    head, tail = pattern[: group.start()], pattern[group.end() :]
+    return [expanded for alternative in group[1].split(",") for expanded in expand_braces(head + alternative + tail)]
+
+
+def glob_regex(pattern: str) -> re.Pattern[str]:
+    """A workspace glob over a folder's path from the root plus ``/``: ``*`` within a segment, ``**`` any depth."""
+    return re.compile(
+        "".join(
+            (
+                "(?:[^/]+/)*"
+                if segment == "**"
+                else re.escape(segment).replace(r"\*", "[^/]*").replace(r"\?", "[^/]") + "/"
+            )
+            for segment in pattern.split("/")
+        )
+    )