pi-harness-runtime 0.5.0 → 0.6.3-beta.13

package/packages/requirement-compiler/src/compiler.ts

@@ -0,0 +1,328 @@
+/**
+ * Requirement Compiler - Main Compiler
+ *
+ * Compiles raw requirements into validated CompiledRequirement.
+ */
+
+import { detectAmbiguities } from "./ambiguity-detector.js";
+import { classifyStatements } from "./classifier.js";
+import { extractStatements } from "./extractor.js";
+import { normalizeAcceptanceCriteria } from "./normalizer.js";
+import { detectRisks } from "./risk-detector.js";
+import {
+	type ClassificationResult,
+	type CompiledRequirement,
+	DEFAULT_COMPILER_CONFIG,
+	type RawRequirement,
+	RequirementCompileError,
+	RequirementCompileErrorCodes,
+	type RequirementCompilerConfig,
+	type RequirementCompilerDependencies,
+} from "./types.js";
+
+/**
+ * Compile a raw requirement into a validated CompiledRequirement.
+ */
+export async function compileRequirement(
+	raw: RawRequirement,
+	deps?: RequirementCompilerDependencies,
+): Promise<CompiledRequirement> {
+	const config: RequirementCompilerConfig = {
+		...DEFAULT_COMPILER_CONFIG,
+		...deps,
+	};
+
+	const clock = deps?.clock ?? (() => new Date());
+
+	// ─── Pre-flight validation ────────────────────────────────────────────────
+
+	if (!raw.text.trim() && !raw.title?.trim()) {
+		throw new RequirementCompileError(
+			RequirementCompileErrorCodes.EMPTY_REQUIREMENT,
+			`Requirement ${raw.id} has no text or title.`,
+			{ requirementId: raw.id },
+		);
+	}
+
+	// ─── Step 1: Extract statements ─────────────────────────────────────────
+
+	const extractor = deps?.extractor ?? { extract: extractStatements };
+	const extractionResult = extractor.extract(raw);
+
+	// ─── Step 2: Classify statements ──────────────────────────────────────
+
+	const classifier = deps?.classifier ?? { classify: classifyStatements };
+	const classification: ClassificationResult = classifier.classify(
+		extractionResult.statements,
+		config,
+	);
+
+	// ─── Step 3: Build goals ─────────────────────────────────────────────────
+
+	const goals = classification.goals.map((stmt, i) => ({
+		id: `goal-${i + 1}`,
+		description: stmt.originalText,
+		sourceRefs: [stmt.sourceRef],
+		priority: undefined as "high" | "medium" | "low" | undefined,
+	}));
+
+	// ─── Step 4: Build constraints ────────────────────────────────────────────
+
+	const constraints = classification.constraints.map((stmt, i) => ({
+		id: `constraint-${i + 1}`,
+		description: stmt.originalText,
+		kind: "mandatory" as const,
+		sourceRefs: [stmt.sourceRef],
+		blocking: true,
+	}));
+
+	// ─── Step 5: Build preferences ───────────────────────────────────────────
+
+	const preferenceConstraints = classification.preferences.map((stmt, i) => ({
+		id: `pref-constraint-${i + 1}`,
+		description: stmt.originalText,
+		kind: "preferable" as const,
+		sourceRefs: [stmt.sourceRef],
+		blocking: false,
+	}));
+
+	// ─── Step 6: Detect ambiguities ───────────────────────────────────────────
+
+	const ambiguityDetector = deps?.ambiguityDetector ?? {
+		detect: detectAmbiguities,
+	};
+	const ambiguities = ambiguityDetector.detect(classification, config);
+
+	// ─── Step 7: Normalize acceptance criteria ────────────────────────────────
+
+	const acceptanceNormalizer = deps?.acceptanceNormalizer ?? {
+		normalize: normalizeAcceptanceCriteria,
+	};
+	const acceptanceCriteria = acceptanceNormalizer.normalize(
+		classification.acceptanceCriterionStatements,
+	);
+
+	// If no explicit acceptance criteria, generate from goals
+	let finalAcceptanceCriteria = acceptanceCriteria;
+	if (acceptanceCriteria.length === 0 && goals.length > 0) {
+		finalAcceptanceCriteria = goals.map((goal, i) => ({
+			id: `AC-${String(i + 1).padStart(3, "0")}`,
+			given: "prerequisites are met",
+			when: "the implementation is complete",
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+			outcome: [`The goal "${goal.description}" is achieved.`] as string[],
+			sourceRefs: goal.sourceRefs,
+			automatable: false,
+		}));
+	}
+
+	// ─── Step 8: Detect risks ─────────────────────────────────────────────────
+
+	const riskDetector = deps?.riskDetector ?? { detect: detectRisks };
+	const riskTags = riskDetector.detect(classification);
+
+	// ─── Step 9: Extract terminology ──────────────────────────────────────────
+
+	const terminology = classification.terminologyMentions.map((stmt) => ({
+		term: stmt.originalText,
+		definition: stmt.normalizedText,
+		language: /[ก-๙]/.test(stmt.originalText) ? "th" : "en",
+		sourceRef: stmt.sourceRef,
+	}));
+
+	// ─── Step 10: Identify actors ──────────────────────────────────────────────
+
+	const actors: CompiledRequirement["actors"] = [];
+	const actorNames = new Set<string>();
+
+	// Scan all meaningful statements for actor mentions
+	const allStmts = [
+		...classification.goals,
+		...classification.constraints,
+		...classification.unknown,
+	];
+	for (const stmt of allStmts) {
+		// Pattern 1: "The [role] can/must/should/is" — catches "The admin", "The user"
+		const pattern1 = stmt.originalText.match(
+			/(?:the|an?|my)\s+([a-z][a-z0-9]*(?:\s+[a-z][a-z0-9]*)?)\s+(?:can|must|should|is|are|has|have|will|does)/gi,
+		);
+		if (pattern1) {
+			for (const match of pattern1) {
+				const name = match
+					.replace(/^(?:the|an?|my)\s+/i, "")
+					.replace(/\s+(?:can|must|should|is|are|has|have|will|does)$/i, "")
+					.trim();
+				// Filter out generic words
+				if (
+					name.length > 1 &&
+					name.length < 30 &&
+					!/^(?:admin|user|system|app|user account|account|any|all|some|each|the)$/i.test(
+						name,
+					)
+				) {
+					const key = name.toLowerCase();
+					if (!actorNames.has(key)) {
+						actorNames.add(key);
+						actors.push({
+							id: `actor-${actors.length + 1}`,
+							name: name.charAt(0).toUpperCase() + name.slice(1),
+							role: name.toLowerCase(),
+							sourceRefs: [stmt.sourceRef],
+						});
+					}
+				}
+			}
+		}
+
+		// Pattern 2: "[role] can" — captures "admin" from "The admin can delete"
+		const pattern2 = stmt.originalText.match(
+			/(?:^|\s)([a-z][a-z0-9]{1,20})\s+can\s+(?:delete|edit|access|view|create|update|remove|manage)/gi,
+		);
+		if (pattern2) {
+			for (const match of pattern2) {
+				const name = match
+					.replace(
+						/\s+can\s+(?:delete|edit|access|view|create|update|remove|manage)$/i,
+						"",
+					)
+					.trim();
+				if (
+					name.length > 1 &&
+					name.length < 30 &&
+					!/^(?:it|this|that|the|a|an|any|all|some|each|their|their own|own)$/i.test(
+						name,
+					)
+				) {
+					const key = name.toLowerCase();
+					if (!actorNames.has(key)) {
+						actorNames.add(key);
+						actors.push({
+							id: `actor-${actors.length + 1}`,
+							name: name.charAt(0).toUpperCase() + name.slice(1),
+							role: name.toLowerCase(),
+							sourceRefs: [stmt.sourceRef],
+						});
+					}
+				}
+			}
+		}
+	}
+
+	// ─── Step 11: Identify non-goals ──────────────────────────────────────────
+
+	const nonGoals: string[] = [];
+	for (const stmt of classification.constraints) {
+		// Explicit "will not" or "should not" statements in non-goal context
+		if (
+			/strip|will not|should not/i.test(stmt.originalText) &&
+			!/stripping|removing/.test(stmt.originalText.toLowerCase())
+		) {
+			nonGoals.push(stmt.originalText);
+		}
+	}
+
+	// ─── Step 12: Build workflows ─────────────────────────────────────────────
+
+	const workflows: CompiledRequirement["workflows"] = [];
+	// Group consecutive statements into workflows heuristically
+	const goalStatements = [
+		...classification.goals,
+		...classification.implementationSuggestions,
+	];
+	if (goalStatements.length >= 2) {
+		workflows.push({
+			id: "workflow-1",
+			name: "Main workflow",
+			steps: goalStatements.map((s) => s.originalText),
+			actors: actors.map((a) => a.name),
+			preconditions: [],
+			outcomes: goals.map((g) => g.description),
+			sourceRefs: goalStatements.flatMap((s) => [s.sourceRef]),
+		});
+	}
+
+	// ─── Step 13: Determine status ────────────────────────────────────────────
+
+	let status: CompiledRequirement["status"] = "ready";
+
+	const blockingAmbiguities = ambiguities.filter((a) => a.blocking);
+
+	if (
+		blockingAmbiguities.length > 0 &&
+		config.allowReversibleAssumptions !== false
+	) {
+		status = "needs_human";
+	} else if (blockingAmbiguities.length > 0) {
+		status = "needs_human";
+	}
+
+	// Check for impossible requirements (contradictions)
+	const contradictions = ambiguities.filter(
+		(a) => a.category === "contradiction",
+	);
+	if (contradictions.length > 0) {
+		throw new RequirementCompileError(
+			RequirementCompileErrorCodes.UNRESOLVABLE_CONTRADICTION,
+			`Requirement ${raw.id} contains unresolvable contradictions.`,
+			{ contradictions: contradictions.map((c) => c.question) },
+		);
+	}
+
+	// Check for empty/vague requirement after processing
+	// A requirement is "empty" if it has no goals, constraints, nonGoals,
+	// AND the text is either blank OR contains only vague/uncertain language
+	const vaguePatterns =
+		/^(maybe|perhaps|possibly|maybe perhaps|perhaps possibly|not sure|not certain|i think|we think|not sure if|uncertain|ambiguous|maybe $|possibly $|\?+$)/i;
+	const isVague = vaguePatterns.test(raw.text.trim());
+	if (
+		goals.length === 0 &&
+		constraints.length === 0 &&
+		nonGoals.length === 0 &&
+		(!raw.text.trim() || isVague)
+	) {
+		throw new RequirementCompileError(
+			RequirementCompileErrorCodes.EMPTY_REQUIREMENT,
+			`Requirement ${raw.id} contains no identifiable goals or constraints.`,
+			{ requirementId: raw.id },
+		);
+	}
+
+	// ─── Step 14: Build source references ────────────────────────────────────
+
+	const sourceRefs = extractionResult.statements.map((s) => s.sourceRef);
+
+	// ─── Step 15: Assemble problem statement ─────────────────────────────────
+
+	const problemStatement =
+		goals.length > 0
+			? goals.map((g) => g.description).join("; ")
+			: (raw.title ?? raw.text.slice(0, 200));
+
+	// ─── Step 16: Build final compiled requirement ────────────────────────────
+
+	const compiled: CompiledRequirement = {
+		id: raw.id,
+		title: raw.title ?? problemStatement.slice(0, 80),
+		problemStatement,
+		goals,
+		nonGoals,
+		constraints: [...constraints, ...preferenceConstraints],
+		actors,
+		workflows,
+		acceptanceCriteria: finalAcceptanceCriteria,
+		assumptions: classification.assumptions.map((stmt, i) => ({
+			id: `assumption-${i + 1}`,
+			description: stmt.originalText,
+			sourceRefs: [stmt.sourceRef],
+			reversible: config.allowReversibleAssumptions !== false,
+		})),
+		ambiguities,
+		terminology,
+		riskTags,
+		sourceRefs,
+		status,
+		compiledAt: clock().toISOString(),
+	};
+
+	return compiled;
+}

