@massa-ai/core 1.2.1

package/dist/services/symbol/architecture.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Architecture Intelligence — P4-T4 (D4)
+ *
+ * Pure functions that derive architectural signal from the file-import graph
+ * and symbol definitions: packages, entry points, routes, hotspots, and layers.
+ * Pairs with `communities.ts` (community detection) and is consumed by
+ * `getProjectMap` to enrich the project-map response (additive — never mutates
+ * existing fields).
+ *
+ * Heuristics ported (rewritten fresh) from codebase-memory-mcp's
+ * `get_architecture` aspects, adapted to massa-ai's symbol_imports / symbol_references
+ * model instead of a labeled property graph.
+ */
+import type { Community } from "./communities.js";
+export interface PackageInfo {
+    /** Common root directory or package marker label. */
+    name: string;
+    /** File paths belonging to this package. */
+    files: string[];
+    fileCount: number;
+    /** Distinct packages this one imports (fan-out). */
+    fanOut: number;
+    /** Distinct packages importing this one (fan-in). */
+    fanIn: number;
+}
+export interface EntryPoint {
+    file: string;
+    /** In-degree (number of distinct internal importers). */
+    inDegree: number;
+    /** Out-degree (number of distinct internal imports this file makes). */
+    outDegree: number;
+    /** Why this file was flagged as an entry-point candidate. */
+    reason: string;
+}
+export interface RouteInfo {
+    /** Route path string (from http_call edge metadata or definition name). */
+    path: string;
+    /** HTTP method when known. */
+    method?: string;
+    /** File where the route/HTTP call originates. */
+    file?: string;
+    /** Symbol name or target FQN bound to the route. */
+    handler?: string;
+}
+export interface HotspotInfo {
+    file: string;
+    /** Centrality (PageRank) score when available, else undefined. */
+    centrality?: number;
+    /** In-degree (number of distinct internal importers). */
+    inDegree: number;
+    /** Symbol count in the file when available. */
+    symbolCount?: number;
+}
+export interface LayerInfo {
+    /** Layer label: entry | api | core | service | leaf | unknown. */
+    layer: "entry" | "api" | "core" | "service" | "leaf" | "unknown";
+    /** Common-path-prefix or community label identifying the layer. */
+    name: string;
+    fileCount: number;
+    /** One-line rationale. */
+    reason: string;
+}
+export interface CommunityInfo {
+    /** Stable community id. */
+    id: number;
+    /** Representative label (common path prefix or most-central file). */
+    label: string;
+    /** Number of files in the community. */
+    size: number;
+    /** Internal / (internal + boundary) edge-weight ratio (0..1). */
+    cohesion: number;
+    /** Top files by degree within the community (≤5). */
+    topFiles: string[];
+}
+export interface ArchitectureMap {
+    packages: PackageInfo[];
+    entryPoints: EntryPoint[];
+    routes: RouteInfo[];
+    hotspots: HotspotInfo[];
+    communities: CommunityInfo[];
+    layers: LayerInfo[];
+    /**
+     * Opt-in `cycles` aspect (Wave 5 FR-02 / N2). Present only when the caller
+     * passed `aspects: ["cycles"]` to {@link computeArchitectureMap}. Each entry
+     * is a file-level strongly connected component of size >1 (or a singleton
+     * self-loop) over the CALL-edge graph.
+     */
+    cycles?: CycleInfo[];
+    /** `true` when the CALL-edge input exceeded the budget and was truncated. */
+    cycles_truncated?: boolean;
+}
+/**
+ * One cycle (strongly connected component) surfaced by the `cycles` aspect.
+ *
+ * `id` is a stable synthetic id derived from the sorted node list so snapshot
+ * fingerprinting and diffing are reproducible. `edgeCount` is the number of
+ * intra-SCC CALL edges (the cost of breaking the cycle).
+ */
+export interface CycleInfo {
+    id: string;
+    nodes: string[];
+    edgeCount: number;
+}
+/** Internal import edge between two files (both endpoints known, non-external). */
+export interface InternalImport {
+    fromFile: string;
+    toFile: string;
+}
+/**
+ * Directed CALL edge between two files (Wave 5 — FR-02 / N2).
+ *
+ * `from` = caller's file (relative path); `to` = callee's file (relative path,
+ * stripped from the callee's structural FQN `path/to/file.ts#Name`). The Tarjan
+ * SCC detector ({@link detectCycles}) runs over CALL edges to surface cyclic
+ * call graphs. Endpoint identity is FILE-level (not symbol-level) so the SCC
+ * partitions reflect file-grained dependency cycles.
+ */
+export interface CallEdge {
+    from: string;
+    to: string;
+}
+export interface SymbolDefLite {
+    filePath: string;
+    name: string;
+    kind: string;
+    exported?: boolean;
+}
+export interface HttpEdgeLite {
+    fromFile?: string;
+    symbolName?: string;
+    targetFqn?: string;
+    method?: string;
+    route?: string;
+}
+interface GraphView {
+    /** All files (nodes). */
+    files: string[];
+    /** Internal import edges (non-external, both endpoints known). */
+    edges: InternalImport[];
+    /** File index for O(1) lookup. */
+    fileIndex: Map<string, number>;
+    /** In-degree per file (distinct importers). */
+    inDegree: Int32Array;
+    /** Out-degree per file (distinct imports). */
+    outDegree: Int32Array;
+    /** File → set of distinct imported files. */
+    outAdj: Map<string, Set<string>>;
+    /** File → set of distinct importers. */
+    inAdj: Map<string, Set<string>>;
+}
+export declare function detectPackages(files: string[], gv: GraphView, opts?: {
+    maxPackages?: number;
+    minFiles?: number;
+}): PackageInfo[];
+export declare function detectEntryPoints(gv: GraphView, opts?: {
+    maxResults?: number;
+    minInDegree?: number;
+}): EntryPoint[];
+export declare function detectRoutes(httpEdges: HttpEdgeLite[], defs: SymbolDefLite[], opts?: {
+    maxResults?: number;
+}): RouteInfo[];
+/**
+ * Most-depended-on files. Combines PageRank centrality (when available) with
+ * in-degree (number of distinct importers) and per-file symbol counts.
+ */
+export declare function detectHotspots(gv: GraphView, opts?: {
+    centrality?: Map<string, number>;
+    symbolCounts?: Map<string, number>;
+    maxResults?: number;
+}): HotspotInfo[];
+/**
+ * Convert raw community memberships (node indices) into labeled clusters over
+ * file paths. Each community gets a representative label (common path prefix
+ * when one exists, else the most-central/most-connected file), a size, a
+ * cohesion metric, and its top files.
+ */
+export declare function labelCommunities(files: string[], gv: GraphView, communities: Community[], opts?: {
+    maxResults?: number;
+    minSize?: number;
+    maxTopFiles?: number;
+}): CommunityInfo[];
+/**
+ * Classify communities/files into de-facto layers using fan-in/fan-out signals:
+ *   - entry:   imported by others, imports little (bootstrap / public surface)
+ *   - api:     contains routes / http_call edges
+ *   - core:    high fan-in, moderate fan-out (foundation modules)
+ *   - leaf:    high fan-out, low fan-in (terminals: handlers, scripts)
+ *   - service: default for mid-coupling groups
+ */
+export declare function classifyLayers(communities: CommunityInfo[], gv: GraphView, routes: RouteInfo[]): LayerInfo[];
+export interface ArchitectureInput {
+    files: string[];
+    internalEdges: InternalImport[];
+    definitions: SymbolDefLite[];
+    httpEdges: HttpEdgeLite[];
+    /**
+     * Directed CALL edges (Wave 5 FR-02 / N2). Populated from
+     * `symbol_references WHERE ref_kind='call'` rows by the snapshot reader;
+     * the `cycles` aspect (T03) runs iterative Tarjan SCC over these. Optional
+     * for backward-compat: pre-Wave-5 callers omit it and `cycles` stays absent
+     * from the resulting {@link ArchitectureMap}.
+     */
+    callEdges?: CallEdge[];
+    centrality?: Map<string, number>;
+    symbolCounts?: Map<string, number>;
+    communities?: Community[];
+}
+/**
+ * Valid aspect names for {@link ArchitectureOptions.aspects} (Wave 5 FR-02 /
+ * FR-04 / AD-W5-020). Used both to validate caller input (teaching error on
+ * unknown value, Wave 4 N6 parity) and to document the contract.
+ */
+export declare const VALID_ARCHITECTURE_ASPECTS: readonly ["cycles"];
+export type ArchitectureAspect = (typeof VALID_ARCHITECTURE_ASPECTS)[number];
+export interface ArchitectureOptions {
+    /** Whether to compute communities (skip to save cost when undesired). */
+    withCommunities?: boolean;
+    /**
+     * Opt-in aspects (Wave 5 FR-02 / FR-04). When present, only listed aspects
+     * beyond the always-on baseline (packages/entryPoints/routes/hotspots/
+     * communities/layers) are computed. Today the only opt-in aspect is
+     * `"cycles"` (iterative Tarjan SCC over CALL edges).
+     *
+     * Unknown values throw a teaching error listing {@link VALID_ARCHITECTURE_ASPECTS}
+     * (Wave 4 N6 parity). `undefined` / empty → no opt-in aspects (backward-
+     * compat with pre-Wave-5 callers).
+     */
+    aspects?: string[];
+}
+/**
+ * Compute the full architecture map. Pure: no DB, no I/O.
+ *
+ * @throws {ToolError} when `opts.aspects` contains an unknown value (Wave 4
+ *   N6 teaching-error parity; message lists {@link VALID_ARCHITECTURE_ASPECTS}).
+ */
+export declare function computeArchitectureMap(input: ArchitectureInput, opts?: ArchitectureOptions): ArchitectureMap;
+export {};
+//# sourceMappingURL=architecture.d.ts.map

package/dist/services/symbol/architecture.d.ts.map

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