@swedevtools/livedoc-vitest 0.2.0 → 0.3.0

package/tools/skills/resources/specifications.md

@@ -1,159 +1,159 @@
-# Specifications — Full Reference
-
-Complete reference for writing MSpec-style specification/rule tests with `@swedevtools/livedoc-vitest`.
-
-## Keywords
-
-```
-specification → rule | ruleOutline
-```
-
-## Import Block
-
-```typescript
-import { specification, rule, ruleOutline } from "@swedevtools/livedoc-vitest";
-```
-
-## Specification
-
-Top-level container grouping related rules:
-
-```typescript
-specification("Calculator Operations", (ctx) => {
-    // ctx.specification → { title, description, tags }
-});
-```
-
-## Rule
-
-Individual test cases with direct assertions:
-
-```typescript
-specification("Calculator Operations", () => {
-    rule("Adding '5' and '3' returns '8'", (ctx) => {
-        const [a, b, expected] = ctx.rule.values; // [5, 3, 8]
-        expect(a + b).toBe(expected);
-    });
-});
-```
-
-## Value Extraction
-
-### Quoted Values — auto-extracted, type-coerced
-
-```typescript
-rule("Adding '5' and '3' returns '8'", (ctx) => {
-    const [a, b, expected] = ctx.rule.values;
-    // a = 5 (number), b = 3, expected = 8
-});
-```
-
-### Named Parameters — `<name:value>` syntax
-
-```typescript
-rule("Subtracting <b:3> from <a:10> returns <expected:7>", (ctx) => {
-    const a = ctx.rule.params.a;             // 10
-    const b = ctx.rule.params.b;             // 3
-    expect(a - b).toBe(ctx.rule.params.expected); // 7
-});
-```
-
-## RuleOutline with Examples
-
-Data-driven rules. Each row in the Examples table creates a separate test:
-
-```typescript
-ruleOutline(`Discount calculations
-    Examples:
-    | price | discount | expected |
-    |   100 |       10 |       90 |
-    |   200 |       25 |      150 |
-    `, (ctx) => {
-    const result = ctx.example.price - (ctx.example.price * ctx.example.discount / 100);
-    expect(result).toBe(ctx.example.expected);
-});
-```
-
-### Combining Title Values and Example Data
-
-RuleOutline supports both title values and example table data:
-
-```typescript
-ruleOutline(`Discount of '10' percent applies to orders over '100' dollars
-    Examples:
-    | orderTotal | expectedDiscount |
-    |        150 |               15 |
-    |        200 |               20 |
-    `, (ctx) => {
-    const [discountPct, threshold] = ctx.rule.values; // From title: [10, 100]
-    const discount = ctx.example.orderTotal * (discountPct / 100); // From table
-    expect(discount).toBe(ctx.example.expectedDiscount);
-});
-```
-
-### Named Params in RuleOutline
-
-```typescript
-ruleOutline(`Applying <operation:multiply> with factor <factor:3>
-    Examples:
-    | input | expected |
-    |     5 |       15 |
-    |    10 |       30 |
-    `, (ctx) => {
-    expect(ctx.rule.params.operation).toBe("multiply");
-    expect(ctx.example.input * ctx.rule.params.factor).toBe(ctx.example.expected);
-});
-```
-
-## Descriptions and Tags
-
-```typescript
-specification(`Email Validation
-    @validation
-    Rules for validating email addresses across formats.
-    `, (ctx) => {
-    // rules...
-});
-```
-
-- **First line** = title
-- **Lines starting with `@`** = tags
-- **Remaining lines** = description
-
-## Async Rules
-
-`rule` callbacks support `async`. `specification` callbacks must be **synchronous**.
-
-```typescript
-rule("Fetching user returns valid data", async (ctx) => {
-    const user = await fetchUser(1);
-    expect(user.name).toBeTruthy();  // ✅ OK
-});
-
-specification("Test", async (ctx) => { /* ❌ NOT ALLOWED */ });
-```
-
-## Context Reference
-
-| Property | Type | Description |
-| --- | --- | --- |
-| `ctx.specification` | `SpecificationContext` | `{title, description, tags}` |
-| `ctx.rule` | `RuleContext` | `{title, description, tags, specification, values, valuesRaw, params, paramsRaw}` |
-| `ctx.example` | `object` | Current example row (ruleOutline only) |
-
-### RuleContext Properties
-
-| Property | Returns |
-| --- | --- |
-| `values` | Coerced quoted values array |
-| `valuesRaw` | Raw string values |
-| `params` | Coerced named values object `<n:v>` |
-| `paramsRaw` | Raw named values string object |
-
-## Validation Checklist
-
-- [ ] All test data appears in rule title strings (self-documenting)
-- [ ] Descriptions provided on `specification` blocks
-- [ ] Values extracted via `ctx.rule.values`, `ctx.rule.params`, or `ctx.example`
-- [ ] Async only on `rule` callbacks, not `specification`
-- [ ] File name ends in `.Spec.ts`
+# Specifications — Full Reference
+
+Complete reference for writing MSpec-style specification/rule tests with `@swedevtools/livedoc-vitest`.
+
+## Keywords
+
+```
+specification → rule | ruleOutline
+```
+
+## Import Block
+
+```typescript
+import { specification, rule, ruleOutline } from "@swedevtools/livedoc-vitest";
+```
+
+## Specification
+
+Top-level container grouping related rules:
+
+```typescript
+specification("Calculator Operations", (ctx) => {
+    // ctx.specification → { title, description, tags }
+});
+```
+
+## Rule
+
+Individual test cases with direct assertions:
+
+```typescript
+specification("Calculator Operations", () => {
+    rule("Adding '5' and '3' returns '8'", (ctx) => {
+        const [a, b, expected] = ctx.rule.values; // [5, 3, 8]
+        expect(a + b).toBe(expected);
+    });
+});
+```
+
+## Value Extraction
+
+### Quoted Values — auto-extracted, type-coerced
+
+```typescript
+rule("Adding '5' and '3' returns '8'", (ctx) => {
+    const [a, b, expected] = ctx.rule.values;
+    // a = 5 (number), b = 3, expected = 8
+});
+```
+
+### Named Parameters — `<name:value>` syntax
+
+```typescript
+rule("Subtracting <b:3> from <a:10> returns <expected:7>", (ctx) => {
+    const a = ctx.rule.params.a;             // 10
+    const b = ctx.rule.params.b;             // 3
+    expect(a - b).toBe(ctx.rule.params.expected); // 7
+});
+```
+
+## RuleOutline with Examples
+
+Data-driven rules. Each row in the Examples table creates a separate test:
+
+```typescript
+ruleOutline(`Discount calculations
+    Examples:
+    | price | discount | expected |
+    |   100 |       10 |       90 |
+    |   200 |       25 |      150 |
+    `, (ctx) => {
+    const result = ctx.example.price - (ctx.example.price * ctx.example.discount / 100);
+    expect(result).toBe(ctx.example.expected);
+});
+```
+
+### Combining Title Values and Example Data
+
+RuleOutline supports both title values and example table data:
+
+```typescript
+ruleOutline(`Discount of '10' percent applies to orders over '100' dollars
+    Examples:
+    | orderTotal | expectedDiscount |
+    |        150 |               15 |
+    |        200 |               20 |
+    `, (ctx) => {
+    const [discountPct, threshold] = ctx.rule.values; // From title: [10, 100]
+    const discount = ctx.example.orderTotal * (discountPct / 100); // From table
+    expect(discount).toBe(ctx.example.expectedDiscount);
+});
+```
+
+### Named Params in RuleOutline
+
+```typescript
+ruleOutline(`Applying <operation:multiply> with factor <factor:3>
+    Examples:
+    | input | expected |
+    |     5 |       15 |
+    |    10 |       30 |
+    `, (ctx) => {
+    expect(ctx.rule.params.operation).toBe("multiply");
+    expect(ctx.example.input * ctx.rule.params.factor).toBe(ctx.example.expected);
+});
+```
+
+## Descriptions and Tags
+
+```typescript
+specification(`Email Validation
+    @validation
+    Rules for validating email addresses across formats.
+    `, (ctx) => {
+    // rules...
+});
+```
+
+- **First line** = title
+- **Lines starting with `@`** = tags
+- **Remaining lines** = description
+
+## Async Rules
+
+`rule` callbacks support `async`. `specification` callbacks must be **synchronous**.
+
+```typescript
+rule("Fetching user returns valid data", async (ctx) => {
+    const user = await fetchUser(1);
+    expect(user.name).toBeTruthy();  // ✅ OK
+});
+
+specification("Test", async (ctx) => { /* ❌ NOT ALLOWED */ });
+```
+
+## Context Reference
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `ctx.specification` | `SpecificationContext` | `{title, description, tags}` |
+| `ctx.rule` | `RuleContext` | `{title, description, tags, specification, values, valuesRaw, params, paramsRaw}` |
+| `ctx.example` | `object` | Current example row (ruleOutline only) |
+
+### RuleContext Properties
+
+| Property | Returns |
+| --- | --- |
+| `values` | Coerced quoted values array |
+| `valuesRaw` | Raw string values |
+| `params` | Coerced named values object `<n:v>` |
+| `paramsRaw` | Raw named values string object |
+
+## Validation Checklist
+
+- [ ] All test data appears in rule title strings (self-documenting)
+- [ ] Descriptions provided on `specification` blocks
+- [ ] Values extracted via `ctx.rule.values`, `ctx.rule.params`, or `ctx.example`
+- [ ] Async only on `rule` callbacks, not `specification`
+- [ ] File name ends in `.Spec.ts`

