spp-lang 0.0.0-stage → 0.1.0

package/dist/src/words/shared.js

@@ -0,0 +1,272 @@
+// The words every backend shares, made from what its driver can do.
+//
+// Queries are Testing Library's, spelled as Cognate words: a role name
+// (Button, Heading, Checkbox…) takes the accessible name to its right and
+// leaves an Element. Spec++ asks for exact names, as Testing Library does,
+// unless you say Containing.
+//
+// Assertions are deferred. "Then I should Not See the Button "Save"" runs See
+// before Not, so See can't just fail on the spot; it leaves an Expectation on
+// the stack for Not to flip, and every Expectation left when the step ends is
+// checked then. Likewise "the Checkbox "Terms" should be Checked": Checked
+// runs first and leaves a Matcher, the Checkbox query lands on top of it, and
+// the step's end pairs them up.
+//
+// A backend builds its vocabulary from queries(), actions() and checks(),
+// with its own words in between, like the Playwright backend's Visit.
+import { describe, SppError, unwrap } from '../language/cognate.js';
+import { called, formsFor, oneOf, TableType, TextType, type } from '../language/types.js';
+// ---------------------------------------------------------------- values
+export class Pattern {
+    text;
+    regex;
+    constructor(text) {
+        this.text = text;
+        this.regex = new RegExp(escapeRegExp(text), 'i');
+    }
+    describe() {
+        return `Containing ${JSON.stringify(this.text)}`;
+    }
+}
+export class Scope {
+    found;
+    constructor(found) {
+        this.found = found;
+    }
+    describe() {
+        return `Within ${this.found.describe()}`;
+    }
+}
+// A driver's handle that remembers the words that made it, for error messages.
+export class Found {
+    handle;
+    label;
+    constructor(handle, label) {
+        this.handle = handle;
+        this.label = label;
+    }
+    describe() {
+        return this.label;
+    }
+}
+export class Matcher {
+    label;
+    state;
+    negated;
+    constructor(label, state, negated = false) {
+        this.label = label;
+        this.state = state;
+        this.negated = negated;
+    }
+    negate() {
+        return new Matcher(this.label, this.state, !this.negated);
+    }
+    against(target, ctx, driver) {
+        return new Expectation(`${target.label} ${this.describe()}`, (not) => driver.expect(ctx, target.handle, this.state, this.negated !== not));
+    }
+    describe() {
+        return (this.negated ? 'Not ' : '') + this.label;
+    }
+}
+// check(not) runs the assertion, inverted when not is true.
+export class Expectation {
+    label;
+    check;
+    constructor(label, check) {
+        this.label = label;
+        this.check = check;
+    }
+    negate() {
+        return new Expectation(`Not ${this.label}`, (not) => this.check(!not));
+    }
+    describe() {
+        return this.label;
+    }
+}
+// ---------------------------------------------------------------- types
+export const ElementType = type('Element', 'something on the page', (v) => v instanceof Found);
+export const PatternType = type('Pattern', 'Containing "some text"', (v) => v instanceof Pattern);
+export const NameType = oneOf('some text', TextType, PatternType);
+export const ScopeType = type('Scope', 'Within something', (v) => v instanceof Scope);
+export const MatcherType = type('Matcher', 'a check', (v) => v instanceof Matcher);
+export const CheckType = type('Check', 'a check', (v) => v instanceof Expectation);
+const QueryName = called(NameType, 'a "name" to look for');
+// The shared words run with whatever context their driver wants.
+const form = formsFor();
+// ---------------------------------------------------------------- helpers
+export const nameOf = (v) => (v instanceof Pattern ? v.regex : v);
+export const say = (v) => (v instanceof Pattern ? v.describe() : JSON.stringify(v));
+export function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+const cap = (s) => s[0].toUpperCase() + s.slice(1);
+// Verbs that take a thing and some text accept them in either order, so
+// "Fill the Field "Email" with "a@b"" and "Fill "a@b" into the Field "Email""
+// both work.
+function eitherOrder(act) {
+    return [
+        form([ElementType, TextType], (ctx, found, text) => act(ctx, found, text)),
+        form([TextType, ElementType], (ctx, text, found) => act(ctx, found, text)),
+    ];
+}
+// ---------------------------------------------------------------- queries
+// The word for each kind of query that isn't by role.
+const QUERY_WORDS = [
+    ['label', 'Field', 'Label'],
+    ['text', 'Text'],
+    ['placeholder', 'Placeholder'],
+    ['alt', 'Alt'],
+    ['title', 'Title'],
+    ['testId', 'TestId'],
+];
+// Finding things: a word for each role and query the driver has, then
+// Containing and Within.
+export function queries(env, driver) {
+    env.kind(ElementType);
+    // A query finds by name, within a Scope if one comes after it.
+    const query = (word, by) => {
+        const found = (ctx, root, name, within = '') => new Found(driver.find(ctx, root?.handle ?? null, by(nameOf(name))), `the ${word} ${say(name)}${within}`);
+        return [
+            form([QueryName, ScopeType], ElementType, (ctx, name, scope) => found(ctx, scope.found, name, ` within ${scope.found.label}`)),
+            form([QueryName], ElementType, (ctx, name) => found(ctx, null, name)),
+        ];
+    };
+    for (const role of driver.roles)
+        env.word(cap(role), ...query(cap(role), (name) => ({ by: 'role', role, name })));
+    for (const [kind, ...words] of QUERY_WORDS) {
+        if (!driver.queries.includes(kind))
+            continue;
+        // Synonyms share their forms, and so describe what they found the same way.
+        const forms = query(words[0], (name) => ({ by: kind, name }));
+        for (const word of words)
+            env.word(word, ...forms);
+    }
+    env.word('Containing', form([TextType], PatternType, (_, text) => new Pattern(text)));
+    const within = form([called(ElementType, 'something on the page to look inside')], ScopeType, (_, found) => new Scope(found));
+    return env.word('Within', within).word('In', within);
+}
+const ACTION_WORDS = [
+    ['click', 'Click'],
+    ['double-click', 'Double-click'],
+    ['hover', 'Hover'],
+    ['focus', 'Focus'],
+    ['check', 'Check'],
+    ['uncheck', 'Uncheck'],
+    ['clear', 'Clear'],
+];
+// Doing things, as far as the driver can.
+export function actions(env, driver) {
+    const can = (a) => driver.actions.includes(a);
+    const act = (ctx, found, action) => driver.act(ctx, found.handle, action);
+    for (const [action, word] of ACTION_WORDS) {
+        if (can(action))
+            env.word(word, form([ElementType], (ctx, found) => act(ctx, found, { do: action })));
+    }
+    if (can('fill')) {
+        const fill = eitherOrder((ctx, found, text) => act(ctx, found, { do: 'fill', text }));
+        // a table of label | value rows
+        if (driver.queries.includes('label'))
+            fill.push(form([TableType], async (ctx, rows) => {
+                for (const [label, value] of rows)
+                    await driver.act(ctx, driver.find(ctx, null, { by: 'label', name: label }), { do: 'fill', text: value });
+            }));
+        env.word('Fill', ...fill);
+    }
+    if (can('type'))
+        env.word('Type', ...eitherOrder((ctx, found, text) => act(ctx, found, { do: 'type', text })));
+    if (can('select'))
+        env.word('Select', ...eitherOrder((ctx, found, text) => act(ctx, found, { do: 'select', text })));
+    if (can('press')) {
+        const Key = called(TextType, 'a "Key" to press');
+        env.word('Press', form([Key, ElementType], (ctx, key, found) => act(ctx, found, { do: 'press', key })), form([Key], (ctx, key) => driver.press(ctx, key)));
+    }
+    return env;
+}
+const STATE_WORDS = [
+    ['visible', 'Visible'],
+    ['hidden', 'Hidden'],
+    ['checked', 'Checked'],
+    ['enabled', 'Enabled'],
+    ['disabled', 'Disabled'],
+    ['focused', 'Focused'],
+    ['empty', 'Empty'],
+];
+// The states that take some text, like Value "eggs".
+const TEXT_STATE_WORDS = [
+    ['value', 'Value'],
+    ['text', 'Read'],
+    ['containing', 'Contain'],
+];
+// Checking things: See, a word for each state the driver can check, and Not.
+export function checks(env, driver) {
+    const can = (s) => driver.states.includes(s);
+    if (can('visible')) {
+        const visible = new Matcher('Visible', { is: 'visible' });
+        const see = [form([ElementType], CheckType, (ctx, found) => visible.against(found, ctx, driver))];
+        if (driver.queries.includes('text'))
+            see.push(form([NameType], CheckType, (ctx, text) => {
+                const handle = driver.find(ctx, null, { by: 'text', name: nameOf(text), loose: true });
+                return visible.against(new Found(handle, `the text ${say(text)}`), ctx, driver);
+            }));
+        env.word('See', ...see);
+    }
+    for (const [is, word] of STATE_WORDS) {
+        if (can(is))
+            env.word(word, form([], MatcherType, () => new Matcher(word, { is })));
+    }
+    for (const [is, word] of TEXT_STATE_WORDS) {
+        if (can(is))
+            env.word(word, form([NameType], MatcherType, (_, v) => new Matcher(`${word} ${say(v)}`, { is, text: nameOf(v) })));
+    }
+    return env.word('Not', form([MatcherType], MatcherType, (_, m) => m.negate()), form([CheckType], CheckType, (_, c) => c.negate()));
+}
+// ---------------------------------------------------------------- the end of a step
+// What's wrong with a step that leaves these behind, said the same way by
+// leftovers and settle.
+const unchecked = (matcher) => `Nothing to check is ${matcher}. Put what should be ${matcher} before it.`;
+const unused = (values) => `Nothing used ${values.join(', ')}. Is the step missing a verb?`;
+// settle's rule, for the checker: what settle would say about a step that
+// leaves values of these types, or null if it would be happy.
+export function leftovers(stack) {
+    const rest = [...stack];
+    for (let v = rest.pop(); v; v = rest.pop()) {
+        if (v.name === CheckType.name)
+            continue;
+        if (v.name === ElementType.name && rest.at(-1)?.name === MatcherType.name) {
+            rest.pop();
+            continue;
+        }
+        if (v.name === MatcherType.name)
+            return unchecked(v.shown);
+        return unused([v, ...rest.reverse()].map((x) => x.shown));
+    }
+    return null;
+}
+// A settle for a driver: it checks whatever assertions a step left behind.
+// Anything else left over is a sentence with no verb, which is almost always
+// a mistake worth saying so.
+export function settler(driver) {
+    return async function settle(stack, ctx) {
+        const pending = [];
+        while (stack.length) {
+            // A noun's value is checked as what it is underneath.
+            const v = unwrap(stack.pop());
+            const under = unwrap(stack.at(-1));
+            if (v instanceof Expectation)
+                pending.push(v);
+            else if (v instanceof Found && under instanceof Matcher) {
+                stack.pop();
+                pending.push(under.against(v, ctx, driver));
+            }
+            else if (v instanceof Matcher) {
+                throw new SppError(unchecked(v.describe()));
+            }
+            else {
+                throw new SppError(unused([v, ...stack.reverse()].map(describe)));
+            }
+        }
+        // Checked in reading order: the stack holds them right to left.
+        for (const e of pending.reverse())
+            await e.check(false);
+    };
+}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "spp-lang",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Specs that run. Written by agents, read by people.",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "spp-lang": "dist/bin/spp-lang.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc",
+    "lint": "biome check",
+    "format": "biome check --write",
+    "test": "node --test 'test/**/*.test.ts'",
+    "test:e2e": "playwright test",
+    "demo": "node examples/demo/serve.ts",
+    "prepack": "npm run build",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "gherkin",
+    "cucumber",
+    "bdd",
+    "playwright",
+    "testing-library",
+    "cognate"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/willmartian/spp-lang.git"
+  },
+  "dependencies": {
+    "@cucumber/gherkin": "^42.0.1",
+    "@cucumber/messages": "^34.2.1",
+    "commander": "^15.0.0",
+    "vscode-languageserver": "^10.1.2",
+    "vscode-languageserver-textdocument": "^1.0.15"
+  },
+  "peerDependencies": {
+    "@playwright/test": "^1.63.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@commitlint/cli": "^21.2.3",
+    "@commitlint/config-conventional": "^21.2.3",
+    "@playwright/test": "^1.63.0",
+    "@types/node": "^26.6.3",
+    "husky": "^9.1.7",
+    "typescript": "^7.0.2"
+  }
+}