@mgamil/mapx 0.2.4

package/dist/core/git-tracker.js

@@ -0,0 +1,159 @@
+import { execSync } from "node:child_process";
+import { resolve, join } from "node:path";
+function getGitBlobHashes(repoRoot) {
+  const hashes = /* @__PURE__ */ new Map();
+  try {
+    const output = execSync("git ls-tree -r HEAD", {
+      cwd: repoRoot,
+      encoding: "utf-8",
+      maxBuffer: 50 * 1024 * 1024
+    });
+    for (const line of output.split("\n")) {
+      if (!line) continue;
+      const tab = line.indexOf("	");
+      if (tab === -1) continue;
+      const parts = line.slice(0, tab).split(" ");
+      if (parts.length < 3) continue;
+      const hash = parts[2];
+      const filePath = line.slice(tab + 1);
+      if (hash && filePath) hashes.set(filePath, hash);
+    }
+  } catch {
+  }
+  return hashes;
+}
+function getChangedFiles(repoRoot, since) {
+  const changes = [];
+  try {
+    let command;
+    if (since) {
+      command = `git diff --name-status ${since}`;
+    } else {
+      command = "git diff --name-status HEAD";
+    }
+    const output = execSync(command, {
+      cwd: repoRoot,
+      encoding: "utf-8",
+      maxBuffer: 50 * 1024 * 1024
+    });
+    for (const line of output.trim().split("\n").filter(Boolean)) {
+      const parts = line.split("	");
+      const status = parts[0].charAt(0);
+      const filePath = parts[parts.length - 1];
+      const statusMap = {
+        "A": "added",
+        "M": "modified",
+        "D": "removed",
+        "R": "renamed",
+        "C": "modified"
+      };
+      changes.push({ path: filePath, status: statusMap[status] || "modified" });
+    }
+  } catch {
+  }
+  try {
+    const stagedOutput = execSync("git diff --name-status --cached", {
+      cwd: repoRoot,
+      encoding: "utf-8"
+    }).trim();
+    for (const line of stagedOutput.split("\n").filter(Boolean)) {
+      const parts = line.split("	");
+      const status = parts[0].charAt(0);
+      const filePath = parts[parts.length - 1];
+      if (!changes.find((c) => c.path === filePath)) {
+        const statusMap = {
+          "A": "added",
+          "M": "modified",
+          "D": "removed",
+          "R": "renamed"
+        };
+        changes.push({ path: filePath, status: statusMap[status] || "modified" });
+      }
+    }
+  } catch {
+  }
+  return changes;
+}
+function getCurrentCommitSha(repoRoot) {
+  try {
+    return execSync("git rev-parse HEAD", { cwd: repoRoot, encoding: "utf-8" }).trim();
+  } catch {
+    return null;
+  }
+}
+function getPreviousCommitSha(repoRoot) {
+  try {
+    return execSync("git rev-parse HEAD~1", { cwd: repoRoot, encoding: "utf-8" }).trim();
+  } catch {
+    return null;
+  }
+}
+function isGitRepo(dir) {
+  try {
+    execSync("git rev-parse --git-dir", { cwd: dir, stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getRepoName(repoRoot) {
+  try {
+    const remote = execSync("git remote get-url origin", { cwd: repoRoot, encoding: "utf-8" }).trim();
+    const basename = remote.split("/").pop() || "unknown";
+    return basename.replace(/\.git$/, "");
+  } catch {
+    return resolve(repoRoot).split("/").pop() || "unknown";
+  }
+}
+import { existsSync, readFileSync } from "node:fs";
+function discoverSubmodules(repoRoot) {
+  const gitmodulesPath = join(repoRoot, ".gitmodules");
+  if (!existsSync(gitmodulesPath)) return [];
+  const submodules = [];
+  try {
+    const content = readFileSync(gitmodulesPath, "utf-8");
+    let currentSubmodule = null;
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith(";")) continue;
+      const sectionMatch = trimmed.match(/^\[submodule\s+"([^"]+)"\]$/i);
+      if (sectionMatch) {
+        if (currentSubmodule && currentSubmodule.name && currentSubmodule.path && currentSubmodule.url) {
+          submodules.push(currentSubmodule);
+        }
+        currentSubmodule = {
+          name: sectionMatch[1],
+          isInitialized: false
+        };
+        continue;
+      }
+      if (currentSubmodule && trimmed.includes("=")) {
+        const eq = trimmed.indexOf("=");
+        const key = trimmed.slice(0, eq).trim().toLowerCase();
+        const val = trimmed.slice(eq + 1).trim();
+        if (key === "path") {
+          currentSubmodule.path = val;
+          const subPath = join(repoRoot, val);
+          const gitFile = join(subPath, ".git");
+          currentSubmodule.isInitialized = existsSync(gitFile);
+        } else if (key === "url") {
+          currentSubmodule.url = val;
+        }
+      }
+    }
+    if (currentSubmodule && currentSubmodule.name && currentSubmodule.path && currentSubmodule.url) {
+      submodules.push(currentSubmodule);
+    }
+  } catch {
+  }
+  return submodules;
+}
+export {
+  discoverSubmodules,
+  getChangedFiles,
+  getCurrentCommitSha,
+  getGitBlobHashes,
+  getPreviousCommitSha,
+  getRepoName,
+  isGitRepo
+};

package/dist/core/graph.d.ts

@@ -0,0 +1,42 @@
+import { SymbolKind, GraphEdge } from '../types.js';
+
+declare class MapxGraph {
+    private graph;
+    private repo;
+    constructor(repo: string);
+    addFileNode(filePath: string, language: string, sizeBytes: number, lines: number): void;
+    addSymbolNode(symbolId: string, filePath: string, name: string, kind: SymbolKind, startLine: number, endLine: number, scope: string | null): void;
+    addDependencyEdge(edge: GraphEdge): void;
+    computePageRank(): Map<string, number>;
+    getRankedFiles(): Array<{
+        path: string;
+        pagerank: number;
+        language: string;
+    }>;
+    getRankedSymbols(): Array<{
+        name: string;
+        kind: SymbolKind;
+        filePath: string;
+        startLine: number;
+        pagerank: number;
+        scope: string | null;
+    }>;
+    getDependencies(filePath: string): Array<{
+        target: string;
+        type: string;
+    }>;
+    getReverseDependencies(filePath: string): Array<{
+        source: string;
+        type: string;
+    }>;
+    getFileCount(): number;
+    getSymbolCount(): number;
+    getEdgeCount(): number;
+    dropFrameworkEdgesForRepo(repoName: string): void;
+    toJSON(): object;
+    static fromJSON(data: object, repo: string): MapxGraph;
+    private fileNodeId;
+    private symbolNodeId;
+}
+
+export { MapxGraph };

package/dist/core/graph.js

@@ -0,0 +1,186 @@
+import Graph from "graphology";
+import pagerank from "graphology-metrics/centrality/pagerank.js";
+class MapxGraph {
+  graph;
+  repo;
+  constructor(repo) {
+    this.repo = repo;
+    this.graph = new Graph({ type: "directed", multi: true });
+  }
+  addFileNode(filePath, language, sizeBytes, lines) {
+    const nodeId = this.fileNodeId(filePath);
+    if (!this.graph.hasNode(nodeId)) {
+      this.graph.addNode(nodeId, { type: "file", path: filePath, language, sizeBytes, lines });
+    } else {
+      this.graph.mergeNodeAttributes(nodeId, { language, sizeBytes, lines });
+    }
+  }
+  addSymbolNode(symbolId, filePath, name, kind, startLine, endLine, scope) {
+    const nodeId = this.symbolNodeId(filePath, symbolId);
+    if (!this.graph.hasNode(nodeId)) {
+      this.graph.addNode(nodeId, { type: "symbol", name, kind, filePath, startLine, endLine, scope });
+    } else {
+      this.graph.mergeNodeAttributes(nodeId, { kind, startLine, endLine, scope });
+    }
+    const fileNodeId = this.fileNodeId(filePath);
+    if (this.graph.hasNode(fileNodeId) && !this.graph.hasEdge(fileNodeId, nodeId)) {
+      this.graph.addDirectedEdge(fileNodeId, nodeId, { type: "contains" });
+    }
+    if (scope) {
+      const parentNodeId = this.symbolNodeId(filePath, scope);
+      if (this.graph.hasNode(parentNodeId) && parentNodeId !== nodeId && !this.graph.hasEdge(parentNodeId, nodeId)) {
+        this.graph.addDirectedEdge(parentNodeId, nodeId, { type: "contains" });
+      }
+    }
+  }
+  addDependencyEdge(edge) {
+    const sourceId = this.fileNodeId(edge.sourceFile);
+    const targetId = this.fileNodeId(edge.targetFile);
+    if (this.graph.hasNode(sourceId) && this.graph.hasNode(targetId)) {
+      const edgeKey = `${sourceId}->${targetId}:${edge.edgeType}:${edge.sourceSymbol || ""}`;
+      if (!this.graph.hasEdge(edgeKey)) {
+        try {
+          this.graph.addDirectedEdgeWithKey(edgeKey, sourceId, targetId, {
+            type: edge.edgeType,
+            sourceSymbol: edge.sourceSymbol,
+            targetSymbol: edge.targetSymbol,
+            weight: edge.weight,
+            verifiability: edge.verifiability || "verified",
+            metadata: edge.metadata || {},
+            repo: edge.repo,
+            targetRepo: edge.targetRepo
+          });
+        } catch {
+        }
+      }
+    }
+  }
+  computePageRank() {
+    try {
+      const scores = pagerank(this.graph, { alpha: 0.85 });
+      for (const [node, score] of Object.entries(scores)) {
+        if (this.graph.hasNode(node)) {
+          this.graph.mergeNodeAttributes(node, { pagerank: score });
+        }
+      }
+      return new Map(Object.entries(scores));
+    } catch {
+      return /* @__PURE__ */ new Map();
+    }
+  }
+  getRankedFiles() {
+    const scores = this.computePageRank();
+    const files = [];
+    for (const [nodeId, score] of scores) {
+      const attrs = this.graph.getNodeAttributes(nodeId);
+      if (attrs.type === "file") {
+        files.push({ path: attrs.path, pagerank: score, language: attrs.language });
+      }
+    }
+    files.sort((a, b) => b.pagerank - a.pagerank);
+    return files;
+  }
+  getRankedSymbols() {
+    const fileRank = this.computePageRank();
+    const symbols = [];
+    for (const node of this.graph.nodes()) {
+      const attrs = this.graph.getNodeAttributes(node);
+      if (attrs.type === "symbol") {
+        const parentFileRank = fileRank.get(this.fileNodeId(attrs.filePath)) || 0;
+        const inDegree = this.graph.inDegree(node);
+        const symbolRank = parentFileRank * (1 + inDegree * 0.1);
+        symbols.push({
+          name: attrs.name,
+          kind: attrs.kind,
+          filePath: attrs.filePath,
+          startLine: attrs.startLine,
+          pagerank: symbolRank,
+          scope: attrs.scope
+        });
+      }
+    }
+    symbols.sort((a, b) => b.pagerank - a.pagerank);
+    return symbols;
+  }
+  getDependencies(filePath) {
+    const nodeId = this.fileNodeId(filePath);
+    if (!this.graph.hasNode(nodeId)) return [];
+    const deps = [];
+    for (const edge of this.graph.outEdges(nodeId)) {
+      const attrs = this.graph.getEdgeAttributes(edge);
+      if (attrs.type !== "contains") {
+        const target = this.graph.getNodeAttributes(this.graph.target(edge));
+        if (target.type === "file") {
+          deps.push({ target: target.path, type: attrs.type });
+        }
+      }
+    }
+    return deps;
+  }
+  getReverseDependencies(filePath) {
+    const nodeId = this.fileNodeId(filePath);
+    if (!this.graph.hasNode(nodeId)) return [];
+    const rdeps = [];
+    for (const edge of this.graph.inEdges(nodeId)) {
+      const attrs = this.graph.getEdgeAttributes(edge);
+      if (attrs.type !== "contains") {
+        const source = this.graph.getNodeAttributes(this.graph.source(edge));
+        if (source.type === "file") {
+          rdeps.push({ source: source.path, type: attrs.type });
+        }
+      }
+    }
+    return rdeps;
+  }
+  getFileCount() {
+    let count = 0;
+    for (const node of this.graph.nodes()) {
+      if (this.graph.getNodeAttribute(node, "type") === "file") count++;
+    }
+    return count;
+  }
+  getSymbolCount() {
+    let count = 0;
+    for (const node of this.graph.nodes()) {
+      if (this.graph.getNodeAttribute(node, "type") === "symbol") count++;
+    }
+    return count;
+  }
+  getEdgeCount() {
+    let count = 0;
+    for (const edge of this.graph.edges()) {
+      const attrs = this.graph.getEdgeAttributes(edge);
+      if (attrs.type !== "contains") count++;
+    }
+    return count;
+  }
+  dropFrameworkEdgesForRepo(repoName) {
+    const toDrop = [];
+    for (const edge of this.graph.edges()) {
+      const attrs = this.graph.getEdgeAttributes(edge);
+      if (attrs.repo === repoName && ["route", "middleware", "hook", "graphql_resolver", "message_handler", "websocket_handler"].includes(attrs.type)) {
+        toDrop.push(edge);
+      }
+    }
+    for (const edge of toDrop) {
+      this.graph.dropEdge(edge);
+    }
+  }
+  toJSON() {
+    return this.graph.toJSON();
+  }
+  static fromJSON(data, repo) {
+    const cg = new MapxGraph(repo);
+    cg.graph.import(data);
+    return cg;
+  }
+  fileNodeId(filePath) {
+    return `file://${filePath}`;
+  }
+  symbolNodeId(filePath, symbolName) {
+    return `symbol://${filePath}::${symbolName}`;
+  }
+}
+export {
+  MapxGraph
+};

package/dist/core/metrics.d.ts

@@ -0,0 +1,24 @@
+import { Store } from './store.js';
+import './store-interface.js';
+import './graph.js';
+import '../types.js';
+
+interface FileMetrics {
+    path: string;
+    language: string;
+    afferent: number;
+    efferent: number;
+    instability: number;
+}
+declare function calculateMetrics(store: Store, options?: {
+    repo?: string;
+    language?: string;
+    verifiedOnly?: boolean;
+}): FileMetrics[];
+interface GraphMetrics {
+    density: number;
+    transitivity: number;
+}
+declare function calculateGraphMetrics(store: Store, repo?: string): GraphMetrics;
+
+export { type FileMetrics, type GraphMetrics, calculateGraphMetrics, calculateMetrics };

package/dist/core/metrics.js

@@ -0,0 +1,87 @@
+function calculateMetrics(store, options = {}) {
+  const files = store.getAllFiles(options.repo);
+  const edges = store.getAllEdges(options.repo);
+  const afferentMap = /* @__PURE__ */ new Map();
+  const efferentMap = /* @__PURE__ */ new Map();
+  for (const f of files) {
+    afferentMap.set(f.path, /* @__PURE__ */ new Set());
+    efferentMap.set(f.path, /* @__PURE__ */ new Set());
+  }
+  for (const e of edges) {
+    if (options.verifiedOnly && e.verifiability === "inferred") {
+      continue;
+    }
+    const src = e.source_file;
+    const tgt = e.target_file;
+    if (src === tgt) continue;
+    if (afferentMap.has(tgt)) {
+      afferentMap.get(tgt).add(src);
+    }
+    if (efferentMap.has(src)) {
+      efferentMap.get(src).add(tgt);
+    }
+  }
+  const results = [];
+  for (const f of files) {
+    const path = f.path;
+    const lang = f.language;
+    if (options.language && lang.toLowerCase() !== options.language.toLowerCase()) {
+      continue;
+    }
+    const ca = afferentMap.get(path)?.size || 0;
+    const ce = efferentMap.get(path)?.size || 0;
+    const sum = ca + ce;
+    const instability = sum > 0 ? ce / sum : 0;
+    results.push({
+      path,
+      language: lang,
+      afferent: ca,
+      efferent: ce,
+      instability
+    });
+  }
+  return results.sort((a, b) => b.instability - a.instability || b.afferent - a.afferent || a.path.localeCompare(b.path));
+}
+function calculateGraphMetrics(store, repo) {
+  const files = store.getAllFiles(repo);
+  const edges = store.getAllEdges(repo);
+  const fileCount = files.length;
+  const edgeCount = edges.length;
+  const density = fileCount > 1 ? edgeCount / (fileCount * (fileCount - 1)) : 0;
+  const adj = /* @__PURE__ */ new Map();
+  for (const f of files) {
+    adj.set(f.path, /* @__PURE__ */ new Set());
+  }
+  for (const e of edges) {
+    const src = e.source_file;
+    const tgt = e.target_file;
+    if (!src || !tgt || src === tgt) continue;
+    if (!adj.has(src)) adj.set(src, /* @__PURE__ */ new Set());
+    if (!adj.has(tgt)) adj.set(tgt, /* @__PURE__ */ new Set());
+    adj.get(src).add(tgt);
+    adj.get(tgt).add(src);
+  }
+  let totalTriplets = 0;
+  let closedTriplets = 0;
+  for (const neighbors of adj.values()) {
+    const k = neighbors.size;
+    if (k < 2) continue;
+    totalTriplets += k * (k - 1) / 2;
+    const neighborArr = Array.from(neighbors);
+    for (let i = 0; i < neighborArr.length; i++) {
+      for (let j = i + 1; j < neighborArr.length; j++) {
+        const u = neighborArr[i];
+        const w = neighborArr[j];
+        if (adj.get(u)?.has(w)) {
+          closedTriplets++;
+        }
+      }
+    }
+  }
+  const transitivity = totalTriplets > 0 ? closedTriplets / totalTriplets : 0;
+  return { density, transitivity };
+}
+export {
+  calculateGraphMetrics,
+  calculateMetrics
+};

package/dist/core/scanner.d.ts

@@ -0,0 +1,53 @@
+import { Store } from './store.js';
+import { MapxGraph } from './graph.js';
+import { Config } from './config.js';
+import { ProgressCallback, ScanResult } from '../types.js';
+import './store-interface.js';
+import '../languages/registry.js';
+
+declare function buildMatcher(excludes: string[], includes: string[]): (rel: string) => boolean;
+declare class Scanner {
+    private store;
+    private config;
+    private graph;
+    private onProgress?;
+    private concurrency;
+    private aborted;
+    private cliExcludes;
+    private cliIncludes;
+    private workspaceFileMap;
+    constructor(store: Store, config: Config, graph: MapxGraph, onProgress?: ProgressCallback, options?: {
+        excludes?: string[];
+        includes?: string[];
+    });
+    abort(): void;
+    private loadResumeState;
+    private saveResumeState;
+    private clearResumeState;
+    private getLockPath;
+    private acquireScanLock;
+    private releaseScanLock;
+    scanFull(repoNames?: string[], options?: {
+        force?: boolean;
+    }): Promise<ScanResult>;
+    private _scanFullForRepo;
+    scanIncremental(repoNames?: string[]): Promise<ScanResult>;
+    private _scanIncrementalForRepo;
+    private discoverFiles;
+    private detectDeletedFiles;
+    private parseFilesParallel;
+    private parseWithWorkers;
+    private parseOnMainThread;
+    private writeParseResult;
+    private writeParseResultWithMap;
+    private resolveReferences;
+    private resolveReferencesWithMap;
+    private resolveRequirePath;
+    private resolveImportPath;
+    private resolveSymbolToFile;
+    private shouldExcludeDir;
+    private getFileInfo;
+    private scanFrameworkRoutesAndHooks;
+}
+
+export { Scanner, buildMatcher };