@grafema/core 0.2.4-beta → 0.2.6-beta

package/dist/index.js

@@ -2,36 +2,51 @@
  * @grafema/core - Core analysis engine for GraphDD
  */
 // Error types
-export { GrafemaError, ConfigError, FileAccessError, LanguageError, DatabaseError, PluginError, AnalysisError, ValidationError, StrictModeError, } from './errors/GrafemaError.js';
+export { GrafemaError, ConfigError, FileAccessError, LanguageError, DatabaseError, PluginError, AnalysisError, ValidationError, StrictModeError, StrictModeFailure, } from './errors/GrafemaError.js';
 // Logging
-export { ConsoleLogger, createLogger } from './logging/Logger.js';
+export { ConsoleLogger, FileLogger, MultiLogger, createLogger } from './logging/Logger.js';
 // Diagnostics
 export { DiagnosticCollector, DiagnosticReporter, DiagnosticWriter } from './diagnostics/index.js';
+// Diagnostic categories (single source of truth)
+export { DIAGNOSTIC_CATEGORIES, CODE_TO_CATEGORY, getCategoryForCode, getCodesForCategory } from './diagnostics/index.js';
 // Config
-export { loadConfig, DEFAULT_CONFIG } from './config/index.js';
+export { loadConfig, DEFAULT_CONFIG, validateVersion, validateServices, validatePatterns, validateWorkspace, validateRouting, } from './config/index.js';
+// Version
+export { GRAFEMA_VERSION, getSchemaVersion } from './version.js';
+// Instructions (for AI agents)
+export { getOnboardingInstruction } from './instructions/index.js';
 // Main orchestrator
 export { Orchestrator } from './Orchestrator.js';
 // Plugin base
-export { Plugin } from './plugins/Plugin.js';
+export { Plugin, createSuccessResult, createErrorResult } from './plugins/Plugin.js';
+export { InfraAnalyzer } from './plugins/InfraAnalyzer.js';
 // Graph backend
 export { GraphBackend, typeToKind, edgeTypeToNumber } from './core/GraphBackend.js';
 // RFDB
 export { RFDBClient } from '@grafema/rfdb-client';
 export { RFDBServerBackend } from './storage/backends/RFDBServerBackend.js';
-export { findRfdbBinary, getPlatformDir, getBinaryNotFoundMessage } from './utils/findRfdbBinary.js';
 // Core utilities
 export { NodeFactory } from './core/NodeFactory.js';
 export { Profiler } from './core/Profiler.js';
-export { computeSemanticId, parseSemanticId, computeDiscriminator } from './core/SemanticId.js';
+export { computeSemanticId, parseSemanticId, computeDiscriminator, computeSemanticIdV2, parseSemanticIdV2, computeContentHash } from './core/SemanticId.js';
 export { ScopeTracker } from './core/ScopeTracker.js';
 export { AnalysisQueue } from './core/AnalysisQueue.js';
 export { ASTWorkerPool } from './core/ASTWorkerPool.js';
 export { GuaranteeManager } from './core/GuaranteeManager.js';
+export { toposort, CycleError } from './core/toposort.js';
+export { buildDependencyGraph } from './core/buildDependencyGraph.js';
 export { clearFileNodesIfNeeded, clearServiceNodeIfExists } from './core/FileNodeManager.js';
 export { CoverageAnalyzer } from './core/CoverageAnalyzer.js';
 export { FileExplainer } from './core/FileExplainer.js';
+export { FileOverview } from './core/FileOverview.js';
 // Hash utilities
 export { calculateFileHash, calculateFileHashAsync, calculateContentHash } from './core/HashUtils.js';
+// RFDB binary finder utilities (REG-410)
+export { findRfdbBinary, getBinaryNotFoundMessage, getPlatformDir } from './utils/findRfdbBinary.js';
+// Module resolution utilities (REG-320)
+export { resolveModulePath, isRelativeImport, resolveRelativeSpecifier, DEFAULT_EXTENSIONS, DEFAULT_INDEX_FILES } from './utils/moduleResolution.js';
+// Node file path resolution (REG-408)
+export { resolveNodeFile } from './utils/resolveNodeFile.js';
 // Type validation and path validation
 export { levenshtein, checkTypoAgainstKnownTypes, resetKnownNodeTypes, getKnownNodeTypes } from './storage/backends/typeValidation.js';
 export { PathValidator } from './validation/PathValidator.js';
