@hover-dev/core 0.15.0 → 0.16.0

package/dist/specs/softBatch.js

@@ -0,0 +1,177 @@
+/**
+ * soft-batch — a deterministic finishing step of the optimization pass.
+ *
+ * After the LLM optimize pass decides WHAT to assert (it reads the observed
+ * feedback and adds the trailing "Then" assertions), this step applies the safe
+ * mechanical rewrite: the maximal *trailing run* of independent assertions in
+ * each `test()` body goes from `expect(...)` to `expect.soft(...)`, so a
+ * field-audit spec reports every failing field in one run instead of halting on
+ * the first. This is the "LLM decides, AST executes" split — the LLM never
+ * reprints the file to do it, so it can't drift; ts-morph applies the soften
+ * surgically and every untouched node stays byte-identical.
+ *
+ * Two assertion shapes are recognised, because that is what specs look like
+ * after optimize:
+ *   A. a bare `await expect(...)....` statement;
+ *   B. a Hover `await test.step('Then · …', async () => { await expect(...) })`
+ *      closure whose body is nothing but assertions — Hover emits one such step
+ *      per observed-feedback assertion, AFTER all the action steps.
+ *
+ * Safety guard (why this is deterministic and never changes test semantics):
+ * we only ever soften an assertion that sits in the trailing run — the suffix
+ * of the test body that is assertions all the way down, with no action after
+ * it. A *gating* assertion — one a later action depends on — is by construction
+ * followed by that action, so it never lands in the trailing run and is never
+ * softened. Softening only changes how failures are *reported* (all collected
+ * vs. stop-on-first), never whether the test passes. We require ≥2 assertions
+ * in the run: soft buys nothing for a single one. `expect.soft` collects across
+ * the whole test regardless of `test.step` nesting, so softening step-wrapped
+ * assertions is sound.
+ */
+import { Project, SyntaxKind, Node } from 'ts-morph';
+/** A trailing run with fewer than this many assertions is left alone —
+ *  `expect.soft` only earns its keep when ≥2 failures could be collected. */
+export const MIN_RUN = 2;
+/** Run the soft-batch step over a spec's source text. Pure: text in, text out. */
+export function softBatch(source) {
+    const project = new Project({
+        useInMemoryFileSystem: true,
+        compilerOptions: { allowJs: true },
+    });
+    const sf = project.createSourceFile('__spec.ts', source, { overwrite: true });
+    // Collect every assertion to soften first (across all test bodies), then
+    // apply — each edit is a localized identifier replace, so sibling targets
+    // stay valid.
+    const targets = [];
+    for (const body of testBodies(sf)) {
+        const run = trailingAssertionRun(body.getStatements());
+        const asserts = run.flatMap(bareAssertionsIn);
+        if (asserts.length >= MIN_RUN)
+            targets.push(...asserts);
+    }
+    let softened = 0;
+    for (const stmt of targets) {
+        if (soften(stmt))
+            softened++;
+    }
+    return { code: sf.getFullText(), changed: softened > 0, softened };
+}
+/**
+ * Yield the block body of every `test(...)` call (including `test.only` /
+ * `.skip` / `.fixme`), but NOT `test.describe` / hooks — those wrap tests, they
+ * aren't a test body.
+ */
+function testBodies(sf) {
+    const bodies = [];
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        if (!isTestCall(call.getExpression()))
+            continue;
+        const cb = call.getArguments().at(-1);
+        if (!cb)
+            continue;
+        if (Node.isArrowFunction(cb) || Node.isFunctionExpression(cb)) {
+            const block = cb.getBody();
+            if (Node.isBlock(block))
+                bodies.push(block);
+        }
+    }
+    return bodies;
+}
+/** `test` | `test.only` | `test.skip` | `test.fixme` — not `test.describe` or hooks. */
+function isTestCall(callee) {
+    if (Node.isIdentifier(callee))
+        return callee.getText() === 'test';
+    if (Node.isPropertyAccessExpression(callee)) {
+        const base = callee.getExpression();
+        if (!Node.isIdentifier(base) || base.getText() !== 'test')
+            return false;
+        return ['only', 'skip', 'fixme'].includes(callee.getName());
+    }
+    return false;
+}
+/** The longest suffix of `statements` that are all assertion units (a bare
+ *  assertion, or a `test.step` whose body is only assertions). */
+function trailingAssertionRun(statements) {
+    const run = [];
+    for (let i = statements.length - 1; i >= 0; i--) {
+        if (!isAssertionUnit(statements[i]))
+            break;
+        run.unshift(statements[i]);
+    }
+    return run;
+}
+/** A statement that contributes only assertions: a bare assertion (case A) or
+ *  an assertion-only `test.step` closure (case B). */
+function isAssertionUnit(stmt) {
+    return isBareAssertion(stmt) || bareAssertionsInStep(stmt) !== null;
+}
+/** The bare-assertion statements a unit contains: itself (case A) or the
+ *  assertions inside its `test.step` closure (case B). */
+function bareAssertionsIn(stmt) {
+    if (isBareAssertion(stmt))
+        return [stmt];
+    return bareAssertionsInStep(stmt) ?? [];
+}
+/** True if the statement is `(await) expect(...)....` — its call chain bottoms
+ *  out at an `expect` identifier. */
+function isBareAssertion(stmt) {
+    if (!Node.isExpressionStatement(stmt))
+        return false;
+    let expr = stmt.getExpression();
+    if (Node.isAwaitExpression(expr))
+        expr = expr.getExpression();
+    return leftmostBase(expr) === 'expect';
+}
+/**
+ * If `stmt` is `await test.step(label, async () => { …only assertions… })`,
+ * return those inner assertion statements; otherwise null. The closure body
+ * must be non-empty and contain ONLY bare assertions — a step that also acts
+ * (a "When" with a check) is not a pure assertion unit and is left alone.
+ */
+function bareAssertionsInStep(stmt) {
+    if (!Node.isExpressionStatement(stmt))
+        return null;
+    let expr = stmt.getExpression();
+    if (Node.isAwaitExpression(expr))
+        expr = expr.getExpression();
+    if (!Node.isCallExpression(expr))
+        return null;
+    const callee = expr.getExpression();
+    if (!Node.isPropertyAccessExpression(callee) ||
+        callee.getName() !== 'step' ||
+        callee.getExpression().getText() !== 'test') {
+        return null;
+    }
+    const cb = expr.getArguments().at(-1);
+    if (!cb || !(Node.isArrowFunction(cb) || Node.isFunctionExpression(cb)))
+        return null;
+    const block = cb.getBody();
+    if (!Node.isBlock(block))
+        return null;
+    const inner = block.getStatements();
+    if (inner.length === 0 || !inner.every(isBareAssertion))
+        return null;
+    return inner;
+}
+/** Descend a call/member chain to its leftmost identifier, e.g.
+ *  `expect(x).toHaveText(y)` → "expect", `page.goto('/')` → "page". */
+function leftmostBase(node) {
+    let cur = node;
+    while (cur && (Node.isCallExpression(cur) || Node.isPropertyAccessExpression(cur))) {
+        cur = cur.getExpression();
+    }
+    return cur && Node.isIdentifier(cur) ? cur.getText() : null;
+}
+/** Rewrite the `expect(` call inside a bare assertion statement to
+ *  `expect.soft(`. Skips ones already soft (their callee is `expect.soft`, not
+ *  the bare identifier `expect`). Returns whether a change was made. */
+function soften(stmt) {
+    for (const call of stmt.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const callee = call.getExpression();
+        if (Node.isIdentifier(callee) && callee.getText() === 'expect') {
+            callee.replaceWithText('expect.soft');
+            return true;
+        }
+    }
+    return false;
+}