package/packages/requirement-compiler/src/extractor.ts

@@ -0,0 +1,155 @@
+/**
+ * Requirement Compiler - Statement Extractor
+ *
+ * Extracts and normalizes statements from raw requirement text.
+ */
+
+import type {
+	ExtractedStatement,
+	ExtractionResult,
+	RawRequirement,
+	SourceReference,
+	StatementKind,
+} from "./types.js";
+
+/**
+ * Split text into sentences, respecting:
+ * - Periods followed by space and capital letter
+ * - Numbered/bulleted lists
+ * - Line breaks
+ */
+function splitSentences(text: string): string[] {
+	// Normalize whitespace
+	const normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+	// Split on sentence boundaries: . ! ? followed by whitespace + capital or newline
+	const sentences = normalized
+		.split(/(?<=[.!?])\s+(?=[A-Z\u0E01-\u0E5B])/gm)
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0);
+	return sentences;
+}
+
+/**
+ * Clean and normalize a statement for comparison.
+ */
+function normalizeStatement(text: string): string {
+	return (
+		text
+			.toLowerCase()
+			// Strip list prefixes: "1. ", "2) ", "• ", "- ", "* "
+			.replace(/^[\s]*\d+[.)]\s*/g, "")
+			.replace(/^[\s\-•*]+/, "")
+			.replace(/\s+/g, " ")
+			.trim()
+	);
+}
+
+/**
+ * Determine the likely statement kind from its text content.
+ */
+function inferKind(text: string): StatementKind {
+	const lower = text.toLowerCase();
+
+	if (
+		lower.includes("prefer") ||
+		lower.includes("should") ||
+		lower.includes("could")
+	) {
+		return "preference";
+	}
+	if (
+		lower.includes("must not") ||
+		lower.includes("shall not") ||
+		lower.includes("cannot")
+	) {
+		return "constraint";
+	}
+	if (
+		lower.includes("must") ||
+		lower.includes("shall") ||
+		lower.includes("require")
+	) {
+		return "explicit_behavior";
+	}
+	if (lower.includes("assume") || lower.includes("we assume")) {
+		return "assumption";
+	}
+	if (lower.includes("we will") || lower.includes("the system")) {
+		return "explicit_behavior";
+	}
+	return "unknown";
+}
+
+/**
+ * Extract all statements from raw requirement text.
+ */
+export function extractStatements(raw: RawRequirement): ExtractionResult {
+	const statements: ExtractedStatement[] = [];
+	const lines: string[] = [];
+
+	// Split by newlines to preserve structure
+	const rawLines = raw.text.split(/\r?\n/).filter((l) => l.trim().length > 0);
+	let lineIndex = 0;
+	let statementIndex = 0;
+
+	for (const line of rawLines) {
+		const trimmedLine = line.trim();
+		if (!trimmedLine) continue;
+
+		lines.push(trimmedLine);
+
+		// Check if this is a numbered item or bullet
+		const numberedMatch = trimmedLine.match(/^(\d+[.)]\s+)(.*)/);
+		const bulletMatch = trimmedLine.match(/^([-•*]\s+)(.*)/);
+
+		let content = trimmedLine;
+		let prefix = "";
+
+		if (numberedMatch) {
+			prefix = numberedMatch[1];
+			content = numberedMatch[2];
+		} else if (bulletMatch) {
+			prefix = bulletMatch[1];
+			content = bulletMatch[2];
+		}
+
+		// Further split by sentences within the line
+		const sentences = splitSentences(content);
+		for (const sentence of sentences) {
+			const fullSentence = prefix + sentence;
+			const sourceRef: SourceReference = {
+				source: raw.source,
+				line: lineIndex + 1,
+				text: fullSentence,
+			};
+
+			const kind = inferKind(fullSentence);
+
+			statements.push({
+				id: `stmt-${statementIndex++}`,
+				kind,
+				originalText: fullSentence,
+				normalizedText: normalizeStatement(fullSentence),
+				sourceRef,
+			});
+		}
+
+		lineIndex++;
+	}
+
+	// Also extract title as a statement if present
+	if (raw.title && raw.title.trim().length > 0) {
+		statements.unshift({
+			id: "stmt-title",
+			kind: "unknown",
+			originalText: raw.title.trim(),
+			normalizedText: normalizeStatement(raw.title.trim()),
+			sourceRef: {
+				source: raw.source,
+				text: raw.title.trim(),
+			},
+		});
+	}
+
+	return { statements, lines };
+}

