@chenguangyao/devflow-kit 0.1.43

package/src/core/workflow-verify.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const DEFAULT_REQUIRED_BY_LEVEL = {
+  L0: ['unit-test.md'],
+  L1: ['unit-test.md', 'smoke-test.md'],
+  L2: ['unit-test.md', 'integration-test.md', 'smoke-test.md', 'self-test.md'],
+  L3: ['unit-test.md', 'integration-test.md', 'e2e-test.md', 'smoke-test.md', 'self-test.md'],
+};
+
+const REPORT_ALIASES = {
+  unit: 'unit-test.md',
+  'unit-test': 'unit-test.md',
+  integration: 'integration-test.md',
+  'integration-test': 'integration-test.md',
+  e2e: 'e2e-test.md',
+  'e2e-test': 'e2e-test.md',
+  smoke: 'smoke-test.md',
+  'smoke-test': 'smoke-test.md',
+  self: 'self-test.md',
+  'self-test': 'self-test.md',
+  self_test: 'self-test.md',
+  regression: 'regression-test.md',
+  'regression-test': 'regression-test.md',
+  perf: 'perf-test.md',
+  'perf-test': 'perf-test.md',
+  contract: 'contract-test.md',
+  'contract-test': 'contract-test.md',
+  joint: 'joint-test.md',
+  'joint-test': 'joint-test.md',
+};
+
+function normalizeReportList(input) {
+  const parts = Array.isArray(input)
+    ? input
+    : String(input || '').split(',');
+  const out = [];
+  const seen = new Set();
+  for (const raw of parts) {
+    const normalized = normalizeReportName(raw);
+    if (!seen.has(normalized)) {
+      out.push(normalized);
+      seen.add(normalized);
+    }
+  }
+  if (!out.length) throw new Error('at least one verify report is required');
+  return out;
+}
+
+function normalizeReportName(raw) {
+  const value = String(raw || '').trim();
+  if (!value) throw new Error('empty verify report name');
+  const key = value.replace(/^reports\//, '').replace(/^test-report\.md#/, '').toLowerCase();
+  if (REPORT_ALIASES[key]) return REPORT_ALIASES[key];
+  if (/^[a-z0-9][a-z0-9-]*\.md$/.test(key)) return key;
+  throw new Error(`unknown verify report: ${value}`);
+}
+
+function defaultRequiredReports(level) {
+  return (DEFAULT_REQUIRED_BY_LEVEL[level] || DEFAULT_REQUIRED_BY_LEVEL.L2).slice();
+}
+
+function requiredReportsForState(st) {
+  const override = st && st.workflow && st.workflow.verify && st.workflow.verify.requiredReports;
+  if (Array.isArray(override) && override.length) return normalizeReportList(override);
+  return defaultRequiredReports(st && st.level);
+}
+
+function missingDefaultReports(level, reports) {
+  const selected = new Set(normalizeReportList(reports));
+  return defaultRequiredReports(level).filter((name) => !selected.has(name));
+}
+
+function reportKindFromName(name) {
+  const normalized = normalizeReportName(name);
+  if (normalized === 'self-test.md') return 'self-test';
+  return normalized.replace(/-test\.md$/, '').replace(/\.md$/, '');
+}
+
+module.exports = {
+  DEFAULT_REQUIRED_BY_LEVEL,
+  REPORT_ALIASES,
+  normalizeReportList,
+  normalizeReportName,
+  defaultRequiredReports,
+  requiredReportsForState,
+  missingDefaultReports,
+  reportKindFromName,
+};

package/src/core/workflow.js

@@ -0,0 +1,433 @@
+'use strict';
+
+const fsSync = require('fs');
+const path = require('path');
+
+const PROTECTED_GATES = ['review', 'verify', 'deliver'];
+
+const BUILTIN_RECIPES = {
+  micro: {
+    label: '极简改动',
+    steps: [
+      { id: 'plan', skill: 'plan' },
+      { id: 'apply', skill: 'apply' },
+      gate('review', 'code-review'),
+      gate('verify', 'verify'),
+      gate('deliver', 'deliver'),
+    ],
+  },
+  standard: {
+    label: '标准研发',
+    steps: [
+      { id: 'requirement', skill: 'requirement-analysis' },
+      { id: 'design', skill: 'tech-spec' },
+      { id: 'plan', skill: 'plan' },
+      { id: 'apply', skill: 'apply' },
+      gate('review', 'code-review'),
+      gate('verify', 'verify'),
+      gate('deliver', 'deliver'),
+      { id: 'archive', skill: 'archive', optional: true },
+    ],
+  },
+  'dependency-upgrade': {
+    label: '依赖升级',
+    steps: [
+      { id: 'dependency-upgrade', skill: 'dependency-upgrade' },
+      { id: 'plan', skill: 'plan' },
+      { id: 'apply', skill: 'apply' },
+      gate('review', 'code-review'),
+      gate('verify', 'verify'),
+      gate('deliver', 'deliver'),
+    ],
+  },
+  'ci-fix': {
+    label: 'CI 修复',
+    steps: [
+      { id: 'ci-fix', skill: 'ci-fix' },
+      { id: 'apply', skill: 'apply' },
+      gate('review', 'code-review'),
+      gate('verify', 'verify'),
+      gate('deliver', 'deliver'),
+    ],
+  },
+  'frontend-quality': {
+    label: '前端改动',
+    extends: 'standard',
+    insertAfter: {
+      apply: [{ id: 'frontend-quality', skill: 'frontend-quality', optional: true }],
+    },
+  },
+  'security-hardening': {
+    label: '安全敏感改动',
+    extends: 'standard',
+    insertAfter: {
+      apply: [{ id: 'security-hardening', skill: 'security-hardening', optional: true }],
+    },
+  },
+  refactor: {
+    label: '技术重构',
+    steps: [
+      { id: 'requirement', skill: 'requirement-analysis', optional: true },
+      { id: 'design', skill: 'tech-spec' },
+      { id: 'plan', skill: 'plan' },
+      { id: 'apply', skill: 'apply' },
+      gate('review', 'code-review'),
+      gate('verify', 'verify'),
+      gate('deliver', 'deliver'),
+    ],
+  },
+};
+
+function gate(id, skill) {
+  return { id, skill, required: true, protected: true };
+}
+
+function recommendRecipe(state, cfg = {}) {
+  if (state.mode === 'micro' || state.level === 'L0') {
+    return { id: 'micro', reason: 'change is L0/micro' };
+  }
+  const risks = new Set((state.riskSignals || []).filter((r) => (r.status || 'open') === 'open').map((r) => r.type));
+  if (risks.has('dependency_change')) return { id: 'dependency-upgrade', reason: 'open dependency_change risk signal' };
+  if (risks.has('ci_failure')) return { id: 'ci-fix', reason: 'open ci_failure risk signal' };
+  if (risks.has('frontend_change')) return { id: 'frontend-quality', reason: 'open frontend_change risk signal' };
+  if (risks.has('security_sensitive')) return { id: 'security-hardening', reason: 'open security_sensitive risk signal' };
+  const configured = cfg.defaults && cfg.defaults.workflow;
+  if (configured) return { id: configured, reason: 'project default workflow' };
+  return { id: 'standard', reason: 'default workflow' };
+}
+
+function expandRecipe(id, cfg = {}) {
+  const recipes = (cfg.workflows && cfg.workflows.recipes) || {};
+  const recipe = recipes[id] || BUILTIN_RECIPES[id];
+  if (!recipe) throw new Error(`unknown workflow recipe: ${id}`);
+
+  const source = recipes[id] ? 'project' : 'builtin';
+  let steps;
+  if (recipe.steps) {
+    steps = clone(recipe.steps).map((s) => normalizeStep(s, source));
+  } else if (recipe.extends) {
+    steps = expandRecipe(recipe.extends, cfg).steps.map((s) => ({ ...s }));
+  } else {
+    throw new Error(`workflow recipe has no steps or extends: ${id}`);
+  }
+
+  steps = applyOverrides(steps, recipe, source);
+  validateSteps(steps, { recipeId: id });
+  return {
+    id,
+    label: recipe.label || id,
+    description: recipe.description || '',
+    source,
+    steps,
+  };
+}
+
+function applyOverrides(steps, recipe, source) {
+  let out = steps.slice();
+  if (recipe.replaceStep) {
+    for (const [id, replacement] of Object.entries(recipe.replaceStep)) {
+      const idx = findStepIndex(out, id);
+      out[idx] = normalizeStep({ ...replacement, id: replacement.id || id }, source);
+    }
+  }
+  if (recipe.disableStep) {
+    for (const id of asList(recipe.disableStep)) {
+      const idx = findStepIndex(out, id);
+      if (isProtected(out[idx])) throw new Error(`cannot disable protected workflow gate: ${id}`);
+      out[idx] = { ...out[idx], status: 'disabled' };
+    }
+  }
+  out = insertAll(out, recipe.insertBefore, source, 'before');
+  out = insertAll(out, recipe.insertAfter, source, 'after');
+  return out;
+}
+
+function insertAll(steps, spec, source, mode) {
+  let out = steps.slice();
+  for (const [anchor, inserts] of Object.entries(spec || {})) {
+    let anchorIdx = findStepIndex(out, anchor);
+    const normalized = asList(inserts).map((s) => normalizeStep(s, source));
+    const at = mode === 'before' ? anchorIdx : anchorIdx + 1;
+    out.splice(at, 0, ...normalized);
+  }
+  return out;
+}
+
+function validateSteps(steps, { recipeId = 'workflow' } = {}) {
+  const seen = new Set();
+  for (const step of steps) {
+    if (!step.id) throw new Error(`${recipeId}: workflow step id is required`);
+    if (seen.has(step.id)) throw new Error(`${recipeId}: duplicate workflow step id: ${step.id}`);
+    seen.add(step.id);
+  }
+  for (const gateId of PROTECTED_GATES) {
+    const step = steps.find((s) => s.id === gateId);
+    if (!step) throw new Error(`${recipeId}: missing protected workflow gate: ${gateId}`);
+    if (!isProtected(step)) throw new Error(`${recipeId}: protected workflow gate must be required: ${gateId}`);
+  }
+  const order = steps.map((s) => s.id);
+  if (order.indexOf('review') > order.indexOf('verify')) throw new Error(`${recipeId}: verify must stay after review`);
+  if (order.indexOf('verify') > order.indexOf('deliver')) throw new Error(`${recipeId}: deliver must stay after verify`);
+  return true;
+}
+
+function createDraft({ recipe, state, reason = '' }) {
+  const now = new Date().toISOString();
+  return {
+    status: 'draft',
+    baseRecipe: {
+      id: recipe.id,
+      label: recipe.label,
+      source: recipe.source,
+      reason,
+    },
+    overrides: [],
+    baseSteps: clone(recipe.steps),
+    steps: clone(recipe.steps),
+    currentStep: firstRunnableStep(recipe.steps),
+    audit: [{ ts: now, event: 'draft.create', recipe: recipe.id, reason }],
+    draftedAt: now,
+  };
+}
+
+function addStep(workflow, { skill, id, after, before }) {
+  ensureWorkflow(workflow);
+  if (!skill) throw new Error('skill is required');
+  const step = normalizeStep({ id: id || skill, skill, optional: true, source: 'change' }, 'change');
+  if (workflow.steps.some((s) => s.id === step.id)) throw new Error(`workflow step already exists: ${step.id}`);
+  const anchor = after || before;
+  if (!anchor) throw new Error('add-step requires --after=<step> or --before=<step>');
+  const idx = findStepIndex(workflow.steps, anchor);
+  const at = before ? idx : idx + 1;
+  workflow.steps.splice(at, 0, step);
+  pushOverride(workflow, { type: 'add-step', step: step.id, skill, after: after || null, before: before || null });
+  audit(workflow, 'step.add', { step: step.id, skill, after: after || null, before: before || null });
+  return step;
+}
+
+function disableStep(workflow, { stepId, reason, allowRequired = false }) {
+  ensureWorkflow(workflow);
+  const step = findStep(workflow.steps, stepId);
+  if ((isProtected(step) || step.required) && !allowRequired) {
+    const e = new Error(`cannot disable required workflow step without checkpoint: ${stepId}`);
+    e.code = 'WORKFLOW_POLICY';
+    throw e;
+  }
+  if (!reason) throw new Error('disable-step requires --reason="..."');
+  step.status = 'disabled';
+  step.disabledReason = reason;
+  pushOverride(workflow, { type: 'disable-step', step: stepId, reason });
+  audit(workflow, 'step.disable', { step: stepId, reason });
+  return step;
+}
+
+function moveStep(workflow, { stepId, after, before }) {
+  ensureWorkflow(workflow);
+  const anchor = after || before;
+  if (!anchor) throw new Error('move-step requires --after=<step> or --before=<step>');
+  const step = findStep(workflow.steps, stepId);
+  if (isProtected(step)) {
+    const reviewIdx = findStepIndex(workflow.steps, 'review');
+    const anchorIdx = findStepIndex(workflow.steps, anchor);
+    const targetIdx = before ? anchorIdx : anchorIdx + 1;
+    if (step.id !== 'review' && targetIdx <= reviewIdx) {
+      const e = new Error(`cannot move protected workflow gate before review: ${stepId}`);
+      e.code = 'WORKFLOW_POLICY';
+      throw e;
+    }
+  }
+  const from = findStepIndex(workflow.steps, stepId);
+  const [removed] = workflow.steps.splice(from, 1);
+  let anchorIdx = findStepIndex(workflow.steps, anchor);
+  const at = before ? anchorIdx : anchorIdx + 1;
+  workflow.steps.splice(at, 0, removed);
+  validateSteps(workflow.steps, { recipeId: 'change workflow' });
+  pushOverride(workflow, { type: 'move-step', step: stepId, after: after || null, before: before || null });
+  audit(workflow, 'step.move', { step: stepId, after: after || null, before: before || null });
+  return removed;
+}
+
+function setVerifyReports(workflow, { requiredReports, reason }) {
+  ensureWorkflow(workflow);
+  workflow.verify = workflow.verify || {};
+  workflow.verify.requiredReports = requiredReports.slice();
+  if (reason) workflow.verify.reason = reason;
+  pushOverride(workflow, { type: 'set-verify', requiredReports: requiredReports.slice(), reason: reason || null });
+  audit(workflow, 'verify.set-reports', { requiredReports: requiredReports.slice(), reason: reason || null });
+  return workflow.verify;
+}
+
+function confirmWorkflow(workflow) {
+  ensureWorkflow(workflow);
+  workflow.status = 'confirmed';
+  workflow.confirmedAt = new Date().toISOString();
+  workflow.currentStep = firstRunnableStep(workflow.steps);
+  audit(workflow, 'workflow.confirm', { currentStep: workflow.currentStep });
+  return workflow;
+}
+
+function assertStepAllowed(workflow, stepId) {
+  if (!workflow) return true;
+  ensureWorkflow(workflow);
+  if (workflow.status !== 'confirmed') {
+    const e = new Error('workflow draft is not confirmed');
+    e.code = 'WORKFLOW_NOT_CONFIRMED';
+    e.currentStep = workflow.currentStep || firstRunnableStep(workflow.steps);
+    throw e;
+  }
+  const current = currentRunnableStep(workflow);
+  if (!current) return true;
+  if (current.id !== stepId) {
+    const e = new Error(`workflow current step is ${current.id}, not ${stepId}`);
+    e.code = 'WORKFLOW_STEP_BLOCKED';
+    e.currentStep = current.id;
+    e.requestedStep = stepId;
+    throw e;
+  }
+  return true;
+}
+
+function completeStep(workflow, stepId) {
+  if (!workflow || workflow.status !== 'confirmed') return false;
+  ensureWorkflow(workflow);
+  const idx = findStepIndex(workflow.steps, stepId);
+  const step = workflow.steps[idx];
+  if (step.status === 'disabled') return false;
+  step.status = 'completed';
+  step.completedAt = new Date().toISOString();
+  const next = nextRunnableStep(workflow.steps, idx + 1);
+  workflow.currentStep = next ? next.id : null;
+  audit(workflow, 'step.complete', { step: stepId, nextStep: workflow.currentStep });
+  return true;
+}
+
+function diffWorkflow(workflow) {
+  ensureWorkflow(workflow);
+  const base = new Set((workflow.baseSteps || []).map((s) => s.id));
+  const added = [];
+  const disabled = [];
+  const moved = [];
+  for (const step of workflow.steps || []) {
+    if (!base.has(step.id)) added.push(step.id);
+    if (step.status === 'disabled') disabled.push(step.id);
+  }
+  for (const item of workflow.overrides || []) {
+    if (item.type === 'move-step' && !moved.includes(item.step)) {
+      moved.push(item.step);
+    }
+  }
+  const verifyReports = workflow.verify && Array.isArray(workflow.verify.requiredReports)
+    ? workflow.verify.requiredReports.slice()
+    : [];
+  return { added, disabled, moved, verifyReports };
+}
+
+function installedSkillExists(root, skill) {
+  if (BUILTIN_STEP_SKILLS.has(skill)) return true;
+  return fsSync.existsSync(path.join(root, 'skills', skill, 'SKILL.md'))
+    || fsSync.existsSync(path.join(__dirname, '..', '..', 'skills', skill, 'SKILL.md'));
+}
+
+const BUILTIN_STEP_SKILLS = new Set([
+  'apply',
+  'archive',
+  'code-review',
+  'deliver',
+  'plan',
+  'requirement-analysis',
+  'review',
+  'tech-spec',
+  'verify',
+]);
+
+function normalizeStep(input, source) {
+  const id = input.id || input.skill;
+  return {
+    id,
+    skill: input.skill || id,
+    label: input.label || id,
+    required: input.required === true || PROTECTED_GATES.includes(id),
+    optional: input.optional === true,
+    protected: input.protected === true || PROTECTED_GATES.includes(id),
+    source: input.source || source,
+    status: input.status || 'pending',
+  };
+}
+
+function firstRunnableStep(steps) {
+  const step = (steps || []).find((s) => s.status !== 'disabled');
+  return step ? step.id : null;
+}
+
+function currentRunnableStep(workflow) {
+  const steps = workflow.steps || [];
+  const current = workflow.currentStep ? steps.find((s) => s.id === workflow.currentStep) : null;
+  if (current && current.status !== 'disabled' && current.status !== 'completed') return current;
+  const start = current ? steps.indexOf(current) + 1 : 0;
+  return nextRunnableStep(steps, start);
+}
+
+function nextRunnableStep(steps, start = 0) {
+  for (let i = start; i < (steps || []).length; i += 1) {
+    const step = steps[i];
+    if (step.status !== 'disabled' && step.status !== 'completed') return step;
+  }
+  return null;
+}
+
+function isProtected(step) {
+  return !!(step && (step.protected || PROTECTED_GATES.includes(step.id)));
+}
+
+function ensureWorkflow(workflow) {
+  if (!workflow || !Array.isArray(workflow.steps)) throw new Error('workflow draft not found. run devflow flow draft first.');
+}
+
+function findStep(steps, id) {
+  const step = steps.find((s) => s.id === id);
+  if (!step) throw new Error(`workflow step not found: ${id}`);
+  return step;
+}
+
+function findStepIndex(steps, id) {
+  const idx = steps.findIndex((s) => s.id === id);
+  if (idx === -1) throw new Error(`workflow step not found: ${id}`);
+  return idx;
+}
+
+function pushOverride(workflow, entry) {
+  workflow.overrides = workflow.overrides || [];
+  workflow.overrides.push({ ts: new Date().toISOString(), ...entry });
+}
+
+function audit(workflow, event, extra) {
+  workflow.audit = workflow.audit || [];
+  workflow.audit.push({ ts: new Date().toISOString(), event, ...(extra || {}) });
+}
+
+function asList(value) {
+  if (!value) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+module.exports = {
+  PROTECTED_GATES,
+  BUILTIN_RECIPES,
+  recommendRecipe,
+  expandRecipe,
+  validateSteps,
+  createDraft,
+  addStep,
+  disableStep,
+  moveStep,
+  setVerifyReports,
+  confirmWorkflow,
+  assertStepAllowed,
+  completeStep,
+  diffWorkflow,
+  installedSkillExists,
+};