opentology 0.4.0 → 0.4.1

package/dist/commands/context.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerContext(program: Command): void;

package/dist/commands/context.js

@@ -0,0 +1,29 @@
+import { handleContextScan } from '../mcp/server.js';
+export function registerContext(program) {
+    const ctx = program.command('context').description('Context management commands');
+    ctx
+        .command('scan')
+        .description('Scan the codebase and update the knowledge graph')
+        .option('--depth <depth>', 'Scan depth: "module" or "symbol"', 'symbol')
+        .option('--incremental', 'Only scan files changed since the last scan', false)
+        .option('--max-files <n>', 'Maximum files to scan (symbol depth)', parseInt)
+        .option('--max-symbols <n>', 'Maximum symbols to extract (symbol depth)', parseInt)
+        .option('--timeout <ms>', 'Timeout in milliseconds (symbol depth)', parseInt)
+        .action(async (opts) => {
+        try {
+            const result = await handleContextScan({
+                depth: opts.depth,
+                incremental: opts.incremental,
+                maxFiles: opts.maxFiles,
+                maxSymbols: opts.maxSymbols,
+                timeoutMs: opts.timeout,
+            });
+            console.log(JSON.stringify(result, null, 2));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`context scan failed: ${msg}`);
+            process.exit(1);
+        }
+    });
+}

package/dist/lib/ask-engine.d.ts

@@ -0,0 +1,31 @@
+import type { StoreAdapter } from './store-adapter.js';
+export interface AskInput {
+    predicate: string;
+    context: Record<string, string>;
+    record?: boolean;
+    graph?: string;
+    graphUri?: string;
+}
+export interface AskOutput {
+    answer: boolean | null;
+    reason?: string;
+    missing?: string[];
+    evaluationUri?: string;
+    bindings?: Array<Record<string, string>>;
+}
+interface ResolvedPredicate {
+    uri: string;
+    title: string;
+    sparqlTemplate: string;
+    requiredParams: string[];
+}
+export declare function resolvePredicate(adapter: StoreAdapter, predicateName: string, contextGraphUri: string): Promise<ResolvedPredicate | null>;
+export declare function validateContext(predicate: ResolvedPredicate, context: Record<string, string>): string[];
+export declare function bindTemplate(template: string, context: Record<string, string>, graphUri: string): string;
+export declare function evaluate(adapter: StoreAdapter, sparql: string): Promise<{
+    answer: boolean;
+    bindings?: Array<Record<string, string>>;
+}>;
+export declare function recordEvaluation(adapter: StoreAdapter, graphUri: string, predicateUri: string, context: Record<string, string>, answer: boolean | null, sessionUri?: string): Promise<string>;
+export declare function ask(adapter: StoreAdapter, contextGraphUri: string, input: AskInput): Promise<AskOutput>;
+export {};

package/dist/lib/ask-engine.js

