bluera-knowledge 0.9.31 → 0.9.34

package/src/services/code-graph.service.test.ts

@@ -32,16 +32,16 @@ export function doWork() {
   helper();
   return 'done';
 }
-`
-        }
+`,
+        },
       ];
 
       const graph = await service.buildGraph(files);
       const nodes = graph.getAllNodes();
 
       expect(nodes.length).toBe(2);
-      expect(nodes.some(n => n.name === 'helper')).toBe(true);
-      expect(nodes.some(n => n.name === 'doWork')).toBe(true);
+      expect(nodes.some((n) => n.name === 'helper')).toBe(true);
+      expect(nodes.some((n) => n.name === 'doWork')).toBe(true);
     });
 
     it('should track function calls', async () => {
@@ -56,15 +56,15 @@ function caller() {
 function callee() {
   return 42;
 }
-`
-        }
+`,
+        },
       ];
 
       const graph = await service.buildGraph(files);
 
       // Check that caller calls callee
       const callerEdges = graph.getEdges('/src/main.ts:caller');
-      const callsCallee = callerEdges.some(e => e.to.includes('callee') && e.type === 'calls');
+      const callsCallee = callerEdges.some((e) => e.to.includes('callee') && e.type === 'calls');
       expect(callsCallee).toBe(true);
     });
 
@@ -78,13 +78,13 @@ import { helper } from './utils.js';
 function useHelper() {
   helper();
 }
-`
-        }
+`,
+        },
       ];
 
       const graph = await service.buildGraph(files);
       const consumerEdges = graph.getEdges('/src/consumer.ts');
-      const hasImport = consumerEdges.some(e => e.type === 'imports');
+      const hasImport = consumerEdges.some((e) => e.type === 'imports');
       expect(hasImport).toBe(true);
     });
 
@@ -92,7 +92,7 @@ function useHelper() {
       const files = [
         { path: '/src/readme.md', content: '# README\n\nThis is docs.' },
         { path: '/src/config.json', content: '{"key": "value"}' },
-        { path: '/src/main.ts', content: 'export function main() {}' }
+        { path: '/src/main.ts', content: 'export function main() {}' },
       ];
 
       const graph = await service.buildGraph(files);
@@ -114,8 +114,8 @@ function useHelper() {
 export function helper() {
   return 'help';
 }
-`
-        }
+`,
+        },
       ];
 
       const graph = await service.buildGraph(files);
@@ -140,9 +140,7 @@ export function helper() {
 
     it('should cache loaded graphs', async () => {
       const storeId = createStoreId('cached-store');
-      const files = [
-        { path: '/src/main.ts', content: 'export function main() {}' }
-      ];
+      const files = [{ path: '/src/main.ts', content: 'export function main() {}' }];
 
       const graph = await service.buildGraph(files);
       await service.saveGraph(storeId, graph);
@@ -157,9 +155,7 @@ export function helper() {
 
     it('should persist graph to JSON file', async () => {
       const storeId = createStoreId('persisted-store');
-      const files = [
-        { path: '/src/main.ts', content: 'export function main() {}' }
-      ];
+      const files = [{ path: '/src/main.ts', content: 'export function main() {}' }];
 
       const graph = await service.buildGraph(files);
       await service.saveGraph(storeId, graph);
@@ -189,8 +185,8 @@ export class Calculator {
     return a - b;
   }
 }
-`
-        }
+`,
+        },
       ];
 
       const graph = await service.buildGraph(files);
@@ -204,13 +200,13 @@ export class Calculator {
 
       const nodes = loadedGraph!.getAllNodes();
       // Should have class + 2 methods
-      const classNode = nodes.find(n => n.name === 'Calculator' && n.type === 'class');
-      const methodNodes = nodes.filter(n => n.type === 'method');
+      const classNode = nodes.find((n) => n.name === 'Calculator' && n.type === 'class');
+      const methodNodes = nodes.filter((n) => n.type === 'method');
 
       expect(classNode).toBeDefined();
       expect(methodNodes.length).toBe(2);
-      expect(methodNodes.some(m => m.name === 'add')).toBe(true);
-      expect(methodNodes.some(m => m.name === 'subtract')).toBe(true);
+      expect(methodNodes.some((m) => m.name === 'add')).toBe(true);
+      expect(methodNodes.some((m) => m.name === 'subtract')).toBe(true);
     });
   });
 
@@ -227,8 +223,8 @@ function caller() {
 function target() {
   return 1;
 }
-`
-        }
+`,
+        },
       ];
 
       const graph = await service.buildGraph(files);
