@analizza-ai/testspec 0.1.1

package/src/commands/init.js

@@ -0,0 +1,112 @@
+/**
+ * src/commands/init.js
+ * Setup wizard: detects or selects SDD framework, selects AI agent,
+ * writes testspec.config.json, and installs agent instruction files into the project.
+ */
+
+import { Command } from 'commander';
+import { createInterface } from 'readline';
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { log } from '../utils/logger.js';
+import { detectSdd } from '../utils/sdd-detector.js';
+
+export const initCommand = new Command('init')
+  .description('Setup wizard — SDD framework + AI agent + writes testspec.config.json')
+  .action(runInit);
+
+export async function runInit() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  let rlClosed = false;
+  rl.once('close', () => { rlClosed = true; });
+  const ask = (q) => new Promise((res) => {
+    if (rlClosed) return res('');
+    rl.question(q, (ans) => res(ans));
+    rl.once('close', () => res(''));
+  });
+
+  log.info('testspec init — Spec Driven Test setup\n');
+
+  // Step 1: detect SDD framework
+  const detected = detectSdd(process.cwd());
+  let sdd;
+
+  if (detected) {
+    const ans = await ask(`Detected SDD framework: ${detected}. Use it? [Y/n] `);
+    sdd = ans.toLowerCase() === 'n' ? await selectSdd(ask) : detected;
+  } else {
+    sdd = await selectSdd(ask);
+  }
+
+  // Step 2: select AI agent
+  log.info('\nWhich AI agent for test generation?');
+  log.info('  1) Claude Code (default)');
+  log.info('  2) GitHub Copilot');
+  const agentAns = await ask('Choose [1/2]: ');
+  const agent = agentAns.trim() === '2' ? 'copilot' : 'claude';
+
+  // Step 3: optional QA repo
+  const qaRepo = await ask('\nQA repo (owner/repo) for tests.md handoff [leave blank to skip]: ');
+
+  rl.close();
+
+  // Step 4: write testspec.config.json
+  const config = {
+    sdd,
+    agent,
+    stubs: { unit: true, integration: true },
+    unitFramework: 'vitest',
+    ...(qaRepo.trim() && { qaRepo: qaRepo.trim() }),
+    loadHints: true,
+    chaosHints: true,
+  };
+
+  writeFileSync(join(process.cwd(), 'testspec.config.json'), JSON.stringify(config, null, 2) + '\n');
+  log.success('testspec.config.json written');
+
+  // Step 5: install agent instruction files
+  if (agent === 'claude') {
+    const { readFileSync } = await import('fs');
+    const { fileURLToPath } = await import('url');
+    const { dirname, join: pjoin } = await import('path');
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const skillsDir = pjoin(__dirname, '../../templates/agent-instructions/skills');
+    const commandsDir = join(process.cwd(), '.claude', 'commands');
+    mkdirSync(commandsDir, { recursive: true });
+
+    const skills = [
+      'testspec-generate.md',
+      'testspec-specify-qa.md',
+      'testspec-apply-qa.md',
+      'testspec-run-qa.md',
+    ];
+    for (const skill of skills) {
+      const tpl = readFileSync(pjoin(skillsDir, skill), 'utf-8');
+      writeFileSync(join(commandsDir, skill), tpl);
+      log.success(`.claude/commands/${skill} written`);
+    }
+  } else {
+    const dir = join(process.cwd(), '.github');
+    mkdirSync(dir, { recursive: true });
+    const { readFileSync } = await import('fs');
+    const { fileURLToPath } = await import('url');
+    const { dirname, join: pjoin } = await import('path');
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const tpl = readFileSync(pjoin(__dirname, '../../templates/agent-instructions/copilot.md'), 'utf-8');
+    writeFileSync(join(dir, 'copilot-instructions.md'), tpl);
+    log.success('.github/copilot-instructions.md written');
+  }
+
+  log.info('\nSetup complete. Run: testspec generate');
+}
+
+async function selectSdd(ask) {
+  log.info('\nSelect SDD framework:');
+  log.info('  1) OpenSpec (default)');
+  log.info('  2) SpecKit (coming soon)');
+  const ans = await ask('Choose [1/2]: ');
+  if (ans.trim() === '2') {
+    log.warn('SpecKit adapter is not yet implemented. Defaulting to OpenSpec.');
+  }
+  return 'openspec';
+}

