pi-harness-runtime 0.9.4 → 0.9.6

package/packages/doc-generator/src/detector.ts

@@ -0,0 +1,113 @@
+/**
+ * Doc Generator — Project Detection (RFC-0014)
+ */
+
+import type { ProjectType, ProjectDetection } from "./types.js";
+
+const SIGNALS: Record<
+	ProjectType,
+	Array<{ pattern: RegExp; weight: number }>
+> = {
+	frappe_erpnext: [
+		{ pattern: /frappe-bench|hooks\.py/, weight: 0.3 },
+		{ pattern: /doctype[/\\]/, weight: 0.4 },
+		{ pattern: /\bapps\/[^/]+\/[^/]+\.py\b/, weight: 0.2 },
+	],
+	frappe_spa: [
+		{ pattern: /frappe-bench\/apps\/[^/]+\/frontend/, weight: 0.4 },
+		{ pattern: /vite\.config\./, weight: 0.3 },
+		{ pattern: /frappe\.call|frappe\.ui\./, weight: 0.3 },
+	],
+	nextjs: [
+		{ pattern: /next\.config\./, weight: 0.4 },
+		{ pattern: /\/(app|pages)\/[^/]+\.(tsx|jsx|ts|js)/, weight: 0.3 },
+		{ pattern: /"next"|'next'/, weight: 0.2 },
+	],
+	react_vite: [
+		{ pattern: /vite\.config\.(ts|js|mjs)/, weight: 0.4 },
+		{ pattern: /src\/main\.(tsx|jsx)/, weight: 0.3 },
+		{ pattern: /index\.html/, weight: 0.2 },
+	],
+	django: [
+		{ pattern: /manage\.py/, weight: 0.4 },
+		{ pattern: /settings\.py/, weight: 0.3 },
+		{ pattern: /models?\.py/, weight: 0.2 },
+	],
+	laravel: [
+		{ pattern: /artisan/, weight: 0.4 },
+		{ pattern: /database\/seeders/, weight: 0.3 },
+		{ pattern: /composer\.json/, weight: 0.2 },
+	],
+	generic_web: [
+		{ pattern: /package\.json/, weight: 0.2 },
+		{ pattern: /index\.(html?|js|ts)/, weight: 0.2 },
+	],
+	unknown: [],
+};
+
+const SEED_STRATEGIES: Record<ProjectType, string> = {
+	frappe_erpnext: "frappe_doc_insert",
+	frappe_spa: "frappe_fixtures",
+	nextjs: "nextjs_factory",
+	react_vite: "vite_seed",
+	django: "django_migrations",
+	laravel: "laravel_seeders",
+	generic_web: "generic_faker",
+	unknown: "generic_faker",
+};
+
+const E2E_STRATEGIES: Record<ProjectType, string> = {
+	frappe_erpnext: "bench_site_browser_flow",
+	frappe_spa: "api_plus_spa_flow",
+	nextjs: "nextjs_dev_server_flow",
+	react_vite: "vite_dev_server_flow",
+	django: "django_test_client_flow",
+	laravel: "laravel_dusk_flow",
+	generic_web: "playwright_generic_flow",
+	unknown: "playwright_generic_flow",
+};
+
+/** Detect project type from a list of file paths. */
+export function detectProjectType(filePaths: string[]): ProjectDetection {
+	const scores: Record<ProjectType, number> = {
+		frappe_erpnext: 0,
+		frappe_spa: 0,
+		nextjs: 0,
+		react_vite: 0,
+		django: 0,
+		laravel: 0,
+		generic_web: 0,
+		unknown: 0,
+	};
+	const signals: string[] = [];
+
+	for (const filePath of filePaths) {
+		for (const [pType, pSignals] of Object.entries(SIGNALS) as [
+			ProjectType,
+			typeof SIGNALS.frappe_erpnext,
+		][]) {
+			for (const { pattern, weight } of pSignals) {
+				if (pattern.test(filePath)) {
+					scores[pType] += weight;
+					signals.push(filePath);
+				}
+			}
+		}
+	}
+
+	const best = Object.entries(scores).sort((a, b) => b[1] - a[1])[0];
+	const projectType = best[1] > 0 ? (best[0] as ProjectType) : "unknown";
+
+	return {
+		projectType,
+		confidence: Math.min(best[1], 1),
+		signals: [...new Set(signals)],
+		recommendedSeedStrategy: SEED_STRATEGIES[projectType],
+		recommendedE2EStrategy: E2E_STRATEGIES[projectType],
+	};
+}
+
+/** Parse signals from a directory listing. */
+export function parseSignals(entries: string[]): string[] {
+	return entries.filter((e) => /[./]/.test(e));
+}

