arcvision 0.2.5 → 0.2.6

package/README.md

@@ -1,74 +1,85 @@
-# ArcVision CLI
-
-Architecture scanner for modern codebases that generates dependency graphs and visualizes your project structure.
-
-## Installation
-
-```bash
-npm install -g arcvision
-```
-
-## Usage
-
-### Quick Start
-1. Sign up at the ArcVision dashboard
-2. Create a project and name it
-3. Generate a CLI token
-4. Run: `arcvision link <token>`
-5. Run: `arcvision scan --upload`
-6. Open dashboard to see results
-
-### Commands
-
-#### Link to Project
-```bash
-arcvision link <token>
-```
-Link this CLI to a project via upload token.
-
-#### Scan Project
-```bash
-arcvision scan [directory] [options]
-```
-Scan the current directory and generate architecture map.
-
-Options:
-- `-u, --upload`: Upload to database
-
-The scan command will also output a blast radius analysis showing the file with the highest blast radius and its potential role on your codebase.
-
-**Blast Radius Analysis**: After scanning, the CLI will display a warning identifying the most critical file in your codebase:
-```
-⚠️ [filename] at the center of the system (blast radius: X out of Y). This file represents a single point of systemic failure. Changes here may affect many parts of the system.
-```
-This feature helps identify high-structure files that are imported by many other files, allowing you to be more cautious when modifying them.
-
-## Features
-
-- **Modern Import Resolution**: Handles path aliases (`@/components/*`), barrel files (`./utils` → `./utils/index.ts`), and directory imports
-- **AST-based Parsing**: Uses Babel parser for accurate import detection
-- **Multi-framework Support**: Works with React, Next.js, and other modern JavaScript frameworks
-- **Dependency Graph Generation**: Creates comprehensive node-edge relationships
-- **Blast Radius Analysis**: Identifies high-structure files that are imported by many other files
-- **Cloud Integration**: Uploads results to ArcVision dashboard for visualization
-
-## Supported Import Patterns
-
-- Relative imports: `./utils`, `../components`
-- Path aliases: `@/components/Button`, `~/lib/utils`
-- Barrel files: `./utils` resolves to `./utils/index.ts(x)`
-- Directory imports: `@/utils` resolves to `src/utils/index.ts(x)`
-- Implicit extensions: `.ts`, `.tsx`, `.js`, `.jsx`
-
-## Architecture
-
-The ArcVision CLI runs locally on your machine and:
-1. Scans your project files using AST parsing
-2. Detects import relationships between files
-3. Resolves path aliases using tsconfig.json/jsconfig.json
-4. Generates a dependency graph in JSON format
-5. Uploads the graph to the ArcVision dashboard via API
-
-## License
-
-MIT
+# ArcVision System Context Artifact
+
+## What This Is
+
+This file is the **canonical structural context** of this codebase.
+It represents how the system actually works — not how it is described.
+
+It is generated directly from source code by ArcVision.
+
+## What This Replaces
+
+This artifact replaces:
+- Manual repository scanning
+- Tribal knowledge held by senior engineers
+- Re-explaining the system to new developers
+- Re-prompting LLMs with partial or incorrect context
+- Guessing blast radius of changes
+
+## When You Must Use This
+
+Use this artifact when:
+- Onboarding a new developer
+- Prompting an AI assistant about this codebase
+- Making architectural changes
+- Investigating unexpected behavior
+- Assessing risk before modifying core modules
+
+## What This Artifact Contains
+
+- Canonical module and dependency graph
+- Execution and data flow relationships
+- Structural roles (service, store, boundary, etc.)
+- Invariants inferred from the system
+- Impact metrics (blast radius, coupling)
+
+## Determinism & Trust
+
+- Generated from commit: b63e62db4aedf6ffb21055dd88d13c8a947a7422
+- Generation timestamp: 2026-01-13T03:50:34.571Z
+- Tool version: 0.2.5
+- Deterministic: same input → same output
+- Explicit assumptions listed inside the artifact
+
+If this artifact conflicts with human memory, **trust the artifact**.
+
+## Structural Context Hubs
+
+The following files have the highest blast radius and represent critical structural hubs in the system:
+
+- **src/lib/utils.ts**
+  - Blast Radius: 62 files (14.73% of codebase)
+  - Risk: Changes here may silently propagate across the system.
+
+- **src/components/ui/button.tsx**
+  - Blast Radius: 49 files (11.64% of codebase)
+  - Risk: Acts as a coordination layer between components.
+
+- **src/lib/supabase/client.ts**
+  - Blast Radius: 45 files (10.69% of codebase)
+  - Risk: Modifications can cause widespread inconsistencies.
+
+
+
+## How to Use With AI
+
+When prompting AI tools, include this file as system context.
+Do not ask the AI to infer architecture without it.
+
+## When to Regenerate
+
+Regenerate this artifact when:
+- Core modules change
+- New services are added
+- Dependency structure shifts
+
+Run:
+
+```
+arcvision scan --upload
+```
+
+## Source of Truth
+
+This artifact is the **source of truth** for system structure.
+All explanations, decisions, and AI reasoning should reference it.

package/dist/index.js