package/src/commands/report.js

@@ -0,0 +1,60 @@
+/**
+ * src/commands/report.js
+ * Gap report: which CTs in tests.md have no corresponding test stub yet.
+ */
+
+import { Command } from 'commander';
+import { readFileSync, existsSync } from 'fs';
+import { log } from '../utils/logger.js';
+import { loadConfig } from '../utils/config.js';
+import { getAdapter as getSddAdapter } from '../adapters/sdd/index.js';
+import { generateReport } from '../core/reporter.js';
+
+export const reportCommand = new Command('report')
+  .description('Coverage/gap report: which CTs have no test stub yet')
+  .option('-c, --change <name>', 'target a specific change folder')
+  .option('--format <fmt>', 'output format: text | json | markdown', 'text')
+  .action(runReport);
+
+export async function runReport(opts = {}) {
+  const config = loadConfig(process.cwd());
+  const sddAdapter = getSddAdapter(config.sdd);
+
+  const changes = sddAdapter.discoverChanges(process.cwd());
+  const changeName = opts.change || changes[changes.length - 1];
+  const outputPath = sddAdapter.getOutputPath(process.cwd(), changeName);
+
+  if (!existsSync(outputPath)) {
+    log.error(`tests.md not found at ${outputPath}. Run "testspec generate" first.`);
+    process.exit(1);
+  }
+
+  const testsContent = readFileSync(outputPath, 'utf-8');
+  const report = generateReport(testsContent, process.cwd(), config);
+
+  if (opts.format === 'json') {
+    console.log(JSON.stringify(report, null, 2));
+  } else if (opts.format === 'markdown') {
+    console.log(formatMarkdown(report));
+  } else {
+    formatText(report);
+  }
+}
+
+function formatText(report) {
+  log.info(`\nCoverage report — ${report.change}`);
+  log.info(`Total CTs: ${report.total} | Covered: ${report.covered} | Missing: ${report.missing.length}`);
+  if (report.missing.length > 0) {
+    log.warn('\nCTs with no stub:');
+    report.missing.forEach((ct) => log.warn(`  · ${ct.id} — ${ct.title}`));
+  } else {
+    log.success('\nAll CTs have stubs.');
+  }
+}
+
+function formatMarkdown(report) {
+  const rows = report.missing.map((ct) => `| ${ct.id} | ${ct.title} | ❌ no stub |`).join('\n');
+  return `## testspec coverage — ${report.change}\n\n` +
+    `Total: ${report.total} | Covered: ${report.covered} | Missing: ${report.missing.length}\n\n` +
+    (rows ? `| CT | Title | Status |\n|---|---|---|\n${rows}` : '_All CTs have stubs._');
+}

package/src/commands/validate.js