package/packages/doc-generator/src/docs.ts

@@ -0,0 +1,158 @@
+/**
+ * Doc Generator — Documentation Generation (RFC-0014)
+ */
+
+import type {
+	DetectedSymbol,
+	GeneratedDocs,
+	DocSection,
+	SourceFile,
+} from "./types.js";
+import { detectProjectType } from "./detector.js";
+
+/** Detect exported symbols in a source file. */
+export function detectSymbols(source: SourceFile): DetectedSymbol[] {
+	const symbols: DetectedSymbol[] = [];
+	const lines = source.content.split("\n");
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const trimmed = line.trim();
+
+		const fnMatch = trimmed.match(
+			/^(?:async\s+)?(?:export\s+)?function\s+(\w+)\s*\(([^)]*)\)/,
+		);
+		if (fnMatch) {
+			symbols.push({
+				name: fnMatch[1],
+				kind: "function",
+				signature: `${fnMatch[1]}(${fnMatch[2]})`,
+				docComment: getDocComment(lines, i),
+				file: source.path,
+				line: i + 1,
+			});
+		}
+
+		const classMatch = trimmed.match(/^(?:export\s+)?class\s+(\w+)/);
+		if (classMatch) {
+			symbols.push({
+				name: classMatch[1],
+				kind: "class",
+				docComment: getDocComment(lines, i),
+				file: source.path,
+				line: i + 1,
+			});
+		}
+
+		const ifaceMatch = trimmed.match(/^export\s+interface\s+(\w+)/);
+		if (ifaceMatch) {
+			symbols.push({
+				name: ifaceMatch[1],
+				kind: "interface",
+				docComment: getDocComment(lines, i),
+				file: source.path,
+				line: i + 1,
+			});
+		}
+
+		const typeMatch = trimmed.match(/^export\s+type\s+(\w+)/);
+		if (typeMatch) {
+			symbols.push({
+				name: typeMatch[1],
+				kind: "type",
+				docComment: getDocComment(lines, i),
+				file: source.path,
+				line: i + 1,
+			});
+		}
+
+		const constMatch = trimmed.match(/^export\s+const\s+(\w+)/);
+		if (constMatch) {
+			symbols.push({
+				name: constMatch[1],
+				kind: "constant",
+				docComment: getDocComment(lines, i),
+				file: source.path,
+				line: i + 1,
+			});
+		}
+	}
+
+	return symbols;
+}
+
+function getDocComment(lines: string[], index: number): string | undefined {
+	for (let j = Math.max(0, index - 5); j < index; j++) {
+		const prev = lines[j].trim();
+		if (prev.startsWith("/**") || prev.startsWith("///")) {
+			const endIdx = lines
+				.slice(j + 1, index)
+				.findIndex((l) => l.includes("*/"));
+			if (endIdx >= 0) {
+				const doc = lines.slice(j, j + endIdx + 2).join("\n");
+				return doc.replace(/\/\*\*|\*\/|[\s*]/g, "").trim();
+			}
+		}
+	}
+	return undefined;
+}
+
+function summarizeSymbols(symbols: DetectedSymbol[]): string {
+	const counts: Record<string, number> = {};
+	for (const s of symbols) counts[s.kind] = (counts[s.kind] ?? 0) + 1;
+	return Object.entries(counts)
+		.map(([k, v]) => `${v} ${k}(s)`)
+		.join(", ");
+}
+
+function formatSymbol(s: DetectedSymbol): string {
+	const sig = s.signature ? `${s.name}${s.signature}` : s.name;
+	return `- ${sig} (${s.file}:${s.line})`;
+}
+
+/** Generate documentation for a list of source files. */
+export function generateDocs(
+	sources: SourceFile[],
+	projectSignals: string[],
+): GeneratedDocs {
+	const detection = detectProjectType(projectSignals);
+	const allSymbols = sources.flatMap(detectSymbols);
+
+	const sections: DocSection[] = [
+		{
+			heading: "Overview",
+			level: 1,
+			content: `Project type: ${detection.projectType} (confidence: ${(detection.confidence * 100).toFixed(0)}%)\nSignals: ${detection.signals.join(", ") || "none"}`,
+		},
+		{
+			heading: "Exports",
+			level: 1,
+			content: `Total exports: ${allSymbols.length}\n${summarizeSymbols(allSymbols)}`,
+		},
+		{
+			heading: "Functions",
+			level: 2,
+			content:
+				allSymbols
+					.filter((s) => s.kind === "function")
+					.map(formatSymbol)
+					.join("\n") || "No functions found.",
+		},
+		{
+			heading: "Types & Interfaces",
+			level: 2,
+			content:
+				allSymbols
+					.filter((s) => s.kind === "type" || s.kind === "interface")
+					.map(formatSymbol)
+					.join("\n") || "No types found.",
+		},
+	];
+
+	return {
+		title: "Generated Documentation",
+		sections,
+		symbols: allSymbols,
+		projectType: detection.projectType,
+	};
+}

