repo-blueprint 0.1.2 → 0.2.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "repo-blueprint",
-  "version": "0.1.2",
-  "description": "Generate a zoomable, dependency-layered architecture map of a code repository by static analysis.",
+  "version": "0.2.0",
+  "description": "A clearer way to see how a repository is built. Maps TypeScript, JavaScript and Python codebases into dependency layers you can zoom through.",
   "license": "MIT",
   "author": {
     "name": "Mo Ganji"

package/README.md

@@ -2,11 +2,12 @@
 
 A clearer way to see how a repository is built. repo-blueprint maps a codebase into layers, with each part placed above its dependencies. Detail is handled by zoom: the top level shows packages, and zooming in reveals folders, then files.
 
-![TanStack Query mapped with repo-blueprint](https://raw.githubusercontent.com/MohGanji/repo-blueprint/v0.1.2/media/demo.gif)
+![TanStack Query mapped with repo-blueprint](https://raw.githubusercontent.com/MohGanji/repo-blueprint/main/media/demo.gif)
 
 - Works with TypeScript, JavaScript and Python, monorepos included
-- Draws imports, RPC and HTTP calls, events, and external systems such as databases and queues
+- Draws imports, RPC and HTTP calls, events, and every third-party package the code imports, named by system (PostgreSQL, Stripe…) when it is a known driver or SDK
 - Flags import cycles, unused packages and orphan files
+- Reports every file it could not map, and every import it could not follow, so nothing drops off the map silently
 - Produces one self-contained HTML file
 - Uses static analysis only, so the output is deterministic
 
@@ -36,8 +37,8 @@ Serves the map on localhost and rebuilds it when files change.
 
 ## Supported projects
 
-- **TypeScript and JavaScript:** any folder with a `package.json` and a `tsconfig.json`, at any depth. Imports are resolved through the project's tsconfig paths.
-- **Python:** any folder with a `pyproject.toml`.
+- **TypeScript and JavaScript:** any folder with a `package.json`, at any depth. ES modules and CommonJS (`require`, `module.exports`) are both read. Imports are resolved through the package's `tsconfig.json` or `jsconfig.json` when it has one. Vue, Svelte and Astro files are not parsed yet and are reported as not mapped.
+- **Python:** any folder with a `pyproject.toml`, flat or `src/` layout.
 
 Each package is shown as an app, a service or a library. A declared type is used when there is one (Backstage `catalog-info.yaml`, Nx `project.json`). Otherwise the role is inferred: an entry file that mounts a UI makes an app, one that starts a server or worker makes a service, and anything else is a library.
 
@@ -53,21 +54,25 @@ You can also copy [`SKILL.md`](https://github.com/MohGanji/repo-blueprint/blob/m
 
 ## Configuration
 
-Put a `.blueprint.json` in the root of the repo being mapped to extend the [defaults](https://github.com/MohGanji/repo-blueprint/blob/main/src/blueprint.config.json). For example, to detect an extra external system:
+None is needed: every imported package is on the map without it. Put a `.blueprint.json` in the root of the repo being mapped to extend the [defaults](https://github.com/MohGanji/repo-blueprint/blob/main/src/blueprint.config.json). For example, to group your own SDKs under one system name:
 
 ```json
 {
-  "externalSystems": { "Stripe": ["stripe"] }
+  "externalSystems": { "Billing API": ["@acme/billing-client"] }
 }
 ```
 
 | Key | Description |
 | --- | --- |
-| `externalSystems` | System names and the packages that indicate them |
+| `externalSystems` | System names and the packages that indicate them. Labels only: a package not listed still appears under its own name |
 | `messaging` | Method and property names for RPC calls, publishes and subscriptions |
 | `folderRoles` | Folder names that imply a role, used by the role-mismatch finding |
 | `sdkDirs` | Folders whose subfolders are generated API clients, named after the services they call |
 
+## Examples
+
+[`examples/`](https://github.com/MohGanji/repo-blueprint/tree/main/examples) holds blueprints of open-source projects, each pinned to a commit in [`corpus.json`](https://github.com/MohGanji/repo-blueprint/blob/main/examples/corpus.json): Express, Koa, debug, Chalk, nanoid, Ky, Zustand and Zod from npm, and Requests, Click, HTTPX, Flask, Rich, Pydantic, FastAPI, Typer, SQLModel, Instructor, LiteLLM and Karpathy's nanochat from PyPI and GitHub. Download one and open it in a browser. `node examples/build-examples.mjs` rebuilds them.
+
 ## How it works
 
 The TypeScript compiler API and Python's `ast` module extract facts from the source. Those become a model of packages, folders, edges and findings, which is rendered as one diagram per folder.
@@ -75,13 +80,15 @@ The TypeScript compiler API and Python's `ast` module extract facts from the sou
 ```
 bin/repo-blueprint.mjs     CLI
 src/
-├── extract-ts.mjs         TypeScript extractor
+├── extract-ts.mjs         TypeScript and JavaScript extractor
 ├── extract-py.py          Python extractor
 ├── model.mjs              packages, edges, roles, findings
 ├── views.mjs              one diagram per folder
 ├── build.mjs              writes the HTML
 └── template.html          the page
 skills/repo-blueprint/     agent skill
+test/                      fixture repos and tests (npm test)
+examples/                  blueprints of open-source repos
 ```
 
 ## Contributing

package/bin/repo-blueprint.mjs

@@ -12,7 +12,7 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const SRC = path.join(ROOT, 'src');
 const HOME = path.join(os.homedir(), '.repo-blueprint');
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.venv', 'venv', '.nx', 'tmp', '.next', 'out', '.turbo']);
-const WATCHED = /\.(tsx?|py)$|(^|\/)(package\.json|tsconfig[\w.-]*\.json|pyproject\.toml|project\.json|catalog-info\.ya?ml|\.blueprint\.json|Dockerfile)$/;
+const WATCHED = /\.(tsx?|jsx?|mts|cts|mjs|cjs|py)$|(^|\/)(package\.json|[tj]sconfig[\w.-]*\.json|pyproject\.toml|project\.json|catalog-info\.ya?ml|\.blueprint\.json|Dockerfile)$/;
 const IGNORED = /(^|\/)(node_modules|\.git|dist|build|coverage|\.venv|venv|__pycache__|\.nx|tmp|\.next|out|\.turbo|playwright-report|test-results)(\/|$)/;
 
 const HELP = `repo-blueprint: map a code repository by static analysis.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "repo-blueprint",
-  "version": "0.1.2",
-  "description": "Generate a zoomable, dependency-layered map of a code repository by static analysis.",
+  "version": "0.2.0",
+  "description": "A clearer way to see how a repository is built. Maps TypeScript, JavaScript and Python codebases into dependency layers you can zoom through.",
   "author": "Mo Ganji <mo@ganji.me>",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,9 @@
   "bin": {
     "repo-blueprint": "bin/repo-blueprint.mjs"
   },
+  "scripts": {
+    "test": "node --test test/"
+  },
   "files": [
     "bin",
     "src",
@@ -37,6 +40,8 @@
     "static-analysis",
     "diagram",
     "typescript",
+    "javascript",
+    "python",
     "claude-code",
     "skill"
   ]

package/skills/repo-blueprint/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: repo-blueprint
-description: Generate a blueprint of a code repository, a zoomable, dependency-layered architecture map built by static analysis (TypeScript and Python). Use when the user asks for a blueprint, architecture map, dependency map, codebase diagram or overview of how a repo fits together, or wants to watch that map update live while they code.
+description: Generate a blueprint of a code repository, a zoomable, dependency-layered architecture map built by static analysis (TypeScript, JavaScript and Python). Use when the user asks for a blueprint, architecture map, dependency map, codebase diagram or overview of how a repo fits together, or wants to watch that map update live while they code.
 ---
 
 # repo-blueprint
 
-Builds a single standalone HTML page that maps a repository: packages, folders and files stacked in dependency tiers, with imports, RPC calls, HTTP calls, events and external systems drawn between them, plus deterministic findings (import cycles, misplaced packages, unused files). Everything comes from static analysis, so the same commit always gives the same page.
+Builds a single standalone HTML page that maps a repository: packages, folders and files stacked in dependency tiers, with imports, RPC calls, HTTP calls, events and every third-party dependency drawn between them, plus deterministic findings (import cycles, misplaced packages, unused files, and any file or import the analysis could not map). Everything comes from static analysis, so the same commit always gives the same page.
 
 ## Commands
 
@@ -14,13 +14,13 @@ The skill runs the `repo-blueprint` npm package, pinned to the version it was wr
 One-time build, writes the HTML and prints its path plus a summary:
 
 ```bash
-npx -y repo-blueprint@0.1.2 build <repo> --open
+npx -y repo-blueprint@0.2.0 build <repo> --open
 ```
 
 Live mode, serves the page and rebuilds it when source files change (run it in the background; it keeps running until stopped):
 
 ```bash
-npx -y repo-blueprint@0.1.2 watch <repo> --open
+npx -y repo-blueprint@0.2.0 watch <repo> --open
 ```
 
 Keep the pinned version as written, even if a newer one exists: the same commit and the same version always produce the same page, so users can compare blueprints over time.
@@ -34,22 +34,22 @@ Keep the pinned version as written, even if a newer one exists: the same commit
 
 1. Use the repo the user names, otherwise the current working directory.
 2. If they want to keep it open while they work, use `watch` in the background and give them the URL it prints. Otherwise use `build --open`.
-3. Relay the two summary lines the build prints (packages by role, findings by category) and the output path or URL. Don't describe the page at length; the user can press **?** inside it for help.
+3. Relay the summary lines the build prints (packages by role, coverage, findings by category) and the output path or URL. If the coverage line says files were skipped, say how many; the page lists them with the reason. Don't describe the page at length; the user can press **?** inside it for help.
 4. If `node` is missing, tell the user the skill needs Node.js 18.17 or newer. If the build fails, show the error. Python packages are skipped with a notice when neither Python 3.10+ nor `uv` is available; say so if it happens.
 
 ## Supported repos
 
-- **TypeScript and JavaScript:** any folder with a `package.json` and a `tsconfig.json`, at any depth. Imports are resolved with the project's own tsconfig paths.
-- **Python:** any folder with a `pyproject.toml`.
+- **TypeScript and JavaScript:** any folder with a `package.json`, at any depth, ES modules or CommonJS. Imports are resolved with the package's `tsconfig.json` or `jsconfig.json` when it has one. Vue, Svelte and Astro files are reported as not mapped.
+- **Python:** any folder with a `pyproject.toml`, flat or `src/` layout.
 - **Roles:** a declared type wins (Backstage `catalog-info.yaml` `spec.type`, Nx `project.json` `projectType`). Otherwise roles come from the code: an entry file that mounts a UI makes an app, one that starts a server or worker (or a Dockerfile or start script) makes a service, and anything else is a library.
 
 ## Per-repo settings
 
 The package ships defaults. A repo can extend or override them with a `.blueprint.json` at its root, using the same keys:
 
-- `externalSystems`: maps a system name to the npm or Python packages that indicate it, for example `{ "Stripe": ["stripe"] }`.
+- `externalSystems`: maps a system name to the npm or Python packages that indicate it, for example `{ "Billing API": ["@acme/billing-client"] }`. It only renames: every imported package is on the map without it.
 - `messaging`: method and property names for RPC calls, publishes and subscriptions, for repos whose message-bus wrapper uses different names.
 - `folderRoles`: folder names that imply a role, used only for the role-mismatch finding.
 - `sdkDirs`: folder names whose subfolders are generated API clients named after the services they call.
 
-Only suggest a `.blueprint.json` when something the user cares about is missing from the map, such as an external system or message links.
+Only suggest a `.blueprint.json` when the user wants packages grouped under a system name, or message links are missing from the map.

package/src/blueprint.config.json

@@ -25,10 +25,20 @@
     "server.ts",
     "worker.ts",
     "app.module.ts",
+    "main.js",
+    "index.js",
+    "server.js",
+    "worker.js",
     "main.py",
     "__main__.py",
     "__init__.py",
-    "*.config.ts"
+    "*.config.ts",
+    "*.config.js",
+    "*.config.mjs",
+    "*.config.cjs",
+    ".*rc.js",
+    ".*rc.cjs",
+    ".*rc.mjs"
   ],
   "frameworkLoaded": [
     "*.entity.ts",
@@ -70,15 +80,23 @@
   },
   "externalSystems": {
     "PostgreSQL": [
-      "typeorm",
-      "@nestjs/typeorm",
       "pg",
-      "sqlalchemy",
-      "knex",
       "postgres",
-      "@prisma/client",
-      "drizzle-orm",
-      "pg-boss"
+      "pg-boss",
+      "psycopg",
+      "psycopg2",
+      "asyncpg"
+    ],
+    "Stripe": [
+      "stripe",
+      "@stripe/stripe-js",
+      "@stripe/react-stripe-js"
+    ],
+    "SQLite": [
+      "better-sqlite3",
+      "sqlite3",
+      "sqlite",
+      "aiosqlite"
     ],
     "MySQL": [
       "mysql",

package/src/build.mjs

@@ -13,8 +13,10 @@ const OUT = path.resolve(process.argv[3]);
 const FACTS = path.resolve(process.argv[4]);
 const name = path.basename(REPO);
 
-const read = (f) => (fs.existsSync(f) ? JSON.parse(fs.readFileSync(f, 'utf8')).workspaces : []);
-const model = buildModel(name, [...read(path.join(FACTS, `${name}-ts.json`)), ...read(path.join(FACTS, `${name}-py.json`))], loadConfig(REPO));
+const read = (f) => (fs.existsSync(f) ? JSON.parse(fs.readFileSync(f, 'utf8')) : { workspaces: [] });
+const tsFacts = read(path.join(FACTS, `${name}-ts.json`));
+const pyFacts = read(path.join(FACTS, `${name}-py.json`));
+const model = buildModel(name, [...tsFacts.workspaces, ...pyFacts.workspaces], loadConfig(REPO), [tsFacts.coverage, pyFacts.coverage]);
 const t0 = Date.now();
 const views = buildViews(model);
 
@@ -69,4 +71,5 @@ const byType = {};
 for (const f of model.findings) byType[f.type] = (byType[f.type] || 0) + 1;
 const nFiles = Object.keys(model.files).length;
 console.log(`${name}${commit ? ` (${branch}@${commit})` : ''}: ${Object.keys(model.packages).length} packages (${Object.entries(roles).map(([r, n]) => `${n} ${r}`).join(', ')}), ${nFiles} files, ${Object.keys(views).length} views`);
+if (model.coverage) console.log(`coverage: ${model.coverage.analyzed} of ${model.coverage.total} source files mapped${model.coverage.skipped ? `, ${model.coverage.skipped} skipped (see findings)` : ''}`);
 console.log(`findings: ${model.findings.length ? Object.entries(byType).map(([t, n]) => `${t} ${n}`).join(', ') : 'none'}`);

package/src/extract-py.py

@@ -7,7 +7,7 @@ import sys
 REPO = os.path.abspath(sys.argv[1])
 OUT = sys.argv[2]
 SUBJECT_RE = re.compile(r"^[A-Za-z][\w-]*(\.[\w#*-]+)+$")
-TEST_RE = re.compile(r"(^|/)(tests?|migrations|scripts|examples)/|(^|/)(test_|conftest)")
+TEST_RE = re.compile(r"(^|/)tests?/|(^|/)(test_|conftest)|_test\.py$")
 
 
 def ext_name(mod):
@@ -62,19 +62,35 @@ def enums_of(tree):
     return out
 
 
+def py_files(d, nested=()):
+    out = []
+    for root, dirs, fs in os.walk(d):
+        dirs[:] = sorted(x for x in dirs if not x.startswith(".") and x not in SKIP and os.path.join(root, x) not in nested)
+        out += [os.path.join(root, f) for f in sorted(fs) if f.endswith(".py")]
+    return out
+
+
+def parse(p, skipped, wid):
+    try:
+        return ast.parse(open(p, encoding="utf-8").read(), filename=p)
+    except (SyntaxError, UnicodeDecodeError, ValueError) as e:
+        why = f"invalid syntax on line {e.lineno}" if isinstance(e, SyntaxError) else "not valid UTF-8 text" if isinstance(e, UnicodeDecodeError) else str(e)
+        skipped.append({"pkg": wid, "file": rel(p), "reason": f"could not be parsed: {why}"})
+        return None
+
+
 def main():
     result = []
+    skipped = []
     packages = discover()
+    # Every .py file (tests excluded) is either analysed or listed in skipped with the reason.
+    for p in py_files(REPO):
+        if not TEST_RE.search(rel(p)) and not any(p.startswith(d + os.sep) for _, d in packages):
+            skipped.append({"pkg": None, "file": rel(p), "reason": "outside any package: no pyproject.toml above it"})
     for wid, wdir in packages:
         nested = [d for _, d in packages if d != wdir and d.startswith(wdir + os.sep)]
-        paths = []
-        for root, dirs, fs in os.walk(wdir):
-            dirs[:] = sorted(d for d in dirs if not d.startswith(".") and d not in SKIP and os.path.join(root, d) not in nested)
-            for f in sorted(fs):
-                p = os.path.join(root, f)
-                if f.endswith(".py") and not TEST_RE.search(rel(p)[len(rel(wdir)) + 1 :]):
-                    paths.append(p)
-        trees = {p: ast.parse(open(p, encoding="utf-8").read(), filename=p) for p in paths}
+        paths = [p for p in py_files(wdir, nested) if not TEST_RE.search(os.path.relpath(p, wdir).replace(os.sep, "/"))]
+        trees = {p: t for p in paths if (t := parse(p, skipped, wid)) is not None}
         enums = {}
         for t in trees.values():
             enums.update(enums_of(t))
@@ -92,12 +108,14 @@ def main():
                 for _ in range(level - 1):
                     base = os.path.dirname(base)
                 parts = mod.split(".") if mod else []
-                cand = os.path.join(base, *parts)
+                cands = [os.path.join(base, *parts)]
             else:
-                cand = os.path.join(wdir, *mod.split("."))
-            for c in (cand + ".py", os.path.join(cand, "__init__.py")):
-                if c in trees:
-                    return rel(c)
+                # Absolute imports resolve from the package root, or from src/ in a src layout.
+                cands = [os.path.join(wdir, *mod.split(".")), os.path.join(wdir, "src", *mod.split("."))]
+            for cand in cands:
+                for c in (cand + ".py", os.path.join(cand, "__init__.py")):
+                    if c in trees:
+                        return rel(c)
             return None
 
         files = {}
@@ -159,7 +177,8 @@ def main():
             continue
         result.append({"id": wid, "dir": rel(wdir) if wdir != REPO else ".", "parent": os.path.basename(os.path.dirname(wdir)) if wdir != REPO else "", "aliases": [], "files": files, "mq": mq, "lang": "python", "meta": meta})
         sys.stdout.write(f"{wid}: {len(files)} files, {len(mq)} mq facts\n")
-    json.dump({"workspaces": result}, open(OUT, "w"))
+    analyzed = sum(len(w["files"]) for w in result)
+    json.dump({"workspaces": result, "coverage": {"total": analyzed + len(skipped), "analyzed": analyzed, "skipped": skipped}}, open(OUT, "w"))
 
 
 main()

package/src/extract-ts.mjs

@@ -10,7 +10,7 @@ const OUT = path.resolve(process.argv[3] || 'facts-ts.json');
 
 import { builtinModules } from 'node:module';
 const BUILTINS = new Set([...builtinModules, 'bun', 'bun:test']);
-const TEST_RE = /(\.spec\.|\.test\.|\.d\.ts$|\/__fixtures__\/|\/__test-fixtures__\/|\/__mocks__\/|\/test\/|\/tests\/|\/simulations\/|vitest\.|playwright\.)/;
+const TEST_RE = /(\.spec\.|\.test\.|\.d\.ts$|(^|\/)(__tests__|__fixtures__|__test-fixtures__|__mocks__|test|tests|test-d|simulations)\/|vitest\.|playwright\.)/;
 const ROUTE_DECORATORS = { Get: 'GET', Post: 'POST', Put: 'PUT', Patch: 'PATCH', Delete: 'DELETE', All: 'ALL' };
 const BOOT_RE = /^(NestFactory\.(create|createMicroservice|createApplicationContext)|Bun\.serve|serve|http\.createServer|https\.createServer|createServer|Worker\.create|[\w.]*\.listen)$/;
 const MOUNT_RE = /^(createRoot|hydrateRoot|ReactDOM\.render|ReactDOM\.createRoot|ReactDOM\.hydrate|createApp|bootstrapApplication|platformBrowserDynamic)$/;
@@ -23,11 +23,55 @@ const clip = (s, n = 70) => {
 };
 
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.venv', 'venv', '.nx', 'tmp', '.next', 'out', '.turbo', 'playwright-report', 'test-results']);
+const SOURCE_RE = /\.(tsx?|jsx?|mts|cts|mjs|cjs)$/;
+const isSource = (f) => SOURCE_RE.test(f) && !/\.d\.[mc]?ts$/.test(f);
+// Single-file components hold imports too, but are not parsed yet: they are counted and reported as skipped.
+const COMPONENT_RE = /\.(vue|svelte|astro)$/;
+const inSkippedDir = (relPath) => relPath.split('/').slice(0, -1).some((seg) => SKIP_DIRS.has(seg) || seg.startsWith('.'));
+
+// Used when a package has neither a tsconfig.json nor a jsconfig.json.
+const DEFAULT_OPTIONS = {
+  allowJs: true,
+  jsx: ts.JsxEmit.Preserve,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  target: ts.ScriptTarget.ES2022,
+  resolveJsonModule: true,
+};
+
+// Source files under dir. With nested: true, it descends into nested packages and also lists component files.
+function walkSources(dir, nested = false) {
+  const out = [];
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const abs = path.join(d, e.name);
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.') && (nested || !fs.existsSync(path.join(abs, 'package.json')))) walk(abs);
+      } else if (isSource(e.name) || (nested && COMPONENT_RE.test(e.name))) out.push(abs);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+// Compiler options and file list for a package: its tsconfig.json, else its jsconfig.json, else defaults over every source file.
+// JavaScript is always analysed, whatever the config says about allowJs.
+function compilerSetup(dir) {
+  for (const name of ['tsconfig.json', 'jsconfig.json']) {
+    const cfgPath = path.join(dir, name);
+    if (!fs.existsSync(cfgPath)) continue;
+    const raw = ts.readConfigFile(cfgPath, ts.sys.readFile).config || {};
+    raw.compilerOptions = { ...raw.compilerOptions, allowJs: true };
+    const parsed = ts.parseJsonConfigFileContent(raw, ts.sys, dir, { noEmit: true }, cfgPath);
+    return { options: parsed.options, fileNames: parsed.fileNames, config: name };
+  }
+  return { options: DEFAULT_OPTIONS, fileNames: walkSources(dir), config: null };
+}
 
 function discoverWorkspaces() {
   const out = [];
   const walk = (dir, depth) => {
-    if (fs.existsSync(path.join(dir, 'tsconfig.json')) && fs.existsSync(path.join(dir, 'package.json'))) out.push(dir);
+    if (fs.existsSync(path.join(dir, 'package.json'))) out.push(dir);
     if (depth >= 4) return;
     for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
       if (e.isDirectory() && !SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) walk(path.join(dir, e.name), depth + 1);
@@ -75,6 +119,16 @@ function declFileOf(checker, expr) {
   return d ? rel(d.getSourceFile().fileName) : null;
 }
 
+const isStringish = (n) => ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n);
+
+// Names a require() call takes: `const { a } = require(x)` → a, `require(x).a` → a, anything else → the whole module.
+function requiredNames(call) {
+  const p = call.parent;
+  if (p && ts.isVariableDeclaration(p) && ts.isObjectBindingPattern(p.name)) return p.name.elements.map((e) => (e.propertyName || e.name).getText());
+  if (p && ts.isPropertyAccessExpression(p) && p.expression === call) return [p.name.text];
+  return ['*'];
+}
+
 function isParamOf(id, checker) {
   const sym = checker.getSymbolAtLocation(id);
   return !!(sym && sym.declarations && sym.declarations.some((d) => ts.isParameter(d)));
@@ -113,12 +167,51 @@ function paramsSig(fn) {
 
 function classifyFn(name, file) {
   if (/^use[A-Z]/.test(name)) return 'hook';
-  if (/^[A-Z]/.test(name) && file.endsWith('.tsx')) return 'component';
+  if (/^[A-Z]/.test(name) && /\.[jt]sx$/.test(file)) return 'component';
   return 'function';
 }
 
-function extractDecls(sf, file) {
+// Target name of a CommonJS export assignment: `module.exports` → '', `exports.a` / `module.exports.a` → 'a', anything else → null.
+function cjsTarget(left) {
+  const t = left.getText();
+  if (t === 'module.exports') return '';
+  const m = /^(?:module\.)?exports\.([A-Za-z_$][\w$]*)$/.exec(t);
+  return m ? m[1] : null;
+}
+
+// CommonJS exports: `module.exports = { a, b: fn }`, `module.exports = fn`, `exports.a = …`.
+function cjsDecls(sf, file) {
+  const local = new Map();
+  for (const st of sf.statements) {
+    if ((ts.isFunctionDeclaration(st) || ts.isClassDeclaration(st)) && st.name) local.set(st.name.text, st);
+    if (ts.isVariableStatement(st)) for (const d of st.declarationList.declarations) if (ts.isIdentifier(d.name) && d.initializer) local.set(d.name.text, d.initializer);
+  }
+  const declOf = (name, value) => {
+    const v = value && ts.isIdentifier(value) && local.has(value.text) ? local.get(value.text) : value;
+    if (v && (ts.isClassDeclaration(v) || ts.isClassExpression(v))) return { name, kind: 'class', decorators: [], extends: [], members: [], routes: [] };
+    if (v && (ts.isFunctionDeclaration(v) || ts.isFunctionExpression(v) || ts.isArrowFunction(v) || ts.isMethodDeclaration(v))) return { name, kind: classifyFn(name, file), sig: paramsSig(v) };
+    return { name, kind: 'const' };
+  };
   const decls = [];
+  for (const st of sf.statements) {
+    if (!ts.isExpressionStatement(st) || !ts.isBinaryExpression(st.expression) || st.expression.operatorToken.kind !== ts.SyntaxKind.EqualsToken) continue;
+    const { left, right } = st.expression;
+    const target = cjsTarget(left);
+    if (target === null) continue;
+    if (target) decls.push(declOf(target, right));
+    else if (ts.isObjectLiteralExpression(right)) {
+      for (const p of right.properties) {
+        if (ts.isShorthandPropertyAssignment(p)) decls.push(declOf(p.name.text, p.name));
+        else if (ts.isPropertyAssignment(p) && p.name) decls.push(declOf(p.name.getText(sf), p.initializer));
+        else if (ts.isMethodDeclaration(p) && p.name) decls.push(declOf(p.name.getText(sf), p));
+      }
+    } else decls.push(declOf('default', right));
+  }
+  return decls;
+}
+
+function extractDecls(sf, file) {
+  const decls = cjsDecls(sf, file);
   for (const st of sf.statements) {
     if (ts.isClassDeclaration(st) && st.name && isExported(st)) {
       const decos = decoratorsOf(st);
@@ -159,6 +252,22 @@ function extractDecls(sf, file) {
   return decls;
 }
 
+// Files a package.json publishes through main, module, browser, bin and exports, as repo-relative paths.
+function publishedFiles(dir, pj) {
+  const out = new Set();
+  const add = (v) => {
+    if (typeof v === 'string') {
+      if (!v.startsWith('.') && !/^[\w@-]/.test(v)) return;
+      const abs = path.resolve(dir, v);
+      for (const c of [abs, ...['.js', '.ts', '.mjs', '.cjs', '/index.js', '/index.ts'].map((x) => abs + x)]) {
+        if (fs.existsSync(c) && fs.statSync(c).isFile()) return out.add(rel(c));
+      }
+    } else if (v && typeof v === 'object') Object.values(v).forEach(add);
+  };
+  for (const k of ['main', 'module', 'browser', 'bin', 'exports', 'types']) add(pj[k]);
+  return [...out].sort();
+}
+
 function declaredRole(dir) {
   const out = {};
   const pj = path.join(dir, 'project.json');
@@ -184,14 +293,13 @@ function analyzeWorkspace(ws, allWs) {
     bin: !!pj.bin,
     exportsField: !!(pj.exports || pj.main || pj.module || pj.types),
     dockerfile: fs.existsSync(path.join(ws.dir, 'Dockerfile')),
+    published: publishedFiles(ws.dir, pj),
     declared: declaredRole(ws.dir),
   };
-  const cfgPath = path.join(ws.dir, 'tsconfig.json');
-  const cfg = ts.readConfigFile(cfgPath, ts.sys.readFile);
-  const parsed = ts.parseJsonConfigFileContent(cfg.config, ts.sys, ws.dir, { noEmit: true }, cfgPath);
-  const options = { ...parsed.options, noEmit: true, skipLibCheck: true, allowJs: false };
+  const setup = compilerSetup(ws.dir);
+  const options = { ...setup.options, noEmit: true, skipLibCheck: true, allowJs: true, checkJs: false, maxNodeModuleJsDepth: 0 };
   const owner = (f) => allWs.filter((w) => f.startsWith(w.dir + path.sep)).sort((a, b) => b.dir.length - a.dir.length)[0];
-  let roots = parsed.fileNames.filter((f) => /\.tsx?$/.test(f) && !TEST_RE.test(rel(f)) && owner(f) === ws);
+  let roots = setup.fileNames.filter((f) => isSource(f) && !TEST_RE.test(rel(f)) && !inSkippedDir(rel(f)) && owner(f) === ws);
   const rootIndex = path.join(ws.dir, 'index.ts');
   if (fs.existsSync(rootIndex) && !roots.includes(rootIndex)) roots.push(rootIndex);
   roots = roots.sort();
@@ -202,17 +310,30 @@ function analyzeWorkspace(ws, allWs) {
 
   const files = {};
   const mq = [];
+  const skipped = [];
+  const inRoots = new Set(roots);
+  const configName = setup.config || 'package settings';
+  for (const abs of walkSources(ws.dir, true)) {
+    if (owner(abs) !== ws || TEST_RE.test(rel(abs)) || inRoots.has(abs)) continue;
+    skipped.push({ file: rel(abs), reason: COMPONENT_RE.test(abs) ? 'not parsed: Vue, Svelte and Astro files are not supported yet' : `left out by its ${configName}` });
+  }
   for (const abs of roots) {
     const sf = program.getSourceFile(abs);
-    if (!sf) continue;
+    if (!sf) {
+      skipped.push({ file: rel(abs), reason: 'could not be read' });
+      continue;
+    }
     const file = rel(abs);
     const imports = [];
+    const unresolved = new Set();
+    const dynamic = new Set();
     const externals = new Set();
     const boot = new Set();
     const mount = new Set();
     const lines = sf.getLineAndCharacterOfPosition(sf.end).line + 1;
 
     const addImport = (spec, names, node) => {
+      if (spec.startsWith('node:') || BUILTINS.has(spec)) return;
       const pkg = Object.keys(PKG_NAMES).find((n) => spec === n || spec.startsWith(n + '/'));
       if (pkg && PKG_NAMES[pkg] !== ws.id) {
         imports.push({ spec, target: `pkg:${PKG_NAMES[pkg]}`, names });
@@ -224,7 +345,12 @@ function analyzeWorkspace(ws, allWs) {
         if (!ts.isBuiltinModule?.(pkgName) && !BUILTINS.has(pkgName)) externals.add(pkgName);
         return;
       }
-      if (!r || r.isExternalLibraryImport || /node_modules/.test(r.resolvedFileName)) return;
+      if (!r) {
+        const bare = spec.replace(/[?#].*$/, '');
+        if (!/\.[A-Za-z0-9]+$/.test(bare) || SOURCE_RE.test(bare)) unresolved.add(spec);
+        return;
+      }
+      if (r.isExternalLibraryImport || /node_modules/.test(r.resolvedFileName)) return;
       const target = rel(r.resolvedFileName);
       if (target.startsWith('..')) return;
       imports.push({ spec, target, names });
@@ -246,7 +372,12 @@ function analyzeWorkspace(ws, allWs) {
         addImport(node.moduleSpecifier.text, names, node);
       } else if (ts.isCallExpression(node)) {
         const callee = node.expression;
-        if (callee.kind === ts.SyntaxKind.ImportKeyword && node.arguments[0] && ts.isStringLiteral(node.arguments[0])) addImport(node.arguments[0].text, ['*'], node);
+        const isImport = callee.kind === ts.SyntaxKind.ImportKeyword;
+        const isRequire = ts.isIdentifier(callee) && callee.text === 'require' && node.arguments.length === 1;
+        if ((isImport || isRequire) && node.arguments[0]) {
+          if (isStringish(node.arguments[0])) addImport(node.arguments[0].text, isImport ? ['*'] : requiredNames(node), node);
+          else dynamic.add(clip(node.arguments[0].getText(sf), 50));
+        }
         const text = callee.getText(sf);
         if (BOOT_RE.test(text)) boot.add(text.replace(/^.*\.(?=listen$)/, '.'));
         if (MOUNT_RE.test(text)) mount.add(text);
@@ -263,7 +394,7 @@ function analyzeWorkspace(ws, allWs) {
           const subj = prop(node.arguments[1], MSG.rpcSubjectProperty);
           if (subj) {
             const { values, inferred } = subjectsOf(checker, subj);
-            for (const s of values) mq.push({ kind: 'rpc-call', subject: s, file, inferred });
+            for (const s of values.filter((v) => SUBJECT_RE.test(v))) mq.push({ kind: 'rpc-call', subject: s, file, inferred });
             if (!values.length) mq.push({ kind: 'rpc-call-dynamic', file, expr: clip(subj.getText(sf), 50) });
           }
         }
@@ -280,9 +411,9 @@ function analyzeWorkspace(ws, allWs) {
       ts.forEachChild(node, visit);
     };
     visit(sf);
-    files[file] = { lines, imports, externals: [...externals].sort(), boot: [...boot].sort(), mount: [...mount].sort(), decls: extractDecls(sf, file) };
+    files[file] = { lines, imports, unresolved: [...unresolved].sort(), dynamic: [...dynamic].sort(), externals: [...externals].sort(), boot: [...boot].sort(), mount: [...mount].sort(), decls: extractDecls(sf, file) };
   }
-  return { id: ws.id, dir: rel(ws.dir) || '.', parent: ws.parent, aliases, files, mq, meta, lang: 'typescript' };
+  return { id: ws.id, dir: rel(ws.dir) || '.', parent: ws.parent, aliases, files, mq, meta, skipped, lang: Object.keys(files).some((f) => /\.[mc]?tsx?$/.test(f)) ? 'typescript' : 'javascript' };
 }
 
 function readMqModule(checker, obj, file) {
@@ -323,11 +454,19 @@ for (const ws of wss) {
   if (name && localDeps.has(name)) PKG_NAMES[name] = ws.id;
 }
 const result = { repo: REPO, workspaces: [] };
+// Every JS/TS source file in the repo (tests excluded) is either analysed or listed here with the reason.
+const skipped = [];
+const owned = (f) => wss.some((w) => f.startsWith(w.dir + path.sep));
+for (const abs of walkSources(REPO, true)) if (!TEST_RE.test(rel(abs)) && !owned(abs)) skipped.push({ pkg: null, file: rel(abs), reason: 'outside any package: no package.json above it' });
 for (const ws of wss) {
   const t0 = Date.now();
   const r = analyzeWorkspace(ws, wss);
+  for (const x of r.skipped) skipped.push({ pkg: ws.id, ...x });
+  delete r.skipped;
   if (!Object.keys(r.files).length) continue;
   result.workspaces.push(r);
   process.stdout.write(`${ws.id}: ${Object.keys(r.files).length} files, ${r.mq.length} mq facts, ${Date.now() - t0}ms\n`);
 }
+const analyzed = result.workspaces.reduce((n, w) => n + Object.keys(w.files).length, 0);
+result.coverage = { total: analyzed + skipped.length, analyzed, skipped };
 fs.writeFileSync(OUT, JSON.stringify(result));

package/src/model.mjs

@@ -1,16 +1,19 @@
 const glob = (pats) => new RegExp('(^|/)(' + pats.map((p) => p.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*').replace(/\/$/, '/.*')).join('|') + ')$');
 
-export function buildModel(repoName, facts, config) {
+// coverage: one { total, analyzed, skipped: [{ pkg, file, reason }] } per extractor that ran.
+export function buildModel(repoName, facts, config, coverages = []) {
+  const parts = coverages.filter(Boolean);
+  const coverage = parts.length ? { total: parts.reduce((n, c) => n + c.total, 0), analyzed: parts.reduce((n, c) => n + c.analyzed, 0), skipped: parts.flatMap((c) => c.skipped) } : null;
   const EXTERNAL_SYSTEMS = config.externalSystems;
   const SYSTEM_OF = Object.fromEntries(Object.entries(EXTERNAL_SYSTEMS).flatMap(([sys, pkgs]) => pkgs.map((p) => [p, sys])));
   const FOLDER_ROLE = config.folderRoles;
   const CONVENTIONAL_ENTRY_RE = glob(config.conventionalEntries);
   const FRAMEWORK_LOADED_RE = glob(config.frameworkLoaded);
   const SDK_RE = new RegExp(`/(${config.sdkDirs.join('|')})/([^/]+)/`);
-  return buildModelWith({ repoName, facts, EXTERNAL_SYSTEMS, SYSTEM_OF, FOLDER_ROLE, CONVENTIONAL_ENTRY_RE, FRAMEWORK_LOADED_RE, SDK_RE });
+  return buildModelWith({ repoName, facts, coverage, EXTERNAL_SYSTEMS, SYSTEM_OF, FOLDER_ROLE, CONVENTIONAL_ENTRY_RE, FRAMEWORK_LOADED_RE, SDK_RE });
 }
 
-function buildModelWith({ repoName, facts, EXTERNAL_SYSTEMS, SYSTEM_OF, FOLDER_ROLE, CONVENTIONAL_ENTRY_RE, FRAMEWORK_LOADED_RE, SDK_RE }) {
+function buildModelWith({ repoName, facts, coverage, EXTERNAL_SYSTEMS, SYSTEM_OF, FOLDER_ROLE, CONVENTIONAL_ENTRY_RE, FRAMEWORK_LOADED_RE, SDK_RE }) {
   const wsList = [...facts].sort((a, b) => a.id.localeCompare(b.id));
   const packages = {};
   const nodes = {};
@@ -38,7 +41,7 @@ function buildModelWith({ repoName, facts, EXTERNAL_SYSTEMS, SYSTEM_OF, FOLDER_R
   for (const [file, f] of Object.entries(files)) {
     for (const d of f.decls) {
       const k = `${f.pkg}::${d.name}`;
-      if (!exportIndex[k] || /index\.tsx?$/.test(exportIndex[k])) exportIndex[k] = file;
+      if (!exportIndex[k] || /index\.[mc]?[jt]sx?$/.test(exportIndex[k])) exportIndex[k] = file;
     }
   }
 
@@ -139,8 +142,7 @@ function buildModelWith({ repoName, facts, EXTERNAL_SYSTEMS, SYSTEM_OF, FOLDER_R
   const thirdParty = {};
   for (const [file, f] of Object.entries(files)) {
     for (const ext of f.externals) {
-      const sys = SYSTEM_OF[ext];
-      if (sys) addEdge(file, `ext:${sys}`, 'ext', ext);
+      addEdge(file, `ext:${SYSTEM_OF[ext] || ext}`, 'ext', ext);
       for (const k of chainOf(file)) {
         const t = (thirdParty[k] ||= {});
         t[ext] = (t[ext] || 0) + 1;
@@ -193,7 +195,7 @@ function buildModelWith({ repoName, facts, EXTERNAL_SYSTEMS, SYSTEM_OF, FOLDER_R
     if (p.role !== 'library') {
       const importers = [...new Set(PE.filter((e) => e.to === p.id && e.kind === 'import').map((e) => e.from))].sort();
       if (importers.length) findings.push({ type: 'runnable-imported', severity: 'design', pkg: p.id, title: `${p.id} is a ${p.role} but ${importers.join(', ')} import${importers.length > 1 ? '' : 's'} its code`, detail: 'Runnable packages imported as libraries couple deploys together.' });
-    } else if (!PE.some((e) => e.to === p.id)) {
+    } else if (Object.keys(packages).length > 1 && !PE.some((e) => e.to === p.id)) {
       findings.push({ type: 'unused-library', severity: 'check', pkg: p.id, title: `${p.id} is a library nothing else uses`, detail: 'No entry point and no other package imports it.' });
     }
   }
@@ -209,9 +211,26 @@ function buildModelWith({ repoName, facts, EXTERNAL_SYSTEMS, SYSTEM_OF, FOLDER_R
   for (const c of unmatched.calls) findings.push({ type: 'rpc-no-server', severity: 'check', pkg: c.pkg, title: `RPC "${c.subject}" has no server in the repo`, detail: `Called from ${c.file}.` });
   for (const p of unmatched.pubs) findings.push({ type: 'event-no-subscriber', severity: 'check', pkg: p.pkg, title: `Event "${p.subject}" has no subscriber in the repo`, detail: `Published from ${p.file}.` });
   for (const s of unmatched.subs) findings.push({ type: 'subscription-no-publisher', severity: 'check', pkg: s.pkg, title: `"${s.subject}" is subscribed but never published in the repo`, detail: `Handled in ${s.file}.${dyn}` });
+  for (const w of wsList) {
+    for (const [file, info] of Object.entries(w.files).sort()) {
+      for (const spec of info.unresolved || []) findings.push({ type: 'unresolved-import', severity: 'check', pkg: w.id, title: `${file} imports ${spec}, which does not resolve to a file`, detail: 'The import is missing from the map. The file may be missing, generated at build time, or reached through an alias the analysis does not know.', files: [file] });
+      for (const expr of info.dynamic || []) findings.push({ type: 'dynamic-import', severity: 'check', pkg: w.id, title: `${file} imports a module named at runtime: ${expr}`, detail: 'Static analysis cannot tell which module this loads, so the import is missing from the map.', files: [file] });
+    }
+  }
+  const skippedBy = new Map();
+  for (const x of coverage ? coverage.skipped : []) {
+    const k = `${x.pkg || ''}|${x.reason}`;
+    if (!skippedBy.has(k)) skippedBy.set(k, { pkg: x.pkg, reason: x.reason, files: [] });
+    skippedBy.get(k).files.push(x.file);
+  }
+  for (const g of skippedBy.values()) {
+    const n = `${g.files.length} file${g.files.length > 1 ? 's' : ''}`;
+    findings.push({ type: 'skipped-files', severity: 'check', pkg: g.pkg || undefined, title: g.pkg ? `${n} in ${g.pkg} ${g.reason}` : `${n} ${g.reason}`, detail: 'These files are not on the map.', files: g.files.sort() });
+  }
+  const published = new Set(Object.values(packages).flatMap((p) => p.meta.published || []));
   const orphans = {};
   for (const [file, f] of Object.entries(files)) {
-    if (importedFiles.has(file) || CONVENTIONAL_ENTRY_RE.test(file) || FRAMEWORK_LOADED_RE.test(file) || f.boot.length || f.mount.length) continue;
+    if (importedFiles.has(file) || published.has(file) || CONVENTIONAL_ENTRY_RE.test(file) || FRAMEWORK_LOADED_RE.test(file) || f.boot.length || f.mount.length) continue;
     (orphans[f.pkg] ||= []).push(file);
   }
   for (const [pkg, list] of Object.entries(orphans).sort()) findings.push({ type: 'orphan-files', severity: 'check', pkg, title: `${list.length} file${list.length > 1 ? 's' : ''} in ${pkg} never imported`, detail: 'Not imported by any other file and not an entry point.', files: list.sort() });
@@ -232,6 +251,7 @@ function buildModelWith({ repoName, facts, EXTERNAL_SYSTEMS, SYSTEM_OF, FOLDER_R
     thirdParty: thirdPartyOut,
     fineEdges: FE,
     findings,
+    coverage: coverage ? { total: coverage.total, analyzed: coverage.analyzed, skipped: coverage.skipped.length } : null,
     mq: { calls: mq.call.length, serves: mq.serve.length, pubs: mq.pub.length, subs: mq.sub.length, dynamic: mq.dynamic },
   };
 }
@@ -244,7 +264,7 @@ function runtimeOf(p, used) {
   const ui = [['react', 'React'], ['react-dom', 'React'], ['vue', 'Vue'], ['@angular/core', 'Angular'], ['svelte', 'Svelte'], ['solid-js', 'Solid']];
   const server = [['@nestjs/core', 'NestJS'], ['@nestjs/common', 'NestJS'], ['express', 'Express'], ['fastify', 'Fastify'], ['hono', 'Hono'], ['@temporalio/worker', 'Temporal'], ['koa', 'Koa']];
   for (const [mod, name] of p.role === 'app' ? [...ui, ...server] : [...server, ...ui]) if (used[mod]) return name;
-  return 'TypeScript';
+  return p.lang === 'javascript' ? 'JavaScript' : 'TypeScript';
 }
 
 function sdkTarget(name, packages, self) {

package/src/template.html

@@ -271,7 +271,7 @@ details summary { cursor: pointer; color: var(--muted); font-size: 13px; }
           <dt>Dependents · outside</dt><dd>What uses this folder from elsewhere.</dd>
           <dt>Frame</dt><dd>The folder itself. Its parts sit in tiers from <b>Ln · Entry</b> (nothing in here uses it) down to <b>L0 · Base</b> (uses nothing else in here). A part sits one tier above the highest thing it imports or calls.</dd>
           <dt>Dependencies · outside</dt><dd>Other code in the repo this folder uses.</dd>
-          <dt>External systems</dt><dd>Databases, brokers and vendors, detected from the packages the code imports.</dd>
+          <dt>External dependencies</dt><dd>Every third-party package the code imports. Known drivers and SDKs are named by the system they reach, such as PostgreSQL or Stripe.</dd>
         </dl>
         <p>A dashed red box is an import cycle: its parts import each other, so they share a tier.</p>
       </section>
@@ -280,7 +280,7 @@ details summary { cursor: pointer; color: var(--muted); font-size: 13px; }
         <dl>
           <dt>Border colour</dt><dd>Green library, blue service, pink app. Dashed boxes are outside the current folder.</dd>
           <dt><span class="plus">+</span></dt><dd>The box has inner parts you can zoom into.</dd>
-          <dt>Lines</dt><dd>Import (solid), RPC call (thick), HTTP call (blue dashed), event subscription (amber, dot end), external system (grey dotted). Each points from the part that depends to the part it depends on.</dd>
+          <dt>Lines</dt><dd>Import (solid), RPC call (thick), HTTP call (blue dashed), event subscription (amber, dot end), external dependency (grey dotted). Each points from the part that depends to the part it depends on.</dd>
         </dl>
       </section>
       <section>
@@ -309,7 +309,7 @@ details summary { cursor: pointer; color: var(--muted); font-size: 13px; }
       </section>
       <section>
         <h3>Running it</h3>
-        <p><code>npx repo-blueprint build &lt;repo&gt;</code> writes a standalone HTML file. <code>npx repo-blueprint watch &lt;repo&gt;</code> serves it and rebuilds on code changes. A repo can add external systems, message-bus method names and folder-role hints in a <code>.blueprint.json</code> at its root.</p>
+        <p><code>npx repo-blueprint build &lt;repo&gt;</code> writes a standalone HTML file. <code>npx repo-blueprint watch &lt;repo&gt;</code> serves it and rebuilds on code changes. A repo can name more external systems, add message-bus method names and folder-role hints in a <code>.blueprint.json</code> at its root.</p>
       </section>
     </div>
   </div>
@@ -472,6 +472,13 @@ function frameBox(layer) {
   const c = layer.querySelector('.pele-cluster[data-id="FRAME"] rect');
   return c ? svgBox(layer, c) : null;
 }
+// The dependency tiers of a view, without the external band: where the opening camera aims when there is no frame.
+function levelsBox(layer) {
+  const boxes = [...layer.querySelectorAll('.pele-cluster')].filter((c) => /^L\d+$/.test(c.getAttribute('data-id'))).map((c) => svgBox(layer, c.querySelector('rect') || c));
+  if (!boxes.length) return null;
+  const x = Math.min(...boxes.map((b) => b.x));
+  return { x, w: Math.max(...boxes.map((b) => b.x + b.w)) - x };
+}
 function fitCam(box, pad = 0.92, maxS = 1.5) {
   const W = stage.clientWidth, H = stage.clientHeight;
   const s = Math.min(maxS, Math.min(W / box.w, H / box.h) * pad);
@@ -488,7 +495,7 @@ function homeCam(layer) {
   const readable = W < 600 ? 0.45 : 0.7;
   if (fit.s >= readable) return fit;
   const s = Math.min(1, Math.max(readable, (W / v.width) * 0.96));
-  const fb = frameBox(layer) || { x: 0, w: v.width };
+  const fb = frameBox(layer) || levelsBox(layer) || { x: 0, w: v.width };
   const x = fb.w * s > W - 24 ? 12 - fb.x * s : W / 2 - (fb.x + fb.w / 2) * s;
   return { s, x, y: 12 };
 }
@@ -812,6 +819,9 @@ const FINDING_TYPES = {
   'rpc-no-server': { label: 'RPC without server', desc: 'An RPC subject is called, but no handler for it exists in the repo.' },
   'event-no-subscriber': { label: 'Unheard event', desc: 'An event is published, but nothing in the repo subscribes to it.' },
   'subscription-no-publisher': { label: 'Orphan subscription', desc: 'Something subscribes to an event that nothing in the repo publishes.' },
+  'skipped-files': { label: 'Not mapped', desc: 'Source files the analysis did not read, with the reason. Nothing they import or export is on the map.' },
+  'unresolved-import': { label: 'Unresolved import', desc: 'An import that does not resolve to a file, so it is missing from the map.' },
+  'dynamic-import': { label: 'Runtime import', desc: 'An import whose module is only known at runtime, so it is missing from the map.' },
   'orphan-files': { label: 'Unimported files', desc: 'Files no other file imports that are not entry points. Often dead code.' },
 };
 const SEVERITY = {
@@ -903,9 +913,10 @@ function edgeHtml(v, e) {
 
 function extHtml(key, v) {
   const name = key.slice(4);
-  const pkgs = M.externalSystems[name] || [];
+  const pkgs = M.externalSystems[name];
   const users = v.all.filter((e) => e.to === key);
-  return `<h2>${esc(name)}</h2><p class="det">External system, outside the repo. Detected from imports of: <span class="mono">${esc(pkgs.join(', '))}</span></p>
+  const what = pkgs ? `External system, outside the repo. Detected from imports of: <span class="mono">${esc(pkgs.join(', '))}</span>` : 'Third-party package, imported from outside the repo.';
+  return `<h2>${esc(name)}</h2><p class="det">${what}</p>
     <div><h3>Used by, in this view</h3><ul>${users.map((e) => `<li><button class="link" data-k="${esc(e.from)}">${esc(labelOf(state.view, e.from))}</button><div class="det mono">${esc(e.details.join(', '))} · ${e.count} file${e.count > 1 ? 's' : ''}</div></li>`).join('')}</ul></div>`;
 }
 
@@ -1063,7 +1074,7 @@ function renderLegend() {
   const on = loadEdgeKinds();
   $('legend').innerHTML = `<span><span class="sw" style="border-color:var(--green)"></span>library</span><span><span class="sw" style="border-color:var(--in)"></span>service</span><span><span class="sw" style="border-color:var(--out)"></span>app</span>
     <span><span class="sw" style="border-color:var(--red);border-style:dashed"></span>import cycle</span>
-    <span><span class="sw" style="border-color:var(--muted);border-style:dotted"></span>external system</span>
+    <span><span class="sw" style="border-color:var(--muted);border-style:dotted"></span>external</span>
     ${EDGE_KINDS.map((e) => `<button class="tog" data-kind="${e.k}" aria-pressed="${on.has(e.k)}" title="${e.label} lines: on shows them always, off shows them only for the hovered box">${line(e.dash, e.color, e.end)}${e.label}</button>`).join('')}
 `;
   for (const b of $('legend').querySelectorAll('.tog')) b.addEventListener('click', () => {

package/src/views.mjs

@@ -206,8 +206,9 @@ function makeView(v) {
   const outerNodes = (side) =>
     [...outer.entries()]
       .filter(([, o]) => o.side === side)
-      .map(([k]) => (k.startsWith('more:') ? { key: k, label: `+${more[side].length} more`, cls: ['outer', 'more'], outerSide: side } : { ...outerOf(k), outerSide: side }))
-      .sort((a, b) => (a.key.startsWith('more:') ? 1 : 0) - (b.key.startsWith('more:') ? 1 : 0) || a.label.localeCompare(b.label));
+      .map(([k, o]) => (k.startsWith('more:') ? { key: k, label: `+${more[side].length} more`, cls: ['outer', 'more'], outerSide: side, weight: 0 } : { ...outerOf(k), outerSide: side, weight: o.weight }))
+      // External dependencies read most-used first; neighbouring packages stay alphabetical.
+      .sort((a, b) => (a.key.startsWith('more:') ? 1 : 0) - (b.key.startsWith('more:') ? 1 : 0) || (side === 'ext' ? b.weight - a.weight : 0) || a.label.localeCompare(b.label));
   const ups = v.frame ? outerNodes('up') : [];
   const downs = v.frame ? outerNodes('down') : [];
   const exts = outerNodes('ext');
@@ -246,7 +247,7 @@ function makeView(v) {
     lines.push('  end');
   }
   if (exts.length) {
-    lines.push('  subgraph EXT["External systems"]');
+    lines.push('  subgraph EXT["External dependencies"]');
     chunk(exts, '    ');
     lines.push('  end');
   }