@@ -0,0 +1,68 @@
+/**
+ * src/commands/validate.js
+ * Maps test run results back to CT-01..N pass/fail status in tests.md.
+ */
+
+import { Command } from 'commander';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { log } from '../utils/logger.js';
+import { loadConfig } from '../utils/config.js';
+import { getAdapter as getSddAdapter } from '../adapters/sdd/index.js';
+
+export const validateCommand = new Command('validate')
+  .description('Map test run results to CT-01..N pass/fail in tests.md')
+  .option('-c, --change <name>', 'target a specific change folder')
+  .option('-r, --results <file>', 'path to test results JSON (vitest/jest --reporter=json)')
+  .action(runValidate);
+
+export async function runValidate(opts = {}) {
+  const config = loadConfig(process.cwd());
+  const sddAdapter = getSddAdapter(config.sdd);
+
+  const changes = sddAdapter.discoverChanges(process.cwd());
+  const changeName = opts.change || changes[changes.length - 1];
+  const outputPath = sddAdapter.getOutputPath(process.cwd(), changeName);
+
+  if (!existsSync(outputPath)) {
+    log.error(`tests.md not found at ${outputPath}. Run "testspec generate" first.`);
+    process.exit(1);
+  }
+
+  if (!opts.results) {
+    log.error('Provide test results with --results <file>');
+    process.exit(1);
+  }
+
+  const testsContent = readFileSync(outputPath, 'utf-8');
+  const results = JSON.parse(readFileSync(opts.results, 'utf-8'));
+
+  const updated = applyResults(testsContent, results);
+  writeFileSync(outputPath, updated);
+  log.success(`tests.md updated with validation results → ${outputPath}`);
+}
+
+/**
+ * Appends pass/fail badges to CT headings based on test result names
+ * that contain the CT identifier (e.g. "CT-01").
+ */
+function applyResults(content, results) {
+  const testNames = extractTestNames(results);
+  return content.replace(/^(### CT-(\d+)[^\n]*)/gm, (line, _full, num) => {
+    const id = `CT-${num.padStart(2, '0')}`;
+    const passed = testNames.filter((n) => n.includes(id) && n.status === 'passed').length;
+    const failed = testNames.filter((n) => n.includes(id) && n.status === 'failed').length;
+    if (passed > 0 && failed === 0) return `${line} ✅`;
+    if (failed > 0) return `${line} ❌`;
+    return line;
+  });
+}
+
+function extractTestNames(results) {
+  const names = [];
+  const traverse = (suite) => {
+    if (suite.tests) suite.tests.forEach((t) => names.push({ name: t.name, status: t.status }));
+    if (suite.suites) suite.suites.forEach(traverse);
+  };
+  if (results.testResults) results.testResults.forEach(traverse);
+  return names;
+}

package/src/core/reporter.js

@@ -0,0 +1,44 @@
+/**
+ * src/core/reporter.js
+ * Generates a CT coverage/gap report by comparing tests.md CTs to existing stub files.
+ */
+
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * @param {string} testsContent  raw tests.md string
+ * @param {string} cwd
+ * @param {object} config
+ * @returns {{ change: string, total: number, covered: number, missing: Array<{id,title}> }}
+ */
+export function generateReport(testsContent, cwd, _config) {
+  const ctMatches = [...testsContent.matchAll(/^### (CT-\d+)\s+[—–-]\s+(.+)$/gm)];
+  const all = ctMatches.map((m) => ({ id: m[1], title: m[2].trim() }));
+
+  const stubsDir = join(cwd, 'tests');
+  const stubFiles = existsSync(stubsDir) ? getAllFiles(stubsDir) : [];
+
+  const missing = all.filter((ct) => !stubFiles.some((f) => f.includes(ct.id.toLowerCase())));
+
+  const featureMatch = testsContent.match(/^feature:\s*(.+)$/m);
+  const changeMatch = testsContent.match(/^change:\s*(.+)$/m);
+
+  return {
+    change: changeMatch ? changeMatch[1].trim() : 'unknown',
+    feature: featureMatch ? featureMatch[1].trim() : 'unknown',
+    total: all.length,
+    covered: all.length - missing.length,
+    missing,
+  };
+}
+
+function getAllFiles(dir) {
+  const results = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.isDirectory()) results.push(...getAllFiles(join(dir, e.name)));
+    else results.push(join(dir, e.name));
+  }
+  return results;
+}

package/src/core/spec-parser.js

