@xulthekl/team-flow 0.23.0 → 0.25.1

package/tests/lib/solutions-capture.test.mjs

@@ -0,0 +1,108 @@
+// tests/lib/solutions-capture.test.mjs
+// Tests for scripts/lib/solutions-capture.mjs — compound capture mechanism
+
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, existsSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+
+const { run: captureRun } = await import(join(ROOT, 'scripts', 'lib', 'solutions-capture.mjs'));
+
+function makeDir() {
+  return mkdtempSync(join(tmpdir(), 'tf-sol-capture-'));
+}
+
+function cleanup(dir) {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+describe('solutions-capture', () => {
+  let dir;
+
+  beforeEach(() => {
+    dir = makeDir();
+  });
+
+  after(() => {
+    // Clean up all temp dirs
+    cleanup(dir);
+  });
+
+  it('creates experience file in correct phase directory', () => {
+    const result = captureRun({
+      phase: 'prd', domain: 'auth', type: 'pitfall', severity: 'high',
+      summary: 'OAuth token refresh fails silently', dir,
+    });
+
+    assert.equal(result.phase, 'prd');
+    assert.equal(result.severity, 'high');
+    assert.match(result.file, /^prd\/\d{4}-\d{2}-\d{2}-.*\.md$/);
+
+    // Verify file exists and has frontmatter
+    const filePath = join(dir, result.file);
+    assert.ok(existsSync(filePath), 'experience file should exist');
+    const content = readFileSync(filePath, 'utf-8');
+    assert.match(content, /^---\nphase: prd\n/);
+    assert.match(content, /domain: auth/);
+    assert.match(content, /type: pitfall/);
+    assert.match(content, /severity: high/);
+  });
+
+  it('creates INDEX.md from scratch when missing', () => {
+    captureRun({
+      phase: 'build', domain: 'ci', type: 'pattern', severity: 'medium',
+      summary: 'Parallel test execution race condition', dir,
+    });
+
+    const indexPath = join(dir, 'INDEX.md');
+    assert.ok(existsSync(indexPath), 'INDEX.md should be created');
+    const content = readFileSync(indexPath, 'utf-8');
+    assert.match(content, /# Solutions Index/);
+    assert.match(content, /parallel test execution/i);
+  });
+
+  it('appends to existing INDEX.md', () => {
+    captureRun({ phase: 'build', domain: 'ci', type: 'pattern', severity: 'high', summary: 'First issue', dir });
+    captureRun({ phase: 'spec', domain: 'api', type: 'insight', severity: 'low', summary: 'Second issue', dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    assert.match(content, /First issue/);
+    assert.match(content, /Second issue/);
+  });
+
+  it('handles Chinese characters in summary (slugify)', () => {
+    const result = captureRun({
+      phase: 'review', domain: 'frontend', type: 'pitfall', severity: 'high',
+      summary: '中文标题测试特殊字符', dir,
+    });
+
+    assert.ok(result.file.includes('review/'), 'file should be in review phase');
+    assert.ok(existsSync(join(dir, result.file)), 'file with Chinese slug should exist');
+  });
+
+  it('uses cross-phase as default when no phase specified', () => {
+    const result = captureRun({ dir });
+    assert.equal(result.phase, 'cross-phase');
+    assert.equal(result.domain, 'general');
+    assert.equal(result.severity, 'medium');
+  });
+
+  it('rejects invalid phase', () => {
+    // capture calls process.exit(1) on invalid phase
+    // We test by checking that the function does not create files
+    const origExit = process.exit;
+    let exitCode = null;
+    process.exit = (code) => { exitCode = code; };
+    try {
+      captureRun({ phase: 'invalid-phase', dir });
+    } catch { /* ignore */ }
+    process.exit = origExit;
+    assert.equal(exitCode, 1, 'should exit with code 1 for invalid phase');
+  });
+});

package/tests/lib/solutions-index-gen.test.mjs

@@ -0,0 +1,147 @@
+// tests/lib/solutions-index-gen.test.mjs
+// Tests for scripts/lib/solutions-index-gen.mjs — full INDEX.md rebuild
+
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, existsSync, rmSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+
+const { run: indexGenRun } = await import(join(ROOT, 'scripts', 'lib', 'solutions-index-gen.mjs'));
+
+function makeDir() {
+  return mkdtempSync(join(tmpdir(), 'tf-sol-indexgen-'));
+}
+
+function cleanup(dir) {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+function writeEntry(dir, phase, filename, fm) {
+  const phaseDir = join(dir, phase);
+  mkdirSync(phaseDir, { recursive: true });
+  const fmLines = Object.entries(fm).map(([k, v]) => `${k}: ${v}`).join('\n');
+  writeFileSync(join(phaseDir, filename), `---\n${fmLines}\n---\n\n${fm.summary || 'Body text'}\n`, 'utf-8');
+}
+
+describe('solutions-index-gen', () => {
+  let dir;
+
+  beforeEach(() => { dir = makeDir(); });
+  after(() => { cleanup(dir); });
+
+  it('rebuilds INDEX.md from phase directories', () => {
+    writeEntry(dir, 'prd', '2026-07-01-auth-issue.md', {
+      phase: 'prd', domain: 'auth', type: 'pitfall', severity: 'high', date: '2026-07-01',
+    });
+    writeEntry(dir, 'build', '2026-07-02-ci-pattern.md', {
+      phase: 'build', domain: 'ci', type: 'pattern', severity: 'medium', date: '2026-07-02',
+    });
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    assert.match(content, /# Solutions Index/);
+    assert.match(content, /auth-issue/);
+    assert.match(content, /ci-pattern/);
+  });
+
+  it('sorts by severity descending (high before medium before low)', () => {
+    writeEntry(dir, 'prd', 'low.md', {
+      phase: 'prd', domain: 'd1', type: 'pitfall', severity: 'low', date: '2026-07-03',
+    });
+    writeEntry(dir, 'prd', 'high.md', {
+      phase: 'prd', domain: 'd2', type: 'pitfall', severity: 'high', date: '2026-07-01',
+    });
+    writeEntry(dir, 'prd', 'medium.md', {
+      phase: 'prd', domain: 'd3', type: 'pitfall', severity: 'medium', date: '2026-07-02',
+    });
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    const highPos = content.indexOf('d2');
+    const medPos = content.indexOf('d3');
+    const lowPos = content.indexOf('d1');
+    assert.ok(highPos < medPos, 'high should appear before medium');
+    assert.ok(medPos < lowPos, 'medium should appear before low');
+  });
+
+  it('sorts by date descending within same severity', () => {
+    writeEntry(dir, 'prd', 'older.md', {
+      phase: 'prd', domain: 'auth', type: 'pitfall', severity: 'high', date: '2026-07-01',
+    });
+    writeEntry(dir, 'prd', 'newer.md', {
+      phase: 'prd', domain: 'auth', type: 'pitfall', severity: 'high', date: '2026-07-15',
+    });
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    const newerPos = content.indexOf('2026-07-15');
+    const olderPos = content.indexOf('2026-07-01');
+    assert.ok(newerPos < olderPos, 'newer date should appear before older date');
+  });
+
+  it('scans all 7 phase directories', () => {
+    const phases = ['prd', 'plan', 'prototype', 'spec', 'build', 'review', 'cross-phase'];
+    for (const phase of phases) {
+      writeEntry(dir, phase, `2026-07-01-${phase}-entry.md`, {
+        phase, domain: 'general', type: 'insight', severity: 'medium', date: '2026-07-01',
+      });
+    }
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    for (const phase of phases) {
+      assert.match(content, new RegExp(phase), `INDEX should contain ${phase} entries`);
+    }
+  });
+
+  it('skips non-.md files', () => {
+    mkdirSync(join(dir, 'build'), { recursive: true });
+    writeFileSync(join(dir, 'build', 'readme.txt'), 'Not a markdown file', 'utf-8');
+    writeEntry(dir, 'build', '2026-07-01-real.md', {
+      phase: 'build', domain: 'ci', type: 'pattern', severity: 'high', date: '2026-07-01',
+    });
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    assert.doesNotMatch(content, /readme\.txt/);
+    assert.match(content, /real\.md/);
+  });
+
+  it('truncates to 150 entries (drops lowest priority)', () => {
+    // Create 155 entries (all high severity, varying dates)
+    mkdirSync(join(dir, 'build'), { recursive: true });
+    for (let i = 0; i < 155; i++) {
+      const day = String((i % 28) + 1).padStart(2, '0');
+      writeEntry(dir, 'build', `entry-${String(i).padStart(3, '0')}.md`, {
+        phase: 'build', domain: `d${i}`, type: 'pattern', severity: 'high', date: `2026-07-${day}`,
+      });
+    }
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    const dataLines = content.split('\n').filter(l => l.startsWith('|') && !l.startsWith('| date') && !l.startsWith('|--'));
+    assert.equal(dataLines.length, 150, 'INDEX should be truncated to 150 entries');
+  });
+
+  it('handles empty solutions directory', () => {
+    // No phase directories exist
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    assert.match(content, /# Solutions Index/);
+    const dataLines = content.split('\n').filter(l => l.startsWith('|') && !l.startsWith('| date') && !l.startsWith('|--'));
+    assert.equal(dataLines.length, 0);
+  });
+});

package/tests/lib/solutions-inject.test.mjs

@@ -0,0 +1,115 @@
+// tests/lib/solutions-inject.test.mjs
+// Tests for scripts/lib/solutions-inject.mjs — compound injection mechanism
+
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, existsSync, rmSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+
+const { run: injectRun } = await import(join(ROOT, 'scripts', 'lib', 'solutions-inject.mjs'));
+
+function makeDir() {
+  return mkdtempSync(join(tmpdir(), 'tf-sol-inject-'));
+}
+
+function cleanup(dir) {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+const INDEX_HEADER = `# Solutions Index
+<!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
+| date | phase | domain | type | severity | summary | file |
+|------|-------|--------|------|----------|---------|------|
+`;
+
+function writeIndex(dir, rows) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'INDEX.md'), INDEX_HEADER + rows.join('\n') + '\n', 'utf-8');
+}
+
+describe('solutions-inject', () => {
+  let dir;
+
+  beforeEach(() => { dir = makeDir(); });
+  after(() => { cleanup(dir); });
+
+  it('returns empty when no INDEX.md exists', () => {
+    const result = injectRun({ phase: 'prd', dir });
+    assert.deepEqual(result.entries, []);
+  });
+
+  it('filters by exact phase match', () => {
+    writeIndex(dir, [
+      '| 2026-07-01 | prd | auth | pitfall | high | PRD auth issue | prd/f1.md |',
+      '| 2026-07-01 | build | auth | pitfall | high | Build auth issue | build/f2.md |',
+    ]);
+    const result = injectRun({ phase: 'prd', dir });
+    assert.equal(result.entries.length, 1);
+    assert.equal(result.entries[0].summary, 'PRD auth issue');
+  });
+
+  it('includes cross-phase entries for any phase query', () => {
+    writeIndex(dir, [
+      '| 2026-07-01 | cross-phase | general | pattern | high | Global pattern | cross-phase/f1.md |',
+      '| 2026-07-01 | prd | auth | pitfall | high | PRD issue | prd/f2.md |',
+    ]);
+    const result = injectRun({ phase: 'build', dir });
+    // cross-phase matches for any phase
+    assert.equal(result.entries.length, 1);
+    assert.equal(result.entries[0].phase, 'cross-phase');
+  });
+
+  it('filters by domain (exact match)', () => {
+    writeIndex(dir, [
+      '| 2026-07-01 | prd | auth | pitfall | high | Auth issue | prd/f1.md |',
+      '| 2026-07-01 | prd | billing | pitfall | high | Billing issue | prd/f2.md |',
+    ]);
+    const result = injectRun({ phase: 'prd', domain: 'auth', dir });
+    assert.equal(result.entries.length, 1);
+    assert.equal(result.entries[0].domain, 'auth');
+  });
+
+  it('domain "general" matches any query', () => {
+    writeIndex(dir, [
+      '| 2026-07-01 | prd | general | pattern | high | General pattern | prd/f1.md |',
+    ]);
+    const result = injectRun({ phase: 'prd', domain: 'auth', dir });
+    assert.equal(result.entries.length, 1);
+  });
+
+  it('sorts by severity descending (high > medium > low)', () => {
+    writeIndex(dir, [
+      '| 2026-07-01 | prd | auth | pitfall | low | Low issue | prd/f1.md |',
+      '| 2026-07-01 | prd | auth | pitfall | high | High issue | prd/f2.md |',
+      '| 2026-07-01 | prd | auth | pitfall | medium | Medium issue | prd/f3.md |',
+    ]);
+    const result = injectRun({ phase: 'prd', dir });
+    assert.equal(result.entries[0].severity, 'high');
+    assert.equal(result.entries[1].severity, 'medium');
+    assert.equal(result.entries[2].severity, 'low');
+  });
+
+  it('limits to top-5 entries', () => {
+    const rows = [];
+    for (let i = 0; i < 10; i++) {
+      rows.push(`| 2026-07-0${(i % 9) + 1} | prd | auth | pitfall | high | Issue ${i} | prd/f${i}.md |`);
+    }
+    writeIndex(dir, rows);
+    const result = injectRun({ phase: 'prd', dir });
+    assert.equal(result.entries.length, 5, 'should cap at top-5');
+  });
+
+  it('returns empty for no matching entries', () => {
+    writeIndex(dir, [
+      '| 2026-07-01 | build | ci | pattern | high | Build issue | build/f1.md |',
+    ]);
+    const result = injectRun({ phase: 'prd', dir });
+    assert.deepEqual(result.entries, []);
+  });
+});

package/tests/lib/solutions-promote.test.mjs

@@ -0,0 +1,200 @@
+// tests/lib/solutions-promote.test.mjs
+// Tests for scripts/lib/solutions-promote.mjs — change→product promotion
+
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, existsSync, rmSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+
+// NODE_ENV=test is set below before import — promote's CLI guard skips when test.
+process.env.NODE_ENV = 'test';
+const { run: promoteRun } = await import(join(ROOT, 'scripts', 'lib', 'solutions-promote.mjs'));
+
+function makeDir(prefix = '') {
+  return mkdtempSync(join(tmpdir(), `tf-sol-promote-${prefix}-`));
+}
+
+function cleanup(dir) {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+function writeLearnings(dir, content) {
+  writeFileSync(join(dir, 'learnings.md'), content, 'utf-8');
+}
+
+const INDEX_HEADER = `# Solutions Index
+| date | phase | domain | type | severity | summary | file |
+|------|-------|--------|------|----------|---------|------|
+`;
+
+function writeGlobalIndex(solDir, rows = []) {
+  mkdirSync(solDir, { recursive: true });
+  writeFileSync(join(solDir, 'INDEX.md'), INDEX_HEADER + rows.join('\n') + '\n', 'utf-8');
+}
+
+describe('solutions-promote', () => {
+  let changeDir, solDir;
+
+  beforeEach(() => {
+    changeDir = makeDir('change');
+    solDir = makeDir('solutions');
+  });
+
+  after(() => {
+    cleanup(changeDir);
+    cleanup(solDir);
+  });
+
+  it('returns zero when no learnings.md exists', () => {
+    const result = promoteRun({ changeDir, dir: solDir });
+    assert.equal(result.promoted, 0);
+    assert.equal(result.updated, 0);
+  });
+
+  it('promotes entry with severity=high and type=pitfall', () => {
+    writeLearnings(changeDir, `## Auth token refresh failure
+---
+phase: build
+domain: auth
+type: pitfall
+severity: high
+date: 2026-07-15
+---
+
+When OAuth token refresh fails, the system silently swallows the error.
+`);
+    const result = promoteRun({ changeDir, dir: solDir });
+    assert.equal(result.promoted, 1);
+    assert.ok(existsSync(join(solDir, 'build')), 'build phase dir should exist');
+  });
+
+  it('promotes entry with severity=medium and type=pattern', () => {
+    writeLearnings(changeDir, `## Retry with backoff pattern
+---
+phase: build
+domain: networking
+type: pattern
+severity: medium
+date: 2026-07-15
+---
+
+Use exponential backoff for API retry logic.
+`);
+    const result = promoteRun({ changeDir, dir: solDir });
+    assert.equal(result.promoted, 1);
+  });
+
+  it('skips entry with severity=low', () => {
+    writeLearnings(changeDir, `## Minor formatting issue
+---
+phase: build
+domain: style
+type: pitfall
+severity: low
+date: 2026-07-15
+---
+
+Some low severity issue.
+`);
+    const result = promoteRun({ changeDir, dir: solDir });
+    assert.equal(result.promoted, 0);
+  });
+
+  it('skips entry with type=insight (not pitfall/pattern)', () => {
+    writeLearnings(changeDir, `## Interesting observation
+---
+phase: build
+domain: auth
+type: insight
+severity: high
+date: 2026-07-15
+---
+
+An insight that should not be promoted.
+`);
+    const result = promoteRun({ changeDir, dir: solDir });
+    assert.equal(result.promoted, 0);
+  });
+
+  it('detects duplicate domain+type and marks as confirmed', () => {
+    writeGlobalIndex(solDir, [
+      '| 2026-07-01 | build | auth | pitfall | medium | Existing auth pitfall | build/existing.md |',
+    ]);
+    writeLearnings(changeDir, `## Another auth pitfall
+---
+phase: build
+domain: auth
+type: pitfall
+severity: high
+date: 2026-07-15
+---
+
+Duplicate domain+type with existing index entry.
+`);
+    const result = promoteRun({ changeDir, dir: solDir });
+    assert.equal(result.updated, 1, 'should detect duplicate and mark as confirmed');
+    assert.equal(result.promoted, 0, 'should not create new file for duplicate');
+  });
+
+  it('promotes multiple entries from single learnings.md', () => {
+    writeLearnings(changeDir, `## Issue one
+---
+phase: spec
+domain: api
+type: pitfall
+severity: high
+date: 2026-07-15
+---
+
+First pitfall.
+
+## Issue two
+---
+phase: spec
+domain: db
+type: pattern
+severity: medium
+date: 2026-07-15
+---
+
+Second pattern.
+
+## Issue three (low sev, skipped)
+---
+phase: spec
+domain: style
+type: pitfall
+severity: low
+date: 2026-07-15
+---
+
+Skipped due to low severity.
+`);
+    const result = promoteRun({ changeDir, dir: solDir });
+    assert.equal(result.promoted, 2, 'should promote 2 entries (high+medium, skip low)');
+  });
+
+  it('appends promoted entry to global INDEX.md', () => {
+    writeGlobalIndex(solDir);
+    writeLearnings(changeDir, `## DB migration ordering
+---
+phase: build
+domain: db
+type: pitfall
+severity: high
+date: 2026-07-15
+---
+
+Migration files must be ordered by timestamp.
+`);
+    promoteRun({ changeDir, dir: solDir });
+    const indexContent = readFileSync(join(solDir, 'INDEX.md'), 'utf-8');
+    assert.match(indexContent, /DB migration ordering/);
+  });
+});