project-knowledge 0.1.0

package/_site/lib/analysis-orchestrator.js

@@ -0,0 +1,433 @@
+// Analysis Orchestrator (TASK-007 + TASK-008)
+// Coordinates: build context pack → run selected AI adapter → validate output
+//              → write drafts and run metadata.
+//
+// Hard rules:
+//   * `project-goal.md` is never overwritten by an analysis pass.
+//     Drafts always land under `_ai/drafts/<run-id>/`.
+//   * `lastAnalyzedCommit` is NEVER updated by analysis. Only the apply step (TASK-009)
+//     advances that pointer.
+//   * Failed analysis produces a `failed` run record and does NOT write any drafts.
+
+const fs = require('fs');
+const path = require('path');
+const { getAdapter } = require('./ai-adapter');
+const { buildContextPack } = require('./context-pack-builder');
+const { execGit } = require('./git-runner');
+const { scanProject } = require('./scanner');
+
+function readTemplate(name) {
+  const p = path.join(__dirname, '..', '..', 'templates', name);
+  if (!fs.existsSync(p)) return null;
+  return fs.readFileSync(p, 'utf-8');
+}
+
+function renderTemplate(content, vars) {
+  return content.replace(/__([A-Z_][A-Z0-9_]*)__/g, (_, key) => (key in vars ? String(vars[key]) : `__${key}__`));
+}
+
+function todayIso() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function shortRunId(input) {
+  return input.toString().slice(0, 12).replace(/[^a-zA-Z0-9-]/g, '-');
+}
+
+function knowledgeLanguage(project) {
+  return project && project.knowledgeLanguage === 'en-US' ? 'en-US' : 'zh-CN';
+}
+
+function labels(project) {
+  if (knowledgeLanguage(project) === 'en-US') {
+    return {
+      aiProposal: 'AI Proposal (pending acceptance)',
+      oneSentenceGoal: 'One-Sentence Goal',
+      targetUsers: 'Target Users',
+      coreScenarios: 'Core Scenarios',
+      successCriteria: 'Success Criteria',
+      nonGoals: 'Non-Goals',
+      priorityPrinciples: 'Priority Principles',
+      prReviewPrinciples: 'PR Review Principles',
+      aiPurpose: 'AI-Inferred Purpose',
+      capabilities: 'Capabilities',
+      architecture: 'Architecture',
+      modules: 'Modules',
+      dataFlow: 'Data Flow',
+      goalSupport: 'Goal Support',
+      gaps: 'Gaps',
+      evidence: 'Evidence',
+      featureDraft: 'AI-generated feature draft (pending acceptance).',
+      summaryProposed: 'Summary (proposed)',
+      goalImpact: 'Goal Impact',
+      proposedOperations: 'Proposed Operations',
+      noEvidence: '(none reported)',
+    };
+  }
+  return {
+    aiProposal: 'AI 建议（待确认）',
+    oneSentenceGoal: '一句话目标',
+    targetUsers: '目标用户',
+    coreScenarios: '核心场景',
+    successCriteria: '成功标准',
+    nonGoals: '非目标',
+    priorityPrinciples: '优先级原则',
+    prReviewPrinciples: 'PR 审核原则',
+    aiPurpose: 'AI 推断的项目用途',
+    capabilities: '当前能力',
+    architecture: '当前架构',
+    modules: '重要模块',
+    dataFlow: '数据 / 控制流',
+    goalSupport: '对项目目标的支撑',
+    gaps: '差距',
+    evidence: '证据',
+    featureDraft: 'AI 生成的功能草稿（待确认）。',
+    summaryProposed: '摘要（建议）',
+    goalImpact: '项目目标影响',
+    proposedOperations: '建议操作',
+    noEvidence: '（未报告）',
+  };
+}
+
+function renderGoalDraft(project, draft) {
+  const tpl = readTemplate('project-goal.md');
+  if (!tpl) return null;
+  const l = labels(project);
+  const today = todayIso();
+  const vars = {
+    PROJECT: project.slug,
+    DATE: today,
+    AUTHOR: process.env.USERNAME || process.env.USER || 'unknown',
+  };
+  let rendered = renderTemplate(tpl, vars);
+  // Replace the body placeholders with the draft content. The template still has
+  // "TODO —" markers; we keep them in the draft and append the AI proposal below.
+  const proposal = [
+    '',
+    `## ${l.aiProposal}`,
+    '',
+    `- **${l.oneSentenceGoal}**: ${draft.oneSentenceGoal || 'TODO'}`,
+    `- **${l.targetUsers}**: ${(draft.targetUsers || []).join(', ') || 'TODO'}`,
+    `- **${l.coreScenarios}**: ${(draft.coreScenarios || []).map(s => `- ${s}`).join('\n') || '- TODO'}`,
+    `- **${l.successCriteria}**: ${(draft.successCriteria || []).map(s => `- ${s}`).join('\n') || '- TODO'}`,
+    `- **${l.nonGoals}**: ${(draft.nonGoals || []).map(s => `- ${s}`).join('\n') || '- TODO'}`,
+    `- **${l.priorityPrinciples}**: ${(draft.priorityPrinciples || []).map(s => `- ${s}`).join('\n') || '- TODO'}`,
+    `- **${l.prReviewPrinciples}**: ${(draft.prReviewPrinciples || []).map(s => `- ${s}`).join('\n') || '- TODO'}`,
+  ].join('\n');
+  return rendered.replace('## Human Revision History', proposal + '\n\n## Human Revision History');
+}
+
+function renderAnalysisDraft(project, draft) {
+  const tpl = readTemplate('project-analysis.md');
+  if (!tpl) return null;
+  const l = labels(project);
+  const vars = { PROJECT: project.slug, DATE: todayIso() };
+  let rendered = renderTemplate(tpl, vars);
+  const proposal = [
+    '',
+    `## ${l.aiProposal}`,
+    '',
+    `- **${l.aiPurpose}**: ${draft.purpose || 'TODO'}`,
+    `- **${l.capabilities}**: ${(draft.capabilities || []).map(s => `- ${s}`).join('\n') || '- TODO'}`,
+    `- **${l.architecture}**: ${draft.architecture || 'TODO'}`,
+    `- **${l.modules}**: ${(draft.modules || []).map(m => `- ${m.slug}: ${m.role}`).join('\n') || '- TODO'}`,
+    `- **${l.dataFlow}**: ${draft.dataFlow || 'TODO'}`,
+    `- **${l.goalSupport}**: ${draft.goalSupport || 'TODO'}`,
+    `- **${l.gaps}**: ${(draft.gaps || []).map(s => `- ${s}`).join('\n') || `- ${l.noEvidence}`}`,
+    `- **${l.evidence}**: ${(draft.evidence || []).map(s => `- ${s}`).join('\n') || `- ${l.noEvidence}`}`,
+  ].join('\n');
+  return rendered.replace('## Evidence List', proposal + '\n\n## Evidence List');
+}
+
+function renderFeatureDraft(project, feature) {
+  const tpl = readTemplate('feature.md');
+  if (!tpl) return null;
+  const l = labels(project);
+  const vars = { PROJECT: project.slug, SLUG: feature.slug, DATE: todayIso() };
+  let rendered = renderTemplate(tpl, vars);
+  const body = [
+    '',
+    `> ${l.featureDraft}`,
+    '',
+    `## ${l.summaryProposed}`,
+    feature.summary || 'TODO',
+    '',
+  ].join('\n');
+  return rendered.replace('## What the Feature Does', body + '\n## What the Feature Does\n' + (feature.summary || 'TODO'));
+}
+
+async function runInitialAnalysis(project, options = {}) {
+  const slug = project.slug;
+  const kbPath = path.resolve(project.kbPath);
+  const aiProfileId = project.aiProfileId || 'mock-agent';
+  const adapter = getAdapter(aiProfileId);
+  if (!adapter) return { ok: false, status: 400, error: `unknown adapter: ${aiProfileId}` };
+  if (!fs.existsSync(kbPath)) return { ok: false, status: 400, error: 'project KB not initialized' };
+
+  const runId = `initial-${shortRunId(Date.now().toString(36) + Math.random().toString(36))}`;
+  const draftsDir = path.join(kbPath, '_ai', 'drafts', runId);
+  const runsDir = path.join(kbPath, '_ai', 'runs');
+  fs.mkdirSync(draftsDir, { recursive: true });
+  fs.mkdirSync(runsDir, { recursive: true });
+
+  const runRecord = {
+    schema: 'ai-run/v1',
+    runId,
+    type: 'initial',
+    project: slug,
+    aiProfileId,
+    knowledgeLanguage: knowledgeLanguage(project),
+    status: 'running',
+    startedAt: new Date().toISOString(),
+    outputPaths: [],
+    drafts: [],
+    goalAccepted: false,
+    headCommitAtRun: project.headCommit || null,
+  };
+
+  try {
+    // 1. Build context pack (no commits needed for initial)
+    const pack = await buildContextPack({
+      project,
+      runId,
+      trigger: 'initial',
+      commits: [],
+    });
+    runRecord.contextPackPath = path.relative(kbPath, path.join(kbPath, '_ai', 'context-packs', runId, 'context-pack.json'));
+
+    // 2. Run analyzer
+    const output = await adapter.analyzeInitialProject({ project, contextPack: pack });
+
+    // 3. Validate output
+    const validation = adapter.validateOutput(output);
+    if (!validation.valid) {
+      runRecord.status = 'failed';
+      runRecord.finishedAt = new Date().toISOString();
+      runRecord.error = 'invalid adapter output';
+      runRecord.validationErrors = validation.errors;
+      writeRun(runsDir, runRecord);
+      return { ok: false, status: 422, error: 'invalid adapter output', validation, runId, runRecord };
+    }
+
+    // 4. Render drafts to disk
+    const goalText = renderGoalDraft(project, output.goalDraft || {});
+    const analysisText = renderAnalysisDraft(project, output.analysisDraft || {});
+    const featureTexts = (output.features || []).map(f => ({ slug: f.slug, text: renderFeatureDraft(project, f) }));
+
+    const goalPath = path.join(draftsDir, 'project-goal.md');
+    const analysisPath = path.join(draftsDir, 'project-analysis.md');
+    fs.writeFileSync(goalPath, goalText || '', 'utf-8');
+    fs.writeFileSync(analysisPath, analysisText || '', 'utf-8');
+    runRecord.drafts.push({ op: 'create-file', path: 'project-goal.md', fromDraft: 'goalDraft' });
+    runRecord.drafts.push({ op: 'create-file', path: 'project-analysis.md', fromDraft: 'analysisDraft' });
+
+    for (const f of featureTexts) {
+      const featurePath = path.join(draftsDir, 'features', `${f.slug}.md`);
+      fs.mkdirSync(path.dirname(featurePath), { recursive: true });
+      fs.writeFileSync(featurePath, f.text || '', 'utf-8');
+      runRecord.drafts.push({ op: 'create-file', path: `features/${f.slug}.md`, fromDraft: 'feature' });
+    }
+    runRecord.outputPaths = runRecord.drafts.map(d => d.path);
+
+    runRecord.status = 'succeeded';
+    runRecord.finishedAt = new Date().toISOString();
+    runRecord.evidenceCount = (output.analysisDraft && output.analysisDraft.evidence) ? output.analysisDraft.evidence.length : 0;
+    writeRun(runsDir, runRecord);
+    return { ok: true, runId, runRecord };
+  } catch (e) {
+    runRecord.status = 'failed';
+    runRecord.finishedAt = new Date().toISOString();
+    runRecord.error = e.message;
+    writeRun(runsDir, runRecord);
+    return { ok: false, status: 500, error: e.message, runId, runRecord };
+  }
+}
+
+function renderChangeDraft(project, change, commit) {
+  const tpl = readTemplate('change.md');
+  if (!tpl) return null;
+  const l = labels(project);
+  const vars = {
+    PROJECT: project.slug,
+    COMMIT: commit.hash,
+    SHORTCOMMIT: (commit.short || commit.hash || '').slice(0, 7),
+    DATE: commit.date || todayIso(),
+    AUTHOR: commit.author || 'unknown',
+    SUBJECT: commit.subject || '',
+    TYPE: (commit.subject || '').match(/^[a-z]+/i) ? RegExp.lastMatch.toLowerCase() : 'chore',
+    CLASSIFICATION: change.classification,
+  };
+  let rendered = renderTemplate(tpl, vars);
+  const proposal = [
+    '',
+    `## ${l.aiProposal}`,
+    '',
+    `- **${l.goalImpact}**: ${change.goalImpact || 'TODO'}`,
+    `- **${l.evidence}**: ${(change.evidence || []).map(s => `- ${s}`).join('\n') || `- ${l.noEvidence}`}`,
+    `- **${l.proposedOperations}**: ${(change.proposedOps || []).map(o => `- ${o.op} ${o.path}${o.fromTemplate ? ` (from ${o.fromTemplate})` : ''}`).join('\n') || `- ${l.noEvidence}`}`,
+  ].join('\n');
+  return rendered.replace('## Reviewer Notes', proposal + '\n\n## Reviewer Notes');
+}
+
+function featureSlugFromSubject(subject) {
+  const s = (subject || '').replace(/^[^:]+:\s*/, '').replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '').toLowerCase();
+  return s.slice(0, 50) || 'change';
+}
+
+async function runCommitAnalysis(project, options = {}) {
+  const slug = project.slug;
+  const kbPath = path.resolve(project.kbPath);
+  const aiProfileId = project.aiProfileId || 'mock-agent';
+  const adapter = getAdapter(aiProfileId);
+  if (!adapter) return { ok: false, status: 400, error: `unknown adapter: ${aiProfileId}` };
+  if (!fs.existsSync(kbPath)) return { ok: false, status: 400, error: 'project KB not initialized' };
+
+  // Run the scanner to discover pending commits since lastAnalyzedCommit.
+  const scan = await scanProject({ slug, ...project }, { maxCommits: options.maxCommits || 200 });
+  if (scan.repoStatus !== 'ok') {
+    return { ok: false, status: 400, error: `git not ok: ${scan.repoStatus} (${scan.error || ''})` };
+  }
+  if (!scan.commits || scan.commits.length === 0) {
+    return { ok: true, noop: true, message: 'no pending commits', runId: null, scan };
+  }
+
+  const runId = `commits-${shortRunId(Date.now().toString(36) + Math.random().toString(36))}`;
+  const draftsDir = path.join(kbPath, '_ai', 'drafts', runId);
+  const runsDir = path.join(kbPath, '_ai', 'runs');
+  fs.mkdirSync(draftsDir, { recursive: true });
+  fs.mkdirSync(runsDir, { recursive: true });
+
+  const runRecord = {
+    schema: 'ai-run/v1',
+    runId,
+    type: 'commits',
+    project: slug,
+    aiProfileId,
+    knowledgeLanguage: knowledgeLanguage(project),
+    status: 'running',
+    startedAt: new Date().toISOString(),
+    mode: scan.mode,
+    range: scan.range,
+    commitCount: scan.commits.length,
+    headCommitAtRun: scan.headCommit || null,
+    lastAnalyzedCommitBefore: project.lastAnalyzedCommit || null,
+    drafts: [],
+    outputPaths: [],
+  };
+
+  try {
+    // 1. Build a commit-aware context pack
+    const pack = await buildContextPack({
+      project,
+      runId,
+      trigger: 'commits',
+      commits: scan.commits,
+    });
+    runRecord.contextPackPath = path.relative(kbPath, path.join(kbPath, '_ai', 'context-packs', runId, 'context-pack.json'));
+
+    // 2. Run analyzer
+    const output = await adapter.analyzeCommitBatch({ project, commits: scan.commits, contextPack: pack });
+
+    // 3. Validate
+    const validation = adapter.validateOutput(output);
+    if (!validation.valid) {
+      runRecord.status = 'failed';
+      runRecord.finishedAt = new Date().toISOString();
+      runRecord.error = 'invalid adapter output';
+      runRecord.validationErrors = validation.errors;
+      writeRun(runsDir, runRecord);
+      return { ok: false, status: 422, error: 'invalid adapter output', validation, runId, runRecord };
+    }
+
+    // 4. Render drafts
+    const changes = output.changes || [];
+    const changesByCommit = new Map(changes.map(c => [c.commit, c]));
+    let touchedGoal = false;
+
+    for (const commit of scan.commits) {
+      const change = changesByCommit.get(commit.hash);
+      if (!change) continue;
+      const shortCommit = (commit.short || commit.hash || '').slice(0, 7);
+      const draftChangePath = path.join(draftsDir, 'changes', `${shortCommit}.md`);
+      fs.mkdirSync(path.dirname(draftChangePath), { recursive: true });
+      fs.writeFileSync(draftChangePath, renderChangeDraft(project, change, commit), 'utf-8');
+      runRecord.drafts.push({ op: 'create-file', path: `changes/${shortCommit}.md`, fromDraft: 'change' });
+      runRecord.outputPaths.push(`changes/${shortCommit}.md`);
+
+      if (change.classification === 'new-feature') {
+        const featureSlug = featureSlugFromSubject(commit.subject);
+        const featurePath = path.join(draftsDir, 'features', `${featureSlug}.md`);
+        fs.mkdirSync(path.dirname(featurePath), { recursive: true });
+        const featureText = renderFeatureDraft(project, {
+          slug: featureSlug,
+          summary: knowledgeLanguage(project) === 'zh-CN'
+            ? `${shortCommit} 引入的新功能：${commit.subject}`
+            : `New feature introduced by ${shortCommit}: ${commit.subject}`,
+        });
+        fs.writeFileSync(featurePath, featureText, 'utf-8');
+        runRecord.drafts.push({ op: 'create-file', path: `features/${featureSlug}.md`, fromDraft: 'feature' });
+        runRecord.outputPaths.push(`features/${featureSlug}.md`);
+      } else if (change.classification === 'refactor' || change.classification === 'infrastructure') {
+        // Note a goal-impact line so the reviewer can see this changed the implementation shape.
+        touchedGoal = touchedGoal || (change.goalImpact && change.goalImpact.length > 0);
+      }
+    }
+
+    runRecord.touchedGoal = touchedGoal;
+    runRecord.status = 'succeeded';
+    runRecord.finishedAt = new Date().toISOString();
+    runRecord.evidenceTotal = changes.reduce((acc, c) => acc + (c.evidence ? c.evidence.length : 0), 0);
+    writeRun(runsDir, runRecord);
+
+    return { ok: true, runId, runRecord, scan };
+  } catch (e) {
+    runRecord.status = 'failed';
+    runRecord.finishedAt = new Date().toISOString();
+    runRecord.error = e.message;
+    writeRun(runsDir, runRecord);
+    return { ok: false, status: 500, error: e.message, runId, runRecord };
+  }
+}
+
+function writeRun(runsDir, runRecord) {
+  const p = path.join(runsDir, `${runRecord.runId}.json`);
+  fs.writeFileSync(p, JSON.stringify(runRecord, null, 2), 'utf-8');
+  return p;
+}
+
+function readRun(kbPath, runId) {
+  const p = path.join(kbPath, '_ai', 'runs', `${runId}.json`);
+  if (!fs.existsSync(p)) return null;
+  return JSON.parse(fs.readFileSync(p, 'utf-8'));
+}
+
+function listRuns(kbPath) {
+  const runsDir = path.join(kbPath, '_ai', 'runs');
+  if (!fs.existsSync(runsDir)) return [];
+  return fs.readdirSync(runsDir).filter(f => f.endsWith('.json')).map(f => {
+    try { return JSON.parse(fs.readFileSync(path.join(runsDir, f), 'utf-8')); } catch { return null; }
+  }).filter(Boolean);
+}
+
+function listDrafts(kbPath, runId) {
+  const dir = path.join(kbPath, '_ai', 'drafts', runId);
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) walk(full);
+      else out.push({ path: path.relative(dir, full).replace(/\\/g, '/'), size: fs.statSync(full).size });
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+module.exports = {
+  runInitialAnalysis,
+  runCommitAnalysis,
+  readRun,
+  listRuns,
+  listDrafts,
+};