@samchon/graph 0.1.0

package/lib/operations/runOverview.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runOverview = runOverview;
+const path_1 = require("../utils/path");
+const isPublicApiNoisePath_1 = require("./isPublicApiNoisePath");
+const isSupportPath_1 = require("./isSupportPath");
+const common_1 = require("./common");
+/** Declaration kinds that make up a meaningful public API surface. */
+const API_KINDS = new Set([
+    "class",
+    "interface",
+    "function",
+    "type",
+    "enum",
+]);
+/**
+ * Project a compact, source-read-free architecture map: counts by kind, folder
+ * layering with export density, the highest-dependency symbols (ranked by real
+ * fan-in/out, excluding structural edges so nesting does not masquerade as
+ * dependency), and the export surface by file. Output is bounded so a model
+ * reads structure cheaply.
+ */
+function runOverview(graph, props) {
+    const aspect = props.aspect ?? "all";
+    const want = (a) => aspect === "all" || aspect === a;
+    return {
+        type: "overview",
+        project: graph.project,
+        languages: graph.languages,
+        counts: counts(graph),
+        ...(want("layers") ? { layers: layers(graph) } : {}),
+        ...(want("hotspots") ? { hotspots: hotspots(graph) } : {}),
+        ...(want("publicApi") ? { publicApi: publicApi(graph) } : {}),
+        ...(want("diagnostics") ? { diagnostics: graph.diagnostics.slice(0, 20) } : {}),
+        next: (0, common_1.resultNext)("answer", "Counts, layers, hotspots, and public API are sufficient for broad orientation."),
+        guide: (0, common_1.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."),
+    };
+}
+function counts(graph) {
+    const byKind = {};
+    const byLanguage = {};
+    let files = 0;
+    for (const node of graph.nodes) {
+        byKind[node.kind] = (byKind[node.kind] ?? 0) + 1;
+        byLanguage[node.language] = (byLanguage[node.language] ?? 0) + 1;
+        if (node.kind === "file")
+            files++;
+    }
+    return {
+        files,
+        nodes: graph.nodes.length,
+        edges: graph.edges.length,
+        byKind,
+        byLanguage,
+    };
+}
+/** Folder-level layering: how source and its export surface spread by directory. */
+function layers(graph) {
+    const byDir = new Map();
+    for (const node of graph.nodes) {
+        if (node.external ||
+            node.ignored ||
+            node.kind === "file" ||
+            (0, isSupportPath_1.isSupportPath)(node.file))
+            continue;
+        const dir = (0, path_1.dirname)(node.file);
+        let entry = byDir.get(dir);
+        if (entry === undefined) {
+            entry = { files: new Set(), exported: 0, languages: new Set() };
+            byDir.set(dir, entry);
+        }
+        entry.files.add(node.file);
+        entry.languages.add(node.language);
+        if (node.exported)
+            entry.exported++;
+    }
+    return [...byDir.entries()]
+        .map(([dir, entry]) => ({
+        dir,
+        files: entry.files.size,
+        exported: entry.exported,
+        languages: [...entry.languages],
+    }))
+        .sort((a, b) => b.files - a.files || b.exported - a.exported)
+        .slice(0, 16);
+}
+/**
+ * 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
+ * ranking reflects code dependency, not nesting.
+ */
+function hotspots(graph) {
+    const real = (id, side) => {
+        const edges = side === "in" ? graph.incoming(id) : graph.outgoing(id);
+        let n = 0;
+        for (const edge of edges)
+            if (!(0, common_1.isStructural)(edge.kind))
+                n++;
+        return n;
+    };
+    return graph.nodes
+        .filter((node) => !node.external &&
+        !node.ignored &&
+        node.kind !== "file" &&
+        !(0, isSupportPath_1.isSupportPath)(node.file))
+        .map((node) => ({
+        ...(0, common_1.summaryOf)(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, 12);
+}
+/**
+ * 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 instead of whichever file
+ * bundles the most aliases; test, typings, and generated files are dropped so
+ * they cannot crowd the real surface out.
+ */
+function publicApi(graph) {
+    const degree = (id) => {
+        let n = 0;
+        for (const edge of graph.outgoing(id))
+            if (!(0, common_1.isStructural)(edge.kind))
+                n++;
+        for (const edge of graph.incoming(id))
+            if (!(0, common_1.isStructural)(edge.kind))
+                n++;
+        return n;
+    };
+    return graph
+        .exported()
+        .filter((node) => API_KINDS.has(node.kind) && !(0, isPublicApiNoisePath_1.isPublicApiNoisePath)(node.file))
+        .map((node) => ({ node, degree: degree(node.id) }))
+        .sort((a, b) => b.degree - a.degree)
+        .slice(0, 16)
+        .map((ranked) => (0, common_1.summaryOf)(ranked.node));
+}
+//# sourceMappingURL=runOverview.js.map

package/lib/operations/runOverview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runOverview.js","sourceRoot":"","sources":["../../src/operations/runOverview.ts"],"names":[],"mappings":"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"}

package/lib/operations/runTour.d.ts

@@ -0,0 +1,8 @@
+import { GraphMemory } from "../model/GraphMemory";
+import { IGraphTour } from "../structures";
+/**
+ * Compose a repository-orientation/code-tour answer surface from existing graph
+ * operations. It returns selected symbols, flows, nearby edges, test anchors,
+ * and answer anchors without reading or embedding source bodies.
+ */
+export declare function runTour(graph: GraphMemory, props: IGraphTour.IRequest): IGraphTour;