@sanqianx/project-knowledge 5.0.24 → 5.0.25

package/_site/_test/helpers/parallel-engine-advanced-harness.js

@@ -0,0 +1,245 @@
+'use strict';
+
+// P-ENG-ADVANCED lane-exclusive harness (parallel-20261023 batch).
+//
+// Drives the VENDORED knowledge-engine (_modules/knowledge-engine, byte-identical
+// to source e5573bb at batch time) inside real child processes with full
+// isolation: ephemeral loopback ports, lane-owned data dirs under
+// PK_TEST_TEMP_ROOT (or the OS temp dir), isolated HOME/TEMP, and a
+// scrubbed child environment (no KB_*/KNOWLEDGE_*/ANTHROPIC_*/CLAUDE* leakage,
+// no env -u dependency). The analyzer is a DECLARATIVE STAND-IN: it writes real
+// staged Markdown + manifest bytes through the engine's real promotion path but
+// does NOT cover real model output. The vector endpoint is a loopback HTTP
+// double: engine-side index behavior is real, vector-hub itself is not covered.
+
+const { spawn, execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const http = require('node:http');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const VENDORED_ENGINE_SERVER = path.join(REPO_ROOT, '_modules', 'knowledge-engine', 'src', 'server.js');
+const ENGINE_CHILD = path.join(__dirname, 'parallel-engine-advanced-engine-child.js');
+
+// Temp root: PK_TEST_TEMP_ROOT or the OS temp dir; never inside the repository.
+const TEMP_ROOT = (() => {
+  const base = path.resolve(process.env.PK_TEST_TEMP_ROOT || path.join(os.tmpdir(), 'project-knowledge-engine-test', 'parallel-engine-advanced'));
+  if (base === REPO_ROOT || base.startsWith(REPO_ROOT + path.sep)) {
+    throw new Error(`temp root must live outside the repository (got ${base})`);
+  }
+  return base;
+})();
+
+function ensureTempRoot() {
+  fs.mkdirSync(TEMP_ROOT, { recursive: true });
+  return TEMP_ROOT;
+}
+
+function makeLaneDir(label) {
+  ensureTempRoot();
+  const dir = fs.mkdtempSync(path.join(TEMP_ROOT, `${label}-`));
+  return dir;
+}
+
+function isolatedEnv(extra = {}) {
+  const home = extra.ISOLATED_HOME || path.join(ensureTempRoot(), 'isolated-home');
+  fs.mkdirSync(home, { recursive: true });
+  const env = { ...process.env };
+  for (const name of Object.keys(env)) {
+    if (/^(KB_|KNOWLEDGE_|ANTHROPIC_|CLAUDE|OPENAI_|CODEX|MINIMAX|GLM|PK_TEST_)/i.test(name)) delete env[name];
+  }
+  const tmp = path.join(ensureTempRoot(), 'tmp');
+  fs.mkdirSync(tmp, { recursive: true });
+  env.HOME = home;
+  env.USERPROFILE = home;
+  env.APPDATA = path.join(home, 'AppData', 'Roaming');
+  env.LOCALAPPDATA = path.join(home, 'AppData', 'Local');
+  env.TEMP = tmp;
+  env.TMP = tmp;
+  env.TMPDIR = tmp;
+  env.GIT_CONFIG_NOSYSTEM = '1';
+  env.GIT_CONFIG_GLOBAL = path.join(home, 'does-not-exist.gitconfig');
+  return { ...env, ...Object.fromEntries(Object.entries(extra).filter(([k]) => k !== 'ISOLATED_HOME')) };
+}
+
+function git(repoPath, args, env) {
+  return execFileSync('git', args, { cwd: repoPath, windowsHide: true, encoding: 'utf8', env }).trim();
+}
+
+// Real fixture git repository with a baseline plus one labeled commit per entry.
+// Mirrors the canonical fixture shape from the engine suite (test/engine.test.js
+// project()) so scanner.collectEvidence sees the same repo shape it supports.
+function buildFixtureRepo(root, name, commits) {
+  const env = isolatedEnv();
+  const repoPath = path.join(root, `repo-${name}`);
+  fs.mkdirSync(repoPath, { recursive: true });
+  git(repoPath, ['init', '-q'], env);
+  git(repoPath, ['config', 'user.email', 'eng-advanced@test.invalid'], env);
+  git(repoPath, ['config', 'user.name', 'P-ENG-ADVANCED'], env);
+  fs.writeFileSync(path.join(repoPath, 'README.md'), `# ${name}\n\nInitial fixture repository.\n`);
+  git(repoPath, ['add', '.'], env);
+  git(repoPath, ['commit', '-qm', 'baseline'], env);
+  const baseline = git(repoPath, ['rev-parse', 'HEAD'], env);
+  const shas = {};
+  for (const label of commits) {
+    fs.writeFileSync(path.join(repoPath, `${label}.txt`), `change ${name} ${label}\n` + 'x'.repeat(64) + '\n');
+    git(repoPath, ['add', '.'], env);
+    git(repoPath, ['commit', '-qm', `feature ${label}`], env);
+    shas[label] = git(repoPath, ['rev-parse', 'HEAD'], env);
+  }
+  return { repoPath, baseline, shas };
+}
+
+async function waitUntil(fn, timeoutMs, describe) {
+  const started = Date.now();
+  for (;;) {
+    const value = await fn();
+    if (value) return value;
+    if (Date.now() - started > timeoutMs) throw new Error(`waitUntil timed out after ${timeoutMs}ms: ${describe}`);
+    await new Promise(resolve => setTimeout(resolve, 25));
+  }
+}
+
+async function callJson(base, route, body, init = {}) {
+  const response = await fetch(`${base}${route}`, {
+    ...init,
+    method: body === undefined && !init.method ? 'GET' : init.method || 'POST',
+    headers: { 'Content-Type': 'application/json', ...(init.headers || {}) },
+    body: body === undefined && (!init.method || init.method === 'GET') ? undefined : JSON.stringify(body),
+  });
+  let payload = null;
+  try { payload = await response.json(); } catch { payload = null; }
+  return { status: response.status, body: payload };
+}
+
+// Loopback vector-service double. Engine-side requestIndex behavior is fully
+// real; this double only stands in for vector-hub's HTTP contract.
+async function startVectorDouble() {
+  const requests = [];
+  let mode = { kind: 'ok' };
+  const server = http.createServer((req, res) => {
+    let raw = '';
+    req.on('data', chunk => { raw += chunk; });
+    req.on('end', () => {
+      let body = null;
+      try { body = raw ? JSON.parse(raw) : null; } catch { body = null; }
+      requests.push({ at: new Date().toISOString(), url: req.url, body });
+      if (mode.kind === 'ok') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+      } else {
+        res.writeHead(mode.httpStatus || 503, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: { code: mode.code || 'EMBEDDING_UNAVAILABLE', message: mode.message || 'vector double scripted failure' } }));
+      }
+    });
+  });
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  return {
+    url: `http://127.0.0.1:${server.address().port}`,
+    requests,
+    setMode(next) { mode = next; },
+    async close() { server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); },
+  };
+}
+
+// Real engine child process running the vendored server module with the
+// declarative stand-in analyzer. Returns { base, proc, dataDir, killHard, stop }.
+async function startEngineChild({ label, dataDir, vectorUrl, planFile, eventsFile, concurrency }) {
+  fs.mkdirSync(dataDir, { recursive: true });
+  const proc = spawn(process.execPath, [ENGINE_CHILD], {
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+    env: isolatedEnv({
+      ENGADV_DATA_DIR: dataDir,
+      ENGADV_VECTOR_URL: vectorUrl,
+      ENGADV_PLAN_FILE: planFile,
+      ENGADV_EVENTS_FILE: eventsFile,
+      ...(concurrency !== undefined ? { ENGADV_CONCURRENCY: String(concurrency) } : {}),
+    }),
+  });
+  let stderr = '';
+  proc.stderr.on('data', chunk => { stderr += chunk; });
+  const base = await new Promise((resolve, reject) => {
+    let out = '';
+    const timer = setTimeout(() => reject(new Error(`engine child not ready; stderr: ${stderr}`)), 30000);
+    proc.stdout.on('data', chunk => {
+      out += chunk;
+      const match = out.match(/^ENGADV-READY (\{.*\})\n/m);
+      if (match) {
+        clearTimeout(timer);
+        resolve(JSON.parse(match[1]).base);
+      }
+    });
+    proc.on('exit', code => { clearTimeout(timer); reject(new Error(`engine child exited early (${code}); stderr: ${stderr}`)); });
+  });
+  async function killHard() {
+    if (proc.exitCode !== null || proc.signalCode !== null) return proc.exitCode;
+    // A HARD crash must not run the engine's graceful shutdown. On POSIX the
+    // default signal of kill() is SIGTERM, and the engine child traps SIGTERM
+    // to close the server gracefully - which releases the single-writer lock
+    // file, so the residual-lock state under test would never exist (root CI
+    // 39927630516 failed on Linux with ENOENT on engine-runtime.lock). SIGKILL
+    // cannot be trapped, so the process dies with the lock still on disk; on
+    // Windows Node maps SIGKILL to TerminateProcess, which is what kill()
+    // already did there.
+    proc.kill('SIGKILL');
+    return await new Promise(resolve => {
+      if (proc.exitCode !== null || proc.signalCode !== null) return resolve(proc.exitCode);
+      proc.on('exit', code => resolve(code));
+    });
+  }
+  async function stop() {
+    if (proc.exitCode !== null) return;
+    proc.send({ type: 'kb:shutdown' });
+    await new Promise(resolve => {
+      const timer = setTimeout(() => { try { proc.kill(); } catch {} resolve(); }, 15000);
+      proc.on('exit', () => { clearTimeout(timer); resolve(); });
+    });
+  }
+  return { base, proc, dataDir, killHard, stop, stderr: () => stderr };
+}
+
+function readEventsFile(eventsFile) {
+  if (!fs.existsSync(eventsFile)) return [];
+  return fs.readFileSync(eventsFile, 'utf8').split('\n').filter(Boolean).map(line => JSON.parse(line));
+}
+
+function writePlan(planFile, plan) {
+  fs.mkdirSync(path.dirname(planFile), { recursive: true });
+  fs.writeFileSync(planFile, JSON.stringify(plan, null, 1));
+}
+
+function listFilesRecursive(root) {
+  const out = [];
+  if (!fs.existsSync(root)) return out;
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const absolute = path.join(root, entry.name);
+    if (entry.isDirectory()) out.push(...listFilesRecursive(absolute).map(sub => `${entry.name}/${sub}`));
+    else out.push(entry.name);
+  }
+  return out.sort();
+}
+
+function saveEvidence(laneDir, name, value) {
+  fs.mkdirSync(laneDir, { recursive: true });
+  fs.writeFileSync(path.join(laneDir, name), JSON.stringify(value, null, 2));
+}
+
+module.exports = {
+  REPO_ROOT,
+  VENDORED_ENGINE_SERVER,
+  TEMP_ROOT,
+  makeLaneDir,
+  isolatedEnv,
+  git,
+  buildFixtureRepo,
+  waitUntil,
+  callJson,
+  startVectorDouble,
+  startEngineChild,
+  readEventsFile,
+  writePlan,
+  listFilesRecursive,
+  saveEvidence,
+};

