knosky 0.4.1 → 0.5.0

package/core/config.mjs

@@ -0,0 +1,189 @@
+// KnoSky protocol config schema, loader, and validator (SAT-426 / KSV2-P1).
+// Pure Node stdlib, ESM — no third-party dependencies.
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// DEFAULTS — the canonical safe config for every knosky project.
+// ---------------------------------------------------------------------------
+
+/** @type {Readonly<KnoskyConfig>} */
+export const DEFAULTS = Object.freeze({
+  knosky_protocol: '1.0',
+  telemetry: false,
+  absolute_paths: false,
+  fail_on_secret: true,
+  allow_excerpts: false,
+  max_excerpt_chars: 0,
+  categories: [],
+  ignore: [],
+});
+
+// ---------------------------------------------------------------------------
+// parseConfigYaml — minimal YAML-subset parser, no deps.
+// Supports: `key: value` lines, booleans, integers, bare/quoted strings,
+// block lists (`- item` lines following a `key:` line with no inline value).
+// Ignores blank lines and # comments.
+// Throws on any line it cannot interpret for a known key.
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a minimal YAML subset used by `.knosky/config.yml`.
+ *
+ * @param {string} text  Raw file contents.
+ * @returns {Record<string, unknown>}  Parsed key/value map.
+ */
+export function parseConfigYaml(text) {
+  const result = {};
+  const lines = text.split(/\r?\n/);
+  let i = 0;
+
+  while (i < lines.length) {
+    const raw = lines[i];
+    // Strip inline comment and trim
+    const line = raw.replace(/#.*$/, '').trimEnd();
+    i++;
+
+    if (!line.trim()) continue; // blank / comment-only
+
+    // Must be a `key: [value]` line at the top level (no leading spaces)
+    const kvMatch = line.match(/^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)/);
+    if (!kvMatch) {
+      throw new Error(`parseConfigYaml: unexpected line: ${JSON.stringify(raw)}`);
+    }
+    const key = kvMatch[1];
+    const rest = kvMatch[2].trim();
+
+    if (rest === '') {
+      // Possibly a block list — collect `  - item` lines that follow
+      const items = [];
+      while (i < lines.length) {
+        const next = lines[i].replace(/#.*$/, '');
+        if (/^\s*-\s/.test(next)) {
+          items.push(next.replace(/^\s*-\s*/, '').trim());
+          i++;
+        } else {
+          break;
+        }
+      }
+      result[key] = items;
+    } else {
+      result[key] = parseScalar(rest, key);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse a scalar YAML value: boolean, integer, or string (bare or quoted).
+ *
+ * @param {string} raw  The raw value string (already trimmed).
+ * @param {string} key  The key name, used for error messages.
+ * @returns {boolean|number|string}
+ */
+function parseScalar(raw, key) {
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+
+  // Integer
+  if (/^-?\d+$/.test(raw)) return parseInt(raw, 10);
+
+  // Double-quoted string
+  if (raw.startsWith('"') && raw.endsWith('"')) return raw.slice(1, -1);
+
+  // Single-quoted string
+  if (raw.startsWith("'") && raw.endsWith("'")) return raw.slice(1, -1);
+
+  // Bare string — must not contain characters that signal unhandled YAML
+  if (/^[A-Za-z0-9._\-/ ]+$/.test(raw)) return raw;
+
+  throw new Error(`parseConfigYaml: cannot parse value for key "${key}": ${JSON.stringify(raw)}`);
+}
+
+// ---------------------------------------------------------------------------
+// loadConfig — read + parse `.knosky/config.yml`, merge over DEFAULTS.
+// Fail-closed: throws on parse error; returns DEFAULTS copy if file absent.
+// ---------------------------------------------------------------------------
+
+/**
+ * Load `.knosky/config.yml` from `root` and merge it over {@link DEFAULTS}.
+ * Returns a plain object (not frozen).  Throws if the file exists but is
+ * malformed.
+ *
+ * @param {string} root  Absolute (or relative) project root.
+ * @returns {Record<string, unknown>}  Merged config object.
+ */
+export function loadConfig(root) {
+  const cfgPath = path.join(root, '.knosky', 'config.yml');
+
+  let text;
+  try {
+    text = fs.readFileSync(cfgPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      // File absent — return a safe copy of defaults
+      return { ...DEFAULTS, categories: [], ignore: [] };
+    }
+    throw err; // permission error, etc — still fail-closed
+  }
+
+  // File exists: parse (throws on malformed — never silently fall back)
+  const parsed = parseConfigYaml(text);
+
+  // Deep-merge: parsed wins per-key; arrays are replaced, not concatenated.
+  return { ...DEFAULTS, categories: [], ignore: [], ...parsed };
+}
+
+// ---------------------------------------------------------------------------
+// validateConfig — collect all constraint violations, return { ok, errors }.
+// ---------------------------------------------------------------------------
+
+const BOOLEAN_KEYS = ['telemetry', 'absolute_paths', 'fail_on_secret', 'allow_excerpts'];
+
+/**
+ * Validate a config object against the KnoSky protocol schema.
+ * Collects every violation; `ok` is true only when `errors` is empty.
+ *
+ * @param {Record<string, unknown>} cfg  Config object (e.g. from {@link loadConfig}).
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateConfig(cfg) {
+  const errors = [];
+  const knownKeys = new Set(Object.keys(DEFAULTS));
+
+  // knosky_protocol must be the string "1.0"
+  if (cfg.knosky_protocol !== '1.0') {
+    errors.push(`knosky_protocol must be "1.0", got: ${JSON.stringify(cfg.knosky_protocol)}`);
+  }
+
+  // Boolean fields
+  for (const k of BOOLEAN_KEYS) {
+    if (typeof cfg[k] !== 'boolean') {
+      errors.push(`${k} must be a boolean, got: ${JSON.stringify(cfg[k])}`);
+    }
+  }
+
+  // max_excerpt_chars must be integer >= 0
+  const mec = cfg.max_excerpt_chars;
+  if (!Number.isInteger(mec) || mec < 0) {
+    errors.push(`max_excerpt_chars must be an integer >= 0, got: ${JSON.stringify(mec)}`);
+  }
+
+  // categories and ignore must be arrays of strings
+  for (const k of ['categories', 'ignore']) {
+    const val = cfg[k];
+    if (!Array.isArray(val) || val.some(v => typeof v !== 'string')) {
+      errors.push(`${k} must be an array of strings, got: ${JSON.stringify(val)}`);
+    }
+  }
+
+  // Unknown keys
+  for (const k of Object.keys(cfg)) {
+    if (!knownKeys.has(k)) {
+      errors.push(`unknown config key: ${k}`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/core/destination.mjs

@@ -0,0 +1,161 @@
+// KnoSky destination parser (KSV2-R2) — extended prefix set for kc_route.
+// Pure Node stdlib + internal imports only. ESM. No new deps.
+import { search } from './retrieve.mjs';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a single node by id "fs:<rest>" OR by provenance.ref === <rest>.
+ * Also accepts a fully-qualified id (already has "fs:" prefix).
+ * @param {object} ctx
+ * @param {string} idOrRef
+ * @returns {object|null}
+ */
+function resolveOne(ctx, idOrRef) {
+  // Try constructing the canonical node id
+  const byConstructed = ctx.byId.get('fs:' + idOrRef);
+  if (byConstructed) return byConstructed;
+  // Try the raw string as-is (already fully qualified, e.g. "fs:src/a.js")
+  const byRaw = ctx.byId.get(idOrRef);
+  if (byRaw) return byRaw;
+  // Fallback: linear scan for provenance.ref match
+  return ctx.city.nodes.find(n => n.provenance && n.provenance.ref === idOrRef) || null;
+}
+
+// ---------------------------------------------------------------------------
+// parseDestination — main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the destination string to an initial set of matching nodes.
+ * Returns { matched: Node[], matchStrength: 'direct'|'folder'|'district'|'edges'|'chain'|'keyword' }
+ *
+ * Supported prefixes (ALL metadata-only, no filesystem access):
+ *   file:<idOrRef>   — node by id "fs:<rest>" OR by provenance.ref === rest; 'direct'
+ *   folder:<prefix>  — nodes whose provenance.ref starts with prefix; 'folder'
+ *   district:<name>  — nodes whose category equals name (case-insensitive) or
+ *                      whose category label matches; 'district'
+ *   importsOf:<idOrRef> — out-edge targets of that node (node.links through ctx.byId); 'edges'
+ *   depChainTo:<idOrRef> — nodes that TRANSITIVELY import/reach the target via
+ *                          reverse-edge BFS; bounded (max depth 6, max 500 visited,
+ *                          visited-set prevents cycles); 'chain'
+ *   <anything else>  — keyword fallback via search(); 'keyword'
+ *
+ * @param {object} ctx         — retrieve context {city:{nodes,categories}, byId:Map}
+ * @param {string} destination
+ * @param {number} limit       — passed through to keyword search
+ * @returns {{ matched: object[], matchStrength: string }}
+ */
+export function parseDestination(ctx, destination, limit) {
+  const dest = String(destination || '').trim();
+
+  // ------------------------------------------------------------------
+  // file:<idOrRef>
+  // ------------------------------------------------------------------
+  if (dest.startsWith('file:')) {
+    const rest = dest.slice('file:'.length);
+    const node = resolveOne(ctx, rest);
+    return { matched: node ? [node] : [], matchStrength: 'direct' };
+  }
+
+  // ------------------------------------------------------------------
+  // folder:<prefix>
+  // ------------------------------------------------------------------
+  if (dest.startsWith('folder:')) {
+    const rest = dest.slice('folder:'.length);
+    // Normalise: ensure trailing slash for prefix match (unless rest already ends with /)
+    const prefix = rest.endsWith('/') ? rest : rest + '/';
+    const matched = ctx.city.nodes.filter(n => {
+      const ref = n.provenance && n.provenance.ref;
+      return typeof ref === 'string' && (ref.startsWith(prefix) || ref === rest);
+    });
+    return { matched, matchStrength: 'folder' };
+  }
+
+  // ------------------------------------------------------------------
+  // district:<name>
+  // ------------------------------------------------------------------
+  if (dest.startsWith('district:')) {
+    const name = dest.slice('district:'.length).toLowerCase();
+    // Build label->id map from city.categories
+    const labelToId = new Map();
+    for (const cat of (ctx.city.categories || [])) {
+      if (cat.label) labelToId.set(String(cat.label).toLowerCase(), String(cat.id).toLowerCase());
+    }
+    const resolvedCatId = labelToId.get(name) || null;
+    const matched = ctx.city.nodes.filter(n => {
+      const cat = String(n.category || '').toLowerCase();
+      return cat === name || (resolvedCatId !== null && cat === resolvedCatId);
+    });
+    return { matched, matchStrength: 'district' };
+  }
+
+  // ------------------------------------------------------------------
+  // importsOf:<idOrRef>
+  // ------------------------------------------------------------------
+  if (dest.startsWith('importsOf:')) {
+    const rest = dest.slice('importsOf:'.length);
+    const node = resolveOne(ctx, rest);
+    if (!node) return { matched: [], matchStrength: 'edges' };
+    const matched = (node.links || []).map(tid => ctx.byId.get(tid)).filter(Boolean);
+    return { matched, matchStrength: 'edges' };
+  }
+
+  // ------------------------------------------------------------------
+  // depChainTo:<idOrRef>
+  // Bounded reverse-edge BFS: finds all nodes that transitively import the target.
+  // Safety invariants:
+  //   - visited Set prevents revisiting nodes (handles cycles A→B→A)
+  //   - max depth 6 per BFS level
+  //   - hard cap of 500 nodes visited (includes the target seed)
+  // ------------------------------------------------------------------
+  if (dest.startsWith('depChainTo:')) {
+    const rest = dest.slice('depChainTo:'.length);
+    const target = resolveOne(ctx, rest);
+    if (!target) return { matched: [], matchStrength: 'chain' };
+    const targetId = target.id;
+
+    // Build reverse-edge index: nodeId -> Set<callerId>
+    // (which nodes have this id in their links)
+    const importedBy = new Map();
+    for (const n of ctx.city.nodes) {
+      for (const link of (n.links || [])) {
+        if (!importedBy.has(link)) importedBy.set(link, new Set());
+        importedBy.get(link).add(n.id);
+      }
+    }
+
+    // BFS — each queue entry carries { id, depth }
+    const visited = new Set();
+    visited.add(targetId);
+    const queue = [{ id: targetId, depth: 0 }];
+
+    while (queue.length > 0 && visited.size < 500) {
+      const { id, depth } = queue.shift();
+      if (depth >= 6) continue;
+      const parents = importedBy.get(id);
+      if (!parents) continue;
+      for (const pid of parents) {
+        if (!visited.has(pid)) {
+          visited.add(pid);
+          queue.push({ id: pid, depth: depth + 1 });
+          if (visited.size >= 500) break;
+        }
+      }
+    }
+
+    // Return callers of target, not the target itself
+    visited.delete(targetId);
+    const matched = [...visited].map(id => ctx.byId.get(id)).filter(Boolean);
+    return { matched, matchStrength: 'chain' };
+  }
+
+  // ------------------------------------------------------------------
+  // no recognized prefix — keyword fallback
+  // ------------------------------------------------------------------
+  const hits = search(ctx, dest, { limit });
+  const matched = hits.map(h => ctx.byId.get(h.id)).filter(Boolean);
+  return { matched, matchStrength: 'keyword' };
+}

package/core/fs-indexer.mjs

@@ -11,7 +11,10 @@ import { gitChurn } from './churn.mjs';
 const args = Object.fromEntries(process.argv.slice(2).map((a, i, arr) => a.startsWith('--') ? [a.slice(2), arr[i + 1]] : []).filter(Boolean));
 const ROOT = args.root && path.resolve(args.root);
 const OUT = args.out || null;
-const MAX = parseInt(args.max || '6000', 10);
+// Validate --max: a non-numeric/zero/negative value must NOT silently disable the
+// cap (NaN comparisons are always false, so `scanned > MAX` would never trip) —
+// that's a resource-exhaustion opening on a hostile/malformed CI invocation.
+const MAX = (() => { const n = parseInt(args.max || '6000', 10); return (Number.isFinite(n) && n > 0) ? n : 6000; })();
 const SHARE_SAFE = process.argv.includes('--share-safe');
 const INCLUDE_ABS = process.argv.includes('--include-absolute-root');
 const ALLOW_LEAKS = process.argv.includes('--allow-leaks');

package/core/overlays.mjs

@@ -0,0 +1,45 @@
+// Operational-overlay metadata ingest (D-155): file-level ONLY.
+// Reads existing local test/coverage artifacts under `root` — never executes tests.
+// Returns a map { '<relpath>': { coverage?: number(0..100), test?: 'pass'|'fail' } }.
+// Key: relpath is always forward-slash, relative to root, no leading './'.
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Parse Istanbul coverage-summary.json. Returns partial overlay map.
+function readIstanbul(root) {
+  const fp = path.join(root, 'coverage', 'coverage-summary.json');
+  let raw;
+  try { raw = fs.readFileSync(fp, 'utf8'); } catch { return {}; }
+  let json;
+  try { json = JSON.parse(raw); } catch { return {}; }
+  const out = {};
+  for (const [key, val] of Object.entries(json)) {
+    if (key === 'total') continue;                  // skip the aggregate row
+    if (!val || typeof val !== 'object') continue;
+    const pct = val.lines?.pct;
+    if (typeof pct !== 'number') continue;
+    const rel = key.replace(/\\/g, '/').replace(/^\.\//, '');
+    out[rel] = { coverage: Math.min(100, Math.max(0, pct)) };
+  }
+  return out;
+}
+
+// Merge source into dest (dest wins on conflict).
+function merge(dest, src) {
+  for (const [k, v] of Object.entries(src)) {
+    dest[k] = dest[k] ? { ...v, ...dest[k] } : v;
+  }
+}
+
+/**
+ * Read all recognised local test/coverage artifacts under `root` and return
+ * a file-level overlay map.  Never executes tests or modifies files.
+ *
+ * @param {string} root  Absolute or relative path to the project root.
+ * @returns {{ [relpath: string]: { coverage?: number, test?: 'pass'|'fail' } }}
+ */
+export function readOverlays(root) {
+  const out = {};
+  merge(out, readIstanbul(root));
+  return out;
+}

package/core/pr-comment.mjs

@@ -0,0 +1,198 @@
+// KnoSky PR-comment renderer (KSV2-CI2) — claims-disciplined public Markdown.
+// Consumes CI1 artifacts (routeJson + safetyJson) and renders the polished
+// PR-GPS comment that knosky ci posts on a pull request.
+//
+// CLAIMS DISCIPLINE — BINDING (D-162 §8):
+//   USE:  "advisory PR-GPS report" / "advisory route you can ignore"
+//   USE:  "route cache / freshness"
+//   USE:  "reads metadata only / never uploads your code"
+//   USE:  "network-silent (verify with --verify-airgap)"
+//   USE:  "open protocol / reference implementation"
+//   NEVER: CI gate / blocks the build / gates the build
+//   NEVER: learns / learns your repo
+//   NEVER: understands your code
+//   NEVER: zero data risk
+//   NEVER: official standard
+//   NEVER: air-gap guarantee
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a confidence fraction [0..1] as a percent string, or 'n/a'.
+ * @param {unknown} val
+ * @returns {string}
+ */
+function fmtConfidence(val) {
+  if (typeof val === 'number' && isFinite(val)) {
+    return Math.round(val * 100) + '%';
+  }
+  return 'n/a';
+}
+
+/**
+ * Extract path + reason from a waypoint entry (string | { path, reason }).
+ * @param {unknown} wp
+ * @returns {{ path: string, reason: string }}
+ */
+function parsWaypoint(wp) {
+  if (typeof wp === 'string') return { path: wp, reason: '' };
+  const path = (wp && typeof wp.path === 'string') ? wp.path : '';
+  const reason = (wp && typeof wp.reason === 'string') ? wp.reason : '';
+  return { path, reason };
+}
+
+// ---------------------------------------------------------------------------
+// renderPrComment — main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the KnoSky PR-GPS comment as a Markdown string.
+ *
+ * This is a DRAFT — the final public wording is Paul's critical gate.
+ *
+ * @param {object} opts
+ * @param {object} opts.routeJson   CI1 route artifact ({ routes, base, head, advisory, … })
+ * @param {object} opts.safetyJson  CI1 safety artifact ({ secrets_found, absolute_paths, … })
+ * @returns {string}  Markdown comment body.
+ */
+export function renderPrComment({ routeJson = {}, safetyJson = {} } = {}) {
+  const lines = [];
+
+  // -------------------------------------------------------------------------
+  // Header
+  // -------------------------------------------------------------------------
+  lines.push('## 🧭 KnoSky PR-GPS');
+  lines.push('');
+  lines.push(
+    '> **DRAFT — advisory PR-GPS report.** ' +
+    'This is an advisory route you can ignore — it never gates or enforces a build outcome.',
+  );
+  lines.push('');
+
+  // -------------------------------------------------------------------------
+  // Per-file route sections
+  // -------------------------------------------------------------------------
+  const routes = Array.isArray(routeJson.routes) ? routeJson.routes : [];
+
+  if (routes.length === 0) {
+    lines.push('_No changed files detected in this PR — nothing to navigate._');
+    lines.push('');
+  } else {
+    for (const { file, route: routeDoc } of routes) {
+      lines.push(`### \`${file}\``);
+      lines.push('');
+
+      // Top ~5 waypoints
+      const waypoints = (Array.isArray(routeDoc && routeDoc.route) ? routeDoc.route : []).slice(0, 5);
+      if (waypoints.length === 0) {
+        lines.push('_No route waypoints found in the route cache for this file._');
+      } else {
+        lines.push('**Advisory route waypoints** _(top ' + waypoints.length + ', from route cache):_');
+        lines.push('');
+        for (const wp of waypoints) {
+          const { path, reason } = parsWaypoint(wp);
+          lines.push(`- \`${path}\`${reason ? ' — ' + reason : ''}`);
+        }
+      }
+      lines.push('');
+
+      // Confidence
+      const conf = fmtConfidence(routeDoc && routeDoc.confidence);
+      lines.push(`**Confidence:** ${conf}`);
+      lines.push('');
+
+      // Freshness / coverage caveats
+      const caveats = Array.isArray(routeDoc && routeDoc.caveats) ? routeDoc.caveats : [];
+      const freshnessOrCoverage = caveats.filter(c =>
+        /recently changed|stale|freshness|coverage/i.test(c),
+      );
+      if (freshnessOrCoverage.length > 0) {
+        lines.push('**Route freshness / coverage caveats:**');
+        lines.push('');
+        for (const c of freshnessOrCoverage) lines.push(`- ${c}`);
+        lines.push('');
+      }
+
+      // Related tests
+      const tests = Array.isArray(routeDoc && routeDoc.tests) ? routeDoc.tests : [];
+      if (tests.length > 0) {
+        lines.push('**Related tests:**');
+        lines.push('');
+        for (const t of tests) {
+          const p = typeof t === 'string' ? t : (t && t.path);
+          if (p) lines.push(`- \`${p}\``);
+        }
+        lines.push('');
+      }
+
+      // Related docs
+      const docs = Array.isArray(routeDoc && routeDoc.docs) ? routeDoc.docs : [];
+      if (docs.length > 0) {
+        lines.push('**Related docs:**');
+        lines.push('');
+        for (const d of docs) {
+          const p = typeof d === 'string' ? d : (d && d.path);
+          if (p) lines.push(`- \`${p}\``);
+        }
+        lines.push('');
+      }
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Suggested reviewer / agent prompt block
+  // -------------------------------------------------------------------------
+  lines.push('---');
+  lines.push('');
+  lines.push('### 💬 Suggested reviewer / agent prompt');
+  lines.push('');
+
+  if (routes.length > 0) {
+    // Collect top waypoints across all changed files (unique, capped at 5)
+    const seen = new Set();
+    const topPaths = [];
+    for (const { route: routeDoc } of routes) {
+      const wps = Array.isArray(routeDoc && routeDoc.route) ? routeDoc.route : [];
+      for (const wp of wps.slice(0, 3)) {
+        const { path } = parsWaypoint(wp);
+        if (path && !seen.has(path)) {
+          seen.add(path);
+          topPaths.push(path);
+          if (topPaths.length >= 5) break;
+        }
+      }
+      if (topPaths.length >= 5) break;
+    }
+    const waypointList = topPaths.map(p => `\`${p}\``).join(', ');
+    lines.push(
+      `> Start your review at: ${waypointList || '_see routes above_'}. ` +
+      'Advisory only — verify before acting.',
+    );
+  } else {
+    lines.push(
+      '> No route waypoints available for this PR. ' +
+      'Advisory only — verify before acting.',
+    );
+  }
+
+  lines.push('');
+
+  // -------------------------------------------------------------------------
+  // Footer — safety / privacy
+  // -------------------------------------------------------------------------
+  lines.push('---');
+  lines.push('');
+  const secretsFound = (safetyJson && typeof safetyJson.secrets_found === 'number')
+    ? safetyJson.secrets_found
+    : 0;
+  lines.push(
+    '_KnoSky reads metadata only — it never uploads your code. ' +
+    `Secrets scan: **${secretsFound}** potential secret(s) found in emitted artifacts. ` +
+    'network-silent (verify with --verify-airgap). ' +
+    'open protocol / reference implementation._',
+  );
+
+  return lines.join('\n');
+}