@dikolab/kbdb 0.3.1 → 0.4.0

package/src/shared/platform/functions/is-process-alive.function.ts

@@ -1,17 +0,0 @@
-/**
- * Checks whether a process with the given PID is alive.
- *
- * Sends signal `0` to the process, which performs a permission
- * check without sending an actual signal. Returns `true` if the
- * process exists and is reachable, `false` otherwise.
- *
- * @param pid - the process identifier to probe
- */
-export function isProcessAlive(pid: number): boolean {
-   try {
-      process.kill(pid, 0);
-      return true;
-   } catch {
-      return false;
-   }
-}

package/src/shared/platform/index.ts

@@ -1,3 +0,0 @@
-export { getTmpdir } from './functions/get-tmpdir.function.ts';
-export { isProcessAlive } from './functions/is-process-alive.function.ts';
-export { getIpcPath } from './functions/get-ipc-path.function.ts';

package/src/shared/runtime/functions/detect-runtime.ts

@@ -1,14 +0,0 @@
-import type { Runtime } from '../typings/runtime.ts';
-
-/**
- * Detects the current JavaScript runtime environment.
- *
- * Returns `'deno'` when the global `Deno` object is present,
- * otherwise returns `'node'`.
- */
-export function detectRuntime(): Runtime {
-   if (typeof globalThis !== 'undefined' && 'Deno' in globalThis) {
-      return 'deno';
-   }
-   return 'node';
-}

package/src/shared/runtime/functions/get-args.ts

@@ -1,16 +0,0 @@
-import { detectRuntime } from './detect-runtime.ts';
-
-/**
- * Returns the command-line arguments for the current runtime.
- *
- * In Deno, reads `Deno.args`; in Node.js, slices `process.argv`
- * past the interpreter and script entries.
- */
-export function getArgs(): string[] {
-   if (detectRuntime() === 'deno') {
-      const g = globalThis as Record<string, unknown>;
-      const deno = g['Deno'] as { args: string[] } | undefined;
-      return deno?.args ?? [];
-   }
-   return process.argv.slice(2);
-}

package/src/shared/runtime/index.ts

@@ -1,3 +0,0 @@
-export { detectRuntime } from './functions/detect-runtime.ts';
-export { getArgs } from './functions/get-args.ts';
-export type { Runtime } from './typings/runtime.ts';

package/src/shared/runtime/typings/runtime.ts

@@ -1,2 +0,0 @@
-/** The runtime environment in which the library is executing. */
-export type Runtime = 'deno' | 'node';

package/src/shared/sync/functions/build-import-report.function.ts

@@ -1,40 +0,0 @@
-import type { ConflictResolution } from '../typings/conflict-resolution.type.ts';
-import type { ExportEntry } from '../typings/export-entry.interface.ts';
-import type { ImportReport } from '../typings/import-report.interface.ts';
-
-/** A resolution record pairing an entry with its resolution. */
-interface ResolutionRecord {
-   /** The export entry being resolved. */
-   readonly entry: ExportEntry;
-   /** The resolution applied to the entry. */
-   readonly resolution: ConflictResolution;
-}
-
-/**
- * Builds an import report from resolution results.
- *
- * Counts each resolution type and determines whether
- * a database rebuild is required after the import.
- */
-export function buildImportReport(
-   resolutions: readonly ResolutionRecord[],
-): ImportReport {
-   let sectionsAdded = 0;
-   let sectionsSkipped = 0;
-   let sectionsSuperseded = 0;
-
-   for (const { resolution } of resolutions) {
-      if (resolution === 'add') sectionsAdded++;
-      else if (resolution === 'skip') sectionsSkipped++;
-      else sectionsSuperseded++;
-   }
-
-   return {
-      sectionsAdded,
-      sectionsSkipped,
-      sectionsSuperseded,
-      documentsAdded: sectionsAdded,
-      documentsSkipped: sectionsSkipped,
-      rebuildRequired: sectionsAdded > 0 || sectionsSuperseded > 0,
-   };
-}

package/src/shared/sync/functions/parse-export-entry.function.ts