package/tools/skills/resources/test-strategy.md

@@ -0,0 +1,103 @@
+# Test Strategy and False-Green Prevention
+
+Use this resource before choosing LiveDoc syntax. The goal is not to convert
+every test. The goal is to publish the smallest trustworthy test whose result
+has lasting documentation value.
+
+## The Two-Question Litmus
+
+A test earns its place only when both answers are yes:
+
+1. **Would it survive a from-scratch rewrite that kept the same promise?**
+2. **Would it fail if that promise broke?**
+
+If the first answer is no, the test probably asserts implementation mechanism.
+If the second answer is no, the test is vacuous or measures the wrong thing.
+
+## Write a Compact Test Brief
+
+Before generating code, identify:
+
+| Field | Question |
+| --- | --- |
+| Claim | What externally meaningful fact must remain true? |
+| Boundary | What must observe that fact: pure code, component, HTTP service, browser, process, filesystem, or source tree? |
+| Oracle | Where does the expected result come from independently of production code? |
+| Determinism | What clock, promise, scheduler, process, port, or fixture must be controlled? |
+| Falsification | What realistic defect must make this test fail? |
+| Owner | Does an existing test already own this behavior? |
+
+Do not generate a LiveDoc test when the claim or observable boundary is unclear.
+
+## Select the Lowest Trustworthy Level
+
+| Claim | Recommended boundary | LiveDoc pattern |
+| --- | --- | --- |
+| Pure calculation, parser, formatter, or domain rule | In-process | `specification` / `rule` |
+| Stateful component behavior | Component integration | Specification or focused Feature |
+| Stakeholder-readable workflow | Smallest realistic workflow | `feature` / `scenario` |
+| Serialization or public payload shape | Complete contract comparison | Rule or outline |
+| Public HTTP behavior | Test server or real HTTP service | Feature or HTTP contract test |
+| Browser layout, focus, scrolling, accessibility tree, or pixels | Real browser | Feature with behavioral assertion and optional evidence |
+| Source/repository policy | AST or filesystem governance test | Rule when the result is useful documentation |
+| Fuzz, property, load, benchmark, or soak testing | Native specialist tool | Optional summary rule, not thousands of published cases |
+
+## Feature or Specification?
+
+Choose in this order:
+
+1. **Would a product stakeholder read this to understand behavior?** Use a Feature.
+2. **Is it a multi-step user or operator journey?** Use a Feature.
+3. **Is it one technical input/output contract or implementation-independent rule?** Use a Specification.
+
+The runtime instrument is separate from the report pattern. A browser Feature
+and an in-process Feature can both be valid; the claim determines the boundary.
+
+## Phrase the Present-Day Promise
+
+- Put values in titles, but keep implementation mechanisms out.
+- Test the goal, not the remembered defect.
+- Avoid team names, revision rounds, "previously", "retired", or development history.
+- A negative assertion is valid when absence is the current promise.
+- Ask whether the title would make sense to a reader who never saw the bug.
+
+| Too specific | Too vague | Trustworthy claim |
+| --- | --- | --- |
+| The shell uses class `h-7` | The chip is accessible | Under a coarse pointer, the chip exposes at least a `44`px target |
+| Function calls helper `normalizeV2` | Formatting works | Input `'abc'` produces canonical output `'ABC'` |
+
+## Make Failures Diagnosable
+
+- One independent claim should produce one reported row.
+- Use `scenarioOutline` or `ruleOutline` when combinations must fail independently.
+- Avoid loops that collapse many meaningful cases into one step.
+- A step should not hide unrelated assertions.
+- Failure messages must name the claim and case that broke.
+
+## False-Green Completion Gate
+
+Before completion:
+
+- [ ] The intended test was collected and executed.
+- [ ] The test passes alone and in its normal suite.
+- [ ] Expected values are independent of the production algorithm.
+- [ ] Complete shapes are compared when shape is the contract.
+- [ ] Missing subjects fail; helpers do not treat absence as success.
+- [ ] No guard clause returns before the assertion.
+- [ ] No fixed sleep is used where a deterministic seam is available.
+- [ ] Shared state has explicit reset and ownership semantics.
+- [ ] For critical behavior, the test has been observed failing for the intended defect.
+- [ ] The failure was behavioral, not a syntax/import/setup failure.
+- [ ] Existing failures are separated from failures introduced by the change.
+
+Use Stryker or another specialist tool for automated mutation testing. LiveDoc
+does not implement its own mutation engine.
+
+## Curate the Living Document
+
+Not every native Vitest test should become a LiveDoc test. Keep low-level harness
+checks, exhaustive generated cases, performance tests, and infrastructure probes
+in the native runner unless their result has durable reader value.
+
+Organize LiveDoc files by product surface. The directory structure is the
+Viewer's table of contents; keep test instrument details below that level.