@@ -0,0 +1,141 @@
+/**
+ * src/core/spec-parser.js
+ * Parses raw SDD artifact strings into a structured SpecContext object.
+ * No LLM calls — pure text parsing.
+ */
+
+import matter from 'gray-matter';
+
+/**
+ * @typedef {object} SpecContext
+ * @property {string} feature
+ * @property {string} changeName
+ * @property {string} sdd
+ * @property {object} stack
+ * @property {string[]} specs          raw spec content strings
+ * @property {string[]} scenarios      extracted scenario titles
+ * @property {string[]} rules          extracted business rules
+ * @property {string[]} contracts      API contracts from design.md
+ * @property {string[]} dbAssertions   DB validation hints from design.md
+ * @property {string[]} outOfScope
+ * @property {string|null} loadHints
+ * @property {string|null} chaosHints
+ * @property {object} rawArtifacts
+ */
+
+/**
+ * @param {object} artifacts   output of SDD adapter.loadArtifacts()
+ * @param {object} config      testspec.config.json
+ * @returns {SpecContext}
+ */
+export function parseSpecs(artifacts, config) {
+  const { proposal, design, specs, tasks, config: sddConfig, changeName } = artifacts;
+
+  const feature = extractFeatureName(changeName, proposal);
+  const stack = buildStack(sddConfig, config);
+
+  return {
+    feature,
+    changeName,
+    sdd: config.sdd || 'openspec',
+    stack,
+    specs,
+    scenarios: extractScenarios(specs),
+    rules: extractRules(specs),
+    contracts: extractContracts(design),
+    dbAssertions: extractDbAssertions(design),
+    outOfScope: extractOutOfScope(proposal, specs),
+    loadHints: config.loadHints ? extractLoadHints(specs, proposal) : null,
+    chaosHints: config.chaosHints ? extractChaosHints(specs, design) : null,
+    rawArtifacts: { proposal, design, specs, tasks },
+  };
+}
+
+function extractFeatureName(changeName, proposal) {
+  if (proposal) {
+    const m = proposal.match(/^#\s+(.+)$/m);
+    if (m) return m[1].trim();
+    const fm = matter(proposal);
+    if (fm.data.feature) return fm.data.feature;
+  }
+  return changeName;
+}
+
+function buildStack(sddConfig, testspecConfig) {
+  return {
+    lang: sddConfig?.stack?.lang || testspecConfig?.stack?.lang || 'node',
+    db: sddConfig?.stack?.db || testspecConfig?.stack?.db || 'postgresql',
+    broker: sddConfig?.stack?.broker || testspecConfig?.stack?.broker || null,
+  };
+}
+
+function extractScenarios(specs) {
+  const scenarios = [];
+  for (const spec of specs) {
+    const matches = spec.matchAll(/^#{2,4}\s+(?:Scenario|Cenário|Scenario:)\s*(.+)$/gim);
+    for (const m of matches) scenarios.push(m[1].trim());
+    // Also extract "Given/When/Then" blocks as scenario titles
+    const gwt = spec.matchAll(/^#{2,4}\s+(.+)$/gm);
+    for (const m of gwt) {
+      const title = m[1].trim();
+      if (!scenarios.includes(title)) scenarios.push(title);
+    }
+  }
+  return [...new Set(scenarios)].slice(0, 50);
+}
+
+function extractRules(specs) {
+  const rules = [];
+  for (const spec of specs) {
+    const matches = spec.matchAll(/^[-*]\s+(?:Rule|Regra):\s*(.+)$/gim);
+    for (const m of matches) rules.push(m[1].trim());
+    // Also capture bullet points under "Rules" / "Business Rules" headers
+    const ruleSection = spec.match(/^#{2,3}\s+(?:Rules?|Business Rules?|Regras?)[^\n]*\n([\s\S]*?)(?=\n#{2,3}|$)/im);
+    if (ruleSection) {
+      const bullets = ruleSection[1].matchAll(/^[-*]\s+(.+)$/gm);
+      for (const b of bullets) rules.push(b[1].trim());
+    }
+  }
+  return [...new Set(rules)].slice(0, 30);
+}
+
+function extractContracts(design) {
+  if (!design) return [];
+  const contracts = [];
+  const endpointMatches = design.matchAll(/`((?:GET|POST|PUT|PATCH|DELETE)\s+\/[^`]+)`/gi);
+  for (const m of endpointMatches) contracts.push(m[1].trim());
+  return [...new Set(contracts)];
+}
+
+function extractDbAssertions(design) {
+  if (!design) return [];
+  const assertions = [];
+  const sqlMatches = design.matchAll(/```sql([\s\S]*?)```/gi);
+  for (const m of sqlMatches) assertions.push(m[1].trim());
+  return assertions;
+}
+
+function extractOutOfScope(proposal, specs) {
+  const outOfScope = [];
+  const sources = [proposal, ...specs].filter(Boolean);
+  for (const src of sources) {
+    const section = src.match(/^#{2,3}\s+Out of [Ss]cope[^\n]*\n([\s\S]*?)(?=\n#{2,3}|$)/im);
+    if (section) {
+      const bullets = section[1].matchAll(/^[-*]\s+(.+)$/gm);
+      for (const b of bullets) outOfScope.push(b[1].trim());
+    }
+  }
+  return [...new Set(outOfScope)];
+}
+
+function extractLoadHints(specs, proposal) {
+  const sources = [...specs, proposal].filter(Boolean).join('\n');
+  const section = sources.match(/^#{2,3}\s+(?:Load|Performance|NFR)[^\n]*\n([\s\S]*?)(?=\n#{2,3}|$)/im);
+  return section ? section[1].trim() : null;
+}
+
+function extractChaosHints(specs, design) {
+  const sources = [design, ...specs].filter(Boolean).join('\n');
+  const section = sources.match(/^#{2,3}\s+(?:Chaos|Failure|Resilience)[^\n]*\n([\s\S]*?)(?=\n#{2,3}|$)/im);
+  return section ? section[1].trim() : null;
+}

package/src/core/stub-generator.js

@@ -0,0 +1,92 @@
+/**
+ * src/core/stub-generator.js
+ * Generates unit and integration test stubs from a SpecContext.
+ * Reads templates from templates/stubs/ and substitutes CT placeholders.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '../../templates/stubs');
+
+/**
+ * @param {import('./spec-parser.js').SpecContext} ctx
+ * @param {object} config
+ * @param {string} outputDir  directory where tests.md was written
+ * @returns {{ unit: string[], integration: string[] }}
+ */
+export function generateStubs(ctx, config, outputDir) {
+  const unitFramework = config.unitFramework || 'vitest';
+  const unit = [];
+  const integration = [];
+
+  if (config.stubs?.unit !== false) {
+    const unitStubs = generateUnitStubs(ctx, unitFramework, outputDir);
+    unit.push(...unitStubs);
+  }
+
+  if (config.stubs?.integration !== false) {
+    const intStubs = generateIntegrationStubs(ctx, config, outputDir);
+    integration.push(...intStubs);
+  }
+
+  return { unit, integration };
+}
+
+function generateUnitStubs(ctx, framework, outputDir) {
+  const tplPath = join(TEMPLATES_DIR, framework, 'unit.template.js');
+  if (!existsSync(tplPath)) return [];
+
+  const template = readFileSync(tplPath, 'utf-8');
+  const written = [];
+
+  ctx.scenarios.forEach((scenario, i) => {
+    const ctId = `CT-${String(i + 1).padStart(2, '0')}`;
+    const fileName = `${ctId.toLowerCase()}-${slugify(scenario)}.unit.test.js`;
+    const outPath = join(outputDir, 'tests', 'unit', fileName);
+
+    const content = template
+      .replace(/\{\{CT_ID\}\}/g, ctId)
+      .replace(/\{\{TITLE\}\}/g, scenario)
+      .replace(/\{\{FEATURE\}\}/g, ctx.feature);
+
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, content);
+    written.push(outPath);
+  });
+
+  return written;
+}
+
+function generateIntegrationStubs(ctx, config, outputDir) {
+  const stack = ctx.stack;
+  let tplName;
+
+  if (stack.broker) {
+    tplName = stack.lang === 'node' ? 'node-pg-kafka.template.js' : 'spring-pg-kafka.template.java';
+  } else {
+    tplName = 'node-pg.template.js';
+  }
+
+  const tplPath = join(TEMPLATES_DIR, 'testcontainers', tplName);
+  if (!existsSync(tplPath)) return [];
+
+  const template = readFileSync(tplPath, 'utf-8');
+  const outPath = join(outputDir, 'tests', 'integration', `${slugify(ctx.feature)}.integration.test.js`);
+
+  const content = template
+    .replace(/\{\{FEATURE\}\}/g, ctx.feature)
+    .replace(/\{\{CHANGE\}\}/g, ctx.changeName)
+    .replace(/\{\{SCENARIOS\}\}/g, ctx.scenarios.map((s, i) =>
+      `  // CT-${String(i + 1).padStart(2, '0')}: ${s}`).join('\n'));
+
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, content);
+  return [outPath];
+}
+
+function slugify(str) {
+  return str.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}

package/src/core/testcontainers.js

@@ -0,0 +1,39 @@
+/**
+ * src/core/testcontainers.js
+ * Builds Testcontainers container setup snippets from stack config.
+ * Used by stub-generator to pre-configure the right container images.
+ */
+
+/**
+ * @param {{ lang: string, db: string, broker: string|null }} stack
+ * @returns {{ imports: string, setup: string, teardown: string }}
+ */
+export function buildContainerSetup(stack) {
+  const imports = [];
+  const setupLines = [];
+  const teardownLines = [];
+
+  if (stack.db === 'postgresql') {
+    imports.push("import { PostgreSqlContainer } from '@testcontainers/postgresql';");
+    setupLines.push(
+      "container = await new PostgreSqlContainer('postgres:16-alpine').start();",
+      'connectionString = container.getConnectionUri();',
+    );
+    teardownLines.push('await container.stop();');
+  }
+
+  if (stack.broker === 'kafka') {
+    imports.push("import { KafkaContainer } from '@testcontainers/kafka';");
+    setupLines.push(
+      "kafkaContainer = await new KafkaContainer('confluentinc/cp-kafka:7.4.0').start();",
+      'brokerUrl = `${kafkaContainer.getHost()}:${kafkaContainer.getMappedPort(9093)}`;',
+    );
+    teardownLines.push('await kafkaContainer.stop();');
+  }
+
+  return {
+    imports: imports.join('\n'),
+    setup: setupLines.join('\n    '),
+    teardown: teardownLines.join('\n    '),
+  };
+}

package/src/core/tests-builder.js

@@ -0,0 +1,120 @@
+/**
+ * src/core/tests-builder.js
+ * Builds the agent prompt from a SpecContext, and assembles the tests.md skeleton.
+ * No LLM calls — only prompt construction. Agent adapters call the LLM.
+ */
+
+/**
+ * Builds the full prompt string to send to (or print for) an AI agent.
+ * @param {import('./spec-parser.js').SpecContext} ctx
+ * @param {object} config
+ * @returns {string}
+ */
+export function buildPrompt(ctx, config) {
+  const stackDesc = [ctx.stack.lang, ctx.stack.db, ctx.stack.broker].filter(Boolean).join(' + ');
+
+  return `# testspec generate — ${ctx.feature}
+
+## Task
+You are generating a \`tests.md\` for the feature **${ctx.feature}** (change: \`${ctx.changeName}\`).
+Follow the SDT canonical structure exactly.
+
+## Stack
+${stackDesc}
+
+## Spec artifacts
+
+### Scenarios detected
+${ctx.scenarios.map((s) => `- ${s}`).join('\n') || '_none detected_'}
+
+### Business rules
+${ctx.rules.map((r) => `- ${r}`).join('\n') || '_none detected_'}
+
+### API contracts (from design.md)
+${ctx.contracts.map((c) => `- \`${c}\``).join('\n') || '_none detected_'}
+
+### DB assertions (from design.md)
+${ctx.dbAssertions.map((a) => `\`\`\`sql\n${a}\n\`\`\``).join('\n') || '_none detected_'}
+
+### Out of scope
+${ctx.outOfScope.map((o) => `- ${o}`).join('\n') || '_none detected_'}
+
+${ctx.loadHints ? `### Load hints\n${ctx.loadHints}\n` : ''}
+${ctx.chaosHints ? `### Chaos hints\n${ctx.chaosHints}\n` : ''}
+
+## Raw spec content
+${ctx.specs.map((s, i) => `### spec-${i + 1}\n${s}`).join('\n\n')}
+
+## Output format
+Produce a complete \`tests.md\` with this EXACT structure:
+
+\`\`\`
+---
+feature: ${ctx.feature}
+change: ${ctx.changeName}
+generated: <ISO timestamp>
+sdd: ${ctx.sdd}
+sdt: 0.1.0
+stack: { lang: ${ctx.stack.lang}, db: ${ctx.stack.db}${ctx.stack.broker ? `, broker: ${ctx.stack.broker}` : ''} }
+---
+
+# Tests — ${ctx.feature}
+
+## Scope
+<bullet list of what is in scope>
+
+## Out of scope
+<bullet list>
+
+## Test cases
+
+### CT-01 — <title>
+| Field               | Value |
+|---------------------|-------|
+| Type                | unit \\| integration \\| e2e \\| load \\| chaos |
+| Layer               | developer \\| qa \\| chaos |
+| Precondition        | ... |
+| Input               | ... |
+| Expected output     | ... |
+| DB validation       | ... |
+| Acceptance criteria | · bullet |
+
+<repeat for each CT>
+${config.loadHints !== false ? `\n## Load profile hints\n| Scenario | RPS | Duration | p95 target | p99 target |\n|---|---|---|---|---|` : ''}
+${config.chaosHints !== false ? `\n## Chaos scenarios\n| Scenario | Failure mode | Expected behaviour |\n|---|---|---|` : ''}
+\`\`\`
+
+Generate as many CTs as needed to cover all scenarios, rules, and contracts.
+Number them CT-01, CT-02, … with no gaps.
+`;
+}
+
+/**
+ * Assembles a minimal tests.md skeleton (used for placeholder generation).
+ * @param {import('./spec-parser.js').SpecContext} ctx
+ * @returns {string}
+ */
+export function buildTests(ctx) {
+  const now = new Date().toISOString();
+  const stackYaml = `{ lang: ${ctx.stack.lang}, db: ${ctx.stack.db}${ctx.stack.broker ? `, broker: ${ctx.stack.broker}` : ''} }`;
+
+  return `---
+feature: ${ctx.feature}
+change: ${ctx.changeName}
+generated: ${now}
+sdd: ${ctx.sdd}
+sdt: 0.1.0
+stack: ${stackYaml}
+---
+
+# Tests — ${ctx.feature}
+
+## Scope
+
+## Out of scope
+${ctx.outOfScope.map((o) => `- ${o}`).join('\n')}
+
+## Test cases
+
+`;
+}

package/src/index.js

@@ -0,0 +1,10 @@
+/**
+ * src/index.js
+ * Public API surface for programmatic use of @analizza-ai/testspec.
+ */
+
+export { parseSpecs } from './core/spec-parser.js';
+export { buildTests } from './core/tests-builder.js';
+export { generateStubs } from './core/stub-generator.js';
+export { loadConfig } from './utils/config.js';
+export { detectSdd } from './utils/sdd-detector.js';