arcvision 0.2.4 → 0.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ArcVision
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.js

@@ -4587,7 +4587,10 @@ var require_tsconfig_utils = __commonJS({
   "src/core/tsconfig-utils.js"(exports2, module2) {
     var fs2 = require("fs");
     var path2 = require("path");
+    var configCache = /* @__PURE__ */ new Map();
     function loadTSConfig(startDir) {
+      if (configCache.has(startDir))
+        return configCache.get(startDir);
       let currentDir = startDir;
       const root = path2.parse(currentDir).root;
       while (currentDir) {
@@ -4605,17 +4608,18 @@ var require_tsconfig_utils = __commonJS({
               try {
                 parsed = JSON.parse(content);
               } catch (e) {
-                const stripped = content.replace(/\/\*[\s\S]*?\*\/|([^\\:]|^)\/\/.*$/gm, "$1").replace(/,\s*([\]}])/g, "$1");
+                let stripped = content.replace(/\/\*[\s\S]*?\*\//g, "").replace(/([^\n\r\"\']|^[^\"\']*)\/\/.*$/gm, "$1").replace(/,\s*(\}|\])/g, "$1").replace(/^[\uFEFF\u200B]+|[\uFEFF\u200B]+$/g, "").replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F-\x9F]/g, "");
                 parsed = JSON.parse(stripped);
               }
               if (parsed) {
-                return {
+                const result = {
                   options: parsed.compilerOptions || {},
                   configDir: currentDir
                 };
+                configCache.set(startDir, result);
+                return result;
               }
             } catch (error) {
-              console.warn(`Warning: Could not parse ${tsconfigPath}:`, error.message);
             }
           }
         }
@@ -4623,7 +4627,9 @@ var require_tsconfig_utils = __commonJS({
           break;
         currentDir = path2.dirname(currentDir);
       }
-      return { options: null, configDir: startDir };
+      const fallback = { options: null, configDir: startDir };
+      configCache.set(startDir, fallback);
+      return fallback;
     }
     module2.exports = { loadTSConfig };
   }
@@ -56393,6 +56399,8 @@ var require_parser = __commonJS({
         allowImportExportEverywhere: true,
         allowReturnOutsideFunction: true,
         allowSuperOutsideMethod: true,
+        errorRecovery: true,
+        // Allow parser to continue after errors
         plugins: [
           "jsx",
           "typescript",
@@ -56427,14 +56435,24 @@ var require_parser = __commonJS({
       try {
         ast = parser.parse(content, parserOptions);
       } catch (error) {
-        console.warn(`\u26A0\uFE0F  Failed to parse ${filePath}: ${error.message}`);
-        return {
-          id: filePath,
-          imports: [],
-          exports: [],
-          functions: [],
-          apiCalls: []
+        const fallbackParserOptions = {
+          ...parserOptions,
+          // Allow more flexible parsing
+          errorRecovery: true
+          // Allow parser to continue after errors
         };
+        try {
+          ast = parser.parse(content, fallbackParserOptions);
+        } catch (fallbackError) {
+          console.warn(`\u26A0\uFE0F  Failed to parse ${filePath}: ${error.message}`);
+          return {
+            id: filePath,
+            imports: [],
+            exports: [],
+            functions: [],
+            apiCalls: []
+          };
+        }
       }
       const metadata = {
         id: filePath,
@@ -57510,65 +57528,68 @@ var require_pass1_facts = __commonJS({
         ...scanOptions,
         ignore: [...scanOptions.ignore, "**/*.d.ts", "**/.next/**", "**/coverage/**", "**/arcvision.context.json"]
       });
+      const CONCURRENCY = 100;
       const rawNodes = [];
       let totalFacts = 0;
-      for (const file of files) {
-        try {
-          const relativePath = path2.relative(directory, file);
-          const normalizedRelativePath = normalize(relativePath);
-          let metadata = {};
-          if (file.endsWith(".json")) {
-            try {
+      for (let i = 0; i < files.length; i += CONCURRENCY) {
+        const batch = files.slice(i, i + CONCURRENCY);
+        const promises = batch.map(async (file) => {
+          try {
+            const relativePath = path2.relative(directory, file);
+            const normalizedRelativePath = normalize(relativePath);
+            let metadata = {};
+            if (file.endsWith(".json")) {
               const content = fs2.readFileSync(file, "utf-8");
-              JSON.parse(content);
               metadata = {
                 id: file,
                 isJson: true,
-                // JSONs might have "imports" in semantic sense (like package.json), but raw syntax is just data
                 raw: content
               };
-            } catch (e) {
-              console.warn(`\u26A0\uFE0F Invalid JSON in ${normalizedRelativePath}: ${e.message}`);
-              continue;
-            }
-          } else {
-            metadata = parser.parseFile(file);
-          }
-          metadata = await pluginManager.processFile(file, metadata);
-          const node = {
-            id: normalizedRelativePath,
-            // Unique ID for this pass
-            filePath: file,
-            type: "file",
-            // The "facts" are the metadata properties
-            facts: {
-              imports: metadata.imports || [],
-              exports: metadata.exports || [],
-              functions: metadata.functions || [],
-              classes: metadata.classes || [],
-              types: metadata.types || [],
-              calls: {
-                functions: metadata.functionCalls || [],
-                methods: metadata.methodCalls || [],
-                constructors: metadata.constructorCalls || []
-              },
-              typeAnalysis: {
-                typeImports: metadata.typeImports || [],
-                interfaceDeps: metadata.interfaceDependencies || [],
-                genericDeps: metadata.genericDependencies || []
-              },
-              di: {
-                injections: metadata.constructorInjections || [],
-                hooks: metadata.hookDependencies || [],
-                context: metadata.contextUsages || []
-              },
-              react: metadata.componentUsage || []
-            }
-          };
-          totalFacts += (metadata.imports?.length || 0) + (metadata.functionCalls?.length || 0);
-          rawNodes.push(node);
-        } catch (e) {
-          console.warn(`\u26A0\uFE0F Pass 1 failed for ${file}: ${e.message}`);
+            } else {
+              metadata = parser.parseFile(file);
+            }
+            metadata = await pluginManager.processFile(file, metadata);
+            const node = {
+              id: normalizedRelativePath,
+              filePath: file,
+              type: "file",
+              facts: {
+                imports: metadata.imports || [],
+                exports: metadata.exports || [],
+                functions: metadata.functions || [],
+                classes: metadata.classes || [],
+                types: metadata.types || [],
+                calls: {
+                  functions: metadata.functionCalls || [],
+                  methods: metadata.methodCalls || [],
+                  constructors: metadata.constructorCalls || []
+                },
+                typeAnalysis: {
+                  typeImports: metadata.typeImports || [],
+                  interfaceDeps: metadata.interfaceDependencies || [],
+                  genericDeps: metadata.genericDependencies || []
+                },
+                di: {
+                  injections: metadata.constructorInjections || [],
+                  hooks: metadata.hookDependencies || [],
+                  context: metadata.contextUsages || []
+                },
+                react: metadata.componentUsage || []
+              }
+            };
+            return { node, factCount: (metadata.imports?.length || 0) + (metadata.functionCalls?.length || 0) };
+          } catch (e) {
+            console.warn(`\u26A0\uFE0F Pass 1 failed for ${file}: ${e.message}`);
+            return null;
+          }
+        });
+        const results = await Promise.all(promises);
+        results.filter(Boolean).forEach((res) => {
+          rawNodes.push(res.node);
+          totalFacts += res.factCount;
+        });
+        if (i % (CONCURRENCY * 4) === 0 && i > 0) {
+          console.log(`   ... processed ${Math.min(i + CONCURRENCY, files.length)} / ${files.length} files`);
         }
       }
       console.log(`   \u2713 Scanned ${rawNodes.length} files`);
@@ -57584,26 +57605,31 @@ var require_path_resolver = __commonJS({
   "src/core/path-resolver.js"(exports2, module2) {
     var fs2 = require("fs");
     var path2 = require("path");
-    function resolveImport(importPath, importerPath, projectRoot, tsconfig, workspaceMap) {
+    function resolveImport(importPath, importerPath, projectRoot, tsconfig, workspaceMap, fileSet) {
       if (importPath.startsWith("http://") || importPath.startsWith("https://") || importPath.startsWith("data:") || importPath.startsWith("file:")) {
         return null;
       }
+      const exists = (p) => {
+        if (fileSet)
+          return fileSet.has(p);
+        return fs2.existsSync(p);
+      };
       if (importPath.startsWith(".")) {
         let resolvedPath = path2.resolve(path2.dirname(importerPath), importPath);
         const extensions = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json"];
         for (const ext of extensions) {
-          if (fs2.existsSync(resolvedPath + ext)) {
+          if (exists(resolvedPath + ext)) {
             return resolvedPath + ext;
           }
         }
         const indexFiles = ["index.ts", "index.tsx", "index.js", "index.jsx", "index.json"];
         for (const idxFile of indexFiles) {
           const indexPath = path2.join(resolvedPath, idxFile);
-          if (fs2.existsSync(indexPath)) {
+          if (exists(indexPath)) {
             return indexPath;
           }
         }
-        if (fs2.existsSync(resolvedPath)) {
+        if (exists(resolvedPath)) {
           return resolvedPath;
         }
         return null;
@@ -57622,18 +57648,18 @@ var require_path_resolver = __commonJS({
                 const targetPath = path2.resolve(projectRoot, path2.join(targetBase, suffix));
                 const extensions = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json"];
                 for (const ext of extensions) {
-                  if (fs2.existsSync(targetPath + ext)) {
+                  if (exists(targetPath + ext)) {
                     return targetPath + ext;
                   }
                 }
                 const indexFiles = ["index.ts", "index.tsx", "index.js", "index.jsx", "index.json"];
                 for (const idxFile of indexFiles) {
                   const indexPath = path2.join(targetPath, idxFile);
-                  if (fs2.existsSync(indexPath)) {
+                  if (exists(indexPath)) {
                     return indexPath;
                   }
                 }
-                if (fs2.existsSync(targetPath)) {
+                if (exists(targetPath)) {
                   return targetPath;
                 }
               }
@@ -57648,18 +57674,18 @@ var require_path_resolver = __commonJS({
                 }
                 const extensions = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json"];
                 for (const ext of extensions) {
-                  if (fs2.existsSync(targetPath + ext)) {
+                  if (exists(targetPath + ext)) {
                     return targetPath + ext;
                   }
                 }
                 const indexFiles = ["index.ts", "index.tsx", "index.js", "index.jsx", "index.json"];
                 for (const idxFile of indexFiles) {
                   const indexPath = path2.join(targetPath, idxFile);
-                  if (fs2.existsSync(indexPath)) {
+                  if (exists(indexPath)) {
                     return indexPath;
                   }
                 }
-                if (fs2.existsSync(targetPath)) {
+                if (exists(targetPath)) {
                   return targetPath;
                 }
               }
@@ -57671,18 +57697,18 @@ var require_path_resolver = __commonJS({
         let resolvedPath = path2.resolve(projectRoot, tsconfig.baseUrl, importPath);
         const extensions = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json"];
         for (const ext of extensions) {
-          if (fs2.existsSync(resolvedPath + ext)) {
+          if (exists(resolvedPath + ext)) {
             return resolvedPath + ext;
           }
         }
         const indexFiles = ["index.ts", "index.tsx", "index.js", "index.jsx", "index.json"];
         for (const idxFile of indexFiles) {
           const indexPath = path2.join(resolvedPath, idxFile);
-          if (fs2.existsSync(indexPath)) {
+          if (exists(indexPath)) {
             return indexPath;
           }
         }
-        if (fs2.existsSync(resolvedPath)) {
+        if (exists(resolvedPath)) {
           return resolvedPath;
         }
       }
@@ -57690,21 +57716,21 @@ var require_path_resolver = __commonJS({
         const packageRoot = workspaceMap.get(importPath);
         try {
           const pkgPath = path2.join(packageRoot, "package.json");
-          if (fs2.existsSync(pkgPath)) {
+          if (exists(pkgPath)) {
             const pkg = JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
             const mainFile = pkg.main || pkg.module || "index.js";
             const searchPath = path2.join(packageRoot, mainFile);
             const extensions = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json"];
             for (const ext of extensions) {
               const p = searchPath + ext;
-              if (fs2.existsSync(p))
+              if (exists(p))
                 return p;
             }
           }
           const indexFiles = ["index.ts", "index.tsx", "index.js", "index.jsx"];
           for (const idx of indexFiles) {
             const p = path2.join(packageRoot, idx);
-            if (fs2.existsSync(p))
+            if (exists(p))
               return p;
           }
         } catch (e) {
@@ -57718,14 +57744,14 @@ var require_path_resolver = __commonJS({
             const targetPath = path2.join(pkgRoot, suffix);
             const extensions = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json", ""];
             for (const ext of extensions) {
-              if (fs2.existsSync(targetPath + ext)) {
+              if (exists(targetPath + ext)) {
                 return targetPath + ext;
               }
             }
             const indexFiles = ["index.ts", "index.tsx", "index.js", "index.jsx"];
             for (const idx of indexFiles) {
               const p = path2.join(targetPath, idx);
-              if (fs2.existsSync(p))
+              if (exists(p))
                 return p;
             }
           }
@@ -58036,6 +58062,7 @@ var require_pass2_semantics = __commonJS({
       const normalize = (p) => p.replace(/\\/g, "/");
       const workspaceMap = workspaceContext ? workspaceContext.workspaceMap : null;
       const fileSet = new Set(rawNodes.map((n) => n.id));
+      const absoluteFileSet = new Set(rawNodes.map((n) => n.filePath));
       const edges = [];
       const addEdge = (source, target, type, confidence = 1, metadata = {}) => {
         if (!source || !target)
@@ -58054,11 +58081,14 @@ var require_pass2_semantics = __commonJS({
       for (const node of rawNodes) {
         if (!node.facts.imports)
           continue;
+        const nodeConfig = loadTSConfig(path2.dirname(node.filePath));
+        const nodeTsconfig = nodeConfig.options;
+        const nodeConfigRoot = nodeConfig.configDir;
         for (const imp of node.facts.imports) {
           const importString = imp.source;
           let targetId = null;
           let resolvedPath = null;
-          const resolvedAbs = resolveImport(importString, node.filePath, configRoot, tsconfig, workspaceMap);
+          const resolvedAbs = resolveImport(importString, node.filePath, nodeConfigRoot, nodeTsconfig, workspaceMap, absoluteFileSet);
           if (resolvedAbs) {
             targetId = normalize(path2.relative(rootDir, resolvedAbs));
             resolvedPath = targetId;
@@ -58139,9 +58169,12 @@ var require_pass2_semantics = __commonJS({
       for (const node of rawNodes) {
         if (!node.facts.typeAnalysis)
           continue;
+        const nodeConfig = loadTSConfig(path2.dirname(node.filePath));
+        const nodeTsconfig = nodeConfig.options;
+        const nodeConfigRoot = nodeConfig.configDir;
         const { typeImports, interfaceDeps, genericDeps } = node.facts.typeAnalysis;
         for (const imp of typeImports) {
-          const resolvedAbs = resolveImport(imp.source, node.filePath, rootDir, tsconfig, workspaceMap);
+          const resolvedAbs = resolveImport(imp.source, node.filePath, nodeConfigRoot, nodeTsconfig, workspaceMap, absoluteFileSet);
           if (resolvedAbs) {
             const targetId = normalize(path2.relative(rootDir, resolvedAbs));
             if (fileSet.has(targetId)) {
@@ -58415,15 +58448,19 @@ var require_pass4_signals = __commonJS({
       });
       const criticalityList = analyzeCriticality(blastRadiusMap, reverseGraph, nodes);
       const criticalityMap = new Map(criticalityList.map((c) => [c.file, c]));
+      const outDegreeMap = /* @__PURE__ */ new Map();
+      const inDegreeMap = /* @__PURE__ */ new Map();
+      edges.forEach((e) => {
+        outDegreeMap.set(e.source, (outDegreeMap.get(e.source) || 0) + 1);
+        inDegreeMap.set(e.target, (inDegreeMap.get(e.target) || 0) + 1);
+      });
       const finalNodes = nodes.map((node) => {
         const signals = {
           blast_radius: blastRadiusMap[node.id] || 0,
           criticality: criticalityMap.get(node.id)?.criticalityScore || 0,
           is_hub: criticalityMap.get(node.id)?.isHub || false,
-          // Calculate instability: closer to 1 means "depends on many things" (outgoing edges)
-          // (coupling)
-          outgoing_deps: edges.filter((e) => e.source === node.id).length,
-          incoming_deps: edges.filter((e) => e.target === node.id).length
+          outgoing_deps: outDegreeMap.get(node.id) || 0,
+          incoming_deps: inDegreeMap.get(node.id) || 0
         };
         return {
           id: node.id,
@@ -58493,8 +58530,8 @@ var require_context_builder = __commonJS({
         language = "javascript"
       } = options;
       const nodes = fileNodes.map((file) => {
-        const role = file.role || "Structure";
-        const layer = file.layer || "generic";
+        const role = file.role || file.structure && file.structure.role || "Structure";
+        const layer = file.layer || file.structure && file.structure.layer || "generic";
         const dependencies = [];
         const uniqueDeps = /* @__PURE__ */ new Set();
         const addDep = (target) => {
@@ -58505,8 +58542,6 @@ var require_context_builder = __commonJS({
         };
         if (file.intelligence && file.intelligence.connections) {
           file.intelligence.connections.forEach((c) => addDep(c.target));
-        } else {
-          edges.filter((e) => e.source === file.id).forEach((e) => addDep(e.target));
         }
         const nodeObj = {
           id: stableId(file.id),
@@ -58515,7 +58550,6 @@ var require_context_builder = __commonJS({
           role,
           dependencies,
           blast_radius: file.signals && file.signals.blast_radius || 0,
-          // New Schema Extensions (if supported by backend, otherwise ignored)
           layer,
           criticality: file.signals ? file.signals.criticality : 0
         };
@@ -65235,6 +65269,8 @@ function analyzeBlastRadius(architectureMap) {
       let blastRadius = 0;
       if (node.metadata && node.metadata.blast_radius !== void 0) {
         blastRadius = node.metadata.blast_radius;
+      } else if (node.signals && node.signals.blast_radius !== void 0) {
+        blastRadius = node.signals.blast_radius;
       } else if (architectureMap.contextSurface && architectureMap.contextSurface.topBlastRadiusFiles) {
         const foundFile = architectureMap.contextSurface.topBlastRadiusFiles.find((f) => f.file === node.path || f.file === node.id);
         if (foundFile) {

package/dist/schema/arcvision_context_schema_v1.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Arcvision System-Level Structural Context",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "generated_at",
+    "system",
+    "nodes",
+    "edges",
+    "metrics"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semantic version of the Arcvision context schema (e.g. 1.0.0)"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp when context was generated"
+    },
+    "system": {
+      "type": "object",
+      "required": ["name", "root_path", "language"],
+      "properties": {
+        "name": { "type": "string" },
+        "root_path": { "type": "string" },
+        "language": { "type": "string" }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "type", "path", "role"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Deterministic, stable ID (never random)"
+          },
+          "type": {
+            "type": "string",
+            "enum": ["file", "module", "class", "function", "service"]
+          },
+          "path": {
+            "type": "string",
+            "description": "Normalized relative path"
+          },
+          "role": {
+            "type": "string",
+            "description": "Why this node exists in the system"
+          },
+          "dependencies": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "relation"],
+        "properties": {
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "relation": {
+            "type": "string",
+            "enum": ["imports", "calls", "owns", "depends_on"]
+          }
+        }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "description": "System-wide aggregate metrics",
+      "additionalProperties": {
+        "type": ["number", "string"]
+      }
+    }
+  }
+}

package/docs/blast-radius-implementation.md

@@ -0,0 +1,76 @@
+# Blast Radius Implementation
+
+## Architecture
+
+### Files Added/Modified
+1. `src/core/blastRadius.js` - Core blast radius calculation logic
+2. `src/core/scanner.js` - Modified to include blast radius in output
+3. `src/index.js` - Modified to display blast radius insight
+
+### Core Functions
+
+#### `buildReverseDependencyGraph(architectureMap)`
+- Creates a reverse dependency map where keys are imported files and values are arrays of files that import them
+- Takes the architecture map (with nodes and edges) as input
+- Returns a map: `{ [importedFile]: [importingFile1, importingFile2, ...] }`
+
+#### `computeBlastRadius(reverseGraph)`
+- Calculates the blast radius for each file as the count of files that import it
+- Takes the reverse dependency graph as input
+- Returns a map: `{ [filePath]: blastRadiusNumber }`
+
+#### `findHighestBlastRadius(blastRadiusMap)`
+- Finds the file with the highest blast radius value
+- Takes the blast radius map as input
+- Returns an object: `{ file: filePath, blast_radius: radius }` or null
+
+## Data Flow
+
+1. **Scanning Phase**: The scanner builds the architecture map with nodes and edges as before
+2. **Blast Radius Calculation Phase**: After the architecture map is built:
+   - Reverse dependency graph is built from the edges
+   - Blast radius is computed for each file
+   - Blast radius values are added to each node's metadata
+3. **Output Phase**: The CLI prints the architecture map as JSON and then shows the blast radius insight
+
+## Data Structure Changes
+
+### Node Metadata
+Each node in the architecture map now includes:
+```javascript
+{
+  id: "relative/file/path.js",
+  type: "file",
+  metadata: {
+    imports: [...],
+    exports: [...],
+    functions: [...],
+    apiCalls: [...],
+    blast_radius: 5  // NEW FIELD
+  }
+}
+```
+
+### CLI Output
+The CLI now prints an additional message after the scan:
+```
+⚠️  src/core/utils.js has the highest blast radius (5). Changes here may affect many parts of the system.
+```
+
+## Algorithm Complexity
+- **Time Complexity**: O(V + E) where V is the number of files and E is the number of import relationships
+- **Space Complexity**: O(V + E) for storing the reverse dependency graph
+
+## Error Handling
+- Handles empty repositories gracefully
+- Handles files with no imports or no dependents
+- Maintains backward compatibility with existing functionality
+- Preserves all existing fields in the architecture map
+
+## Testing Considerations
+The implementation should be tested with:
+- Empty repositories
+- Repositories with no dependencies
+- Repositories with complex dependency chains
+- Repositories with circular dependencies
+- Large repositories with many files

package/docs/blast-radius.md

@@ -0,0 +1,44 @@
+# Blast Radius Feature
+
+## Overview
+The Blast Radius feature analyzes your codebase to identify files that are most critical to your application. It calculates how many other files depend on each file, helping you identify high-structure areas where changes could have wide-ranging roles.
+
+## How It Works
+- **Blast Radius Score**: For each file, the blast radius is calculated as the number of files that import it (direct dependencies only).
+- **Reverse Dependency Graph**: The system builds a reverse dependency graph to track which files import each file.
+- **Structure Assessment**: Files with higher blast radius scores are considered higher structure because changes to them could affect many other parts of the system.
+
+## Output
+The blast radius score is added to each file's metadata in the architecture map:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "src/auth/session.ts",
+      "type": "file",
+      "metadata": {
+        "imports": ["src/db/client.ts", "src/utils/logger.ts"],
+        "exports": [],
+        "functions": [],
+        "apiCalls": [],
+        "blast_radius": 2
+      }
+    }
+  ],
+  "edges": [...]
+}
+```
+
+## CLI Output
+After scanning, the CLI will display a warning for the file with the highest blast radius:
+
+```
+⚠️  src/auth/session.ts has the highest blast radius (2). Changes here may affect many parts of the system.
+```
+
+## Use Cases
+- Identify critical files that require extra care during refactoring
+- Understand the potential role of code changes
+- Prioritize code review efforts for high-structure files
+- Analyze architectural dependencies in your codebase

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcvision",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Architecture scanner for modern codebases",
   "bin": {
     "arcvision": "./dist/index.js"
@@ -38,11 +38,15 @@
   "author": "ArcVision",
   "repository": {
     "type": "git",
-    "url": "https://github.com/your-org/arcvision.git"
+    "url": "https://github.com/arcvision/arcvision.git"
   },
   "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE",
+    "schema",
+    "docs"
   ],
   "publishConfig": {
     "access": "public"

package/schema/arcvision_context_schema_v1.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Arcvision System-Level Structural Context",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "generated_at",
+    "system",
+    "nodes",
+    "edges",
+    "metrics"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semantic version of the Arcvision context schema (e.g. 1.0.0)"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp when context was generated"
+    },
+    "system": {
+      "type": "object",
+      "required": ["name", "root_path", "language"],
+      "properties": {
+        "name": { "type": "string" },
+        "root_path": { "type": "string" },
+        "language": { "type": "string" }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "type", "path", "role"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Deterministic, stable ID (never random)"
+          },
+          "type": {
+            "type": "string",
+            "enum": ["file", "module", "class", "function", "service"]
+          },
+          "path": {
+            "type": "string",
+            "description": "Normalized relative path"
+          },
+          "role": {
+            "type": "string",
+            "description": "Why this node exists in the system"
+          },
+          "dependencies": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "relation"],
+        "properties": {
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "relation": {
+            "type": "string",
+            "enum": ["imports", "calls", "owns", "depends_on"]
+          }
+        }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "description": "System-wide aggregate metrics",
+      "additionalProperties": {
+        "type": ["number", "string"]
+      }
+    }
+  }
+}