@work-graph/cli 0.2.0

package/vendor/src/seedAnalyticsRecord.mjs

@@ -0,0 +1,217 @@
+import { readFile } from 'node:fs/promises';
+import { basename, relative, resolve } from 'node:path';
+
+import {
+  DEFAULT_ANALYTICS_RECORD_JOURNAL_PATH,
+  appendAnalyticsRecordJournal,
+  buildAnalyticsRecord,
+  readAnalyticsRecordJournal,
+} from './analyticsRecordStore.mjs';
+
+export const SEED_ANALYTICS_RECORD_SCHEMA = 'workgraph.seed-analytics-record.v1';
+
+const H1_PATTERN = /^#\s+(AN-\d+(?:-[A-Z0-9]+)?)\s*:\s*(.+)$/mu;
+const QUERY_PATTERN = /^\*\*Запрос:\*\*\s*(.+)$/mu;
+
+function splitCsv(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function normalizeBodyPath(bodyPath, cwd) {
+  const absolutePath = resolve(cwd, bodyPath);
+  return relative(cwd, absolutePath).replace(/\\/gu, '/');
+}
+
+function slugFromBodyPath(bodyPath) {
+  return basename(bodyPath, '.md')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, '-')
+    .replace(/^-+|-+$/gu, '')
+    .slice(0, 48);
+}
+
+export function parseAnalyticsMarkdownMetadata(body) {
+  const h1Match = body.match(H1_PATTERN);
+  const queryMatch = body.match(QUERY_PATTERN);
+
+  return {
+    key: h1Match?.[1]?.trim() ?? '',
+    title: h1Match?.[2]?.trim() ?? '',
+    query: queryMatch?.[1]?.trim() ?? '',
+  };
+}
+
+export function parseSeedAnalyticsRecordArgs(argv, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const parsed = {
+    cwd,
+    body: '',
+    key: '',
+    title: '',
+    query: '',
+    topic: 'general',
+    tags: [],
+    relatedFiles: [],
+    journalPath: DEFAULT_ANALYTICS_RECORD_JOURNAL_PATH,
+    dryRun: false,
+    force: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const next = argv[index + 1];
+
+    if (arg === '--body' && next) {
+      parsed.body = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--key' && next) {
+      parsed.key = next.trim();
+      index += 1;
+      continue;
+    }
+    if (arg === '--title' && next) {
+      parsed.title = next.trim();
+      index += 1;
+      continue;
+    }
+    if (arg === '--query' && next) {
+      parsed.query = next.trim();
+      index += 1;
+      continue;
+    }
+    if (arg === '--topic' && next) {
+      parsed.topic = next.trim();
+      index += 1;
+      continue;
+    }
+    if (arg === '--tags' && next) {
+      parsed.tags = splitCsv(next);
+      index += 1;
+      continue;
+    }
+    if (arg === '--related-files' && next) {
+      parsed.relatedFiles = splitCsv(next);
+      index += 1;
+      continue;
+    }
+    if (arg === '--journal' && next) {
+      parsed.journalPath = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--cwd' && next) {
+      parsed.cwd = resolve(next);
+      index += 1;
+      continue;
+    }
+    if (arg === '--dry-run') {
+      parsed.dryRun = true;
+      continue;
+    }
+    if (arg === '--force') {
+      parsed.force = true;
+    }
+  }
+
+  if (!parsed.body) {
+    throw new TypeError('--body is required (path to work/analytics/*.md)');
+  }
+
+  parsed.bodyPath = normalizeBodyPath(parsed.body, parsed.cwd);
+  return parsed;
+}
+
+function pickNonEmpty(explicit, fallback) {
+  const value = String(explicit ?? '').trim();
+  return value || String(fallback ?? '').trim();
+}
+
+export async function buildAnalyticsRecordInputFromMarkdown(options) {
+  const bodyPath = normalizeBodyPath(options.body ?? options.bodyPath, options.cwd ?? process.cwd());
+  const absolutePath = resolve(options.cwd ?? process.cwd(), bodyPath);
+  const body = await readFile(absolutePath, 'utf8');
+  const metadata = parseAnalyticsMarkdownMetadata(body);
+
+  const key = pickNonEmpty(options.key, metadata.key);
+  const title = pickNonEmpty(options.title, metadata.title);
+  const query = pickNonEmpty(options.query, metadata.query);
+
+  if (!title) {
+    throw new TypeError(`title is required (--title or H1 "# AN-XX: title" in ${bodyPath})`);
+  }
+  if (!query) {
+    throw new TypeError(`query is required (--query or "**Запрос:**" in ${bodyPath})`);
+  }
+
+  const slug = slugFromBodyPath(bodyPath);
+  const tags = [...(options.tags ?? [])];
+  if (key && !tags.includes(key)) {
+    tags.push(key);
+  }
+
+  const relatedFiles = [...(options.relatedFiles ?? [])];
+  if (!relatedFiles.includes(bodyPath)) {
+    relatedFiles.unshift(bodyPath);
+  }
+
+  return {
+    title: key ? `${key}: ${title}` : title,
+    query,
+    slug,
+    topic: options.topic ?? 'general',
+    status: options.status ?? 'published',
+    tags,
+    relatedFiles,
+    bodyPath,
+    author: options.author ?? 'agent',
+    ...(key ? { key } : {}),
+  };
+}
+
+export async function seedAnalyticsRecord(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const journalPath = options.journalPath ?? DEFAULT_ANALYTICS_RECORD_JOURNAL_PATH;
+  const recordInput = await buildAnalyticsRecordInputFromMarkdown({ ...options, cwd });
+  const record = buildAnalyticsRecord(recordInput);
+
+  const journal = await readAnalyticsRecordJournal({ cwd, journalPath });
+  const existingById = journal.records.find((entry) => entry.id === record.id);
+  const existingByKey = record.key
+    ? journal.records.find((entry) => entry.key === record.key)
+    : null;
+  const existingByBodyPath = journal.records.find((entry) => entry.bodyPath === record.bodyPath);
+
+  if (!options.force && (existingById || existingByKey || existingByBodyPath)) {
+    return {
+      schema: SEED_ANALYTICS_RECORD_SCHEMA,
+      skipped: true,
+      reason: 'record_exists',
+      id: existingById?.id ?? existingByKey?.id ?? existingByBodyPath?.id ?? record.id,
+      key: existingById?.key ?? existingByKey?.key ?? existingByBodyPath?.key ?? record.key ?? null,
+      bodyPath: record.bodyPath,
+      journalPath: resolve(cwd, journalPath),
+    };
+  }
+
+  const appendResult = await appendAnalyticsRecordJournal([record], journalPath, {
+    cwd,
+    dryRun: options.dryRun === true,
+  });
+
+  return {
+    schema: SEED_ANALYTICS_RECORD_SCHEMA,
+    skipped: false,
+    appended: appendResult.appended,
+    dryRun: options.dryRun === true,
+    id: record.id,
+    key: record.key ?? null,
+    title: record.title,
+    bodyPath: record.bodyPath,
+    journalPath: resolve(cwd, journalPath),
+  };
+}