@@ -1,45 +0,0 @@
-import type { ExportEntry } from '../typings/export-entry.interface.ts';
-
-/** Extracts a quoted string value for a TOML key. */
-function extractField(lines: string[], key: string): string {
-   for (const line of lines) {
-      const prefix = `${key} = "`;
-      if (line.startsWith(prefix) && line.endsWith('"')) {
-         return line.slice(prefix.length, -1);
-      }
-   }
-   throw new Error(`Missing required field: ${key}`);
-}
-
-/**
- * Parses a serialized export entry.
- *
- * Expects TOML frontmatter delimited by `+++` lines,
- * followed by the body content.
- *
- * @throws {Error} if the frontmatter delimiters are absent
- *   or required fields are missing.
- */
-export function parseExportEntry(content: string): ExportEntry {
-   const firstDelim = content.indexOf('+++');
-   if (firstDelim === -1) {
-      throw new Error('Missing opening +++ delimiter');
-   }
-   const afterFirst = firstDelim + 3;
-   const secondDelim = content.indexOf('+++', afterFirst);
-   if (secondDelim === -1) {
-      throw new Error('Missing closing +++ delimiter');
-   }
-
-   const frontmatter = content.slice(afterFirst, secondDelim).trim();
-   const body = content.slice(secondDelim + 3).replace(/^\n/, '');
-   const lines = frontmatter.split('\n');
-
-   return {
-      kbid: extractField(lines, 'kbid'),
-      sourceKey: extractField(lines, 'sourceKey'),
-      heading: extractField(lines, 'heading'),
-      createdAt: extractField(lines, 'createdAt'),
-      body,
-   };
-}

package/src/shared/sync/functions/resolve-conflict.function.ts

@@ -1,31 +0,0 @@
-import type { ConflictResolution } from '../typings/conflict-resolution.type.ts';
-import type { ExportEntry } from '../typings/export-entry.interface.ts';
-
-/**
- * Determines the conflict resolution action for
- * an incoming section.
- *
- * Rules applied in order:
- * 1. Same kbid exists -> skip
- * 2. Same source_key, incoming is newer -> supersede
- * 3. Same source_key, incoming is not newer -> skip
- * 4. No match -> add
- */
-export function resolveConflict(
-   incoming: ExportEntry,
-   existingKbids: ReadonlySet<string>,
-   existingBySourceKey: ReadonlyMap<string, ExportEntry>,
-): ConflictResolution {
-   if (existingKbids.has(incoming.kbid)) {
-      return 'skip';
-   }
-
-   const existing = existingBySourceKey.get(incoming.sourceKey);
-   if (existing !== undefined) {
-      const incomingTime = new Date(incoming.createdAt).getTime();
-      const existingTime = new Date(existing.createdAt).getTime();
-      return incomingTime > existingTime ? 'supersede' : 'skip';
-   }
-
-   return 'add';
-}

package/src/shared/sync/functions/serialize-export-entry.function.ts

@@ -1,18 +0,0 @@
-import type { ExportEntry } from '../typings/export-entry.interface.ts';
-
-/**
- * Serializes an export entry to a flat file format.
- *
- * Format: TOML frontmatter delimited by `+++` lines,
- * followed by the body content.
- */
-export function serializeExportEntry(entry: ExportEntry): string {
-   const frontmatter = [
-      `kbid = "${entry.kbid}"`,
-      `sourceKey = "${entry.sourceKey}"`,
-      `heading = "${entry.heading}"`,
-      `createdAt = "${entry.createdAt}"`,
-   ].join('\n');
-
-   return `+++\n${frontmatter}\n+++\n${entry.body}`;
-}

package/src/shared/sync/index.ts

@@ -1,9 +0,0 @@
-export { resolveConflict } from './functions/resolve-conflict.function.ts';
-export { buildImportReport } from './functions/build-import-report.function.ts';
-export { serializeExportEntry } from './functions/serialize-export-entry.function.ts';
-export { parseExportEntry } from './functions/parse-export-entry.function.ts';
-export type { ExportEntry } from './typings/export-entry.interface.ts';
-export type { ExportOptions } from './typings/export-options.interface.ts';
-export type { ImportOptions } from './typings/import-options.interface.ts';
-export type { ImportReport } from './typings/import-report.interface.ts';
-export type { ConflictResolution } from './typings/conflict-resolution.type.ts';

package/src/shared/sync/typings/conflict-resolution.type.ts

@@ -1,8 +0,0 @@
-/**
- * Conflict resolution strategy.
- *
- * - 'skip': same kbid -> skip
- * - 'supersede': same source_key -> replace if newer
- * - 'add': no match -> add
- */
-export type ConflictResolution = 'skip' | 'supersede' | 'add';

