knosky 0.4.1 → 0.5.0

package/core/route.mjs

@@ -0,0 +1,299 @@
+// KnoSky route engine (KSV2-R1/R2/R3) — structural destination -> ranked advisory route.
+// Pure Node stdlib + internal imports only. ESM. No new deps.
+import { getRelated } from './retrieve.mjs';
+import { makeRouteDoc, validateRouteDoc } from './schema.mjs';
+import { parseDestination } from './destination.mjs';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Guard: a path from provenance.ref should never be absolute or contain "..".
+ * Returns true when the path is safe to include in output.
+ * @param {string|undefined} ref
+ * @returns {boolean}
+ */
+function isSafeRef(ref) {
+  if (!ref || typeof ref !== 'string') return false;
+  if (ref.startsWith('/')) return false;
+  if (/^[A-Za-z]:[\\\/]/.test(ref)) return false;
+  if (ref.split(/[/\\]/).some(seg => seg === '..')) return false;
+  return true;
+}
+
+/**
+ * Return the node's provenance.ref, or null if missing/unsafe.
+ * @param {object} node
+ * @returns {string|null}
+ */
+function safeRef(node) {
+  const ref = node.provenance && node.provenance.ref;
+  return isSafeRef(ref) ? ref : null;
+}
+
+/**
+ * Return true when node looks like a test file.
+ * @param {object} node
+ */
+function isTest(node) {
+  const ref = safeRef(node) || '';
+  const cat = String(node.category || '').toLowerCase();
+  return (
+    cat === 'test' ||
+    /\/test\//.test(ref) ||
+    /\.test\./.test(ref) ||
+    /\.spec\./.test(ref) ||
+    /\/test\//.test(node.id || '')
+  );
+}
+
+/**
+ * Return true when node looks like a docs file.
+ * @param {object} node
+ */
+function isDoc(node) {
+  const ref = safeRef(node) || '';
+  const cat = String(node.category || '').toLowerCase();
+  return (
+    cat === 'docs' ||
+    cat === 'documentation' ||
+    ref.endsWith('.md') ||
+    ref.endsWith('.rst') ||
+    ref.endsWith('.txt')
+  );
+}
+
+/**
+ * Tokenise a string into lowercase alphanumeric tokens, stripping any "word:" prefix.
+ * @param {string} str
+ * @returns {Set<string>}
+ */
+function tokenise(str) {
+  const stripped = String(str || '').replace(/^\w+:/, '');
+  return new Set((stripped.toLowerCase().match(/[a-z0-9]+/g) || []));
+}
+
+// ---------------------------------------------------------------------------
+// kcRoute — main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a ranked, advisory, metadata-only route doc.
+ *
+ * @param {object} ctx         — retrieve context from load()
+ * @param {string} destination — navigation target string
+ * @param {object} [opts]
+ * @param {number} [opts.limit=8]    — max route entries
+ * @param {object} [opts.overlays]   — optional overlay map from readOverlays():
+ *                                     { '<relpath>': { coverage?: number(0..100), test?: 'pass'|'fail' } }
+ *                                     Absence means coverage is unknown — the coverage-unknown caveat fires.
+ * @returns {object} route doc (passes validateRouteDoc)
+ */
+export function kcRoute(ctx, destination, { limit = 8, overlays } = {}) {
+  const clampedLimit = Math.max(1, Math.min(20, limit));
+  const { matched, matchStrength } = parseDestination(ctx, destination, clampedLimit);
+
+  // Collect direct-match ids + categories for scoring
+  const directIds = new Set(matched.map(n => n.id));
+  const directCategories = new Set(
+    matched.map(n => String(n.category || '').toLowerCase()).filter(Boolean),
+  );
+
+  // Destination keyword tokens (strip any "word:" prefix)
+  const destTokens = tokenise(destination);
+
+  // Expand to 1-hop neighbours via getRelated (imports + importedBy); de-dupe by id
+  const candidateMap = new Map();
+  for (const n of matched) {
+    candidateMap.set(n.id, n);
+  }
+
+  for (const n of matched) {
+    const rel = getRelated(ctx, n.id);
+    if (!rel) continue;
+    for (const imp of rel.imports.concat(rel.importedBy)) {
+      if (!candidateMap.has(imp.id)) {
+        const full = ctx.byId.get(imp.id);
+        if (full) candidateMap.set(imp.id, full);
+      }
+    }
+  }
+
+  // Score candidates
+  const caveats = [];
+  const lowCoverageCaveats = [];
+  const scored = [];
+
+  for (const [id, node] of candidateMap) {
+    let score = 0;
+    const reasons = [];
+
+    // Signal 1: destination match (+5)
+    if (directIds.has(id)) {
+      score += 5;
+      reasons.push('destination');
+    }
+
+    // Signal 2: import proximity (+2)
+    const rel = getRelated(ctx, id);
+    if (rel) {
+      const importsDirectMatch = rel.imports.some(m => directIds.has(m.id));
+      const importedByDirectMatch = rel.importedBy.some(m => directIds.has(m.id));
+      if (importsDirectMatch || importedByDirectMatch) {
+        score += 2;
+        reasons.push(importsDirectMatch ? 'imports destination' : 'imported by destination');
+      }
+    }
+
+    // Signal 3: same district (+1.5) — shares category with a direct match but is not itself a direct match
+    if (!directIds.has(id) && directCategories.size > 0) {
+      const cat = String(node.category || '').toLowerCase();
+      if (cat && directCategories.has(cat)) {
+        score += 1.5;
+        reasons.push('same district');
+      }
+    }
+
+    // Signal 4: keyword overlap (+1, capped once)
+    if (destTokens.size > 0) {
+      const candidateText = [node.title || '', ...(node.headings || [])].join(' ');
+      const candidateTokens = tokenise(candidateText);
+      const hasOverlap = [...destTokens].some(t => candidateTokens.has(t));
+      if (hasOverlap) {
+        score += 1;
+        reasons.push('name/heading match');
+      }
+    }
+
+    // Signal 5: recently changed (+1)
+    if (node.churn && typeof node.churn === 'object' && node.churn.c > 0) {
+      score += 1;
+      reasons.push('recently changed');
+    } else if (typeof node.churn === 'number' && node.churn > 0) {
+      score += 1;
+      reasons.push('recently changed');
+    }
+
+    // Signal 6: low coverage (+0.5 if overlays provided and coverage < 50)
+    if (overlays !== undefined && overlays !== null) {
+      const ref = safeRef(node);
+      if (ref) {
+        const overlay = overlays[ref];
+        if (overlay && typeof overlay.coverage === 'number') {
+          if (overlay.coverage < 50) {
+            score += 0.5;
+            lowCoverageCaveats.push(
+              'low coverage: ' + ref + ' (' + Math.round(overlay.coverage) + '%) — extra review advised',
+            );
+          }
+          // coverage >= 50: no change, no penalty
+        }
+      }
+    }
+
+    scored.push({ id, node, score, reason: reasons.join('; ') || 'neighbourhood match' });
+  }
+
+  // Sort: score desc, then id asc
+  scored.sort((a, b) => b.score - a.score || String(a.id).localeCompare(String(b.id)));
+
+  // Build caveats
+  // — churn caveat for any high-churn file in the top results
+  const topCandidates = scored.slice(0, clampedLimit + 5); // check a bit beyond route
+  for (const s of topCandidates) {
+    const churn = s.node.churn;
+    const hasChurn = (churn && typeof churn === 'object' && churn.c > 0) ||
+                     (typeof churn === 'number' && churn > 0);
+    if (hasChurn) {
+      caveats.push('recently changed: ' + (s.node.provenance && s.node.provenance.ref || s.id) + ' has high churn — verify before acting');
+      break; // one caveat entry is sufficient
+    }
+  }
+
+  // — low-coverage caveats (one per underperforming file, from signal 6)
+  for (const c of lowCoverageCaveats) {
+    caveats.push(c);
+  }
+
+  // — coverage unknown caveat: only when overlays were NOT provided
+  if (overlays === undefined || overlays === null) {
+    const hasCoverageGap = scored.some(s => s.node.coverage === undefined || s.node.coverage === null);
+    if (hasCoverageGap) {
+      caveats.push('coverage unknown: one or more nodes lack coverage overlay data');
+    }
+  }
+
+  // — mandatory advisory caveat (always present)
+  caveats.push('advisory route — verify before acting; KnoSky does not read code meaning');
+
+  // — staleness caveat when source_rev is present
+  const source_rev = ctx.city.source_rev || null;
+  if (source_rev) {
+    caveats.push('route is based on rev ' + source_rev + ' and may be stale');
+  }
+
+  // Slice into route + alternates
+  const routeEntries = scored.slice(0, clampedLimit);
+  const alternateEntries = scored.slice(clampedLimit, clampedLimit + 5);
+
+  function toEntry(s) {
+    const path = safeRef(s.node) || s.id;
+    return { path, id: s.id, reason: s.reason, score: s.score };
+  }
+
+  // Defense in depth: only isSafeRef() gates output (the previous `|| !path.startsWith('/')`
+  // clause was a bug — any path lacking a leading '/' but containing '..' would pass through
+  // it unfiltered; validateRouteDoc() catches that downstream today, but this filter should
+  // not have been able to let it through in the first place).
+  const route = routeEntries.map(toEntry).filter(e => isSafeRef(e.path));
+  const alternates = alternateEntries.map(toEntry).filter(e => isSafeRef(e.path));
+
+  // Confidence: direct -> ~0.95 ceiling; folder/district/edges/chain -> ~0.75; keyword -> ~0.6
+  let confidence = 0;
+  if (routeEntries.length > 0) {
+    const topScore = routeEntries[0].score;
+    if (matchStrength === 'direct') {
+      // direct hit scores at least 5; normalise to ~0.95 max
+      confidence = Math.min(0.95, topScore / 10);
+    } else if (matchStrength === 'folder' || matchStrength === 'district' ||
+               matchStrength === 'edges' || matchStrength === 'chain') {
+      confidence = Math.min(0.75, topScore / 10);
+    } else {
+      // keyword — lower ceiling
+      confidence = Math.min(0.6, topScore / 20);
+    }
+    confidence = Math.max(0, Math.min(1, confidence));
+  }
+
+  // Classify tests / docs from all candidates
+  const tests = [];
+  const docs = [];
+  for (const [, node] of candidateMap) {
+    const ref = safeRef(node);
+    if (!ref) continue;
+    if (isTest(node)) tests.push({ path: ref, id: node.id });
+    else if (isDoc(node)) docs.push({ path: ref, id: node.id });
+  }
+
+  const doc = makeRouteDoc({
+    destination,
+    route,
+    alternates,
+    caveats,
+    confidence,
+    source_rev,
+  });
+
+  // Attach tests + docs (extra fields beyond the base envelope — schema.validateRouteDoc does not reject them)
+  doc.tests = tests;
+  doc.docs = docs;
+
+  // Invariant: doc MUST pass validateRouteDoc
+  const validation = validateRouteDoc(doc);
+  if (!validation.ok) {
+    throw new Error('kcRoute produced an invalid route doc: ' + validation.errors.join('; '));
+  }
+
+  return doc;
+}