package/_site/_test/helpers/parallel-engine-advanced-standin-analyzer.js

@@ -0,0 +1,80 @@
+'use strict';
+
+// P-ENG-ADVANCED declarative stand-in analyzer.
+//
+// HONEST SCOPE LABEL: this analyzer produces real staged Markdown bytes and a
+// valid knowledge-staging-manifest through the engine's REAL promotion path,
+// but it does NOT cover real model output, real prompt adherence, or the
+// headless Claude Agent SDK worker. Every case that relies on it is evidence
+// about engine scheduling/promotion/indexing machinery, never about model
+// quality. The debug simulateFailure flag is handled by the engine itself
+// BEFORE this analyzer runs (DEBUG_SIMULATED_FAILURE).
+//
+// Plan file shape (JSON, read per claim):
+// {
+//   "default": { "delayMs": 300, "markdownHeader": "..." },
+//   "rules": [{ "projectId": "...", "commitSha": "...", "delayMs": 5000 }]
+// }
+// Behavior: sleep delayMs (timing control), then write
+// changes/<sha12>.md plus the manifest with the frozen claim evidence refs.
+// Every start/finish appends a JSONL record to the events file for
+// cross-process invocation-count and overlap evidence.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const AtomicFile = require('../../../_modules/knowledge-engine/src/runtime/atomic-file.js');
+
+function hashBuffer(value) {
+  return `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`;
+}
+
+function appendEvent(eventsFile, record) {
+  if (!eventsFile) return;
+  fs.mkdirSync(path.dirname(eventsFile), { recursive: true });
+  fs.appendFileSync(eventsFile, `${JSON.stringify({ ...record, at: new Date().toISOString(), pid: process.pid })}\n`);
+}
+
+function readPlan(planFile) {
+  if (!planFile || !fs.existsSync(planFile)) return { default: {} };
+  try { return JSON.parse(fs.readFileSync(planFile, 'utf8')); } catch { return { default: {} }; }
+}
+
+function createStandinAnalyzer({ planFile, eventsFile } = {}) {
+  return {
+    sourceReadMode: 'isolated-frozen-evidence',
+    async runClaim(input) {
+      const plan = readPlan(planFile);
+      const rule = (plan.rules || []).find(r => (!r.projectId || r.projectId === input.projectId) && (!r.commitSha || r.commitSha === input.claim.commitSha)) || {};
+      const effective = { ...(plan.default || {}), ...rule };
+      appendEvent(eventsFile, { kind: 'start', projectId: input.projectId, commitSha: input.claim.commitSha, runId: input.claim.runId, delayMs: effective.delayMs || 0 });
+      if (effective.delayMs) await new Promise(resolve => setTimeout(resolve, effective.delayMs));
+      const relative = `changes/${input.claim.commitSha.slice(0, 12)}.md`;
+      const content = `${effective.markdownHeader || '# Verified maintenance'} ${input.projectId}\n\nCommit ${input.claim.commitSha} implements a fixture change.\n\n- Project: ${input.projectId}\n- Staged by: declarative stand-in analyzer (no real model output)\n`;
+      AtomicFile.writeFileAtomic(path.join(input.stagingPath, 'files', relative), content);
+      const refs = [
+        `commit:${input.claim.commitSha}`,
+        input.claim.patchHash && `patch:${input.claim.patchHash}`,
+        input.claim.conversationSnapshotHash && `conversation:${input.claim.conversationSnapshotHash}`,
+        input.claim.retrievalManifestHash && `retrieval:${input.claim.retrievalManifestHash}`,
+      ].filter(Boolean);
+      AtomicFile.writeJsonAtomic(input.manifestPath, {
+        schema: 'knowledge-staging-manifest/v1',
+        projectId: input.projectId,
+        runId: input.claim.runId,
+        commitSha: input.claim.commitSha,
+        operations: [{
+          path: relative,
+          operation: 'create',
+          sha256: hashBuffer(content),
+          reason: 'Frozen Git evidence from fixture commit',
+          evidenceReferences: refs,
+        }],
+      });
+      appendEvent(eventsFile, { kind: 'finish', projectId: input.projectId, commitSha: input.claim.commitSha, runId: input.claim.runId });
+      return { ok: true };
+    },
+  };
+}
+
+module.exports = { createStandinAnalyzer };