package/src/shared/sync/typings/export-entry.interface.ts

@@ -1,13 +0,0 @@
-/** A single entry in an export manifest. */
-export interface ExportEntry {
-   /** Section kbid. */
-   readonly kbid: string;
-   /** Source key. */
-   readonly sourceKey: string;
-   /** Section heading. */
-   readonly heading: string;
-   /** Content body. */
-   readonly body: string;
-   /** Created timestamp (ISO). */
-   readonly createdAt: string;
-}

package/src/shared/sync/typings/export-options.interface.ts

@@ -1,9 +0,0 @@
-/** Options for export operation. */
-export interface ExportOptions {
-   /** Export format. */
-   readonly format: 'git' | 'archive';
-   /** Output directory or file path. */
-   readonly outputPath: string;
-   /** Exclude vector indexes. */
-   readonly excludeVectors: boolean;
-}

package/src/shared/sync/typings/import-options.interface.ts

@@ -1,7 +0,0 @@
-/** Options for import operation. */
-export interface ImportOptions {
-   /** Source path (exported directory or archive). */
-   readonly fromPath: string;
-   /** Dry-run mode. */
-   readonly dryRun: boolean;
-}

package/src/shared/sync/typings/import-report.interface.ts

@@ -1,15 +0,0 @@
-/** Report of an import operation. */
-export interface ImportReport {
-   /** Sections added. */
-   readonly sectionsAdded: number;
-   /** Sections skipped (same kbid). */
-   readonly sectionsSkipped: number;
-   /** Sections superseded (same source_key, newer). */
-   readonly sectionsSuperseded: number;
-   /** Documents added. */
-   readonly documentsAdded: number;
-   /** Documents skipped. */
-   readonly documentsSkipped: number;
-   /** Whether rebuild is required. */
-   readonly rebuildRequired: boolean;
-}

package/src/shared/version/constants/version.constant.ts

@@ -1,2 +0,0 @@
-/** Current package version, kept in sync with package.json. */
-export const VERSION = '0.2.2';

package/src/shared/version/index.ts

@@ -1 +0,0 @@
-export { VERSION } from './constants/version.constant.ts';

package/src/shared/wasm-codec/functions/decode-add-section-result.function.ts

