feat: add incremental parsing with cross-file edge preservation

- Implement deterministic node IDs based on coreType + filePath + name
- Add file change detection using mtime, size, and content hash
- Save cross-file edges before deletion and restore after import
- Load existing nodes from Neo4j for outgoing edge detection
- Fix missing await on parseChildNodes causing nodes to be lost
- Add FairSquare monorepo auto-detection (@fairsquare/source)
- Add debug logging utilities for troubleshooting

This enables fast incremental updates when modifying individual files,
preserving relationships like INJECTS edges between services.

Author: drewdrewH

src/constants.ts

@@ -1 +1,24 @@
 export const MAX_TRAVERSAL_DEPTH = 5;
+
+// Shared exclude patterns for file parsing and change detection
+// Regex patterns (escaped dots, anchored to end)
+export const EXCLUDE_PATTERNS_REGEX = [
+  'node_modules/',
+  'dist/',
+  'build/',
+  'coverage/',
+  '\\.d\\.ts$',
+  '\\.spec\\.ts$',
+  '\\.test\\.ts$',
+];
+
+// Glob patterns for use with glob library
+export const EXCLUDE_PATTERNS_GLOB = [
+  'node_modules/**',
+  'dist/**',
+  'build/**',
+  'coverage/**',
+  '**/*.d.ts',
+  '**/*.spec.ts',
+  '**/*.test.ts',
+];

src/core/config/nestjs-framework-schema.ts

@@ -1,6 +1,8 @@
 /* eslint-disable prefer-arrow/prefer-arrow-functions */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
+import { EXCLUDE_PATTERNS_REGEX } from '../../constants.js';
+
 import {
   CoreNodeType,
   FrameworkSchema,
@@ -940,7 +942,7 @@ export const NESTJS_FRAMEWORK_SCHEMA: FrameworkSchema = {
 
 export const NESTJS_PARSE_OPTIONS: ParseOptions = {
   includePatterns: ['**/*.ts', '**/*.tsx'],
-  excludePatterns: ['node_modules/', 'dist/', 'coverage/', '.d.ts', '.spec.ts', '.test.ts'],
+  excludePatterns: EXCLUDE_PATTERNS_REGEX,
   maxFiles: 1000,
   frameworkSchemas: [NESTJS_FRAMEWORK_SCHEMA],
 };

src/core/config/schema.ts

@@ -1,6 +1,8 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 // graph.ts - Optimized for Neo4j performance with context-based framework properties
 
+import { EXCLUDE_PATTERNS_REGEX } from '../../constants.js';
+
 // ============================================================================
 // CORE ENUMS
 // ============================================================================
@@ -141,6 +143,9 @@ export interface Neo4jNodeProperties {
   endLine: number;
   sourceCode: string;
   createdAt: string;
+  contentHash?: string;
+  mtime?: number;
+  size?: number;
 
   // === FRAMEWORK-SPECIFIC (Dynamic) ===
   context?: Record<string, any>;
@@ -1170,7 +1175,7 @@ export interface ParseOptions {
 
 export const DEFAULT_PARSE_OPTIONS: ParseOptions = {
   includePatterns: ['**/*.ts', '**/*.tsx'],
-  excludePatterns: ['node_modules/', 'dist/', 'coverage/', '.d.ts', '.spec.ts', '.test.ts'],
+  excludePatterns: EXCLUDE_PATTERNS_REGEX,
   maxFiles: 1000,
   coreSchema: CORE_TYPESCRIPT_SCHEMA,
   frameworkSchemas: [],

src/core/parsers/parser-factory.ts

@@ -3,6 +3,7 @@
  * Creates TypeScript parsers with appropriate framework schemas
  */
 
+import { EXCLUDE_PATTERNS_REGEX } from '../../constants.js';
 import { FAIRSQUARE_FRAMEWORK_SCHEMA } from '../config/fairsquare-framework-schema.js';
 import { NESTJS_FRAMEWORK_SCHEMA } from '../config/nestjs-framework-schema.js';
 import { CORE_TYPESCRIPT_SCHEMA, FrameworkSchema, CoreNodeType } from '../config/schema.js';
@@ -35,7 +36,7 @@ export class ParserFactory {
       tsConfigPath = 'tsconfig.json',
       projectType = ProjectType.NESTJS, // Default to NestJS (use auto-detect for best results)
       customFrameworkSchemas = [],
-      excludePatterns = ['node_modules', 'dist', 'build', '.spec.', '.test.'],
+      excludePatterns = EXCLUDE_PATTERNS_REGEX,
       excludedNodeTypes = [CoreNodeType.PARAMETER_DECLARATION],
     } = options;
 
@@ -100,7 +101,10 @@ export class ParserFactory {
       };
 
       const hasNestJS = '@nestjs/common' in deps || '@nestjs/core' in deps;
-      const hasFairSquare = '@fairsquare/core' in deps || '@fairsquare/server' in deps;
+      const hasFairSquare =
+        '@fairsquare/core' in deps ||
+        '@fairsquare/server' in deps ||
+        packageJson.name === '@fairsquare/source';
 
       if (hasFairSquare && hasNestJS) {
         return ProjectType.BOTH;