codebase-onboarder 0.3.1 → 0.4.1

package/shared/analyzer/languages/csharp.js

@@ -1,19 +1,40 @@
 // C# analyzer
-import { blankComments, lineCounter, uniqueBy } from '../util.js';
+//
+// C# is namespace-rooted exactly as Java is package-rooted: a file's path is its
+// namespace spelled with slashes, under a project root. The difference that
+// matters is the import. Java's `import a.b.C;` names a *class*, so one path
+// answers it; C#'s `using A.B;` names a *namespace*, and the classes inside it
+// are not knowable from the import string. So a namespace import resolves to a
+// directory and the scanner links to every file in it — the same shape Go uses
+// for packages.
+import { blankComments, lineCounter } from '../util.js';
 
 export const extensions = ['.cs'];
 
+const NAMESPACE_RE = /^\s*namespace\s+([A-Za-z0-9_.]+)\s*[;{]/m;
+
 export function analyze(source, path) {
   const clean = blankComments(source);
   const lineAt = lineCounter(clean);
 
+  // The file's own namespace. Captured first because every import is resolved
+  // relative to it — this declaration is the only place the root is written down.
+  // Block-scoped namespaces (`namespace A.B { }`) are the norm, and the regex
+  // accepts both the `;` and `{` forms.
+  const namespace = (clean.match(NAMESPACE_RE) || [])[1] || '';
+
   const imports = [];
-  for (const m of clean.matchAll(/\busing\s+([a-zA-Z0-9_.]+)\s*;/g)) {
-    imports.push({ spec: m[1], line: lineAt(m.index) });
+  // `using static A.B.C;` names a type (and optionally a member of it); plain
+  // `using A.B;` names a namespace. The distinction decides whether we look for
+  // a file or a directory.
+  for (const m of clean.matchAll(/\busing\s+(static\s+)?([A-Za-z0-9_.]+)\s*;/g)) {
+    imports.push({ spec: m[2], static: !!m[1], namespace, line: lineAt(m.index) });
   }
+  // `using X = Y;` aliases and global usings are out of scope; a spec that fails
+  // to resolve is reported as unresolved rather than guessed at.
 
   const classes = [];
-  for (const m of clean.matchAll(/(\[[^\]]+\]\s*)*\b(?:public\s+|private\s+|protected\s+|internal\s+)*(?:abstract\s+|sealed\s+)?(?:class|interface|struct|record|enum)\s+([a-zA-Z0-9_]+)/g)) {
+  for (const m of clean.matchAll(/(\[[^\]]+\]\s*)*\b(?:public\s+|private\s+|protected\s+|internal\s+)*(?:abstract\s+|sealed\s+|static\s+|partial\s+)*(?:class|interface|struct|record|enum)\s+([a-zA-Z0-9_]+)/g)) {
     const attributes = [];
     if (m[1]) {
       for (const am of m[1].matchAll(/\[([A-Za-z0-9_]+)/g)) {
@@ -30,10 +51,64 @@ export function analyze(source, path) {
     exports: classes.map(c => ({ name: c.name, kind: 'class' })),
     functions: [],
     classes,
-    hasMain
+    hasMain,
+    namespace,
   };
 }
 
-export function resolveImport(spec, fromPath, has, context = {}) {
+// A C# `using` is resolved by *path suffix*, not by a root prefix. See
+// `resolveImport` below for why that distinction matters — it is the whole
+// difference between C# and Java, and getting it backwards drops every import.
+//
+// `sourceRootFor` is kept and exported because it is the answer for the layouts
+// where a project *does* mirror the full namespace (`Acme/Services/User.cs`).
+// It is a fallback, not the main path.
+export function sourceRootFor(fromPath, namespace) {
+  if (!namespace) return null;
+  const suffix = namespace.replace(/\./g, '/');
+  const normalized = String(fromPath).replace(/\\/g, '/');
+  const nested = normalized.lastIndexOf('/' + suffix + '/');
+  if (nested >= 0) return normalized.slice(0, nested + 1);
+  if (normalized === suffix || normalized.startsWith(suffix + '/')) return '';
+  return null;
+}
+
+export function resolveImport(spec, fromPath, has, context = {}, meta = {}) {
+  const parts = spec.split('.').filter(Boolean);
+  const findDir = (segments) => (segments.length ? context.findDirEndingWith?.(segments.join('/')) : null);
+  if (!parts.length) return { unresolved: spec };
+
+  // A C# `using` is ambiguous from the string alone: in `using Acme.Models;`,
+  // `Models` might be a namespace (link its directory) or a type (link the
+  // file). Both readings are tried, most specific first.
+  //
+  // The other half of the puzzle is that C# resolves by *path suffix*, not by a
+  // root prefix the way Java does. `namespace Acme.Services` conventionally
+  // lives in `src/Services/`: the folders mirror the namespace, but the leading
+  // `Acme` — the project or company root — is not a directory. So the namespace
+  // segments are matched against the *tail* of a real directory path, which is
+  // what `findDirEndingWith` answers. Stripping the whole namespace instead, the
+  // Java approach, matches nothing here and silently drops every import.
+
+  // Reading 1: the last segment is a type. Find the directory holding its
+  // namespace, then the file named after it.
+  const namespaceParts = parts.slice(0, -1);
+  for (let take = namespaceParts.length; take > 0; take -= 1) {
+    const dir = findDir(namespaceParts.slice(namespaceParts.length - take));
+    if (!dir) continue;
+    const exact = dir + '/' + parts[parts.length - 1] + '.cs';
+    if (has(exact)) return { path: exact };
+    if (meta.static) return { unresolved: spec }; // `using static A.B.C;` is always a type
+  }
+
+  // Reading 2: the whole spec is a namespace, so link its directory.
+  for (let take = parts.length; take > 0; take -= 1) {
+    const dir = findDir(parts.slice(parts.length - take));
+    if (dir) return { packageDir: dir };
+  }
+
+  // The BCL (`System`, `System.Collections.Generic`) and every NuGet package land
+  // here. Staying unresolved is the honest answer: a file we invent would be a
+  // node in the graph that does not exist.
   return { unresolved: spec };
 }

package/shared/analyzer/languages/java.js

@@ -1,15 +1,33 @@
 // Java analyzer
+//
+// Java is package-rooted: a source file's path *is* its package spelled with
+// slashes, under a source root (`src/main/java` in Maven, `src/main/java` in
+// Gradle, or a plain directory in a one-off project). That single fact is what
+// turns an import into a file, and it is why Java can have a real import graph
+// at all — the C# analyzer sitting next to this one cannot, because a C# file
+// carries no path↔namespace correspondence to invert.
 import { blankComments, lineCounter, uniqueBy } from '../util.js';
 
 export const extensions = ['.java'];
 
+const PACKAGE_RE = /^[ \t]*package\s+([a-zA-Z0-9_.]+)\s*;/m;
+
 export function analyze(source, path) {
   const clean = blankComments(source);
   const lineAt = lineCounter(clean);
 
+  // The file's own package, captured first because every import in the file is
+  // resolved relative to it: `resolveImport` has to know where the source root
+  // ends and the package begins, and this declaration is the only place that is
+  // written down. A file with no `package` is in the default package, which is a
+  // real (if unfashionable) case rather than an error.
+  const packageName = (clean.match(PACKAGE_RE) || [])[1] || '';
+
   const imports = [];
   for (const m of clean.matchAll(/\bimport\s+(static\s+)?([a-zA-Z0-9_.]+)/g)) {
-    imports.push({ spec: m[2], static: !!m[1], line: lineAt(m.index) });
+    // `packageName` rides along on the import so the resolver can do its job
+    // from the import object alone — which is the fifth argument scan.js passes.
+    imports.push({ spec: m[2], static: !!m[1], packageName, line: lineAt(m.index) });
   }
 
   const classes = [];
@@ -26,14 +44,71 @@ export function analyze(source, path) {
   const hasMain = /public\s+static\s+void\s+main\s*\(/.test(clean);
 
   return {
-    imports,
+    imports: uniqueBy(imports, (i) => i.spec + (i.static ? ' static' : '')),
     exports: classes.map(c => ({ name: c.name, kind: 'class' })),
     functions: [],
     classes,
-    hasMain
+    hasMain,
+    packageName,
   };
 }
 
-export function resolveImport(spec, fromPath, has, context = {}) {
+// The source root: the part of this file's path that sits *above* its package.
+// `src/main/java/com/example/app/AppController.java` with package
+// `com.example.app` gives `src/main/java/` — and that prefix is exactly what
+// turns `com.example.model.User` into a path worth looking for.
+//
+// Returns '' when the file declares no package: with nothing to strip there is
+// no way to know where the root is, and guessing would mean inventing files.
+export function sourceRootFor(fromPath, packageName) {
+  if (!packageName) return null;
+  const suffix = packageName.replace(/\./g, '/');
+  const normalized = String(fromPath).replace(/\\/g, '/');
+  // Two shapes, and both are real. With a source root the package segment is
+  // preceded by a directory (`src/main/java/com/acme/…`); in a project with no
+  // root at all the path *begins* with the package (`com/acme/…`) and the root
+  // is the empty string. That is not the same as "no root" — it is the repo top,
+  // which is a perfectly good answer.
+  const nested = normalized.lastIndexOf('/' + suffix + '/');
+  if (nested >= 0) return normalized.slice(0, nested + 1);
+  if (normalized === suffix || normalized.startsWith(suffix + '/')) return '';
+  // The package is not in the path at all (a generated source dir, a file moved
+  // out of its package). No root can be inferred, and inventing one would put a
+  // node in the graph that does not exist.
+  return null;
+}
+
+// Candidate file paths for an import, longest spec first.
+//
+// The longest is the obvious one (`model.User` → `…/model/User.java`). The
+// shorter ones exist because Java lets you import a *nested* type
+// (`com.example.Outer.Inner` lives in `Outer.java`) and a *static member*
+// (`com.example.Constants.MAX` lives in `Constants.java`). Rather than
+// special-case the syntax, walk back a segment at a time and take the first
+// that exists. The static flag only decides where the walk starts, so the
+// common case does not pay for the rare one.
+function candidatesFor(spec, root, { static: isStatic = false } = {}) {
+  const parts = spec.split('.').filter(Boolean);
+  const out = [];
+  const start = isStatic && parts.length > 1 ? 1 : 0;
+  for (let end = parts.length; end > start; end -= 1) {
+    out.push(root + parts.slice(0, end).join('/') + '.java');
+  }
+  return out;
+}
+
+export function resolveImport(spec, fromPath, has, context = {}, meta = {}) {
+  const root = sourceRootFor(fromPath, meta.packageName);
+  // `null` means "no root could be inferred". `''` means the root is the repo
+  // top, which is the correct answer for a project laid out with no source root
+  // at all — treating that as "no root" silently dropped every flat-layout import.
+  if (root === null) return { unresolved: spec };
+  for (const candidate of candidatesFor(spec, root, { static: meta.static })) {
+    if (has(candidate)) return { path: candidate };
+  }
+  // Nothing in the repo matched. The JDK and every third-party library land
+  // here, and staying `unresolved` is the honest answer: inventing a file would
+  // put a node in the graph that does not exist. scan.js reports these by name
+  // so the reader knows exactly what the analyzer could not place.
   return { unresolved: spec };
 }

package/shared/analyzer/languages/rust.js

@@ -1,4 +1,18 @@
 // Rust analyzer
+//
+// Rust has no `import` in the Java sense: a crate is a module tree, and `use`
+// names a path *into* that tree. The mapping is still real, though, and it is
+// what gives a Rust repo a graph:
+//
+//   crate root      src/lib.rs, src/main.rs, or crates/<name>/src/lib.rs
+//   module `a`      src/a.rs  or  src/a/mod.rs
+//   `crate::a::T`   T is declared in src/a.rs (or src/a/mod.rs)
+//
+// So a `use` resolves to the *module file* that owns the item, and the leading
+// `crate` is just the crate root. `self::` and `super::` are relative to the
+// current file's module directory. Anything outside the crate — `std`, a
+// dependency from Cargo.toml — stays unresolved, because inventing a file would
+// be a node in the graph that does not exist.
 import { blankComments, lineCounter, uniqueBy } from '../util.js';
 
 export const extensions = ['.rs'];
@@ -8,7 +22,9 @@ export function analyze(source, path) {
   const lineAt = lineCounter(clean);
 
   const imports = [];
-  for (const m of clean.matchAll(/\b(?:use|mod)\s+([a-zA-Z0-9_:]+)/g)) {
+  // `use foo::bar;` and `mod foo;` are both dependencies on a file, and both are
+  // worth an edge. `pub use` is a re-export — still a real dependency.
+  for (const m of clean.matchAll(/\b(?:pub\s+)?(?:use|mod)\s+([a-zA-Z0-9_:]+)/g)) {
     imports.push({ spec: m[1], line: lineAt(m.index) });
   }
 
@@ -37,6 +53,92 @@ export function analyze(source, path) {
   };
 }
 
-export function resolveImport(spec, fromPath, has, context = {}) {
+const dirOfPath = (p) => {
+  const at = String(p).lastIndexOf('/');
+  return at < 0 ? '' : String(p).slice(0, at + 1);
+};
+
+// The crate root: the `src/` directory, wherever it sits. `src/lib.rs` → `src/`;
+// `crates/foo/src/main.rs` → `crates/foo/src/`. A crate with no `src/` (a flat
+// `lib.rs` in the repo root) is rooted at that file's own directory, which is the
+// same rule with one fewer component to find.
+export function crateRootFor(fromPath) {
+  const normalized = String(fromPath).replace(/\\/g, '/');
+  const segments = normalized.split('/');
+  const at = segments.lastIndexOf('src');
+  if (at < 0) return dirOfPath(normalized);
+  return segments.slice(0, at + 1).join('/') + '/';
+}
+
+// The directory that holds the *children* of the module this file defines.
+//
+// This is not simply the dirname, and getting it wrong breaks every `self::`.
+//   src/lib.rs       → `src/`        the crate root's children sit in src/
+//   src/a/b.rs       → `src/a/b/`    the module is `a::b`, so `self::x` is a/b/x.rs
+//   src/a/b/mod.rs   → `src/a/b/`    the same module, declared the directory way
+//
+// The lib/main special case is the one that is easy to miss: they are named
+// after the crate, not after their module, so stripping `.rs` from `src/lib.rs`
+// would invent a module called `lib`.
+export function moduleDirFor(fromPath) {
+  const normalized = String(fromPath).replace(/\\/g, '/');
+  const dir = dirOfPath(normalized);
+  const name = normalized.slice(dir.length);
+  if (name === 'mod.rs' || name === 'lib.rs' || name === 'main.rs') return dir;
+  return normalized.replace(/\.rs$/, '') + '/';
+}
+
+// A module named by a path is either `path.rs` or `path/mod.rs`. Both are
+// idiomatic Rust, so both are tried and the first that exists wins.
+function moduleCandidates(path) {
+  return [path + '.rs', path + '/mod.rs'];
+}
+
+export function resolveImport(spec, fromPath, has, context = {}, meta = {}) {
+  const from = String(fromPath).replace(/\\/g, '/');
+  const raw = String(spec);
+  // `::foo::Bar` is a 2018 absolute path — another crate, not this one.
+  if (raw.startsWith('::')) return { unresolved: spec };
+  const segments = raw.split('::').filter(Boolean);
+  if (!segments.length) return { unresolved: spec };
+
+  // Where the path starts. `crate::` is the crate root; `self::` and a bare
+  // `mod foo;` are the current file's own module; `super::` is one level up.
+  const head = segments[0];
+  let base;
+  let rest;
+  if (head === 'crate') {
+    base = crateRootFor(from);
+    rest = segments.slice(1);
+  } else if (head === 'super') {
+    // `dirOfPath` already ends in a separator, so do not add another — `src/a//`
+    // never matches a real path, and the miss would be silent.
+    base = dirOfPath(moduleDirFor(from).replace(/\/$/, ''));
+    rest = segments.slice(1);
+  } else if (head === 'self') {
+    base = moduleDirFor(from);
+    rest = segments.slice(1);
+  } else {
+    // A bare `mod foo;` declares a module beside the current one. A bare
+    // `use foo::Bar;` means an *external crate* in Rust 2018, so it will not be
+    // found here and stays unresolved — which is the right answer for
+    // `serde::Serialize` and every other dependency.
+    base = moduleDirFor(from);
+    rest = segments;
+  }
+  if (!rest.length) return { unresolved: spec };
+
+  // `crate::a::b::T` means T is declared *in* the module `a::b`, so the answer is
+  // the module file for the longest prefix that exists. Trying the deepest path
+  // first costs one lookup and covers the flat `mod a;` → `a.rs` case.
+  for (let end = rest.length; end > 0; end -= 1) {
+    const candidate = base + rest.slice(0, end).join('/');
+    for (const file of moduleCandidates(candidate)) {
+      if (has(file)) return { path: file };
+    }
+  }
+
+  // `std`, `serde`, anything from Cargo.toml: outside this crate. Unresolved is
+  // the honest answer, and scan.js reports these by name.
   return { unresolved: spec };
 }

package/shared/analyzer/scan.js

@@ -126,8 +126,31 @@ export async function scanRepo(source, options = {}) {
   }
   const findByName = (n) => nameIndex.get(n) || null;
 
+  // Find a directory whose path *ends with* a run of segments. This is what C#
+  // needs and Java does not: a C# file's folder mirrors the namespace, but the
+  // root namespace (the company or project name) is normally not a directory,
+  // so `namespace Acme.Services` lives in `src/Services/`. Matching on a path
+  // suffix is the only thing that finds it — stripping the whole namespace, the
+  // Java approach, matches nothing and silently drops every import.
+  //
+  // Keyed by the last three segments, which is enough to tell
+  // `Acme/Models/Entities` apart from a bare `Entities` elsewhere while staying
+  // O(1) per lookup. A collision at the shortest key keeps the first match, and
+  // callers query longest-first, so the most specific answer is tried first.
+  const dirByTail = new Map();
+  for (const d of dirSet) {
+    if (!d) continue;
+    const segments = d.split('/');
+    for (let take = 1; take <= 3 && take <= segments.length; take += 1) {
+      const key = segments.slice(segments.length - take).join('/');
+      if (!dirByTail.has(key)) dirByTail.set(key, d);
+    }
+  }
+  const findDirEndingWith = (suffix) => (suffix ? dirByTail.get(suffix) || null : null);
+
   const context = {
     hasDir,
+    findDirEndingWith,
     findByName,
     modulePath: await readModulePath(source),
     tsPaths: await readTsConfigPaths(source),
@@ -212,15 +235,20 @@ export async function scanRepo(source, options = {}) {
   const tally = { total: 0, internal: 0, external: 0, unresolved: 0 };
   const unresolvedSpecs = new Map(); // spec -> { count, from }
 
-  // Go resolves an import to a *directory*, and every .go file in it is a
+  // A resolver may answer with a *directory* instead of a file: Go's import is a
+  // package, and a C# `using Acme.Models;` names a namespace whose classes we
+  // cannot know from the import alone. Every file in that directory is a
   // target. Indexed once here rather than scanned per import — a Go repo with
   // 1,000 files and 8,000 imports was doing eight million comparisons for it.
-  const goFilesByDir = new Map();
+  //
+  // Language-neutral on purpose: this used to be `goFilesByDir`, built only from
+  // Go files, which meant no other language could use the mechanism that already
+  // existed for exactly this problem.
+  const filesByDir = new Map();
   for (const f of files) {
-    if (f.lang !== 'go') continue;
-    const bucket = goFilesByDir.get(f.dir);
+    const bucket = filesByDir.get(f.dir);
     if (bucket) bucket.push(f.path);
-    else goFilesByDir.set(f.dir, [f.path]);
+    else filesByDir.set(f.dir, [f.path]);
   }
 
   for (const file of files) {
@@ -233,7 +261,10 @@ export async function scanRepo(source, options = {}) {
         addEdge(edges, edgeKeys, file.path, res.path, 'imports', imp.symbols);
       } else if (res.packageDir) {
         tally.internal++;
-        for (const target of goFilesByDir.get(res.packageDir) || []) {
+        // A directory import means "everything in there". addEdge de-duplicates,
+        // so a package with fifty files yields fifty honest edges rather than
+        // one edge standing in for all of them.
+        for (const target of filesByDir.get(res.packageDir) || []) {
           addEdge(edges, edgeKeys, file.path, target, 'imports', imp.symbols);
         }
       } else if (res.external) {