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

package/packages/requirement-compiler/dist/types.js

@@ -0,0 +1,129 @@
+/**
+ * Requirement Compiler - Types
+ *
+ * Type definitions for raw and compiled requirements.
+ */
+// ─── SDK Version ────────────────────────────────────────────────────────────
+export const SDK_VERSION = "1.0.0";
+export const DEFAULT_COMPILER_CONFIG = {
+    projectLanguage: "en",
+    autoPromotePreferences: false,
+    allowReversibleAssumptions: true,
+    riskKeywords: {
+        financial: [
+            "payment",
+            "cost",
+            "price",
+            "fee",
+            "charge",
+            "invoice",
+            "tax",
+            "VAT",
+            "value added tax",
+            "ภาษี",
+            "ภาษีมูลค่าเพิ่ม",
+            "เงิน",
+            "บาท",
+        ],
+        privacy: [
+            "personal",
+            "data",
+            "privacy",
+            "GDPR",
+            "PDPA",
+            "consent",
+            "ข้อมูลส่วนบุคคล",
+            "consent",
+        ],
+        authentication: [
+            "auth",
+            "login",
+            "password",
+            "token",
+            "JWT",
+            "OAuth",
+            "session",
+            "เข้าสู่ระบบ",
+        ],
+        authorization: [
+            "permission",
+            "role",
+            "access control",
+            "ACL",
+            "authorize",
+            "สิทธิ์",
+        ],
+        data_migration: [
+            "migration",
+            "import",
+            "export",
+            "convert",
+            "migrate",
+            "ย้ายข้อมูล",
+        ],
+        regulatory: [
+            "compliance",
+            "regulation",
+            "audit",
+            "log",
+            "report",
+            "กฎหมาย",
+            "ระเบียบ",
+        ],
+        destructive_operation: [
+            "delete",
+            "drop",
+            "truncate",
+            "remove",
+            "purge",
+            "destroy",
+            "ลบ",
+        ],
+    },
+    mandatoryKeywords: [
+        "must",
+        "shall",
+        "required",
+        "need to",
+        "have to",
+        "จะต้อง",
+        "ต้อง",
+        "required",
+    ],
+    preferenceKeywords: [
+        "prefer",
+        "should",
+        "could",
+        "might",
+        "suggest",
+        "recommend",
+        "nice to have",
+        "ควร",
+    ],
+};
+// ─── Compiler Errors ──────────────────────────────────────────────────────
+/**
+ * Error codes for requirement compilation failures.
+ * Use this enum-like object for programmatic error checking.
+ */
+export const RequirementCompileErrorCodes = {
+    EMPTY_REQUIREMENT: "EMPTY_REQUIREMENT",
+    IMPOSSIBLE_REQUIREMENT: "IMPOSSIBLE_REQUIREMENT",
+    POLICY_VIOLATION: "POLICY_VIOLATION",
+    UNSUPPORTED_ATTACHMENT: "UNSUPPORTED_ATTACHMENT",
+    UNRESOLVABLE_CONTRADICTION: "UNRESOLVABLE_CONTRADICTION",
+};
+/**
+ * Error thrown during requirement compilation.
+ */
+export class RequirementCompileError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "RequirementCompileError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/packages/requirement-compiler/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,+EAA+E;AAE/E,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AA8ZnC,MAAM,CAAC,MAAM,uBAAuB,GAA8B;IACjE,eAAe,EAAE,IAAI;IACrB,sBAAsB,EAAE,KAAK;IAC7B,0BAA0B,EAAE,IAAI;IAChC,YAAY,EAAE;QACb,SAAS,EAAE;YACV,SAAS;YACT,MAAM;YACN,OAAO;YACP,KAAK;YACL,QAAQ;YACR,SAAS;YACT,KAAK;YACL,KAAK;YACL,iBAAiB;YACjB,MAAM;YACN,iBAAiB;YACjB,MAAM;YACN,KAAK;SACL;QACD,OAAO,EAAE;YACR,UAAU;YACV,MAAM;YACN,SAAS;YACT,MAAM;YACN,MAAM;YACN,SAAS;YACT,iBAAiB;YACjB,SAAS;SACT;QACD,cAAc,EAAE;YACf,MAAM;YACN,OAAO;YACP,UAAU;YACV,OAAO;YACP,KAAK;YACL,OAAO;YACP,SAAS;YACT,aAAa;SACb;QACD,aAAa,EAAE;YACd,YAAY;YACZ,MAAM;YACN,gBAAgB;YAChB,KAAK;YACL,WAAW;YACX,QAAQ;SACR;QACD,cAAc,EAAE;YACf,WAAW;YACX,QAAQ;YACR,QAAQ;YACR,SAAS;YACT,SAAS;YACT,YAAY;SACZ;QACD,UAAU,EAAE;YACX,YAAY;YACZ,YAAY;YACZ,OAAO;YACP,KAAK;YACL,QAAQ;YACR,QAAQ;YACR,SAAS;SACT;QACD,qBAAqB,EAAE;YACtB,QAAQ;YACR,MAAM;YACN,UAAU;YACV,QAAQ;YACR,OAAO;YACP,SAAS;YACT,IAAI;SACJ;KACD;IACD,iBAAiB,EAAE;QAClB,MAAM;QACN,OAAO;QACP,UAAU;QACV,SAAS;QACT,SAAS;QACT,QAAQ;QACR,MAAM;QACN,UAAU;KACV;IACD,kBAAkB,EAAE;QACnB,QAAQ;QACR,QAAQ;QACR,OAAO;QACP,OAAO;QACP,SAAS;QACT,WAAW;QACX,cAAc;QACd,KAAK;KACL;CACD,CAAC;AAiDF,6EAA6E;AAE7E;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC3C,iBAAiB,EAAE,mBAAmB;IACtC,sBAAsB,EAAE,wBAAwB;IAChD,gBAAgB,EAAE,kBAAkB;IACpC,sBAAsB,EAAE,wBAAwB;IAChD,0BAA0B,EAAE,4BAA4B;CAC/C,CAAC;AAKX;;GAEG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAEhC;IAEA;IAHjB,YACiB,IAAiC,EACjD,OAAe,EACC,OAAiC;QAEjD,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAA6B;QAEjC,YAAO,GAAP,OAAO,CAA0B;QAGjD,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACvC,CAAC;CACD"}