package/vendor/src/semanticSearchBm25.mjs

@@ -0,0 +1,103 @@
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+
+export function tokenizeForBm25(text) {
+  return String(text ?? '')
+    .toLowerCase()
+    .split(/[^a-z0-9\u0400-\u04ff]+/u)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 2);
+}
+
+export function buildBm25Index(documents) {
+  const docTokens = documents.map((document) => {
+    const corpusText = [
+      document.label,
+      document.summary,
+      ...(document.parts ?? []).map((part) => part.text),
+      document.excerpt ?? '',
+    ].filter(Boolean).join(' ');
+
+    const tokens = tokenizeForBm25(corpusText);
+    const termFreq = new Map();
+    for (const token of tokens) {
+      termFreq.set(token, (termFreq.get(token) ?? 0) + 1);
+    }
+
+    return {
+      id: document.id,
+      length: tokens.length,
+      termFreq,
+    };
+  });
+
+  const documentFrequency = new Map();
+  for (const doc of docTokens) {
+    for (const term of doc.termFreq.keys()) {
+      documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);
+    }
+  }
+
+  const avgDocLength = docTokens.length === 0
+    ? 0
+    : docTokens.reduce((sum, doc) => sum + doc.length, 0) / docTokens.length;
+
+  return {
+    docTokens,
+    documentFrequency,
+    avgDocLength,
+    documentCount: docTokens.length,
+  };
+}
+
+export function scoreBm25(queryTokens, index, options = {}) {
+  const k1 = options.k1 ?? 1.2;
+  const b = options.b ?? 0.75;
+  const scores = new Map();
+
+  if (queryTokens.length === 0 || index.documentCount === 0) {
+    return scores;
+  }
+
+  for (const doc of index.docTokens) {
+    let score = 0;
+
+    for (const term of queryTokens) {
+      const tf = doc.termFreq.get(term) ?? 0;
+      if (tf === 0) {
+        continue;
+      }
+
+      const df = index.documentFrequency.get(term) ?? 0;
+      const idf = Math.log(1 + (index.documentCount - df + 0.5) / (df + 0.5));
+      const numerator = tf * (k1 + 1);
+      const denominator = tf + k1 * (1 - b + b * (doc.length / Math.max(index.avgDocLength, 1)));
+      score += idf * (numerator / denominator);
+    }
+
+    if (score > 0) {
+      scores.set(doc.id, Number(score.toFixed(4)));
+    }
+  }
+
+  return scores;
+}
+
+export function mergeLexicalAndBm25Scores(entries, bm25Scores, options = {}) {
+  const bm25Weight = Number(options.bm25Weight ?? 4);
+
+  return entries
+    .map((entry) => ({
+      ...entry,
+      lexicalScore: entry.score,
+      bm25Score: bm25Scores.get(entry.id) ?? 0,
+      score: entry.score + bm25Weight * (bm25Scores.get(entry.id) ?? 0),
+    }))
+    .sort((left, right) => {
+      const byScore = right.score - left.score;
+      if (byScore !== 0) {
+        return byScore;
+      }
+
+      return compareText(left.id, right.id);
+    });
+}