@@ -0,0 +1,111 @@
+// ── Resolve ──
+export async function resolvePredicate(adapter, predicateName, contextGraphUri) {
+    const sparql = `
+    PREFIX otx: <https://opentology.dev/vocab#>
+    SELECT ?uri ?title ?template ?param WHERE {
+      GRAPH <${contextGraphUri}> {
+        ?uri a otx:Predicate ;
+             otx:title ?title ;
+             otx:sparqlTemplate ?template .
+        OPTIONAL { ?uri otx:requiredParam ?param }
+        FILTER(?title = "${predicateName}" || ?uri = <urn:predicate:${predicateName}>)
+      }
+    }
+  `;
+    const results = await adapter.sparqlQuery(sparql);
+    const bindings = results.results.bindings;
+    if (bindings.length === 0)
+        return null;
+    const first = bindings[0];
+    const requiredParams = bindings
+        .map((b) => b.param?.value)
+        .filter((v) => !!v);
+    return {
+        uri: first.uri.value,
+        title: first.title.value,
+        sparqlTemplate: first.template.value,
+        requiredParams: [...new Set(requiredParams)],
+    };
+}
+// ── Validate ──
+export function validateContext(predicate, context) {
+    return predicate.requiredParams.filter((p) => !(p in context));
+}
+// ── Evaluate ──
+export function bindTemplate(template, context, graphUri) {
+    let bound = template;
+    bound = bound.replace(/\{\{graphUri\}\}/g, graphUri);
+    for (const [key, value] of Object.entries(context)) {
+        bound = bound.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
+    }
+    return bound;
+}
+export async function evaluate(adapter, sparql) {
+    const trimmed = sparql.trim();
+    // ASK query → boolean
+    if (/^(PREFIX\s+\S+:\s+<[^>]+>\s+)*ASK\b/i.test(trimmed)) {
+        const answer = await adapter.askQuery(trimmed);
+        return { answer };
+    }
+    // SELECT query → has results?
+    const results = await adapter.sparqlQuery(trimmed);
+    const bindings = results.results.bindings.map((b) => {
+        const row = {};
+        for (const [k, v] of Object.entries(b)) {
+            row[k] = v.value;
+        }
+        return row;
+    });
+    return { answer: bindings.length > 0, bindings: bindings.length > 0 ? bindings : undefined };
+}
+// ── Record ──
+export async function recordEvaluation(adapter, graphUri, predicateUri, context, answer, sessionUri) {
+    const now = new Date().toISOString().slice(0, 10);
+    const seq = Date.now() % 100000;
+    const evalUri = `urn:evaluation:${now}-${seq}`;
+    const inputJson = JSON.stringify(context).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    let turtle = `
+@prefix otx: <https://opentology.dev/vocab#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+<${evalUri}> a otx:Evaluation ;
+    otx:predicate <${predicateUri}> ;
+    otx:input "${inputJson}" ;
+    otx:result "${String(answer)}" ;
+    otx:date "${now}"^^xsd:date .
+`;
+    if (sessionUri) {
+        turtle += `<${evalUri}> otx:createdIn <${sessionUri}> .\n`;
+    }
+    await adapter.insertTurtle(graphUri, turtle);
+    return evalUri;
+}
+// ── Main ask() ──
+export async function ask(adapter, contextGraphUri, input) {
+    // 1. Resolve predicate
+    const predicate = await resolvePredicate(adapter, input.predicate, contextGraphUri);
+    if (!predicate) {
+        return { answer: null, reason: `Unknown predicate: "${input.predicate}"` };
+    }
+    // 2. Validate required params
+    const missing = validateContext(predicate, input.context);
+    if (missing.length > 0) {
+        return { answer: null, missing, reason: `Missing required parameters: ${missing.join(', ')}` };
+    }
+    // 3. Bind template and evaluate
+    const boundSparql = bindTemplate(predicate.sparqlTemplate, input.context, contextGraphUri);
+    const { answer, bindings } = await evaluate(adapter, boundSparql);
+    // 4. Optionally record
+    let evaluationUri;
+    if (input.record !== false) {
+        evaluationUri = await recordEvaluation(adapter, contextGraphUri, predicate.uri, input.context, answer);
+    }
+    return {
+        answer,
+        reason: answer
+            ? `Predicate "${predicate.title}" evaluated to true`
+            : `Predicate "${predicate.title}" evaluated to false`,
+        evaluationUri,
+        bindings,
+    };
+}

package/dist/lib/context-sync.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { addTrackedFile, saveConfig } from './config.js';
 import { createReadyAdapter } from './store-factory.js';
 import { extractDependencyGraph } from './codebase-scanner.js';
+import { escapeTurtleLiteral as escapeTurtle } from './sparql-utils.js';
 const OTX = 'https://opentology.dev/vocab#';
 const XSD = 'http://www.w3.org/2001/XMLSchema#';
 /**
@@ -224,6 +225,3 @@ export async function syncContext(config, projectRoot) {
     saveConfig(config);
     return { sessionsRecovered, modulesUpdated, moduleStats, actions };
 }
-function escapeTurtle(s) {
-    return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
-}

package/dist/lib/deep-scan-triples.js

@@ -2,6 +2,7 @@
  * Converts DeepScanResult into OTX-compliant SPARQL INSERT DATA triples
  * with batched insert and scoped delete-then-insert strategy.
  */