@@ -44,9 +59,13 @@ export { IncrementalReanalyzer } from './core/IncrementalReanalyzer.js';
 export { GraphAPI } from './api/GraphAPI.js';
 export { GuaranteeAPI } from './api/GuaranteeAPI.js';
 // Node kinds
-export { isGuaranteeType } from './core/nodes/NodeKind.js';
+export { isGuaranteeType, isGrafemaType } from './core/nodes/NodeKind.js';
 // Issue nodes (detected problems)
 export { IssueNode } from './core/nodes/IssueNode.js';
+// Plugin nodes (self-describing pipeline)
+export { PluginNode } from './core/nodes/PluginNode.js';
+// Guarantee nodes (contract-based)
+export { GuaranteeNode } from './core/nodes/GuaranteeNode.js';
 // Node contracts
 export { FunctionNode } from './core/nodes/FunctionNode.js';
 export { CallSiteNode } from './core/nodes/CallSiteNode.js';
@@ -57,13 +76,17 @@ export { MethodNode } from './core/nodes/MethodNode.js';
 export { ExportNode } from './core/nodes/ExportNode.js';
 export { VariableDeclarationNode } from './core/nodes/VariableDeclarationNode.js';
 export { ExternalModuleNode } from './core/nodes/ExternalModuleNode.js';
+export { ExternalFunctionNode } from './core/nodes/ExternalFunctionNode.js';
 export { NetworkRequestNode } from './core/nodes/NetworkRequestNode.js';
 export { InterfaceNode } from './core/nodes/InterfaceNode.js';
 export { TypeNode } from './core/nodes/TypeNode.js';
+export { TypeParameterNode } from './core/nodes/TypeParameterNode.js';
 export { EnumNode } from './core/nodes/EnumNode.js';
 export { DecoratorNode } from './core/nodes/DecoratorNode.js';
 export { ExpressionNode } from './core/nodes/ExpressionNode.js';
 export { ArgumentExpressionNode } from './core/nodes/ArgumentExpressionNode.js';
+// AST CollisionResolver (v2 semantic ID disambiguation)
+export { CollisionResolver } from './plugins/analysis/ast/CollisionResolver.js';
 // AST Visitors (for advanced usage)
 export { ASTVisitor, ImportExportVisitor, VariableVisitor, FunctionVisitor, ClassVisitor, CallExpressionVisitor, TypeScriptVisitor } from './plugins/analysis/ast/visitors/index.js';
 // AST Location utilities (REG-122)
@@ -77,10 +100,12 @@ export { RustModuleIndexer } from './plugins/indexing/RustModuleIndexer.js';
 export { JSASTAnalyzer } from './plugins/analysis/JSASTAnalyzer.js';
 export { ExpressRouteAnalyzer } from './plugins/analysis/ExpressRouteAnalyzer.js';
 export { ExpressResponseAnalyzer } from './plugins/analysis/ExpressResponseAnalyzer.js';
+export { NestJSRouteAnalyzer } from './plugins/analysis/NestJSRouteAnalyzer.js';
 export { ExpressAnalyzer } from './plugins/analysis/ExpressAnalyzer.js';
 export { SocketIOAnalyzer } from './plugins/analysis/SocketIOAnalyzer.js';
 export { DatabaseAnalyzer } from './plugins/analysis/DatabaseAnalyzer.js';
 export { FetchAnalyzer } from './plugins/analysis/FetchAnalyzer.js';
+export { SocketAnalyzer } from './plugins/analysis/SocketAnalyzer.js';
 export { ServiceLayerAnalyzer } from './plugins/analysis/ServiceLayerAnalyzer.js';
 export { ReactAnalyzer } from './plugins/analysis/ReactAnalyzer.js';
 export { RustAnalyzer } from './plugins/analysis/RustAnalyzer.js';