@@ -1,112 +0,0 @@
-import { decodeString } from './decode-string.function.ts';
-import { decodeU32 } from './decode-u32.function.ts';
-import { decodeU64 } from './decode-u64.function.ts';
-import { decodeF32 } from './decode-f32.function.ts';
-
-/**
- * A near-duplicate section identified during add-section indexing.
- */
-export interface NearDuplicate {
-   /** Knowledge-base identifier of the near-duplicate section. */
-   readonly kbid: string;
-   /** Jaccard similarity score (0.0–1.0). */
-   readonly similarity: number;
-}
-
-/**
- * Decoded result of a `worker_add_section` WASM call.
- *
- * Mirrors the Rust `AddSectionResult` struct encoded via the
- * `Encode` trait wire format.
- */
-export interface AddSectionResult {
-   /** Knowledge-base identifier assigned to the new section. */
-   readonly kbid: string;
-   /** Number of unique terms indexed for the section. */
-   readonly indexedTermsCount: number;
-   /** Wall-clock time the add operation took, in milliseconds. */
-   readonly elapsedMs: number;
-   /**
-    * Knowledge-base identifier of the section that was superseded,
-    * or `null` if no supersession occurred.
-    */
-   readonly superseded: string | null;
-   /** Advisory warnings emitted during indexing. */
-   readonly warnings: string[];
-   /**
-    * Near-duplicate sections detected above the similarity threshold
-    * (Jaccard ≥ 0.85).
-    */
-   readonly nearDuplicates: NearDuplicate[];
-}
-
-/**
- * Decodes the binary `AddSectionResult` returned by the
- * `worker_add_section` WASM export.
- *
- * Wire format (little-endian):
- * - `kbid`: `u32` length + UTF-8 bytes
- * - `indexed_terms_count`: `u32`
- * - `elapsed_ms`: `u64`
- * - `superseded`: `u8` flag (0=None, 1=Some) + optional `String`
- * - `warnings`: `u32` count + each `String`
- * - `near_duplicates`: `u32` count + each (`String` + `f32`)
- */
-export function decodeAddSectionResult(
-   bytes: Uint8Array,
-): AddSectionResult {
-   let offset = 0;
-
-   const kbid = decodeString(bytes, offset);
-   offset += kbid.bytesRead;
-
-   const indexedTermsCount = decodeU32(bytes, offset);
-   offset += indexedTermsCount.bytesRead;
-
-   const elapsedMsBig = decodeU64(bytes, offset);
-   offset += elapsedMsBig.bytesRead;
-
-   // Decode Option<String> for superseded
-   const supersededTag = bytes[offset];
-   offset += 1;
-   let superseded: string | null = null;
-   if (supersededTag === 0x01) {
-      const supersededStr = decodeString(bytes, offset);
-      offset += supersededStr.bytesRead;
-      superseded = supersededStr.value;
-   }
-
-   // Decode Vec<String> for warnings
-   const warningCount = decodeU32(bytes, offset);
-   offset += warningCount.bytesRead;
-   const warnings: string[] = [];
-   for (let i = 0; i < warningCount.value; i++) {
-      const warning = decodeString(bytes, offset);
-      offset += warning.bytesRead;
-      warnings.push(warning.value);
-   }
-
-   // Decode Vec<(String, f32)> for near_duplicates
-   const dupCount = decodeU32(bytes, offset);
-   offset += dupCount.bytesRead;
-   const nearDuplicates: NearDuplicate[] = [];
-   for (let i = 0; i < dupCount.value; i++) {
-      const dupKbid = decodeString(bytes, offset);
-      offset += dupKbid.bytesRead;
-      const similarity = decodeF32(bytes, offset);
-      offset += similarity.bytesRead;
-      nearDuplicates.push({
-         kbid: dupKbid.value,
-         similarity: similarity.value,
-      });
-   }
-
-   return {
-      kbid: kbid.value,
-      indexedTermsCount: indexedTermsCount.value,
-      elapsedMs: Number(elapsedMsBig.value),
-      superseded,
-      warnings,
-      nearDuplicates,
-   };
-}

package/src/shared/wasm-codec/functions/decode-compose-output.function.ts

@@ -1,16 +0,0 @@
-import { decodeString } from './decode-string.function.ts';
-import { decodeU64 } from './decode-u64.function.ts';
-
-export interface ComposeOutput {
-   markdown: string;
-   totalChars: bigint;
-}
-
-export function decodeComposeOutput(bytes: Uint8Array): ComposeOutput {
-   const md = decodeString(bytes, 0);
-   const totalChars = decodeU64(bytes, md.bytesRead);
-   return {
-      markdown: md.value,
-      totalChars: totalChars.value,
-   };
-}

package/src/shared/wasm-codec/functions/decode-document-manifest-list.function.ts

@@ -1,70 +0,0 @@
-import { decodeString } from './decode-string.function.ts';
-import { decodeU32 } from './decode-u32.function.ts';
-import { decodeU64 } from './decode-u64.function.ts';
-import type {
-   DocumentManifest,
-   DocumentSection,
-} from './decode-document-manifest.function.ts';
-
-export type { DocumentManifest, DocumentSection };
-
-/**
- * Decodes a WASM byte slice into an array of `DocumentManifest` values.
- *
- * The binary format is: u32 count, followed by count × DocumentManifest
- * entries. Each entry contains: docid (string), title (string),
- * createdAt (u64), docType (string), section count (u32), then each
- * section's kbid (string) and position (u32).
- *
- * @param bytes - raw bytes returned by `worker_list_docs_by_type`
- * @returns decoded array of document manifests, empty when count is zero
- */
-export function decodeDocumentManifestList(
-   bytes: Uint8Array,
-): DocumentManifest[] {
-   let offset = 0;
-   const count = decodeU32(bytes, offset);
-   offset += count.bytesRead;
-
-   const manifests: DocumentManifest[] = [];
-   for (let i = 0; i < count.value; i++) {
-      const docid = decodeString(bytes, offset);
-      offset += docid.bytesRead;
-
-      const title = decodeString(bytes, offset);
-      offset += title.bytesRead;
-
-      const createdAt = decodeU64(bytes, offset);
-      offset += createdAt.bytesRead;
-
-      const docType = decodeString(bytes, offset);
-      offset += docType.bytesRead;
-
-      const secCount = decodeU32(bytes, offset);
-      offset += secCount.bytesRead;
-
-      const sections: DocumentSection[] = [];
-      for (let j = 0; j < secCount.value; j++) {
-         const kbid = decodeString(bytes, offset);
-         offset += kbid.bytesRead;
-
-         const position = decodeU32(bytes, offset);
-         offset += position.bytesRead;
-
-         sections.push({
-            kbid: kbid.value,
-            position: position.value,
-         });
-      }
-
-      manifests.push({
-         docid: docid.value,
-         title: title.value,
-         createdAt: createdAt.value,
-         docType: docType.value,
-         sections,
-      });
-   }
-
-   return manifests;
-}

