forge-workflow 0.0.1 → 0.0.3

package/lib/dep-guard/task-parser.js

@@ -0,0 +1,318 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { normalizeRepoPath } = require('./path-utils.js');
+
+function ensureTaskFile(taskFile) {
+	if (!taskFile || typeof taskFile !== 'string') {
+		throw new Error('Task file path is required');
+	}
+
+	const absolutePath = path.resolve(taskFile);
+	if (!fs.existsSync(absolutePath)) {
+		throw new Error(`Task file does not exist: ${absolutePath}`);
+	}
+
+	return absolutePath;
+}
+
+function parseFilesLine(value) {
+	if (!value) {
+		return [];
+	}
+
+	return value
+		.split(',')
+		.map((file) => file.replaceAll('`', '').trim())
+		.filter(Boolean);
+}
+
+function flushTask(tasks, currentTask) {
+	if (!currentTask) {
+		return;
+	}
+
+	tasks.push({
+		number: currentTask.number,
+		title: currentTask.title,
+		files: currentTask.files,
+		whatToImplement: currentTask.whatToImplement.trim(),
+		expectedOutput: currentTask.expectedOutput.trim(),
+	});
+}
+
+function isIdentifierStart(character) {
+	return /[A-Za-z_]/.test(character);
+}
+
+function isIdentifierPart(character) {
+	return /\w/.test(character);
+}
+
+function extractSymbols(text) {
+	const symbols = new Set();
+	let searchIndex = 0;
+
+	while (searchIndex < text.length) {
+		const callIndex = text.indexOf('()', searchIndex);
+		if (callIndex === -1) {
+			break;
+		}
+
+		let startIndex = callIndex - 1;
+		while (startIndex >= 0 && isIdentifierPart(text[startIndex])) {
+			startIndex -= 1;
+		}
+
+		const symbol = text.slice(startIndex + 1, callIndex);
+		if (symbol && isIdentifierStart(symbol[0])) {
+			symbols.add(symbol);
+		}
+
+		searchIndex = callIndex + 2;
+	}
+
+	for (const match of text.match(/`([^`\r\n]+)`/g) ?? []) {
+		const token = match.slice(1, -1).trim();
+		if (!token || /[/.\\\s]/.test(token)) {
+			continue;
+		}
+
+		if (/^[A-Za-z_][A-Za-z0-9_-]*$/.test(token)) {
+			symbols.add(token);
+		}
+	}
+
+	return Array.from(symbols);
+}
+
+function detectContractType(symbol, annotation = '') {
+	if (annotation === 'data-format' || annotation === 'command-contract' || annotation === 'return-shape') {
+		return annotation;
+	}
+
+	if (/Schema$|Format$/i.test(symbol)) {
+		return 'data-format';
+	}
+
+	if (/Contract$/i.test(symbol)) {
+		return 'command-contract';
+	}
+
+	if (symbol.includes('-')) {
+		return 'command-contract';
+	}
+
+	if (/Shape$/i.test(symbol)) {
+		return 'return-shape';
+	}
+
+	return 'modified';
+}
+
+function extractContractMentions(text) {
+	const mentions = new Map();
+	for (const symbol of extractSymbols(text)) {
+		mentions.set(symbol, {
+			symbol,
+			annotation: text.includes(`${symbol}()`) ? 'modified' : detectContractType(symbol),
+		});
+	}
+
+	for (const match of text.match(/\b[A-Za-z_]\w*(?:Schema|Format|Contract|Shape)\b/g) ?? []) {
+		if (mentions.has(match)) {
+			continue;
+		}
+
+		mentions.set(match, {
+			symbol: match,
+			annotation: detectContractType(match),
+		});
+	}
+
+	return Array.from(mentions.values());
+}
+
+function escapeRegExp(value) {
+	return value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+
+function resolveRepositoryFile(repositoryRoot, filePath) {
+	if (!repositoryRoot || !filePath || path.isAbsolute(filePath)) {
+		return null;
+	}
+
+	const absoluteRoot = path.resolve(repositoryRoot);
+	const absolutePath = path.resolve(absoluteRoot, filePath);
+	const relativePath = path.relative(absoluteRoot, absolutePath);
+	if (
+		relativePath === ''
+		|| relativePath.startsWith(`..${path.sep}`)
+		|| relativePath === '..'
+		|| path.isAbsolute(relativePath)
+	) {
+		return null;
+	}
+
+	return absolutePath;
+}
+
+function fileContainsSymbol(repositoryRoot, filePath, symbol) {
+	const absolutePath = resolveRepositoryFile(repositoryRoot, filePath);
+	if (!absolutePath) {
+		return false;
+	}
+
+	if (!fs.existsSync(absolutePath)) {
+		return false;
+	}
+
+	const content = fs.readFileSync(absolutePath, 'utf8');
+	if (/^[A-Za-z_]\w*$/.test(symbol)) {
+		return new RegExp(String.raw`\b${escapeRegExp(symbol)}\b`).test(content);
+	}
+
+	return content.includes(symbol);
+}
+
+function resolveMentionFiles(task, mention, repositoryRoot) {
+	const files = task.files ?? [];
+	if (files.length === 0) {
+		return [];
+	}
+
+	if (!repositoryRoot) {
+		return files.map((file) => normalizeRepoPath(file));
+	}
+
+	const matchingFiles = files
+		.filter((file) => fileContainsSymbol(repositoryRoot, file, mention.symbol))
+		.map((file) => normalizeRepoPath(file));
+	return matchingFiles;
+}
+
+function extractTaskContracts(taskContext, options = {}) {
+	if (!taskContext || !Array.isArray(taskContext.tasks)) {
+		return [];
+	}
+
+	const contracts = new Set();
+	const repositoryRoot = options.repositoryRoot;
+
+	for (const task of taskContext.tasks) {
+		const mentions = extractContractMentions(task.whatToImplement ?? '');
+		for (const mention of mentions) {
+			for (const file of resolveMentionFiles(task, mention, repositoryRoot)) {
+				contracts.add(`${file}:${mention.symbol}(${mention.annotation})`);
+			}
+		}
+	}
+
+	return Array.from(contracts).sort((left, right) => left.localeCompare(right));
+}
+
+function isTaskHeader(line) {
+	return line.startsWith('## Task ');
+}
+
+function parseTaskHeader(line) {
+	if (!isTaskHeader(line)) {
+		return null;
+	}
+
+	const prefixLength = '## Task '.length;
+	const separatorIndex = line.indexOf(':', prefixLength);
+	if (separatorIndex === -1) {
+		return null;
+	}
+
+	const numberText = line.slice(prefixLength, separatorIndex).trim();
+	if (!numberText || Array.from(numberText).some((character) => character < '0' || character > '9')) {
+		return null;
+	}
+
+	const title = line.slice(separatorIndex + 1).trim();
+	if (!title) {
+		return null;
+	}
+
+	return {
+		number: Number(numberText),
+		title,
+	};
+}
+
+function parseTaskField(currentTask, line, currentField) {
+	if (line.startsWith('File(s):')) {
+		currentTask.files = parseFilesLine(line.slice('File(s):'.length).trim());
+		return null;
+	}
+
+	if (line.startsWith('What to implement:')) {
+		currentTask.whatToImplement = line.slice('What to implement:'.length).trim();
+		return 'whatToImplement';
+	}
+
+	if (line.startsWith('Expected output:')) {
+		currentTask.expectedOutput = line.slice('Expected output:'.length).trim();
+		return 'expectedOutput';
+	}
+
+	if (line === 'TDD steps:' || line === '---') {
+		return null;
+	}
+
+	if (currentField && line.trim()) {
+		currentTask[currentField] = `${currentTask[currentField]} ${line.trim()}`.trim();
+	}
+
+	return currentField;
+}
+
+function parseTaskFile(taskFile) {
+	const absolutePath = ensureTaskFile(taskFile);
+	const content = fs.readFileSync(absolutePath, 'utf8');
+	const lines = content.split(/\r?\n/);
+	const tasks = [];
+	let currentTask = null;
+	let currentField = null;
+
+	for (const rawLine of lines) {
+		const line = rawLine.trimEnd();
+		const taskHeader = parseTaskHeader(line);
+
+		if (taskHeader) {
+			flushTask(tasks, currentTask);
+			currentTask = {
+				number: taskHeader.number,
+				title: taskHeader.title,
+				files: [],
+				whatToImplement: '',
+				expectedOutput: '',
+			};
+			currentField = null;
+			continue;
+		}
+
+		if (!currentTask) {
+			continue;
+		}
+
+		currentField = parseTaskField(currentTask, line, currentField);
+	}
+
+	flushTask(tasks, currentTask);
+
+	return {
+		path: absolutePath,
+		taskCount: tasks.length,
+		tasks,
+	};
+}
+
+module.exports = {
+	detectContractType,
+	extractContractMentions,
+	extractSymbols,
+	extractTaskContracts,
+	parseTaskFile,
+};

package/lib/plugin-catalog.js

@@ -24,10 +24,10 @@ const STAGES = Object.freeze({
   RESEARCH: 'research',
   PLAN: 'plan',
   DEV: 'dev',
-  CHECK: 'check',
+  VALIDATE: 'validate',
   SHIP: 'ship',
   REVIEW: 'review',
-  MERGE: 'merge',
+  PREMERGE: 'premerge',
 });
 
 const BUDGET_MODES = Object.freeze({
@@ -101,16 +101,6 @@ const CATALOG = Object.freeze({
     detectWhen: [],
     install: { method: 'npm', cmd: 'bun add -g @beads/bd' },
   },
-  openspec: {
-    name: 'OpenSpec',
-    type: 'cli',
-    tier: 'free',
-    stage: 'plan',
-    description: 'Spec-driven development proposals',
-    detectWhen: [],
-    install: { method: 'npm', cmd: 'bun add -g @fission-ai/openspec' },
-  },
-
   // ── Dev ──
   'typescript-lsp': {
     name: 'TypeScript LSP',
@@ -155,7 +145,7 @@ const CATALOG = Object.freeze({
     name: 'ESLint',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'JavaScript/TypeScript linting',
     detectWhen: ['file:eslint.config.js', 'dep:eslint'],
     install: { method: 'npm', cmd: 'bun add -D eslint', dev: true },
@@ -164,7 +154,7 @@ const CATALOG = Object.freeze({
     name: 'Biome',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Fast formatter and linter',
     detectWhen: ['file:biome.json'],
     install: { method: 'npm', cmd: 'bun add -D @biomejs/biome', dev: true },
@@ -173,7 +163,7 @@ const CATALOG = Object.freeze({
     name: 'Prettier',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Opinionated code formatter',
     detectWhen: ['file:.prettierrc'],
     install: { method: 'npm', cmd: 'bun add -D prettier', dev: true },
@@ -182,7 +172,7 @@ const CATALOG = Object.freeze({
     name: 'ESLint Security Plugin',
     type: 'config',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Security-focused ESLint rules',
     detectWhen: ['dep:express', 'dep:fastify'],
     install: { method: 'npm', cmd: 'bun add -D eslint-plugin-security', dev: true },
@@ -191,7 +181,7 @@ const CATALOG = Object.freeze({
     name: 'SonarCloud Analysis',
     type: 'skill',
     tier: 'free-public',
-    stage: 'check',
+    stage: 'validate',
     description: 'Code quality and security analysis via SonarCloud REST API',
     detectWhen: [],
     install: {
@@ -204,7 +194,7 @@ const CATALOG = Object.freeze({
     name: 'Sonar Scanner',
     type: 'cli',
     tier: 'free-public',
-    stage: 'check',
+    stage: 'validate',
     description: 'SonarCloud/SonarQube CLI scanner',
     detectWhen: ['file:sonar-project.properties'],
     install: { method: 'npm', cmd: 'bun add -D sonarqube-scanner', dev: true },
@@ -214,7 +204,7 @@ const CATALOG = Object.freeze({
     name: 'CodeQL',
     type: 'cli',
     tier: 'free-public',
-    stage: 'check',
+    stage: 'validate',
     description: 'Semantic code analysis by GitHub',
     detectWhen: [],
     install: { method: 'binary', cmd: 'GitHub-provided (github.com/github/codeql-action)' },
@@ -224,7 +214,7 @@ const CATALOG = Object.freeze({
     name: 'npm audit',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Dependency vulnerability scanning',
     detectWhen: [],
     install: { method: 'npm', cmd: 'built-in (bun pm audit)' },
@@ -233,7 +223,7 @@ const CATALOG = Object.freeze({
     name: 'Vitest',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Vite-native test runner',
     detectWhen: ['dep:vitest', 'file:vitest.config.ts'],
     install: { method: 'npm', cmd: 'bun add -D vitest', dev: true },
@@ -242,7 +232,7 @@ const CATALOG = Object.freeze({
     name: 'Jest',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Delightful JavaScript testing',
     detectWhen: ['dep:jest', 'file:jest.config.js'],
     install: { method: 'npm', cmd: 'bun add -D jest', dev: true },
@@ -251,7 +241,7 @@ const CATALOG = Object.freeze({
     name: 'Playwright',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'End-to-end browser testing',
     detectWhen: ['dep:@playwright/test'],
     install: { method: 'npm', cmd: 'bun add -D @playwright/test', dev: true },
@@ -260,7 +250,7 @@ const CATALOG = Object.freeze({
     name: 'c8',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Native V8 code coverage',
     detectWhen: [],
     install: { method: 'npm', cmd: 'bun add -D c8', dev: true },
@@ -269,7 +259,7 @@ const CATALOG = Object.freeze({
     name: 'Stryker',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Mutation testing for JavaScript',
     detectWhen: [],
     install: { method: 'npm', cmd: 'bun add -D @stryker-mutator/core', dev: true },
@@ -278,7 +268,7 @@ const CATALOG = Object.freeze({
     name: 'Oxlint',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Blazing-fast Rust-based linter',
     detectWhen: [],
     install: { method: 'npm', cmd: 'bun add -D oxlint', dev: true },
@@ -341,7 +331,7 @@ const CATALOG = Object.freeze({
     name: 'Changesets',
     type: 'cli',
     tier: 'free',
-    stage: 'merge',
+    stage: 'premerge',
     description: 'Versioning and changelog management',
     detectWhen: ['file:package.json'],
     install: { method: 'npm', cmd: 'bun add -D @changesets/cli', dev: true },
@@ -350,7 +340,7 @@ const CATALOG = Object.freeze({
     name: 'Release Please',
     type: 'config',
     tier: 'free',
-    stage: 'merge',
+    stage: 'premerge',
     description: 'Automated release PRs by Google',
     detectWhen: [],
     install: { method: 'config', cmd: 'GitHub Action (google-github-actions/release-please-action)' },

package/lib/workflow-profiles.js

@@ -12,29 +12,26 @@
 const PROFILES = {
   critical: {
     name: 'Critical (Maximum Rigor)',
-    stages: ['/status', '/research', '/plan', '/dev', '/validate', '/ship', '/review', '/merge', '/verify'],
+    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/review', '/premerge', '/verify'],
     tdd: 'strict',
     research: 'required',
-    openspec: 'required-strategic',
     description: 'Security, auth, payments, data integrity, breaking changes',
     keywords: ['auth', 'security', 'payment', 'crypto', 'password', 'token', 'session', 'data-migration', 'breaking']
   },
 
   standard: {
     name: 'Standard (Full Workflow)',
-    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/merge'],
+    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/review', '/premerge'],
     tdd: 'required',
     research: 'optional',
-    openspec: 'strategic',
     description: 'Most features and non-critical enhancements'
   },
 
   simple: {
     name: 'Simple (Streamlined)',
-    stages: ['/dev', '/validate', '/ship', '/merge'],
+    stages: ['/dev', '/validate', '/ship', '/premerge'],
     tdd: 'recommended',
     research: 'skip',
-    openspec: 'no',
     description: 'UI tweaks, small improvements, minor fixes'
   },
 
@@ -43,26 +40,23 @@ const PROFILES = {
     stages: ['/dev', '/validate', '/ship'],
     tdd: 'required',  // Must reproduce bug
     research: 'skip',
-    openspec: 'no',
     description: 'Production bugs, urgent fixes',
     keywords: ['urgent', 'production', 'emergency', 'hotfix', 'critical']
   },
 
   docs: {
     name: 'Docs (Documentation Only)',
-    stages: ['/verify', '/ship', '/merge'],
+    stages: ['/verify', '/ship', '/premerge'],
     tdd: 'no',
     research: 'no',
-    openspec: 'no',
     description: 'Documentation updates, README changes'
   },
 
   refactor: {
     name: 'Refactor (Behavior-Preserving)',
-    stages: ['/plan', '/dev', '/validate', '/ship', '/merge'],
+    stages: ['/plan', '/dev', '/validate', '/ship', '/premerge'],
     tdd: 'strict',  // Must preserve behavior
     research: 'optional',
-    openspec: 'architectural',
     description: 'Code cleanup, optimization, behavior-preserving improvements'
   }
 };

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "forge-workflow",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "7-stage TDD workflow for ALL AI coding agents (Claude, Cursor, Cline, OpenCode, Copilot, Kilo Code, Roo Code, Codex)",
   "bin": {
     "forge": "bin/forge.js",
     "forge-validate": "bin/forge-validate.js"
   },
+  "workspaces": [
+    "packages/*"
+  ],
   "scripts": {
     "test": "bun test",
     "test:setup": "bash test-env/automation/setup-fixtures.sh",
@@ -36,7 +39,7 @@
     "@commitlint/config-conventional": "^20.4.1",
     "@eslint/js": "^10.0.1",
     "@microsoft/eslint-formatter-sarif": "^3.1.0",
-    "@stryker-mutator/core": "^9.5.1",
+    "@stryker-mutator/core": "^9.6.0",
     "c8": "^11.0.0",
     "eslint": "^10.0.2",
     "globals": "^17.3.0",
@@ -73,12 +76,21 @@
   "files": [
     "bin/",
     "lib/",
+    "skills/",
     ".claude/commands/",
     ".claude/rules/",
     ".claude/scripts/",
-    ".forge/hooks/",
+    ".claude/skills/",
+    ".cursor/",
+    ".cline/",
+    ".roo/",
+    ".codex/",
+    ".kilocode/",
+    ".opencode/",
+    ".github/prompts/",
     ".github/PLUGIN_TEMPLATE.json",
-    "docs/",
+    ".forge/hooks/",
+    "docs/*.md",
     "install.sh",
     "lefthook.yml",
     "AGENTS.md",
@@ -86,10 +98,12 @@
     ".mcp.json.example"
   ],
   "dependencies": {
+    "@babel/parser": "^7.29.2",
     "fastest-levenshtein": "^1.0.16"
   },
   "overrides": {
     "eslint": "^10.0.2",
+    "flatted": "3.4.2",
     "minimatch": "10.2.4"
   },
   "c8": {