package/tools/skills/resources/web-testing.md

@@ -0,0 +1,62 @@
+# Web Testing: jsdom or Real Browser
+
+Where a test runs is decided by what it claims, not convenience.
+
+## Use jsdom for Observable DOM Contracts
+
+jsdom is appropriate for:
+
+- component state transitions;
+- roles, accessible names, labels, and descriptions;
+- deterministic event handling;
+- form validation and submission;
+- loading, empty, error, and recovery states;
+- adapter/repository calls;
+- basic keyboard-event contracts that do not require real focus behavior.
+
+## Use a Real Browser for Platform Behavior
+
+Use Playwright or another real browser for:
+
+- measured geometry and responsive breakpoints;
+- overflow, clipping, sticky positioning, and scrolling;
+- focus trapping and restoration;
+- `inert`, modal isolation, and the accessibility tree;
+- computed styles, contrast, media queries, and theme geometry;
+- pointer hit testing and real keyboard navigation;
+- screenshots and visual comparison.
+
+Do not assert CSS class names as proxies for appearance. A class rename can fail
+while the product remains correct, and a broken stylesheet can leave the proxy
+green.
+
+## Browser Workflow
+
+1. Prove readiness without a fixed sleep.
+2. Interact through user-visible controls.
+3. Assert the semantic or geometric behavior.
+4. Attach a screenshot when it helps a reader or reviewer understand the state.
+5. Verify the browser, worker, server, ports, and temporary files are released.
+
+Read `resources/playwright.md` for the LiveDoc browser and screenshot APIs.
+
+## Screenshots Are Evidence
+
+A screenshot supports a claim; it does not replace the assertion.
+
+Capture states a reader needs to understand:
+
+- meaningful starting state;
+- important user-triggered transitions;
+- final outcome;
+- failure state when diagnostic evidence is useful.
+
+Feature journeys commonly benefit from screenshots. A browser-based
+Specification may also attach evidence when the technical contract is visual.
+
+Never attach:
+
+- credentials, tokens, cookies, or authorization headers;
+- unredacted personal data;
+- traces or screenshots captured before readiness;
+- large artifacts without a clear documentation purpose.

