@analizza-ai/testspec 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-25
+
+### Added
+- `testspec init` — setup wizard for SDD framework + AI agent detection
+- `testspec generate` — reads OpenSpec artifacts → writes `tests.md` + stubs
+- `testspec validate` — maps test run results back to CT-01..N pass/fail
+- `testspec report` — CT coverage/gap report
+- OpenSpec adapter (full implementation)
+- SpecKit adapter (stub, not yet implemented)
+- Claude Code agent adapter (print-to-chat + `--api` mode)
+- GitHub Copilot agent adapter (print-to-chat)
+- Unit test stub templates: Vitest, Jest, Pytest, JUnit
+- Integration test stub templates: Node.js + PostgreSQL, Node.js + PostgreSQL + Kafka, Spring Boot + PostgreSQL + Kafka
+- `tests.md` canonical structure with CT tables, load profile hints, chaos scenarios
+- Agent instruction templates: CLAUDE.md, copilot.md, AGENTS.md

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diego Lirio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# @analizza-ai/testspec
+
+[![npm](https://img.shields.io/npm/v/@analizza-ai/testspec)](https://www.npmjs.com/package/@analizza-ai/testspec)
+[![CI](https://github.com/analizza-ai/testspec/actions/workflows/ci.yml/badge.svg)](https://github.com/analizza-ai/testspec/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@analizza-ai/testspec)](./LICENSE)
+[![node](https://img.shields.io/node/v/@analizza-ai/testspec)](./package.json)
+
+**Spec Driven Test — the test layer for SDD**
+
+testspec (SDT) inverts traditional test generation. Instead of writing code first and covering it with tests, SDT drives the entire test lifecycle from your spec artifacts. Specs are the single source of truth.
+
+---
+
+## Test pyramid
+
+```
+┌─────────────────────────────────────────────────┐
+│              CHAOS ENGINEERING                  │  ← /testspec-run-qa
+│         (resilience · DR · fault injection)     │
+├─────────────────────────────────────────────────┤
+│               QA LAYER                          │  ← /testspec-apply-qa
+│     end-to-end tests · load tests (k6/Gatling)  │
+├─────────────────────────────────────────────────┤
+│             DEVELOPER LAYER                     │  ← testspec generate
+│   unit tests · integration tests (Testcontainers│
+│   PostgreSQL · Kafka · etc.)                    │
+└─────────────────────────────────────────────────┘
+         All layers driven by: tests.md
+         tests.md driven by: spec.md + proposal.md + design.md
+```
+
+---
+
+## What is SDT
+
+testspec reads the spec artifacts produced by your SDD framework (OpenSpec, SpecKit, etc.) and generates:
+
+1. **`tests.md`** — a technology-agnostic test document with numbered CT-01..N test cases
+2. **Unit test stubs** — Jest / Vitest / Pytest / JUnit skeletons named after CTs
+3. **Integration test stubs** — Testcontainers-based, pre-configured for your stack
+
+The QA layer then consumes `tests.md` to generate k6/Gatling scripts without ambiguity.
+
+---
+
+## Quick start
+
+```bash
+# install globally
+npm install -g @analizza-ai/testspec
+
+# in your project root (must have openspec/ or similar)
+testspec init       # detects SDD framework, selects AI agent, writes config
+testspec generate   # reads specs → writes tests.md + stubs
+testspec validate --results test-results.json
+testspec report
+```
+
+---
+
+## How it works
+
+```
+Spec artifacts (proposal.md · design.md · specs/**/*.md · tasks.md)
+    ↓
+testspec generate
+    ↓
+SpecContext (scenarios, rules, contracts, dbAssertions)
+    ↓
+Agent prompt (printed to chat or sent via --api)
+    ↓
+tests.md  (CT-01..N)
+    ↓
+Unit stubs + Integration stubs (Testcontainers)
+    ↓
+QA repo reads tests.md via GitHub MCP
+    ↓
+k6 / Gatling scripts  ·  chaos scripts
+```
+
+---
+
+## Supported SDD frameworks
+
+| Framework | Status |
+|-----------|--------|
+| OpenSpec (`@fission-ai/openspec`) | ✅ v1 |
+| SpecKit | planned |
+| BMAD | planned |
+| Kiro (AWS) | planned |
+| Custom | planned |
+
+## Supported AI agents
+
+| Agent | Status |
+|-------|--------|
+| Claude Code | ✅ print-to-chat + `--api` |
+| GitHub Copilot | ✅ print-to-chat |
+
+## Supported unit test frameworks
+
+| Framework | Status |
+|-----------|--------|
+| Vitest | ✅ |
+| Jest | ✅ |
+| Pytest | ✅ |
+| JUnit | ✅ |
+
+## Supported integration runtimes
+
+| Runtime | Status |
+|---------|--------|
+| Testcontainers + PostgreSQL | ✅ |
+| Testcontainers + PostgreSQL + Kafka | ✅ |
+| Testcontainers + Spring Boot + Kafka | ✅ |
+
+---
+
+## tests.md format
+
+```yaml
+---
+feature: Item Creation
+change: item-creation
+generated: 2026-05-25T10:00:00.000Z
+sdd: openspec
+sdt: 0.1.0
+stack: { lang: node, db: postgresql }
+qa-repo: analizza-ai/qa
+---
+
+# Tests — Item Creation
+
+## Scope
+## Out of scope
+
+## Test cases
+
+### CT-01 — Create item with valid payload
+
+| Field               | Value                        |
+|---------------------|------------------------------|
+| Type                | integration                  |
+| Layer               | developer                    |
+| Precondition        | User is authenticated        |
+| Input               | POST /api/items { name: "x" }|
+| Expected output     | 201 Created { id: 1 }        |
+| DB validation       | SELECT id FROM items WHERE id = 1 |
+| Acceptance criteria | · item persisted · id returned |
+
+## Load profile hints
+## Chaos scenarios
+```
+
+---
+
+## Configuration
+
+`testspec.config.json` in your project root:
+
+```json
+{
+  "sdd": "openspec",
+  "agent": "claude",
+  "unitFramework": "vitest",
+  "stubs": { "unit": true, "integration": true },
+  "loadHints": true,
+  "chaosHints": true,
+  "qaRepo": "your-org/qa-repo"
+}
+```
+
+---
+
+## Adapter extension guide
+
+See [docs/adapters-sdd.md](docs/adapters-sdd.md) to add a custom SDD framework adapter.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome.
+
+---
+
+## License
+
+MIT © Diego Lirio

package/bin/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * bin/cli.js
+ * Entry point for the testspec CLI.
+ */
+
+import { program } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
+
+program
+  .name('testspec')
+  .description('Spec Driven Test — generate tests.md and stubs from SDD specs')
+  .version(pkg.version);
+
+const { initCommand } = await import('../src/commands/init.js');
+const { generateCommand } = await import('../src/commands/generate.js');
+const { validateCommand } = await import('../src/commands/validate.js');
+const { reportCommand } = await import('../src/commands/report.js');
+
+program.addCommand(initCommand);
+program.addCommand(generateCommand);
+program.addCommand(validateCommand);
+program.addCommand(reportCommand);
+
+// alias: testspec-generate → generate
+program
+  .command('testspec-generate')
+  .description('Alias for "generate" — reads specs → writes tests.md + stubs')
+  .option('-c, --change <name>', 'target a specific change folder')
+  .option('--api', 'call Claude API instead of printing prompt to chat')
+  .option('--no-stubs', 'skip stub generation, write tests.md only')
+  .action(async (opts) => {
+    const { runGenerate } = await import('../src/commands/generate.js');
+    await runGenerate(opts);
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@analizza-ai/testspec",
+  "version": "0.1.1",
+  "description": "Spec Driven Test — the test layer for SDD",
+  "type": "module",
+  "bin": {
+    "testspec": "./bin/cli.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src bin tests",
+    "lint:fix": "eslint src bin tests --fix"
+  },
+  "keywords": [
+    "sdd",
+    "spec-driven",
+    "test-generation",
+    "testspec",
+    "openspec",
+    "claude",
+    "ai-testing"
+  ],
+  "author": "Diego Lirio <diegolirio.dl@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/analizza-ai/testspec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/analizza-ai/testspec/issues"
+  },
+  "homepage": "https://github.com/analizza-ai/testspec#readme",
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "gray-matter": "^4.0.3",
+    "chalk": "^5.3.0",
+    "glob": "^11.0.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^1.6.0",
+    "eslint": "^9.0.0",
+    "@anthropic-ai/sdk": "^0.30.0"
+  },
+  "optionalDependencies": {
+    "@anthropic-ai/sdk": "^0.30.0"
+  }
+}

package/src/adapters/agents/claude.js

@@ -0,0 +1,88 @@
+/**
+ * src/adapters/agents/claude.js
+ * Claude adapter. Builds the SpecContext → tests.md prompt.
+ * Default: prints prompt to stdout (agent reads it in chat).
+ * With --api flag: calls Claude API (requires ANTHROPIC_API_KEY).
+ */
+
+import { buildPrompt } from '../../core/tests-builder.js';
+import { log } from '../../utils/logger.js';
+
+export class ClaudeAdapter {
+  /**
+   * @param {object} specContext
+   * @param {object} config
+   * @param {{ useApi: boolean }} opts
+   * @returns {Promise<string>} tests.md content
+   */
+  async generateTests(specContext, config, opts = {}) {
+    const prompt = buildPrompt(specContext, config);
+
+    if (!opts.useApi) {
+      log.info('\n─── Prompt for Claude Code (/testspec-generate) ────────\n');
+      console.log(prompt);
+      log.info('\n────────────────────────────────────────────────────────\n');
+      log.warn('Paste the output above into your Claude Code chat to get tests.md.');
+      log.warn('Re-run with --api to call Claude API directly.');
+
+      // Return a placeholder tests.md so the CLI can write a file
+      return buildPlaceholder(specContext);
+    }
+
+    return this.#callApi(prompt, specContext, config);
+  }
+
+  async #callApi(prompt, _specContext, _config) {
+    let Anthropic;
+    try {
+      ({ default: Anthropic } = await import('@anthropic-ai/sdk'));
+    } catch {
+      log.error('@anthropic-ai/sdk not installed. Run: npm install @anthropic-ai/sdk');
+      process.exit(1);
+    }
+
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      log.error('ANTHROPIC_API_KEY env var is required for --api mode.');
+      process.exit(1);
+    }
+
+    const client = new Anthropic({ apiKey });
+    log.info('Calling Claude API…');
+
+    const message = await client.messages.create({
+      model: 'claude-sonnet-4-6',
+      max_tokens: 8192,
+      messages: [{ role: 'user', content: prompt }],
+    });
+
+    return message.content[0].text;
+  }
+}
+
+function buildPlaceholder(specContext) {
+  const now = new Date().toISOString();
+  return `---
+feature: ${specContext.feature}
+change: ${specContext.changeName}
+generated: ${now}
+sdd: ${specContext.sdd}
+sdt: 0.1.0
+status: placeholder — run with --api or paste the prompt into Claude Code
+---
+
+# Tests — ${specContext.feature}
+
+> This file was generated as a placeholder. Paste the printed prompt into your Claude Code chat
+> and replace this file with the output, or re-run \`testspec generate --api\`.
+
+## Scope
+_To be filled by agent_
+
+## Out of scope
+_To be filled by agent_
+
+## Test cases
+_To be filled by agent_
+`;
+}

package/src/adapters/agents/copilot.js

@@ -0,0 +1,39 @@
+/**
+ * src/adapters/agents/copilot.js
+ * GitHub Copilot adapter. Prints the prompt so Copilot can read it via copilot-instructions.md context.
+ * Does not call an API — Copilot reads the prompt in the editor chat.
+ */
+
+import { buildPrompt } from '../../core/tests-builder.js';
+import { log } from '../../utils/logger.js';
+
+export class CopilotAdapter {
+  /**
+   * @param {object} specContext
+   * @param {object} config
+   * @returns {Promise<string>} placeholder tests.md
+   */
+  async generateTests(specContext, config) {
+    const prompt = buildPrompt(specContext, config);
+
+    log.info('\n─── Prompt for GitHub Copilot ───────────────────────────\n');
+    console.log(prompt);
+    log.info('\n────────────────────────────────────────────────────────\n');
+    log.warn('Paste the above into GitHub Copilot Chat to generate tests.md.');
+
+    const now = new Date().toISOString();
+    return `---
+feature: ${specContext.feature}
+change: ${specContext.changeName}
+generated: ${now}
+sdd: ${specContext.sdd}
+sdt: 0.1.0
+status: placeholder — paste the prompt into GitHub Copilot Chat
+---
+
+# Tests — ${specContext.feature}
+
+> Paste the printed prompt into GitHub Copilot Chat and replace this file with the output.
+`;
+  }
+}

package/src/adapters/agents/index.js

@@ -0,0 +1,22 @@
+/**
+ * src/adapters/agents/index.js
+ * Registry mapping AI agent names to their adapter implementations.
+ */
+
+import { ClaudeAdapter } from './claude.js';
+import { CopilotAdapter } from './copilot.js';
+
+const registry = {
+  claude: ClaudeAdapter,
+  copilot: CopilotAdapter,
+};
+
+/**
+ * Returns an instantiated adapter for the given agent name.
+ * @param {string} name
+ */
+export function getAdapter(name = 'claude') {
+  const Adapter = registry[name.toLowerCase()];
+  if (!Adapter) throw new Error(`Unknown agent adapter: "${name}". Supported: ${Object.keys(registry).join(', ')}`);
+  return new Adapter();
+}

package/src/adapters/sdd/index.js

@@ -0,0 +1,23 @@
+/**
+ * src/adapters/sdd/index.js
+ * Registry mapping SDD framework names to their adapter implementations.
+ */
+
+import { OpenSpecAdapter } from './openspec.js';
+import { SpecKitAdapter } from './speckit.js';
+
+const registry = {
+  openspec: OpenSpecAdapter,
+  speckit: SpecKitAdapter,
+};
+
+/**
+ * Returns an instantiated adapter for the given SDD framework name.
+ * @param {string} name
+ * @returns {OpenSpecAdapter | SpecKitAdapter}
+ */
+export function getAdapter(name = 'openspec') {
+  const Adapter = registry[name.toLowerCase()];
+  if (!Adapter) throw new Error(`Unknown SDD adapter: "${name}". Supported: ${Object.keys(registry).join(', ')}`);
+  return new Adapter();
+}

package/src/adapters/sdd/openspec.js

@@ -0,0 +1,58 @@
+/**
+ * src/adapters/sdd/openspec.js
+ * Full OpenSpec adapter. Reads change folders under openspec/changes/{name}/
+ * and loads proposal.md, design.md, specs/**\/*.md, tasks.md, config.yaml.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { glob } from 'glob';
+import yaml from 'js-yaml';
+
+export class OpenSpecAdapter {
+  /** @returns {string[]} list of change names (non-archived) */
+  discoverChanges(root) {
+    const changesDir = join(root, 'openspec', 'changes');
+    if (!existsSync(changesDir)) return [];
+    return readdirSync(changesDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name !== 'archive')
+      .map((e) => e.name)
+      .sort();
+  }
+
+  /**
+   * Loads all spec artifacts for a change.
+   * @returns {{ proposal: string, design: string, specs: string[], tasks: string, config: object }}
+   */
+  loadArtifacts(root, changeName) {
+    const base = join(root, 'openspec', 'changes', changeName);
+
+    const read = (file) => {
+      const p = join(base, file);
+      return existsSync(p) ? readFileSync(p, 'utf-8') : '';
+    };
+
+    const specFiles = glob.sync('specs/**/*.md', { cwd: base });
+    const specs = specFiles.map((f) => readFileSync(join(base, f), 'utf-8'));
+
+    const configPath = join(root, 'openspec', 'config.yaml');
+    const config = existsSync(configPath)
+      ? yaml.load(readFileSync(configPath, 'utf-8'))
+      : {};
+
+    return {
+      proposal: read('proposal.md'),
+      design: read('design.md'),
+      specs,
+      specFiles,
+      tasks: read('tasks.md'),
+      config,
+      changeName,
+    };
+  }
+
+  /** @returns {string} absolute path where tests.md should be written */
+  getOutputPath(root, changeName) {
+    return join(root, 'openspec', 'changes', changeName, 'tests.md');
+  }
+}

package/src/adapters/sdd/speckit.js

@@ -0,0 +1,19 @@
+/**
+ * src/adapters/sdd/speckit.js
+ * SpecKit adapter stub. Interface only — not yet implemented.
+ * Implement discoverChanges / loadArtifacts / getOutputPath when SpecKit is supported.
+ */
+
+export class SpecKitAdapter {
+  discoverChanges(_root) {
+    throw new Error('SpecKit adapter is not yet implemented.');
+  }
+
+  loadArtifacts(_root, _changeName) {
+    throw new Error('SpecKit adapter is not yet implemented.');
+  }
+
+  getOutputPath(_root, _changeName) {
+    throw new Error('SpecKit adapter is not yet implemented.');
+  }
+}

package/src/commands/generate.js

@@ -0,0 +1,66 @@
+/**
+ * src/commands/generate.js
+ * Core command: reads SDD spec artifacts → builds tests.md + optional stubs.
+ * Also registered as the "testspec-generate" alias in bin/cli.js.
+ */
+
+import { Command } from 'commander';
+import { log } from '../utils/logger.js';
+import { loadConfig } from '../utils/config.js';
+import { getAdapter as getSddAdapter } from '../adapters/sdd/index.js';
+import { getAdapter as getAgentAdapter } from '../adapters/agents/index.js';
+import { parseSpecs } from '../core/spec-parser.js';
+import { generateStubs } from '../core/stub-generator.js';
+import { writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+export const generateCommand = new Command('generate')
+  .description('Read specs → write tests.md + optional unit/integration stubs')
+  .option('-c, --change <name>', 'target a specific change folder')
+  .option('--api', 'call Claude API instead of printing prompt to chat')
+  .option('--no-stubs', 'skip stub generation, write tests.md only')
+  .action(runGenerate);
+
+export async function runGenerate(opts = {}) {
+  const config = loadConfig(process.cwd());
+  const sddAdapter = getSddAdapter(config.sdd);
+  const agentAdapter = getAgentAdapter(config.agent);
+
+  // 1. Discover and load artifacts
+  const changes = sddAdapter.discoverChanges(process.cwd());
+  if (changes.length === 0) {
+    log.error('No changes found. Run from a project root with SDD artifacts.');
+    process.exit(1);
+  }
+
+  const changeName = opts.change || changes[changes.length - 1];
+  log.info(`Processing change: ${changeName}`);
+
+  const artifacts = sddAdapter.loadArtifacts(process.cwd(), changeName);
+  const outputPath = sddAdapter.getOutputPath(process.cwd(), changeName);
+
+  // 2. Parse into SpecContext
+  const specContext = parseSpecs(artifacts, config);
+  log.info(`Parsed ${specContext.specs.length} spec file(s)`);
+
+  // 3. Generate tests.md via agent adapter
+  const testsContent = await agentAdapter.generateTests(specContext, config, {
+    useApi: opts.api ?? false,
+  });
+
+  // 4. Write tests.md
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, testsContent);
+  log.success(`tests.md written → ${outputPath}`);
+
+  // 5. Optional stubs
+  const stubsEnabled = opts.stubs !== false && config.stubs?.unit !== false;
+  if (stubsEnabled) {
+    const stubResults = generateStubs(specContext, config, dirname(outputPath));
+    log.success(`Unit stubs: ${stubResults.unit.length} file(s)`);
+    log.success(`Integration stubs: ${stubResults.integration.length} file(s)`);
+  }
+
+  const ctCount = (testsContent.match(/^### CT-\d+/gm) || []).length;
+  log.info(`\nSummary: ${specContext.specs.length} spec(s) → ${ctCount} CT(s) → tests.md written`);
+}