package/core/schema.mjs

@@ -0,0 +1,250 @@
+// KnoSky protocol artifact schemas and validators (SAT-427 / KSV2-P2).
+// Covers: route.json and intent-manifest.json envelope shapes.
+// Pure Node stdlib, ESM — no third-party dependencies.
+
+// ---------------------------------------------------------------------------
+// Protocol version constant
+// ---------------------------------------------------------------------------
+
+/** @type {string} */
+export const PROTOCOL_VERSION = '1.0';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true if `str` is an absolute path (Unix or Windows).
+ * @param {string} str
+ * @returns {boolean}
+ */
+function isAbsolutePath(str) {
+  if (str.startsWith('/')) return true;
+  // Windows: C:\ or C:/
+  if (/^[A-Za-z]:[\\\/]/.test(str)) return true;
+  return false;
+}
+
+/**
+ * Return true if `str` contains a `..` path segment.
+ * Splits on both `/` and `\`.
+ * @param {string} str
+ * @returns {boolean}
+ */
+function hasDotDotSegment(str) {
+  return str.split(/[/\\]/).some(seg => seg === '..');
+}
+
+/**
+ * Extract the path string from a route/manifest entry.
+ * An entry is either a plain string or an object with a `path` field.
+ * Returns null if the entry carries no recognisable path.
+ *
+ * @param {unknown} entry
+ * @returns {string|null}
+ */
+function extractPathString(entry) {
+  if (typeof entry === 'string') return entry;
+  if (entry !== null && typeof entry === 'object' && typeof entry.path === 'string') {
+    return entry.path;
+  }
+  return null;
+}
+
+/**
+ * Validate the absolute-path invariant over an array of entries.
+ * Pushes error messages into `errors` for each violation found.
+ *
+ * @param {unknown[]} entries   Array of string or { path } objects.
+ * @param {string}    fieldName Label for error messages.
+ * @param {string[]}  errors    Accumulator array.
+ */
+function checkAbsolutePaths(entries, fieldName, errors) {
+  for (let i = 0; i < entries.length; i++) {
+    const p = extractPathString(entries[i]);
+    if (p === null) continue; // non-path entry — skip
+    if (isAbsolutePath(p)) {
+      errors.push(`${fieldName}[${i}] must not be an absolute path: ${JSON.stringify(p)}`);
+    }
+    if (hasDotDotSegment(p)) {
+      errors.push(`${fieldName}[${i}] must not contain a ".." path segment: ${JSON.stringify(p)}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// makeRouteDoc
+// ---------------------------------------------------------------------------
+
+/**
+ * Construct a KnoSky `route` artifact envelope.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.destination    Navigation target.
+ * @param {unknown[]} [opts.route]       Ordered waypoints.
+ * @param {unknown[]} [opts.alternates]  Alternate routes.
+ * @param {string[]}  [opts.caveats]     Advisory notes.
+ * @param {number}    [opts.confidence]  Confidence score [0..1].
+ * @param {string|null} [opts.source_rev] VCS revision that produced this doc.
+ * @returns {object}
+ */
+export function makeRouteDoc({
+  destination,
+  route = [],
+  alternates = [],
+  caveats = [],
+  confidence = 0,
+  source_rev = null,
+} = {}) {
+  return {
+    knosky_protocol: PROTOCOL_VERSION,
+    artifact_type: 'route',
+    advisory: true,
+    generated_at: new Date().toISOString(),
+    source_rev,
+    destination,
+    route,
+    alternates,
+    caveats,
+    confidence,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// validateRouteDoc
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a KnoSky `route` document.
+ * Collects every violation; `ok` is true only when `errors` is empty.
+ *
+ * @param {object} doc
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateRouteDoc(doc) {
+  const errors = [];
+
+  if (doc.knosky_protocol !== '1.0') {
+    errors.push(`knosky_protocol must be "1.0", got: ${JSON.stringify(doc.knosky_protocol)}`);
+  }
+
+  if (doc.artifact_type !== 'route') {
+    errors.push(`artifact_type must be "route", got: ${JSON.stringify(doc.artifact_type)}`);
+  }
+
+  if (doc.advisory !== true) {
+    errors.push(`advisory must be true, got: ${JSON.stringify(doc.advisory)}`);
+  }
+
+  for (const field of ['route', 'alternates', 'caveats']) {
+    if (!Array.isArray(doc[field])) {
+      errors.push(`${field} must be an array, got: ${JSON.stringify(doc[field])}`);
+    }
+  }
+
+  if (typeof doc.confidence !== 'number' || doc.confidence < 0 || doc.confidence > 1) {
+    errors.push(`confidence must be a number in [0, 1], got: ${JSON.stringify(doc.confidence)}`);
+  }
+
+  // Absolute-path invariant applies to route[] and alternates[]
+  if (Array.isArray(doc.route)) {
+    checkAbsolutePaths(doc.route, 'route', errors);
+  }
+  if (Array.isArray(doc.alternates)) {
+    checkAbsolutePaths(doc.alternates, 'alternates', errors);
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// makeIntentManifest
+// ---------------------------------------------------------------------------
+
+/**
+ * Construct a KnoSky `intent-manifest` artifact envelope.
+ *
+ * @param {object}   opts
+ * @param {Array<{ path: string, sha256: string }>} [opts.paths]  Files covered.
+ * @param {unknown[]} [opts.edges]       Dependency edges.
+ * @param {string|null} [opts.expiry]    ISO-8601 expiry timestamp or null.
+ * @param {object}   opts.secret_scan    REQUIRED secret-scan result object.
+ * @returns {object}
+ */
+export function makeIntentManifest({
+  paths = [],
+  edges = [],
+  expiry = null,
+  secret_scan,
+} = {}) {
+  return {
+    knosky_protocol: PROTOCOL_VERSION,
+    artifact_type: 'intent-manifest',
+    advisory: true,
+    generated_at: new Date().toISOString(),
+    paths,
+    edges,
+    expiry,
+    secret_scan,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// validateIntentManifest
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a KnoSky `intent-manifest` document.
+ * Collects every violation; `ok` is true only when `errors` is empty.
+ *
+ * @param {object} doc
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateIntentManifest(doc) {
+  const errors = [];
+
+  if (doc.knosky_protocol !== '1.0') {
+    errors.push(`knosky_protocol must be "1.0", got: ${JSON.stringify(doc.knosky_protocol)}`);
+  }
+
+  if (doc.artifact_type !== 'intent-manifest') {
+    errors.push(`artifact_type must be "intent-manifest", got: ${JSON.stringify(doc.artifact_type)}`);
+  }
+
+  if (doc.advisory !== true) {
+    errors.push(`advisory must be true, got: ${JSON.stringify(doc.advisory)}`);
+  }
+
+  // paths must be an array of { path: string (non-empty), sha256: string }
+  if (!Array.isArray(doc.paths)) {
+    errors.push(`paths must be an array, got: ${JSON.stringify(doc.paths)}`);
+  } else {
+    for (let i = 0; i < doc.paths.length; i++) {
+      const entry = doc.paths[i];
+      if (!entry || typeof entry !== 'object') {
+        errors.push(`paths[${i}] must be an object`);
+        continue;
+      }
+      if (typeof entry.path !== 'string' || entry.path.length === 0) {
+        errors.push(`paths[${i}].path must be a non-empty string, got: ${JSON.stringify(entry.path)}`);
+      }
+      if (typeof entry.sha256 !== 'string') {
+        errors.push(`paths[${i}].sha256 must be a string, got: ${JSON.stringify(entry.sha256)}`);
+      }
+    }
+
+    // Absolute-path invariant on paths[].path
+    checkAbsolutePaths(doc.paths, 'paths', errors);
+  }
+
+  // secret_scan must be present and have a valid status
+  if (!doc.secret_scan || typeof doc.secret_scan !== 'object') {
+    errors.push('secret_scan is required and must be an object');
+  } else if (doc.secret_scan.status !== 'clean' && doc.secret_scan.status !== 'blocked') {
+    errors.push(
+      `secret_scan.status must be "clean" or "blocked", got: ${JSON.stringify(doc.secret_scan.status)}`,
+    );
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/mcp/server.mjs

@@ -4,6 +4,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { load, search, getNode, listCategories, getProvenance, getRelated } from "../core/retrieve.mjs";
+import { kcRoute } from "../core/route.mjs";
 
 const CITY = process.env.KC_CITY || process.argv[2];
 if (!CITY) { console.error("Knowledge City MCP: set KC_CITY (or pass a path) to a city-data.v2.json"); process.exit(1); }
@@ -70,5 +71,38 @@ server.registerTool("kc_related", {
   return { content: [{ type: "text", text: lines.join(NL) }], structuredContent: r };
 });
 
+server.registerTool("kc_route", {
+  title: "Route to a destination (agent GPS)",
+  description: "ADVISORY, metadata-only route through the repo towards a destination. Returns where-to-look-first (ranked waypoints), alternates, related tests, related docs, caveats, and a confidence score. Does NOT read or analyse code — structural navigation only, local, no network. Verify findings before acting.",
+  inputSchema: {
+    destination: z.string().max(400).describe("navigation target — e.g. file:src/auth.js, folder:src/auth, or keywords"),
+    limit: z.number().int().min(1).max(20).optional().describe("max route entries (default 8, max 20)"),
+  },
+  annotations: { readOnlyHint: true, openWorldHint: false },
+}, async ({ destination, limit }) => {
+  const doc = kcRoute(ctx, String(destination).slice(0, 400), { limit: limit ? Math.min(Math.max(1, limit), 20) : 8 });
+  const lines = [
+    `Route to: ${doc.destination}  (confidence ${(doc.confidence * 100).toFixed(0)}%)`,
+    '',
+    'Route:',
+    ...(doc.route.map((e, i) => `  ${i + 1}. ${e.path}  [${e.reason}]`)),
+  ];
+  if (doc.alternates && doc.alternates.length > 0) {
+    lines.push('', 'Alternates:');
+    for (const e of doc.alternates) lines.push(`  - ${e.path}  [${e.reason}]`);
+  }
+  if (doc.tests && doc.tests.length > 0) {
+    lines.push('', 'Tests: ' + doc.tests.map(e => e.path).join(', '));
+  }
+  if (doc.docs && doc.docs.length > 0) {
+    lines.push('', 'Docs: ' + doc.docs.map(e => e.path).join(', '));
+  }
+  if (doc.caveats && doc.caveats.length > 0) {
+    lines.push('', 'Caveats:');
+    for (const c of doc.caveats) lines.push(`  ⚠ ${c}`);
+  }
+  return { content: [{ type: "text", text: lines.join('\n') }], structuredContent: doc };
+});
+
 await server.connect(new StdioServerTransport());
 console.error(`knowledge-city MCP ready — ${ctx.city.node_count} nodes, ${(ctx.city.categories||[]).length} categories`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knosky",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Turn any repo or docs folder into an explorable city, plus a local MCP that grounds your AI in your own source with citations. Local-first, free, $0 tokens.",
   "type": "module",
   "bin": {