@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/review/command.js

@@ -0,0 +1,246 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { validateFindings, countFindings, reviewAdvisories, invalidProjectCandidate, invalidPresetCandidate, telemetryProtocol } = require('./findings.js');
+const { resolveActiveFeature } = require('../feature-resolve.js');
+const { TelemetryWriter } = require('../trace/telemetry.js');
+const { finishRuntime } = require('../cli-result.js');
+const { handleReviewStart, validSlug } = require('./start.js');
+const { crossCheckAuthor, authoringIdentities } = require('./identity.js');
+const { isQualifiedId } = require('../../helper/package-ids.js');
+
+                                        
+                                              
+                                                                                      
+                                                                 
+                                                                                       
+
+const TELEMETRY_COUNT_KEYS = Object.freeze([
+  'rounds', 'seats', 'seat_findings', 'converged', 'blocker', 'should_fix', 'note',
+  'open', 'fixed', 'refuted', 'user_accepted', 'pre_existing', 'escaped', 'confirmed',
+  'plausible', 'unverified_blockers', 'bug_classes',
+]);
+
+// Inherited location variables would point the check at another repository (C-8).
+const GIT_LOCATION_KEYS = Object.freeze([
+  'GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_COMMON_DIR',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+]);
+
+function defaultGit(args          , cwd        , env     )                            {
+  const gitEnv = { ...env };
+  for (const key of GIT_LOCATION_KEYS) delete gitEnv[key];
+  return spawnSync('git', ['-C', cwd, ...args], { cwd, env: gitEnv, stdio: 'ignore' });
+}
+
+/** The project's `review.sameFamily` (119 L-C3), read for the checkout the verb runs in. A settings view that cannot
+ * load, or an invalid project or local value for the key (C-6: the resolver would fall back to the default without a
+ * word), is `warn` plus `unread`; the caller turns `unread` into an error. Never a crash, never a silent `refuse`. */
+function readSameFamily(load                                                     , cwd        , env     )                                                {
+  try {
+    const resolution = load({ projectRoot: path.resolve(cwd), env }).get('review.sameFamily');
+    if (invalidProjectCandidate(resolution)) return { value: 'warn', unread: true };
+    return { value: resolution.value === 'refuse' ? 'refuse' : 'warn', unread: false };
+  } catch {
+    return { value: 'warn', unread: true };
+  }
+}
+
+/** The effective `review.preset` (C-2 closure), read for the checkout the verb runs in. A settings view that cannot
+ * load, or an invalid user, project or local value (the resolver would fall back to `auto` without a word), is `unread`;
+ * the caller turns `unread` into an error, so a broken setting never relaxes the check. */
+function readPreset(load                                                     , cwd        , env     )                                     {
+  try {
+    const resolution = load({ projectRoot: path.resolve(cwd), env }).get('review.preset');
+    if (invalidPresetCandidate(resolution)) return { value: 'auto', unread: true };
+    return { value: typeof resolution.value === 'string' ? resolution.value : 'auto', unread: false };
+  } catch {
+    return { value: 'auto', unread: true };
+  }
+}
+
+// A preset id: a core one as protocols.ts validates it (`^[a-z][a-z0-9-]*$`), or a package preset's qualified id
+// (`<package>.<preset>`, 122 IC-003). Whether it is available and strict enough is the resolver's answer (IC-014).
+const CORE_PRESET_ID = /^[a-z][a-z0-9-]*$/;
+const presetIdShape = (value         )          => typeof value === 'string' && (CORE_PRESET_ID.test(value) || isQualifiedId(value));
+
+function usage(message        , json         , out                        )         {
+  out(json
+    ? JSON.stringify({ ok: false, error: 'usage', message })
+    : `doflow review: ${message}`);
+  return finishRuntime(2);
+}
+
+function hasValue(value         )          {
+  return value !== undefined && value !== null;
+}
+
+function emptyValue(value         )          {
+  return typeof value === 'string' && value.trim().length === 0;
+}
+
+function handleReviewCommand({
+  action,
+  slug,
+  path: recordPath,
+  base,
+  preset,
+  adviceClient,
+  json = false,
+  cwd = process.cwd(),
+  env = process.env,
+  git = defaultGit,
+  loadSettings = (options                                   ) => require('../settings/resolve.js').loadSettings(options),
+  writer,
+  resolve = resolveActiveFeature,
+  out = (line        ) => console.log(line),
+}      = {})                           {
+  if (action !== 'check' && action !== 'start') return usage('action must be check or start', json, out);
+  if (emptyValue(slug) || emptyValue(recordPath) || emptyValue(base) || emptyValue(preset)) return usage('flag values must not be empty', json, out);
+  if (action === 'start') {
+    // 095b IC-001: the start verb reads no record path, and the slug becomes a file name.
+    if (hasValue(recordPath)) return usage('--path is not valid with --action start', json, out);
+    if ((hasValue(slug) && !validSlug(slug)) || (hasValue(base) && typeof base !== 'string')) {
+      return usage('--slug must be a plain feature name and --base a string', json, out);
+    }
+    if (hasValue(preset) && !presetIdShape(preset)) {
+      return usage('--preset must be a preset id (lower-case letters, digits and hyphens, or <package>.<preset> for a package preset)', json, out);
+    }
+    return handleReviewStart({ slug: hasValue(slug) ? slug : null, base: hasValue(base) ? base : null, preset: hasValue(preset) ? preset : null, json, cwd, env, resolve, adviceClient, out });
+  }
+  if (hasValue(base)) return usage('--base is valid only with --action start', json, out);
+  if (hasValue(preset)) return usage('--preset is valid only with --action start', json, out);
+  if (hasValue(slug) && hasValue(recordPath)) return usage('use either --slug or --path, not both', json, out);
+  if ((hasValue(slug) && typeof slug !== 'string') || (hasValue(recordPath) && typeof recordPath !== 'string')) {
+    return usage('--slug and --path values must be strings', json, out);
+  }
+
+  const telemetryWriter               = writer || new TelemetryWriter({ env, start: cwd });
+  let file                = null;
+  let resolverMessage                = null;
+  if (hasValue(recordPath)) {
+    file = path.resolve(cwd, recordPath);
+  } else {
+    let feature     ;
+    try {
+      feature = (resolve                   )({ projectRoot: cwd, slug: hasValue(slug) ? slug : null });
+    } catch (error     ) {
+      feature = { error: 'resolver-failed', message: error?.message || String(error) };
+    }
+    if (feature?.error || typeof feature?.featureFolder !== 'string' || !feature.featureFolder) {
+      resolverMessage = typeof feature?.message === 'string' && feature.message
+        ? feature.message
+        : (typeof feature?.error === 'string' && feature.error ? feature.error : 'feature could not be resolved');
+    } else {
+      file = path.resolve(feature.featureFolder, 'review', 'findings.json');
+    }
+  }
+
+  const errors           = [];
+  const errorDetails = new Map                ();
+  const ancestryAdvisories           = [];
+  const identityAdvisories           = [];
+  let sameFamily                    = 'warn';
+  let reviewPreset = 'auto';
+  let authors        = [];
+  let record                      = null;
+  if (file === null) {
+    errors.push('missing');
+    errorDetails.set('missing', resolverMessage || 'feature record could not be located');
+  } else {
+    let raw        ;
+    try {
+      raw = fs.readFileSync(file, 'utf8');
+    } catch (error     ) {
+      if (error?.code === 'ENOENT') errors.push('missing');
+      else errors.push('unreadable');
+      if (error?.message) errorDetails.set(errors[0], error.message);
+      raw = '';
+    }
+
+    if (errors.length === 0) {
+      // Settings are read only for a record that declares an author: nothing else depends on them (L-C3).
+      let peek      = null;
+      try { peek = JSON.parse(raw); } catch { /* validateFindings reports `json` */ }
+      if (peek !== null && typeof peek === 'object' && Object.hasOwn(peek, 'author')) {
+        const read = readSameFamily(loadSettings, cwd, env);
+        sameFamily = read.value;
+        if (read.unread) errors.push('same-family-setting-unread');
+      }
+      // A record that omits `protocol` is held to the effective `review.preset` (C-2 closure), so it is read for every record.
+      if (peek !== null && typeof peek === 'object') {
+        const read = readPreset(loadSettings, cwd, env);
+        reviewPreset = read.value;
+        if (read.unread) errors.push('review-preset-setting-unread');
+      }
+      authors = authoringIdentities({ slug: peek?.slug, cwd, env, record: peek, fsImpl: fs });
+      const validation = validateFindings(raw, { sameFamily, preset: reviewPreset, authors });
+      for (const error of validation.errors) errors.push(error); // a spread overflows the stack at ~200k errors (C-6)
+      if (!validation.errors.includes('json')) {
+        try { record = JSON.parse(raw); } catch { record = null; }
+      }
+      if (validation.ok && record) {
+        if (Object.hasOwn(record, 'author')) identityAdvisories.push(...crossCheckAuthor({ record, cwd, env }));
+        for (const finding of record.converged) {
+          if (typeof finding.preExistingAt !== 'string') continue;
+          let status                           ;
+          try {
+            status = (git             )(
+              ['merge-base', '--is-ancestor', finding.preExistingAt, record.reviewedHead],
+              path.dirname(file),
+              env,
+            )?.status;
+          } catch {
+            status = null;
+          }
+          if (status === 1) errors.push(`preExistingAt-not-ancestor:${finding.id}`);
+          else if (status !== 0) ancestryAdvisories.push(`ancestry-unchecked:${finding.id}`);
+        }
+      }
+    }
+  }
+
+  const advisories = (record && validateFindings(record, { sameFamily, preset: reviewPreset, authors }).ok
+    ? reviewAdvisories(record, { sameFamily, authors }).concat(identityAdvisories)
+    : []).concat(ancestryAdvisories).sort();
+  const valid = errors.length === 0;
+  const counts = valid && record ? countFindings(record) : null;
+  const result = { schema: 1, path: file, valid, errors, advisories, counts };
+
+  if (json) {
+    out(JSON.stringify(result));
+  } else {
+    out(`review check: ${valid ? 'valid' : 'invalid'} (${errors.length} errors, ${advisories.length} advisories)`);
+    for (const error of errors) {
+      const detail = errorDetails.get(error);
+      out(`error: ${error}${detail ? `: ${detail}` : ''}`);
+    }
+    for (const advisory of advisories) out(`advisory: ${advisory}`);
+    if (counts) out(Object.entries(counts).map(([key, value]) => `${key}=${value}`).join(' '));
+  }
+
+  // Only a validated slug is a feature slug; an invalid record's slug can hold anything (C-1, IC-004).
+  const task = valid && record && typeof record.slug === 'string' ? record.slug : null;
+  const telemetryRecord               = {
+    kind: 'review.run',
+    task,
+    depth: null,
+    risk: null,
+    protocol: null,
+    head: null,
+    ...Object.fromEntries(TELEMETRY_COUNT_KEYS.map((key) => [key, null])),
+    advisories: advisories.length,
+    errors: errors.length,
+  };
+  if (counts && record) Object.assign(telemetryRecord, counts, { depth: record.depth ?? null, risk: record.risk ?? null, protocol: telemetryProtocol(record.protocol?.id), head: record.reviewedHead });
+  try { telemetryWriter.write([telemetryRecord]); } catch { /* telemetry never changes the check result */ }
+
+  return finishRuntime(valid ? 0 : 1);
+}
+
+module.exports = { handleReviewCommand };
+