@@ -88,7 +113,7 @@ export { SQLiteAnalyzer } from './plugins/analysis/SQLiteAnalyzer.js';
 export { SystemDbAnalyzer } from './plugins/analysis/SystemDbAnalyzer.js';
 export { IncrementalAnalysisPlugin } from './plugins/analysis/IncrementalAnalysisPlugin.js';
 // Enrichment plugins
-export { MethodCallResolver } from './plugins/enrichment/MethodCallResolver.js';
+export { MethodCallResolver, LIBRARY_SEMANTIC_GROUPS } from './plugins/enrichment/MethodCallResolver.js';
 export { ArgumentParameterLinker } from './plugins/enrichment/ArgumentParameterLinker.js';
 export { AliasTracker } from './plugins/enrichment/AliasTracker.js';
 export { ValueDomainAnalyzer } from './plugins/enrichment/ValueDomainAnalyzer.js';
@@ -96,12 +121,22 @@ export { MountPointResolver } from './plugins/enrichment/MountPointResolver.js';
 export { PrefixEvaluator } from './plugins/enrichment/PrefixEvaluator.js';
 export { InstanceOfResolver } from './plugins/enrichment/InstanceOfResolver.js';
 export { HTTPConnectionEnricher } from './plugins/enrichment/HTTPConnectionEnricher.js';
+export { SocketConnectionEnricher } from './plugins/enrichment/SocketConnectionEnricher.js';
 export { ImportExportLinker } from './plugins/enrichment/ImportExportLinker.js';
 export { FunctionCallResolver } from './plugins/enrichment/FunctionCallResolver.js';
 export { RustFFIEnricher } from './plugins/enrichment/RustFFIEnricher.js';
 export { NodejsBuiltinsResolver } from './plugins/enrichment/NodejsBuiltinsResolver.js';
 export { ExternalCallResolver } from './plugins/enrichment/ExternalCallResolver.js';
 export { ClosureCaptureEnricher } from './plugins/enrichment/ClosureCaptureEnricher.js';
+export { ExpressHandlerLinker } from './plugins/enrichment/ExpressHandlerLinker.js';
+export { RejectionPropagationEnricher } from './plugins/enrichment/RejectionPropagationEnricher.js';
+export { CallbackCallResolver } from './plugins/enrichment/CallbackCallResolver.js';
+export { ConfigRoutingMapBuilder } from './plugins/enrichment/ConfigRoutingMapBuilder.js';
+export { ServiceConnectionEnricher } from './plugins/enrichment/ServiceConnectionEnricher.js';
+// Resource system (REG-256)
+export { ResourceRegistryImpl } from './core/ResourceRegistry.js';
+export { RoutingMapImpl, createRoutingMap } from './resources/RoutingMapImpl.js';
+export { InfraResourceMapImpl, createInfraResourceMap } from './resources/InfraResourceMapImpl.js';
 // Builtin registry
 export { BuiltinRegistry } from './data/builtins/index.js';
 // Globals registry
@@ -110,12 +145,14 @@ export { GlobalsRegistry, ALL_GLOBALS } from './data/globals/index.js';
 export { CallResolverValidator } from './plugins/validation/CallResolverValidator.js';
 export { EvalBanValidator } from './plugins/validation/EvalBanValidator.js';
 export { SQLInjectionValidator } from './plugins/validation/SQLInjectionValidator.js';
+export { AwaitInLoopValidator } from './plugins/validation/AwaitInLoopValidator.js';
 export { ShadowingDetector } from './plugins/validation/ShadowingDetector.js';
 export { GraphConnectivityValidator } from './plugins/validation/GraphConnectivityValidator.js';
 export { DataFlowValidator } from './plugins/validation/DataFlowValidator.js';
 export { TypeScriptDeadCodeValidator } from './plugins/validation/TypeScriptDeadCodeValidator.js';
-export { NodeCreationValidator } from './plugins/validation/NodeCreationValidator.js';
 export { BrokenImportValidator } from './plugins/validation/BrokenImportValidator.js';
