@ttsc/graph 0.16.5 → 0.16.7

package/src/server/runOverview.ts

@@ -1,5 +1,8 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { ITtscGraphNode } from "../structures/ITtscGraphNode";
 import { ITtscGraphOverview } from "../structures/ITtscGraphOverview";
+import { isPublicApiNoisePath, isSupportPath } from "./pathPolicy";
+import { resultGuide, resultNext } from "./resultGuide";
 
 /** Edges that express nesting/packaging, not code dependency. */
 const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
@@ -13,10 +16,10 @@ const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
  */
 export function runOverview(
   graph: TtscGraphMemory,
-  props: ITtscGraphOverview.IProps,
+  props: ITtscGraphOverview.IRequest,
 ): ITtscGraphOverview {
   const aspect = props.aspect ?? "all";
-  const want = (a: ITtscGraphOverview.IProps["aspect"]): boolean =>
+  const want = (a: ITtscGraphOverview.IRequest["aspect"]): boolean =>
     aspect === "all" || aspect === a;
 
   const byKind: Record<string, number> = {};
@@ -27,6 +30,7 @@ export function runOverview(
   }
 
   const result: ITtscGraphOverview = {
+    type: "overview",
     project: graph.project,
     counts: {
       files,
@@ -34,6 +38,13 @@ export function runOverview(
       edges: graph.edges.length,
       byKind,
     },
+    next: resultNext(
+      "answer",
+      "Counts, layers, hotspots, and public API are sufficient for broad orientation.",
+    ),
+    guide: resultGuide(
+      "Use counts, layers, hotspots, and public API as a broad orientation map. Do not expand it into file reads unless the user needs exact source body text.",
+    ),
   };
   if (want("layers")) result.layers = layers(graph);
   if (want("hotspots")) result.hotspots = hotspots(graph);
@@ -45,7 +56,13 @@ export function runOverview(
 function layers(graph: TtscGraphMemory): ITtscGraphOverview.ILayer[] {
   const byDir = new Map<string, { files: Set<string>; exported: number }>();
   for (const node of graph.nodes) {
-    if (node.external || node.kind === "file") continue;
+    if (
+      node.external ||
+      node.ignored ||
+      node.kind === "file" ||
+      isSupportPath(node.file)
+    )
+      continue;
     const dir = dirname(node.file);
     let entry = byDir.get(dir);
     if (!entry) {
@@ -62,12 +79,12 @@ function layers(graph: TtscGraphMemory): ITtscGraphOverview.ILayer[] {
       exported: entry.exported,
     }))
     .sort((a, b) => b.files - a.files)
-    .slice(0, 16);
+    .slice(0, 10);
 }
 
 /**
  * The symbols at the center of the dependency graph, ranked by real fan-in and
- * fan-out — structural `contains`/`exports`/`imports` edges are excluded so the
+ * fan-out. Structural `contains`/`exports`/`imports` edges are excluded so the
  * ranking reflects code dependency, not nesting.
  */
 function hotspots(graph: TtscGraphMemory): ITtscGraphOverview.IHotspot[] {
@@ -78,18 +95,21 @@ function hotspots(graph: TtscGraphMemory): ITtscGraphOverview.IHotspot[] {
     return n;
   };
   return graph.nodes
-    .filter((node) => !node.external && node.kind !== "file")
+    .filter(
+      (node) =>
+        !node.external &&
+        !node.ignored &&
+        node.kind !== "file" &&
+        !isSupportPath(node.file),
+    )
     .map((node) => ({
-      id: node.id,
-      name: node.qualifiedName ?? node.name,
-      kind: node.kind,
-      file: node.file,
+      ...nodeOf(node),
       fanIn: real(node.id, "in"),
       fanOut: real(node.id, "out"),
     }))
     .filter((h) => h.fanIn + h.fanOut > 0)
     .sort((a, b) => b.fanIn + b.fanOut - (a.fanIn + a.fanOut))
-    .slice(0, 15);
+    .slice(0, 10);
 }
 
 /** Declaration kinds that make up a meaningful public API surface. */
@@ -102,12 +122,13 @@ const API_KINDS = new Set<string>([
 ]);
 
 /**
- * The exported API surface: the exported symbols a consumer of the project would
- * use, ranked by how depended-on each is (real fan-in/out, structural edges
- * excluded). Ranking by dependency rather than by which file declares the most
- * exports surfaces the load-bearing types (a DataSource, a SelectQueryBuilder)
- * instead of whichever file bundles the most type aliases; test, typings, and
- * generated files are dropped so they cannot crowd the real surface out.
+ * The exported API surface: the exported symbols a consumer of the project
+ * would use, ranked by how depended-on each is (real fan-in/out, structural
+ * edges excluded). Ranking by dependency rather than by which file declares the
+ * most exports surfaces the load-bearing types (a DataSource, a
+ * SelectQueryBuilder) instead of whichever file bundles the most type aliases;
+ * test, typings, and generated files are dropped so they cannot crowd the real
+ * surface out.
  */
 function publicApi(graph: TtscGraphMemory): ITtscGraphOverview.IPublicApi[] {
   const degree = (id: string): number => {
@@ -122,29 +143,22 @@ function publicApi(graph: TtscGraphMemory): ITtscGraphOverview.IPublicApi[] {
     .exported()
     .filter((node) => API_KINDS.has(node.kind) && !isNoiseFile(node.file))
     .map((node) => ({
-      name: node.qualifiedName ?? node.name,
-      kind: node.kind,
-      file: node.file,
+      node: nodeOf(node),
       degree: degree(node.id),
     }))
     .sort((a, b) => b.degree - a.degree)
-    .slice(0, 30)
-    .map(({ name, kind, file }) => ({ name, kind, file }));
+    .slice(0, 15)
+    .map((ranked) => ranked.node);
 }
 
 /**
  * A file whose exports are noise for an architecture overview: a test, a
- * dependency's bundled `.d.ts`/typings, or generated output. The conventions are
- * universal (a `test`/`spec` path, a `typings` file), so excluding them is not
- * framework-specific — it keeps the API surface to authored, used code.
+ * dependency's bundled `.d.ts`/typings, or generated output. The conventions
+ * are universal (a `test`/`spec` path, a `typings` file), so excluding them is
+ * not framework-specific; it keeps the API surface to authored, used code.
  */
 function isNoiseFile(file: string): boolean {
-  return (
-    /(^|\/)(test|tests|__tests__|spec|sample|samples)\//.test(file) ||
-    /\.(test|spec)\.[cm]?tsx?$/.test(file) ||
-    /(^|\/|\.)typings\.[cm]?ts$/.test(file) ||
-    /\.d\.[cm]?ts$/.test(file)
-  );
+  return isPublicApiNoisePath(file);
 }
 
 /** The parent directory of a project-relative path (`.` at the root). */
@@ -152,3 +166,17 @@ function dirname(file: string): string {
   const slash = file.lastIndexOf("/");
   return slash >= 0 ? file.slice(0, slash) : ".";
 }
+
+/** Stable symbol coordinate shared by overview facets. */
+function nodeOf(node: ITtscGraphNode): ITtscGraphOverview.INode {
+  const out: ITtscGraphOverview.INode = {
+    id: node.id,
+    name: node.qualifiedName ?? node.name,
+    kind: node.kind,
+    file: node.file,
+  };
+  if (node.evidence?.startLine !== undefined) {
+    out.line = node.evidence.startLine;
+  }
+  return out;
+}