package/packages/requirement-compiler/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Requirement Compiler - Public Exports
+ *
+ * Compiles raw requirements into validated CompiledRequirement.
+ */
+
+export { detectAmbiguities } from "./ambiguity-detector.js";
+export { classifyStatements } from "./classifier.js";
+export { compileRequirement } from "./compiler.js";
+export { extractStatements } from "./extractor.js";
+export { normalizeAcceptanceCriteria } from "./normalizer.js";
+export { detectRisks } from "./risk-detector.js";
+export {
+	type AcceptanceCriterion,
+	type AcceptanceNormalizer,
+	type AmbiguityDetector,
+	type CompiledRequirement,
+	DEFAULT_COMPILER_CONFIG,
+	// Types
+	type RawRequirement,
+	type RequirementActor,
+	type RequirementAmbiguity,
+	type RequirementAssumption,
+	RequirementCompileError,
+	type RequirementCompileErrorCode,
+	RequirementCompileErrorCodes,
+	type RequirementCompilerConfig,
+	type RequirementCompilerDependencies,
+	type RequirementConstraint,
+	type RequirementGoal,
+	type RequirementWorkflow,
+	type RiskDetector,
+	SDK_VERSION,
+	type StatementClassifier,
+	type StatementExtractor,
+} from "./types.js";

