codebase-onboarder 0.6.0 → 1.0.0

package/cli/explorer/session.js

@@ -1,3 +1,4 @@
+import { throwIfAborted } from '../../shared/analyzer/scanControl.js';
 // One repository, loaded into memory, the way the website loads it.
 //
 // This is the whole reason the terminal app can stand in for the site: it runs
@@ -9,10 +10,8 @@
 //
 // Everything below the loader is pure data plus a few lookups. The loader is
 // the only async part, and it is the only part that touches the filesystem.
-
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-
 import { nodeFileSource } from '../../server/fileSourceNode.js';
 import { buildSearchIndex } from '../../server/searchIndex.js';
 import { searchDocuments } from '../../server/apiSearch.js';
@@ -29,7 +28,6 @@ import { analyzeStack } from '../../shared/analyzer/stack.js';
 import { buildTourStops } from '../../shared/analyzer/tour.js';
 import { explainFile, explainFolder, explainOverview } from '../../shared/analyzer/explainLocal.js';
 import { languageLabel } from '../../shared/analyzer/languages/index.js';
-
 // Does this argument name a repository to fetch, rather than a folder on this
 // machine? The check is deliberately narrow: only the URL shapes git itself
 // accepts, so a folder that happens to be called `ssh://stuff` cannot exist on a
@@ -38,109 +36,111 @@ import { languageLabel } from '../../shared/analyzer/languages/index.js';
 // `github.com/src/server` because someone typed `cd src/server` would be a
 // genuinely bad failure. The shorthand, if it is wanted, has to be asked for.
 export function isGitUrl(target) {
-  return /^(https?:\/\/|git@|ssh:\/\/)/.test(String(target || '').trim());
+    return /^(https?:\/\/|git@|ssh:\/\/)/.test(String(target || '').trim());
 }
-
 // Open a local folder or clone a remote one — the same three ways in the web
 // app's landing page offers, narrowed to the two that make sense for a command
 // line. A clone is left in place when the session ends; `closeRemote` removes it,
 // and the session calls that on `cd` and on exit, so nothing is orphaned in the
 // temp dir.