package/src/runtime/review/dominance.js

@@ -0,0 +1,68 @@
+'use strict';
+
+// 122 IC-014: `dominates(P, B, context)`, the strictness comparison between two protocol presets. Pure:
+// no filesystem, no throw. P dominates B when every field that makes a review or debate stricter is at
+// least as strict in P. `context` carries the ordered core tiers (models.json `dispatchTiers.tiers`,
+// loosest first) and the synthesizer lattice (protocols.json `synthesizerStrength`). An unknown tier or
+// synthesizer has no rank and never dominates: no `indexOf` of -1 is read as a rank.
+
+const FAMILY_STRICTNESS                         = { any: 0, 'different-from-author': 1 };
+
+const isObject = (value     )          => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** A rank from `ranks`, or null when `key` has none. */
+function rankOf(ranks                        , key     )                {
+  return typeof key === 'string' && Object.hasOwn(ranks, key) && Number.isInteger(ranks[key]) ? ranks[key] : null;
+}
+
+/** True when seat `p` covers seat `b`: a lens superset, a family at least as strict, a tier at least as high. */
+function seatCovers(p     , b     , tierRank                        )          {
+  if (!isObject(p) || !isObject(b) || !isObject(p.model) || !isObject(b.model)) return false;
+  const pLenses = new Set(Array.isArray(p.lenses) ? p.lenses : []);
+  if (!(Array.isArray(b.lenses) ? b.lenses : []).every((lens     ) => pLenses.has(lens))) return false;
+  const pFamily = rankOf(FAMILY_STRICTNESS, p.model.family ?? 'any');
+  const bFamily = rankOf(FAMILY_STRICTNESS, b.model.family ?? 'any');
+  if (pFamily === null || bFamily === null || pFamily < bFamily) return false;
+  const pTier = rankOf(tierRank, p.model.tier);
+  const bTier = rankOf(tierRank, b.model.tier);
+  return pTier !== null && bTier !== null && pTier >= bTier;
+}
+
+/**
+ * True when every B seat maps to a distinct P seat that covers it: a maximum bipartite matching by
+ * augmenting paths (Kuhn), so a first-fit choice never hides a matching that exists. Seats are few.
+ */
+function seatsMatch(pSeats       , bSeats       , tierRank                        )          {
+  if (bSeats.length > pSeats.length) return false;
+  const covers = bSeats.map((b) => pSeats.map((p) => seatCovers(p, b, tierRank)));
+  const owner           = new Array(pSeats.length).fill(-1); // P seat index -> B seat index
+  const augment = (bi        , seen           )          => {
+    for (let pi = 0; pi < pSeats.length; pi++) {
+      if (!covers[bi][pi] || seen[pi]) continue;
+      seen[pi] = true;
+      if (owner[pi] === -1 || augment(owner[pi], seen)) { owner[pi] = bi; return true; }
+    }
+    return false;
+  };
+  return bSeats.every((_, bi) => augment(bi, new Array(pSeats.length).fill(false)));
+}
+
+function dominates(P     , B     , context      = {})          {
+  if (!isObject(P) || !isObject(B) || !isObject(context)) return false;
+  const { tiers, synthesizerStrength } = context;
+  if (!Array.isArray(tiers) || !isObject(synthesizerStrength)) return false;
+  const tierRank                         = Object.fromEntries(tiers.map((tier        , i        ) => [tier, i]));
+
+  if (P.kind !== B.kind || P.decider !== B.decider) return false;
+  if (!Array.isArray(P.seats) || !Array.isArray(B.seats) || !seatsMatch(P.seats, B.seats, tierRank)) return false;
+  if (!isObject(P.rounds) || !isObject(B.rounds)) return false;
+  for (const field of ['default', 'min']) {
+    if (!Number.isInteger(P.rounds[field]) || !Number.isInteger(B.rounds[field]) || P.rounds[field] < B.rounds[field]) return false;
+  }
+  if (B.crossAnswer === true && P.crossAnswer !== true) return false;
+  const pSynth = rankOf(synthesizerStrength, P.synthesizer);
+  const bSynth = rankOf(synthesizerStrength, B.synthesizer);
+  return pSynth !== null && bSynth !== null && pSynth >= bSynth;
+}
+
+module.exports = { dominates };