package/packages/requirement-compiler/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@pi-harness/requirement-compiler",
+  "version": "0.6.3-beta.13",
+  "description": "Compiles raw requirements into validated CompiledRequirement with ambiguity detection and risk tagging",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@pi-harness/types": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0"
+  }
+}

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

@@ -0,0 +1,302 @@
+/**
+ * Requirement Compiler - Ambiguity Detector
+ *
+ * Detects ambiguities, contradictions, and missing information.
+ */
+
+import type {
+	ClassificationResult,
+	RequirementAmbiguity,
+	RequirementCompilerConfig,
+} from "./types.js";
+
+/**
+ * Vague terms that indicate ambiguity.
+ */
+const VAGUE_TERMS = [
+	"well",
+	"fast",
+	"good",
+	"nice",
+	"modern",
+	"robust",
+	"efficient",
+	"scalable",
+	"secure",
+	"reliable",
+	"appropriate",
+	"reasonable",
+	"some",
+	"few",
+	"many",
+	"several",
+	"lots of",
+	"a bit",
+	"as needed",
+	"when necessary",
+	"properly",
+];
+
+/**
+ * Questions that signal missing actors.
+ */
+const ACTOR_QUESTIONS = [
+	"who should",
+	"who will",
+	"who can",
+	"who is responsible",
+	"which user",
+	"what role",
+];
+
+function detectVagueTerms(
+	statements: {
+		originalText: string;
+		normalizedText: string;
+		sourceRef: { source: string; line?: number; text: string };
+	}[],
+): RequirementAmbiguity[] {
+	const ambiguities: RequirementAmbiguity[] = [];
+	let ambiguityIndex = 0;
+
+	for (const stmt of statements) {
+		const lower = stmt.normalizedText;
+		for (const term of VAGUE_TERMS) {
+			if (lower.includes(term)) {
+				ambiguities.push({
+					id: `ambig-${ambiguityIndex++}`,
+					question: `The term "${term}" is vague. What does "${stmt.originalText.slice(0, 50)}" specifically require?`,
+					blocking: false,
+					affectedGoals: [],
+					evidence: [stmt.sourceRef],
+					category: "vague_term",
+				});
+				break;
+			}
+		}
+	}
+
+	return ambiguities;
+}
+
+function detectMissingActors(
+	statements: {
+		originalText: string;
+		normalizedText: string;
+		sourceRef: { source: string; line?: number; text: string };
+	}[],
+): RequirementAmbiguity[] {
+	const ambiguities: RequirementAmbiguity[] = [];
+	let ambiguityIndex = 0;
+
+	for (const stmt of statements) {
+		const lower = stmt.normalizedText;
+		for (const q of ACTOR_QUESTIONS) {
+			if (lower.includes(q)) {
+				ambiguities.push({
+					id: `ambig-${ambiguityIndex++}`,
+					question: `Actor not specified: ${stmt.originalText}`,
+					blocking: true,
+					affectedGoals: [],
+					evidence: [stmt.sourceRef],
+					category: "missing_actor",
+				});
+				break;
+			}
+		}
+	}
+
+	return ambiguities;
+}
+
+function detectContradictions(
+	goals: {
+		originalText: string;
+		normalizedText: string;
+		sourceRef: { source: string; line?: number; text: string };
+	}[],
+	constraints: {
+		originalText: string;
+		normalizedText: string;
+		sourceRef: { source: string; line?: number; text: string };
+	}[],
+): RequirementAmbiguity[] {
+	const ambiguities: RequirementAmbiguity[] = [];
+	let ambiguityIndex = 0;
+
+	// Normalize for contradiction comparison:
+	// Strips both modal verbs ("must", "shall") AND negation words ("not", "don't", "do not", etc.)
+	// Then collapses whitespace and lowercases.
+	// This lets "allow X" vs "must/do not allow X" both normalize to "allow x".
+	function normalizeForContradiction(text: string): string {
+		// Normalize for comparison: remove negation phrases and modal verbs,
+		// leaving only the core action. This lets "allow X" vs "must/do not allow X"
+		// both normalize to "allow x".
+		let result = text;
+		// Remove negation phrases — "do not", "does not", "must not", "shall not"
+		// These appear with or without leading whitespace (start of sentence)
+		result = result.replace(/(?:^|\s)do(?:\s+not|\s+NOT)\s+/gi, " ");
+		result = result.replace(/(?:^|\s)does(?:\s+not|\s+NOT)\s+/gi, " ");
+		result = result.replace(/(?:^|\s)must\s+not\s+/gi, " ");
+		result = result.replace(/(?:^|\s)shall\s+not\s+/gi, " ");
+		result = result.replace(/(?:^|\s)should\s+not\s+/gi, " ");
+		result = result.replace(/(?:^|\s)will\s+not\s+/gi, " ");
+		// Remove standalone negation words (never, no, don't, cannot)
+		// surrounded by spaces — does NOT match "not" inside "anonymous"
+		result = result.replace(
+			/\s+(?:never|no|don.t|doesn.t|can.t|cannot)\s+/gi,
+			" ",
+		);
+		result = result.replace(/\s+not\s+/gi, " ");
+		// Remove modal verbs
+		result = result.replace(
+			/\s+(?:must|shall|should|will|can|may|might)\s*/gi,
+			" ",
+		);
+		result = result.replace(/\s+/g, " ").trim().toLowerCase();
+		return result;
+	}
+
+	// Check goal vs constraint pairs
+	for (const c of constraints) {
+		const normalizedConstr = normalizeForContradiction(c.normalizedText);
+		for (const g of goals) {
+			const normalizedGoal = normalizeForContradiction(g.normalizedText);
+
+			// Check if goal and constraint oppose each other after normalization
+			if (normalizedGoal === normalizedConstr && normalizedGoal.length > 3) {
+				ambiguities.push({
+					id: `ambig-${ambiguityIndex++}`,
+					question: `Contradiction detected: "${g.originalText}" contradicts "${c.originalText}". Which takes precedence?`,
+					blocking: true,
+					affectedGoals: [],
+					evidence: [g.sourceRef, c.sourceRef],
+					category: "contradiction",
+				});
+			}
+
+			// Check quantity contradictions
+			const qtyMatch = c.normalizedText.match(/\d+/);
+			const goalQtyMatch = g.normalizedText.match(/\d+/);
+			if (
+				qtyMatch &&
+				goalQtyMatch &&
+				qtyMatch[0] !== goalQtyMatch[0] &&
+				c.normalizedText.includes("not")
+			) {
+				ambiguities.push({
+					id: `ambig-${ambiguityIndex++}`,
+					question: `Quantity conflict: constraint says "${c.originalText}" but goal says "${g.originalText}". Clarify the correct value.`,
+					blocking: true,
+					affectedGoals: [],
+					evidence: [g.sourceRef, c.sourceRef],
+					category: "contradiction",
+				});
+			}
+		}
+	}
+
+	// Also check goal vs goal pairs (when both have negation)
+	for (let i = 0; i < goals.length; i++) {
+		for (let j = i + 1; j < goals.length; j++) {
+			const ga = goals[i];
+			const gb = goals[j];
+			const normA = normalizeForContradiction(ga.normalizedText);
+			const normB = normalizeForContradiction(gb.normalizedText);
+			if (normA === normB && normA.length > 3) {
+				// Check that one has negation and the other doesn't
+				const hasNegA = /\bnot\b|don.t|cannot/i.test(ga.normalizedText);
+				const hasNegB = /\bnot\b|don.t|cannot/i.test(gb.normalizedText);
+				if (hasNegA !== hasNegB) {
+					ambiguities.push({
+						id: `ambig-${ambiguityIndex++}`,
+						question: `Contradiction detected: "${ga.originalText}" contradicts "${gb.originalText}". Which takes precedence?`,
+						blocking: true,
+						affectedGoals: [],
+						evidence: [ga.sourceRef, gb.sourceRef],
+						category: "contradiction",
+					});
+				}
+			}
+		}
+	}
+
+	return ambiguities;
+}
+
+function detectScopeUncertainty(
+	statements: {
+		originalText: string;
+		normalizedText: string;
+		sourceRef: { source: string; line?: number; text: string };
+	}[],
+): RequirementAmbiguity[] {
+	const ambiguities: RequirementAmbiguity[] = [];
+	let ambiguityIndex = 0;
+
+	const scopeKeywords = [
+		"maybe",
+		"possibly",
+		"or not",
+		"if possible",
+		"if needed",
+		"optional",
+		"as appropriate",
+	];
+
+	for (const stmt of statements) {
+		const lower = stmt.normalizedText;
+		for (const kw of scopeKeywords) {
+			if (lower.includes(kw)) {
+				ambiguities.push({
+					id: `ambig-${ambiguityIndex++}`,
+					question: `Scope unclear: "${stmt.originalText}" uses "${kw}". Is this required or optional?`,
+					blocking: false,
+					affectedGoals: [],
+					evidence: [stmt.sourceRef],
+					category: "scope_unclear",
+				});
+				break;
+			}
+		}
+	}
+
+	return ambiguities;
+}
+
+/**
+ * Detect ambiguities in classified statements.
+ */
+export function detectAmbiguities(
+	classification: ClassificationResult,
+	_config: RequirementCompilerConfig,
+): RequirementAmbiguity[] {
+	const allStatements = [
+		...classification.goals,
+		...classification.constraints,
+		...classification.preferences,
+		...classification.unknown,
+	];
+
+	const ambiguities: RequirementAmbiguity[] = [
+		...detectVagueTerms(allStatements),
+		// Check all meaningful statements for missing actors, not just goals
+		// (preferences and unknown statements like "Who should..." may also lack actors)
+		...detectMissingActors([
+			...classification.goals,
+			...classification.preferences,
+			...classification.unknown,
+		]),
+		...detectContradictions(classification.goals, classification.constraints),
+		...detectScopeUncertainty(allStatements),
+	];
+
+	// De-duplicate by evidence text
+	const seen = new Set<string>();
+	return ambiguities.filter((a) => {
+		const key = a.question;
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}

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

@@ -0,0 +1,145 @@
+/**
+ * Requirement Compiler - Statement Classifier
+ *
+ * Classifies extracted statements into goals, constraints, preferences, etc.
+ */
+
+import type {
+	ClassificationResult,
+	ExtractedStatement,
+	RequirementCompilerConfig,
+} from "./types.js";
+
+/**
+ * Classify a single statement based on its text content and keywords.
+ */
+function classifyStatement(
+	stmt: ExtractedStatement,
+	config: RequirementCompilerConfig,
+): ExtractedStatement {
+	const lower = stmt.normalizedText;
+
+	// Terminology patterns — Thai-only or bilingual short phrases
+	// MUST check FIRST so Thai text doesn't get captured by keyword patterns
+	if (/[ก-๙]/.test(stmt.originalText) && stmt.originalText.length < 80) {
+		return { ...stmt, kind: "terminology" };
+	}
+
+	const mandKw = config.mandatoryKeywords ?? [];
+	const prefKw = config.preferenceKeywords ?? [];
+
+	// Constraint patterns — negation ANYWHERE in statement
+	// MUST check BEFORE mandatory/preference keyword checks so "must not allow"
+	// -> constraint (not behavior or preference)
+	const hasNegation =
+		/not\s/.test(lower) ||
+		/don.t/.test(lower) ||
+		/\bnever\s/.test(lower) ||
+		/\bavoid\s/.test(lower) ||
+		/cannot\b/.test(lower);
+	if (hasNegation) {
+		return { ...stmt, kind: "constraint" };
+	}
+
+	// Check explicit mandatory markers
+	const isMandatory = mandKw.some((kw) => lower.includes(kw.toLowerCase()));
+	// Check explicit preference markers
+	const isPreference = prefKw.some((kw) => lower.includes(kw.toLowerCase()));
+
+	// Override kind based on explicit markers
+	if (isMandatory && !isPreference) {
+		return { ...stmt, kind: "explicit_behavior" };
+	}
+	if (isPreference && !isMandatory) {
+		return { ...stmt, kind: "preference" };
+	}
+
+	// Pattern-based classification
+	if (
+		lower.startsWith("we will") ||
+		lower.startsWith("the system should") ||
+		lower.startsWith("the app should") ||
+		lower.startsWith("the user should")
+	) {
+		return { ...stmt, kind: "explicit_behavior" };
+	}
+
+	// Goal patterns — action verbs at start of statement
+	const goalPattern =
+		/^(?:the\s+(?:system|app|user)\s+)?(allow|enable|provide|show|display|create|add|support|let|implement|build|use|send|receive|save|load|calculate|process)\b/i;
+	if (goalPattern.test(lower)) {
+		return { ...stmt, kind: "goal" };
+	}
+
+	// Assumption patterns
+	if (
+		/^assume\s/.test(lower) ||
+		lower.includes("assuming that") ||
+		lower.includes("we assume")
+	) {
+		return { ...stmt, kind: "assumption" };
+	}
+
+	// Acceptance criterion patterns (Given/When/Then) — check BEFORE tech suggestions
+	// so "Given...use..." doesn't get classified as implementation_suggestion
+	if (
+		/(?:^|[\s,])given\s/i.test(stmt.originalText) ||
+		/(?:^|[\s,])when\s/i.test(stmt.originalText) ||
+		/(?:^|[\s,])then\s/i.test(stmt.originalText)
+	) {
+		return { ...stmt, kind: "acceptance_criterion" };
+	}
+
+	// Technology suggestion patterns — use word boundary for "use"
+	if (
+		/\buse\b/.test(lower) ||
+		lower.includes("implement with") ||
+		lower.includes("write in") ||
+		lower.includes("build with")
+	) {
+		return { ...stmt, kind: "implementation_suggestion" };
+	}
+
+	return stmt;
+}
+
+/**
+ * Classify all extracted statements.
+ */
+export function classifyStatements(
+	statements: ExtractedStatement[],
+	config: RequirementCompilerConfig,
+): ClassificationResult {
+	const classified = statements.map((s) => classifyStatement(s, config));
+
+	const goals = classified.filter(
+		(s) => s.kind === "goal" || s.kind === "explicit_behavior",
+	);
+	const constraints = classified.filter((s) => s.kind === "constraint");
+	const preferences = classified.filter((s) => s.kind === "preference");
+	const implSuggestions = classified.filter(
+		(s) => s.kind === "implementation_suggestion",
+	);
+	const terminology = classified.filter((s) => s.kind === "terminology");
+	const actors = classified.filter((s) => s.kind === "actor_mention");
+	const acceptance = classified.filter(
+		(s) => s.kind === "acceptance_criterion",
+	);
+	const assumptions = classified.filter((s) => s.kind === "assumption");
+	const unknown = classified.filter(
+		(s) => s.kind === "unknown" && s.id !== "stmt-title",
+	);
+
+	return {
+		statements: classified,
+		goals,
+		constraints,
+		preferences,
+		implementationSuggestions: implSuggestions,
+		terminologyMentions: terminology,
+		actorMentions: actors,
+		acceptanceCriterionStatements: acceptance,
+		assumptions,
+		unknown,
+	};
+}