@useody/detectors 0.0.1

package/dist/time-bombs.js

@@ -0,0 +1,113 @@
+import { parseLlmJsonResponse } from '@useody/platform-core';
+import { completeWithTimeout } from './helpers/llm-timeout.js';
+import { DATE_PATTERN, extractDeadlines, classifyDeadline, findCompletionNode, } from './time-bomb-utils.js';
+/**
+ * Detect date-dependent commitments that may have expired.
+ * Parses dates without LLM; uses LLM for richer analysis when available.
+ */
+const detectTimeBombs = async (nodes, _edges, llm) => {
+    const detections = [];
+    const now = new Date();
+    const nowLabel = now.toISOString().split('T')[0];
+    for (const node of nodes) {
+        const facts = node.content.facts ?? [];
+        const raw = node.content.raw ?? '';
+        const text = `${node.title} ${facts.join(' ')} ${node.content.summary} ${raw}`;
+        if (!DATE_PATTERN.test(text))
+            continue;
+        if (!llm) {
+            const deadlines = extractDeadlines(text, now);
+            if (deadlines.length === 0)
+                continue;
+            const nodeDocType = node.metadata?.['docType'] ?? undefined;
+            for (const dl of deadlines) {
+                const det = classifyDeadline(dl, now, node.id, nowLabel, nodeDocType);
+                if (det)
+                    detections.push(det);
+            }
+            continue;
+        }
+        const response = await completeWithTimeout(llm, [
+            {
+                role: 'system',
+                content: [
+                    'You analyze text for date-dependent commitments.',
+                    `Today is ${nowLabel}.`,
+                    'Return JSON: {"hasTimeBomb":boolean,"deadline":string|null,',
+                    '"expired":boolean,"description":string}',
+                    'Keep description under 30 words.',
+                ].join(' '),
+            },
+            { role: 'user', content: `Text: "${text.slice(0, 1000)}"` },
+        ], { temperature: 0, maxTokens: 150 });
+        if (!response)
+            continue;
+        const parsed = parseLlmJsonResponse(response);
+        if (parsed.data?.hasTimeBomb) {
+            detections.push({
+                type: 'time_bomb',
+                severity: parsed.data.expired ? 'critical' : 'warning',
+                nodeIds: [node.id],
+                description: parsed.data.description,
+                suggestedAction: parsed.data.expired
+                    ? `Deadline "${parsed.data.deadline}" has passed. Update or remove.`
+                    : `Deadline "${parsed.data.deadline}" approaching. Verify status.`,
+                metadata: {
+                    deadline: parsed.data.deadline,
+                    expired: parsed.data.expired,
+                },
+            });
+        }
+    }
+    // Deduplicate: group by deadline label, merge nodeIds
+    const byDeadline = new Map();
+    for (const det of detections) {
+        const key = det.metadata?.['deadline'] ?? det.description;
+        const existing = byDeadline.get(key);
+        if (existing) {
+            const merged = [...new Set([...existing.nodeIds, ...det.nodeIds])];
+            const sevOrder = { critical: 0, warning: 1, info: 2 };
+            const bestSev = sevOrder[det.severity] < sevOrder[existing.severity] ? det.severity : existing.severity;
+            byDeadline.set(key, {
+                ...existing,
+                severity: bestSev,
+                nodeIds: merged,
+                description: merged.length > 1
+                    ? `${existing.description.replace(/\s*\(\d+ documents?\)$/g, '')} (${String(merged.length)} documents)`
+                    : existing.description,
+            });
+        }
+        else {
+            byDeadline.set(key, det);
+        }
+    }
+    const deduped = [...byDeadline.values()];
+    const MAX_TIME_BOMBS = 20;
+    const capped = deduped.slice(0, MAX_TIME_BOMBS);
+    return capped.map((det) => {
+        if (det.metadata?.expired !== true)
+            return det;
+        const nodeId = det.nodeIds[0];
+        if (!nodeId)
+            return det;
+        const node = nodes.find((n) => n.id === nodeId);
+        if (!node)
+            return det;
+        const nodeText = `${node.title} ${(node.content.facts ?? []).join(' ')} ${node.content.summary}`;
+        const completionTitle = findCompletionNode(nodeId, nodeText, nodes);
+        if (!completionTitle)
+            return det;
+        return {
+            ...det,
+            severity: 'info',
+            description: `Deadline passed but may have been completed — see '${completionTitle}'`,
+        };
+    });
+};
+detectTimeBombs.preFilter = {
+    similarityThreshold: 0,
+    topK: 0,
+    requireAllNodes: true,
+};
+export { detectTimeBombs, extractDeadlines, classifyDeadline };
+//# sourceMappingURL=time-bombs.js.map

