@grafema/core 0.1.0-alpha.5 → 0.2.0-beta

package/dist/config/ConfigLoader.js

@@ -0,0 +1,249 @@
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { parse as parseYAML } from 'yaml';
+/**
+ * Default plugin configuration.
+ * Matches current DEFAULT_PLUGINS in analyze.ts and config.ts (MCP).
+ */
+export const DEFAULT_CONFIG = {
+    plugins: {
+        discovery: [],
+        indexing: ['JSModuleIndexer'],
+        analysis: [
+            'JSASTAnalyzer',
+            'ExpressRouteAnalyzer',
+            'ExpressResponseAnalyzer',
+            'SocketIOAnalyzer',
+            'DatabaseAnalyzer',
+            'FetchAnalyzer',
+            'ServiceLayerAnalyzer',
+        ],
+        enrichment: [
+            'MethodCallResolver',
+            'ArgumentParameterLinker',
+            'AliasTracker',
+            'ClosureCaptureEnricher',
+            'ValueDomainAnalyzer',
+            'MountPointResolver',
+            'PrefixEvaluator',
+            'ImportExportLinker',
+            'HTTPConnectionEnricher',
+        ],
+        validation: [
+            'GraphConnectivityValidator',
+            'DataFlowValidator',
+            'EvalBanValidator',
+            'CallResolverValidator',
+            'SQLInjectionValidator',
+            'ShadowingDetector',
+            'TypeScriptDeadCodeValidator',
+            'BrokenImportValidator',
+        ],
+    },
+    services: [], // Empty by default (uses auto-discovery)
+    strict: false, // Graceful degradation by default
+};
+/**
+ * Load Grafema config from project directory.
+ *
+ * Priority:
+ * 1. config.yaml (preferred)
+ * 2. config.json (deprecated, fallback)
+ * 3. DEFAULT_CONFIG (if neither exists)
+ *
+ * Warnings:
+ * - Logs deprecation warning if config.json is used
+ * - Logs parse errors but doesn't throw (returns defaults)
+ *
+ * @param projectPath - Absolute path to project root
+ * @param logger - Optional logger for warnings (defaults to console.warn)
+ * @returns Parsed config or defaults
+ */
+export function loadConfig(projectPath, logger = console) {
+    const grafemaDir = join(projectPath, '.grafema');
+    const yamlPath = join(grafemaDir, 'config.yaml');
+    const jsonPath = join(grafemaDir, 'config.json');
+    // 1. Try YAML first (preferred)
+    if (existsSync(yamlPath)) {
+        let parsed;
+        try {
+            const content = readFileSync(yamlPath, 'utf-8');
+            parsed = parseYAML(content);
+            // Validate structure - ensure plugins sections are arrays if they exist
+            if (parsed.plugins) {
+                for (const phase of ['discovery', 'indexing', 'analysis', 'enrichment', 'validation']) {
+                    const value = parsed.plugins[phase];
+                    if (value !== undefined && value !== null && !Array.isArray(value)) {
+                        throw new Error(`plugins.${phase} must be an array, got ${typeof value}`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            logger.warn(`Failed to parse config.yaml: ${error.message}`);
+            logger.warn('Using default configuration');
+            return DEFAULT_CONFIG;
+        }
+        // Validate services array if present (THROWS on error per Linus review)
+        // This is OUTSIDE try-catch - config errors MUST throw
+        validateServices(parsed.services, projectPath);
+        // Validate include/exclude patterns (THROWS on error)
+        validatePatterns(parsed.include, parsed.exclude, logger);
+        // Merge with defaults (user config may be partial)
+        return mergeConfig(DEFAULT_CONFIG, parsed);
+    }
+    // 2. Fallback to JSON (migration path)
+    if (existsSync(jsonPath)) {
+        logger.warn('⚠ config.json is deprecated. Run "grafema init --force" to migrate to config.yaml');
+        let parsed;
+        try {
+            const content = readFileSync(jsonPath, 'utf-8');
+            parsed = JSON.parse(content);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            logger.warn(`Failed to parse config.json: ${error.message}`);
+            logger.warn('Using default configuration');
+            return DEFAULT_CONFIG;
+        }
+        // Validate services array if present (THROWS on error)
+        // This is OUTSIDE try-catch - config errors MUST throw
+        validateServices(parsed.services, projectPath);
+        // Validate include/exclude patterns (THROWS on error)
+        validatePatterns(parsed.include, parsed.exclude, logger);
+        return mergeConfig(DEFAULT_CONFIG, parsed);
+    }
+    // 3. No config file - return defaults
+    return DEFAULT_CONFIG;
+}
+/**
+ * Validate services array structure.
+ * THROWS on error (fail loudly per Linus review).
+ *
+ * @param services - Parsed services array (may be undefined)
+ * @param projectPath - Project root for path validation
+ */
+function validateServices(services, projectPath) {
+    // undefined/null is valid (means use defaults)
+    if (services === undefined || services === null) {
+        return;
+    }
+    // Must be an array
+    if (!Array.isArray(services)) {
+        throw new Error(`Config error: services must be an array, got ${typeof services}`);
+    }
+    // Validate each service
+    for (let i = 0; i < services.length; i++) {
+        const svc = services[i];
+        // Must be an object
+        if (typeof svc !== 'object' || svc === null) {
+            throw new Error(`Config error: services[${i}] must be an object`);
+        }
+        // Name validation - required, non-empty string
+        if (typeof svc.name !== 'string') {
+            throw new Error(`Config error: services[${i}].name must be a string, got ${typeof svc.name}`);
+        }
+        if (!svc.name.trim()) {
+            throw new Error(`Config error: services[${i}].name cannot be empty or whitespace-only`);
+        }
+        // Path validation - required, non-empty string
+        if (typeof svc.path !== 'string') {
+            throw new Error(`Config error: services[${i}].path must be a string, got ${typeof svc.path}`);
+        }
+        if (!svc.path.trim()) {
+            throw new Error(`Config error: services[${i}].path cannot be empty or whitespace-only`);
+        }
+        // Path validation - must be relative (reject absolute paths per Linus review)
+        if (svc.path.startsWith('/') || svc.path.startsWith('~')) {
+            throw new Error(`Config error: services[${i}].path must be relative to project root, got "${svc.path}"`);
+        }
+        // Path validation - must exist
+        const absolutePath = join(projectPath, svc.path);
+        if (!existsSync(absolutePath)) {
+            throw new Error(`Config error: services[${i}].path "${svc.path}" does not exist`);
+        }
+        // Path validation - must be directory
+        if (!statSync(absolutePath).isDirectory()) {
+            throw new Error(`Config error: services[${i}].path "${svc.path}" must be a directory`);
+        }
+        // entryPoint validation (optional field) - must be non-empty string if provided
+        if (svc.entryPoint !== undefined) {
+            if (typeof svc.entryPoint !== 'string') {
+                throw new Error(`Config error: services[${i}].entryPoint must be a string, got ${typeof svc.entryPoint}`);
+            }
+            if (!svc.entryPoint.trim()) {
+                throw new Error(`Config error: services[${i}].entryPoint cannot be empty or whitespace-only`);
+            }
+        }
+    }
+}
+/**
+ * Validate include/exclude patterns.
+ * THROWS on error (fail loudly per project convention).
+ *
+ * Validation rules:
+ * 1. Must be arrays if provided
+ * 2. Array elements must be non-empty strings
+ * 3. Warn (don't error) if include array is empty (would exclude everything)
+ *
+ * @param include - Parsed include patterns (may be undefined)
+ * @param exclude - Parsed exclude patterns (may be undefined)
+ * @param logger - Logger for warnings
+ */
+function validatePatterns(include, exclude, logger) {
+    // Validate include
+    if (include !== undefined && include !== null) {
+        if (!Array.isArray(include)) {
+            throw new Error(`Config error: include must be an array, got ${typeof include}`);
+        }
+        for (let i = 0; i < include.length; i++) {
+            if (typeof include[i] !== 'string') {
+                throw new Error(`Config error: include[${i}] must be a string, got ${typeof include[i]}`);
+            }
+            if (!include[i].trim()) {
+                throw new Error(`Config error: include[${i}] cannot be empty or whitespace-only`);
+            }
+        }
+        // Warn if empty array (would exclude everything)
+        if (include.length === 0) {
+            logger.warn('Warning: include is an empty array - no files will be processed');
+        }
+    }
+    // Validate exclude
+    if (exclude !== undefined && exclude !== null) {
+        if (!Array.isArray(exclude)) {
+            throw new Error(`Config error: exclude must be an array, got ${typeof exclude}`);
+        }
+        for (let i = 0; i < exclude.length; i++) {
+            if (typeof exclude[i] !== 'string') {
+                throw new Error(`Config error: exclude[${i}] must be a string, got ${typeof exclude[i]}`);
+            }
+            if (!exclude[i].trim()) {
+                throw new Error(`Config error: exclude[${i}] cannot be empty or whitespace-only`);
+            }
+        }
+    }
+}
+/**
+ * Merge user config with defaults.
+ * User config takes precedence, but missing sections use defaults.
+ */
+function mergeConfig(defaults, user) {
+    return {
+        plugins: {
+            discovery: user.plugins?.discovery ?? defaults.plugins.discovery,
+            indexing: user.plugins?.indexing ?? defaults.plugins.indexing,
+            analysis: user.plugins?.analysis ?? defaults.plugins.analysis,
+            enrichment: user.plugins?.enrichment ?? defaults.plugins.enrichment,
+            validation: user.plugins?.validation ?? defaults.plugins.validation,
+        },
+        services: user.services ?? defaults.services,
+        // Include/exclude patterns: pass through if specified, otherwise undefined
+        // (don't merge with defaults - undefined means "no filtering")
+        // Note: YAML null becomes undefined here (null ?? undefined = undefined)
+        include: user.include ?? undefined,
+        exclude: user.exclude ?? undefined,
+        strict: user.strict ?? defaults.strict,
+    };
+}

package/dist/config/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Configuration loading utilities
+ */
+export { loadConfig, DEFAULT_CONFIG } from './ConfigLoader.js';
+export type { GrafemaConfig } from './ConfigLoader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/config/index.js

@@ -0,0 +1,4 @@
+/**
+ * Configuration loading utilities
+ */
+export { loadConfig, DEFAULT_CONFIG } from './ConfigLoader.js';

package/dist/core/ASTWorker.d.ts

@@ -3,32 +3,13 @@
  *
  * Receives: { filePath, moduleId, moduleName }
  * Returns: { collections } - extracted AST data for GraphBuilder
+ *
+ * Uses ScopeTracker for semantic ID generation (REG-133).
+ * IDs are stable and don't change when unrelated code is added/removed.
  */
-/**
- * Import node structure
- */
-interface ImportNode {
-    id: string;
-    type: 'IMPORT';
-    name: string;
-    importedName: string;
-    source: string;
-    file: string;
-    line: number;
-}
-/**
- * Export node structure
- */
-interface ExportNode {
-    id: string;
-    type: 'EXPORT';
-    name: string;
-    exportType?: string;
-    localName?: string;
-    isDefault?: boolean;
-    file: string;
-    line: number;
-}
+import { type ClassNodeRecord } from './nodes/ClassNode.js';
+import { type ImportNodeRecord } from './nodes/ImportNode.js';
+import { type ExportNodeRecord } from './nodes/ExportNode.js';
 /**
  * Variable declaration node
  */
@@ -56,7 +37,6 @@ interface ClassInstantiationInfo {
  */
 interface FunctionNode {
     id: string;
-    stableId: string;
     type: 'FUNCTION' | 'METHOD';
     name: string;
     file: string;
@@ -84,15 +64,10 @@ interface ParameterNode {
     line: number;
 }
 /**
- * Class declaration node
+ * Class declaration node (matches ClassNodeRecord from ClassNode factory)
+ * Workers use legacy line-based IDs
  */
-interface ClassDeclarationNode {
-    id: string;
-    type: 'CLASS';
-    name: string;
-    file: string;
-    line: number;
-    superClass: string | null;
+interface ClassDeclarationNode extends ClassNodeRecord {
 }
 /**
  * Call site node
@@ -123,8 +98,8 @@ export interface ASTCollections {
     classDeclarations: ClassDeclarationNode[];
     methodCallbacks: unknown[];
     callArguments: unknown[];
-    imports: ImportNode[];
-    exports: ExportNode[];
+    imports: ImportNodeRecord[];
+    exports: ExportNodeRecord[];
     httpRequests: unknown[];
     literals: unknown[];
     variableAssignments: unknown[];

package/dist/core/ASTWorker.d.ts.map

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