@depxray/core 1.3.0

package/dist/types.d.ts

@@ -0,0 +1,316 @@
+/**
+ * A single node in the scanned folder/file tree.
+ *
+ * This structure is the source of truth for the project structure graph MVP.
+ * Unlike dependency graph nodes, directories and files are both represented.
+ */
+export interface FileTreeNode {
+    /** Unique identifier — the absolute path */
+    id: string;
+    /** Short display name (last path segment only) */
+    name: string;
+    /** Path relative to the scanned project root */
+    relativePath: string;
+    /** Absolute path on disk */
+    absolutePath: string;
+    /** Whether this node is a file or directory */
+    kind: 'file' | 'directory';
+    /** File extension for files, otherwise null */
+    extension: string | null;
+    /** Nesting depth from the root node */
+    depth: number;
+    /** Child nodes, only populated for directories */
+    children: FileTreeNode[];
+    /** File size in bytes, only populated for files */
+    sizeBytes?: number;
+}
+/**
+ * A node in the structure graph used by the browser UI.
+ */
+export interface StructureGraphNode {
+    /** Unique identifier — the absolute path */
+    id: string;
+    /** Short label for display */
+    label: string;
+    /** Path relative to the scanned project root */
+    relativePath: string;
+    /** Absolute path on disk */
+    absolutePath: string;
+    /** Whether this node is a file or directory */
+    kind: 'file' | 'directory';
+    /** File extension for files, otherwise null */
+    extension: string | null;
+    /** Nesting depth from the root node */
+    depth: number;
+    /** Whether this directory is currently collapsed */
+    collapsed: boolean;
+    /** Whether this node is hidden because an ancestor is collapsed */
+    hidden: boolean;
+    /** Number of direct children */
+    childCount: number;
+    /** Total recursive descendant count */
+    descendantCount: number;
+    /** File size in bytes, only populated for files */
+    sizeBytes?: number;
+}
+/**
+ * A directed edge from a parent node to its child in the file tree.
+ */
+export interface StructureGraphEdge {
+    /** Stable edge identifier */
+    id: string;
+    /** Parent node absolute path */
+    source: string;
+    /** Child node absolute path */
+    target: string;
+}
+/**
+ * The structure graph payload produced from a file tree.
+ */
+export interface StructureGraph {
+    /** Root project directory */
+    rootDir: string;
+    /** Graph nodes for directories and files */
+    nodes: StructureGraphNode[];
+    /** Parent-to-child edges */
+    edges: StructureGraphEdge[];
+}
+/**
+ * A single file node in the dependency graph.
+ *
+ * Each scanned file becomes a GraphNode. The `id` is the absolute path,
+ * which guarantees uniqueness. The `relativePath` is for display purposes.
+ */
+export interface GraphNode {
+    /** Unique identifier — the absolute file path */
+    id: string;
+    /** Path relative to the project root (for display and portability) */
+    relativePath: string;
+    /** File extension: '.ts', '.tsx', '.js', or '.jsx' */
+    extension: string;
+    /** Number of files that import this file (incoming edges) */
+    inDegree: number;
+    /** Number of files this file imports (outgoing edges) */
+    outDegree: number;
+    /** Whether this file participates in a circular dependency */
+    isCircular: boolean;
+    /** Detected component or export name (from default export, if any) */
+    componentName?: string;
+}
+/**
+ * A directed edge representing an import relationship.
+ *
+ * The edge goes from `source` (the file that contains the import statement)
+ * to `target` (the file being imported).
+ */
+export interface GraphEdge {
+    /** Absolute path of the importing file */
+    source: string;
+    /** Absolute path of the imported file */
+    target: string;
+    /** The original import specifier as written in the source code */
+    importSpecifier: string;
+    /** List of named imports, e.g., ['useState', 'useEffect'] */
+    importedNames: string[];
+    /** Whether this is a type-only import (`import type { ... }`) */
+    isTypeOnly: boolean;
+    /** Whether this is a dynamic import (`import('...')`) */
+    isDynamic: boolean;
+}
+/**
+ * A detected circular dependency chain.
+ *
+ * For example, if A imports B and B imports A, the chain would be:
+ * ['A.tsx', 'B.tsx', 'A.tsx']
+ */
+export interface CircularChain {
+    /** Ordered list of relative file paths forming the cycle */
+    chain: string[];
+    /** Human-readable description, e.g., "A.tsx → B.tsx → A.tsx" */
+    description: string;
+}
+/**
+ * The complete dependency graph for a project.
+ */
+export interface DependencyGraph {
+    /** Absolute path of the scanned project root */
+    rootDir: string;
+    /** All file nodes in the graph */
+    nodes: GraphNode[];
+    /** All import edges in the graph */
+    edges: GraphEdge[];
+    /** All detected circular dependency chains */
+    circularDependencies: CircularChain[];
+    /** Metadata about the scan */
+    metadata: ScanMetadata;
+}
+/**
+ * Options for configuring the scanner.
+ *
+ * All fields are optional and have sensible defaults.
+ */
+export interface ScanOptions {
+    /** Absolute path to the project root directory (required) */
+    rootDir: string;
+    /**
+     * File extensions to include in the scan.
+     * @default ['.js', '.jsx', '.ts', '.tsx']
+     */
+    extensions?: string[];
+    /**
+     * Additional directory/file patterns to ignore (on top of defaults).
+     * Uses glob-like matching against relative paths.
+     */
+    ignorePatterns?: string[];
+    /**
+     * Whether to detect circular dependencies.
+     * @default true
+     */
+    detectCircular?: boolean;
+    /**
+     * Whether to resolve path aliases from tsconfig.json/jsconfig.json.
+     * @default true
+     */
+    resolveAliases?: boolean;
+    /**
+     * Maximum depth for directory traversal.
+     * @default Infinity
+     */
+    maxDepth?: number;
+    /**
+     * Whether to include type-only imports in the graph.
+     * @default true
+     */
+    includeTypeImports?: boolean;
+    /**
+     * Whether to include dynamic imports (`import('...')`) in the graph.
+     * @default true
+     */
+    includeDynamicImports?: boolean;
+    /**
+     * Patterns for known entry points to exclude from orphan detection.
+     * Uses lightweight glob matching against relative paths.
+     */
+    entryPointPatterns?: string[];
+}
+/**
+ * Options for detecting files that have no incoming import edges.
+ */
+export interface OrphanDetectionOptions {
+    /** Patterns for known entry points to exclude from orphan detection */
+    entryPointPatterns?: string[];
+}
+/**
+ * Options for scanning a raw folder/file tree.
+ */
+export interface ScanFileTreeOptions {
+    /** Additional directory/file names to ignore */
+    ignorePatterns?: string[];
+    /**
+     * Maximum child depth to traverse from the root node.
+     * @default Infinity
+     */
+    maxDepth?: number;
+}
+/**
+ * The result returned by `scanProject()`.
+ *
+ * Contains the full dependency graph, summary statistics, and any errors
+ * encountered during scanning.
+ */
+export interface ScanResult {
+    /** The complete dependency graph */
+    graph: DependencyGraph;
+    /** Total number of files scanned */
+    totalFiles: number;
+    /** Total number of import edges found */
+    totalImports: number;
+    /** Total number of circular dependency chains */
+    circularCount: number;
+    /** Relative paths of files with no incoming imports, excluding entry points */
+    orphanFiles: string[];
+    /** Files that could not be parsed, with error details */
+    errors: ScanError[];
+    /** How long the scan took in milliseconds */
+    durationMs: number;
+}
+/**
+ * A file that failed to parse during scanning.
+ */
+export interface ScanError {
+    /** Absolute path of the file that failed */
+    filePath: string;
+    /** Human-readable error message */
+    error: string;
+}
+/**
+ * Metadata about a scan, included in the graph and exported JSON.
+ */
+export interface ScanMetadata {
+    /** ISO 8601 timestamp of when the scan was performed */
+    scannedAt: string;
+    /** How long the scan took in milliseconds */
+    scanDurationMs: number;
+    /** Absolute path of the project root */
+    projectRoot: string;
+    /** Total number of files in the graph */
+    totalFiles: number;
+    /** Total number of edges in the graph */
+    totalEdges: number;
+    /** Number of circular dependency chains detected */
+    circularCount: number;
+    /** Version of @depxray/core that produced this graph */
+    depxrayVersion: string;
+}
+/**
+ * Raw import information extracted from a single file's AST.
+ * This is an intermediate representation before path resolution.
+ */
+export interface RawImportInfo {
+    /** The import specifier as written in source, e.g., './Button' or '@/utils' */
+    source: string;
+    /** Named imports: ['Button', 'ButtonProps'] */
+    specifiers: string[];
+    /** Whether this is `import type { ... }` */
+    isTypeOnly: boolean;
+    /** Whether this is a dynamic `import('...')` */
+    isDynamic: boolean;
+    /** Line number in the source file */
+    line: number;
+}
+/**
+ * A resolved import — the raw import after path resolution.
+ */
+export interface ResolvedImport {
+    /** The original raw import info */
+    raw: RawImportInfo;
+    /** The resolved absolute file path, or null if unresolvable */
+    resolvedPath: string | null;
+    /** Why the import couldn't be resolved (if resolvedPath is null) */
+    error?: string;
+}
+/**
+ * A path alias mapping loaded from tsconfig.json or jsconfig.json.
+ *
+ * Example: `"@/*": ["./src/*"]` becomes:
+ *   { prefix: '@/', paths: ['/abs/path/to/src/'] }
+ */
+export interface AliasMapping {
+    /** The alias prefix (without the wildcard `*`), e.g., '@/' */
+    prefix: string;
+    /** Absolute directory paths this alias maps to */
+    paths: string[];
+}
+/**
+ * Default directories and patterns to ignore during file discovery.
+ */
+export declare const DEFAULT_IGNORE_PATTERNS: string[];
+/**
+ * Default file extensions to scan.
+ */
+export declare const DEFAULT_EXTENSIONS: string[];
+/**
+ * Default entry points excluded from orphan detection.
+ */
+export declare const DEFAULT_ENTRY_POINT_PATTERNS: string[];
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,45 @@
+"use strict";
+// ============================================================================
+// React Dependency Graph — Core Types
+// ============================================================================
+// All shared type definitions for the scanner, graph, and output formats.
+// These types are consumed by the CLI and future integrations
+// (MCP server, Antigravity, Codex).
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ENTRY_POINT_PATTERNS = exports.DEFAULT_EXTENSIONS = exports.DEFAULT_IGNORE_PATTERNS = void 0;
+/**
+ * Default directories and patterns to ignore during file discovery.
+ */
+exports.DEFAULT_IGNORE_PATTERNS = [
+    'node_modules',
+    'dist',
+    'build',
+    'out',
+    '.next',
+    'coverage',
+    '.git',
+    '.cache',
+    '.turbo',
+    '.depxray',
+    '__mocks__',
+];
+/**
+ * Default file extensions to scan.
+ */
+exports.DEFAULT_EXTENSIONS = ['.js', '.jsx', '.ts', '.tsx'];
+/**
+ * Default entry points excluded from orphan detection.
+ */
+exports.DEFAULT_ENTRY_POINT_PATTERNS = [
+    '**/index.*',
+    '**/main.*',
+    '**/app.*',
+    '**/App.*',
+    '**/*.test.*',
+    '**/*.spec.*',
+    '**/*.config.*',
+    '**/vite.config.*',
+    '**/next.config.*',
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,+EAA+E;AAC/E,sCAAsC;AACtC,+EAA+E;AAC/E,0EAA0E;AAC1E,8DAA8D;AAC9D,oCAAoC;AACpC,+EAA+E;;;AA8Y/E;;GAEG;AACU,QAAA,uBAAuB,GAAa;IAC/C,cAAc;IACd,MAAM;IACN,OAAO;IACP,KAAK;IACL,OAAO;IACP,UAAU;IACV,MAAM;IACN,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,WAAW;CACZ,CAAC;AAEF;;GAEG;AACU,QAAA,kBAAkB,GAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAE3E;;GAEG;AACU,QAAA,4BAA4B,GAAa;IACpD,YAAY;IACZ,WAAW;IACX,UAAU;IACV,UAAU;IACV,aAAa;IACb,aAAa;IACb,eAAe;IACf,kBAAkB;IAClB,kBAAkB;CACnB,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@depxray/core",
+  "version": "1.3.0",
+  "description": "Static analysis engine for JavaScript and TypeScript dependency graphs, codebase context, and AI-agent tooling.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.24.0",
+    "@babel/traverse": "^7.24.0",
+    "@babel/types": "^7.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0",
+    "@types/babel__traverse": "^7.20.0",
+    "@types/node": "^20.0.0"
+  },
+  "keywords": [
+    "dependency-graph",
+    "dependency-analysis",
+    "static-analysis",
+    "javascript",
+    "typescript",
+    "imports",
+    "codebase",
+    "codebase-explorer",
+    "architecture",
+    "ai-agent",
+    "coding-agent",
+    "agentic-ai",
+    "llm"
+  ],
+  "license": "MIT"
+}