+import { escapeTurtleLiteral } from './sparql-utils.js';
 const OTX = 'https://opentology.dev/vocab#';
 function encodeSegment(s) {
     return encodeURIComponent(s);
@@ -12,9 +13,7 @@ function symbolUri(filePath, kind, name) {
 function moduleUri(filePath) {
     return `urn:module:${filePath}`;
 }
-function esc(s) {
-    return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-}
+const esc = escapeTurtleLiteral;
 // ── Triple generation ───────────────────────────────────────────
 export function generateSymbolTriples(result) {
     const triples = [];

package/dist/lib/git-utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns absolute paths of source files changed since the given git ref.
+ * Includes both committed changes (sinceRef..HEAD) and staged changes.
+ * Returns [] on any git error (graceful fallback).
+ */
+export declare function getChangedSourceFiles(rootDir: string, sinceRef: string): string[];

package/dist/lib/git-utils.js

@@ -0,0 +1,34 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { extname, join } from 'node:path';
+const SOURCE_EXTENSIONS = new Set([
+    '.ts', '.js', '.tsx', '.jsx',
+    '.py', '.go', '.rs', '.java', '.swift',
+]);
+/**
+ * Returns absolute paths of source files changed since the given git ref.
+ * Includes both committed changes (sinceRef..HEAD) and staged changes.
+ * Returns [] on any git error (graceful fallback).
+ */
+export function getChangedSourceFiles(rootDir, sinceRef) {
+    try {
+        // Verify sinceRef is reachable (guards against shallow clones or rebased history)
+        execFileSync('git', ['cat-file', '-e', sinceRef], {
+            cwd: rootDir, timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const committed = execFileSync('git', ['diff', '--name-only', sinceRef, 'HEAD'], { cwd: rootDir, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const staged = execFileSync('git', ['diff', '--name-only', '--cached'], { cwd: rootDir, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const relative = [
+            ...committed.split('\n').filter(Boolean),
+            ...staged.split('\n').filter(Boolean),
+        ];
+        const unique = [...new Set(relative)];
+        return unique
+            .filter(f => SOURCE_EXTENSIONS.has(extname(f).toLowerCase()))
+            .map(f => join(rootDir, f))
+            .filter(f => existsSync(f));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/persist.d.ts

@@ -0,0 +1,10 @@
+import type { StoreAdapter } from './store-adapter.js';
+import type { OpenTologyConfig } from './config.js';
+export declare const MAX_TRIPLES_PER_PUSH = 100;
+export declare function assertTripleLimit(tripleCount: number): void;
+/**
+ * Persist a named graph to a .ttl file in embedded mode.
+ * Exports the full graph, writes to .opentology/data/{slug}.ttl, and tracks
+ * the file in config — mirroring CLI push behavior.
+ */
+export declare function persistGraph(adapter: StoreAdapter, config: OpenTologyConfig, graphUri: string): Promise<void>;

package/dist/lib/persist.js

@@ -0,0 +1,29 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { addTrackedFile, saveConfig } from './config.js';
+export const MAX_TRIPLES_PER_PUSH = 100;
+export function assertTripleLimit(tripleCount) {
+    if (tripleCount > MAX_TRIPLES_PER_PUSH) {
+        throw new Error(`Too many triples (${tripleCount}). Maximum is ${MAX_TRIPLES_PER_PUSH} per push. Split your data into smaller batches.`);
+    }
+}
+/**
+ * Persist a named graph to a .ttl file in embedded mode.
+ * Exports the full graph, writes to .opentology/data/{slug}.ttl, and tracks
+ * the file in config — mirroring CLI push behavior.
+ */
+export async function persistGraph(adapter, config, graphUri) {
+    if (config.mode !== 'embedded')
+        return;
+    const exported = await adapter.exportGraph(graphUri);
+    if (!exported.trim())
+        return;
+    // Derive a filename slug from the graph URI
+    const slug = graphUri.replace(/[^a-zA-Z0-9-]/g, '_').replace(/_+/g, '_');
+    const dataDir = join(process.cwd(), '.opentology', 'data');
+    const filePath = join(dataDir, `${slug}.ttl`);
+    mkdirSync(dataDir, { recursive: true });
+    writeFileSync(filePath, exported, 'utf-8');
+    addTrackedFile(config, graphUri, filePath);
+    saveConfig(config);
+}

package/dist/lib/scan-state.d.ts

@@ -0,0 +1,8 @@
+export interface ScanState {
+    lastScanRef: string;
+    lastScanAt: string;
+    scannedFiles: string[];
+}
+export declare function readScanState(rootDir: string): ScanState | null;
+export declare function writeScanState(rootDir: string, state: ScanState): void;
+export declare function getCurrentGitRef(rootDir: string): string;

package/dist/lib/scan-state.js

@@ -0,0 +1,32 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const STATE_FILE = '.opentology/last-scan.json';
+export function readScanState(rootDir) {
+    const stateFile = join(rootDir, STATE_FILE);
+    if (!existsSync(stateFile))
+        return null;
+    try {
+        return JSON.parse(readFileSync(stateFile, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeScanState(rootDir, state) {
+    const stateFile = join(rootDir, STATE_FILE);
+    writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf-8');
+}
+export function getCurrentGitRef(rootDir) {
+    try {
+        return execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd: rootDir,
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return 'HEAD';
+    }
+}

package/dist/lib/snapshot.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { persistGraph } from '../mcp/server.js';
+import { persistGraph } from './persist.js';
 const DEFAULT_RETENTION = 5;
 /**
  * Derive a filesystem-safe slug from a graph URI.

package/dist/lib/sparql-utils.d.ts

@@ -1,5 +1,10 @@
 import type { Quad } from 'n3';
 export declare const WELL_KNOWN_PREFIXES: Record<string, string>;
+/**
+ * Escape a string for use inside a Turtle double-quoted literal.
+ * Handles backslash, quotes, control characters, and non-BMP Unicode.
+ */
+export declare function escapeTurtleLiteral(s: string): string;
 export declare function termToSparql(term: Quad['subject'] | Quad['predicate'] | Quad['object']): string;
 export declare function parseTurtle(turtle: string): Promise<Quad[]>;
 export declare function serializeQuadsToTurtle(quads: Quad[]): Promise<string>;

package/dist/lib/sparql-utils.js

@@ -13,6 +13,21 @@ export const WELL_KNOWN_PREFIXES = {
     'http://www.w3.org/ns/prov#': 'prov',
 };
 // ── Term / Turtle helpers ─────────────────────────────────────────────
+/**
+ * Escape a string for use inside a Turtle double-quoted literal.
+ * Handles backslash, quotes, control characters, and non-BMP Unicode.
+ */
+export function escapeTurtleLiteral(s) {
+    return s
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t')
+        .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, (ch) => {
+        return '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0');
+    });
+}
 export function termToSparql(term) {
     switch (term.termType) {
         case 'NamedNode':
@@ -20,12 +35,7 @@ export function termToSparql(term) {
         case 'BlankNode':
             return `_:${term.value}`;
         case 'Literal': {
-            const escaped = term.value
-                .replace(/\\/g, '\\\\')
-                .replace(/"/g, '\\"')
-                .replace(/\n/g, '\\n')
-                .replace(/\r/g, '\\r')
-                .replace(/\t/g, '\\t');
+            const escaped = escapeTurtleLiteral(term.value);
             if (term.language) {
                 return `"${escaped}"@${term.language}`;
             }

package/dist/mcp/handlers/context.d.ts

@@ -0,0 +1,33 @@
+export interface ContextLoadOutput {
+    projectId: string;
+    graphUri: string;
+    sessions: Array<{
+        uri: string;
+        title: string;
+        date: string;
+        nextTodo?: string;
+    }>;
+    openIssues: Array<{
+        uri: string;
+        title: string;
+        date: string;
+    }>;
+    recentDecisions: Array<{
+        uri: string;
+        title: string;
+        date: string;
+        reason?: string;
+    }>;
+    meta: {
+        contextTripleCount: number;
+        sessionsTripleCount: number;
+        loadedAt: string;
+    };
+    warnings?: string[];
+}
+export declare function handleContextScan(args: Record<string, unknown>): Promise<unknown>;
+export declare function handleContextInit(args: Record<string, unknown>): Promise<unknown>;
+export declare function handleContextLoad(): Promise<ContextLoadOutput>;
+export declare function handleContextSearch(args: Record<string, unknown>): Promise<unknown>;
+export declare function handleContextImpact(args: Record<string, unknown>): Promise<unknown>;
+export declare function handleContextStatus(): Promise<unknown>;