package/packages/doc-generator/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Doc Generator — Main Entry (RFC-0014)
+ */
+
+export { detectProjectType, parseSignals } from "./detector.js";
+export { detectSymbols, generateDocs } from "./docs.js";
+export type * from "./types.js";

package/packages/doc-generator/src/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Doc Generator Types (RFC-0014)
+ */
+
+export interface SourceFile {
+	path: string;
+	content: string;
+	language: string;
+}
+
+export type ProjectType =
+	| "frappe_erpnext"
+	| "frappe_spa"
+	| "nextjs"
+	| "react_vite"
+	| "django"
+	| "laravel"
+	| "generic_web"
+	| "unknown";
+
+export interface ProjectDetection {
+	projectType: ProjectType;
+	confidence: number;
+	signals: string[];
+	recommendedSeedStrategy: string;
+	recommendedE2EStrategy: string;
+}
+
+export interface DetectedSymbol {
+	name: string;
+	kind: "function" | "class" | "interface" | "type" | "constant" | "variable";
+	signature?: string;
+	docComment?: string;
+	file: string;
+	line: number;
+}
+
+export interface GeneratedDocs {
+	title: string;
+	sections: DocSection[];
+	symbols: DetectedSymbol[];
+	projectType: ProjectType;
+}
+
+export interface DocSection {
+	heading: string;
+	level: 1 | 2 | 3;
+	content: string;
+}
+
+export type SeedStrategy =
+	| "frappe_doc_insert"
+	| "frappe_fixtures"
+	| "nextjs_factory"
+	| "vite_seed"
+	| "django_migrations"
+	| "laravel_seeders"
+	| "generic_faker";

