@mainahq/core 0.2.0

package/src/features/__tests__/numbering.test.ts

@@ -0,0 +1,319 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { DesignChoices } from "../numbering";
+import {
+	createFeatureDir,
+	getNextFeatureNumber,
+	scaffoldFeature,
+	scaffoldFeatureWithContext,
+} from "../numbering";
+
+function makeTmpDir(): string {
+	const dir = join(
+		tmpdir(),
+		`maina-features-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+describe("getNextFeatureNumber", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = makeTmpDir();
+	});
+
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	test("empty dir returns '001'", async () => {
+		const featuresDir = join(tmpDir, ".maina", "features");
+		mkdirSync(featuresDir, { recursive: true });
+		const result = await getNextFeatureNumber(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value).toBe("001");
+		}
+	});
+
+	test("existing 001, 002 returns '003'", async () => {
+		const featuresDir = join(tmpDir, ".maina", "features");
+		mkdirSync(join(featuresDir, "001-first-feature"), { recursive: true });
+		mkdirSync(join(featuresDir, "002-second-feature"), { recursive: true });
+		const result = await getNextFeatureNumber(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value).toBe("003");
+		}
+	});
+
+	test("non-sequential (001, 003) returns '004'", async () => {
+		const featuresDir = join(tmpDir, ".maina", "features");
+		mkdirSync(join(featuresDir, "001-first"), { recursive: true });
+		mkdirSync(join(featuresDir, "003-third"), { recursive: true });
+		const result = await getNextFeatureNumber(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value).toBe("004");
+		}
+	});
+
+	test("no .maina/features dir yet creates it and returns '001'", async () => {
+		// tmpDir exists but has no .maina/features
+		const result = await getNextFeatureNumber(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value).toBe("001");
+		}
+		expect(existsSync(join(tmpDir, ".maina", "features"))).toBe(true);
+	});
+
+	test("ignores non-directory entries", async () => {
+		const featuresDir = join(tmpDir, ".maina", "features");
+		mkdirSync(featuresDir, { recursive: true });
+		mkdirSync(join(featuresDir, "001-first"), { recursive: true });
+		// Create a file that looks like a feature but isn't a directory
+		Bun.write(join(featuresDir, "002-not-a-dir.md"), "just a file");
+		const result = await getNextFeatureNumber(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value).toBe("002");
+		}
+	});
+
+	test("ignores directories without numeric prefix", async () => {
+		const featuresDir = join(tmpDir, ".maina", "features");
+		mkdirSync(featuresDir, { recursive: true });
+		mkdirSync(join(featuresDir, "001-first"), { recursive: true });
+		mkdirSync(join(featuresDir, "not-numbered"), { recursive: true });
+		const result = await getNextFeatureNumber(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value).toBe("002");
+		}
+	});
+});
+
+describe("createFeatureDir", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = makeTmpDir();
+		mkdirSync(join(tmpDir, ".maina", "features"), { recursive: true });
+	});
+
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	test("creates correct directory structure", async () => {
+		const result = await createFeatureDir(tmpDir, "001", "my-feature");
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(existsSync(result.value)).toBe(true);
+		}
+	});
+
+	test("returns full path", async () => {
+		const result = await createFeatureDir(tmpDir, "001", "my-feature");
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			const expected = join(tmpDir, ".maina", "features", "001-my-feature");
+			expect(result.value).toBe(expected);
+		}
+	});
+
+	test("handles kebab-case conversion from spaces", async () => {
+		const result = await createFeatureDir(tmpDir, "002", "My Cool Feature");
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value).toContain("002-my-cool-feature");
+			expect(existsSync(result.value)).toBe(true);
+		}
+	});
+
+	test("handles kebab-case conversion from camelCase", async () => {
+		const result = await createFeatureDir(tmpDir, "003", "myCoolFeature");
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value).toContain("003-my-cool-feature");
+			expect(existsSync(result.value)).toBe(true);
+		}
+	});
+
+	test("handles kebab-case conversion from PascalCase", async () => {
+		const result = await createFeatureDir(tmpDir, "004", "MyCoolFeature");
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value).toContain("004-my-cool-feature");
+			expect(existsSync(result.value)).toBe(true);
+		}
+	});
+
+	test("returns error if directory already exists", async () => {
+		const dir = join(tmpDir, ".maina", "features", "001-my-feature");
+		mkdirSync(dir, { recursive: true });
+		const result = await createFeatureDir(tmpDir, "001", "my-feature");
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toContain("already exists");
+		}
+	});
+});
+
+describe("scaffoldFeature", () => {
+	let tmpDir: string;
+	let featureDir: string;
+
+	beforeEach(() => {
+		tmpDir = makeTmpDir();
+		featureDir = join(tmpDir, ".maina", "features", "001-test-feature");
+		mkdirSync(featureDir, { recursive: true });
+	});
+
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	test("creates spec.md, plan.md, tasks.md", async () => {
+		const result = await scaffoldFeature(featureDir);
+		expect(result.ok).toBe(true);
+		expect(existsSync(join(featureDir, "spec.md"))).toBe(true);
+		expect(existsSync(join(featureDir, "plan.md"))).toBe(true);
+		expect(existsSync(join(featureDir, "tasks.md"))).toBe(true);
+	});
+
+	test("spec.md contains WHAT/WHY sections only (no HOW)", async () => {
+		await scaffoldFeature(featureDir);
+		const content = readFileSync(join(featureDir, "spec.md"), "utf-8");
+		// WHAT/WHY sections
+		expect(content).toContain("Feature:");
+		expect(content).toContain("User Stories");
+		expect(content).toContain("Success Criteria");
+		expect(content).toContain("Problem Statement");
+		expect(content).toContain("Out of Scope");
+		// Must NOT contain HOW sections
+		expect(content).not.toContain("## Architecture");
+		expect(content).not.toContain("## Tasks");
+	});
+
+	test("plan.md contains HOW sections only", async () => {
+		await scaffoldFeature(featureDir);
+		const content = readFileSync(join(featureDir, "plan.md"), "utf-8");
+		// HOW sections
+		expect(content).toContain("Architecture");
+		expect(content).toContain("Tasks");
+		expect(content).toContain("Failure Modes");
+		expect(content).toContain("Testing Strategy");
+		// Must NOT contain WHAT/WHY sections
+		expect(content).not.toContain("User Stories");
+		expect(content).not.toContain("Success Criteria");
+	});
+
+	test("all files contain [NEEDS CLARIFICATION] marker", async () => {
+		await scaffoldFeature(featureDir);
+		const spec = readFileSync(join(featureDir, "spec.md"), "utf-8");
+		const plan = readFileSync(join(featureDir, "plan.md"), "utf-8");
+		const tasks = readFileSync(join(featureDir, "tasks.md"), "utf-8");
+		expect(spec).toContain("[NEEDS CLARIFICATION]");
+		expect(plan).toContain("[NEEDS CLARIFICATION]");
+		expect(tasks).toContain("[NEEDS CLARIFICATION]");
+	});
+
+	test("returns error if featureDir does not exist", async () => {
+		const badDir = join(tmpDir, "nonexistent");
+		const result = await scaffoldFeature(badDir);
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toContain("does not exist");
+		}
+	});
+});
+
+describe("scaffoldFeatureWithContext", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = makeTmpDir();
+	});
+
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	test("creates enriched spec.md with description and tradeoffs", async () => {
+		mkdirSync(tmpDir, { recursive: true });
+		const choices: DesignChoices = {
+			description: "User authentication system with OAuth support",
+			pattern: "service-layer",
+			libraries: ["passport.js", "jsonwebtoken"],
+			tradeoffs: ["Chose simplicity over enterprise features for MVP"],
+			clarifications: [
+				{ question: "Support OAuth?", answer: "Yes, Google and GitHub" },
+			],
+		};
+
+		const result = await scaffoldFeatureWithContext(
+			tmpDir,
+			"user-auth",
+			choices,
+		);
+		expect(result.ok).toBe(true);
+
+		const spec = readFileSync(join(tmpDir, "spec.md"), "utf-8");
+		expect(spec).toContain("User authentication system with OAuth support");
+		expect(spec).toContain("Chose simplicity over enterprise features for MVP");
+		expect(spec).toContain("Support OAuth?");
+		expect(spec).toContain("Yes, Google and GitHub");
+		// Spec should NOT contain implementation details (HOW)
+		expect(spec).not.toContain("service-layer");
+		expect(spec).not.toContain("passport.js");
+	});
+
+	test("creates enriched plan.md with pattern and libraries", async () => {
+		mkdirSync(tmpDir, { recursive: true });
+		const choices: DesignChoices = {
+			pattern: "repository",
+			libraries: ["drizzle", "zod"],
+		};
+
+		const result = await scaffoldFeatureWithContext(
+			tmpDir,
+			"data-layer",
+			choices,
+		);
+		expect(result.ok).toBe(true);
+
+		const plan = readFileSync(join(tmpDir, "plan.md"), "utf-8");
+		expect(plan).toContain("repository");
+		expect(plan).toContain("drizzle");
+		expect(plan).toContain("zod");
+		// Plan should NOT contain WHAT/WHY
+		expect(plan).toContain("HOW only");
+	});
+
+	test("falls back to generic markers when choices are empty", async () => {
+		mkdirSync(tmpDir, { recursive: true });
+		const choices: DesignChoices = {};
+
+		const result = await scaffoldFeatureWithContext(tmpDir, "simple", choices);
+		expect(result.ok).toBe(true);
+
+		const plan = readFileSync(join(tmpDir, "plan.md"), "utf-8");
+		expect(plan).toContain("[NEEDS CLARIFICATION]");
+	});
+
+	test("creates tasks.md with standard template", async () => {
+		mkdirSync(tmpDir, { recursive: true });
+		const choices: DesignChoices = { description: "Test feature" };
+
+		await scaffoldFeatureWithContext(tmpDir, "test", choices);
+
+		const tasks = readFileSync(join(tmpDir, "tasks.md"), "utf-8");
+		expect(tasks).toContain("Task Breakdown");
+	});
+});

package/src/features/__tests__/quality.test.ts

@@ -0,0 +1,295 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { scoreSpec } from "../quality";
+
+function makeTmpDir(): string {
+	const dir = join(
+		tmpdir(),
+		`maina-quality-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+describe("scoreSpec", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = makeTmpDir();
+	});
+
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	// --- Good spec with measurable verbs → score > 70 ---
+	test("good spec with measurable verbs scores > 70", () => {
+		const specPath = join(tmpDir, "spec.md");
+		writeFileSync(
+			specPath,
+			`# Feature: Token Budget
+
+## Problem Statement
+The context engine needs a configurable token budget.
+
+## User Stories
+- As a developer, I want to configure token budgets per command.
+
+## Success Criteria
+- \`calculateTokens\` returns the correct token count for a given input
+- \`assembleContext\` validates that tokens stay within budget of 4000
+- \`parseConfig\` reads the \`.maina/config.json\` file and returns parsed settings
+- The budget engine computes utilization as \`tokens / budget\`
+- \`rejectOverBudget\` throws when context exceeds the configured limit
+
+## Scope
+- In scope: token counting, budget configuration
+- Out of scope: streaming, multi-model
+
+## Design Decisions
+- Use tree-sitter for AST parsing
+`,
+		);
+
+		const result = scoreSpec(specPath);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		expect(result.value.overall).toBeGreaterThan(70);
+	});
+
+	// --- Spec with vague verbs → measurability < 50 ---
+	test("spec with vague verbs has measurability < 50", () => {
+		const specPath = join(tmpDir, "spec.md");
+		writeFileSync(
+			specPath,
+			`# Feature: Auth
+
+## Problem Statement
+We need auth.
+
+## User Stories
+- As a user, I want to log in.
+
+## Success Criteria
+- The system handles user authentication
+- The module manages session state
+- The service supports OAuth providers
+- The component processes login requests
+- The layer deals with token refresh
+
+## Scope
+- Auth
+
+## Design Decisions
+- TBD
+`,
+		);
+
+		const result = scoreSpec(specPath);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		expect(result.value.measurability).toBeLessThan(50);
+	});
+
+	// --- Spec with weasel words → ambiguity < 50 ---
+	test("spec with weasel words has ambiguity < 50", () => {
+		const specPath = join(tmpDir, "spec.md");
+		writeFileSync(
+			specPath,
+			`# Feature: Maybe Auth
+
+## Problem Statement
+This might possibly solve some authentication issues.
+
+## User Stories
+- As a user, I should possibly be able to log in maybe.
+
+## Success Criteria
+- The system should maybe validate credentials
+- Various appropriate methods could be used
+- Some users might possibly need sessions
+- It should probably handle various edge cases
+- The module could possibly support some providers
+- Maybe it should also handle appropriate errors
+
+## Scope
+- Various things
+
+## Design Decisions
+- Possibly use some appropriate library
+`,
+		);
+
+		const result = scoreSpec(specPath);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		expect(result.value.ambiguity).toBeLessThan(50);
+	});
+
+	// --- Spec with all sections → completeness = 100 ---
+	test("spec with all required sections has completeness 100", () => {
+		const specPath = join(tmpDir, "spec.md");
+		writeFileSync(
+			specPath,
+			`# Feature: Complete
+
+## Problem Statement
+Something.
+
+## User Stories
+- Story.
+
+## Success Criteria
+- Criterion.
+
+## Scope
+- Scope.
+
+## Design Decisions
+- Decision.
+`,
+		);
+
+		const result = scoreSpec(specPath);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		expect(result.value.completeness).toBe(100);
+	});
+
+	// --- Spec missing sections → completeness < 100 ---
+	test("spec missing sections has completeness < 100", () => {
+		const specPath = join(tmpDir, "spec.md");
+		writeFileSync(
+			specPath,
+			`# Feature: Incomplete
+
+## Problem Statement
+Something.
+
+## Success Criteria
+- Criterion.
+`,
+		);
+
+		const result = scoreSpec(specPath);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		expect(result.value.completeness).toBeLessThan(100);
+	});
+
+	// --- Spec with [NEEDS CLARIFICATION] → completeness penalized ---
+	test("spec with [NEEDS CLARIFICATION] has completeness penalized", () => {
+		const specPath = join(tmpDir, "spec.md");
+		writeFileSync(
+			specPath,
+			`# Feature: Unclear
+
+## Problem Statement
+Something. [NEEDS CLARIFICATION]
+
+## User Stories
+- Story. [NEEDS CLARIFICATION]
+
+## Success Criteria
+- Criterion validates input.
+
+## Scope
+- Scope.
+
+## Design Decisions
+- Decision.
+`,
+		);
+
+		const result = scoreSpec(specPath);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		// All sections present = 100, minus 2 * 10 = 80
+		expect(result.value.completeness).toBe(80);
+	});
+
+	// --- Spec with backtick identifiers → testability high ---
+	test("spec with backtick identifiers has high testability", () => {
+		const specPath = join(tmpDir, "spec.md");
+		writeFileSync(
+			specPath,
+			`# Feature: Testable
+
+## Problem Statement
+Need testable criteria.
+
+## User Stories
+- As a developer, I want clear criteria.
+
+## Success Criteria
+- \`parseInput\` returns a valid AST node
+- The output file is written to \`/tmp/output.json\`
+- The function returns error code 404 when not found
+- \`validateEmail\` rejects strings without @ symbol
+- The response contains exactly 5 items
+
+## Scope
+- Parsing and validation
+
+## Design Decisions
+- Use tree-sitter
+`,
+		);
+
+		const result = scoreSpec(specPath);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		expect(result.value.testability).toBeGreaterThan(70);
+	});
+
+	// --- Empty spec → score 0 ---
+	test("empty spec scores 0", () => {
+		const specPath = join(tmpDir, "spec.md");
+		writeFileSync(specPath, "");
+
+		const result = scoreSpec(specPath);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		expect(result.value.overall).toBe(0);
+	});
+
+	// --- File not found → error Result ---
+	test("file not found returns error Result", () => {
+		const result = scoreSpec(join(tmpDir, "nonexistent.md"));
+		expect(result.ok).toBe(false);
+		if (result.ok) return;
+		expect(result.error).toContain("not found");
+	});
+
+	// --- Details array is populated ---
+	test("details array is populated with human-readable breakdown", () => {
+		const specPath = join(tmpDir, "spec.md");
+		writeFileSync(
+			specPath,
+			`# Feature: Details
+
+## Problem Statement
+Something.
+
+## User Stories
+- Story.
+
+## Success Criteria
+- \`validate\` returns true for valid input
+
+## Scope
+- Scope.
+
+## Design Decisions
+- Decision.
+`,
+		);
+
+		const result = scoreSpec(specPath);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		expect(result.value.details.length).toBeGreaterThan(0);
+	});
+});