knosky 0.4.1 → 0.6.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/constants.mjs

@@ -0,0 +1,13 @@
+// Shared, dependency-free constants used by more than one core module.
+// Kept in its own file (no imports, no side effects) so any core/*.mjs can
+// import from it without creating a circular dependency between modules.
+
+// Upper bound for a plausible ledger sequence (git commit count). 1 billion
+// is far beyond any real repo's commit count and far below
+// Number.MAX_SAFE_INTEGER (~9e15), so it rejects implausible/attacker-
+// supplied values (e.g. 1e100) with no precision-loss risk of its own.
+// Enforced independently at two layers — core/freshness.mjs's
+// extractLedgerSeq (structural validation) and core/ledger.mjs's
+// checkAndAdvance (the persisted guard itself) — both import this single
+// source of truth so the two layers cannot silently diverge.
+export const MAX_PLAUSIBLE_LEDGER_SEQ = 1_000_000_000;

package/core/cross-repo.mjs

@@ -0,0 +1,111 @@
+// Cross-repo graph utilities (SAT-448): edge detection, boundary extraction, and rendering metadata.
+// Pure logic — no filesystem access, no new deps. Works on the in-memory city/byId structures
+// produced by retrieve.load() or any equivalent.
+//
+// A node's *repo* identity is determined by provenance.repo when present, falling back to
+// provenance.store (e.g. "fs", "gh:owner/repo") so existing city data stays fully compatible —
+// single-repo graphs have no cross-repo edges because every node shares the same store value.
+
+// ---------------------------------------------------------------------------
+// repoOf
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the repository identity of a node.
+ * Preference order:
+ *   1. node.provenance.repo  — explicit multi-repo label (new field, optional)
+ *   2. node.provenance.store — always present; used as the identity when repo is absent
+ *      (works correctly for single-repo graphs: all nodes share one store → no cross edges)
+ *
+ * Returns null if provenance is absent or malformed.
+ *
+ * @param {object} node
+ * @returns {string|null}
+ */
+export function repoOf(node) {
+  if (!node || typeof node !== 'object') return null;
+  const prov = node.provenance;
+  if (!prov || typeof prov !== 'object') return null;
+  if (typeof prov.repo === 'string' && prov.repo.length > 0) return prov.repo;
+  if (typeof prov.store === 'string' && prov.store.length > 0) return prov.store;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// isCrossRepoEdge
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true when the edge (fromId → toId) crosses a repo boundary.
+ * An edge is cross-repo when repoOf(fromNode) !== repoOf(toNode) AND both are non-null.
+ * Edges where either endpoint is missing or has no repo identity are treated as same-repo
+ * (conservative: no false positives).
+ *
+ * @param {Map<string, object>} byId   — node map from retrieve.load()
+ * @param {string}              fromId
+ * @param {string}              toId
+ * @returns {boolean}
+ */
+export function isCrossRepoEdge(byId, fromId, toId) {
+  const src = byId.get(fromId);
+  const dst = byId.get(toId);
+  if (!src || !dst) return false;
+  const r1 = repoOf(src);
+  const r2 = repoOf(dst);
+  if (r1 === null || r2 === null) return false;
+  return r1 !== r2;
+}
+
+// ---------------------------------------------------------------------------
+// getCrossRepoEdges
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk every node's `links` array and return all edges that cross a repo boundary.
+ *
+ * @param {object} ctx  — { city: { nodes: [] }, byId: Map }
+ * @returns {Array<{ from: string, to: string, fromRepo: string, toRepo: string }>}
+ */
+export function getCrossRepoEdges(ctx) {
+  const edges = [];
+  for (const node of (ctx.city.nodes || [])) {
+    if (!Array.isArray(node.links)) continue;
+    const fromRepo = repoOf(node);
+    if (fromRepo === null) continue;
+    for (const toId of node.links) {
+      const dst = ctx.byId.get(toId);
+      if (!dst) continue;
+      const toRepo = repoOf(dst);
+      if (toRepo === null) continue;
+      if (fromRepo !== toRepo) {
+        edges.push({ from: node.id, to: toId, fromRepo, toRepo });
+      }
+    }
+  }
+  return edges;
+}
+
+// ---------------------------------------------------------------------------
+// getRepoBoundaries
+// ---------------------------------------------------------------------------
+
+/**
+ * Return a summary of every distinct repo present in the graph and its node membership.
+ *
+ * @param {object} ctx  — { city: { nodes: [] }, byId: Map }
+ * @returns {Array<{ repo: string, nodeIds: string[], count: number }>}
+ *            Sorted by count desc, then repo asc.
+ */
+export function getRepoBoundaries(ctx) {
+  /** @type {Map<string, string[]>} */
+  const byRepo = new Map();
+  for (const node of (ctx.city.nodes || [])) {
+    const r = repoOf(node);
+    if (r === null) continue;
+    if (!byRepo.has(r)) byRepo.set(r, []);
+    byRepo.get(r).push(node.id);
+  }
+  return [...byRepo.entries()]
+    .map(([repo, nodeIds]) => ({ repo, nodeIds, count: nodeIds.length }))
+    .sort((a, b) => b.count - a.count || String(a.repo).localeCompare(String(b.repo)));
+}

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/escalate.mjs

@@ -0,0 +1,68 @@
+// KnoSky HITL escalation gate (D-166 / SAT-467) — any P0/critical or ambiguous
+// review result must surface to Paul, never proceed silently.
+// D-166 (SAT-466): zero-P0/critical + all reviewers succeeded → auto-proceed-to-publish.
+// Pure function: no I/O, no external dependencies, safe to import anywhere.
+
+/**
+ * Decide whether a review result must be escalated to Paul, or may auto-publish.
+ *
+ * Rules (D-166 hitl gate, SAT-467 / SAT-466):
+ *   - One or more CRITICAL findings   → P0, escalate immediately.
+ *   - All reviewers failed             → ambiguous (no result at all), escalate.
+ *   - Any reviewer failed (degraded)   → ambiguous (result is incomplete), escalate.
+ *   - Zero criticals + zero failures + at least one reviewer ran
+ *                                      → canAutoPublish (D-166 pre-authorized path).
+ *
+ * @param {object}   opts
+ * @param {object[]} [opts.criticals]  CRITICAL findings ({ sev, file, hint, role }).
+ * @param {object[]} [opts.failed]     Failed reviewer records ({ role, err, ok: false }).
+ * @param {number}   [opts.total]      Total reviewer count dispatched this run.
+ * @returns {{ escalate: boolean, reasons: string[], paulMessage: string, canAutoPublish: boolean }}
+ *   escalate       — true iff the result must block and surface to Paul.
+ *   reasons        — human-readable list explaining why escalation was triggered
+ *                    (empty array when escalate === false).
+ *   paulMessage    — the block line to embed in the PR review body;
+ *                    non-empty iff escalate === true.
+ *   canAutoPublish — DATA ONLY, not an authorization by itself (D-173): true iff a clean
+ *                    review (zero criticals, zero reviewer failures, ≥1 reviewer ran)
+ *                    would satisfy D-166's pre-authorized-publish condition. Callers must
+ *                    NOT treat this as license to take an autonomous action (e.g. approving
+ *                    a PR, publishing a release) on its own -- it exists so a separately
+ *                    gated, narrowly-scoped release workflow can consume it for the actual
+ *                    SAT-437/D-166 publish decision. The general per-PR review script
+ *                    deliberately does NOT act on it -- see that script's own comments.
+ */
+export function shouldEscalateToPaul({ criticals = [], failed = [], total = 0 } = {}) {
+  const reasons = [];
+
+  // P0 / critical findings — must never pass silently
+  if (criticals.length > 0) {
+    reasons.push(`${criticals.length} CRITICAL finding(s)`);
+  }
+
+  const allFailed = total > 0 && failed.length === total;
+
+  if (allFailed) {
+    // No reviewer returned a result — outcome is unknowable (ambiguous)
+    reasons.push('all reviewers failed (no result — ambiguous)');
+  } else if (failed.length > 0) {
+    // At least one reviewer failed — remaining results are incomplete (ambiguous)
+    reasons.push(`${failed.length} of ${total} reviewer(s) failed (degraded — ambiguous)`);
+  }
+
+  const escalate = reasons.length > 0;
+
+  // D-166 (SAT-466): pre-authorized auto-publish path — zero criticals, all reviewers
+  // succeeded, and at least one reviewer actually ran.  Do NOT auto-publish when total
+  // is 0 (no-reviewer synthetic run) — that would be a silent pass with no evidence.
+  const canAutoPublish = !escalate && total > 0 && failed.length === 0;
+
+  return {
+    escalate,
+    reasons,
+    paulMessage: escalate
+      ? 'Merge blocked until CRITICAL items are resolved or dismissed by Paul.'
+      : '',
+    canAutoPublish,
+  };
+}