package/src/shared/wasm-codec/functions/decode-document-manifest.function.ts

@@ -1,87 +0,0 @@
-import { decodeString } from './decode-string.function.ts';
-import { decodeU32 } from './decode-u32.function.ts';
-import { decodeU64 } from './decode-u64.function.ts';
-
-/**
- * A single section reference within a document manifest.
- *
- * Associates a knowledge-base identifier with the section's
- * ordinal position in the document.
- */
-export interface DocumentSection {
-   /** Knowledge-base identifier of the referenced section. */
-   kbid: string;
-   /** Zero-based position of this section within its document. */
-   position: number;
-}
-
-/**
- * A document manifest decoded from WASM binary output.
- *
- * Represents a grouped document record with its ordered list of
- * section references as returned by `worker_retrieve_doc`.
- */
-export interface DocumentManifest {
-   /** Unique document identifier. */
-   docid: string;
-   /** Human-readable document title. */
-   title: string;
-   /** Document creation timestamp as a Unix epoch value. */
-   createdAt: bigint;
-   /** Application-level type name assigned to this document. */
-   docType: string;
-   /** Ordered list of section references belonging to the document. */
-   sections: DocumentSection[];
-}
-
-/**
- * Decodes a single `DocumentManifest` from WASM binary output.
- *
- * Reads fields in the order: docid, title, createdAt, docType,
- * section count, then each section's kbid and position.
- *
- * @param bytes - raw bytes returned by `worker_retrieve_doc`
- * @returns the decoded document manifest
- */
-export function decodeDocumentManifest(
-   bytes: Uint8Array,
-): DocumentManifest {
-   let offset = 0;
-
-   const docid = decodeString(bytes, offset);
-   offset += docid.bytesRead;
-
-   const title = decodeString(bytes, offset);
-   offset += title.bytesRead;
-
-   const createdAt = decodeU64(bytes, offset);
-   offset += createdAt.bytesRead;
-
-   const docType = decodeString(bytes, offset);
-   offset += docType.bytesRead;
-
-   const count = decodeU32(bytes, offset);
-   offset += count.bytesRead;
-
-   const sections: DocumentSection[] = [];
-   for (let i = 0; i < count.value; i++) {
-      const kbid = decodeString(bytes, offset);
-      offset += kbid.bytesRead;
-
-      const position = decodeU32(bytes, offset);
-      offset += position.bytesRead;
-
-      sections.push({
-         kbid: kbid.value,
-         position: position.value,
-      });
-   }
-
-   return {
-      docid: docid.value,
-      title: title.value,
-      createdAt: createdAt.value,
-      docType: docType.value,
-      sections,
-   };
-}

package/src/shared/wasm-codec/functions/decode-f32.function.ts

@@ -1,16 +0,0 @@
-import type { DecodeResult } from './decode-string.function.ts';
-
-export function decodeF32(
-   bytes: Uint8Array,
-   offset: number,
-): DecodeResult<number> {
-   const view = new DataView(
-      bytes.buffer,
-      bytes.byteOffset,
-      bytes.byteLength,
-   );
-   return {
-      value: view.getFloat32(offset, true),
-      bytesRead: 4,
-   };
-}

package/src/shared/wasm-codec/functions/decode-key-value-text.function.ts

@@ -1,15 +0,0 @@
-export function decodeKeyValueText(
-   text: string,
-): Record<string, string> {
-   const result: Record<string, string> = {};
-   for (const line of text.split('\n')) {
-      const idx = line.indexOf('=');
-      if (idx < 0) continue;
-      const key = line.slice(0, idx);
-      const value = line.slice(idx + 1);
-      if (key) {
-         result[key] = value;
-      }
-   }
-   return result;
-}