+export { UnconnectedRouteValidator } from './plugins/validation/UnconnectedRouteValidator.js';
+export { PackageCoverageValidator, COVERED_PACKAGES_RESOURCE_ID, createCoveredPackagesResource } from './plugins/validation/PackageCoverageValidator.js';
 // Discovery plugins
 export { SimpleProjectDiscovery } from './plugins/discovery/SimpleProjectDiscovery.js';
 export { DiscoveryPlugin } from './plugins/discovery/DiscoveryPlugin.js';
@@ -131,3 +168,5 @@ export { VCSPlugin, VCSPluginFactory, FileStatus } from './plugins/vcs/VCSPlugin
 export { InterfaceSchemaExtractor, GraphSchemaExtractor } from './schema/index.js';
 // Graph Query Utilities
 export { findCallsInFunction, findContainingFunction, traceValues, aggregateValues, NONDETERMINISTIC_PATTERNS, NONDETERMINISTIC_OBJECTS } from './queries/index.js';
+export { buildNodeContext, getNodeDisplayName, formatEdgeMetadata, STRUCTURAL_EDGE_TYPES } from './queries/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/instructions/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Get the onboarding instruction document.
+ *
+ * Returns the full markdown text of the onboarding procedure
+ * that guides an AI agent through project study and configuration.
+ */
+export declare function getOnboardingInstruction(): string;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/instructions/index.ts"],"names":[],"mappings":"AAYA;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD"}

package/dist/instructions/index.js

@@ -0,0 +1,20 @@
+/**
+ * Grafema instruction documents for AI agents.
+ *
+ * Instructions are markdown documents that guide agent behavior.
+ * They are read at runtime from the installed package.
+ */
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Get the onboarding instruction document.
+ *
+ * Returns the full markdown text of the onboarding procedure
+ * that guides an AI agent through project study and configuration.
+ */
+export function getOnboardingInstruction() {
+    return readFileSync(join(__dirname, 'onboarding.md'), 'utf-8');
+}
+//# sourceMappingURL=index.js.map

package/dist/instructions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/instructions/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,EAAE,OAAO,CAAC,CAAC;AACjE,CAAC"}

package/dist/instructions/onboarding.md