package/packages/doc-generator/test/docs.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Doc Generator Tests (RFC-0014)
+ */
+
+import { describe, it, expect } from "bun:test";
+import {
+	detectProjectType,
+	parseSignals,
+	detectSymbols,
+	generateDocs,
+} from "../src/index.js";
+import type { SourceFile } from "../src/index.js";
+
+const src = (content: string, path = "src/utils.ts"): SourceFile => ({
+	path,
+	content,
+	language: "typescript",
+});
+
+describe("detectProjectType", () => {
+	it("detects Frappe/ERPNext", () => {
+		const signals = ["frappe-bench/apps/myapp/hooks.py", "doctype/CRM"];
+		const result = detectProjectType(signals);
+		expect(result.projectType).toBe("frappe_erpnext");
+		expect(result.signals).toContain("frappe-bench/apps/myapp/hooks.py");
+	});
+
+	it("detects Next.js", () => {
+		const signals = ["next.config.js", "app/layout.tsx", "pages/index.ts"];
+		const result = detectProjectType(signals);
+		expect(result.projectType).toBe("nextjs");
+	});
+
+	it("detects React/Vite", () => {
+		const signals = ["vite.config.ts", "src/main.tsx", "index.html"];
+		const result = detectProjectType(signals);
+		expect(result.projectType).toBe("react_vite");
+	});
+
+	it("detects Django", () => {
+		const signals = ["manage.py", "settings.py"];
+		const result = detectProjectType(signals);
+		expect(result.projectType).toBe("django");
+	});
+
+	it("detects Laravel", () => {
+		const signals = ["artisan", "database/seeders/UserSeeder.php"];
+		const result = detectProjectType(signals);
+		expect(result.projectType).toBe("laravel");
+	});
+
+	it("returns unknown for empty signals", () => {
+		const result = detectProjectType([]);
+		expect(result.projectType).toBe("unknown");
+		expect(result.confidence).toBe(0);
+	});
+
+	it("returns generic_web for package.json", () => {
+		const result = detectProjectType(["package.json", "index.js"]);
+		expect(result.projectType).toBe("generic_web");
+	});
+
+	it("includes recommended seed strategy", () => {
+		const result = detectProjectType(["manage.py"]);
+		expect(result.recommendedSeedStrategy).toBe("django_migrations");
+	});
+
+	it("includes recommended e2e strategy", () => {
+		const result = detectProjectType(["next.config.js"]);
+		expect(result.recommendedE2EStrategy).toBe("nextjs_dev_server_flow");
+	});
+
+	it("confidence is 0-1", () => {
+		const result = detectProjectType(["doctype/CRM"]);
+		expect(result.confidence).toBeGreaterThanOrEqual(0);
+		expect(result.confidence).toBeLessThanOrEqual(1);
+	});
+});
+
+describe("parseSignals", () => {
+	it("filters paths with dots or slashes", () => {
+		const entries = ["frappe-bench", "doctype", "README.md", "apps/main.py"];
+		const signals = parseSignals(entries);
+		expect(signals).toContain("README.md");
+		expect(signals).toContain("apps/main.py");
+		expect(signals).not.toContain("doctype");
+	});
+});
+
+describe("detectSymbols", () => {
+	it("detects function declarations", () => {
+		const s = src(
+			"export function add(a: number, b: number): number { return a + b; }",
+		);
+		const symbols = detectSymbols(s);
+		const fn = symbols.find((sym) => sym.kind === "function");
+		expect(fn).toBeDefined();
+		expect(fn!.name).toBe("add");
+		expect(fn!.signature).toContain("add");
+	});
+
+	it("detects async functions", () => {
+		const s = src("async function fetchData(): Promise<string> { return ''; }");
+		const symbols = detectSymbols(s);
+		expect(symbols.some((sym) => sym.kind === "function")).toBe(true);
+	});
+
+	it("detects class declarations", () => {
+		const s = src("export class UserService { }");
+		const symbols = detectSymbols(s);
+		expect(symbols.some((sym) => sym.kind === "class")).toBe(true);
+	});
+
+	it("detects interface declarations", () => {
+		const s = src("export interface Config { port: number; }");
+		const symbols = detectSymbols(s);
+		expect(symbols.some((sym) => sym.kind === "interface")).toBe(true);
+	});
+
+	it("detects type aliases", () => {
+		const s = src("export type ID = string | number;");
+		const symbols = detectSymbols(s);
+		expect(symbols.some((sym) => sym.kind === "type")).toBe(true);
+	});
+
+	it("detects const exports", () => {
+		const s = src("export const MAX_RETRIES = 3;");
+		const symbols = detectSymbols(s);
+		expect(symbols.some((sym) => sym.kind === "constant")).toBe(true);
+	});
+
+	it("includes file and line number", () => {
+		const s = src("function a() {}\nfunction b() {}");
+		const symbols = detectSymbols(s);
+		const b = symbols.find((sym) => sym.name === "b");
+		expect(b!.line).toBe(2);
+	});
+});
+
+describe("generateDocs", () => {
+	it("generates overview section", () => {
+		const sources = [
+			src("export function hello() {}", "src/a.ts"),
+			src("export type Config = {}", "src/b.ts"),
+		];
+		const docs = generateDocs(sources, ["next.config.js"]);
+		expect(docs.sections.some((s) => s.heading === "Overview")).toBe(true);
+		expect(docs.sections.some((s) => s.heading === "Functions")).toBe(true);
+	});
+
+	it("sets project type from signals", () => {
+		const docs = generateDocs([], ["vite.config.ts", "src/main.tsx"]);
+		expect(docs.projectType).toBe("react_vite");
+	});
+
+	it("lists exported symbols", () => {
+		const sources = [src("export function fn() {}")];
+		const docs = generateDocs(sources, []);
+		expect(docs.symbols.length).toBeGreaterThan(0);
+	});
+
+	it("includes exported functions in sections", () => {
+		const sources = [src("export function publicFn() {}")];
+		const docs = generateDocs(sources, []);
+		const fnSection = docs.sections.find((s) => s.heading === "Functions");
+		expect(fnSection!.content).toContain("publicFn");
+	});
+});