package/vendor/src/semanticSearchExcerpts.mjs

@@ -0,0 +1,68 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { normalizeBoundedTargetPath } from './workGraphBoundedTargetFileRead.mjs';
+
+const DEFAULT_EXCERPT_CHARS = 1200;
+
+export async function readSemanticSearchFileExcerpt(filePath, options = {}) {
+  const repoRoot = resolve(options.repoRoot ?? options.cwd ?? process.cwd());
+  const normalized = normalizeBoundedTargetPath(filePath, repoRoot);
+  if (!normalized.ok) {
+    return { ok: false, path: filePath, excerpt: '', error: normalized.error };
+  }
+
+  const readFileImpl = options.readFile ?? readFile;
+  const maxChars = options.maxExcerptChars ?? DEFAULT_EXCERPT_CHARS;
+
+  try {
+    const absolute = resolve(repoRoot, normalized.path);
+    const content = await readFileImpl(absolute, 'utf8');
+    const excerpt = content.slice(0, maxChars).trim();
+    return {
+      ok: true,
+      path: normalized.path,
+      excerpt,
+      truncated: content.length > maxChars,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, path: normalized.path, excerpt: '', error: message };
+  }
+}
+
+export async function enrichSemanticDocumentsWithExcerpts(documents, options = {}) {
+  const repoRoot = resolve(options.repoRoot ?? options.cwd ?? process.cwd());
+  const targetFilesByWorkId = options.targetFilesByWorkId ?? new Map();
+  const enriched = [];
+
+  for (const document of documents) {
+    const excerptPaths = document.kind === 'file_artifact' && document.filePath
+      ? [document.filePath]
+      : document.kind === 'work_item'
+        ? (targetFilesByWorkId.get(document.workId) ?? []).slice(0, options.maxFilesPerWorkItem ?? 2)
+        : [];
+
+    let excerpt = '';
+    const excerptSources = [];
+
+    for (const filePath of excerptPaths) {
+      const loaded = await readSemanticSearchFileExcerpt(filePath, { ...options, repoRoot });
+      if (loaded.ok && loaded.excerpt) {
+        excerpt += `${loaded.excerpt}\n`;
+        excerptSources.push(loaded.path);
+      }
+    }
+
+    enriched.push({
+      ...document,
+      excerpt: excerpt.trim(),
+      excerptSources,
+      parts: excerpt
+        ? [...(document.parts ?? []), { text: excerpt, weight: 3 }]
+        : [...(document.parts ?? [])],
+    });
+  }
+
+  return enriched;
+}

