tewip-ai 0.7.1 → 0.8.0

package/README.md

@@ -166,6 +166,22 @@ that lost its markup) and **5 of 5 harmless changes ignored** (capitals, extra s
 implemented as a link, reordered sections). No designer has judged the output yet, so the roadmap's
 own metric is still open.
 
+## Bugs filed back, and test cases where your team keeps them (Phase 10, completed)
+
+```bash
+tewip bugs report.xml --project SHOP             # shows what it would file; nothing is created
+tewip bugs report.xml --project SHOP --create    # files them
+tewip jira plan.json --export xray --out cases.csv    # or --export zephyr
+```
+
+`tewip bugs` files a ticket only for failures **it** diagnosed as a real bug, with the error, the
+evidence and the run link. A flaky test or a broken environment is deliberately not filed - that is
+the point of diagnosing first. The same failure is never filed twice: the second sighting is a short
+note on the ticket Tewip itself opened. A dry run needs no Jira account at all.
+
+`--export xray|zephyr` writes the plan's scenarios as the CSV those tools import, one row per step.
+No account, no network; importing stays your step.
+
 ## Security: which findings actually matter (Phase 9, new)
 
 ```bash

package/TEAM-GUIDE.md

@@ -121,6 +121,8 @@ collects environment failures in one issue, and (optionally) opens a fix pull re
 | `tewip write` | Turns the plan's scenarios into real tests in your own framework, and keeps only the ones that pass repeatedly **and** fail when their check is broken on purpose | When you know what to test but not how to write it |
 | `tewip plan --issue PROJ-123` | Plans from the Jira ticket itself: its description and acceptance criteria | "Here's the story, what should we test?" |
 | `tewip jira plan.json --project PROJ` | Files the plan's scenarios as test-case tickets, linked to the story | Handing work to the team |
+| `tewip bugs report.xml --project PROJ` | Files a bug for each failure that really is a bug, with its evidence; files nothing for flaky tests or environment problems | After a CI run with real failures |
+| `tewip jira plan.json --export xray` | Writes the test cases as a CSV for Xray or Zephyr Scale | Your team keeps cases in a test-management tool |
 | `tewip secure [--url http://localhost:3000]` | Runs your dependency and secret scanners, checks the running app's headers, cookies and exposed files, then says which findings need someone now and which are noise or unreachable | Before a release, or in CI |
 | `tewip spec "<feature>"` | An epic, its user stories and acceptance criteria, grounded in your code; files them in Jira with `--project PROJ --create` | Before the work is broken down |
 | `tewip report report.xml --gate` | The CI command for GitLab, Jenkins, CircleCI, Azure, Bitbucket and the rest: diagnoses the run, comments on the GitLab merge request, and fails the build only on failures that need a person | Your CI is not GitHub Actions |

package/dist/cli/tewip.js

@@ -38,6 +38,13 @@ Usage:
                                     File the plan's scenarios as test-case issues, linked to the
                                     story. Shows what it would create; --create actually files
                                     them, and the same scenario is never filed twice.
+      --export xray|zephyr          Write the cases as a CSV for Xray or Zephyr Scale instead.
+                                    No account needed; importing stays your step.
+  tewip bugs <report> --project PROJ [--create] [--max 5]
+                                    File a bug ticket for each failure Tewip diagnosed as a real
+                                    bug, with its evidence and run link. A flaky test or a broken
+                                    environment is deliberately not filed, and the same failure is
+                                    never filed twice.
   tewip secure [--url http://localhost:3000] [--secrets-only] [--gate] [--out security.md]
                                     Runs the scanners this project already has (npm audit,
                                     pip-audit, osv-scanner) plus Tewip's own secret scan, then says
@@ -148,12 +155,20 @@ async function main() {
         case 'jira': {
             const planFile = args.find((a) => a.endsWith('.json'));
             const project = flag(args, 'project');
-            if (!planFile || !project)
-                throw new Error('usage: tewip jira <plan.json> --project PROJ [--issue PROJ-123] [--type "Test"] [--only QS-001,QS-002] [--create]');
+            // Writing a file for a test-management tool needs no project at all.
+            if (!planFile || (!project && !flag(args, 'export'))) {
+                throw new Error(['usage: tewip jira <plan.json> --project PROJ [--issue PROJ-123] [--only QS-001,QS-002] [--create]', '   or: tewip jira <plan.json> --export xray|zephyr [--out cases.csv]'].join('\n'));
+            }
             const { runJira } = await import('../engine/work/jira-command.js');
+            const exportAs = flag(args, 'export');
+            if (exportAs && exportAs !== 'xray' && exportAs !== 'zephyr')
+                throw new Error('--export takes xray or zephyr');
             await runJira({
                 planFile,
-                projectKey: project,
+                // An export needs no project at all; filing into Jira has already been checked to have one.
+                projectKey: project ?? '',
+                exportAs: exportAs,
+                out: flag(args, 'out'),
                 type: flag(args, 'type'),
                 issueKey: flag(args, 'issue'),
                 create: args.includes('--create'),
@@ -161,6 +176,22 @@ async function main() {
             });
             return;
         }
+        case 'bugs': {
+            const report = args.find((a, i) => !a.startsWith('--') && !['--project', '--max'].includes(args[i - 1] ?? ''));
+            const project = flag(args, 'project');
+            if (!report || !project)
+                throw new Error('usage: tewip bugs <report.xml | reports-dir | blob-report-dir> --project PROJ [--create] [--max 5]');
+            process.env.TEWIP_LLM_CACHE ??= join(process.cwd(), '.tewip', 'llm-cache.jsonl');
+            const { runBugs } = await import('../engine/work/bug-command.js');
+            await runBugs({
+                root: process.cwd(),
+                report,
+                projectKey: project,
+                create: args.includes('--create'),
+                max: Math.max(1, Number(flag(args, 'max')) || 5),
+            });
+            return;
+        }
         case 'secure': {
             const { runSecure } = await import('../engine/secure/secure-command.js');
             const items = await runSecure({

package/dist/engine/work/bug-command.js

@@ -0,0 +1,135 @@
+// Phase 10, the third direction: a failure that really is a bug becomes a bug ticket, with the
+// evidence that makes it one. A failure that is a flaky test or a broken environment does not -
+// that is the whole point. Filing everything is what people already do, and it is why nobody reads
+// the tickets.
+//
+// The same restraint as the rest: nothing is created without --create, the same failure is never
+// filed twice (a second sighting is a comment on the ticket Tewip itself opened), and no ticket is
+// ever moved, assigned or closed.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { loadCorrections } from '../corrections.js';
+import { HistoryIndex } from '../history.js';
+import { importJunit } from '../import/junit.js';
+import { importBlobReportDir } from '../import/blob.js';
+import { llmFromEnv } from '../llm/client.js';
+import { buildItems } from '../../outlets/items.js';
+import { ciFacts } from '../ci/platform.js';
+import { Jira, jiraFromEnv, jiraHelp } from './jira.js';
+import { TEWIP_LABEL } from './jira-command.js';
+/** Bugs Tewip filed carry this as well, so a second run finds them and does not file again. */
+export const BUG_LABEL = 'tewip-bug';
+const isBlobDir = (path) => statSync(path).isDirectory() && readdirSync(path).some((f) => /^report.*\.zip$/.test(f));
+/** The bug report a developer actually wants: what failed, what it did, and why Tewip believes it. */
+export function bugBody(item, runUrl) {
+    return [
+        `The test "${item.title}" failed, and Tewip diagnosed a real bug in the application rather than a problem with the test.`,
+        '',
+        `Test: ${item.testId}`,
+        `File: ${item.file}`,
+        item.commit ? `Commit: ${item.commit}` : '',
+        runUrl ? `Run: ${runUrl}` : '',
+        '',
+        'What the test saw:',
+        item.errorHead,
+        '',
+        `Diagnosis: ${item.diagnosis.category} at ${item.diagnosis.confidence.toFixed(2)} confidence (${item.source}).`,
+        '',
+        'Evidence:',
+        ...item.evidence.slice(0, 6).map((line) => `- ${line}`),
+        '',
+        `Suggested next step: ${item.action.summary}`,
+        '',
+        'Filed by Tewip because this failure looks like the application being wrong, not the test. If it',
+        'is not, say so on the failure in CI (/triage CATEGORY #n reason) and Tewip will answer with your',
+        'decision next time instead of its own.',
+    ]
+        .filter((line) => line !== '')
+        .join('\n');
+}
+/** A short line for a ticket that already exists: the same bug, seen again. */
+export const seenAgain = (item, runUrl) => `Seen again: "${item.title}" failed in ${runUrl || 'another run'}${item.commit ? ` on ${item.commit.slice(0, 8)}` : ''}. Tewip still reads it as a real bug (${item.diagnosis.confidence.toFixed(2)}).`;
+/**
+ * A title that stays the same across runs, so the same failure is recognised next time. The area is
+ * added only when it says something the title does not: "checkout (checkout)" helps nobody.
+ */
+export function bugSummary(item) {
+    const where = (item.component || item.file || '').trim();
+    const same = !where || item.title.toLowerCase().includes(where.toLowerCase());
+    return (same ? item.title : `${item.title} (${where})`).replace(/\s+/g, ' ').slice(0, 250);
+}
+export async function runBugs(cmd) {
+    const config = jiraFromEnv();
+    // A dry run answers the question people ask first - "what would it file?" - and needs no account
+    // at all. Only --create talks to Jira.
+    if (cmd.create && !config?.token)
+        throw new Error(`filing a bug needs a token: showing what would be filed does not.\n${jiraHelp()}`);
+    const path = resolve(cmd.report);
+    if (!existsSync(path))
+        throw new Error(`no such report: ${cmd.report}`);
+    const facts = ciFacts();
+    const name = basename(statSync(path).isDirectory() ? path : dirname(path)).replace(/[^\w.-]+/g, '-');
+    const historyDir = join(cmd.root, '.tewip', 'history', name);
+    const meta = { runId: facts.runId || `local-${Date.now()}`, gitSha: facts.sha, workspace: cmd.root };
+    const imported = isBlobDir(path) ? importBlobReportDir(path, meta, join(historyDir, 'files')) : importJunit(path, meta);
+    const index = new HistoryIndex(imported.records, [imported.summary]);
+    const items = await buildItems(imported.records, index, { dataset: `local: ${name}`, llm: llmFromEnv(), corrections: loadCorrections(historyDir) });
+    // Only what Tewip itself calls a bug, and only when it is confident enough to put a person's name
+    // on it. Everything else is deliberately left out.
+    const bugs = items.filter((i) => i.diagnosis.category === 'REAL_BUG' && i.diagnosis.confidence >= 0.8);
+    const lines = [`Report: ${cmd.report}`, `Project: ${cmd.projectKey}`, ''];
+    if (items.length === 0) {
+        console.log('Every test in that report passed. Nothing to file.');
+        return [];
+    }
+    if (bugs.length === 0) {
+        const kinds = [...new Set(items.map((i) => i.diagnosis.category))].join(', ');
+        console.log(`${items.length} failure(s), and none of them is a real bug Tewip is confident about (${kinds}). Nothing was filed, which is the point.`);
+        return [];
+    }
+    const jira = config?.token ? new Jira(config) : null;
+    let type = 'Bug';
+    let existing = [];
+    if (jira) {
+        const types = await jira.issueTypes(cmd.projectKey);
+        type = ['Bug', 'Defect', 'Task'].find((t) => types.includes(t)) ?? types[0];
+        if (!type)
+            throw new Error(`no issue type available in ${cmd.projectKey}`);
+        existing = await jira.findByLabel(cmd.projectKey, BUG_LABEL);
+    }
+    else {
+        lines.push('Jira was not contacted: this is what would be filed. Set TEWIP_JIRA_URL, TEWIP_JIRA_EMAIL and TEWIP_JIRA_TOKEN, then add --create.', '');
+    }
+    let filed = 0;
+    for (const item of bugs.slice(0, cmd.max)) {
+        const summary = bugSummary(item);
+        const already = existing.find((i) => i.summary === summary);
+        if (already) {
+            lines.push(`  ${item.title}  already filed as ${already.key}`);
+            if (cmd.create && jira) {
+                await jira.comment(already.key, seenAgain(item, facts.runUrl)).catch(() => lines.push(`    (could not add the note to ${already.key})`));
+                lines.push(`    added a note that it happened again`);
+            }
+            continue;
+        }
+        if (!cmd.create || !jira) {
+            lines.push(`  would file: ${summary}`);
+            lines.push(`      because: ${item.diagnosis.category} at ${item.diagnosis.confidence.toFixed(2)} - ${item.errorHead.replace(/\s+/g, ' ').slice(0, 100)}`);
+            continue;
+        }
+        const key = await jira.createIssue({
+            projectKey: cmd.projectKey,
+            type,
+            summary,
+            description: bugBody(item, facts.runUrl),
+            labels: [TEWIP_LABEL, BUG_LABEL, `tewip-${item.component.replace(/[^\w-]+/g, '-')}`.slice(0, 40)],
+        });
+        lines.push(`  filed ${key}: ${summary}`);
+        filed++;
+    }
+    const left = items.length - bugs.length;
+    lines.push('', `${bugs.length} of ${items.length} failure(s) look like real bugs; ${left} were flaky tests, environment or test data and were deliberately not filed.`);
+    lines.push(cmd.create ? `${filed} ticket(s) created. Tewip never moves, assigns or closes one.` : 'Nothing was created. Add --create to file them.');
+    console.log(lines.join('\n'));
+    return bugs;
+}

package/dist/engine/work/jira-command.js

@@ -5,7 +5,10 @@
 // scenario only once: every issue it creates carries a label, so a second run finds them and skips
 // what is already there rather than making duplicates.
 import { readFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import { Jira, jiraFromEnv, jiraHelp } from './jira.js';
+import { exportTestCases, importHint } from './testcase-export.js';
 export const TEWIP_LABEL = 'tewip';
 /** One test case, written the way a person reads it rather than as JSON. */
 export function issueBody(scenario, feature, source) {
@@ -36,9 +39,25 @@ function chosen(plan, only) {
     return plan.scenarios.filter((s) => (wanted.size ? wanted.has(s.id.toUpperCase()) : !s.covered_by));
 }
 export async function runJira(cmd) {
+    const saved0 = JSON.parse(readFileSync(cmd.planFile, 'utf8'));
+    if (cmd.exportAs) {
+        // A file for Xray or Zephyr: no account, no network, and importing stays the person's step.
+        const chosenCases = chosen(saved0.plan, cmd.only);
+        if (chosenCases.length === 0)
+            throw new Error('every scenario in the plan is already covered by a test');
+        const csv = exportTestCases({ ...saved0.plan, scenarios: chosenCases }, saved0.feature, cmd.exportAs);
+        const file = resolve(cmd.out ?? `tewip-${cmd.exportAs}.csv`);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, `${csv}\n`, 'utf8');
+        console.log(`${chosenCases.length} test case(s) for ${cmd.exportAs === 'xray' ? 'Xray' : 'Zephyr Scale'}.`);
+        console.log(importHint(cmd.exportAs, file));
+        return;
+    }
     const config = jiraFromEnv();
     if (!config)
         throw new Error(jiraHelp());
+    if (!config.token)
+        throw new Error(`filing test cases needs a token: reading a public tracker is free, writing to one is not.\n${jiraHelp()}`);
     const jira = new Jira(config);
     const saved = JSON.parse(readFileSync(cmd.planFile, 'utf8'));
     const scenarios = chosen(saved.plan, cmd.only);

package/dist/engine/work/jira.js

@@ -109,6 +109,10 @@ export class Jira {
     }
     /** A description is a document tree on Cloud and a string of wiki markup everywhere else. */
     bodyFor(version, body) {
+        const asComment = body;
+        if (typeof asComment.body === 'string') {
+            return version === 2 ? body : { body: { type: 'doc', version: 1, content: [{ type: 'paragraph', content: [{ type: 'text', text: asComment.body.slice(0, 30_000) }] }] } };
+        }
         const fields = body.fields;
         if (!fields || typeof fields.description !== 'string')
             return body;
@@ -140,6 +144,13 @@ export class Jira {
         });
         return created.key;
     }
+    /**
+     * A note on a ticket Tewip itself opened - never on anyone else's. The caller finds the ticket by
+     * Tewip's own label, which is the only way it recognises its own work.
+     */
+    async comment(key, text) {
+        await this.request('POST', `/issue/${encodeURIComponent(key)}/comment`, { body: text });
+    }
     /** Links a created issue to the ticket it came from, the only relationship Tewip makes. */
     async link(fromKey, toKey, type = 'Relates') {
         await this.request('POST', '/issueLink', { type: { name: type }, inwardIssue: { key: fromKey }, outwardIssue: { key: toKey } });

package/dist/engine/work/testcase-export.js

@@ -0,0 +1,75 @@
+/** One cell of a CSV, quoted the way every spreadsheet and importer expects. */
+export function cell(value) {
+    const text = String(value ?? '').replace(/\r?\n/g, '\n');
+    return /[",\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+const row = (cells) => cells.map(cell).join(',');
+/** Xray's manual-test import: the test is repeated on every step row, as its importer expects. */
+export function toXrayCsv(plan, feature) {
+    const header = ['Issue ID', 'Summary', 'Description', 'Test Type', 'Action', 'Data', 'Expected Result', 'Priority', 'Labels'];
+    const lines = [row(header)];
+    for (const s of plan.scenarios) {
+        const steps = s.steps.length > 0 ? s.steps : ['(see the expected result)'];
+        steps.forEach((step, index) => {
+            lines.push(row([
+                s.id,
+                index === 0 ? `${s.id} ${s.title}` : '',
+                index === 0 ? describe(s, feature) : '',
+                index === 0 ? 'Manual' : '',
+                step,
+                index === 0 ? s.preconditions : '',
+                index === steps.length - 1 ? s.expected : '',
+                index === 0 ? priority(s.priority) : '',
+                index === 0 ? `tewip ${s.type}` : '',
+            ]));
+        });
+    }
+    return lines.join('\n');
+}
+/** Zephyr Scale's test-case import, whose columns are named differently for the same idea. */
+export function toZephyrCsv(plan, feature) {
+    const header = ['Name', 'Objective', 'Precondition', 'Priority', 'Status', 'Labels', 'Folder', 'Step', 'Test Data', 'Expected Result'];
+    const lines = [row(header)];
+    for (const s of plan.scenarios) {
+        const steps = s.steps.length > 0 ? s.steps : ['(see the expected result)'];
+        steps.forEach((step, index) => {
+            lines.push(row([
+                index === 0 ? `${s.id} ${s.title}` : '',
+                index === 0 ? describe(s, feature) : '',
+                index === 0 ? s.preconditions : '',
+                index === 0 ? priority(s.priority) : '',
+                index === 0 ? 'Draft' : '',
+                index === 0 ? `tewip,${s.type}` : '',
+                index === 0 ? `/${feature.replace(/[^\w -]+/g, '').slice(0, 60)}` : '',
+                step,
+                '',
+                index === steps.length - 1 ? s.expected : '',
+            ]));
+        });
+    }
+    return lines.join('\n');
+}
+const PRIORITY = { P0: 'High', P1: 'Medium', P2: 'Low' };
+const priority = (p) => PRIORITY[p] ?? 'Medium';
+/** What the case is for, and where it came from, so a reviewer can judge it. */
+function describe(s, feature) {
+    return [
+        s.title,
+        `Feature: ${feature}`,
+        `Type: ${s.type}`,
+        s.grounded_on ? `Grounded on: ${s.grounded_on}` : '',
+        s.covered_by ? `Already covered by: ${s.covered_by}` : 'Not covered by an existing test.',
+        'Drafted by Tewip; review before you rely on it.',
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+export function exportTestCases(plan, feature, format) {
+    return format === 'xray' ? toXrayCsv(plan, feature) : toZephyrCsv(plan, feature);
+}
+/** What to tell the person after writing the file, since importing is their step, not Tewip's. */
+export function importHint(format, file) {
+    return format === 'xray'
+        ? `Written to ${file}. In Jira: Xray > Import > Tests from CSV, and check the column mapping on the first screen.`
+        : `Written to ${file}. In Jira: Zephyr Scale > Test Cases > Import > CSV, and check the column mapping on the first screen.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Tewip finds why each failing test failed - real bug, flaky test, environment, test data or changed selector - for any stack, from the command line, CI, or your editor.",
   "keywords": [
     "test-failures",