@@ -0,0 +1,121 @@
+# Grafema Project Onboarding
+
+## Goal
+Study the target project and create a `.grafema/config.yaml` that correctly
+describes its services, entry points, and analysis configuration.
+
+## Prerequisites
+- The project directory exists and contains source code
+- `.grafema/` directory exists (run `grafema init` if not)
+
+## Step 1: Initial Reconnaissance
+
+Use `read_project_structure` to get the directory tree.
+
+Look for:
+- `package.json` in root and subdirectories (indicates JS/TS packages)
+- `pnpm-workspace.yaml`, `lerna.json`, root `package.json` with `workspaces`
+  field (workspace/monorepo indicators)
+- `tsconfig.json` files (TypeScript project)
+- `Dockerfile`, `docker-compose.yml`, `k8s/`, `apps.json` (deployment configs
+  that may reveal service boundaries)
+- Directories named `apps/`, `packages/`, `services/`, `pkg/`, `modules/`
+  (common monorepo structures)
+
+## Step 2: Identify Services
+
+A "service" in Grafema is an independently analyzable unit of code with its
+own entry point. Typically:
+- A standalone application (API server, web app, CLI tool)
+- A package in a monorepo that other packages depend on
+- A microservice in a deployment configuration
+
+For each potential service, determine:
+1. **Name** — human-readable identifier (e.g., "backend", "dashboard")
+2. **Path** — directory path relative to project root
+3. **Entry point** — the main source file (prefer TypeScript source over
+   compiled output)
+
+### How to find entry points
+Check in order:
+1. `package.json` "source" field (TypeScript source entry)
+2. `package.json` "main" field, but look for `.ts` equivalent in `src/`
+3. Common patterns: `src/index.ts`, `src/main.ts`, `src/app.ts`,
+   `src/server.ts`, `index.ts`
+4. For React apps: `src/App.tsx`, `src/index.tsx`
+5. Check `bin` field in package.json for CLI tools
+
+### When to ask the user
+- "I found [X] that looks like [description]. Should I include it as a
+  service?"
+- "This directory has multiple potential entry points: [list].
+  Which should I use?"
+- "I found deployment configuration mentioning services not visible in
+  the code structure. Should I investigate?"
+
+## Step 3: Run Auto-Discovery (Optional)
+
+Use `discover_services` to see what Grafema's built-in detection finds.
+Compare with your own findings from Steps 1-2. Note discrepancies —
+auto-discovery may miss services or misidentify entry points.
+
+## Step 4: Configure Plugins
+
+Default plugins work for most JS/TS projects. Adjust if:
+- Project uses specific frameworks (Express, React, Socket.IO) — ensure
+  corresponding analyzers are enabled
+- Project has Rust components — add `RustModuleIndexer` and `RustAnalyzer`
+- Project has unusual file patterns — configure `include`/`exclude`
+
+Default plugin list (reference only — omit from config to use defaults):
+  indexing: [JSModuleIndexer]
+  analysis: [JSASTAnalyzer, ExpressRouteAnalyzer, ExpressResponseAnalyzer,
+    SocketIOAnalyzer, DatabaseAnalyzer, FetchAnalyzer, ServiceLayerAnalyzer]
+  enrichment: [MethodCallResolver, ArgumentParameterLinker, AliasTracker,
+    ClosureCaptureEnricher, RejectionPropagationEnricher, ValueDomainAnalyzer,
+    MountPointResolver, ExpressHandlerLinker, PrefixEvaluator,
+    ImportExportLinker, HTTPConnectionEnricher]
+  validation: [GraphConnectivityValidator, DataFlowValidator, EvalBanValidator,
+    CallResolverValidator, SQLInjectionValidator, ShadowingDetector,
+    TypeScriptDeadCodeValidator, BrokenImportValidator]
+
+## Step 5: Write Configuration
+
+Use `write_config` to save the discovered configuration.
+
+The config should include:
+- `services` array with all confirmed services (name, path, optional entryPoint)
+- `plugins` section (only if overriding defaults)
+- `include`/`exclude` patterns (only if needed)
+- `workspace.roots` (for multi-root workspaces only)
+
+## Step 6: Verify
+
+Run `analyze_project` to build the graph. Then check:
+- `get_stats` — are node/edge counts reasonable for the project size?
+- `get_coverage` — are the expected files analyzed?
+
+If coverage is low or results are unexpected, iterate:
+revisit services, entry points, or include/exclude patterns.
+
+## Common Patterns
+
+### Monorepo with workspaces
+Look for `pnpm-workspace.yaml` or `workspaces` in root `package.json`.
+Each workspace package is typically a service. Use `read_project_structure`
+with depth=2 to see the package layout.
+
+### Legacy project with multiple entry points
+Look for `scripts` in `package.json`, `bin` field, or multiple files
+in `src/` that look like entry points (contain `app.listen()`,
+`createServer()`, `express()`).
+
+### Microservices with shared deployment
+Look for `docker-compose.yml`, Kubernetes configs, or similar
+deployment manifests that list services. Cross-reference with
+code directories.
+
+### Single-package project
+If there is only one `package.json` at the root and no monorepo
+structure, the project is likely a single service. The service path
+is `.` (root), and the entry point is determined from `package.json`.

package/dist/logging/Logger.d.ts

@@ -4,12 +4,15 @@
  * Features:
  * - 5 log levels: silent, errors, warnings, info, debug
  * - Context support for structured logging
- * - No external dependencies
+ * - Console and file output (or both via MultiLogger)
  * - Safe handling of circular references
  *
  * Usage:
  *   const logger = createLogger('info');
  *   logger.info('Processing files', { count: 150 });