-export async function openRepoOrClone(target, { onProgress } = {}) {
-  const raw = String(target || '').trim();
-  if (!isGitUrl(raw)) return openRepo(raw, { onProgress });
-
-  const url = assertGitUrl(raw);
-  if (onProgress) onProgress({ phase: 'clone', url });
-  const clone = await cloneRepo(url);
-  try {
-    const repo = await openRepo(clone.dir, { onProgress });
-    // The repo's own name is what a person recognizes; the temp path is kept so
-    // `about` can still print a path someone could go and look at.
-    return {
-      ...repo,
-      name: repoNameFromUrl(url) || repo.name,
-      gitUrl: url,
-      tempId: path.basename(clone.dir),
-      cloneDir: clone.dir,
-    };
-  } catch (err) {
-    // A clone that was never loaded has no session to clean it up later, so it
-    // has to go now or it is a temp directory nobody owns.
-    await removeClone(clone.dir);
-    throw err;
-  }
+export async function openRepoOrClone(target, options = {}) {
+    throwIfAborted(options.signal);
+    const onProgress = options.onProgress;
+    const raw = String(target || '').trim();
+    if (!isGitUrl(raw))
+        return openRepo(raw, options);
+    const url = assertGitUrl(raw);
+    if (onProgress)
+        onProgress({ phase: 'clone', url });
+    const clone = await cloneRepo(url);
+    try {
+        const repo = await openRepo(clone.dir, options);
+        // The repo's own name is what a person recognizes; the temp path is kept so
+        // `about` can still print a path someone could go and look at.
+        return {
+            ...repo,
+            name: repoNameFromUrl(url) || repo.name,
+            gitUrl: url,
+            tempId: path.basename(clone.dir),
+            cloneDir: clone.dir,
+        };
+    }
+    catch (err) {
+        // A clone that was never loaded has no session to clean it up later, so it
+        // has to go now or it is a temp directory nobody owns.
+        await removeClone(clone.dir);
+        throw err;
+    }
 }
-
 // The URL this repo should be asked about on GitHub, or null.
 //
 // A repo this session cloned knows its own URL. A repo someone was standing in
 // does not, and git does. Asking git here rather than in the `github` command
 // keeps the answer on the repo object, so every consumer gets it the same way.
 export async function remoteUrlFor(repo) {
-  if (repo.gitUrl) return repo.gitUrl;
-  if (repo.remoteChecked) return null;
-  repo.remoteChecked = true;
-  const found = await gitRemoteOrigin(repo.root);
-  if (found.ok) repo.gitUrl = found.url;
-  return repo.gitUrl || null;
+    if (repo.gitUrl)
+        return repo.gitUrl;
+    if (repo.remoteChecked)
+        return null;
+    repo.remoteChecked = true;
+    const found = await gitRemoteOrigin(repo.root);
+    if (found.ok)
+        repo.gitUrl = found.url;
+    return repo.gitUrl || null;
 }
-
 // Drop a temp clone, if this repo is one. Safe to call on a local repo: it
 // checks the shape of the directory rather than trusting a flag, so a bug
 // elsewhere cannot turn "clean up" into "delete the folder the user is in".
 export async function closeRemote(repo) {
-  if (repo?.cloneDir) await removeClone(repo.cloneDir);
+    if (repo?.cloneDir)
+        await removeClone(repo.cloneDir);
 }
-
 // Scan a directory and return the loaded repo, or throw an Error whose message
 // is safe to print straight to the user. `target` may be `~`, a relative path,
 // or anything `expandHome` understands; it defaults to the current directory.
-export async function openRepo(target = '.', { onProgress } = {}) {
-  const root = expandHome(String(target || '.'));
-  const stat = await fs.stat(root).catch(() => null);
-  if (!stat) throw new Error('No such folder: ' + root);
-  if (!stat.isDirectory()) throw new Error('Not a folder: ' + root);
-
-  const source = nodeFileSource(root);
-  const scan = await scanRepo(source, { onProgress });
-  const manifest = await detectManifest(source);
-  const facts = computeFacts(scan, manifest);
-  const searchIndex = await buildSearchIndex(source, scan.files.map((f) => f.path));
-
-  // The layers projection is an input to patterns, not a parallel view of the
-  // same thing — `detectPatterns` reads the layer depths to place a file in the
-  // architecture. Compute once, share. The coupling matrix is the same kind of
-  // thing: a projection of `facts.folderEdges` that both the site and the
-  // terminal's heat grid read, so it is computed once here rather than per view.
-  const layers = computeLayers(scan, facts);
-
-  return {
-    root,
-    name: scan.name || path.basename(root),
-    scan,
-    facts,
-    manifest,
-    searchIndex,
-    layers,
-    coupling: couplingMatrix(scan, facts),
-    health: analyzeHealth(scan, facts),
-    patterns: detectPatterns(scan, facts, manifest, layers),
-    security: summarizeSecurity(scan),
-    stack: analyzeStack(manifest, scan.stats.languages || {}),
-    tour: buildTourStops(scan, facts),
-    languages: languageRows(scan),
-  };
+export async function openRepo(target = '.', options = {}) {
+    const root = expandHome(String(target || '.'));
+    const stat = await fs.stat(root).catch(() => null);
+    if (!stat)
+        throw new Error('No such folder: ' + root);
+    if (!stat.isDirectory())
+        throw new Error('Not a folder: ' + root);
+    const source = nodeFileSource(root);
+    const scan = await scanRepo(source, options);
+    const manifest = await detectManifest(source);
+    const facts = computeFacts(scan, manifest);
+    const searchIndex = await buildSearchIndex(source, scan.files.map((f) => f.path));
+    // The layers projection is an input to patterns, not a parallel view of the
+    // same thing — `detectPatterns` reads the layer depths to place a file in the
+    // architecture. Compute once, share. The coupling matrix is the same kind of
+    // thing: a projection of `facts.folderEdges` that both the site and the
+    // terminal's heat grid read, so it is computed once here rather than per view.
+    const layers = computeLayers(scan, facts);
+    const loaded = {
+        root,
+        name: scan.name || path.basename(root),
+        scan,
+        facts,
+        manifest,
+        searchIndex,
+        layers,
+        coupling: couplingMatrix(scan, facts),
+        health: analyzeHealth(scan, facts),
+        patterns: detectPatterns(scan, facts, manifest, layers),
+        security: summarizeSecurity(scan),
+        stack: analyzeStack(manifest, scan.stats.languages || {}),
+        tour: buildTourStops(scan, facts),
+        languages: languageRows(scan),
+    };
+    return loaded;
 }
-
 // LOC per language, biggest first, with the display label the site uses — so
 // `JavaScript` here and `JavaScript` there are the same string.
 function languageRows(scan) {
-  return Object.entries(scan.stats.languages || {})
-    .map(([id, loc]) => ({ id, loc, label: languageLabel(id) }))
-    .sort((a, b) => b.loc - a.loc || a.label.localeCompare(b.label));
+    return Object.entries(scan.stats.languages || {})
+        .map(([id, loc]) => ({ id, loc, label: languageLabel(id) }))
+        .sort((a, b) => Number(b.loc) - Number(a.loc) || a.label.localeCompare(b.label));
 }
-
 // The one place a typed path becomes a real file. People type `logger.js`, not
 // `server/logger.js`, and a tool that says "no such file" for a file that is
 // right there is worse than no tool. So: exact, then folder, then suffix, then
@@ -148,104 +148,103 @@ function languageRows(scan) {
 // than guessed at — silently picking the wrong `index.js` is the failure mode
 // that makes people stop trusting a map.
 export function resolveTarget(repo, typed) {
-  const raw = String(typed || '').trim().replace(/^\.\//, '');
-  if (!raw) return { error: 'Name a file or folder.' };
-
-  // `.` and `./` are the root, which is a real folder and a common thing to type
-  // (`tree .`, `explain .`). Without this they fell through to the substring
-  // match and offered eight unrelated files as "did you mean", which is worse
-  // than useless — it is actively misleading. The root folder's path is `''`.
-  if (raw === '.' || raw === './') return { folder: ROOT_FOLDER };
-
-  const files = repo.scan.files;
-  if (!repo.byPath) repo.byPath = new Map(files.map((f) => [f.path, f]));
-  if (repo.byPath.has(raw)) return { file: repo.byPath.get(raw) };
-
-  const folder = folderFor(repo, raw);
-  if (folder) return { folder };
-
-  const lower = raw.toLowerCase();
-  const suffix = files.filter((f) => f.path.endsWith('/' + raw));
-  if (suffix.length === 1) return { file: suffix[0] };
-  if (suffix.length > 1) return { error: 'Which one?', candidates: suffix.map((f) => f.path) };
-
-  const base = files.filter((f) => f.name.toLowerCase() === lower);
-  if (base.length === 1) return { file: base[0] };
-  if (base.length > 1) return { error: 'Which one?', candidates: base.map((f) => f.path) };
-
-  const loose = files.filter((f) => f.path.toLowerCase().includes(lower));
-  if (loose.length) {
-    loose.sort((a, b) => a.path.length - b.path.length);
-    return { error: 'No exact match. Did you mean:', candidates: loose.slice(0, 8).map((f) => f.path) };
-  }
-  return { error: 'Nothing in this repo matches "' + raw + '".' };
+    const raw = String(typed || '').trim().replace(/^\.\//, '');
+    if (!raw)
+        return { error: 'Name a file or folder.' };
+    // `.` and `./` are the root, which is a real folder and a common thing to type
+    // (`tree .`, `explain .`). Without this they fell through to the substring
+    // match and offered eight unrelated files as "did you mean", which is worse
+    // than useless — it is actively misleading. The root folder's path is `''`.
+    if (raw === '.' || raw === './')
+        return { folder: ROOT_FOLDER };
+    const files = repo.scan.files;
+    if (!repo.byPath)
+        repo.byPath = new Map(files.map((f) => [f.path, f]));
+    if (repo.byPath.has(raw))
+        return { file: repo.byPath.get(raw) };
+    const folder = folderFor(repo, raw);
+    if (folder)
+        return { folder };
+    const lower = raw.toLowerCase();
+    const suffix = files.filter((f) => f.path.endsWith('/' + raw));
+    if (suffix.length === 1)
+        return { file: suffix[0] };
+    if (suffix.length > 1)
+        return { error: 'Which one?', candidates: suffix.map((f) => f.path) };
+    const base = files.filter((f) => f.name.toLowerCase() === lower);
+    if (base.length === 1)
+        return { file: base[0] };
+    if (base.length > 1)
+        return { error: 'Which one?', candidates: base.map((f) => f.path) };
+    const loose = files.filter((f) => f.path.toLowerCase().includes(lower));
+    if (loose.length) {
+        loose.sort((a, b) => a.path.length - b.path.length);
+        return { error: 'No exact match. Did you mean:', candidates: loose.slice(0, 8).map((f) => f.path) };
+    }
+    return { error: 'Nothing in this repo matches "' + raw + '".' };
 }
-
 // The root folder is a real answer, not a sentinel: `tree .` and `explain .`
 // both need one, and it carries the same fields `resolveTarget` returns for any
 // other folder so the callers need no special case.
 const ROOT_FOLDER = Object.freeze({ name: '', path: '', loc: 0, comment: 0, blank: 0, size: 0, langs: {} });
-
 function folderFor(repo, typed) {
-  const clean = typed.replace(/\/+$/, '');
-  if (clean === '') return ROOT_FOLDER;
-  const exact = repo.scan.folders.find((d) => d.path === clean);
-  if (exact) return exact;
-  const matches = repo.scan.folders.filter((d) => d.path.endsWith('/' + clean) || d.name === clean);
-  return matches.length === 1 ? matches[0] : null;
+    const clean = typed.replace(/\/+$/, '');
+    if (clean === '')
+        return ROOT_FOLDER;
+    const exact = repo.scan.folders.find((d) => d.path === clean);
+    if (exact)
+        return exact;
+    const matches = repo.scan.folders.filter((d) => d.path.endsWith('/' + clean) || d.name === clean);
+    return matches.length === 1 ? matches[0] : null;
 }
-
 // Read a file through the same containment check the HTTP route uses. A tool
 // whose job is showing you one repository has no business reading any path on
 // the machine, and going through `resolveInside` means there is no second,
 // looser door to get there.
 export async function readRepoFile(repo, repoPath) {
-  const abs = resolveInside(repo.root, repoPath);
-  if (!abs) throw new Error('That path is outside the repository.');
-  return fs.readFile(abs, 'utf8');
+    const abs = resolveInside(repo.root, repoPath);
+    if (!abs)
+        throw new Error('That path is outside the repository.');
+    return fs.readFile(abs, 'utf8');
 }
-
 // The website's search, verbatim: same TF-IDF ranking, same query language
 // (`ext:`, `path:`, `-exclude`, `"phrases"`, `/regex/`), same result shape. A
 // query that works in one surface works in the other, because it is the same
 // function.
 export function searchRepo(repo, query, { limit = 12 } = {}) {
-  return searchDocuments(repo.searchIndex, query, { limit });
+    return searchDocuments(repo.searchIndex, query, { limit });
 }
-
 // A number a person typed, or nothing. `show f 1.5 2.5` used to print
 // `1.5–3 of 344`: `Number('1.5')` passed the `|| 1` fallback, the label
 // interpolated the fraction, and only `slice()` coerced it. A line range is
 // either a whole number of lines or it is a mistake, and a mistake gets a
 // message rather than a wrong heading.
 export function lineNumber(value, fallback) {
-  if (value === undefined || value === null || value === '') return fallback;
-  const n = Number(value);
-  return Number.isInteger(n) && n > 0 ? n : null;
+    if (value === undefined || value === null || value === '')
+        return fallback;
+    const n = Number(value);
+    return Number.isInteger(n) && n > 0 ? n : null;
 }
-
 export function explainRepoFile(repo, file) {
-  return explainFile(file.path, file, repo.facts);
+    return explainFile(file.path, file, repo.facts);
 }
-
 export function explainRepoFolder(repo, folder) {
-  return explainFolder(folder.path, repo.scan, repo.facts);
+    return explainFolder(folder.path, repo.scan, repo.facts);
 }
-
 export function explainRepoOverview(repo) {
-  return explainOverview(repo.scan, repo.facts, repo.manifest);
+    return explainOverview(repo.scan, repo.facts, repo.manifest);
 }
-
 // Short facts about a file, in the order `docs.js` states them, so the terminal
 // and the generated docs never describe the same file differently.
 export function fileFacts(repo, file) {
-  return {
-    role: roleOf(file.path, repo.facts),
-    loc: file.loc || 0,
-    complexity: file.complexity || 0,
-    fanIn: repo.facts.fanIn[file.path] || 0,
-    fanOut: repo.facts.fanOut[file.path] || 0,
-    inCycle: (repo.facts.inCycle || []).includes(file.path),
-    findings: (file.findings || []).length,
-  };
+    return {
+        role: roleOf(file.path, repo.facts),
+        loc: file.loc || 0,
+        complexity: file.complexity || 0,
+        fanIn: repo.facts.fanIn[file.path] || 0,
+        fanOut: repo.facts.fanOut[file.path] || 0,
+        inCycle: (repo.facts.inCycle || []).includes(file.path),
+        findings: (file.findings || []).length,
+    };
 }
+//# sourceMappingURL=session.js.map

package/cli/explorer/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/cli/explorer/session.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ScanOptions } from '../../shared/contracts.js';\nimport { throwIfAborted } from '../../shared/analyzer/scanControl.js';\n// One repository, loaded into memory, the way the website loads it.\n//\n// This is the whole reason the terminal app can stand in for the site: it runs\n// the *same* modules in the *same* order as `server/apiScan.js` — FileSource →\n// scanRepo → detectManifest → computeFacts → buildSearchIndex — and then the\n// same projections the browser's views are projections of (health, layers,\n// patterns, security, stack, tour). Nothing here re-implements analysis, so the\n// two surfaces cannot drift into telling different stories about one repo.\n//\n// Everything below the loader is pure data plus a few lookups. The loader is\n// the only async part, and it is the only part that touches the filesystem.\n\nimport { promises as fs } from 'node:fs';\nimport path from 'node:path';\n\nimport { nodeFileSource } from '../../server/fileSourceNode.js';\nimport { buildSearchIndex } from '../../server/searchIndex.js';\nimport { searchDocuments } from '../../server/apiSearch.js';\nimport { expandHome, resolveInside } from '../../server/paths.js';\nimport { assertGitUrl, cloneRepo, removeClone, repoNameFromUrl } from '../../server/gitClone.js';\nimport { gitRemoteOrigin } from '../../server/gitRemote.js';\nimport { scanRepo } from '../../shared/analyzer/scan.js';\nimport { detectManifest } from '../../shared/analyzer/services.js';\nimport { computeFacts, roleOf } from '../../shared/analyzer/graph.js';\nimport { analyzeHealth } from '../../shared/analyzer/health.js';\nimport { computeLayers, detectPatterns, couplingMatrix } from '../../shared/analyzer/patterns.js';\nimport { summarizeSecurity } from '../../shared/analyzer/security.js';\nimport { analyzeStack } from '../../shared/analyzer/stack.js';\nimport { buildTourStops } from '../../shared/analyzer/tour.js';\nimport { explainFile, explainFolder, explainOverview } from '../../shared/analyzer/explainLocal.js';\nimport { languageLabel } from '../../shared/analyzer/languages/index.js';\n\n// Does this argument name a repository to fetch, rather than a folder on this\n// machine? The check is deliberately narrow: only the URL shapes git itself\n// accepts, so a folder that happens to be called `ssh://stuff` cannot exist on a\n// filesystem anyway, while `owner/repo` is NOT accepted — too many real folders\n// are named like that (`src/server`, `app/models`) and silently cloning\n// `github.com/src/server` because someone typed `cd src/server` would be a\n// genuinely bad failure. The shorthand, if it is wanted, has to be asked for.\nexport function isGitUrl(target) {\n  return /^(https?:\\/\\/|git@|ssh:\\/\\/)/.test(String(target || '').trim());\n}\n\n// Open a local folder or clone a remote one — the same three ways in the web\n// app's landing page offers, narrowed to the two that make sense for a command\n// line. A clone is left in place when the session ends; `closeRemote` removes it,\n// and the session calls that on `cd` and on exit, so nothing is orphaned in the\n// temp dir.\nexport async function openRepoOrClone(target: string, options: ScanOptions = {}) {\n  throwIfAborted(options.signal);\n  const onProgress = options.onProgress;\n  const raw = String(target || '').trim();\n  if (!isGitUrl(raw)) return openRepo(raw, options);\n\n  const url = assertGitUrl(raw);\n  if (onProgress) onProgress({ phase: 'clone', url });\n  const clone = await cloneRepo(url);\n  try {\n    const repo = await openRepo(clone.dir, options);\n    // The repo's own name is what a person recognizes; the temp path is kept so\n    // `about` can still print a path someone could go and look at.\n    return {\n      ...repo,\n      name: repoNameFromUrl(url) || repo.name,\n      gitUrl: url,\n      tempId: path.basename(clone.dir),\n      cloneDir: clone.dir,\n    };\n  } catch (err) {\n    // A clone that was never loaded has no session to clean it up later, so it\n    // has to go now or it is a temp directory nobody owns.\n    await removeClone(clone.dir);\n    throw err;\n  }\n}\n\n// The URL this repo should be asked about on GitHub, or null.\n//\n// A repo this session cloned knows its own URL. A repo someone was standing in\n// does not, and git does. Asking git here rather than in the `github` command\n// keeps the answer on the repo object, so every consumer gets it the same way.\nexport async function remoteUrlFor(repo) {\n  if (repo.gitUrl) return repo.gitUrl;\n  if (repo.remoteChecked) return null;\n  repo.remoteChecked = true;\n  const found = await gitRemoteOrigin(repo.root);\n  if (found.ok) repo.gitUrl = found.url;\n  return repo.gitUrl || null;\n}\n\n// Drop a temp clone, if this repo is one. Safe to call on a local repo: it\n// checks the shape of the directory rather than trusting a flag, so a bug\n// elsewhere cannot turn \"clean up\" into \"delete the folder the user is in\".\nexport async function closeRemote(repo) {\n  if (repo?.cloneDir) await removeClone(repo.cloneDir);\n}\n\n// Scan a directory and return the loaded repo, or throw an Error whose message\n// is safe to print straight to the user. `target` may be `~`, a relative path,\n// or anything `expandHome` understands; it defaults to the current directory.\nexport async function openRepo(target: string = '.', options: ScanOptions = {}) {\n  const root = expandHome(String(target || '.'));\n  const stat = await fs.stat(root).catch(() => null);\n  if (!stat) throw new Error('No such folder: ' + root);\n  if (!stat.isDirectory()) throw new Error('Not a folder: ' + root);\n\n  const source = nodeFileSource(root);\n  const scan = await scanRepo(source, options);\n  const manifest = await detectManifest(source);\n  const facts = computeFacts(scan, manifest);\n  const searchIndex = await buildSearchIndex(source, scan.files.map((f) => f.path));\n\n  // The layers projection is an input to patterns, not a parallel view of the\n  // same thing — `detectPatterns` reads the layer depths to place a file in the\n  // architecture. Compute once, share. The coupling matrix is the same kind of\n  // thing: a projection of `facts.folderEdges` that both the site and the\n  // terminal's heat grid read, so it is computed once here rather than per view.\n  const layers = computeLayers(scan, facts);\n\n  const loaded = {\n    root,\n    name: scan.name || path.basename(root),\n    scan,\n    facts,\n    manifest,\n    searchIndex,\n    layers,\n    coupling: couplingMatrix(scan, facts),\n    health: analyzeHealth(scan, facts),\n    patterns: detectPatterns(scan, facts, manifest, layers),\n    security: summarizeSecurity(scan),\n    stack: analyzeStack(manifest, scan.stats.languages || {}),\n    tour: buildTourStops(scan, facts),\n    languages: languageRows(scan),\n  };\n  return loaded as typeof loaded & { gitUrl?: string; cloneDir?: string; tempId?: string };\n}\n\n// LOC per language, biggest first, with the display label the site uses — so\n// `JavaScript` here and `JavaScript` there are the same string.\nfunction languageRows(scan) {\n  return Object.entries(scan.stats.languages || {})\n    .map(([id, loc]) => ({ id, loc, label: languageLabel(id) }))\n    .sort((a, b) => Number(b.loc) - Number(a.loc) || a.label.localeCompare(b.label));\n}\n\n// The one place a typed path becomes a real file. People type `logger.js`, not\n// `server/logger.js`, and a tool that says \"no such file\" for a file that is\n// right there is worse than no tool. So: exact, then folder, then suffix, then\n// basename, then a substring. Ambiguity is reported with the candidates rather\n// than guessed at — silently picking the wrong `index.js` is the failure mode\n// that makes people stop trusting a map.\nexport function resolveTarget(repo, typed) {\n  const raw = String(typed || '').trim().replace(/^\\.\\//, '');\n  if (!raw) return { error: 'Name a file or folder.' };\n\n  // `.` and `./` are the root, which is a real folder and a common thing to type\n  // (`tree .`, `explain .`). Without this they fell through to the substring\n  // match and offered eight unrelated files as \"did you mean\", which is worse\n  // than useless — it is actively misleading. The root folder's path is `''`.\n  if (raw === '.' || raw === './') return { folder: ROOT_FOLDER };\n\n  const files = repo.scan.files;\n  if (!repo.byPath) repo.byPath = new Map(files.map((f) => [f.path, f]));\n  if (repo.byPath.has(raw)) return { file: repo.byPath.get(raw) };\n\n  const folder = folderFor(repo, raw);\n  if (folder) return { folder };\n\n  const lower = raw.toLowerCase();\n  const suffix = files.filter((f) => f.path.endsWith('/' + raw));\n  if (suffix.length === 1) return { file: suffix[0] };\n  if (suffix.length > 1) return { error: 'Which one?', candidates: suffix.map((f) => f.path) };\n\n  const base = files.filter((f) => f.name.toLowerCase() === lower);\n  if (base.length === 1) return { file: base[0] };\n  if (base.length > 1) return { error: 'Which one?', candidates: base.map((f) => f.path) };\n\n  const loose = files.filter((f) => f.path.toLowerCase().includes(lower));\n  if (loose.length) {\n    loose.sort((a, b) => a.path.length - b.path.length);\n    return { error: 'No exact match. Did you mean:', candidates: loose.slice(0, 8).map((f) => f.path) };\n  }\n  return { error: 'Nothing in this repo matches \"' + raw + '\".' };\n}\n\n// The root folder is a real answer, not a sentinel: `tree .` and `explain .`\n// both need one, and it carries the same fields `resolveTarget` returns for any\n// other folder so the callers need no special case.\nconst ROOT_FOLDER = Object.freeze({ name: '', path: '', loc: 0, comment: 0, blank: 0, size: 0, langs: {} });\n\nfunction folderFor(repo, typed) {\n  const clean = typed.replace(/\\/+$/, '');\n  if (clean === '') return ROOT_FOLDER;\n  const exact = repo.scan.folders.find((d) => d.path === clean);\n  if (exact) return exact;\n  const matches = repo.scan.folders.filter((d) => d.path.endsWith('/' + clean) || d.name === clean);\n  return matches.length === 1 ? matches[0] : null;\n}\n\n// Read a file through the same containment check the HTTP route uses. A tool\n// whose job is showing you one repository has no business reading any path on\n// the machine, and going through `resolveInside` means there is no second,\n// looser door to get there.\nexport async function readRepoFile(repo, repoPath) {\n  const abs = resolveInside(repo.root, repoPath);\n  if (!abs) throw new Error('That path is outside the repository.');\n  return fs.readFile(abs, 'utf8');\n}\n\n// The website's search, verbatim: same TF-IDF ranking, same query language\n// (`ext:`, `path:`, `-exclude`, `\"phrases\"`, `/regex/`), same result shape. A\n// query that works in one surface works in the other, because it is the same\n// function.\nexport function searchRepo(repo, query, { limit = 12 }: Record<string, any> = {}) {\n  return searchDocuments(repo.searchIndex, query, { limit });\n}\n\n// A number a person typed, or nothing. `show f 1.5 2.5` used to print\n// `1.5–3 of 344`: `Number('1.5')` passed the `|| 1` fallback, the label\n// interpolated the fraction, and only `slice()` coerced it. A line range is\n// either a whole number of lines or it is a mistake, and a mistake gets a\n// message rather than a wrong heading.\nexport function lineNumber(value, fallback) {\n  if (value === undefined || value === null || value === '') return fallback;\n  const n = Number(value);\n  return Number.isInteger(n) && n > 0 ? n : null;\n}\n\nexport function explainRepoFile(repo, file) {\n  return explainFile(file.path, file, repo.facts);\n}\n\nexport function explainRepoFolder(repo, folder) {\n  return explainFolder(folder.path, repo.scan, repo.facts);\n}\n\nexport function explainRepoOverview(repo) {\n  return explainOverview(repo.scan, repo.facts, repo.manifest);\n}\n\n// Short facts about a file, in the order `docs.js` states them, so the terminal\n// and the generated docs never describe the same file differently.\nexport function fileFacts(repo, file) {\n  return {\n    role: roleOf(file.path, repo.facts),\n    loc: file.loc || 0,\n    complexity: file.complexity || 0,\n    fanIn: repo.facts.fanIn[file.path] || 0,\n    fanOut: repo.facts.fanOut[file.path] || 0,\n    inCycle: (repo.facts.inCycle || []).includes(file.path),\n    findings: (file.findings || []).length,\n  };\n}\n"]}

package/cli/explorer/views.d.ts

@@ -0,0 +1,19 @@
+export declare function overview(repo: any): string;
+export declare function tree(repo: any, { sub, depth, limit }?: Record<string, any>): string;
+export declare function find(repo: any, { query, limit }?: Record<string, any>): string;
+export declare function show(repo: any, { target, from, count }?: Record<string, any>): Promise<string>;
+export declare function targetError(found: any): string;
+export declare function deps(repo: any, { target, limit }?: Record<string, any>): string;
+export declare function explain(repo: any, { target }?: Record<string, any>): string;
+export declare function tour(repo: any): string;
+export declare function health(repo: any): string;
+export declare function hubs(repo: any, { limit }?: Record<string, any>): string;
+export declare function layers(repo: any, { limit }?: Record<string, any>): string;
+export declare function patterns(repo: any): string;
+export declare function stats(repo: any, { limit }?: Record<string, any>): string;
+export declare function security(repo: any, { limit }?: Record<string, any>): string;
+export declare function stack(repo: any, { limit }?: Record<string, any>): string;
+export declare function entry(repo: any): string;
+export declare function externals(repo: any): string;
+export declare function about(repo: any, version?: string): string;
+export declare function github(repo: any, result: any): string;