@chappibunny/repolens 1.16.2 → 1.16.4

package/src/analyzers/import-parsers.js

@@ -164,6 +164,23 @@ function localNames(inner) {
   return names;
 }
 
+/** `{ a, b as c, type D }` → [{ imported: "a", local: "a" }, { imported: "b", local: "c" }]. */
+function braceBindings(inner) {
+  const out = [];
+  for (const part of splitTopCommas(inner)) {
+    const trimmed = part.trim().replace(/\s+/g, " ");
+    if (!trimmed || /^type\s+/.test(trimmed)) continue;
+    const asMatch = trimmed.match(/^([A-Za-z_$][\w$]*|"[^"]*"|'[^']*')\s+as\s+([A-Za-z_$][\w$]*)$/);
+    if (asMatch) {
+      out.push({ imported: asMatch[1].replace(/^["']|["']$/g, ""), local: asMatch[2] });
+      continue;
+    }
+    const id = trimmed.match(/^([A-Za-z_$][\w$]*)$/);
+    if (id) out.push({ imported: id[1], local: id[1] });
+  }
+  return out;
+}
+
 function readAlias(source, i) {
   let j = skipWs(source, i);
   const word = readWord(source, j);
@@ -206,7 +223,7 @@ function readFromClause(source, i) {
 }
 
 /**
- * @returns {{ specifier: string, typeOnly: boolean, names: string[] }[]}
+ * @returns {{ specifier: string, typeOnly: boolean, names: string[], kind: string, bindings: { imported: string, local: string|null }[] }[]}
  * `names` are the local bindings (`import { a as b }` → `b`) so callers can
  * count `b(` as a use of this import. Type-only imports still list names.
  */
@@ -215,7 +232,12 @@ export function extractJsImports(source) {
   const n = source.length;
   let i = 0;
 
-  function add(specifier, typeOnly, names = []) {
+  // `kind`: "import" (has local bindings), "reexport" (`export { a } from`),
+  // "reexport-all" (`export * from`), "side-effect" (`import "x"`), or "dynamic"
+  // (`import()` / `require()`). `bindings` pair each imported name with its local
+  // name (`*` for a namespace import, `default` for a default import); for a
+  // re-export, `local` is null.
+  function add(specifier, typeOnly, names = [], kind = "import", bindings = []) {
     if (typeof specifier !== "string") return;
     const locals = [];
     const seen = new Set();
@@ -224,7 +246,7 @@ export function extractJsImports(source) {
       seen.add(name);
       locals.push(name);
     }
-    imports.push({ specifier, typeOnly: Boolean(typeOnly), names: locals });
+    imports.push({ specifier, typeOnly: Boolean(typeOnly), names: locals, kind, bindings: typeOnly ? [] : bindings });
   }
 
   function parseRequire(at) {
@@ -234,7 +256,7 @@ export function extractJsImports(source) {
     if (!lit) return at;
     const after = skipWs(source, lit.next);
     if (source[after] !== ")") return at;
-    add(lit.value, false);
+    add(lit.value, false, [], "dynamic");
     return after + 1;
   }
 
@@ -245,7 +267,7 @@ export function extractJsImports(source) {
       if (!lit) return at;
       const after = skipWs(source, lit.next);
       if (source[after] !== ")") return at;
-      add(lit.value, false);
+      add(lit.value, false, [], "dynamic");
       return after + 1;
     }
     if (source[j] === ".") return at;
@@ -264,22 +286,26 @@ export function extractJsImports(source) {
       const clause = readFromClause(source, close + 1);
       if (!clause) return close + 1;
       const onlyTypes = typeOnly || braceIsTypeOnly(inner);
-      add(clause.value, onlyTypes, typeOnly ? [] : localNames(inner));
+      add(clause.value, onlyTypes, typeOnly ? [] : localNames(inner), "import", typeOnly ? [] : braceBindings(inner));
       return clause.next;
     }
 
     if (source[j] === "*" || isIdentStart(source[j]) || source[j] === "'" || source[j] === '"') {
       if (source[j] === "'" || source[j] === '"') {
         const lit = readJsString(source, j);
-        if (lit) add(lit.value, typeOnly);
+        if (lit) add(lit.value, typeOnly, [], "side-effect");
         return lit ? lit.next : j;
       }
       // default binding, namespace, or `name, { ... }`
       let sawValue = !typeOnly;
       const names = [];
+      const bindings = [];
       if (source[j] !== "*") {
         const binding = readWord(source, j);
-        if (binding.word && !typeOnly) names.push(binding.word);
+        if (binding.word && !typeOnly) {
+          names.push(binding.word);
+          bindings.push({ imported: "default", local: binding.word });
+        }
         j = skipWs(source, binding.next);
         if (source[j] === ",") {
           sawValue = !typeOnly;
@@ -288,7 +314,10 @@ export function extractJsImports(source) {
       } else {
         j = skipWs(source, j + 1);
         const alias = readAlias(source, j);
-        if (alias.name && !typeOnly) names.push(alias.name);
+        if (alias.name && !typeOnly) {
+          names.push(alias.name);
+          bindings.push({ imported: "*", local: alias.name });
+        }
         j = skipWs(source, alias.next);
       }
       if (source[j] === "{") {
@@ -298,13 +327,16 @@ export function extractJsImports(source) {
         const clause = readFromClause(source, close + 1);
         if (!clause) return close + 1;
         const onlyTypes = typeOnly || (!sawValue && braceIsTypeOnly(inner));
-        if (!onlyTypes) names.push(...localNames(inner));
-        add(clause.value, onlyTypes, names);
+        if (!onlyTypes) {
+          names.push(...localNames(inner));
+          bindings.push(...braceBindings(inner));
+        }
+        add(clause.value, onlyTypes, names, "import", bindings);
         return clause.next;
       }
       const clause = readFromClause(source, j);
       if (!clause) return at;
-      add(clause.value, typeOnly, typeOnly ? [] : names);
+      add(clause.value, typeOnly, typeOnly ? [] : names, "import", bindings);
       return clause.next;
     }
 
@@ -322,7 +354,7 @@ export function extractJsImports(source) {
     if (source[j] === "*") {
       const clause = readFromClause(source, j + 1);
       if (!clause) return at;
-      add(clause.value, typeOnly);
+      add(clause.value, typeOnly, [], "reexport-all");
       return clause.next;
     }
     if (source[j] === "{") {
@@ -331,7 +363,8 @@ export function extractJsImports(source) {
       const inner = source.slice(j + 1, close);
       const clause = readFromClause(source, close + 1);
       if (!clause) return close + 1;
-      add(clause.value, typeOnly || braceIsTypeOnly(inner));
+      const bindings = braceBindings(inner).map((item) => ({ imported: item.imported, local: null }));
+      add(clause.value, typeOnly || braceIsTypeOnly(inner), [], "reexport", bindings);
       return clause.next;
     }
     return at;

package/src/analyzers/language-coverage.js

@@ -0,0 +1,222 @@
+// Which scanned source files the import graph and code health can read.
+// RepoLens detects and scans many languages, but it builds import graphs and scores code
+// health only for JavaScript/TypeScript, Python, and Go. A C# or Java repository must not
+// get "no circular dependencies" or "health 100/100" from one incidental docs script.
+
+import path from "node:path";
+import { LANGUAGE_PROFILES } from "../core/languages.js";
+import { isNonProductPath } from "../utils/path-roles.js";
+
+export const ANALYZED_LANGUAGES_TEXT = "JavaScript/TypeScript, Python, and Go";
+
+const ANALYZED_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".py", ".pyw", ".go"]);
+
+// A code-health badge is one number for the whole repository. Below this share of
+// product source files in analyzed languages, `repolens badge` refuses to print it.
+// The docs still show the partial graph and scores with a coverage note.
+export const BADGE_MIN_SHARE = 0.1;
+
+// Vendored or third-party trees are not the repository's own code, in any language.
+export const VENDORED_DIRECTORIES = new Set([
+  "vendor", "vendored", "third_party", "third-party", "thirdparty", "3rdparty",
+  "deps", "external", "extern", "node_modules", "bower_components",
+]);
+
+const LABEL_BY_EXTENSION = new Map();
+LABEL_BY_EXTENSION.set(".vue", "Vue");
+LABEL_BY_EXTENSION.set(".svelte", "Svelte");
+const COMPANION_LABELS_LIST = ["Vue", "Svelte"];
+for (const profile of LANGUAGE_PROFILES) {
+  const label = profile.id === "java" ? "Java/Kotlin" : profile.id === "cpp" ? "C/C++" : profile.label;
+  for (const ext of profile.extensions) {
+    if (!LABEL_BY_EXTENSION.has(ext)) LABEL_BY_EXTENSION.set(ext, label);
+  }
+}
+
+function isDeclarationFile(file) {
+  return /\.d\.[cm]?ts$/.test(file);
+}
+
+export function isVendoredPath(file) {
+  const parts = String(file || "").replace(/\\/g, "/").toLowerCase().split("/");
+  parts.pop();
+  return parts.some((segment) => VENDORED_DIRECTORIES.has(segment));
+}
+
+/**
+ * Product source = not a test, docs, tooling, example, or vendored path.
+ *
+ * - "none": no source files in any known language
+ * - "full": every product source file is in an analyzed language
+ * - "partial": analyzed-language product code exists next to other languages; analysis
+ *   runs and every page says what it did not cover
+ * - "unsupported": no analyzed-language product code at all (only a docs script, a test
+ *   helper, or vendored files); graph and health are not built
+ *
+ * @param {string[]} files - scanned file paths
+ */
+export function computeLanguageCoverage(files) {
+  let analyzedFiles = 0;
+  let analyzedProductFiles = 0;
+  let unanalyzedFiles = 0;
+  let unanalyzedProductFiles = 0;
+  let vendoredFiles = 0;
+  let vendoredAnalyzedFiles = 0;
+  const byLabelProduct = new Map();
+  const byLabelAll = new Map();
+
+  for (const raw of files || []) {
+    const file = String(raw).replace(/\\/g, "/");
+    if (isDeclarationFile(file)) continue;
+    const ext = path.posix.extname(file).toLowerCase();
+    const analyzed = ANALYZED_EXTENSIONS.has(ext);
+    const label = analyzed ? null : LABEL_BY_EXTENSION.get(ext);
+    if (!analyzed && !label) continue;
+    if (isVendoredPath(file)) {
+      vendoredFiles += 1;
+      if (analyzed) vendoredAnalyzedFiles += 1;
+      continue;
+    }
+    const product = !isNonProductPath(file);
+    if (analyzed) {
+      analyzedFiles += 1;
+      if (product) analyzedProductFiles += 1;
+      continue;
+    }
+    unanalyzedFiles += 1;
+    byLabelAll.set(label, (byLabelAll.get(label) || 0) + 1);
+    if (product) {
+      unanalyzedProductFiles += 1;
+      byLabelProduct.set(label, (byLabelProduct.get(label) || 0) + 1);
+    }
+  }
+
+  // Product files decide everything; a tree with no product files at all (only tests,
+  // docs, or tooling) falls back to every non-vendored file.
+  const useProduct = analyzedProductFiles + unanalyzedProductFiles > 0;
+  const analyzedBase = useProduct ? analyzedProductFiles : analyzedFiles;
+  const unanalyzedBase = useProduct ? unanalyzedProductFiles : unanalyzedFiles;
+  const byLabel = useProduct ? byLabelProduct : byLabelAll;
+  const totalBase = analyzedBase + unanalyzedBase;
+  const share = totalBase > 0 ? analyzedBase / totalBase : null;
+  // Vue and Svelte components sit next to analyzed JavaScript/TypeScript. They are not
+  // analyzed, but they do not count against the badge share: a component library with
+  // two .ts files and forty .vue files keeps its (partial) score.
+  const companionBase = COMPANION_LABELS_LIST.reduce((sum, label) => sum + (byLabel.get(label) || 0), 0);
+  const badgeShare = totalBase - companionBase > 0 ? analyzedBase / (totalBase - companionBase) : null;
+
+  const unanalyzedLanguages = [...byLabel.entries()]
+    .map(([label, count]) => ({ label, files: count }))
+    .sort((a, b) => b.files - a.files || a.label.localeCompare(b.label));
+
+  let status;
+  if (totalBase === 0) status = "none";
+  else if (unanalyzedBase === 0) status = "full";
+  else if (analyzedBase === 0) status = "unsupported";
+  else status = "partial";
+
+  return {
+    status,
+    analyzedFiles,
+    analyzedProductFiles,
+    unanalyzedFiles,
+    unanalyzedProductFiles,
+    vendoredFiles,
+    vendoredAnalyzedFiles,
+    productBased: useProduct,
+    analyzedBase,
+    totalBase,
+    unanalyzedLanguages,
+    share,
+    companionBase,
+    badgeShare,
+  };
+}
+
+/** Whether one code-health number may stand for the repository. */
+export function badgeCoverageOk(coverage) {
+  if (!coverage) return true;
+  if (coverage.status === "full" || coverage.status === "none") return true;
+  if (coverage.status === "unsupported") return false;
+  const share = coverage.badgeShare ?? coverage.share ?? 0;
+  return share >= BADGE_MIN_SHARE;
+}
+
+/**
+ * Short qualifier for claims made from the graph ("no circular dependencies"), or "".
+ * Partial: " (analyzed files only: 50 of 650 product source files; C/C++ not analyzed)".
+ */
+export function coverageScope(coverage) {
+  if (!coverage || coverage.status !== "partial") return "";
+  return ` (analyzed files only: ${coverage.analyzedBase} of ${coverage.totalBase} ${coverage.productBased ? "product " : ""}source files; ${unanalyzedLanguageNames(coverage)} not analyzed)`;
+}
+
+/** "C# (780 files)" / "Java/Kotlin (247 files) and C (3 files)". */
+export function describeUnanalyzedLanguages(coverage, limit = 3) {
+  const list = (coverage?.unanalyzedLanguages || []).slice(0, limit)
+    .map(({ label, files }) => `${label} (${files} ${coverage?.productBased ? "product " : ""}file${files === 1 ? "" : "s"})`);
+  if (list.length === 0) return "";
+  if (list.length === 1) return list[0];
+  return `${list.slice(0, -1).join(", ")} and ${list[list.length - 1]}`;
+}
+
+/** Short language names only: "C#", "Java/Kotlin and Scala". */
+export function unanalyzedLanguageNames(coverage, limit = 3) {
+  const list = (coverage?.unanalyzedLanguages || []).slice(0, limit).map(({ label }) => label);
+  if (list.length <= 1) return list[0] || "";
+  return `${list.slice(0, -1).join(", ")} and ${list[list.length - 1]}`;
+}
+
+/**
+ * Files an analyzer should read. When the analyzed languages are only incidental
+ * (status "unsupported"), none: the graph or score would describe a docs script,
+ * not the repository.
+ */
+export function filesForAnalysis(files, coverage = computeLanguageCoverage(files)) {
+  if (coverage.status === "unsupported") return [];
+  return files;
+}
+
+function verbFor(coverage) {
+  return (coverage?.unanalyzedLanguages || []).length > 1 ? "are" : "is";
+}
+
+/**
+ * Markdown lines that say what a page did not analyze.
+ * `what` is "import analysis" or "code health".
+ * Returns [] for full coverage or when there is nothing to say.
+ */
+export function coverageNotice(coverage, what) {
+  if (!coverage) return [];
+  const langs = describeUnanalyzedLanguages(coverage);
+  if (coverage.status === "unsupported") {
+    const n = (coverage.analyzedFiles || 0) + (coverage.vendoredAnalyzedFiles || 0);
+    const incidental = n > 0
+      ? ` ${n === 1 ? "One file" : `${n} files`} in a supported language ${n === 1 ? "was" : "were"} found only in docs, tests, tooling, examples, or vendored directories, so ${n === 1 ? "it was" : "they were"} not ${what === "code health" ? "scored" : "graphed"} as if ${n === 1 ? "it were" : "they were"} the codebase.`
+      : "";
+    return [
+      `> ${langs} ${verbFor(coverage)} not supported for ${what} yet. RepoLens ${what === "code health" ? "scores" : "builds import graphs for"} ${ANALYZED_LANGUAGES_TEXT} only.`,
+      "",
+      `Modules and file structure for this repository are still documented in the other pages. This is a language limitation, not a problem with your \`scan.include\` patterns.${incidental}`,
+      "",
+    ];
+  }
+  if (coverage.status === "partial") {
+    const pct = coverage.share != null ? Math.round(coverage.share * 100) : null;
+    return [
+      `> **Partial coverage:** ${what} covers ${coverage.analyzedBase} of ${coverage.totalBase} ${coverage.productBased ? "product " : ""}source files${pct != null ? ` (${pct}%)` : ""}, the ${ANALYZED_LANGUAGES_TEXT} ones. ${langs} ${verbFor(coverage)} not analyzed, so results below say nothing about ${coverage.unanalyzedLanguages.length > 1 ? "those languages" : "that language"}.`,
+      "",
+    ];
+  }
+  return [];
+}
+
+/** One plain-text line for logs and the badge CLI. */
+export function coverageLine(coverage, what) {
+  if (!coverage || (coverage.status !== "unsupported" && coverage.status !== "partial")) return "";
+  const langs = describeUnanalyzedLanguages(coverage);
+  if (coverage.status === "unsupported") {
+    return `${langs} ${verbFor(coverage)} not supported for ${what} yet (${ANALYZED_LANGUAGES_TEXT} only).`;
+  }
+  return `${what} covers ${ANALYZED_LANGUAGES_TEXT} only; ${langs} ${verbFor(coverage)} not analyzed.`;
+}