+ *
+ *   // Write logs to file (REG-199):
+ *   const logger = createLogger('info', { logFile: '.grafema/analysis.log' });
  */
 /**
  * Log level type
@@ -42,7 +45,54 @@ export declare class ConsoleLogger implements Logger {
     trace(message: string, context?: Record<string, unknown>): void;
 }
 /**
- * Create a Logger instance with the specified log level
+ * File-based Logger implementation (REG-199)
+ *
+ * Writes log messages to a file with ISO timestamps using a write stream
+ * (non-blocking I/O). File is truncated on construction (overwritten each run).
+ * Parent directories are created automatically.
+ *
+ * Validates path on construction — throws if the directory is not writable
+ * or the path points to a directory.
+ */
+export declare class FileLogger implements Logger {
+    private readonly priority;
+    private readonly stream;
+    constructor(logLevel: LogLevel, filePath: string);
+    private shouldLog;
+    private writeLine;
+    error(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    debug(message: string, context?: Record<string, unknown>): void;
+    trace(message: string, context?: Record<string, unknown>): void;
+    /** Flush and close the write stream. Returns when all data is written. */
+    close(): Promise<void>;
+}
+/**
+ * Multi-output Logger that delegates to multiple Logger instances.
+ *
+ * Each inner logger applies its own level filtering independently.
+ * Used to write to both console and file simultaneously.
+ */
+export declare class MultiLogger implements Logger {
+    private readonly loggers;
+    constructor(loggers: Logger[]);
+    error(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    debug(message: string, context?: Record<string, unknown>): void;
+    trace(message: string, context?: Record<string, unknown>): void;
+    /** Close all inner loggers that have a close() method (e.g., FileLogger). */
+    close(): Promise<void>;
+}
+/**
+ * Create a Logger instance with the specified log level.
+ *
+ * When logFile is specified, returns a MultiLogger that writes to both
+ * console and file. The file logger always captures at 'debug' level
+ * for complete post-mortem debugging, regardless of the console level.
  */
-export declare function createLogger(level: LogLevel): Logger;
+export declare function createLogger(level: LogLevel, options?: {
+    logFile?: string;
+}): Logger;
 //# sourceMappingURL=Logger.d.ts.map

package/dist/logging/Logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/logging/Logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACjE;AAsDD;;;;GAIG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,GAAE,QAAiB;IAKvC,OAAO,CAAC,SAAS;IAIjB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAS/D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAS9D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAS9D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAS/D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAQhE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/logging/Logger.ts"],"names":[],"mappings":"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"}

package/dist/logging/Logger.js

@@ -4,13 +4,18 @@
  * Features:
  * - 5 log levels: silent, errors, warnings, info, debug
  * - Context support for structured logging
- * - No external dependencies
+ * - Console and file output (or both via MultiLogger)
  * - Safe handling of circular references
  *
  * Usage:
  *   const logger = createLogger('info');
  *   logger.info('Processing files', { count: 150 });
+ *
+ *   // Write logs to file (REG-199):
+ *   const logger = createLogger('info', { logFile: '.grafema/analysis.log' });
  */
+import { createWriteStream, writeFileSync, mkdirSync, accessSync, statSync, constants } from 'fs';
+import { dirname, resolve } from 'path';
 /**
  * Log level priorities (higher = more verbose)
  */
@@ -127,8 +132,143 @@ export class ConsoleLogger {
     }
 }
 /**
- * Create a Logger instance with the specified log level
+ * File-based Logger implementation (REG-199)
+ *
+ * Writes log messages to a file with ISO timestamps using a write stream
+ * (non-blocking I/O). File is truncated on construction (overwritten each run).
+ * Parent directories are created automatically.
+ *
+ * Validates path on construction — throws if the directory is not writable
+ * or the path points to a directory.
+ */
+export class FileLogger {
+    priority;
+    stream;
+    constructor(logLevel, filePath) {
+        this.priority = LOG_LEVEL_PRIORITY[logLevel];
+        const resolvedPath = resolve(filePath);
+        // Create parent directories
+        const dir = dirname(resolvedPath);
+        mkdirSync(dir, { recursive: true });
+        // Validate: parent directory must be writable
+        try {
+            accessSync(dir, constants.W_OK);
+        }
+        catch {
+            throw new Error(`Cannot write log file: directory '${dir}' is not writable`);
+        }
+        // Validate: path must not point to an existing directory
+        try {
+            if (statSync(resolvedPath).isDirectory()) {
+                throw new Error(`Cannot write log file: '${resolvedPath}' is a directory`);
+            }
+        }
+        catch (e) {
+            // If stat throws, file doesn't exist yet — that's fine
+            if (e instanceof Error && e.message.includes('is a directory'))
+                throw e;
+        }
+        // Truncate/create file synchronously (validates writeability),
+        // then open stream in append mode for non-blocking writes
+        writeFileSync(resolvedPath, '');
+        this.stream = createWriteStream(resolvedPath, { flags: 'a' });
+        this.stream.on('error', () => {
+            // Silently ignore stream errors — don't crash analysis for logging failures
+        });
+    }
+    shouldLog(methodLevel) {
+        return this.priority >= methodLevel;
+    }
+    writeLine(level, message, context) {
+        const timestamp = new Date().toISOString();
+        const formatted = formatMessage(`${timestamp} [${level}] ${message}`, context);
+        this.stream.write(formatted + '\n');
+    }
+    error(message, context) {
+        if (!this.shouldLog(METHOD_LEVELS.error))
+            return;
+        this.writeLine('ERROR', message, context);
+    }
+    warn(message, context) {
+        if (!this.shouldLog(METHOD_LEVELS.warn))
+            return;
+        this.writeLine('WARN', message, context);
+    }
+    info(message, context) {
+        if (!this.shouldLog(METHOD_LEVELS.info))
+            return;
+        this.writeLine('INFO', message, context);
+    }
+    debug(message, context) {
+        if (!this.shouldLog(METHOD_LEVELS.debug))
+            return;
+        this.writeLine('DEBUG', message, context);
+    }
+    trace(message, context) {
+        if (!this.shouldLog(METHOD_LEVELS.trace))
+            return;
+        this.writeLine('TRACE', message, context);
+    }
+    /** Flush and close the write stream. Returns when all data is written. */
+    close() {
+        return new Promise((resolve) => {
+            this.stream.end(resolve);
+        });
+    }
+}
+/**
+ * Multi-output Logger that delegates to multiple Logger instances.
+ *
+ * Each inner logger applies its own level filtering independently.
+ * Used to write to both console and file simultaneously.
+ */
+export class MultiLogger {
+    loggers;
+    constructor(loggers) {
+        this.loggers = loggers;
+    }
+    error(message, context) {
+        for (const logger of this.loggers)
+            logger.error(message, context);
+    }
+    warn(message, context) {
+        for (const logger of this.loggers)
+            logger.warn(message, context);
+    }
+    info(message, context) {
+        for (const logger of this.loggers)
+            logger.info(message, context);
+    }
+    debug(message, context) {
+        for (const logger of this.loggers)
+            logger.debug(message, context);
+    }
+    trace(message, context) {
+        for (const logger of this.loggers)
+            logger.trace(message, context);
+    }
+    /** Close all inner loggers that have a close() method (e.g., FileLogger). */
+    async close() {
+        for (const logger of this.loggers) {
+            if (logger instanceof FileLogger) {
+                await logger.close();
+            }
+        }
+    }
+}
+/**
+ * Create a Logger instance with the specified log level.
+ *
+ * When logFile is specified, returns a MultiLogger that writes to both
+ * console and file. The file logger always captures at 'debug' level
+ * for complete post-mortem debugging, regardless of the console level.
  */
-export function createLogger(level) {
-    return new ConsoleLogger(level);
+export function createLogger(level, options) {
+    const consoleLogger = new ConsoleLogger(level);
+    if (options?.logFile) {
+        const fileLogger = new FileLogger('debug', options.logFile);
+        return new MultiLogger([consoleLogger, fileLogger]);
+    }
+    return consoleLogger;
 }
+//# sourceMappingURL=Logger.js.map

package/dist/logging/Logger.js.map

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