package/vendor/src/semanticSearchTfidfVector.mjs

@@ -0,0 +1,86 @@
+import { tokenizeForBm25 } from './semanticSearchBm25.mjs';
+
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+
+function documentText(document) {
+  const parts = document.parts ?? [];
+  return parts.map((part) => String(part.text ?? '')).join('\n');
+}
+
+export function buildTfidfIndex(documents) {
+  const docCount = documents.length;
+  const docFreq = new Map();
+  const docTokens = documents.map((document) => {
+    const counts = new Map();
+    for (const token of tokenizeForBm25(documentText(document))) {
+      counts.set(token, (counts.get(token) ?? 0) + 1);
+    }
+
+    for (const token of counts.keys()) {
+      docFreq.set(token, (docFreq.get(token) ?? 0) + 1);
+    }
+
+    return { id: document.id, counts };
+  });
+
+  const vectors = docTokens.map((entry) => {
+    const total = [...entry.counts.values()].reduce((sum, value) => sum + value, 0) || 1;
+    const weights = new Map();
+
+    for (const [token, count] of entry.counts.entries()) {
+      const tf = count / total;
+      const idf = Math.log((docCount + 1) / ((docFreq.get(token) ?? 0) + 1)) + 1;
+      weights.set(token, tf * idf);
+    }
+
+    return { id: entry.id, weights };
+  });
+
+  return {
+    schema: 'semantic-search.tfidf-index.v1',
+    docCount,
+    vectors,
+  };
+}
+
+function vectorNorm(weights) {
+  let sum = 0;
+  for (const value of weights.values()) {
+    sum += value * value;
+  }
+
+  return Math.sqrt(sum) || 1;
+}
+
+function cosineSimilarity(left, right) {
+  let dot = 0;
+  for (const [token, weight] of left.entries()) {
+    dot += weight * (right.get(token) ?? 0);
+  }
+
+  return dot / (vectorNorm(left) * vectorNorm(right));
+}
+
+export function scoreTfidfCosine(query, index) {
+  const queryCounts = new Map();
+  for (const token of tokenizeForBm25(String(query ?? ''))) {
+    queryCounts.set(token, (queryCounts.get(token) ?? 0) + 1);
+  }
+
+  const total = [...queryCounts.values()].reduce((sum, value) => sum + value, 0) || 1;
+  const queryWeights = new Map();
+  for (const [token, count] of queryCounts.entries()) {
+    queryWeights.set(token, count / total);
+  }
+
+  return index.vectors
+    .map((entry) => ({
+      id: entry.id,
+      score: cosineSimilarity(queryWeights, entry.weights),
+    }))
+    .filter((entry) => entry.score > 0)
+    .sort((left, right) => {
+      const byScore = right.score - left.score;
+      return byScore !== 0 ? byScore : compareText(left.id, right.id);
+    });
+}