bluera-knowledge 0.13.3 → 0.14.1

package/src/types/brands.test.ts

@@ -1,47 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { createStoreId, createDocumentId, isStoreId, isDocumentId } from './brands.js';
-
-describe('branded types', () => {
-  describe('StoreId', () => {
-    it('creates a valid store ID', () => {
-      const id = createStoreId('store-123');
-      expect(id).toBe('store-123');
-    });
-
-    it('validates store ID format', () => {
-      expect(isStoreId('valid-store-id')).toBe(true);
-      expect(isStoreId('')).toBe(false);
-      expect(isStoreId('has spaces')).toBe(false);
-    });
-
-    it('throws error for invalid store ID', () => {
-      expect(() => createStoreId('invalid id with spaces')).toThrow(
-        'Invalid store ID: invalid id with spaces'
-      );
-    });
-
-    it('throws error for empty store ID', () => {
-      expect(() => createStoreId('')).toThrow('Invalid store ID: ');
-    });
-  });
-
-  describe('DocumentId', () => {
-    it('creates a valid document ID', () => {
-      const id = createDocumentId('doc-456');
-      expect(id).toBe('doc-456');
-    });
-
-    it('validates document ID format', () => {
-      expect(isDocumentId('valid-doc-id')).toBe(true);
-      expect(isDocumentId('')).toBe(false);
-    });
-
-    it('throws error for invalid document ID', () => {
-      expect(() => createDocumentId('invalid@id')).toThrow('Invalid document ID: invalid@id');
-    });
-
-    it('throws error for empty document ID', () => {
-      expect(() => createDocumentId('')).toThrow('Invalid document ID: ');
-    });
-  });
-});

package/src/types/brands.ts

@@ -1,32 +0,0 @@
-// Branded type symbols
-declare const StoreIdBrand: unique symbol;
-declare const DocumentIdBrand: unique symbol;
-
-// Branded types
-export type StoreId = string & { readonly [StoreIdBrand]: typeof StoreIdBrand };
-export type DocumentId = string & { readonly [DocumentIdBrand]: typeof DocumentIdBrand };
-
-// Valid ID pattern: alphanumeric, hyphens, underscores
-const ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
-
-export function isStoreId(value: string): value is StoreId {
-  return value.length > 0 && ID_PATTERN.test(value);
-}
-
-export function isDocumentId(value: string): value is DocumentId {
-  return value.length > 0 && ID_PATTERN.test(value);
-}
-
-export function createStoreId(value: string): StoreId {
-  if (!isStoreId(value)) {
-    throw new Error(`Invalid store ID: ${value}`);
-  }
-  return value;
-}
-
-export function createDocumentId(value: string): DocumentId {
-  if (!isDocumentId(value)) {
-    throw new Error(`Invalid document ID: ${value}`);
-  }
-  return value;
-}

package/src/types/config.ts

@@ -1,79 +0,0 @@
-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

@@ -1,54 +0,0 @@
-import { z } from 'zod';
-import type { DocumentId, StoreId } from './brands.js';
-
-// ============================================================================
-// Zod Schemas
-// ============================================================================
-
-export const DocumentTypeSchema = z.enum(['file', 'chunk', 'web']);
-
-export const DocumentMetadataSchema = z
-  .object({
-    path: z.string().optional(),
-    url: z.string().optional(),
-    type: DocumentTypeSchema,
-    storeId: z.string(),
-    indexedAt: z.union([z.string(), z.date()]),
-    fileHash: z.string().optional(),
-    chunkIndex: z.number().optional(),
-    totalChunks: z.number().optional(),
-  })
-  .loose(); // Allow additional fields per index signature
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export type DocumentType = z.infer<typeof DocumentTypeSchema>;
-
-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

@@ -1,73 +0,0 @@
-// 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';
-
-// Store definition types (for git-committable config)
-export {
-  type StoreDefinition,
-  type FileStoreDefinition,
-  type RepoStoreDefinition,
-  type WebStoreDefinition,
-  type StoreDefinitionsConfig,
-  StoreDefinitionSchema,
-  FileStoreDefinitionSchema,
-  RepoStoreDefinitionSchema,
-  WebStoreDefinitionSchema,
-  StoreDefinitionsConfigSchema,
-  isFileStoreDefinition,
-  isRepoStoreDefinition,
-  isWebStoreDefinition,
-  DEFAULT_STORE_DEFINITIONS_CONFIG,
-} from './store-definition.js';

package/src/types/job.ts

@@ -1,61 +0,0 @@
-import { z } from 'zod';
-
-// ============================================================================
-// Zod Schemas
-// ============================================================================
-
-export const JobTypeSchema = z.enum(['clone', 'index', 'crawl']);
-export const JobStatusSchema = z.enum(['pending', 'running', 'completed', 'failed', 'cancelled']);
-
-export const JobDetailsSchema = z.object({
-  storeName: z.string().optional(),
-  storeId: z.string().optional(),
-  url: z.string().optional(),
-  path: z.string().optional(),
-  filesProcessed: z.number().optional(),
-  totalFiles: z.number().optional(),
-  startedAt: z.string().optional(),
-  completedAt: z.string().optional(),
-  cancelledAt: z.string().optional(),
-  error: z.string().optional(),
-  // Crawl-specific fields
-  crawlInstruction: z.string().optional(),
-  extractInstruction: z.string().optional(),
-  maxPages: z.number().optional(),
-  simple: z.boolean().optional(),
-  useHeadless: z.boolean().optional(),
-  pagesCrawled: z.number().optional(),
-});
-
-export const JobSchema = z.object({
-  id: z.string(),
-  type: JobTypeSchema,
-  status: JobStatusSchema,
-  progress: z.number().min(0).max(100),
-  message: z.string(),
-  details: JobDetailsSchema.default({}),
-  createdAt: z.string(),
-  updatedAt: z.string(),
-});
-
-// ============================================================================
-// Types (inferred from schemas)
-// ============================================================================
-
-export type JobType = z.infer<typeof JobTypeSchema>;
-export type JobStatus = z.infer<typeof JobStatusSchema>;
-export type JobDetails = z.infer<typeof JobDetailsSchema>;
-export type Job = z.infer<typeof JobSchema>;
-
-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

@@ -1,9 +0,0 @@
-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

@@ -1,54 +0,0 @@
-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');
-    });
-
-    it('throws wrapped error for non-Error error value', () => {
-      const result = err('string error message');
-      expect(() => unwrap(result)).toThrow('string error message');
-    });
-
-    it('converts non-string error to string', () => {
-      const result = err(404);
-      expect(() => unwrap(result)).toThrow('404');
-    });
-  });
-
-  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

@@ -1,41 +0,0 @@
-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

@@ -1,105 +0,0 @@
-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 minRelevance?: number | undefined; // Minimum raw cosine similarity [0-1] to include results
-  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
-        readonly urlKeywordBoost: number; // URL keyword matching multiplier
-        readonly pathKeywordBoost: number; // File path keyword matching multiplier
-        readonly rawVectorScore?: number; // Raw cosine similarity [0-1] before RRF/normalization
-      }
-    | undefined;
-}
-
-export type SearchConfidence = 'high' | 'medium' | 'low';
-
-export interface SearchResponse {
-  readonly query: string;
-  readonly mode: SearchMode;
-  readonly stores: readonly StoreId[];
-  readonly results: readonly SearchResult[];
-  readonly totalResults: number;
-  readonly timeMs: number;
-  readonly confidence?: SearchConfidence | undefined; // Based on max raw vector similarity
-  readonly maxRawScore?: number | undefined; // Highest raw cosine similarity found
-}