package/packages/doc-generator/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "./dist", "rootDir": "./src", "types": ["node"], "lib": ["ES2022"] },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}

package/packages/evaluation-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/evaluation-engine",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "Evaluation engine for pi-harness runtime (RFC-0057)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/evaluation-runner/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Evaluation Runner — Main Entry (RFC-0020)
+ */
+export { EvaluationRunner, exactMatchEvaluator, substringMatchEvaluator, lengthEvaluator } from "./runner.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/evaluation-runner/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9G,mBAAmB,YAAY,CAAC"}

package/packages/evaluation-runner/dist/index.js

@@ -0,0 +1,5 @@
+/**
+ * Evaluation Runner — Main Entry (RFC-0020)
+ */
+export { EvaluationRunner, exactMatchEvaluator, substringMatchEvaluator, lengthEvaluator } from "./runner.js";
+//# sourceMappingURL=index.js.map

package/packages/evaluation-runner/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/packages/evaluation-runner/dist/runner.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Evaluation Runner — Core (RFC-0020)
+ */
+import type { EvaluationConfig, EvaluationInput, EvaluatorFn, EvaluationReport, EvaluationSuite } from "./types.js";
+export declare class EvaluationRunner {
+    private evaluators;
+    private config;
+    constructor(config?: EvaluationConfig);
+    registerEvaluator(name: string, fn: EvaluatorFn): void;
+    runSuite(suite: EvaluationSuite, execute: (input: EvaluationInput) => Promise<string>): Promise<EvaluationReport>;
+    private runCase;
+    listEvaluators(): string[];
+}
+export declare const exactMatchEvaluator: EvaluatorFn;
+export declare const substringMatchEvaluator: EvaluatorFn;
+export declare const lengthEvaluator: EvaluatorFn;
+//# sourceMappingURL=runner.d.ts.map

package/packages/evaluation-runner/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAEX,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,gBAAgB,EAEhB,eAAe,EACf,MAAM,YAAY,CAAC;AAOpB,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,MAAM,CAA6B;IAE3C,YAAY,MAAM,GAAE,gBAAqB,EAMxC;IAED,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI,CAErD;IAEK,QAAQ,CACb,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,GAClD,OAAO,CAAC,gBAAgB,CAAC,CAsC3B;YAEa,OAAO;IA6DrB,cAAc,IAAI,MAAM,EAAE,CAEzB;CACD;AAGD,eAAO,MAAM,mBAAmB,EAAE,WASjC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,WAUrC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAa7B,CAAC"}