@xulthekl/team-flow 0.22.4

package/src/parsing/requirement-blocks.ts

@@ -0,0 +1,244 @@
+export interface RequirementBlock {
+  headerLine: string;
+  name: string;
+  raw: string;
+}
+
+export interface RequirementsSectionParts {
+  before: string;
+  headerLine: string;
+  preamble: string;
+  bodyBlocks: RequirementBlock[];
+  after: string;
+}
+
+export function normalizeRequirementName(name: string): string {
+  return name.trim();
+}
+
+export const REQUIREMENT_HEADER_REGEX = /^###\s*Requirement:\s*(.+)\s*$/i;
+
+function normalizeLineEndings(content: string): string {
+  return content.replace(/\r\n?/g, '\n');
+}
+
+export function extractRequirementsSection(content: string): RequirementsSectionParts {
+  const normalized = normalizeLineEndings(content);
+  const lines = normalized.split('\n');
+  const reqHeaderIndex = lines.findIndex((l) => /^##\s+Requirements\s*$/i.test(l));
+
+  if (reqHeaderIndex === -1) {
+    const before = content.trimEnd();
+    const headerLine = '## Requirements';
+    return {
+      before: before ? before + '\n\n' : '',
+      headerLine,
+      preamble: '',
+      bodyBlocks: [],
+      after: '\n',
+    };
+  }
+
+  let endIndex = lines.length;
+  for (let i = reqHeaderIndex + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) {
+      endIndex = i;
+      break;
+    }
+  }
+
+  const before = lines.slice(0, reqHeaderIndex).join('\n');
+  const headerLine = lines[reqHeaderIndex];
+  const sectionBodyLines = lines.slice(reqHeaderIndex + 1, endIndex);
+
+  const blocks: RequirementBlock[] = [];
+  let cursor = 0;
+  let preambleLines: string[] = [];
+
+  while (
+    cursor < sectionBodyLines.length &&
+    !REQUIREMENT_HEADER_REGEX.test(sectionBodyLines[cursor])
+  ) {
+    preambleLines.push(sectionBodyLines[cursor]);
+    cursor++;
+  }
+
+  while (cursor < sectionBodyLines.length) {
+    const headerLineCandidate = sectionBodyLines[cursor];
+    const headerMatch = headerLineCandidate.match(REQUIREMENT_HEADER_REGEX);
+    if (!headerMatch) {
+      cursor++;
+      continue;
+    }
+    const name = normalizeRequirementName(headerMatch[1]);
+    cursor++;
+    const bodyLines: string[] = [headerLineCandidate];
+    while (
+      cursor < sectionBodyLines.length &&
+      !REQUIREMENT_HEADER_REGEX.test(sectionBodyLines[cursor]) &&
+      !/^##\s+/.test(sectionBodyLines[cursor])
+    ) {
+      bodyLines.push(sectionBodyLines[cursor]);
+      cursor++;
+    }
+    const raw = bodyLines.join('\n').trimEnd();
+    blocks.push({ headerLine: headerLineCandidate, name, raw });
+  }
+
+  const after = lines.slice(endIndex).join('\n');
+  const preamble = preambleLines.join('\n').trimEnd();
+
+  return {
+    before: before.trimEnd() ? before + '\n' : before,
+    headerLine,
+    preamble,
+    bodyBlocks: blocks,
+    after: after.startsWith('\n') ? after : '\n' + after,
+  };
+}
+
+export interface DeltaPlan {
+  added: RequirementBlock[];
+  modified: RequirementBlock[];
+  removed: string[];
+  renamed: Array<{ from: string; to: string }>;
+  sectionPresence: {
+    added: boolean;
+    modified: boolean;
+    removed: boolean;
+    renamed: boolean;
+  };
+}
+
+function splitTopLevelSections(content: string): Record<string, string> {
+  const lines = content.split('\n');
+  const result: Record<string, string> = {};
+  const indices: Array<{ title: string; index: number; level: number }> = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^(##)\s+(.+)$/);
+    if (m) {
+      const level = m[1].length;
+      indices.push({ title: m[2].trim(), index: i, level });
+    }
+  }
+  for (let i = 0; i < indices.length; i++) {
+    const current = indices[i];
+    const next = indices[i + 1];
+    const body = lines
+      .slice(current.index + 1, next ? next.index : lines.length)
+      .join('\n');
+    result[current.title] = body;
+  }
+  return result;
+}
+
+function getSectionCaseInsensitive(
+  sections: Record<string, string>,
+  desired: string
+): { body: string; found: boolean } {
+  const target = desired.toLowerCase();
+  for (const [title, body] of Object.entries(sections)) {
+    if (title.toLowerCase() === target) return { body, found: true };
+  }
+  return { body: '', found: false };
+}
+
+function parseRequirementBlocksFromSection(sectionBody: string): RequirementBlock[] {
+  if (!sectionBody) return [];
+  const lines = normalizeLineEndings(sectionBody).split('\n');
+  const blocks: RequirementBlock[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    while (i < lines.length && !REQUIREMENT_HEADER_REGEX.test(lines[i])) i++;
+    if (i >= lines.length) break;
+    const headerLine = lines[i];
+    const m = headerLine.match(REQUIREMENT_HEADER_REGEX);
+    if (!m) {
+      i++;
+      continue;
+    }
+    const name = normalizeRequirementName(m[1]);
+    const buf: string[] = [headerLine];
+    i++;
+    while (
+      i < lines.length &&
+      !REQUIREMENT_HEADER_REGEX.test(lines[i]) &&
+      !/^##\s+/.test(lines[i])
+    ) {
+      buf.push(lines[i]);
+      i++;
+    }
+    blocks.push({ headerLine, name, raw: buf.join('\n').trimEnd() });
+  }
+  return blocks;
+}
+
+function parseRemovedNames(sectionBody: string): string[] {
+  if (!sectionBody) return [];
+  const names: string[] = [];
+  const lines = normalizeLineEndings(sectionBody).split('\n');
+  for (const line of lines) {
+    const m = line.match(REQUIREMENT_HEADER_REGEX);
+    if (m) {
+      names.push(normalizeRequirementName(m[1]));
+      continue;
+    }
+    const bullet = line.match(/^\s*-\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
+    if (bullet) {
+      names.push(normalizeRequirementName(bullet[1]));
+    }
+  }
+  return names;
+}
+
+function parseRenamedPairs(
+  sectionBody: string
+): Array<{ from: string; to: string }> {
+  if (!sectionBody) return [];
+  const pairs: Array<{ from: string; to: string }> = [];
+  const lines = normalizeLineEndings(sectionBody).split('\n');
+  let current: { from?: string; to?: string } = {};
+  for (const line of lines) {
+    const fromMatch = line.match(
+      /^\s*-?\s*FROM:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/
+    );
+    const toMatch = line.match(
+      /^\s*-?\s*TO:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/
+    );
+    if (fromMatch) {
+      current.from = normalizeRequirementName(fromMatch[1]);
+    } else if (toMatch) {
+      current.to = normalizeRequirementName(toMatch[1]);
+      if (current.from && current.to) {
+        pairs.push({ from: current.from, to: current.to });
+        current = {};
+      }
+    }
+  }
+  return pairs;
+}
+
+export function parseDeltaSpec(content: string): DeltaPlan {
+  const normalized = normalizeLineEndings(content);
+  const sections = splitTopLevelSections(normalized);
+  const addedLookup = getSectionCaseInsensitive(sections, 'ADDED Requirements');
+  const modifiedLookup = getSectionCaseInsensitive(sections, 'MODIFIED Requirements');
+  const removedLookup = getSectionCaseInsensitive(sections, 'REMOVED Requirements');
+  const renamedLookup = getSectionCaseInsensitive(sections, 'RENAMED Requirements');
+  const added = parseRequirementBlocksFromSection(addedLookup.body);
+  const modified = parseRequirementBlocksFromSection(modifiedLookup.body);
+  const removedNames = parseRemovedNames(removedLookup.body);
+  const renamedPairs = parseRenamedPairs(renamedLookup.body);
+  return {
+    added,
+    modified,
+    removed: removedNames,
+    renamed: renamedPairs,
+    sectionPresence: {
+      added: addedLookup.found,
+      modified: modifiedLookup.found,
+      removed: removedLookup.found,
+      renamed: renamedLookup.found,
+    },
+  };
+}

package/src/schema/base.ts

@@ -0,0 +1,8 @@
+export interface Scenario {
+  rawText: string;
+}
+
+export interface Requirement {
+  text: string;
+  scenarios: Scenario[];
+}

package/src/schema/change.ts

@@ -0,0 +1,29 @@
+import { Requirement } from './base.js';
+
+export type DeltaOperationType = 'ADDED' | 'MODIFIED' | 'REMOVED' | 'RENAMED';
+
+export interface Rename {
+  from: string;
+  to: string;
+}
+
+export interface Delta {
+  spec: string;
+  operation: DeltaOperationType;
+  description: string;
+  requirement?: Requirement;
+  requirements?: Requirement[];
+  rename?: Rename;
+}
+
+export interface Change {
+  name: string;
+  why: string;
+  whatChanges: string;
+  deltas: Delta[];
+  metadata?: {
+    version?: string;
+    format?: string;
+    sourcePath?: string;
+  };
+}

package/src/schema/index.ts

@@ -0,0 +1,3 @@
+export type { Scenario, Requirement } from './base.js';
+export type { DeltaOperationType, Rename, Delta, Change } from './change.js';
+export type { Spec } from './spec.js';

package/src/schema/spec.ts

@@ -0,0 +1,12 @@
+import { Requirement } from './base.js';
+
+export interface Spec {
+  name: string;
+  overview: string;
+  requirements: Requirement[];
+  metadata?: {
+    version?: string;
+    format?: string;
+    sourcePath?: string;
+  };
+}

package/src/validation/constants.ts

@@ -0,0 +1,53 @@
+export const MIN_WHY_SECTION_LENGTH = 50;
+export const MIN_PURPOSE_LENGTH = 50;
+
+export const MAX_WHY_SECTION_LENGTH = 1000;
+export const MAX_REQUIREMENT_TEXT_LENGTH = 500;
+export const MAX_DELTAS_PER_CHANGE = 10;
+
+export const VALIDATION_MESSAGES = {
+  SCENARIO_EMPTY: 'Scenario text cannot be empty',
+  REQUIREMENT_EMPTY: 'Requirement text cannot be empty',
+  REQUIREMENT_NO_SHALL: 'Requirement must contain SHALL or MUST keyword',
+  REQUIREMENT_NO_SCENARIOS: 'Requirement must have at least one scenario',
+  SPEC_NAME_EMPTY: 'Spec name cannot be empty',
+  SPEC_PURPOSE_EMPTY: 'Purpose section cannot be empty',
+  SPEC_NO_REQUIREMENTS: 'Spec must have at least one requirement',
+  CHANGE_NAME_EMPTY: 'Change name cannot be empty',
+  CHANGE_WHY_TOO_SHORT: `Why section must be at least ${MIN_WHY_SECTION_LENGTH} characters`,
+  CHANGE_WHY_TOO_LONG: `Why section should not exceed ${MAX_WHY_SECTION_LENGTH} characters`,
+  CHANGE_WHAT_EMPTY: 'What Changes section cannot be empty',
+  CHANGE_NO_DELTAS: 'Change must have at least one delta',
+  CHANGE_TOO_MANY_DELTAS: `Consider splitting changes with more than ${MAX_DELTAS_PER_CHANGE} deltas`,
+  DELTA_SPEC_EMPTY: 'Spec name cannot be empty',
+  DELTA_DESCRIPTION_EMPTY: 'Delta description cannot be empty',
+
+  PURPOSE_TOO_BRIEF: `Purpose section is too brief (less than ${MIN_PURPOSE_LENGTH} characters)`,
+  REQUIREMENT_TOO_LONG: `Requirement text is very long (>${MAX_REQUIREMENT_TEXT_LENGTH} characters). Consider breaking it down.`,
+  DELTA_DESCRIPTION_TOO_BRIEF: 'Delta description is too brief',
+  DELTA_MISSING_REQUIREMENTS: 'Delta should include requirements',
+
+  GUIDE_NO_DELTAS:
+    'No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. Tip: run "openspec change show <change-id> --json --deltas-only" to inspect parsed deltas.',
+  GUIDE_MISSING_SPEC_SECTIONS:
+    'Missing required sections. Expected headers: "## Purpose" and "## Requirements". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...',
+  GUIDE_MISSING_CHANGE_SECTIONS:
+    'Missing required sections. Expected headers: "## Why" and "## What Changes". Ensure deltas are documented in specs/ using delta headers.',
+  GUIDE_SCENARIO_FORMAT:
+    'Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...',
+} as const;
+
+export const VERIFICATION_DIMENSIONS = ['Completeness', 'Correctness', 'Coherence'] as const;
+
+export const VERIFICATION_MESSAGES = {
+  COMPLETENESS_MISSING_TASK: 'Task in tasks.md has no corresponding code change in diff summary',
+  COMPLETENESS_MISSING_REQUIREMENT: 'SHALL/MUST requirement in spec has no matching implementation in diff summary: {requirement}',
+  CORRECTNESS_TEST_FAILURE: 'Test suite has failures',
+  CORRECTNESS_MISSING_SCENARIO: 'Spec scenario has no corresponding test assertion',
+  COHERENCE_NAMING_MISMATCH: 'Design decision naming does not match implementation naming',
+  COHERENCE_PATTERN_MISSING: 'Architecture pattern from design.md not found in implementation: {pattern}',
+  VERIFICATION_PLACEHOLDER_DETECTED: 'Diff summary contains placeholder markers (TODO, FIXME, HACK)',
+  CONFLICT_DETECTED: 'Requirement "{requirement}" is modified by multiple changes: {changes}',
+} as const;
+
+export const MIN_ABANDONMENT_REASON_LENGTH = 50;

package/src/validation/tokenizer.ts

@@ -0,0 +1,180 @@
+/**
+ * Multi-language tokenizer for team-flow keyword extraction.
+ * Supports English (stemming + stop words) and Chinese (CJK sliding window).
+ * Zero external dependencies.
+ */
+
+// --- English stop words ---
+const ENGLISH_STOP_WORDS = new Set([
+  'the', 'be', 'to', 'of', 'and', 'a', 'in', 'that', 'have', 'i',
+  'it', 'for', 'not', 'on', 'with', 'he', 'as', 'you', 'do', 'at',
+  'this', 'but', 'his', 'by', 'from', 'they', 'we', 'say', 'her', 'she',
+  'or', 'an', 'will', 'my', 'one', 'all', 'would', 'there', 'their',
+  'what', 'so', 'up', 'out', 'if', 'about', 'who', 'get', 'which', 'go',
+  'me', 'when', 'make', 'can', 'like', 'time', 'no', 'just', 'him',
+  'know', 'take', 'people', 'into', 'year', 'your', 'good', 'some',
+  'could', 'them', 'see', 'other', 'than', 'then', 'now', 'look',
+  'only', 'come', 'its', 'over', 'think', 'also', 'back', 'after',
+  'use', 'two', 'how', 'our', 'work', 'first', 'well', 'way', 'even',
+  'new', 'want', 'because', 'any', 'these', 'give', 'day', 'most', 'us',
+  'is', 'am', 'are', 'was', 'were', 'been', 'has', 'had', 'did', 'does',
+  'based', 'using', 'used',
+]);
+
+// --- Chinese stop words ---
+const CHINESE_STOP_WORDS = new Set([
+  '的', '了', '在', '是', '我', '有', '和', '就', '不', '人',
+  '都', '一', '一个', '上', '也', '很', '到', '说', '要', '去',
+  '你', '会', '着', '没有', '看', '好', '自己', '这',
+]);
+
+// --- Chinese punctuation ---
+const CHINESE_PUNCTUATION = /[，。！？；：、""''（）【】《》]/;
+
+// --- CJK Unicode ranges ---
+const CJK_REGEX = /[一-鿿㐀-䶿]+/g;
+const CJK_CHAR_REGEX = /[一-鿿㐀-䶿]/g;
+
+/**
+ * Lightweight English stemmer — copy of the one in validator.ts.
+ * Strips only the most common suffixes (-ing, -er, -ed, -s, -tion)
+ * so that natural variations like "limiting" / "limiter" / "limit"
+ * collapse to the same stem.
+ *
+ * Intentionally conservative — false-negative matching is preferred
+ * over false-positive.
+ */
+function stem(word: string): string {
+  const w = word.toLowerCase();
+  if (w.length <= 3) return w;
+  // Longer suffixes first so "ting" strips before "ing", "tion" before "ion", etc.
+  const suffixes: Array<[string, number]> = [
+    ['ation', 3], ['tion', 3], ['ness', 3], ['ment', 3],
+    ['ings', 3], ['ally', 3],
+    ['ing', 3], ['ier', 3], ['ied', 3], ['ies', 3],
+    ['ted', 3], ['ned', 3], ['red', 3], ['sed', 3], ['led', 3],
+    ['ped', 3], ['ded', 3], ['ved', 3], ['wed', 3], ['xed', 3],
+    ['zed', 3], ['ced', 3], ['ged', 3], ['ked', 3],
+    ['ers', 3], ['ors', 3],
+    ['ary', 3], ['ory', 3], ['ity', 3], ['ism', 3], ['ist', 3],
+    ['ent', 3], ['ant', 3], ['ous', 3], ['ive', 3], ['ful', 3],
+    ['ly', 3], ['ed', 3], ['er', 3], ['es', 3],
+    ['al', 3], ['en', 3], ['ty', 3], ['or', 3], ['ar', 3],
+    ['ry', 3], ['ic', 3], ['id', 3],
+  ];
+  for (const [suffix, minRoot] of suffixes) {
+    if (w.endsWith(suffix) && w.length - suffix.length >= minRoot) {
+      return w.slice(0, -suffix.length);
+    }
+  }
+  if (w.endsWith('s') && w.length > 4) return w.slice(0, -1);
+  return w;
+}
+
+/**
+ * Tokenize English text: lowercase, split on non-alphanumeric,
+ * remove stop words, apply stemming, filter short tokens.
+ */
+function tokenizeEnglish(text: string): Set<string> {
+  const tokens = new Set<string>();
+  const words = text.toLowerCase().split(/[^a-z0-9]+/).filter(w => w.length > 0);
+  for (const word of words) {
+    if (ENGLISH_STOP_WORDS.has(word)) continue;
+    const stemmed = stem(word);
+    if (stemmed.length < 3) continue;
+    tokens.add(stemmed);
+  }
+  return tokens;
+}
+
+/**
+ * Tokenize Chinese text: extract CJK sequences, produce sliding-window
+ * tokens (2-char through 5-char), also extract ASCII words with English stemming.
+ * Remove Chinese stop words.
+ */
+function tokenizeChinese(text: string): Set<string> {
+  const tokens = new Set<string>();
+
+  // Split on Chinese punctuation first
+  const segments = text.split(CHINESE_PUNCTUATION);
+
+  for (const segment of segments) {
+    // Extract CJK character sequences
+    const cjkRuns = segment.match(CJK_REGEX);
+    if (cjkRuns) {
+      for (const run of cjkRuns) {
+        if (run.length < 2) continue;
+
+        // Add the full run as a token (if not a stop word)
+        if (!CHINESE_STOP_WORDS.has(run)) {
+          tokens.add(run);
+        }
+
+        // Sliding windows from length 2 up to min(run.length, 5)
+        const maxWindow = Math.min(run.length, 5);
+        for (let windowSize = 2; windowSize <= maxWindow; windowSize++) {
+          for (let i = 0; i <= run.length - windowSize; i++) {
+            const ngram = run.slice(i, i + windowSize);
+            if (!CHINESE_STOP_WORDS.has(ngram)) {
+              tokens.add(ngram);
+            }
+          }
+        }
+      }
+    }
+
+    // Extract ASCII words from mixed content
+    const asciiWords = segment.match(/[a-zA-Z0-9]+/g);
+    if (asciiWords) {
+      for (const word of asciiWords) {
+        const lower = word.toLowerCase();
+        if (ENGLISH_STOP_WORDS.has(lower)) continue;
+        const stemmed = stem(lower);
+        if (stemmed.length < 3) continue;
+        tokens.add(stemmed);
+      }
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * Auto-detect the language of the given text.
+ * Returns 'en', 'zh', or 'mixed'.
+ */
+export function detectLanguage(text: string): 'en' | 'zh' | 'mixed' {
+  const cjkMatches = text.match(CJK_CHAR_REGEX);
+  const cjkCount = cjkMatches ? cjkMatches.length : 0;
+  const totalChars = text.replace(/\s/g, '').length;
+  const cjkRatio = totalChars > 0 ? cjkCount / totalChars : 0;
+
+  const hasAsciiWords = /[a-zA-Z]{2,}/.test(text);
+
+  if (cjkRatio > 0.3 && hasAsciiWords) return 'mixed';
+  if (cjkRatio > 0.3) return 'zh';
+  return 'en';
+}
+
+/**
+ * Main tokenizer entry point.
+ * @param text - The text to tokenize.
+ * @param language - 'auto' | 'en' | 'zh'. Defaults to 'auto'.
+ * @returns Set of token strings.
+ */
+export function tokenize(text: string, language?: 'auto' | 'en' | 'zh'): Set<string> {
+  const lang = language ?? 'auto';
+
+  if (lang === 'en') return tokenizeEnglish(text);
+  if (lang === 'zh') return tokenizeChinese(text);
+
+  // auto-detect
+  const detected = detectLanguage(text);
+  if (detected === 'en') return tokenizeEnglish(text);
+  if (detected === 'zh') return tokenizeChinese(text);
+
+  // mixed: union of both
+  const enTokens = tokenizeEnglish(text);
+  const zhTokens = tokenizeChinese(text);
+  return new Set([...enTokens, ...zhTokens]);
+}

package/src/validation/types.ts

@@ -0,0 +1,47 @@
+export type ValidationLevel = 'ERROR' | 'WARNING' | 'INFO';
+
+export interface ValidationIssue {
+  level: ValidationLevel;
+  path: string;
+  message: string;
+  line?: number;
+}
+
+export interface ValidationReport {
+  valid: boolean;
+  issues: ValidationIssue[];
+  summary: {
+    errors: number;
+    warnings: number;
+    info: number;
+  };
+}
+
+export type VerificationDimension = 'Completeness' | 'Correctness' | 'Coherence';
+export type VerificationStatus = 'PASS' | 'FAIL' | 'WARN';
+
+export interface VerificationFinding {
+  level: 'CRITICAL' | 'IMPORTANT' | 'INFO';
+  dimension: VerificationDimension;
+  message: string;
+}
+
+export interface VerificationReport {
+  dimensions: {
+    name: VerificationDimension;
+    status: VerificationStatus;
+    findings: VerificationFinding[];
+  }[];
+  verdict: 'PASS' | 'CONDITIONAL' | 'FAIL';
+}
+
+export interface SyncConflict {
+  requirement: string;
+  spec: string;
+  changes: string[];
+}
+
+export interface ConflictReport {
+  hasConflicts: boolean;
+  conflicts: SyncConflict[];
+}