package/dist/RuleContext-BZhuy-zS.d.ts

@@ -1,206 +0,0 @@
-import { Attachment } from '@swedevtools/livedoc-schema';
-
-/**
- * Global type definitions for LiveDoc-Vitest
- */
-
-type DataTableRow = any[] | { [key: string]: any };
-
-interface LiveDocMetaTable {
-    name: string;
-    description: string;
-    dataTable: DataTableRow[];
-}
-
-interface LiveDocStepTaskMeta {
-    kind: "step";
-    step: {
-        rawTitle: string;
-        type: string;
-    };
-    scenarioOutline?: {
-        title?: string;
-        description: string;
-        tables: LiveDocMetaTable[];
-        tags: string[];
-        example: {
-            sequence: number;
-            values: Record<string, unknown>;
-        };
-    };
-}
-
-interface LiveDocRuleExampleTaskMeta {
-    kind: "ruleExample";
-    ruleOutline: {
-        title: string;
-        description: string;
-        tables: LiveDocMetaTable[];
-        tags: string[];
-        example: {
-            sequence: number;
-            values: Record<string, unknown>;
-        };
-    };
-}
-
-interface LiveDocRuleTaskMeta {
-    kind: "rule";
-    rule: {
-        title: string;
-        description: string;
-        tags: string[];
-    };
-}
-
-type LiveDocTaskMeta = LiveDocStepTaskMeta | LiveDocRuleExampleTaskMeta | LiveDocRuleTaskMeta;
-
-/**
- * Extend Vitest's TaskMeta to include LiveDoc context
- */
-declare module "@vitest/runner" {
-    interface TaskMeta {
-        livedoc?: LiveDocTaskMeta;
-    }
-}
-
-/**
- * Framework metadata about the current step
- * READ-ONLY - contains title, parsed values, tables, docStrings
- * Provides helpers for accessing step data in various formats
- */
-declare class StepContext {
-    private _table?;
-    private _attachments;
-    title: string;
-    displayTitle: string;
-    dataTable: DataTableRow[];
-    docString: string;
-    type: string;
-    values: any[];
-    valuesRaw: string[];
-    params: Record<string, any>;
-    paramsRaw: Record<string, string>;
-    constructor(attachments?: Attachment[]);
-    /**
-     * Attach arbitrary data (base64-encoded) to this step.
-     */
-    attach(data: string, opts?: {
-        title?: string;
-        mimeType?: string;
-        kind?: 'image' | 'screenshot' | 'file';
-    }): void;
-    /**
-     * Convenience: attach a PNG screenshot.
-     */
-    attachScreenshot(base64: string, title?: string): void;
-    /**
-     * Convenience: attach a JSON payload (e.g., API response).
-     */
-    attachJSON(data: unknown, title?: string): void;
-    /** Attachments collected during step execution. */
-    get attachments(): Attachment[];
-    /**
-     * Parse docString as JSON entity
-     */
-    get docStringAsEntity(): any;
-    /**
-     * Get data table with headers as column names
-     */
-    get table(): DataTableRow[];
-    /**
-     * Convert 2-column table to key-value entity
-     */
-    get tableAsEntity(): DataTableRow | undefined;
-    /**
-     * Get data table as-is (raw array of arrays)
-     */
-    tableAsList(): DataTableRow[];
-    /**
-     * Get first column as single array
-     */
-    get tableAsSingleList(): any[];
-    private convertToTable;
-    private convertDataTableRowToEntity;
-    private coerceValue;
-    private convertToDateIfPossible;
-}
-
-/**
- * Framework metadata about the scenario
- * READ-ONLY - contains title/description/tags/step references
- * NOT for user test data! Use local variables instead.
- */
-declare class ScenarioContext {
-    title: string;
-    description: string;
-    given?: StepContext;
-    and: StepContext[];
-    tags: string[];
-    /** All steps in this scenario */
-    steps: StepContext[];
-}
-
-/**
- * Framework metadata about the feature
- * READ-ONLY - contains file/title/description/tags
- * NOT for user test data! Use local variables instead.
- */
-declare class FeatureContext {
-    filename: string;
-    title: string;
-    description: string;
-    tags: string[];
-}
-
-/**
- * Framework metadata about the background
- * READ-ONLY - extends ScenarioContext with background-specific data
- */
-declare class BackgroundContext extends ScenarioContext {
-}
-
-/**
- * Framework metadata about the specification
- * READ-ONLY - contains file/title/description/tags
- * NOT for user test data! Use local variables instead.
- */
-declare class SpecificationContext {
-    filename: string;
-    title: string;
-    description: string;
-    tags: string[];
-}
-
-/**
- * Framework metadata about the rule.
- * Provides title, description, tags, and extracted values/params from the rule title.
- *
- * @example
- * ```typescript
- * rule("Adding '5' and '3' returns '8'", (ctx) => {
- *     const [a, b, expected] = ctx.rule.values; // [5, 3, 8]
- *     expect(a + b).toBe(expected);
- * });
- *
- * rule("Processing <action:login> for <user:alice>", (ctx) => {
- *     const action = ctx.rule.params.action; // "login"
- * });
- * ```
- */
-declare class RuleContext {
-    title: string;
-    description: string;
-    tags: string[];
-    specification: SpecificationContext;
-    /** Extracted and type-coerced quoted values from the rule title. */
-    values: any[];
-    /** Raw string values before type coercion. */
-    valuesRaw: string[];
-    /** Extracted and type-coerced named parameters from <name:value> patterns. */
-    params: Record<string, any>;
-    /** Raw string named parameters before type coercion. */
-    paramsRaw: Record<string, string>;
-}
-
-export { BackgroundContext as B, type DataTableRow as D, FeatureContext as F, RuleContext as R, ScenarioContext as S, StepContext as a, SpecificationContext as b };

package/dist/globals.cjs

@@ -1,2 +0,0 @@
-'use strict';
-