bluera-knowledge 0.9.21

package/src/types/config.ts

@@ -0,0 +1,79 @@
+export interface EmbeddingConfig {
+  readonly model: string;
+  readonly batchSize: number;
+  readonly dimensions: number;
+}
+
+export interface IndexingConfig {
+  readonly concurrency: number;
+  readonly chunkSize: number;
+  readonly chunkOverlap: number;
+  readonly ignorePatterns: readonly string[];
+}
+
+export interface SearchConfig {
+  readonly defaultMode: 'vector' | 'fts' | 'hybrid';
+  readonly defaultLimit: number;
+  readonly minScore: number;
+  readonly rrf: {
+    readonly k: number;
+    readonly vectorWeight: number;
+    readonly ftsWeight: number;
+  };
+}
+
+export interface CrawlConfig {
+  readonly userAgent: string;
+  readonly timeout: number;
+  readonly maxConcurrency: number;
+}
+
+export interface ServerConfig {
+  readonly port: number;
+  readonly host: string;
+}
+
+export interface AppConfig {
+  readonly version: number;
+  readonly dataDir: string;
+  readonly embedding: EmbeddingConfig;
+  readonly indexing: IndexingConfig;
+  readonly search: SearchConfig;
+  readonly crawl: CrawlConfig;
+  readonly server: ServerConfig;
+}
+
+export const DEFAULT_CONFIG: AppConfig = {
+  version: 1,
+  dataDir: '.bluera/bluera-knowledge/data',
+  embedding: {
+    model: 'Xenova/all-MiniLM-L6-v2',
+    batchSize: 32,
+    dimensions: 384,
+  },
+  indexing: {
+    concurrency: 4,
+    chunkSize: 1000,
+    chunkOverlap: 150,
+    ignorePatterns: ['node_modules/**', '.git/**', '*.min.js', '*.map'],
+  },
+  search: {
+    defaultMode: 'hybrid',
+    defaultLimit: 10,
+    minScore: 0.5,
+    rrf: {
+      k: 40,
+      vectorWeight: 0.7,
+      ftsWeight: 0.3,
+    },
+  },
+  crawl: {
+    userAgent: 'BlueraKnowledge/1.0',
+    timeout: 30000,
+    maxConcurrency: 3,
+  },
+  server: {
+    port: 3847,
+    host: '127.0.0.1',
+  },
+};

package/src/types/document.ts

@@ -0,0 +1,30 @@
+import type { DocumentId, StoreId } from './brands.js';
+
+export type DocumentType = 'file' | 'chunk' | 'web';
+
+export interface DocumentMetadata {
+  readonly path?: string | undefined;
+  readonly url?: string | undefined;
+  readonly type: DocumentType;
+  readonly storeId: StoreId;
+  readonly indexedAt: Date;
+  readonly fileHash?: string | undefined;
+  readonly chunkIndex?: number | undefined;
+  readonly totalChunks?: number | undefined;
+  readonly [key: string]: unknown;
+}
+
+export interface Document {
+  readonly id: DocumentId;
+  readonly content: string;
+  readonly vector: readonly number[];
+  readonly metadata: DocumentMetadata;
+}
+
+export interface DocumentChunk {
+  readonly id: DocumentId;
+  readonly content: string;
+  readonly startLine?: number | undefined;
+  readonly endLine?: number | undefined;
+  readonly metadata: DocumentMetadata;
+}

package/src/types/index.ts

@@ -0,0 +1,66 @@
+// Branded types
+export {
+  type StoreId,
+  type DocumentId,
+  createStoreId,
+  createDocumentId,
+  isStoreId,
+  isDocumentId,
+} from './brands.js';
+
+// Result type
+export {
+  type Result,
+  ok,
+  err,
+  isOk,
+  isErr,
+  unwrap,
+  unwrapOr,
+} from './result.js';
+
+// Store types
+export {
+  type Store,
+  type FileStore,
+  type RepoStore,
+  type WebStore,
+  type StoreType,
+  type StoreStatus,
+  isFileStore,
+  isRepoStore,
+  isWebStore,
+} from './store.js';
+
+// Document types
+export {
+  type Document,
+  type DocumentChunk,
+  type DocumentMetadata,
+  type DocumentType,
+} from './document.js';
+
+// Search types
+export {
+  type SearchQuery,
+  type SearchResult,
+  type SearchResponse,
+  type SearchMode,
+} from './search.js';
+
+// Config types
+export {
+  type AppConfig,
+  type EmbeddingConfig,
+  type IndexingConfig,
+  type SearchConfig,
+  type CrawlConfig,
+  type ServerConfig,
+  DEFAULT_CONFIG,
+} from './config.js';
+
+// Progress types
+export {
+  type ProgressEvent,
+  type ProgressCallback,
+} from './progress.js';

package/src/types/job.ts

