popeye-cli 1.10.0 → 2.1.0

package/src/pipeline/artifact-manager.ts

@@ -0,0 +1,339 @@
+/**
+ * Artifact Manager — manages immutable versioned artifacts under /docs/.
+ * Supports both Markdown and JSON content types (P0-C).
+ * Implements version chains via group_id + previous_id (P1-2).
+ */
+
+import { randomUUID } from 'node:crypto';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import type {
+  ArtifactType,
+  ArtifactEntry,
+  ArtifactRef,
+  ContentType,
+  PipelinePhase,
+} from './types.js';
+
+// ─── Constants ───────────────────────────────────────────
+
+/** Directory mappings: artifact type -> subdirectory under /docs/ */
+const ARTIFACT_DIRS: Record<string, string> = {
+  master_plan: 'master-plan',
+  architecture: 'architecture',
+  role_plan: 'role-plans',
+  consensus: 'consensus',
+  arbitration: 'arbitration',
+  audit_report: 'audit',
+  rca_report: 'incidents',
+  production_readiness: 'production',
+  release_notes: 'release',
+  deployment: 'release',
+  rollback: 'release',
+  repo_snapshot: 'snapshots',
+  build_check: 'checks',
+  test_check: 'checks',
+  lint_check: 'checks',
+  typecheck_check: 'checks',
+  placeholder_scan: 'checks',
+  qa_validation: 'role-plans',
+  review_decision: 'consensus',
+  stuck_report: 'incidents',
+  journalist_trace: 'journal',
+  resolved_commands: 'checks',
+  constitution: 'governance',
+  change_request: 'governance',
+};
+
+/** All required subdirectories under /docs/ */
+const DOCS_SUBDIRS = [
+  'master-plan',
+  'architecture',
+  'role-plans',
+  'consensus',
+  'arbitration',
+  'audit',
+  'incidents',
+  'production',
+  'release',
+  'snapshots',
+  'checks',
+  'journal',
+  'governance',
+];
+
+// ─── Helper Functions ────────────────────────────────────
+
+function computeSha256(content: string): string {
+  return createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+
+function shortId(): string {
+  return randomUUID().split('-')[0];
+}
+
+function formatDate(): string {
+  return new Date().toISOString().split('T')[0];
+}
+
+function getExtension(contentType: ContentType): string {
+  return contentType === 'json' ? '.json' : '.md';
+}
+
+// ─── Artifact Manager ────────────────────────────────────
+
+export interface ArtifactManagerOptions {
+  projectDir: string;
+}
+
+export class ArtifactManager {
+  private readonly projectDir: string;
+  private readonly docsDir: string;
+
+  constructor(options: ArtifactManagerOptions) {
+    this.projectDir = options.projectDir;
+    this.docsDir = join(options.projectDir, 'docs');
+  }
+
+  /** Ensure all /docs/ subdirectories exist */
+  ensureDocsStructure(): void {
+    if (!existsSync(this.docsDir)) {
+      mkdirSync(this.docsDir, { recursive: true });
+    }
+    for (const subdir of DOCS_SUBDIRS) {
+      const dirPath = join(this.docsDir, subdir);
+      if (!existsSync(dirPath)) {
+        mkdirSync(dirPath, { recursive: true });
+      }
+    }
+  }
+
+  /** Create an artifact from Markdown content */
+  createArtifactText(
+    type: ArtifactType,
+    markdown: string,
+    phase: PipelinePhase,
+    groupId?: string,
+  ): ArtifactEntry {
+    return this.createArtifact(type, markdown, phase, 'markdown', groupId);
+  }
+
+  /** Create an artifact from a JSON-serializable object */
+  createArtifactJson(
+    type: ArtifactType,
+    jsonObject: unknown,
+    phase: PipelinePhase,
+    groupId?: string,
+  ): ArtifactEntry {
+    const content = JSON.stringify(jsonObject, null, 2);
+    return this.createArtifact(type, content, phase, 'json', groupId);
+  }
+
+  /** Core artifact creation logic */
+  private createArtifact(
+    type: ArtifactType,
+    content: string,
+    phase: PipelinePhase,
+    contentType: ContentType,
+    groupId?: string,
+  ): ArtifactEntry {
+    this.ensureDocsStructure();
+
+    const resolvedGroupId = groupId ?? randomUUID();
+    const existingArtifacts = this.listArtifacts(type);
+    const version = this.getNextVersion(resolvedGroupId, existingArtifacts);
+    const previousEntry = this.getLatestInGroup(resolvedGroupId, existingArtifacts);
+
+    const id = randomUUID();
+    const date = formatDate();
+    const sid = shortId();
+    const ext = getExtension(contentType);
+    const filename = `${type}_${sid}_v${version}_${date}${ext}`;
+
+    const subdir = ARTIFACT_DIRS[type] ?? 'misc';
+    const dirPath = join(this.docsDir, subdir);
+    if (!existsSync(dirPath)) {
+      mkdirSync(dirPath, { recursive: true });
+    }
+
+    const filePath = join(dirPath, filename);
+    const sha256 = computeSha256(content);
+
+    writeFileSync(filePath, content, 'utf-8');
+
+    const relativePath = relative(this.projectDir, filePath);
+
+    const entry: ArtifactEntry = {
+      id,
+      type,
+      phase,
+      version,
+      path: relativePath,
+      sha256,
+      timestamp: new Date().toISOString(),
+      immutable: true,
+      content_type: contentType,
+      group_id: resolvedGroupId,
+      previous_id: previousEntry?.id,
+    };
+
+    return entry;
+  }
+
+  /** Get the file path for a given artifact type and naming components */
+  getArtifactPath(
+    type: ArtifactType,
+    sid: string,
+    version: number,
+    date: string,
+    contentType: ContentType,
+  ): string {
+    const ext = getExtension(contentType);
+    const subdir = ARTIFACT_DIRS[type] ?? 'misc';
+    return join(this.docsDir, subdir, `${type}_${sid}_v${version}_${date}${ext}`);
+  }
+
+  /** List all artifacts, optionally filtered by type */
+  listArtifacts(type?: ArtifactType): ArtifactEntry[] {
+    // Scan for artifact JSON metadata files in a .artifacts/ dir
+    const metaDir = join(this.docsDir, '.artifacts');
+    if (!existsSync(metaDir)) {
+      return [];
+    }
+
+    const entries: ArtifactEntry[] = [];
+    const files = readdirSync(metaDir).filter((f) => f.endsWith('.json'));
+
+    for (const file of files) {
+      try {
+        const raw = readFileSync(join(metaDir, file), 'utf-8');
+        const parsed = JSON.parse(raw) as ArtifactEntry;
+        if (!type || parsed.type === type) {
+          entries.push(parsed);
+        }
+      } catch {
+        // Skip malformed metadata files
+      }
+    }
+
+    return entries.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+  }
+
+  /** Verify an artifact's SHA-256 matches its stored content */
+  verifyArtifact(entry: ArtifactEntry): boolean {
+    const fullPath = join(this.projectDir, entry.path);
+    if (!existsSync(fullPath)) {
+      return false;
+    }
+
+    const content = readFileSync(fullPath, 'utf-8');
+    const currentHash = computeSha256(content);
+    return currentHash === entry.sha256;
+  }
+
+  /** Get the latest artifact of a given type */
+  getLatestArtifact(type: ArtifactType): ArtifactEntry | null {
+    const all = this.listArtifacts(type);
+    if (all.length === 0) return null;
+    return all[all.length - 1];
+  }
+
+  /** Get next version number for a group across existing artifacts */
+  getNextVersion(groupId: string, existingArtifacts: ArtifactEntry[]): number {
+    const groupArtifacts = existingArtifacts.filter((a) => a.group_id === groupId);
+    if (groupArtifacts.length === 0) return 1;
+    const maxVersion = Math.max(...groupArtifacts.map((a) => a.version));
+    return maxVersion + 1;
+  }
+
+  /** Convert an ArtifactEntry to an ArtifactRef */
+  toArtifactRef(entry: ArtifactEntry): ArtifactRef {
+    return {
+      artifact_id: entry.id,
+      path: entry.path,
+      sha256: entry.sha256,
+      version: entry.version,
+      type: entry.type,
+    };
+  }
+
+  /** Store artifact metadata for later retrieval */
+  storeArtifactMetadata(entry: ArtifactEntry): void {
+    const metaDir = join(this.docsDir, '.artifacts');
+    if (!existsSync(metaDir)) {
+      mkdirSync(metaDir, { recursive: true });
+    }
+
+    const metaPath = join(metaDir, `${entry.id}.json`);
+    writeFileSync(metaPath, JSON.stringify(entry, null, 2), 'utf-8');
+  }
+
+  /** Create an artifact and store its metadata in one step */
+  createAndStoreText(
+    type: ArtifactType,
+    markdown: string,
+    phase: PipelinePhase,
+    groupId?: string,
+  ): ArtifactEntry {
+    const entry = this.createArtifactText(type, markdown, phase, groupId);
+    this.storeArtifactMetadata(entry);
+    return entry;
+  }
+
+  /** Create a JSON artifact and store its metadata in one step */
+  createAndStoreJson(
+    type: ArtifactType,
+    jsonObject: unknown,
+    phase: PipelinePhase,
+    groupId?: string,
+  ): ArtifactEntry {
+    const entry = this.createArtifactJson(type, jsonObject, phase, groupId);
+    this.storeArtifactMetadata(entry);
+    return entry;
+  }
+
+  /** Update /docs/INDEX.md with current artifact listing */
+  updateIndex(artifacts: ArtifactEntry[]): void {
+    this.ensureDocsStructure();
+
+    const lines: string[] = [
+      '# Documentation Index',
+      '',
+      `> Auto-generated by Popeye Pipeline — ${new Date().toISOString()}`,
+      '',
+      '## Artifacts',
+      '',
+      '| Type | Version | Path | Phase | Timestamp |',
+      '|------|---------|------|-------|-----------|',
+    ];
+
+    const sorted = [...artifacts].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+
+    for (const a of sorted) {
+      lines.push(`| ${a.type} | v${a.version} | ${a.path} | ${a.phase} | ${a.timestamp} |`);
+    }
+
+    lines.push('');
+    const indexPath = join(this.docsDir, 'INDEX.md');
+    writeFileSync(indexPath, lines.join('\n'), 'utf-8');
+  }
+
+  /** Get the latest artifact entry in a specific group */
+  private getLatestInGroup(
+    groupId: string,
+    existingArtifacts: ArtifactEntry[],
+  ): ArtifactEntry | null {
+    const groupArtifacts = existingArtifacts
+      .filter((a) => a.group_id === groupId)
+      .sort((a, b) => a.version - b.version);
+    if (groupArtifacts.length === 0) return null;
+    return groupArtifacts[groupArtifacts.length - 1];
+  }
+}
+
+/** Factory function */
+export function createArtifactManager(projectDir: string): ArtifactManager {
+  return new ArtifactManager({ projectDir });
+}

package/src/pipeline/artifact-validators.ts

@@ -0,0 +1,224 @@
+/**
+ * Artifact Completeness Validators — deterministic structural checks.
+ * Runs BEFORE LLM review in consensus phases to catch obvious issues.
+ * Each validator checks for required sections, minimum content length,
+ * and structural integrity specific to its artifact type.
+ */
+
+import type { ArtifactType } from './types.js';
+
+// ─── Types ───────────────────────────────────────────────
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+// ─── Section Patterns ────────────────────────────────────
+
+/** Regex patterns for detecting markdown sections (case-insensitive) */
+function hasSection(content: string, patterns: RegExp[]): boolean {
+  return patterns.some((p) => p.test(content));
+}
+
+function findMissingSections(
+  content: string,
+  required: { name: string; patterns: RegExp[] }[],
+): string[] {
+  const missing: string[] = [];
+  for (const { name, patterns } of required) {
+    if (!hasSection(content, patterns)) {
+      missing.push(name);
+    }
+  }
+  return missing;
+}
+
+// ─── Per-Type Validators ─────────────────────────────────
+
+function validateMasterPlan(content: string): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (content.length < 200) {
+    errors.push('Master plan is too short (min 200 characters)');
+  }
+
+  const missing = findMissingSections(content, [
+    { name: 'Goals/Objectives', patterns: [/#+\s*(goals?|objectives?)/i, /\bgoals?\b.*:/i] },
+    { name: 'Milestones', patterns: [/#+\s*milestones?/i, /\bmilestone\s+\d/i] },
+    { name: 'Success Criteria', patterns: [/#+\s*success\s+criteria/i, /\bsuccess\s+criteria\b/i, /#+\s*acceptance\s+criteria/i] },
+  ]);
+
+  for (const section of missing) {
+    errors.push(`Missing required section: ${section}`);
+  }
+
+  // Check for empty sections (heading followed by another heading or end)
+  const emptyHeadings = content.match(/^(#+\s+.+)\n(?=#+\s+|\s*$)/gm);
+  if (emptyHeadings && emptyHeadings.length > 2) {
+    warnings.push(`${emptyHeadings.length} potentially empty sections detected`);
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+function validateArchitecture(content: string): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (content.length < 200) {
+    errors.push('Architecture document is too short (min 200 characters)');
+  }
+
+  const missing = findMissingSections(content, [
+    { name: 'Components/Modules', patterns: [/#+\s*(components?|modules?|services?)/i, /\bcomponent\b/i] },
+    { name: 'Data Flow/Contracts', patterns: [/#+\s*(data\s+flow|contracts?|api|interfaces?)/i, /\bcontract\b/i, /\bdata\s+flow\b/i] },
+    { name: 'Tech Stack', patterns: [/#+\s*(tech\s+stack|technology|stack)/i, /\btech\s+stack\b/i] },
+  ]);
+
+  for (const section of missing) {
+    errors.push(`Missing required section: ${section}`);
+  }
+
+  // Must reference at least one file path
+  const hasFilePath = /(?:src\/|app\/|pages\/|lib\/|\.ts|\.js|\.py|\.go)/.test(content);
+  if (!hasFilePath) {
+    warnings.push('Architecture should reference at least one file path');
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+function validateRolePlan(content: string): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (content.length < 100) {
+    errors.push('Role plan is too short (min 100 characters)');
+  }
+
+  const missing = findMissingSections(content, [
+    { name: 'Tasks/Responsibilities', patterns: [/#+\s*(tasks?|responsibilities?|work\s+items?)/i, /\btask\b/i] },
+    { name: 'Dependencies', patterns: [/#+\s*(dependenc|prerequisites?|requires?)/i, /\bdepend/i] },
+    { name: 'Acceptance Criteria', patterns: [/#+\s*(acceptance|done\s+when|completion)/i, /\bacceptance\b/i, /\bdone\s+when\b/i] },
+  ]);
+
+  for (const section of missing) {
+    errors.push(`Missing required section: ${section}`);
+  }
+
+  // Should reference a role name
+  const rolePatterns = /\b(DISPATCHER|ARCHITECT|DB_EXPERT|BACKEND|FRONTEND|WEBSITE|QA_TESTER|REVIEWER|AUDITOR|JOURNALIST)\b/i;
+  if (!rolePatterns.test(content)) {
+    warnings.push('Role plan should reference the role name');
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+function validateQaValidation(content: string): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const missing = findMissingSections(content, [
+    { name: 'Test Results', patterns: [/#+\s*(test\s+results?|results?)/i, /\btest\s+results?\b/i, /\bpass(?:ed|ing)?\b/i] },
+    { name: 'Coverage', patterns: [/#+\s*coverage/i, /\bcoverage\b/i, /\d+\s*%/] },
+  ]);
+
+  for (const section of missing) {
+    errors.push(`Missing required section: ${section}`);
+  }
+
+  // Should contain pass/fail counts
+  const hasPassFail = /\b\d+\s*(pass|fail|error|skip)/i.test(content);
+  if (!hasPassFail) {
+    warnings.push('QA validation should include pass/fail counts');
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+function validateAuditReport(content: string): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Try JSON parsing
+  try {
+    const parsed = JSON.parse(content);
+    if (!Array.isArray(parsed.findings)) {
+      errors.push('Audit report must have a "findings" array');
+    }
+    if (typeof parsed.overall_status !== 'string') {
+      errors.push('Audit report must have "overall_status"');
+    }
+    if (typeof parsed.system_risk_score !== 'number') {
+      errors.push('Audit report must have "system_risk_score"');
+    }
+  } catch {
+    // Not JSON — check for markdown-style audit
+    if (!content.includes('findings') && !content.includes('finding')) {
+      errors.push('Audit report must contain findings');
+    }
+    if (!content.includes('status') && !content.includes('PASS') && !content.includes('FAIL')) {
+      errors.push('Audit report must contain overall status');
+    }
+    if (!content.includes('risk') && !content.includes('score')) {
+      warnings.push('Audit report should include risk score');
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+// ─── Validator Registry ──────────────────────────────────
+
+const VALIDATORS: Partial<Record<ArtifactType, (content: string) => ValidationResult>> = {
+  master_plan: validateMasterPlan,
+  architecture: validateArchitecture,
+  role_plan: validateRolePlan,
+  qa_validation: validateQaValidation,
+  audit_report: validateAuditReport,
+};
+
+// ─── Public API ──────────────────────────────────────────
+
+/**
+ * Validate artifact content completeness based on type-specific rules.
+ * Returns a ValidationResult with errors (blocking) and warnings (non-blocking).
+ *
+ * Args:
+ *   type: The artifact type to validate against.
+ *   content: The artifact content string.
+ *
+ * Returns:
+ *   ValidationResult with valid flag, errors, and warnings.
+ */
+export function validateArtifactCompleteness(
+  type: ArtifactType,
+  content: string,
+): ValidationResult {
+  const validator = VALIDATORS[type];
+  if (!validator) {
+    // No validator for this type — pass by default
+    return { valid: true, errors: [], warnings: [] };
+  }
+
+  if (!content || content.trim().length === 0) {
+    return {
+      valid: false,
+      errors: [`${type} artifact has empty content`],
+      warnings: [],
+    };
+  }
+
+  return validator(content);
+}
+
+/**
+ * Get all artifact types that have validators.
+ */
+export function getValidatableArtifactTypes(): ArtifactType[] {
+  return Object.keys(VALIDATORS) as ArtifactType[];
+}