package/_site/_test/helpers/parallel-engine-advanced-ui-host.js

@@ -0,0 +1,177 @@
+'use strict';
+
+// P-ENGINE-REVIEW-R2/R3 lane-exclusive candidate host for the knowledge-engine UI.
+//
+// Purpose: let a REAL browser load the REAL product UI bytes from a directory
+// the caller chooses (the vendored copy = as shipped, or the module source
+// tree = candidate fix), while /api/* is reverse-proxied to the REAL vendored
+// engine - mirroring the product shell wiring where the UI is embedded
+// same-origin behind the shell proxy. The engine refuses cross-origin
+// requests (src/server.js FORBIDDEN_ORIGIN), so the browser origin and the
+// API origin must be this one host.
+//
+// Harness-only fault injection (never touches the engine or the UI bytes):
+//   * retryDelayMs      - hold retry POST responses so a second native click can
+//                         land while the first intent is still in flight.
+//   * dropRetry         - forward the retry POST upstream, let the engine really
+//                         execute it, then destroy the browser socket without
+//                         any response bytes (lost response -> the product
+//                         client faces an UNKNOWN result).
+//   * rejectRetryStatus - answer the retry POST with an explicit error status
+//                         (e.g. 409) WITHOUT forwarding it (the API clearly
+//                         refused the intent).
+//   * holdRetryForward  - accept the retry POST but do NOT forward it yet, so
+//                         the engine still reports the run as failed and every
+//                         detail re-render rebuilds a retry button for the SAME
+//                         in-flight intent (the re-render counter-proof).
+//                         releaseHeldRetries() forwards the parked requests.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const http = require('node:http');
+const path = require('node:path');
+
+const STATIC_FILES = new Map([
+  ['/', ['index.html', 'text/html; charset=utf-8']],
+  ['/index.html', ['index.html', 'text/html; charset=utf-8']],
+  ['/app.js', ['app.js', 'text/javascript; charset=utf-8']],
+  ['/app.css', ['app.css', 'text/css; charset=utf-8']],
+]);
+
+function fileSha(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function startUiHost({ uiDir, engineBase, retryDelayMs = 0, dropRetry = false, rejectRetryStatus = 0, holdRetryForward = false }) {
+  const settings = { retryDelayMs, dropRetry, rejectRetryStatus, holdRetryForward };
+  const state = {
+    proxiedApiRequests: 0,
+    receivedRetryPosts: 0,
+    forwardedRetryPosts: 0,
+    rejectedRetryResponses: 0,
+    heldRetryPosts: 0,
+    droppedRetryResponses: 0,
+  };
+  const held = [];
+
+  const forward = ({ url, method, headers, body }, res, isRetryPost) => {
+    const target = new URL(url.pathname + url.search, engineBase);
+    const outHeaders = { ...headers, host: target.host };
+    delete outHeaders.origin;
+    delete outHeaders.connection;
+    delete outHeaders['proxy-connection'];
+    delete outHeaders['content-length'];
+    if (body.length) outHeaders['content-length'] = String(body.length);
+    if (isRetryPost) state.forwardedRetryPosts += 1;
+    const upstream = http.request(target, { method, headers: outHeaders }, up => {
+      const responseChunks = [];
+      up.on('data', chunk => responseChunks.push(chunk));
+      up.on('end', () => {
+        const payload = Buffer.concat(responseChunks);
+        if (isRetryPost && settings.dropRetry) {
+          // The engine has fully executed the retry. Start the response (so
+          // the browser cannot transparently retry the request on a fresh
+          // keep-alive connection) and then destroy the socket mid-flight -
+          // the product client faces a truncated answer, i.e. an UNKNOWN
+          // result it must reconcile by querying, never by re-dispatching.
+          state.droppedRetryResponses += 1;
+          const out = { ...up.headers };
+          delete out['content-length'];
+          delete out['transfer-encoding'];
+          delete out.connection;
+          res.writeHead(up.statusCode, out);
+          res.flushHeaders();
+          setTimeout(() => res.destroy(), 30);
+          return;
+        }
+        const reply = () => {
+          const out = { ...up.headers };
+          delete out['content-length'];
+          delete out['transfer-encoding'];
+          delete out.connection;
+          if (payload.length) out['content-length'] = String(payload.length);
+          res.writeHead(up.statusCode, out);
+          res.end(payload);
+        };
+        if (isRetryPost && settings.retryDelayMs > 0) setTimeout(reply, settings.retryDelayMs);
+        else reply();
+      });
+    });
+    upstream.on('error', () => res.destroy());
+    upstream.end(body);
+  };
+
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    const staticEntry = req.method === 'GET' ? STATIC_FILES.get(url.pathname) : null;
+    if (staticEntry) {
+      res.writeHead(200, { 'Content-Type': staticEntry[1], 'Cache-Control': 'no-store' });
+      res.end(fs.readFileSync(path.join(uiDir, staticEntry[0])));
+      return;
+    }
+    if (!url.pathname.startsWith('/api/')) {
+      res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+      res.end('not found');
+      return;
+    }
+    state.proxiedApiRequests += 1;
+    const chunks = [];
+    req.on('data', chunk => chunks.push(chunk));
+    req.on('end', () => {
+      const body = Buffer.concat(chunks);
+      const headers = { ...req.headers };
+      // The shell proxy terminates the browser origin; the engine would refuse
+      // any mismatched Origin header (FORBIDDEN_ORIGIN).
+      delete headers.origin;
+      delete headers.connection;
+      delete headers['proxy-connection'];
+      delete headers['content-length'];
+      const isRetryPost = req.method === 'POST' && /\/api\/runs\/[^/]+\/retry$/.test(url.pathname);
+      if (isRetryPost) state.receivedRetryPosts += 1;
+
+      if (isRetryPost && settings.rejectRetryStatus) {
+        state.rejectedRetryResponses += 1;
+        res.writeHead(settings.rejectRetryStatus, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ ok: false, error: 'RUN_NOT_RETRYABLE', message: `ui-host injected explicit refusal (HTTP ${settings.rejectRetryStatus})` }));
+        return;
+      }
+      if (isRetryPost && settings.holdRetryForward) {
+        state.heldRetryPosts += 1;
+        held.push({ url, method: req.method, headers, body, res });
+        return;
+      }
+      forward({ url, method: req.method, headers, body }, res, isRetryPost);
+    });
+  });
+
+  return {
+    state,
+    uiDir,
+    uiHashes: {
+      'index.html': fileSha(path.join(uiDir, 'index.html')),
+      'app.js': fileSha(path.join(uiDir, 'app.js')),
+      'app.css': fileSha(path.join(uiDir, 'app.css')),
+    },
+    configure(next) { Object.assign(settings, next); },
+    // Forward every parked retry POST and answer it (the held intent finally
+    // reaches the engine).
+    releaseHeldRetries() {
+      const parked = held.splice(0, held.length);
+      for (const request of parked) {
+        const isRetryPost = request.method === 'POST' && /\/api\/runs\/[^/]+\/retry$/.test(request.url.pathname);
+        forward(request, request.res, isRetryPost);
+      }
+      return parked.length;
+    },
+    async listen() {
+      await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+      return `http://127.0.0.1:${server.address().port}`;
+    },
+    async close() {
+      server.closeAllConnections();
+      await new Promise(resolve => server.close(resolve));
+    },
+  };
+}
+
+module.exports = { startUiHost };