@@ -260,31 +256,29 @@ function target() {
 function callee() {
   return 1;
 }
-`
-        }
+`,
+        },
       ];
 
       const graph = await service.buildGraph(files);
       const related = service.getRelatedCode(graph, '/src/main.ts', 'target');
 
       // target is called by caller (and possibly itself due to regex-based detection)
-      const callers = related.filter(r => r.relationship === 'calls this');
+      const callers = related.filter((r) => r.relationship === 'calls this');
       expect(callers.length).toBeGreaterThanOrEqual(1);
-      expect(callers.some(c => c.id.includes('caller'))).toBe(true);
+      expect(callers.some((c) => c.id.includes('caller'))).toBe(true);
 
       // target calls callee
-      const callees = related.filter(r => r.relationship === 'called by this');
+      const callees = related.filter((r) => r.relationship === 'called by this');
       expect(callees.length).toBeGreaterThanOrEqual(1);
-      expect(callees.some(c => c.id.includes('callee'))).toBe(true);
+      expect(callees.some((c) => c.id.includes('callee'))).toBe(true);
     });
   });
 
   describe('clearCache', () => {
     it('should clear cached graphs', async () => {
       const storeId = createStoreId('cache-test');
-      const files = [
-        { path: '/src/main.ts', content: 'export function main() {}' }
-      ];
+      const files = [{ path: '/src/main.ts', content: 'export function main() {}' }];
 
       const graph = await service.buildGraph(files);
       await service.saveGraph(storeId, graph);

package/src/services/code-graph.service.ts

@@ -1,10 +1,10 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { CodeGraph, type GraphNode } from '../analysis/code-graph.js';
 import { ASTParser } from '../analysis/ast-parser.js';
-import { RustASTParser } from '../analysis/rust-ast-parser.js';
+import { CodeGraph, type GraphNode } from '../analysis/code-graph.js';
 import { GoASTParser } from '../analysis/go-ast-parser.js';
 import { ParserFactory } from '../analysis/parser-factory.js';
+import { RustASTParser } from '../analysis/rust-ast-parser.js';
 import type { PythonBridge } from '../crawl/bridge.js';
 import type { StoreId } from '../types/brands.js';
 
@@ -157,7 +157,7 @@ export class CodeGraphService {
             name: node.name,
             exported: node.exported,
             startLine: node.startLine,
-            endLine: node.endLine
+            endLine: node.endLine,
           };
           if (node.signature !== undefined) {
             graphNode.signature = node.signature;
@@ -195,7 +195,7 @@ export class CodeGraphService {
           from: edge.from,
           to: edge.to,
           type: edgeType,
-          confidence: edge.confidence
+          confidence: edge.confidence,
         });
       }
 
@@ -209,18 +209,26 @@ export class CodeGraphService {
   /**
    * Get usage stats for a code element.
    */
-  getUsageStats(graph: CodeGraph, filePath: string, symbolName: string): { calledBy: number; calls: number } {
+  getUsageStats(
+    graph: CodeGraph,
+    filePath: string,
+    symbolName: string
+  ): { calledBy: number; calls: number } {
     const nodeId = `${filePath}:${symbolName}`;
     return {
       calledBy: graph.getCalledByCount(nodeId),
-      calls: graph.getCallsCount(nodeId)
+      calls: graph.getCallsCount(nodeId),
     };
   }
 
   /**
    * Get related code (callers and callees) for a code element.
    */
-  getRelatedCode(graph: CodeGraph, filePath: string, symbolName: string): Array<{ id: string; relationship: string }> {
+  getRelatedCode(
+    graph: CodeGraph,
+    filePath: string,
+    symbolName: string
+  ): Array<{ id: string; relationship: string }> {
     const nodeId = `${filePath}:${symbolName}`;
     const related: Array<{ id: string; relationship: string }> = [];
 
@@ -269,14 +277,18 @@ export class CodeGraphService {
   /**
    * Type guard for valid node types.
    */
-  private isValidNodeType(type: string): type is 'function' | 'class' | 'interface' | 'type' | 'const' | 'method' {
+  private isValidNodeType(
+    type: string
+  ): type is 'function' | 'class' | 'interface' | 'type' | 'const' | 'method' {
     return ['function', 'class', 'interface', 'type', 'const', 'method'].includes(type);
   }
 
   /**
    * Validate and return a node type, or undefined if invalid.
    */
-  private validateNodeType(type: string): 'function' | 'class' | 'interface' | 'type' | 'const' | 'method' | undefined {
+  private validateNodeType(
+    type: string
+  ): 'function' | 'class' | 'interface' | 'type' | 'const' | 'method' | undefined {
     if (this.isValidNodeType(type)) {
       return type;
     }
@@ -293,7 +305,9 @@ export class CodeGraphService {
   /**
    * Validate and return an edge type, or undefined if invalid.
    */
-  private validateEdgeType(type: string): 'calls' | 'imports' | 'extends' | 'implements' | undefined {
+  private validateEdgeType(
+    type: string
+  ): 'calls' | 'imports' | 'extends' | 'implements' | undefined {
     if (this.isValidEdgeType(type)) {
       return type;
     }

package/src/services/code-unit.service.test.ts

@@ -97,7 +97,7 @@ function nested() {
       expect(result?.fullContent).toContain('if (true)');
     });
 
-    it('handles function with braces in string literals', () => {
+    it('correctly handles braces inside double-quoted string literals', () => {
       const code = `
 function withString() {
   const template = "{ this is a brace }";
@@ -107,11 +107,24 @@ function withString() {
 
       const result = service.extractCodeUnit(code, 'withString', 'typescript');
 
-      // NOTE: Current implementation has a bug - it doesn't handle braces in strings
-      // This test documents the current behavior
       expect(result).toBeDefined();
-      // The brace counting may be incorrect due to string literal braces
-      // but it should still complete the extraction
+      expect(result?.endLine).toBe(4);
+      expect(result?.fullContent).toContain('return template');
+    });
+
+    it('correctly handles braces inside single-quoted string literals', () => {
+      const code = `
+function withSingleQuote() {
+  const json = '{"key": "value"}';
+  return json;
+}
+      `.trim();
+
+      const result = service.extractCodeUnit(code, 'withSingleQuote', 'typescript');
+
+      expect(result).toBeDefined();
+      expect(result?.endLine).toBe(4);
+      expect(result?.fullContent).toContain('return json');
     });
 
     it('returns undefined for non-existent function', () => {
@@ -524,7 +537,7 @@ const unrelated = { key: "value" };
       expect(result?.fullContent).not.toContain('unrelated');
     });
 
-    it('handles brace in comments (limitation - not supported)', () => {
+    it('correctly handles braces in single-line comments', () => {
       const code = `
 function withComment() {
   // This comment has a brace: {
@@ -534,15 +547,30 @@ function withComment() {
 
       const result = service.extractCodeUnit(code, 'withComment', 'typescript');
 
-      // NOTE: Current implementation doesn't handle braces in comments
-      // This may cause incorrect boundary detection
       expect(result).toBeDefined();
+      expect(result?.endLine).toBe(4);
+      expect(result?.fullContent).toContain('return true');
     });
 
-    it('handles template literals with braces (limitation)', () => {
+    it('correctly handles braces in multi-line comments', () => {
+      const code = `
+function withMultiComment() {
+  /* { braces } in comment */
+  return false;
+}
+      `.trim();
+
+      const result = service.extractCodeUnit(code, 'withMultiComment', 'typescript');
+
+      expect(result).toBeDefined();
+      expect(result?.endLine).toBe(4);
+      expect(result?.fullContent).toContain('return false');
+    });
+
+    it('correctly handles template literals with embedded expressions', () => {
       const code = `
 function withTemplate() {
-  const str = \`template \${var} end\`;
+  const str = \`template \${value} end\`;
   return str;
 }
       `.trim();
@@ -550,7 +578,23 @@ function withTemplate() {
       const result = service.extractCodeUnit(code, 'withTemplate', 'typescript');
 
       expect(result).toBeDefined();
-      expect(result?.fullContent).toContain('template');
+      expect(result?.endLine).toBe(4);
+      expect(result?.fullContent).toContain('return str');
+    });
+
+    it('correctly handles template literals with braces in text', () => {
+      const code = `
+function withTemplateBraces() {
+  const json = \`{"key": "value"}\`;
+  return json;
+}
+      `.trim();
+
+      const result = service.extractCodeUnit(code, 'withTemplateBraces', 'typescript');
+
+      expect(result).toBeDefined();
+      expect(result?.endLine).toBe(4);
+      expect(result?.fullContent).toContain('return json');
     });
   });
 

package/src/services/code-unit.service.ts

@@ -43,17 +43,83 @@ export class CodeUnitService {
 
     if (startLine === -1) return undefined;
 
-    // Find end line (naive: next empty line or next top-level declaration)
+    // Find end line using state machine that tracks strings and comments
     let endLine = startLine;
     let braceCount = 0;
     let foundFirstBrace = false;
 
-    // NOTE: This brace counting does not handle braces inside strings or comments.
-    // It may incorrectly determine boundaries if code contains braces in string literals.
+    // State machine for tracking context
+    let inSingleQuote = false;
+    let inDoubleQuote = false;
+    let inTemplateLiteral = false;
+    let inMultiLineComment = false;
+
     for (let i = startLine - 1; i < lines.length; i++) {
       const line = lines[i] ?? '';
+      let inSingleLineComment = false;
+
+      for (let j = 0; j < line.length; j++) {
+        const char = line[j];
+        const prevChar = j > 0 ? line[j - 1] : '';
+        const nextChar = j < line.length - 1 ? line[j + 1] : '';
+
+        // Skip escaped characters within strings
+        if (prevChar === '\\' && (inSingleQuote || inDoubleQuote || inTemplateLiteral)) {
+          continue;
+        }
+
+        // Inside multi-line comment - only look for end marker
+        if (inMultiLineComment) {
+          if (char === '*' && nextChar === '/') {
+            inMultiLineComment = false;
+            j++; // Skip the /
+          }
+          continue;
+        }
+
+        // Inside single-line comment - skip rest of line
+        if (inSingleLineComment) {
+          continue;
+        }
+
+        // Inside a string - only look for closing delimiter
+        if (inSingleQuote) {
+          if (char === "'") inSingleQuote = false;
+          continue;
+        }
+        if (inDoubleQuote) {
+          if (char === '"') inDoubleQuote = false;
+          continue;
+        }
+        if (inTemplateLiteral) {
+          if (char === '`') inTemplateLiteral = false;
+          continue;
+        }
+
+        // Not inside any special context - check for context starters
+        if (char === '/' && nextChar === '*') {
+          inMultiLineComment = true;
+          j++; // Skip the *
+          continue;
+        }
+        if (char === '/' && nextChar === '/') {
+          inSingleLineComment = true;
+          continue;
+        }
+        if (char === "'") {
+          inSingleQuote = true;
+          continue;
+        }
+        if (char === '"') {
+          inDoubleQuote = true;
+          continue;
+        }
+        if (char === '`') {
+          inTemplateLiteral = true;
+          continue;
+        }
 
-      for (const char of line) {
+        // Count braces (we're not inside any string or comment)
         if (char === '{') {
           braceCount++;
           foundFirstBrace = true;
@@ -80,19 +146,22 @@ export class CodeUnitService {
       fullContent,
       startLine,
       endLine,
-      language
+      language,
     };
   }
 
   private extractSignature(line: string, name: string, type: string): string {
     // Remove 'export', 'async', trim whitespace
-    const sig = line.replace(/^\s*export\s+/, '').replace(/^\s*async\s+/, '').trim();
+    const sig = line
+      .replace(/^\s*export\s+/, '')
+      .replace(/^\s*async\s+/, '')
+      .trim();
 
     if (type === 'function') {
       // Extract just "functionName(params): returnType"
-      // TODO: This regex is limited and may not handle complex return types, generics, or multiline signatures
-      const match = sig.match(/function\s+(\w+\([^)]*\):\s*\w+)/);
-      if (match?.[1] !== undefined && match[1].length > 0) return match[1];
+      // Supports: simple types, generics (Promise<T>), arrays (T[]), unions (T | null)
+      const match = sig.match(/function\s+(\w+\([^)]*\):\s*[\w<>[\],\s|]+)/);
+      if (match?.[1] !== undefined && match[1].length > 0) return match[1].trim();
     }
 
     if (type === 'class') {
@@ -103,8 +172,13 @@ export class CodeUnitService {
       // For arrow functions, extract the variable declaration part
       // Example: const myFunc = (param: string): void => ...
       // Returns: const myFunc = (param: string): void
-      const arrowMatch = sig.match(new RegExp(`((?:const|let|var)\\s+${name}\\s*=\\s*(?:async\\s+)?\\([^)]*\\)(?::\\s*[^=]+)?)`));
-      if (arrowMatch?.[1] != null && arrowMatch[1] !== '') return arrowMatch[1].trim();
+      const arrowMatch = sig.match(
+        new RegExp(
+          `((?:const|let|var)\\s+${name}\\s*=\\s*(?:async\\s+)?\\([^)]*\\)(?::\\s*[^=]+)?)`
+        )
+      );
+      const matchedSig = arrowMatch?.[1];
+      if (matchedSig !== undefined && matchedSig !== '') return matchedSig.trim();
 
       // Fallback for simple arrow functions without params
       return `const ${name}`;

package/src/services/config.service.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { ConfigService } from './config.service.js';
-import { rm, mkdtemp } from 'node:fs/promises';
+import { rm, mkdtemp, writeFile, access } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -42,10 +42,7 @@ describe('ConfigService', () => {
 
   describe('path expansion', () => {
     it('expands tilde to home directory', () => {
-      const service = new ConfigService(
-        configPath,
-        '~/.bluera/data'
-      );
+      const service = new ConfigService(configPath, '~/.bluera/data');
       const dataDir = service.resolveDataDir();
       // Note: expandPath is called in constructor, so ~ will be kept
       // since dataDir parameter is explicitly provided
@@ -53,11 +50,7 @@ describe('ConfigService', () => {
     });
 
     it('resolves relative paths against project root', () => {
-      const service = new ConfigService(
-        configPath,
-        undefined,
-        tempDir
-      );
+      const service = new ConfigService(configPath, undefined, tempDir);
       const dataDir = service.resolveDataDir();
       // When dataDir is undefined, it uses DEFAULT_CONFIG.dataDir which is relative
       expect(dataDir).toContain(tempDir);
@@ -65,20 +58,14 @@ describe('ConfigService', () => {
 
     it('keeps absolute paths as-is', () => {
       const absolutePath = '/absolute/path/to/data';
-      const service = new ConfigService(
-        configPath,
-        absolutePath
-      );
+      const service = new ConfigService(configPath, absolutePath);
       const dataDir = service.resolveDataDir();
       expect(dataDir).toBe(absolutePath);
     });
 
     it('uses explicit dataDir when provided', () => {
       const explicitDir = '/explicit/data/dir';
-      const service = new ConfigService(
-        configPath,
-        explicitDir
-      );
+      const service = new ConfigService(configPath, explicitDir);
       const dataDir = service.resolveDataDir();
       expect(dataDir).toBe(explicitDir);
     });
@@ -124,4 +111,36 @@ describe('ConfigService', () => {
       expect(loaded).toBeDefined();
     });
   });
+
+  describe('first-run vs corruption handling (CLAUDE.md compliance)', () => {
+    it('creates config file on first run when missing', async () => {
+      // Config file does not exist
+      const config = await configService.load();
+
+      // Should return default config
+      expect(config.version).toBe(1);
+
+      // File should now exist (created automatically)
+      await expect(access(configPath)).resolves.toBeUndefined();
+    });
+
+    it('throws on corrupted config file', async () => {
+      // Create corrupted config file
+      await writeFile(configPath, '{invalid json syntax');
+
+      // Create fresh service (no cache)
+      const freshService = new ConfigService(configPath, tempDir);
+
+      // Should throw per CLAUDE.md "fail early and fast"
+      await expect(freshService.load()).rejects.toThrow();
+    });
+
+    it('throws with descriptive message on JSON parse error', async () => {
+      await writeFile(configPath, '{"incomplete":');
+
+      const freshService = new ConfigService(configPath, tempDir);
+
+      await expect(freshService.load()).rejects.toThrow(/JSON|parse|config/i);
+    });
+  });
 });

package/src/services/config.service.ts

@@ -1,9 +1,21 @@
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
+import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import type { AppConfig } from '../types/config.js';
-import { DEFAULT_CONFIG } from '../types/config.js';
+import { dirname, resolve } from 'node:path';
 import { ProjectRootService } from './project-root.service.js';
+import { DEFAULT_CONFIG } from '../types/config.js';
+import type { AppConfig } from '../types/config.js';
+
+/**
+ * Check if a file exists
+ */
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 export class ConfigService {
   private readonly configPath: string;
@@ -33,12 +45,23 @@ export class ConfigService {
       return this.config;
     }
 
+    const exists = await fileExists(this.configPath);
+    if (!exists) {
+      // First run - create config file with defaults
+      this.config = { ...DEFAULT_CONFIG };
+      await this.save(this.config);
+      return this.config;
+    }
+
+    // File exists - load it (throws on corruption per CLAUDE.md "fail early")
+    const content = await readFile(this.configPath, 'utf-8');
     try {
-      const content = await readFile(this.configPath, 'utf-8');
       // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
       this.config = { ...DEFAULT_CONFIG, ...JSON.parse(content) } as AppConfig;
-    } catch {
-      this.config = { ...DEFAULT_CONFIG };
+    } catch (error) {
+      throw new Error(
+        `Failed to parse config file at ${this.configPath}: ${error instanceof Error ? error.message : String(error)}`
+      );
     }
 
     return this.config;