@3fn/core 14.0.0 → 14.1.0

package/src/tools/release/cli/ReleasePipeline.ts

@@ -1,165 +0,0 @@
-/**
- * ReleasePipeline — orchestrates the release tool pipeline.
- *
- * analyze()       → scan + classify + recommend version
- * generateNotes() → analyze + render markdown + write files
- * release()       → generateNotes + tag + GitHub publish
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { TagResolver } from '../pipeline/TagResolver';
-import { SummaryScanner } from '../pipeline/SummaryScanner';
-import { ChangeExtractor } from '../pipeline/ChangeExtractor';
-import { ChangeClassifier } from '../pipeline/ChangeClassifier';
-import { NotesRenderer } from '../pipeline/NotesRenderer';
-import { GitHubPublisher, GitHubConfig } from '../publishers/GitHubPublisher';
-import { PipelineRecommendation, RenderedNotes, ReleaseConfig, ExtractedChange, ClassifiedChange, GitHubRelease } from '../types';
-
-export class ReleasePipeline {
-  private config: ReleaseConfig;
-  private cwd: string;
-
-  constructor(cwd?: string) {
-    this.cwd = cwd || process.cwd();
-    this.config = this.loadConfig();
-  }
-
-  async analyze(): Promise<PipelineRecommendation> {
-    const tagResolver = new TagResolver();
-    const tag = await tagResolver.getLatestTag();
-
-    const scanner = new SummaryScanner(this.cwd);
-    const summaries = await scanner.findSummariesSinceTag(tag);
-
-    if (summaries.length === 0) {
-      return {
-        currentVersion: tag?.tag.replace(/^v/, '') || '0.0.0',
-        recommendedVersion: tag?.tag.replace(/^v/, '') || '0.0.0',
-        bumpType: 'none',
-        rationale: 'No new summary docs found since last tag',
-        confidence: 1.0,
-        changes: [],
-      };
-    }
-
-    const extractor = new ChangeExtractor();
-    const extracted: ExtractedChange[] = summaries
-      .map((s) => extractor.extract(s))
-      .filter((e): e is ExtractedChange => e !== undefined);
-
-    const classifier = new ChangeClassifier();
-    const classified: ClassifiedChange[] = classifier.classify(extracted);
-
-    const currentVersion = tag?.tag.replace(/^v/, '') || '0.0.0';
-    const bumpType = this.determineBump(classified);
-    const recommendedVersion = this.bumpVersion(currentVersion, bumpType);
-
-    return {
-      currentVersion,
-      recommendedVersion,
-      bumpType,
-      rationale: this.buildRationale(classified),
-      confidence: classified.some((c) => c.change.deliverables?.length) ? 0.9 : 0.7,
-      changes: classified,
-    };
-  }
-
-  async generateNotes(): Promise<RenderedNotes> {
-    const recommendation = await this.analyze();
-    const renderer = new NotesRenderer();
-    const notes = renderer.render(recommendation);
-
-    const outputDir = path.resolve(this.cwd, this.config.outputDir);
-    fs.mkdirSync(outputDir, { recursive: true });
-
-    const filename = `release-${recommendation.recommendedVersion}.md`;
-    fs.writeFileSync(path.join(outputDir, filename), notes.public, 'utf-8');
-    fs.writeFileSync(path.join(outputDir, `${filename}.internal.md`), notes.internal, 'utf-8');
-    fs.writeFileSync(path.join(outputDir, `${filename}.json`), JSON.stringify(notes.json, null, 2), 'utf-8');
-
-    return notes;
-  }
-
-  async release(dryRun = false): Promise<{ notes: RenderedNotes; published: boolean; releaseUrl?: string; error?: string }> {
-    const notes = await this.generateNotes();
-    const version = notes.json.version;
-
-    if (dryRun) {
-      return { notes, published: false };
-    }
-
-    const tagResolver = new TagResolver();
-    await tagResolver.createTag(`v${version}`, `Release ${version}`);
-
-    if (this.config.repoUrl) {
-      const [owner, repo] = this.parseRepoUrl(this.config.repoUrl);
-      const token = process.env.GITHUB_TOKEN || '';
-      if (!token) {
-        return { notes, published: false, error: 'GITHUB_TOKEN not set — tag created but GitHub release skipped' };
-      }
-      const publisher = new GitHubPublisher({ token, owner, repo });
-      const release: GitHubRelease = {
-        tagName: `v${version}`,
-        name: `Release ${version}`,
-        body: notes.public,
-        draft: false,
-        prerelease: false,
-        artifacts: [],
-      };
-      const result = await publisher.createRelease(release);
-      const error = result.errors.length > 0 ? result.errors[0].message : undefined;
-      return { notes, published: result.success, releaseUrl: result.githubReleaseUrl, error };
-    }
-
-    return { notes, published: false, error: 'No repoUrl configured — tag created but GitHub release skipped' };
-  }
-
-  checkAccumulation(): string | null {
-    const outputDir = path.resolve(this.cwd, this.config.outputDir);
-    if (!fs.existsSync(outputDir)) return null;
-    const files = fs.readdirSync(outputDir).filter((f) => !f.startsWith('.'));
-    return files.length > 5 ? `⚠️  Output directory has ${files.length} files — consider cleaning old releases` : null;
-  }
-
-  private loadConfig(): ReleaseConfig {
-    const configPath = path.resolve(this.cwd, 'src/tools/release/release-config.json');
-    try {
-      return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-    } catch {
-      return { npmPublishEnabled: false, repoUrl: '', outputDir: 'docs/releases' };
-    }
-  }
-
-  private parseRepoUrl(url: string): [string, string] {
-    const match = url.match(/github\.com[/:]([^/]+)\/([^/.]+)/);
-    return match ? [match[1], match[2]] : ['', ''];
-  }
-
-  private determineBump(classified: ClassifiedChange[]): 'major' | 'minor' | 'patch' | 'none' {
-    if (classified.length === 0) return 'none';
-    if (classified.some((c) => c.priority === 'breaking')) return 'major';
-    if (classified.some((c) => c.priority === 'prominent')) return 'minor';
-    return 'patch';
-  }
-
-  private bumpVersion(version: string, bump: 'major' | 'minor' | 'patch' | 'none'): string {
-    const [major, minor, patch] = version.split('.').map(Number);
-    switch (bump) {
-      case 'major': return `${major + 1}.0.0`;
-      case 'minor': return `${major}.${minor + 1}.0`;
-      case 'patch': return `${major}.${minor}.${patch + 1}`;
-      default: return version;
-    }
-  }
-
-  private buildRationale(classified: ClassifiedChange[]): string {
-    const counts = { breaking: 0, prominent: 0, context: 0 };
-    for (const c of classified) counts[c.priority]++;
-    const parts: string[] = [];
-    if (counts.breaking) parts.push(`${counts.breaking} breaking`);
-    if (counts.prominent) parts.push(`${counts.prominent} prominent`);
-    if (counts.context) parts.push(`${counts.context} context`);
-    return `${classified.length} changes: ${parts.join(', ')}`;
-  }
-}

package/src/tools/release/cli/release-tool.ts

@@ -1,107 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Release Tool CLI
- *
- * Commands:
- *   analyze  — scan changes and display version recommendation
- *   notes    — generate release notes without releasing
- *   release  — generate notes, tag, and publish (with --dry-run option)
- */
-
-import { ReleasePipeline } from './ReleasePipeline';
-
-const COMMANDS = ['analyze', 'notes', 'release'] as const;
-type Command = (typeof COMMANDS)[number];
-
-async function main(): Promise<void> {
-  const args = process.argv.slice(2);
-  const command = args[0] as Command;
-  const dryRun = args.includes('--dry-run');
-
-  if (!command || !COMMANDS.includes(command)) {
-    console.log('Usage: release-tool <command> [options]\n');
-    console.log('Commands:');
-    console.log('  analyze    Scan changes and display version recommendation');
-    console.log('  notes      Generate release notes without releasing');
-    console.log('  release    Generate notes, create tag, and publish GitHub release');
-    console.log('\nOptions:');
-    console.log('  --dry-run  Preview release without creating tag or publishing');
-    process.exit(1);
-  }
-
-  const pipeline = new ReleasePipeline();
-
-  // Check accumulation warning
-  const warning = pipeline.checkAccumulation();
-  if (warning) console.log(warning + '\n');
-
-  try {
-    switch (command) {
-      case 'analyze':
-        return await runAnalyze(pipeline);
-      case 'notes':
-        return await runNotes(pipeline);
-      case 'release':
-        return await runRelease(pipeline, dryRun);
-    }
-  } catch (err) {
-    console.error(`\n❌ ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
-  }
-}
-
-async function runAnalyze(pipeline: ReleasePipeline): Promise<void> {
-  console.log('🔍 Analyzing changes since last tag...\n');
-  const rec = await pipeline.analyze();
-
-  console.log(`Current version:     ${rec.currentVersion}`);
-  console.log(`Recommended version: ${rec.recommendedVersion}`);
-  console.log(`Bump type:           ${rec.bumpType}`);
-  console.log(`Confidence:          ${Math.round(rec.confidence * 100)}%`);
-  console.log(`Rationale:           ${rec.rationale}`);
-
-  if (rec.changes.length > 0) {
-    console.log(`\nChanges (${rec.changes.length}):`);
-    for (const c of rec.changes) {
-      const icon = c.priority === 'breaking' ? '🔴' : c.priority === 'prominent' ? '🟡' : '🔵';
-      console.log(`  ${icon} ${c.change.taskTitle} (${c.deliverableType})`);
-    }
-  }
-}
-
-async function runNotes(pipeline: ReleasePipeline): Promise<void> {
-  console.log('📝 Generating release notes...\n');
-  const notes = await pipeline.generateNotes();
-  console.log(`Version: ${notes.json.version}`);
-  console.log(`Changes: ${notes.json.changes.length}`);
-  console.log(`\nFiles written to docs/releases/`);
-  console.log('\n--- Public Notes Preview ---\n');
-  console.log(notes.public);
-}
-
-async function runRelease(pipeline: ReleasePipeline, dryRun: boolean): Promise<void> {
-  if (dryRun) console.log('🏃 Dry run — no tag or publish will occur\n');
-  console.log('🚀 Running release pipeline...\n');
-
-  const result = await pipeline.release(dryRun);
-  const version = result.notes.json.version;
-
-  if (dryRun) {
-    console.log(`Would release: v${version}`);
-    console.log(`Changes: ${result.notes.json.changes.length}`);
-    console.log('\n--- Public Notes Preview ---\n');
-    console.log(result.notes.public);
-    return;
-  }
-
-  if (result.published) {
-    console.log(`✅ Released v${version}`);
-    if (result.releaseUrl) console.log(`   ${result.releaseUrl}`);
-  } else {
-    console.log(`⚠️  v${version} tagged but not published`);
-    if (result.error) console.log(`   ${result.error}`);
-  }
-}
-
-main();

package/src/tools/release/pipeline/ChangeClassifier.ts

@@ -1,61 +0,0 @@
-/**
- * ChangeClassifier for Release Tool
- *
- * Maps ExtractedChange objects to ClassifiedChange with priority tier.
- * Uses structured Deliverables field when present, falls back to keyword heuristics.
- */
-
-import { ExtractedChange, ClassifiedChange, Priority } from '../types';
-
-const PRIORITY_MAP: Record<string, Priority> = { '🔴': 'breaking', '🟡': 'prominent', '🔵': 'context' };
-
-const KEYWORD_RULES: [RegExp, Priority, string][] = [
-  [/\bbreaking\b/i, 'breaking', 'Breaking change'],
-  [/\btoken\b/i, 'breaking', 'Token'],
-  [/\bcomponent\b/i, 'breaking', 'Component'],
-  [/\btool\b/i, 'prominent', 'Tool'],
-  [/\bagent\b/i, 'prominent', 'Agent'],
-  [/\bmcp\b/i, 'prominent', 'MCP'],
-  [/\bbuild\b/i, 'prominent', 'Build'],
-  [/\bgovernance\b/i, 'context', 'Governance'],
-  [/\bprocess\b/i, 'context', 'Process'],
-  [/\binfrastructure\b/i, 'context', 'Infrastructure'],
-  [/\bdocumentation\b/i, 'context', 'Documentation'],
-];
-
-const PRIORITY_ORDER: Record<Priority, number> = { breaking: 0, prominent: 1, context: 2 };
-
-export class ChangeClassifier {
-  classify(changes: ExtractedChange[]): ClassifiedChange[] {
-    return changes
-      .map((change) => this.classifyOne(change))
-      .sort((a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority]);
-  }
-
-  private classifyOne(change: ExtractedChange): ClassifiedChange {
-    if (change.deliverables && change.deliverables.length > 0) {
-      const highest = change.deliverables.reduce((best, d) =>
-        PRIORITY_ORDER[PRIORITY_MAP[d.priority]] < PRIORITY_ORDER[PRIORITY_MAP[best.priority]] ? d : best,
-      );
-      return {
-        change,
-        priority: PRIORITY_MAP[highest.priority],
-        deliverableType: highest.type,
-      };
-    }
-
-    return this.classifyByKeywords(change);
-  }
-
-  private classifyByKeywords(change: ExtractedChange): ClassifiedChange {
-    const text = [change.taskTitle, change.whatWasDone, ...change.keyChanges].join(' ');
-
-    for (const [pattern, priority, type] of KEYWORD_RULES) {
-      if (pattern.test(text)) {
-        return { change, priority, deliverableType: type };
-      }
-    }
-
-    return { change, priority: 'context', deliverableType: 'Other' };
-  }
-}

package/src/tools/release/pipeline/ChangeExtractor.ts

@@ -1,87 +0,0 @@
-/**
- * ChangeExtractor for Release Tool
- *
- * Parses summary doc markdown into structured ExtractedChange objects.
- * Handles both the optional ## Deliverables field and plain section extraction.
- */
-
-import { SummaryDoc, ExtractedChange, DeliverableEntry } from '../types';
-
-export class ChangeExtractor {
-  extract(doc: SummaryDoc): ExtractedChange {
-    const sections = this.parseSections(doc.raw);
-
-    return {
-      specName: doc.specName,
-      taskTitle: this.extractTitle(doc.raw),
-      taskType: this.extractMetadata(doc.raw, 'Type') || 'Unknown',
-      whatWasDone: sections['what was done'] || '',
-      whyItMatters: sections['why it matters'] || '',
-      keyChanges: this.extractList(sections['key changes'] || ''),
-      impact: this.extractList(sections['impact'] || ''),
-      deliverables: this.extractDeliverables(sections['deliverables'] || sections['deliverables *(optional)*'] || ''),
-    };
-  }
-
-  private parseSections(raw: string): Record<string, string> {
-    const sections: Record<string, string> = {};
-    const lines = raw.split('\n');
-    let currentHeading = '';
-    let currentContent: string[] = [];
-
-    for (const line of lines) {
-      const headingMatch = line.match(/^##\s+(.+)$/);
-      if (headingMatch) {
-        if (currentHeading) {
-          sections[currentHeading] = currentContent.join('\n').trim();
-        }
-        currentHeading = headingMatch[1].toLowerCase().trim();
-        currentContent = [];
-      } else if (currentHeading) {
-        currentContent.push(line);
-      }
-    }
-
-    if (currentHeading) {
-      sections[currentHeading] = currentContent.join('\n').trim();
-    }
-
-    return sections;
-  }
-
-  private extractTitle(raw: string): string {
-    const match = raw.match(/^#\s+(?:Task\s+\d+\s+Summary:\s*)?(.+)$/m);
-    return match ? match[1].trim() : '';
-  }
-
-  private extractMetadata(raw: string, key: string): string | null {
-    const match = raw.match(new RegExp(`\\*\\*${key}\\*\\*:\\s*(.+)`, 'i'));
-    return match ? match[1].trim() : null;
-  }
-
-  private extractList(content: string): string[] {
-    return content
-      .split('\n')
-      .filter((l) => l.trim().startsWith('-') || l.trim().startsWith('*'))
-      .map((l) => l.replace(/^[-*]\s*/, '').replace(/^[\u{2000}-\u{FFFF}\u{1F000}-\u{1FFFF}]\uFE0F?\s*/u, '').trim())
-      .filter((l) => l.length > 0);
-  }
-
-  private extractDeliverables(content: string): DeliverableEntry[] | undefined {
-    if (!content) return undefined;
-
-    const entries: DeliverableEntry[] = [];
-    for (const line of content.split('\n')) {
-      const match = line.match(/^-\s*(🔴|🟡|🔵)\s+([^:]+):\s*(.+)$/);
-      if (match) {
-        entries.push({
-          priority: match[1] as '🔴' | '🟡' | '🔵',
-          type: match[2].trim(),
-          description: match[3].trim(),
-        });
-      }
-    }
-
-    return entries.length > 0 ? entries : undefined;
-  }
-}

package/src/tools/release/pipeline/NotesRenderer.ts

@@ -1,66 +0,0 @@
-/**
- * NotesRenderer for Release Tool
- *
- * Generates markdown release notes from a PipelineRecommendation.
- * Public notes include 🔴 (breaking) and 🟡 (prominent) only.
- * Internal notes include all tiers.
- */
-
-import { PipelineRecommendation, RenderedNotes, ClassifiedChange, ReleaseData } from '../types';
-
-const TIER_HEADINGS: Record<string, string> = {
-  breaking: '🔴 Breaking / Consumer-Facing',
-  prominent: '🟡 Ecosystem Changes',
-  context: '🔵 Internal / Context',
-};
-
-export class NotesRenderer {
-  render(recommendation: PipelineRecommendation): RenderedNotes {
-    const grouped = this.groupByPriority(recommendation.changes);
-    const date = new Date().toISOString().split('T')[0];
-
-    const json: ReleaseData = {
-      version: recommendation.recommendedVersion,
-      previousVersion: recommendation.currentVersion,
-      date,
-      changes: recommendation.changes,
-      recommendation,
-    };
-
-    const header = `# Release ${recommendation.recommendedVersion}\n\n**Date**: ${date}  \n**Previous**: ${recommendation.currentVersion}  \n**Bump**: ${recommendation.bumpType}\n`;
-
-    const publicSections = this.renderSections(grouped, ['breaking', 'prominent']);
-    const internalSections = this.renderSections(grouped, ['breaking', 'prominent', 'context']);
-
-    return {
-      public: publicSections ? `${header}\n${publicSections}` : `${header}\nNo consumer-facing changes in this release.\n`,
-      internal: `${header}\n${internalSections || 'No changes in this release.\n'}`,
-      json,
-    };
-  }
-
-  private groupByPriority(changes: ClassifiedChange[]): Record<string, ClassifiedChange[]> {
-    const grouped: Record<string, ClassifiedChange[]> = {};
-    for (const c of changes) {
-      (grouped[c.priority] ??= []).push(c);
-    }
-    return grouped;
-  }
-
-  private renderSections(grouped: Record<string, ClassifiedChange[]>, tiers: string[]): string {
-    return tiers
-      .filter((tier) => grouped[tier]?.length)
-      .map((tier) => `## ${TIER_HEADINGS[tier]}\n\n${this.renderChanges(grouped[tier])}`)
-      .join('\n');
-  }
-
-  private renderChanges(changes: ClassifiedChange[]): string {
-    return changes
-      .map((c) => {
-        const lines = [`- **${c.change.taskTitle}** *(${c.deliverableType})*`];
-        if (c.change.whatWasDone) lines.push(`  ${c.change.whatWasDone}`);
-        return lines.join('\n');
-      })
-      .join('\n') + '\n';
-  }
-}

package/src/tools/release/pipeline/SummaryScanner.ts

@@ -1,70 +0,0 @@
-/**
- * SummaryScanner for Release Tool
- *
- * Discovers task summary documents added since the last release tag.
- * Uses git log when a tag exists, falls back to glob when no tags.
- */
-
-import { execSync } from 'child_process';
-import * as fs from 'fs';
-import * as path from 'path';
-import { TagInfo, SummaryDoc } from '../types';
-
-const SUMMARY_GLOB = 'docs/specs/*/task-*-summary.md';
-
-export class SummaryScanner {
-  private cwd: string;
-
-  constructor(cwd?: string) {
-    this.cwd = cwd || process.cwd();
-  }
-
-  async findSummariesSinceTag(tag: TagInfo | null): Promise<SummaryDoc[]> {
-    const paths = tag ? this.findViaGit(tag) : this.findViaGlob();
-    return paths.map((p) => this.parseSummaryDoc(p)).filter((d): d is SummaryDoc => d !== null);
-  }
-
-  private findViaGit(tag: TagInfo): string[] {
-    try {
-      const output = execSync(
-        `git log --diff-filter=A --name-only --pretty=format: ${tag.tag}..HEAD -- "${SUMMARY_GLOB}"`,
-        { cwd: this.cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] },
-      );
-      return output.split('\n').map((l) => l.trim()).filter((l) => l.length > 0);
-    } catch {
-      return this.findViaGlob();
-    }
-  }
-
-  private findViaGlob(): string[] {
-    try {
-      const output = execSync(`find docs/specs -name "task-*-summary.md" -type f 2>/dev/null | sort`,
-        { cwd: this.cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] },
-      );
-      return output.split('\n').map((l) => l.trim()).filter((l) => l.length > 0);
-    } catch {
-      return [];
-    }
-  }
-
-  private parseSummaryDoc(filePath: string): SummaryDoc | null {
-    try {
-      const fullPath = path.resolve(this.cwd, filePath);
-      const raw = fs.readFileSync(fullPath, 'utf-8');
-
-      const specMatch = filePath.match(/docs\/specs\/([^/]+)\//);
-      const taskMatch = filePath.match(/task-(\d+)-summary\.md$/);
-
-      if (!specMatch || !taskMatch) return null;
-
-      return {
-        path: filePath,
-        specName: specMatch[1],
-        taskNumber: parseInt(taskMatch[1]),
-        raw,
-      };
-    } catch {
-      return null;
-    }
-  }
-}

package/src/tools/release/pipeline/TagResolver.ts

@@ -1,40 +0,0 @@
-/**
- * TagResolver for Release Tool
- *
- * Resolves release boundaries using git tags.
- * Git tags are the only persistent state in this system.
- */
-
-import { execSync } from 'child_process';
-import { TagInfo } from '../types';
-
-export class TagResolver {
-  private cwd: string;
-
-  constructor(cwd?: string) {
-    this.cwd = cwd || process.cwd();
-  }
-
-  async getLatestTag(): Promise<TagInfo | null> {
-    try {
-      const tag = this.exec('git describe --tags --abbrev=0').trim();
-      if (!tag) return null;
-
-      const commit = this.exec(`git rev-list -n 1 ${tag}`).trim();
-      const date = this.exec(`git log -1 --format=%aI ${tag}`).trim();
-
-      return { tag, commit, date };
-    } catch {
-      return null;
-    }
-  }
-
-  async createTag(version: string, message: string): Promise<void> {
-    const tag = version.startsWith('v') ? version : `v${version}`;
-    this.exec(`git tag -a ${tag} -m "${message.replace(/"/g, '\\"')}"`);
-  }
-
-  private exec(command: string): string {
-    return execSync(command, { cwd: this.cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
-  }
-}