package/dist/undocumented.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Undocumented topic detector.
+ * Finds topics frequently discussed in chat with no matching documentation.
+ * @module undocumented
+ */
+import type { DetectorFn } from '@useody/platform-core';
+/**
+ * Detect topics discussed frequently in chat with no documentation.
+ * Requires all nodes (requireAllNodes: true) to separate chat vs doc sources.
+ */
+declare const detectUndocumented: DetectorFn;
+export { detectUndocumented };
+//# sourceMappingURL=undocumented.d.ts.map

package/dist/undocumented.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undocumented.d.ts","sourceRoot":"","sources":["../src/undocumented.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAIV,UAAU,EAEX,MAAM,uBAAuB,CAAC;AAmE/B;;;GAGG;AACH,QAAA,MAAM,kBAAkB,EAAE,UA6CzB,CAAC;AAQF,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/undocumented.js

@@ -0,0 +1,84 @@
+import { sharedTokens, lexicalScore, buildSignal, } from './helpers/text-utils.js';
+const CHAT_SOURCE_TYPES = new Set(['slack', 'teams', 'discord', 'chat']);
+const DOC_SOURCE_TYPES = new Set([
+    'markdown', 'pdf', 'notion', 'confluence', 'linear', 'jira',
+]);
+function cosineSimilarity(a, b) {
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+function buildClusters(chatNodes) {
+    const clusters = [];
+    const assigned = new Set();
+    for (const node of chatNodes) {
+        if (assigned.has(node.id))
+            continue;
+        if (node.embedding.length === 0)
+            continue;
+        const similar = chatNodes.filter((other) => other.id !== node.id &&
+            !assigned.has(other.id) &&
+            other.embedding.length > 0 &&
+            cosineSimilarity(node.embedding, other.embedding) > 0.64);
+        const clusterIds = [node.id, ...similar.map((s) => s.id)];
+        if (clusterIds.length < 3)
+            continue;
+        for (const id of clusterIds)
+            assigned.add(id);
+        const allFacts = [
+            ...(node.content.facts ?? []),
+            ...similar.flatMap((s) => s.content.facts ?? []),
+        ];
+        clusters.push({
+            topic: node.title,
+            nodeIds: clusterIds,
+            facts: [...new Set(allFacts)].slice(0, 10),
+        });
+    }
+    return clusters;
+}
+/**
+ * Detect topics discussed frequently in chat with no documentation.
+ * Requires all nodes (requireAllNodes: true) to separate chat vs doc sources.
+ */
+const detectUndocumented = async (nodes, _edges, _llm) => {
+    const detections = [];
+    const chatNodes = nodes.filter((n) => CHAT_SOURCE_TYPES.has(n.content.source?.sourceType ?? ''));
+    const docNodes = nodes.filter((n) => DOC_SOURCE_TYPES.has(n.content.source?.sourceType ?? ''));
+    const clusters = buildClusters(chatNodes);
+    for (const cluster of clusters) {
+        const clusterSignal = buildSignal(cluster.topic, cluster.facts);
+        const hasDoc = docNodes.some((doc) => {
+            const docSignal = buildSignal(doc.title, doc.content.facts ?? []);
+            const shared = sharedTokens(clusterSignal.titleTokens, docSignal.titleTokens).length;
+            const lexical = lexicalScore(clusterSignal.tokens, docSignal.tokens);
+            return shared >= 2 || (shared >= 1 && lexical >= 0.28);
+        });
+        if (hasDoc)
+            continue;
+        const mentions = cluster.nodeIds.length;
+        detections.push({
+            type: 'undocumented',
+            severity: mentions >= 6 ? 'warning' : 'info',
+            nodeIds: cluster.nodeIds.slice(0, 10),
+            description: `Discussed ${mentions} times in chat with no documentation. ` +
+                `Key points: ${cluster.facts.slice(0, 5).join('; ')}`,
+            suggestedAction: `Create a document covering: ${cluster.facts.slice(0, 5).join('; ')}`,
+        });
+    }
+    return detections;
+};
+detectUndocumented.preFilter = {
+    similarityThreshold: 0,
+    topK: 0,
+    requireAllNodes: true,
+};
+export { detectUndocumented };
+//# sourceMappingURL=undocumented.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@useody/detectors",
+  "description": "Five pure-function detectors for contradictions, duplicates, staleness, undocumented topics, and time bombs",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@useody/platform-core": "workspace:*"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ufukkaraca/ody-platform.git",
+    "directory": "packages/detectors"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "README.md",
+    "LICENSE"
+  ]
+}