@@ -57524,7 +57524,7 @@ var require_pass1_facts = __commonJS({
       if (fs2.existsSync(pluginDir)) {
         pluginManager.loadPluginsFromDirectory(pluginDir);
       }
-      const files = await glob("**/*.{js,jsx,ts,tsx,json}", {
+      const files = await glob("**/*.{js,jsx,ts,tsx,json,lua}", {
         ...scanOptions,
         ignore: [...scanOptions.ignore, "**/*.d.ts", "**/.next/**", "**/coverage/**", "**/arcvision.context.json"]
       });
@@ -57545,14 +57545,27 @@ var require_pass1_facts = __commonJS({
                 isJson: true,
                 raw: content
               };
+            } else if (file.endsWith(".lua")) {
+              const content = fs2.readFileSync(file, "utf-8");
+              metadata = {
+                id: file,
+                isLua: true,
+                raw: content,
+                // Extract potential invocations from Lua content
+                potentialInvocations: extractLuaInvocations(content)
+              };
             } else {
               metadata = parser.parseFile(file);
             }
             metadata = await pluginManager.processFile(file, metadata);
+            const isLuaFile = file.endsWith(".lua");
+            const nodeType = isLuaFile ? "execution_script" : "file";
+            const nodeRole = isLuaFile ? "atomic_redis_operation" : "Structure";
             const node = {
               id: normalizedRelativePath,
               filePath: file,
-              type: "file",
+              type: nodeType,
+              role: nodeRole,
               facts: {
                 imports: metadata.imports || [],
                 exports: metadata.exports || [],
@@ -57574,9 +57587,14 @@ var require_pass1_facts = __commonJS({
                   hooks: metadata.hookDependencies || [],
                   context: metadata.contextUsages || []
                 },
-                react: metadata.componentUsage || []
+                react: metadata.componentUsage || [],
+                potentialInvocations: metadata.potentialInvocations || []
               }
             };
+            if (isLuaFile) {
+              node.language = "lua";
+              node.execution_boundary = "redis";
+            }
             return { node, factCount: (metadata.imports?.length || 0) + (metadata.functionCalls?.length || 0) };
           } catch (e) {
             console.warn(`\u26A0\uFE0F Pass 1 failed for ${file}: ${e.message}`);
@@ -57596,6 +57614,22 @@ var require_pass1_facts = __commonJS({
       console.log(`   \u2713 Extracted ${totalFacts} raw syntactic facts`);
       return rawNodes;
     }
+    function extractLuaInvocations(content) {
+      const invocations = [];
+      const patterns = [
+        /readFileSync\(['"].*\.lua['"].*\)/gi,
+        /defineCommand\(\s*\{\s*lua\s*:.*\}/gi,
+        /redis\.call\(['"].*['"].*\)/gi,
+        /redis\.pcall\(['"].*['"].*\)/gi
+      ];
+      patterns.forEach((pattern) => {
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+          invocations.push(match[0]);
+        }
+      });
+      return invocations;
+    }
     module2.exports = { executePass1 };
   }
 });
@@ -58165,6 +58199,66 @@ var require_pass2_semantics = __commonJS({
         }
       }
       console.log(`   \u2713 Resolved ${resolvedCalls} semantic call edges`);
+      let luaInvocationCount = 0;
+      for (const node of rawNodes) {
+        if (!node.facts.potentialInvocations || node.facts.potentialInvocations.length === 0)
+          continue;
+        const content = node.filePath && require("fs").readFileSync(node.filePath, "utf-8");
+        if (!content)
+          continue;
+        const luaInvocationPatterns = [
+          /readFileSync\(['"].*\.lua['"].*\)/gi,
+          /defineCommand\(\s*\{\s*lua\s*:.*?\}/gi,
+          /require\(['"].*\.lua['"].*\)/gi,
+          /fs\.readFileSync\(['"].*\.lua['"].*\)/gi,
+          /import\s+.*?from\s+['"].*\.lua['"].*\)?/gi,
+          /import\(['"].*\.lua['"].*\)/gi,
+          /loadScript\(['"].*\.lua['"].*\)/gi,
+          /loadLua\(['"].*\.lua['"].*\)/gi,
+          /load\(['"].*\.lua['"].*\)/gi
+        ];
+        for (const pattern of luaInvocationPatterns) {
+          let match;
+          while ((match = pattern.exec(content)) !== null) {
+            const luaFileMatch = match[0].match(/['"].*?\.lua['"]/);
+            if (luaFileMatch) {
+              let luaFilePath = luaFileMatch[0].slice(1, -1);
+              if (luaFilePath.startsWith("./") || luaFilePath.startsWith("../")) {
+                luaFilePath = path2.resolve(path2.dirname(node.filePath), luaFilePath);
+                luaFilePath = normalize(path2.relative(rootDir, luaFilePath));
+              } else if (luaFilePath.startsWith("/")) {
+                luaFilePath = normalize(path2.relative(rootDir, path2.join(rootDir, luaFilePath)));
+              } else {
+                const commonLuaDirs = ["src", "scripts", "commands", "lua", "lib"];
+                let foundPath = null;
+                for (const dir of commonLuaDirs) {
+                  const candidatePath = normalize(path2.join(dir, luaFilePath));
+                  if (fileSet.has(candidatePath)) {
+                    foundPath = candidatePath;
+                    break;
+                  }
+                }
+                if (foundPath) {
+                  luaFilePath = foundPath;
+                } else {
+                  const nodeDir = path2.dirname(node.id);
+                  luaFilePath = normalize(path2.join(nodeDir, luaFilePath));
+                }
+              }
+              if (fileSet.has(luaFilePath)) {
+                addEdge(node.id, luaFilePath, "invokes_execution_script", 1, {
+                  type: "lua_invocation",
+                  invocation_pattern: match[0],
+                  original_match: match[0],
+                  resolved_path: luaFilePath
+                });
+                luaInvocationCount++;
+              }
+            }
+          }
+        }
+      }
+      console.log(`   \u2713 Detected ${luaInvocationCount} Lua script invocations`);
       let typeEdgesCount = 0;
       for (const node of rawNodes) {
         if (!node.facts.typeAnalysis)
@@ -58522,6 +58616,8 @@ var require_id_generator = __commonJS({
 var require_context_builder = __commonJS({
   "src/core/context_builder.js"(exports2, module2) {
     var path2 = require("path");
+    var { spawnSync } = require("child_process");
+    var crypto = require("crypto");
     var { stableId } = require_id_generator();
     function buildContext(fileNodes, edges, symbols, options = {}) {
       const {
@@ -58619,9 +58715,11 @@ var require_context_builder = __commonJS({
         total_dependencies: schemaEdges.length,
         files_with_high_blast_radius: nodes.filter((n) => n.blast_radius > 5).length
       };
+      const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+      const dateOnly = timestamp.split("T")[0];
       const context = {
         schema_version: "1.0.0",
-        generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+        generated_at: timestamp,
         system: {
           name: projectName,
           root_path: path2.resolve(directory),
@@ -58631,11 +58729,453 @@ var require_context_builder = __commonJS({
         edges: schemaEdges,
         symbols: symbols || [],
         metrics,
-        contextSurface: options.contextSurface || []
+        contextSurface: options.contextSurface || [],
+        // Phase 2 requirement: Explicit Assumptions Section
+        assumptions: generateAssumptions(),
+        // Phase 2 requirement: Embed Commit Identity
+        source: {
+          repo: getGitInfo().repo,
+          commit: getGitInfo().commit,
+          generated_at: dateOnly,
+          // Use date only to avoid time variations
+          arcvision_version: options.arcvisionVersion || "0.1.0"
+        },
+        // Phase 3 requirement: Structural layers definition
+        structural_layers: generateAdaptiveStructuralLayers(directory),
+        // Phase 3 requirement: Project envelope
+        project_envelope: generateProjectEnvelope(directory)
+      };
+      const contextWithoutIntegrity = { ...context };
+      delete contextWithoutIntegrity.integrity;
+      const hash = crypto.createHash("sha256").update(JSON.stringify(contextWithoutIntegrity)).digest("hex");
+      context.integrity = {
+        sha256: hash
       };
       return context;
     }
-    module2.exports = { buildContext };
+    function getGitInfo() {
+      try {
+        const originResult = spawnSync("git", ["remote", "get-url", "origin"], {
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+        let repoUrl = "unknown";
+        if (originResult.status === 0) {
+          let url = originResult.stdout.toString().trim();
+          if (url.startsWith("git@")) {
+            url = url.replace(/^git@(.*?):/, "https://$1/");
+            url = url.replace(/\.git$/, "");
+          } else if (url.endsWith(".git")) {
+            url = url.replace(/\.git$/, "");
+          }
+          repoUrl = url;
+        }
+        const commitResult = spawnSync("git", ["rev-parse", "HEAD"], {
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+        let commitHash = "unknown";
+        if (commitResult.status === 0) {
+          commitHash = commitResult.stdout.toString().trim();
+        }
+        return {
+          repo: repoUrl,
+          commit: commitHash
+        };
+      } catch (error) {
+        return {
+          repo: "unknown",
+          commit: "unknown"
+        };
+      }
+    }
+    function calculateIntegrityHash(obj) {
+      try {
+        const objCopy = JSON.parse(JSON.stringify(obj));
+        if (objCopy.integrity) {
+          delete objCopy.integrity;
+        }
+        const jsonString = JSON.stringify(objCopy);
+        return crypto.createHash("sha256").update(jsonString).digest("hex");
+      } catch (error) {
+        return "calculation_error";
+      }
+    }
+    function generateStructuralLayers() {
+      return {
+        "runtime_code": {
+          "status": "included",
+          "description": "Source files that directly participate in runtime execution and system behavior"
+        },
+        "execution_scripts": {
+          "status": "included",
+          "description": "Scripts invoked by runtime code to perform atomic or system-critical operations"
+        },
+        "infrastructure_scripts": {
+          "status": "included",
+          "description": "Scripts that manage infrastructure-level behavior (queues, databases, orchestration)"
+        },
+        "configuration": {
+          "status": "optional",
+          "description": "Project configuration files represented as metadata, not execution graph nodes"
+        },
+        "documentation": {
+          "status": "optional",
+          "description": "Documentation files represented as metadata only"
+        },
+        "assets": {
+          "status": "excluded",
+          "description": "Static assets with no effect on execution semantics"
+        }
+      };
+    }
+    function generateAdaptiveStructuralLayers(directory) {
+      const fs2 = require("fs");
+      const path3 = require("path");
+      const hasPackageJson = fs2.existsSync(path3.join(directory, "package.json"));
+      const hasConfigFiles = fs2.existsSync(path3.join(directory, "tsconfig.json")) || fs2.existsSync(path3.join(directory, "config")) || fs2.existsSync(path3.join(directory, "webpack.config.js"));
+      const hasSrcDir = fs2.existsSync(path3.join(directory, "src"));
+      const hasTestDir = fs2.existsSync(path3.join(directory, "test")) || fs2.existsSync(path3.join(directory, "tests"));
+      const hasDocsDir = fs2.existsSync(path3.join(directory, "docs"));
+      let totalFiles = 0;
+      let jsFiles = 0;
+      let tsFiles = 0;
+      let luaFiles = 0;
+      let configFiles = 0;
+      function walk(dir, depth = 0) {
+        if (depth > 3)
+          return;
+        if (!fs2.existsSync(dir))
+          return;
+        const items = fs2.readdirSync(dir, { withFileTypes: true });
+        for (const item of items) {
+          const fullPath = path3.join(dir, item.name);
+          if (item.isDirectory()) {
+            if (!item.name.startsWith(".") && item.name !== "node_modules" && item.name !== "dist" && item.name !== "build" && item.name !== ".git") {
+              walk(fullPath, depth + 1);
+            }
+          } else {
+            totalFiles++;
+            if (item.name.endsWith(".js"))
+              jsFiles++;
+            if (item.name.endsWith(".ts"))
+              tsFiles++;
+            if (item.name.endsWith(".lua"))
+              luaFiles++;
+            if ([".json", ".yaml", ".yml", ".toml", ".config.js", ".config.ts", ".rc"].some((ext) => item.name.endsWith(ext)))
+              configFiles++;
+          }
+        }
+      }
+      walk(directory);
+      const isLuaProject = luaFiles > 0 && luaFiles / totalFiles > 0.1;
+      const isLargeProject = totalFiles > 1e3;
+      const layers = {
+        "runtime_code": {
+          "status": "included",
+          "description": "Source files that directly participate in runtime execution and system behavior",
+          "project_characteristics": {
+            "has_package_json": hasPackageJson,
+            "has_src_directory": hasSrcDir,
+            "total_files": totalFiles,
+            "javascript_files": jsFiles,
+            "typescript_files": tsFiles,
+            "lua_files": luaFiles
+          }
+        },
+        "execution_scripts": {
+          "status": isLuaProject ? "included" : "included",
+          "description": "Scripts invoked by runtime code to perform atomic or system-critical operations",
+          "project_characteristics": {
+            "lua_files_count": luaFiles,
+            "is_lua_project": isLuaProject
+          }
+        },
+        "infrastructure_scripts": {
+          "status": "included",
+          "description": "Scripts that manage infrastructure-level behavior (queues, databases, orchestration)"
+        },
+        "configuration": {
+          "status": hasConfigFiles ? "optional" : "excluded",
+          "description": "Project configuration files represented as metadata, not execution graph nodes"
+        },
+        "documentation": {
+          "status": hasDocsDir || hasPackageJson ? "optional" : "excluded",
+          "description": "Documentation files represented as metadata only"
+        },
+        "assets": {
+          "status": "excluded",
+          "description": "Static assets with no effect on execution semantics"
+        }
+      };
+      layers.project_metadata = {
+        "size_category": isLargeProject ? "large" : totalFiles > 100 ? "medium" : "small",
+        "file_count": totalFiles,
+        "language_mix": {
+          "javascript": jsFiles,
+          "typescript": tsFiles,
+          "lua": luaFiles,
+          "config": configFiles
+        },
+        "has_package_management": hasPackageJson,
+        "has_standard_structure": hasSrcDir,
+        "has_tests": hasTestDir,
+        "is_lua_intensive": isLuaProject
+      };
+      return layers;
+    }
+    function generateProjectEnvelope(directory) {
+      const fs2 = require("fs");
+      const path3 = require("path");
+      const envelope = {
+        configuration_files: [],
+        documentation: [],
+        build_tools: []
+      };
+      const configFiles = [
+        "package.json",
+        "tsconfig.json",
+        "jsconfig.json",
+        "webpack.config.js",
+        "webpack.config.ts",
+        "vite.config.js",
+        "vite.config.ts",
+        "rollup.config.js",
+        "rollup.config.ts",
+        "babel.config.js",
+        "babel.config.ts",
+        ".babelrc",
+        ".babelrc.js",
+        "eslint.config.mjs",
+        "eslint.config.js",
+        ".eslintrc",
+        ".eslintrc.js",
+        ".eslintrc.json",
+        "jest.config.js",
+        "jest.config.ts",
+        "jest.config.json",
+        "mocha.opts",
+        "nodemon.json",
+        "nodemon.js",
+        "next.config.ts",
+        "next.config.js",
+        "nuxt.config.js",
+        "nuxt.config.ts",
+        "postcss.config.mjs",
+        "postcss.config.js",
+        "tailwind.config.js",
+        "tailwind.config.ts",
+        "supabase/config.toml",
+        "pnpm-workspace.yaml",
+        "yarn.lock",
+        "package-lock.json",
+        "tsconfig.base.json",
+        "tsconfig.node.json",
+        "tsconfig.app.json",
+        "turbo.json",
+        "biome.json",
+        "biome.jsonc",
+        "angular.json",
+        "nest-cli.json",
+        "remix.config.js",
+        "remix.config.ts"
+      ];
+      const docFiles = [
+        "README.md",
+        "README.txt",
+        "readme.md",
+        "Readme.md",
+        "CHANGELOG.md",
+        "CHANGELOG.txt",
+        "LICENSE",
+        "LICENSE.md",
+        "CONTRIBUTING.md",
+        "NOTICE",
+        "NOTICE.md",
+        "SECURITY.md",
+        "CODE_OF_CONDUCT.md",
+        "PULL_REQUEST_TEMPLATE.md",
+        "ISSUE_TEMPLATE.md",
+        "HISTORY.md",
+        "AUTHORS",
+        "THANKS",
+        "CITATION.cff",
+        "CITATION.bib"
+      ];
+      const buildToolFiles = [
+        "typedoc.config.cjs",
+        "typedoc.json",
+        "typedoc.config.js",
+        "typedoc.config.ts",
+        "documentation.config.js",
+        "docs.config.js",
+        "api-extractor.json",
+        "api-documenter.json",
+        "jsdoc.json",
+        "jsdoc.config.json",
+        "compodoc.json",
+        "documentation.yml"
+      ];
+      function findFilesRecursively(dir, fileNames, results, maxDepth = 3, currentDepth = 0) {
+        if (currentDepth > maxDepth)
+          return;
+        if (!fs2.existsSync(dir))
+          return;
+        const items = fs2.readdirSync(dir, { withFileTypes: true });
+        for (const item of items) {
+          const fullPath = path3.join(dir, item.name);
+          if (item.isDirectory()) {
+            if (!item.name.startsWith(".") && item.name !== "node_modules" && item.name !== "dist" && item.name !== "build") {
+              findFilesRecursively(fullPath, fileNames, results, maxDepth, currentDepth + 1);
+            }
+          } else {
+            if (fileNames.includes(item.name)) {
+              const relativePath = path3.relative(directory, fullPath);
+              results.push({
+                path: relativePath,
+                name: item.name
+              });
+            }
+          }
+        }
+      }
+      const foundConfigFiles = [];
+      findFilesRecursively(directory, configFiles, foundConfigFiles);
+      foundConfigFiles.forEach((fileObj) => {
+        envelope.configuration_files.push({
+          path: fileObj.path,
+          role: getRoleForConfigFile(fileObj.name)
+        });
+      });
+      const foundDocFiles = [];
+      findFilesRecursively(directory, docFiles, foundDocFiles);
+      foundDocFiles.forEach((fileObj) => {
+        envelope.documentation.push({
+          path: fileObj.path,
+          role: getRoleForDocFile(fileObj.name)
+        });
+      });
+      const foundBuildToolFiles = [];
+      findFilesRecursively(directory, buildToolFiles, foundBuildToolFiles);
+      foundBuildToolFiles.forEach((fileObj) => {
+        envelope.build_tools.push({
+          path: fileObj.path,
+          role: getRoleForBuildToolFile(fileObj.name)
+        });
+      });
+      envelope.configuration_files = envelope.configuration_files.filter(
+        (file, index, self2) => index === self2.findIndex((f) => f.path === file.path)
+      );
+      envelope.documentation = envelope.documentation.filter(
+        (file, index, self2) => index === self2.findIndex((f) => f.path === file.path)
+      );
+      envelope.build_tools = envelope.build_tools.filter(
+        (file, index, self2) => index === self2.findIndex((f) => f.path === file.path)
+      );
+      return envelope;
+    }
+    function getRoleForConfigFile(fileName) {
+      const roles = {
+        "package.json": "dependency_manifest",
+        "tsconfig.json": "compiler_configuration",
+        "jsconfig.json": "compiler_configuration",
+        "webpack.config.js": "bundler_configuration",
+        "webpack.config.ts": "bundler_configuration",
+        "vite.config.js": "bundler_configuration",
+        "vite.config.ts": "bundler_configuration",
+        "rollup.config.js": "bundler_configuration",
+        "rollup.config.ts": "bundler_configuration",
+        "babel.config.js": "transpiler_configuration",
+        "babel.config.ts": "transpiler_configuration",
+        ".babelrc": "transpiler_configuration",
+        ".babelrc.js": "transpiler_configuration",
+        "eslint.config.mjs": "linting_configuration",
+        "eslint.config.js": "linting_configuration",
+        ".eslintrc": "linting_configuration",
+        ".eslintrc.js": "linting_configuration",
+        ".eslintrc.json": "linting_configuration",
+        "jest.config.js": "testing_configuration",
+        "jest.config.ts": "testing_configuration",
+        "jest.config.json": "testing_configuration",
+        "mocha.opts": "testing_configuration",
+        "nodemon.json": "development_configuration",
+        "nodemon.js": "development_configuration",
+        "next.config.ts": "framework_configuration",
+        "next.config.js": "framework_configuration",
+        "nuxt.config.js": "framework_configuration",
+        "nuxt.config.ts": "framework_configuration",
+        "postcss.config.mjs": "css_processing_configuration",
+        "postcss.config.js": "css_processing_configuration",
+        "tailwind.config.js": "css_framework_configuration",
+        "tailwind.config.ts": "css_framework_configuration",
+        "supabase/config.toml": "database_service_configuration",
+        "pnpm-workspace.yaml": "package_manager_configuration",
+        "yarn.lock": "dependency_lockfile",
+        "package-lock.json": "dependency_lockfile",
+        "tsconfig.base.json": "compiler_base_configuration",
+        "tsconfig.node.json": "compiler_node_configuration",
+        "tsconfig.app.json": "compiler_app_configuration",
+        "turbo.json": "build_system_configuration",
+        "biome.json": "formatter_linter_configuration",
+        "biome.jsonc": "formatter_linter_configuration",
+        "angular.json": "framework_configuration",
+        "nest-cli.json": "framework_configuration",
+        "remix.config.js": "framework_configuration",
+        "remix.config.ts": "framework_configuration"
+      };
+      return roles[fileName] || "general_configuration";
+    }
+    function getRoleForDocFile(fileName) {
+      const roles = {
+        "README.md": "system_overview",
+        "README.txt": "system_overview",
+        "readme.md": "system_overview",
+        "Readme.md": "system_overview",
+        "CHANGELOG.md": "change_history",
+        "CHANGELOG.txt": "change_history",
+        "LICENSE": "license_terms",
+        "LICENSE.md": "license_terms",
+        "CONTRIBUTING.md": "contribution_guidelines",
+        "NOTICE": "legal_notice",
+        "NOTICE.md": "legal_notice",
+        "SECURITY.md": "security_policy",
+        "CODE_OF_CONDUCT.md": "code_of_conduct",
+        "PULL_REQUEST_TEMPLATE.md": "pull_request_guidelines",
+        "ISSUE_TEMPLATE.md": "issue_reporting_guidelines",
+        "HISTORY.md": "project_history",
+        "AUTHORS": "authorship_information",
+        "THANKS": "acknowledgements",
+        "CITATION.cff": "citation_information",
+        "CITATION.bib": "citation_information"
+      };
+      return roles[fileName] || "documentation";
+    }
+    function getRoleForBuildToolFile(fileName) {
+      const roles = {
+        "typedoc.config.cjs": "documentation_generator",
+        "typedoc.json": "documentation_generator",
+        "typedoc.config.js": "documentation_generator",
+        "typedoc.config.ts": "documentation_generator",
+        "documentation.config.js": "documentation_generator",
+        "docs.config.js": "documentation_generator",
+        "api-extractor.json": "api_documentation_generator",
+        "api-documenter.json": "api_documentation_generator",
+        "jsdoc.json": "documentation_generator",
+        "jsdoc.config.json": "documentation_generator",
+        "compodoc.json": "angular_documentation_generator",
+        "documentation.yml": "documentation_generator"
+      };
+      return roles[fileName] || "build_tool_configuration";
+    }
+    function generateAssumptions() {
+      return [
+        "Dynamic imports resolved statically where possible",
+        "Runtime reflection not fully captured",
+        "Only code reachable from entry points analyzed",
+        "Third-party dependencies treated as black boxes",
+        "Build-time code generation not reflected in static analysis",
+        "ArcVision prioritizes execution-relevant structure over exhaustive file indexing. Non-runtime files are represented as envelope metadata unless they directly affect execution."
+      ];
+    }
+    module2.exports = { buildContext, getGitInfo, calculateIntegrityHash, generateAssumptions, generateStructuralLayers, generateProjectEnvelope, generateAdaptiveStructuralLayers };
   }
 });
 
@@ -65222,7 +65762,9 @@ var require_scanner = __commonJS({
         const contextOptions = {
           directory,
           projectName: path2.basename(directory),
-          contextSurface
+          contextSurface,
+          arcvisionVersion: process.env.npm_package_version || "0.1.0"
+          // Pass version from package.json
         };
         let context = buildContext(nodes, edges, symbols, contextOptions);
         console.log("   Validating structural context...");
@@ -65244,6 +65786,199 @@ var require_scanner = __commonJS({
   }
 });
 
+// src/core/diff-analyzer.js
+var require_diff_analyzer = __commonJS({
+  "src/core/diff-analyzer.js"(exports2, module2) {
+    function generateDiffSummary2(oldContext, newContext) {
+      const diffSummary = {
+        nodes_added: 0,
+        nodes_removed: 0,
+        edges_added: 0,
+        edges_removed: 0,
+        roles_changed: 0,
+        blast_radius_changes: 0
+      };
+      const oldNodeMap = new Map(oldContext.nodes.map((node) => [node.path, node]));
+      const newNodeMap = new Map(newContext.nodes.map((node) => [node.path, node]));
+      for (const [path2, node] of newNodeMap) {
+        if (!oldNodeMap.has(path2)) {
+          diffSummary.nodes_added++;
+        }
+      }
+      for (const [path2, node] of oldNodeMap) {
+        if (!newNodeMap.has(path2)) {
+          diffSummary.nodes_removed++;
+        }
+      }
+      const oldEdgeMap = new Map(
+        oldContext.edges.map((edge) => [`${edge.from}::${edge.to}::${edge.relation}`, edge])
+      );
+      const newEdgeMap = new Map(
+        newContext.edges.map((edge) => [`${edge.from}::${edge.to}::${edge.relation}`, edge])
+      );
+      for (const [key, edge] of newEdgeMap) {
+        if (!oldEdgeMap.has(key)) {
+          diffSummary.edges_added++;
+        }
+      }
+      for (const [key, edge] of oldEdgeMap) {
+        if (!newEdgeMap.has(key)) {
+          diffSummary.edges_removed++;
+        }
+      }
+      for (const newNode of newContext.nodes) {
+        const oldNode = oldNodeMap.get(newNode.path);
+        if (oldNode && oldNode.role !== newNode.role) {
+          diffSummary.roles_changed++;
+        }
+      }
+      for (const newNode of newContext.nodes) {
+        const oldNode = oldNodeMap.get(newNode.path);
+        if (oldNode && oldNode.blast_radius !== newNode.blast_radius) {
+          diffSummary.blast_radius_changes++;
+        }
+      }
+      return {
+        diff_summary: diffSummary
+      };
+    }
+    module2.exports = { generateDiffSummary: generateDiffSummary2 };
+  }
+});
+
+// src/core/readme-generator.js
+var require_readme_generator = __commonJS({
+  "src/core/readme-generator.js"(exports2, module2) {
+    var fs2 = require("fs");
+    var path2 = require("path");
+    var { spawnSync } = require("child_process");
+    function getCommitHash() {
+      try {
+        const result = spawnSync("git", ["rev-parse", "HEAD"], {
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+        if (result.status === 0) {
+          return result.stdout.toString().trim();
+        }
+        return "unknown";
+      } catch (error) {
+        return "unknown";
+      }
+    }
+    function generateReadmeContent(commitHash, timestamp, toolVersion, blastRadiusData = null) {
+      let content = `# ArcVision System Context Artifact
+
+
+## What This Is [arcvision.context.json](./arcvision.context.json)
+
+This file is the **canonical structural context** of this codebase.
+It represents how the system actually works \u2014 not how it is described.
+
+It is generated directly from source code by ArcVision.
+
+## What This Replaces
+
+This artifact replaces:
+- Manual repository scanning
+- Tribal knowledge held by senior engineers
+- Re-explaining the system to new developers
+- Re-prompting LLMs with partial or incorrect context
+- Guessing blast radius of changes
+
+## When You Must Use This
+
+Use this artifact when:
+- Onboarding a new developer
+- Prompting an AI assistant about this codebase
+- Making architectural changes
+- Investigating unexpected behavior
+- Assessing risk before modifying core modules
+
+## What This Artifact Contains
+
+- Canonical module and dependency graph
+- Execution and data flow relationships
+- Structural roles (service, store, boundary, etc.)
+- Invariants inferred from the system
+- Impact metrics (blast radius, coupling)
+
+## Determinism & Trust
+
+- Generated from commit: ${commitHash}
+- Generation timestamp: ${timestamp}
+- Tool version: ${toolVersion}
+- Deterministic: same input \u2192 same output
+- Explicit assumptions listed inside the artifact
+
+If this artifact conflicts with human memory, **trust the artifact**.`;
+      if (blastRadiusData && blastRadiusData.topFiles && blastRadiusData.topFiles.length > 0) {
+        content += `
+
+## Structural Context Hubs
+
+The following files have the highest blast radius and represent critical structural hubs in the system:
+
+`;
+        blastRadiusData.topFiles.forEach((item, index) => {
+          let warningMessage = "";
+          if (index === 0) {
+            warningMessage = "Changes here may silently propagate across the system.";
+          } else if (index === 1) {
+            warningMessage = "Acts as a coordination layer between components.";
+          } else {
+            warningMessage = "Modifications can cause widespread inconsistencies.";
+          }
+          content += `- **${item.file}**
+  - Blast Radius: ${item.blastRadius} files (${item.percentOfGraph}% of codebase)
+  - Risk: ${warningMessage}
+
+`;
+        });
+      } else {
+        content += `
+
+## Structural Context Hubs
+
+No high-structure files detected based on import dependencies.`;
+      }
+      content += `
+
+## How to Use With AI
+
+When prompting AI tools, include this file as system context.
+Do not ask the AI to infer architecture without it.
+
+## When to Regenerate
+
+Regenerate this artifact when:
+- Core modules change
+- New services are added
+- Dependency structure shifts
+
+Run:
+
+\`\`\`
+arcvision scan --upload
+\`\`\`
+
+## Source of Truth
+
+This artifact is the **source of truth** for system structure.
+All explanations, decisions, and AI reasoning should reference it.`;
+      return content;
+    }
+    function generateReadme(outputDir, toolVersion, blastRadiusData = null) {
+      const commitHash = getCommitHash();
+      const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+      const readmeContent = generateReadmeContent(commitHash, timestamp, toolVersion, blastRadiusData);
+      const readmePath = path2.join(outputDir, "README.md");
+      fs2.writeFileSync(readmePath, readmeContent);
+      console.log(`\u2705 System context README generated at ${readmePath}`);
+    }
+    module2.exports = { generateReadme, generateReadmeContent, getCommitHash };
+  }
+});
+
 // src/index.js
 var { Command } = require_commander();
 var chalk = require_source();
@@ -65251,6 +65986,7 @@ var path = require("path");
 var fs = require("fs");
 var os = require("os");
 var scanner = require_scanner();
+var { generateDiffSummary } = require_diff_analyzer();
 var version = "1.0.0";
 try {
   const packageJsonPath = path.join(__dirname, "../package.json");
@@ -65267,7 +66003,9 @@ function analyzeBlastRadius(architectureMap) {
   if (architectureMap.nodes && architectureMap.nodes.length > 0) {
     architectureMap.nodes.forEach((node) => {
       let blastRadius = 0;
-      if (node.metadata && node.metadata.blast_radius !== void 0) {
+      if (node.blast_radius !== void 0) {
+        blastRadius = node.blast_radius;
+      } else 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;
@@ -65463,11 +66201,15 @@ program.command("scan").description("Scan the current directory and generate arc
     }
     if (options.upload) {
       await uploadToDatabase(map);
+      const { generateReadme } = require_readme_generator();
+      generateReadme(".", version, blastRadiusAnalysis);
     } else {
       const fs2 = require("fs");
       const outputFileName = "arcvision.context.json";
       fs2.writeFileSync(outputFileName, JSON.stringify(map, null, 2));
       console.log(chalk.green(`\u2705 Structural context saved to ${outputFileName}`));
+      const { generateReadme } = require_readme_generator();
+      generateReadme(".", version, blastRadiusAnalysis);
       console.log(chalk.dim("\nUse --upload to send to dashboard."));
     }
   } catch (error) {
@@ -65492,4 +66234,29 @@ program.command("scan").description("Scan the current directory and generate arc
     }
   }
 });
+program.command("diff").description("Compare two context artifacts and generate diff summary").argument("<old-file>", "Path to the old context artifact").argument("<new-file>", "Path to the new context artifact").action(async (oldFile, newFile) => {
+  try {
+    console.log(chalk.blue(`Comparing context artifacts:`));
+    console.log(chalk.blue(`  Old: ${oldFile}`));
+    console.log(chalk.blue(`  New: ${newFile}`));
+    const oldContext = JSON.parse(fs.readFileSync(oldFile, "utf8"));
+    const newContext = JSON.parse(fs.readFileSync(newFile, "utf8"));
+    const diffResult = generateDiffSummary(oldContext, newContext);
+    newContext.diff_summary = diffResult.diff_summary;
+    const outputFileName = "arcvision.context.diff.json";
+    fs.writeFileSync(outputFileName, JSON.stringify(newContext, null, 2));
+    console.log(chalk.green("\u2705 Structural diff completed!"));
+    console.log(chalk.green(`\u2705 Diff summary saved to ${outputFileName}`));
+    console.log(chalk.yellow("\nDiff Summary:"));
+    console.log(chalk.yellow(`  Nodes Added: ${diffResult.diff_summary.nodes_added}`));
+    console.log(chalk.yellow(`  Nodes Removed: ${diffResult.diff_summary.nodes_removed}`));
+    console.log(chalk.yellow(`  Edges Added: ${diffResult.diff_summary.edges_added}`));
+    console.log(chalk.yellow(`  Edges Removed: ${diffResult.diff_summary.edges_removed}`));
+    console.log(chalk.yellow(`  Roles Changed: ${diffResult.diff_summary.roles_changed}`));
+    console.log(chalk.yellow(`  Blast Radius Changes: ${diffResult.diff_summary.blast_radius_changes}`));
+  } catch (error) {
+    console.error(chalk.red("\u274C Diff failed:"), error.message);
+    process.exit(1);
+  }
+});
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcvision",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Architecture scanner for modern codebases",
   "bin": {
     "arcvision": "./dist/index.js"

package/schema/arcvision_context_schema_v1.json

@@ -8,7 +8,12 @@
     "system",
     "nodes",
     "edges",
-    "metrics"
+    "metrics",
+    "assumptions",
+    "source",
+    "integrity",
+    "structural_layers",
+    "project_envelope"
   ],
   "properties": {
     "schema_version": {
@@ -79,6 +84,138 @@
       "additionalProperties": {
         "type": ["number", "string"]
       }
+    },
+    "assumptions": {
+      "type": "array",
+      "description": "Explicit assumptions about analysis limitations",
+      "items": {
+        "type": "string"
+      }
+    },
+    "source": {
+      "type": "object",
+      "description": "Source repository and commit information",
+      "required": ["repo", "commit", "generated_at", "arcvision_version"],
+      "properties": {
+        "repo": { "type": "string" },
+        "commit": { "type": "string" },
+        "generated_at": { "type": "string" },
+        "arcvision_version": { "type": "string" }
+      }
+    },
+    "integrity": {
+      "type": "object",
+      "description": "Integrity hash of the artifact",
+      "required": ["sha256"],
+      "properties": {
+        "sha256": { "type": "string" }
+      }
+    },
+    "structural_layers": {
+      "type": "object",
+      "description": "Defines which structural layers are included in the analysis",
+      "required": ["runtime_code", "execution_scripts", "infrastructure_scripts", "configuration", "documentation", "assets"],
+      "properties": {
+        "runtime_code": {
+          "type": "object",
+          "required": ["status", "description"],
+          "properties": {
+            "status": { "type": "string", "enum": ["included", "excluded"] },
+            "description": { "type": "string" }
+          }
+        },
+        "execution_scripts": {
+          "type": "object",
+          "required": ["status", "description"],
+          "properties": {
+            "status": { "type": "string", "enum": ["included", "excluded"] },
+            "description": { "type": "string" }
+          }
+        },
+        "infrastructure_scripts": {
+          "type": "object",
+          "required": ["status", "description"],
+          "properties": {
+            "status": { "type": "string", "enum": ["included", "excluded"] },
+            "description": { "type": "string" }
+          }
+        },
+        "configuration": {
+          "type": "object",
+          "required": ["status", "description"],
+          "properties": {
+            "status": { "type": "string", "enum": ["included", "excluded", "optional"] },
+            "description": { "type": "string" }
+          }
+        },
+        "documentation": {
+          "type": "object",
+          "required": ["status", "description"],
+          "properties": {
+            "status": { "type": "string", "enum": ["included", "excluded", "optional"] },
+            "description": { "type": "string" }
+          }
+        },
+        "assets": {
+          "type": "object",
+          "required": ["status", "description"],
+          "properties": {
+            "status": { "type": "string", "enum": ["included", "excluded"] },
+            "description": { "type": "string" }
+          }
+        }
+      }
+    },
+    "project_envelope": {
+      "type": "object",
+      "description": "Project-level files that provide context but are not execution graph nodes",
+      "properties": {
+        "configuration_files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": { "type": "string" },
+              "role": { "type": "string" }
+            },
+            "required": ["path", "role"]
+          }
+        },
+        "documentation": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": { "type": "string" },
+              "role": { "type": "string" }
+            },
+            "required": ["path", "role"]
+          }
+        },
+        "build_tools": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": { "type": "string" },
+              "role": { "type": "string" }
+            },
+            "required": ["path", "role"]
+          }
+        }
+      }
+    },
+    "diff_summary": {
+      "type": "object",
+      "description": "Structural diff summary between commits",
+      "properties": {
+        "nodes_added": { "type": "number" },
+        "nodes_removed": { "type": "number" },
+        "edges_added": { "type": "number" },
+        "edges_removed": { "type": "number" },
+        "roles_changed": { "type": "number" },
+        "blast_radius_changes": { "type": "number" }
+      }
     }
   }
 }

package/dist/schema/arcvision_context_schema_v1.json

@@ -1,84 +0,0 @@
-{
-  "$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"]
-      }
-    }
-  }
-}