pi-harness-runtime 1.1.445 → 1.1.447

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

@@ -1,328 +0,0 @@
-/**
- * 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

@@ -1,155 +0,0 @@
-/**
- * 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

@@ -1,36 +0,0 @@
-/**
- * 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

@@ -1,161 +0,0 @@
-/**
- * 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;
-}