@@ -0,0 +1,46 @@
+export type JobType = 'clone' | 'index' | 'crawl';
+export type JobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+
+export interface JobDetails {
+  storeName?: string;
+  storeId?: string;
+  url?: string;
+  path?: string;
+  filesProcessed?: number;
+  totalFiles?: number;
+  startedAt?: string;
+  completedAt?: string;
+  cancelledAt?: string;
+  error?: string;
+  // Crawl-specific fields
+  crawlInstruction?: string;
+  extractInstruction?: string;
+  maxPages?: number;
+  simple?: boolean;
+  useHeadless?: boolean;
+  pagesCrawled?: number;
+}
+
+export interface Job {
+  id: string;
+  type: JobType;
+  status: JobStatus;
+  progress: number; // 0-100
+  message: string;
+  details: JobDetails;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateJobParams {
+  type: JobType;
+  details: JobDetails;
+  message?: string;
+}
+
+export interface UpdateJobParams {
+  status?: JobStatus;
+  progress?: number;
+  message?: string;
+  details?: Partial<JobDetails>;
+}

package/src/types/progress.ts

@@ -0,0 +1,9 @@
+export interface ProgressEvent {
+  type: 'start' | 'progress' | 'complete' | 'error';
+  current: number;
+  total: number;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export type ProgressCallback = (event: ProgressEvent) => void;

package/src/types/result.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { ok, err, isOk, isErr, unwrap, unwrapOr } from './result.js';
+
+describe('Result type', () => {
+  describe('ok', () => {
+    it('creates a success result', () => {
+      const result = ok(42);
+      expect(isOk(result)).toBe(true);
+      expect(isErr(result)).toBe(false);
+    });
+  });
+
+  describe('err', () => {
+    it('creates an error result', () => {
+      const result = err(new Error('failed'));
+      expect(isErr(result)).toBe(true);
+      expect(isOk(result)).toBe(false);
+    });
+  });
+
+  describe('unwrap', () => {
+    it('returns value for success', () => {
+      const result = ok(42);
+      expect(unwrap(result)).toBe(42);
+    });
+
+    it('throws for error', () => {
+      const result = err(new Error('failed'));
+      expect(() => unwrap(result)).toThrow('failed');
+    });
+  });
+
+  describe('unwrapOr', () => {
+    it('returns value for success', () => {
+      const result = ok(42);
+      expect(unwrapOr(result, 0)).toBe(42);
+    });
+
+    it('returns default for error', () => {
+      const result = err(new Error('failed'));
+      expect(unwrapOr(result, 0)).toBe(0);
+    });
+  });
+});

package/src/types/result.ts

@@ -0,0 +1,41 @@
+export type Result<T, E = Error> =
+  | { readonly success: true; readonly data: T }
+  | { readonly success: false; readonly error: E };
+
+export function ok<T>(data: T): Result<T, never> {
+  return { success: true, data };
+}
+
+export function err<E>(error: E): Result<never, E> {
+  return { success: false, error };
+}
+
+export function isOk<T, E>(result: Result<T, E>): result is { success: true; data: T } {
+  return result.success;
+}
+
+export function isErr<T, E>(result: Result<T, E>): result is { success: false; error: E } {
+  return !result.success;
+}
+
+export function unwrap<T, E>(result: Result<T, E>): T {
+  if (isOk(result)) {
+    return result.data;
+  }
+  // Type guard ensures result has 'error' property
+  if (isErr(result)) {
+    if (result.error instanceof Error) {
+      throw result.error;
+    }
+    throw new Error(String(result.error));
+  }
+  // This should never happen due to discriminated union
+  throw new Error('Invalid result type');
+}
+
+export function unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T {
+  if (isOk(result)) {
+    return result.data;
+  }
+  return defaultValue;
+}

package/src/types/search.ts

@@ -0,0 +1,95 @@
+import type { StoreId, DocumentId } from './brands.js';
+import type { DocumentMetadata } from './document.js';
+
+export type SearchMode = 'vector' | 'fts' | 'hybrid';
+
+export interface CodeUnit {
+  type: 'function' | 'class' | 'interface' | 'type' | 'const' | 'documentation' | 'example';
+  name: string;
+  signature: string;
+  fullContent: string;
+  startLine: number;
+  endLine: number;
+  language: string;
+}
+
+export interface ResultSummary {
+  readonly type: 'function' | 'class' | 'interface' | 'pattern' | 'documentation';
+  readonly name: string;
+  readonly signature: string;
+  readonly purpose: string;
+  readonly location: string;
+  readonly relevanceReason: string;
+}
+
+export interface ResultContext {
+  readonly interfaces: readonly string[];
+  readonly keyImports: readonly string[];
+  readonly relatedConcepts: readonly string[];
+  readonly usage: {
+    readonly calledBy: number;
+    readonly calls: number;
+  };
+}
+
+export interface ResultFull {
+  readonly completeCode: string;
+  readonly relatedCode: ReadonlyArray<{
+    readonly file: string;
+    readonly summary: string;
+    readonly relationship: string;
+  }>;
+  readonly documentation: string;
+  readonly tests?: string | undefined;
+}
+
+export type DetailLevel = 'minimal' | 'contextual' | 'full';
+
+export interface SearchQuery {
+  readonly query: string;
+  readonly stores?: readonly StoreId[] | undefined;
+  readonly mode?: SearchMode | undefined;
+  readonly limit?: number | undefined;
+  readonly threshold?: number | undefined;
+  readonly filter?: Record<string, unknown> | undefined;
+  readonly includeContent?: boolean | undefined;
+  readonly contextLines?: number | undefined;
+
+  // Detail level for progressive context
+  readonly detail?: DetailLevel | undefined;
+}
+
+export interface SearchResult {
+  readonly id: DocumentId;
+  score: number;
+  readonly content: string;
+  readonly highlight?: string | undefined;
+  readonly metadata: DocumentMetadata;
+
+  // Structured code unit for AI agents
+  readonly codeUnit?: CodeUnit | undefined;
+
+  // Progressive context layers
+  readonly summary?: ResultSummary | undefined;
+  readonly context?: ResultContext | undefined;
+  readonly full?: ResultFull | undefined;
+
+  // Ranking attribution metadata for transparency
+  readonly rankingMetadata?: {
+    readonly vectorRank?: number;    // Position in vector results (1-based)
+    readonly ftsRank?: number;       // Position in FTS results (1-based)
+    readonly vectorRRF: number;      // Vector contribution to RRF score
+    readonly ftsRRF: number;         // FTS contribution to RRF score
+    readonly fileTypeBoost: number;  // File type multiplier applied
+    readonly frameworkBoost: number; // Framework context multiplier
+  } | undefined;
+}
+
+export interface SearchResponse {
+  readonly query: string;
+  readonly mode: SearchMode;
+  readonly stores: readonly StoreId[];
+  readonly results: readonly SearchResult[];
+  readonly totalResults: number;
+  readonly timeMs: number;
+}

package/src/types/store.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import { isFileStore, isRepoStore, isWebStore } from './store.js';
+import type { Store, FileStore, RepoStore, WebStore } from './store.js';
+import { createStoreId } from './brands.js';
+
+describe('Store types', () => {
+  const fileStore: FileStore = {
+    type: 'file',
+    id: createStoreId('file-store'),
+    name: 'My Files',
+    path: '/path/to/files',
+    description: 'Test file store',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+
+  const repoStore: RepoStore = {
+    type: 'repo',
+    id: createStoreId('repo-store'),
+    name: 'My Repo',
+    path: '/path/to/repo',
+    branch: 'main',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+
+  const webStore: WebStore = {
+    type: 'web',
+    id: createStoreId('web-store'),
+    name: 'Docs Site',
+    url: 'https://docs.example.com',
+    depth: 2,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+
+  describe('isFileStore', () => {
+    it('returns true for file stores', () => {
+      expect(isFileStore(fileStore)).toBe(true);
+    });
+
+    it('returns false for other store types', () => {
+      expect(isFileStore(repoStore)).toBe(false);
+      expect(isFileStore(webStore)).toBe(false);
+    });
+  });
+
+  describe('isRepoStore', () => {
+    it('returns true for repo stores', () => {
+      expect(isRepoStore(repoStore)).toBe(true);
+    });
+
+    it('returns false for other store types', () => {
+      expect(isRepoStore(fileStore)).toBe(false);
+      expect(isRepoStore(webStore)).toBe(false);
+    });
+  });
+
+  describe('isWebStore', () => {
+    it('returns true for web stores', () => {
+      expect(isWebStore(webStore)).toBe(true);
+    });
+
+    it('returns false for other store types', () => {
+      expect(isWebStore(fileStore)).toBe(false);
+      expect(isWebStore(repoStore)).toBe(false);
+    });
+  });
+});

package/src/types/store.ts

@@ -0,0 +1,47 @@
+import type { StoreId } from './brands.js';
+
+export type StoreType = 'file' | 'repo' | 'web';
+export type StoreStatus = 'ready' | 'indexing' | 'error';
+
+interface BaseStore {
+  readonly id: StoreId;
+  readonly name: string;
+  readonly description?: string | undefined;
+  readonly tags?: readonly string[] | undefined;
+  readonly status?: StoreStatus | undefined;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+}
+
+export interface FileStore extends BaseStore {
+  readonly type: 'file';
+  readonly path: string;
+}
+
+export interface RepoStore extends BaseStore {
+  readonly type: 'repo';
+  readonly path: string;
+  readonly url?: string | undefined;
+  readonly branch?: string | undefined;
+}
+
+export interface WebStore extends BaseStore {
+  readonly type: 'web';
+  readonly url: string;
+  readonly depth: number;
+  readonly maxPages?: number | undefined;
+}
+
+export type Store = FileStore | RepoStore | WebStore;
+
+export function isFileStore(store: Store): store is FileStore {
+  return store.type === 'file';
+}
+
+export function isRepoStore(store: Store): store is RepoStore {
+  return store.type === 'repo';
+}
+
+export function isWebStore(store: Store): store is WebStore {
+  return store.type === 'web';
+}