package/packages/requirement-compiler/src/normalizer.ts

@@ -0,0 +1,161 @@
+/**
+ * Requirement Compiler - Acceptance Criteria Normalizer
+ *
+ * Converts acceptance criterion statements into Given/When/Then format.
+ */
+
+import type { AcceptanceCriterion, ExtractedStatement } from "./types.js";
+
+/**
+ * Parse Given/When/Then from a statement if already in that format.
+ */
+function parseGivenWhenThen(text: string): {
+	given?: string;
+	when?: string;
+	outcome?: string[];
+} | null {
+	const givenMatch = text.match(/given\s+([\s\S]+?)(?:,?\s+when|,?\s+then|$)/i);
+	const whenMatch = text.match(/when\s+([\s\S]+?)(?:,?\s+then|$)/i);
+	const thenMatch = text.match(/then\s+([\s\S]+)/i);
+
+	if (!givenMatch && !whenMatch && !thenMatch) return null;
+
+	return {
+		given: givenMatch ? givenMatch[1].trim() : undefined,
+		when: whenMatch ? whenMatch[1].trim() : undefined,
+		outcome: thenMatch
+			? thenMatch[1]
+					.split(/,?\s+and\s+/i)
+					.map((s) => s.trim())
+					.filter(Boolean)
+			: undefined,
+	};
+}
+
+/**
+ * Infer Given/When/Then from natural language.
+ */
+function inferGivenWhenThen(text: string): {
+	given: string;
+	when: string;
+	outcome: string[];
+} {
+	const lower = text.toLowerCase();
+
+	// Extract action verb phrase
+	const actionMatch = lower.match(/(?:should|must|will|can)\s+(.+)/);
+	const action = actionMatch ? actionMatch[1].trim() : text;
+
+	// Infer "when" from context
+	let when = "the user submits the form";
+	if (lower.includes("on click")) {
+		when = "the user clicks the button";
+	} else if (lower.includes("on load")) {
+		when = "the page loads";
+	} else if (lower.includes("on save")) {
+		when = "the user saves";
+	} else if (lower.includes("on submit")) {
+		when = "the user submits";
+	} else if (lower.includes("on delete")) {
+		when = "the user deletes";
+	}
+
+	// Infer "given" preconditions
+	let given = "a valid user is authenticated";
+	if (lower.includes("admin")) {
+		given = "an admin user is authenticated";
+	} else if (lower.includes("guest")) {
+		given = "a guest user is on the page";
+	}
+
+	return {
+		given,
+		when,
+		outcome: [`${action.charAt(0).toUpperCase()}${action.slice(1)}.`],
+	};
+}
+
+/**
+ * Check if a statement is automatable.
+ */
+function isAutomatable(text: string): boolean {
+	const lower = text.toLowerCase();
+	// Statements mentioning UI interactions, API calls, file operations are automatable
+	const automatablePatterns = [
+		"return",
+		"save",
+		"display",
+		"show",
+		"create",
+		"delete",
+		"update",
+		"send",
+		"receive",
+		"validate",
+		"check",
+		"verify",
+		"contain",
+		"visible",
+		"exists",
+		"http",
+		"response",
+		"status",
+	];
+	// Statements about visual design, "feel", "look" are not easily automatable
+	const nonAutomatablePatterns = [
+		"look good",
+		"feel",
+		"user experience",
+		"intuitive",
+		"pleasing",
+		"beautiful",
+	];
+
+	const hasAuto = automatablePatterns.some((p) => lower.includes(p));
+	const hasNonAuto = nonAutomatablePatterns.some((p) => lower.includes(p));
+
+	return hasAuto && !hasNonAuto;
+}
+
+/**
+ * Normalize acceptance criteria statements.
+ */
+export function normalizeAcceptanceCriteria(
+	statements: ExtractedStatement[],
+): AcceptanceCriterion[] {
+	const criteria: AcceptanceCriterion[] = [];
+	let criterionIndex = 0;
+
+	for (const stmt of statements) {
+		const text = stmt.originalText;
+		const parsed = parseGivenWhenThen(text);
+
+		if (parsed) {
+			criteria.push({
+				id: `AC-${String(criterionIndex + 1).padStart(3, "0")}`,
+				given: parsed.given ?? "prerequisites are met",
+				when: parsed.when ?? "the action is performed",
+				outcome: parsed.outcome ?? [text],
+				sourceRefs: [stmt.sourceRef],
+				automatable: isAutomatable(text),
+				originalText: text,
+			});
+		} else {
+			// Infer Given/When/Then from natural language
+			const inferred = inferGivenWhenThen(text);
+			criteria.push({
+				id: `AC-${String(criterionIndex + 1).padStart(3, "0")}`,
+				given: inferred.given,
+				when: inferred.when,
+				outcome: inferred.outcome,
+				sourceRefs: [stmt.sourceRef],
+				automatable: isAutomatable(text),
+				originalText: text,
+			});
+		}
+
+		criterionIndex++;
+	}
+
+	return criteria;
+}