package/dist/specs/text.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Small text helpers shared across the spec/CSV emitters.
+ *
+ * Hoisted here so the two crystallization outputs (writeSpec's JSDoc header and
+ * writeCaseCsv's Xray rows) derive a slug and a one-sentence "Expected" line the
+ * same way — they used to carry byte-identical copies of this logic.
+ */
+/** Lowercase, hyphenate, and trim a display name into a filesystem-safe slug. */
+export declare function slugify(name: string): string;
+/**
+ * The first sentence of a done-summary, trimmed. Agents sometimes ramble; the
+ * Expected blocks only want the leading sentence. Splits on the gap that
+ * follows sentence-ending punctuation (`.`, `!`, `?`); a summary with no such
+ * punctuation comes back trimmed in full.
+ */
+export declare function firstSentence(summary: string): string;
+//# sourceMappingURL=text.d.ts.map

package/dist/specs/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/specs/text.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM5C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/specs/text.js

@@ -0,0 +1,24 @@
+/**
+ * Small text helpers shared across the spec/CSV emitters.
+ *
+ * Hoisted here so the two crystallization outputs (writeSpec's JSDoc header and
+ * writeCaseCsv's Xray rows) derive a slug and a one-sentence "Expected" line the
+ * same way — they used to carry byte-identical copies of this logic.
+ */
+/** Lowercase, hyphenate, and trim a display name into a filesystem-safe slug. */
+export function slugify(name) {
+    return name
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * The first sentence of a done-summary, trimmed. Agents sometimes ramble; the
+ * Expected blocks only want the leading sentence. Splits on the gap that
+ * follows sentence-ending punctuation (`.`, `!`, `?`); a summary with no such
+ * punctuation comes back trimmed in full.
+ */
+export function firstSentence(summary) {
+    return summary.split(/(?<=[.!?])\s+/)[0]?.trim() ?? summary.trim();
+}

package/dist/specs/writeCaseCsv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writeCaseCsv.d.ts","sourceRoot":"","sources":["../../src/specs/writeCaseCsv.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,qBAAa,kBAAmB,SAAQ,KAAK;aACf,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B;;uEAEmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;+CAC2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAEnE,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiBzF"}
+{"version":3,"file":"writeCaseCsv.d.ts","sourceRoot":"","sources":["../../src/specs/writeCaseCsv.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,qBAAa,kBAAmB,SAAQ,KAAK;aACf,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B;;uEAEmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;+CAC2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAEnE,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiBzF"}

package/dist/specs/writeCaseCsv.js

@@ -31,6 +31,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { humanSteps } from './humanSteps.js';
+import { slugify, firstSentence } from './text.js';
 export class CaseCsvExistsError extends Error {
     slug;
     path;
@@ -59,13 +60,6 @@ export async function writeCaseCsv(opts) {
     return { path, slug };
 }
 // ───────── helpers ─────────
-function slugify(name) {
-    return name
-        .toLowerCase()
-        .trim()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-}
 function renderCsv(slug, opts) {
     const rows = buildRows(slug, opts);
     // CRLF row terminator — what Excel / Numbers / Xray's importer all
@@ -112,7 +106,7 @@ function expectedFor(assertions, steps) {
     }
     const done = [...steps].reverse().find(s => s.kind === 'done');
     if (done?.summary) {
-        return done.summary.split(/(?<=[.!?])\s+/)[0]?.trim() ?? done.summary.trim();
+        return firstSentence(done.summary);
     }
     return '';
 }

package/dist/specs/writeSpec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAUzD,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;0DAE0D;AAC1D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,eAAgB,SAAQ,KAAK;aACZ,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAEhE,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAiChF;AAgVD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM9E;AAED;;oCAEoC;AACpC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAqB9E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAQ1F"}
+{"version":3,"file":"writeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/writeSpec.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAWzD,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;0DAE0D;AAC1D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,eAAgB,SAAQ,KAAK;aACZ,IAAI,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA1C,IAAI,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAIvE;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAEhE,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAiChF;AAuUD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM9E;AAED;;oCAEoC;AACpC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAqB9E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,CAQ1F"}

package/dist/specs/writeSpec.js

@@ -23,6 +23,7 @@ import { humanSteps, humanStep } from './humanSteps.js';
 import { writeSidecar } from './sidecar.js';
 import { readPageObjectManifest, } from './pageObjectManifest.js';
 import { stepSignature } from './detectSharedFlows.js';
+import { slugify, firstSentence } from './text.js';
 /**
  * Marker the deterministic translator leaves where a captured action is a real
  * interaction but has no single-step Playwright translation (e.g. file upload,
@@ -80,13 +81,6 @@ export async function writeSpec(opts) {
     });
     return { path, slug };
 }
-function slugify(name) {
-    return name
-        .toLowerCase()
-        .trim()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-}
 // Escape sequences that would prematurely terminate the JSDoc block.
 // (Backtick literal of close-comment sequence omitted on purpose — see how
 // the regex below is built — to avoid recursively poisoning *this* file.)
@@ -108,8 +102,7 @@ function collectExpected(assertions, doneSummary) {
     }
     if (doneSummary && doneSummary.trim()) {
         // Take the first sentence only — agents sometimes ramble.
-        const first = doneSummary.split(/(?<=[.!?])\s+/)[0] ?? doneSummary;
-        return [first.trim()];
+        return [firstSentence(doneSummary)];
     }
     return [];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",
@@ -49,10 +49,13 @@
     "README.md"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@playwright/mcp": "0.0.75",
     "cross-spawn": "^7.0.6",
     "playwright-core": "^1.50.0",
-    "ws": "^8.20.1"
+    "ts-morph": "^28.0.0",
+    "ws": "^8.20.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",