@ngockhoale/ukit 3.4.45 → 3.4.47

package/scripts/audit/decision-coverage.mjs

@@ -1,322 +0,0 @@
-#!/usr/bin/env node
-/**
- * decision-coverage.mjs (TASK-004 / M07, SPEC §5 FR-010)
- *
- * CI coverage guard: every consequential decision point in the fixed scan set
- * must be covered by a DECISION_REGISTRY entry or a committed allowlist entry.
- *
- * Discovery convention (deterministic, no invented semantics):
- *   (a) an exported function named /^(derive|resolve|select|choose|decide)[A-Z]/
- *       whose body returns a value drawn from a >=2-member choice set — a
- *       Set/Object.freeze([...])/object-literal constant, a switch, or a
- *       ternary over >=2 string literals;
- *   (b) any site carrying a `// @decision-point <key>` annotation.
- * Point key = the annotation key, else `<basename>:<functionName>`.
- *
- * Allowlist: docs/pstack/decision-coverage-allowlist.json —
- *   [{"key":"<pointKey>","reason":"deterministic|delegated|out-of-scope","owner":"<file>"}]
- *
- * Exit 0 when every discovered point is covered; exit 1 printing each
- * uncovered key (and each invalid allowlist entry). Reports only — does not
- * yet block promotion.
- *
- * Usage: node scripts/audit/decision-coverage.mjs
- *          [--root <dir>] [--allowlist <path>] [--extra-scan <file>...]
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import { DECISION_REGISTRY } from '../../src/decision/registry.js';
-
-const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const DEFAULT_ROOT = path.resolve(SCRIPT_DIR, '..', '..');
-
-// Fixed scan set (FR-010) — relative to the repo root.
-const SCAN_FILES = [
-  'src/index/taskRouting.js',
-  'src/core/executionContracts.js',
-  'template_project/.claude/ukit/index/route-task.mjs',
-];
-const SCAN_GLOBS = ['src/decision/'];
-const DEFAULT_ALLOWLIST = 'docs/pstack/decision-coverage-allowlist.json';
-
-const DECISION_NAME_RE =
-  /^export\s+(?:async\s+)?function\s+((?:derive|resolve|select|choose|decide)[A-Z]\w*)\s*\(/gm;
-const ANNOTATION_RE = /@decision-point\s+([A-Za-z0-9._-]+)/g;
-const CONST_RE =
-  /(?:^|[;{}\n])\s*(?:export\s+)?const\s+([A-Z][A-Za-z0-9_]*)\s*=\s*(?:new\s+Set\s*\(|Object\.freeze\s*\()?\s*([\[{])/g;
-const ALLOWED_REASONS = new Set(['deterministic', 'delegated', 'out-of-scope']);
-
-// --- tiny lexical scanner (strings/comments aware) ---------------------------
-
-function skipString(source, i) {
-  const quote = source[i];
-  for (let j = i + 1; j < source.length; j += 1) {
-    if (source[j] === '\\') { j += 1; continue; }
-    if (source[j] === quote) return j;
-  }
-  return source.length;
-}
-
-function skipLineComment(source, i) {
-  const nl = source.indexOf('\n', i);
-  return nl === -1 ? source.length : nl;
-}
-
-function skipBlockComment(source, i) {
-  const end = source.indexOf('*/', i + 2);
-  return end === -1 ? source.length : end + 1;
-}
-
-// Index of the bracket closing source[openIdx], or -1.
-function findMatching(source, openIdx) {
-  const open = source[openIdx];
-  const close = open === '{' ? '}' : open === '[' ? ']' : ')';
-  let depth = 0;
-  for (let i = openIdx; i < source.length; i += 1) {
-    const ch = source[i];
-    if (ch === "'" || ch === '"' || ch === '`') { i = skipString(source, i); continue; }
-    if (ch === '/' && source[i + 1] === '/') { i = skipLineComment(source, i); continue; }
-    if (ch === '/' && source[i + 1] === '*') { i = skipBlockComment(source, i); continue; }
-    if (ch === open) depth += 1;
-    else if (ch === close) {
-      depth -= 1;
-      if (depth === 0) return i;
-    }
-  }
-  return -1;
-}
-
-// Commas at bracket depth 0 inside (start, end) — member count = commas + 1.
-function countTopLevelCommas(source, start, end) {
-  let depth = 0;
-  let commas = 0;
-  let sawContent = false;
-  for (let i = start; i < end; i += 1) {
-    const ch = source[i];
-    if (ch === "'" || ch === '"' || ch === '`') { i = skipString(source, i); sawContent = true; continue; }
-    if (ch === '/' && source[i + 1] === '/') { i = skipLineComment(source, i); continue; }
-    if (ch === '/' && source[i + 1] === '*') { i = skipBlockComment(source, i); continue; }
-    if (ch === '{' || ch === '[' || ch === '(') depth += 1;
-    else if (ch === '}' || ch === ']' || ch === ')') depth -= 1;
-    else if (ch === ',' && depth === 0) commas += 1;
-    else if (!/\s/.test(ch)) sawContent = true;
-  }
-  return sawContent ? commas + 1 : 0;
-}
-
-// --- discovery ---------------------------------------------------------------
-
-// Names of >=2-member choice-set constants declared anywhere in the file.
-function collectChoiceSets(source) {
-  const names = new Set();
-  CONST_RE.lastIndex = 0;
-  let match;
-  while ((match = CONST_RE.exec(source)) !== null) {
-    const openIdx = match.index + match[0].lastIndexOf(match[2]);
-    const closeIdx = findMatching(source, openIdx);
-    if (closeIdx === -1) continue;
-    if (countTopLevelCommas(source, openIdx + 1, closeIdx) >= 2) {
-      names.add(match[1]);
-    }
-    CONST_RE.lastIndex = openIdx + 1;
-  }
-  return names;
-}
-
-// Heuristic (a): the body returns from a >=2-member choice set — a switch, a
-// ternary over >=2 string literals, or a reference to a choice-set constant.
-function isConsequential(body, choiceSetNames) {
-  if (/\bswitch\s*\(/.test(body)) return true;
-  if (/\?\s*['"][^'"]*['"]\s*:\s*['"]/.test(body)) return true;
-  for (const name of choiceSetNames) {
-    if (new RegExp(`\\b${name}\\b`).test(body)) return true;
-  }
-  return false;
-}
-
-function discoverInSource(source, basename) {
-  const points = [];
-  const choiceSets = collectChoiceSets(source);
-
-  DECISION_NAME_RE.lastIndex = 0;
-  let match;
-  while ((match = DECISION_NAME_RE.exec(source)) !== null) {
-    const paramsOpen = source.indexOf('(', match.index + match[0].indexOf('('));
-    const paramsClose = findMatching(source, paramsOpen);
-    if (paramsClose === -1) continue;
-    const bodyOpen = source.indexOf('{', paramsClose);
-    if (bodyOpen === -1) continue;
-    const bodyClose = findMatching(source, bodyOpen);
-    if (bodyClose === -1) continue;
-    const body = source.slice(bodyOpen, bodyClose + 1);
-    if (isConsequential(body, choiceSets)) {
-      points.push(`${basename}:${match[1]}`);
-    }
-    DECISION_NAME_RE.lastIndex = bodyClose + 1;
-  }
-
-  ANNOTATION_RE.lastIndex = 0;
-  while ((match = ANNOTATION_RE.exec(source)) !== null) {
-    points.push(match[1]);
-  }
-  return points;
-}
-
-// --- CLI ---------------------------------------------------------------------
-
-function parseArgs(argv) {
-  const args = { root: DEFAULT_ROOT, allowlist: null, extraScan: [] };
-  const valueFor = (flag, i) => {
-    const next = argv[i + 1];
-    if (next === undefined || next.startsWith('--')) {
-      console.error(`missing value for ${flag}`);
-      process.exit(2);
-    }
-    return next;
-  };
-  for (let i = 0; i < argv.length; i += 1) {
-    if (argv[i] === '--root') { args.root = path.resolve(valueFor('--root', i)); i += 1; }
-    else if (argv[i] === '--allowlist') { args.allowlist = path.resolve(valueFor('--allowlist', i)); i += 1; }
-    else if (argv[i] === '--extra-scan') { args.extraScan.push(path.resolve(valueFor('--extra-scan', i))); i += 1; }
-    else {
-      console.error(`unknown argument: ${argv[i]}`);
-      process.exit(2);
-    }
-  }
-  return args;
-}
-
-function scanFiles(root, extraScan) {
-  const files = SCAN_FILES.map((f) => path.join(root, f));
-  for (const dir of SCAN_GLOBS) {
-    const absDir = path.join(root, dir);
-    if (!fs.existsSync(absDir)) {
-      return { error: `scan directory missing: ${dir}` };
-    }
-    for (const entry of fs.readdirSync(absDir).sort()) {
-      if (entry.endsWith('.js')) files.push(path.join(absDir, entry));
-    }
-  }
-  for (const extra of extraScan) {
-    let stat;
-    try {
-      stat = fs.statSync(extra);
-    } catch (error) {
-      return { error: `extra-scan path is not a file: ${extra} (${error.code ?? error.message})` };
-    }
-    if (!stat.isFile()) {
-      return { error: `extra-scan path is not a file: ${extra}` };
-    }
-  }
-  files.push(...extraScan);
-  return { files };
-}
-
-function loadAllowlist(allowlistPath) {
-  if (!fs.existsSync(allowlistPath)) {
-    return { entries: [], errors: [`allowlist missing: ${allowlistPath}`] };
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(fs.readFileSync(allowlistPath, 'utf8'));
-  } catch (error) {
-    return { entries: [], errors: [`allowlist is not valid JSON: ${error.message}`] };
-  }
-  if (!Array.isArray(parsed)) {
-    return { entries: [], errors: ['allowlist must be a JSON array'] };
-  }
-  const entries = [];
-  const errors = [];
-  parsed.forEach((entry, index) => {
-    const label = `allowlist[${index}]`;
-    if (!entry || typeof entry !== 'object') {
-      errors.push(`${label}: entry must be an object`);
-      return;
-    }
-    if (typeof entry.key !== 'string' || entry.key.length === 0) {
-      errors.push(`${label}: key must be a non-empty string`);
-      return;
-    }
-    if (!ALLOWED_REASONS.has(entry.reason)) {
-      errors.push(
-        `${label} (${entry.key}): reason must be one of: ${[...ALLOWED_REASONS].join(', ')}`,
-      );
-      return;
-    }
-    if (typeof entry.owner !== 'string' || entry.owner.length === 0) {
-      errors.push(`${label} (${entry.key}): owner must be a non-empty string`);
-      return;
-    }
-    entries.push(entry);
-  });
-  return { entries, errors };
-}
-
-function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const allowlistPath = args.allowlist ?? path.join(args.root, DEFAULT_ALLOWLIST);
-
-  const { files, error } = scanFiles(args.root, args.extraScan);
-  if (error) {
-    console.error(`decision-coverage: ${error}`);
-    process.exit(1);
-  }
-
-  const discovered = [];
-  for (const file of files) {
-    if (!fs.existsSync(file)) {
-      console.error(`decision-coverage: scan file missing: ${path.relative(args.root, file)}`);
-      process.exit(1);
-    }
-    let source;
-    try {
-      source = fs.readFileSync(file, 'utf8');
-    } catch (error) {
-      const rel = path.relative(args.root, file);
-      console.error(
-        `decision-coverage: cannot read ${rel}: ${error.code ?? error.message}`,
-      );
-      process.exit(1);
-    }
-    discovered.push(...discoverInSource(source, path.basename(file)));
-  }
-
-  const registryKeys = new Set(DECISION_REGISTRY.map((entry) => entry.decisionKey));
-  const { entries, errors } = loadAllowlist(allowlistPath);
-  const allowlisted = new Set(entries.map((entry) => entry.key));
-
-  const uncovered = [...new Set(discovered)]
-    .filter((key) => !registryKeys.has(key) && !allowlisted.has(key))
-    .sort();
-
-  for (const err of errors) {
-    console.log(`INVALID-ALLOWLIST ${err}`);
-  }
-  for (const key of uncovered) {
-    console.log(`UNCOVERED ${key}`);
-  }
-
-  if (errors.length > 0 || uncovered.length > 0) {
-    console.log(
-      `decision-coverage: FAIL — ${uncovered.length} uncovered, ${errors.length} invalid allowlist entries`,
-    );
-    process.exit(1);
-  }
-  const registryCovered = [...new Set(discovered)].filter((k) => registryKeys.has(k)).length;
-  console.log(
-    `decision-coverage: ok — ${new Set(discovered).size} decision points covered ` +
-    `(registry: ${registryCovered}, allowlisted: ${new Set(discovered).size - registryCovered})`,
-  );
-}
-
-try {
-  main();
-} catch (error) {
-  console.error(
-    `decision-coverage: ${error instanceof Error ? error.message : String(error)}`,
-  );
-  process.exit(1);
-}

package/scripts/audit/subagent-cost/analyze.mjs

@@ -1,107 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { loadCorpus } from './reader.mjs';
-import { computeMetrics } from './metrics.mjs';
-import { computeDuplicates } from './duplicates.mjs';
-import { renderMarkdown } from './render.mjs';
-
-const MISSING = [
-  'Provider/gateway id is not recorded in transcript usage.',
-  'Native request latency is unavailable; timestamp gaps are only approximate.',
-  'Retry counts are not recorded as a distinct telemetry field.',
-  'Per-sub-agent request-shape cost is unavailable.',
-  'Price table is absent; currency cost cannot be calculated.',
-  'Codex and omp transcripts are not included by this Claude Code reader.',
-  'Observability token categories are unavailable.',
-];
-
-export async function buildReport(root, opts = {}) {
-  const corpus = await loadCorpus(root, { since: opts.since ?? null, until: opts.until ?? null });
-  // Wave-1 reader predates the normalized call.depth field; derive it without
-  // changing that shared module, while honoring depth when it is already present.
-  const depthByAgent = new Map(corpus.agents.map((agent) => [`${agent.sessionId}\u0000${agent.agentId}`, agent.depth]));
-  for (const call of corpus.calls) {
-    if (call.depth == null) call.depth = call.agentId == null ? 0 : (depthByAgent.get(`${call.sessionId}\u0000${call.agentId}`) ?? 1);
-  }
-  const metrics = computeMetrics(corpus);
-  const duplicates = computeDuplicates(corpus);
-  const headline = {
-    subShare: metrics.share.subOfInputSide,
-    subUncachedShare: metrics.share.subOfUncached,
-    contextAmplification: duplicates.amplification,
-    duplicateContextRatio: duplicates.duplicateRatio,
-    avgCallsPerTask: metrics.perTask.avgCalls,
-  };
-  return {
-    schema: 'subagent-cost/v1',
-    generatedAt: new Date().toISOString(),
-    root: path.basename(path.resolve(root)),
-    window: { since: opts.since ?? null, until: opts.until ?? null },
-    stats: corpus.stats,
-    headline,
-    metrics,
-    duplicates,
-    missing: [...MISSING],
-  };
-}
-
-function parseArgs(args) {
-  const opts = {};
-  const allowed = new Set(['--root', '--since', '--until', '--json', '--md']);
-  for (let i = 0; i < args.length; i += 1) {
-    const flag = args[i];
-    if (!allowed.has(flag)) throw new Error(`bad flag: ${flag}`);
-    const value = args[i + 1];
-    if (!value || value.startsWith('--')) throw new Error(`missing value for ${flag}`);
-    if (opts[flag]) throw new Error(`duplicate flag: ${flag}`);
-    opts[flag] = value;
-    i += 1;
-  }
-  if (!opts['--root']) throw new Error('missing required --root');
-  for (const flag of ['--since', '--until']) {
-    if (opts[flag] && !Number.isFinite(Date.parse(opts[flag]))) throw new Error(`invalid ISO date for ${flag}: ${opts[flag]}`);
-  }
-  if (opts['--since'] && opts['--until'] && Date.parse(opts['--since']) > Date.parse(opts['--until'])) throw new Error('--since must be <= --until');
-  return opts;
-}
-
-async function main(args) {
-  let opts;
-  try {
-    opts = parseArgs(args);
-  } catch (error) {
-    process.stderr.write(`${error.message}\n`);
-    return 2;
-  }
-  let report;
-  try {
-    report = await buildReport(opts['--root'], { since: opts['--since'] ?? null, until: opts['--until'] ?? null });
-  } catch (error) {
-    process.stderr.write(`${error.message}\n`);
-    return 2;
-  }
-  const markdown = renderMarkdown(report);
-  try {
-    if (opts['--json']) {
-      fs.mkdirSync(path.dirname(path.resolve(opts['--json'])), { recursive: true });
-      fs.writeFileSync(opts['--json'], `${JSON.stringify(report, null, 2)}\n`);
-    }
-    if (opts['--md']) {
-      fs.mkdirSync(path.dirname(path.resolve(opts['--md'])), { recursive: true });
-      fs.writeFileSync(opts['--md'], markdown);
-    }
-  } catch (error) {
-    process.stderr.write(`${error.message}\n`);
-    return 2;
-  }
-  process.stdout.write(`subagent-cost: ${report.metrics.totals.main.calls + report.metrics.totals.sub.calls} calls, ${report.stats.files} files, headline subShare=${report.headline.subShare}\n`);
-  if (opts['--json']) process.stdout.write(`json: ${path.resolve(opts['--json'])}\n`);
-  if (opts['--md']) process.stdout.write(`md: ${path.resolve(opts['--md'])}\n`);
-  return 0;
-}
-
-const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : null;
-if (invokedPath === fileURLToPath(import.meta.url)) {
-  process.exitCode = await main(process.argv.slice(2));
-}

package/scripts/audit/subagent-cost/check-doc.mjs

@@ -1,91 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { realpathSync } from 'node:fs';
-import { pathToFileURL } from 'node:url';
-
-const HEADLINE_KEYS = ['subShare', 'subUncachedShare', 'contextAmplification', 'duplicateContextRatio', 'avgCallsPerTask'];
-const MARKER = /<!--\s*HEADLINE\s+(\{[^\n]*\})\s*-->/;
-
-function parseArgs(args) {
-  const options = {};
-  for (let i = 0; i < args.length; i += 1) {
-    const flag = args[i];
-    if (!['--doc', '--report'].includes(flag) || !args[i + 1] || args[i + 1].startsWith('--')) {
-      throw new Error('usage: check-doc.mjs --doc <md> --report <json>');
-    }
-    if (options[flag]) throw new Error(`duplicate flag: ${flag}`);
-    options[flag] = args[++i];
-  }
-  if (!options['--doc'] || !options['--report']) throw new Error('usage: check-doc.mjs --doc <md> --report <json>');
-  return options;
-}
-
-async function checkDoc(docPath, reportPath) {
-  let doc;
-  let reportText;
-  try {
-    [doc, reportText] = await Promise.all([readFile(docPath, 'utf8'), readFile(reportPath, 'utf8')]);
-  } catch (error) {
-    console.error(`check-doc: ${error.message}`);
-    return 2;
-  }
-
-  let report;
-  try {
-    report = JSON.parse(reportText);
-  } catch {
-    console.error('check-doc: report is not valid JSON');
-    return 2;
-  }
-  const marker = doc.match(MARKER);
-  if (!marker) {
-    console.error('check-doc: missing HEADLINE marker');
-    return 2;
-  }
-  let embedded;
-  try {
-    embedded = JSON.parse(marker[1]);
-  } catch {
-    console.error('check-doc: invalid HEADLINE JSON');
-    return 2;
-  }
-
-  const mismatches = [];
-  const headline = report?.headline;
-  for (const key of HEADLINE_KEYS) {
-    const actual = embedded[key];
-    const expected = headline?.[key];
-    if (actual === null || expected === null) {
-      if (actual !== expected) mismatches.push(key);
-    } else if (typeof actual !== 'number' || !Number.isFinite(actual) || typeof expected !== 'number' || !Number.isFinite(expected) || Math.abs(actual - expected) > 0.001 * Math.max(1, Math.abs(actual), Math.abs(expected))) {
-      mismatches.push(key);
-    }
-  }
-
-  for (let section = 1; section <= 17; section += 1) {
-    if (!new RegExp(`^## ${section}\\.`, 'm').test(doc)) mismatches.push(`## ${section}.`);
-  }
-  for (let question = 1; question <= 16; question += 1) {
-    if (!new RegExp(`\\bQ${question}\\b`).test(doc)) mismatches.push(`Q${question}`);
-  }
-
-  if (mismatches.length) {
-    console.error(`check-doc: mismatch: ${[...new Set(mismatches)].join(', ')}`);
-    return 1;
-  }
-  console.log('check-doc: headline and required markers match');
-  return 0;
-}
-
-async function main() {
-  let options;
-  try {
-    options = parseArgs(process.argv.slice(2));
-  } catch (error) {
-    console.error(`check-doc: ${error.message}`);
-    process.exitCode = 2;
-    return;
-  }
-  process.exitCode = await checkDoc(options['--doc'], options['--report']);
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) await main();