@swedevtools/livedoc-vitest 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# @swedevtools/livedoc-vitest Changelog
+
+All notable changes to the LiveDoc Vitest SDK are documented in this file.
+
+Use the `[next release]` section for changes that have not yet been promoted into a named package release, including temporary `0.0.0.x` builds.
+
+## [next release]
+
+## [0.3.0] - 2026-08-29
+
+### Added
+
+- Added explicit full and partial Viewer publishing so focused development runs preserve the latest full test picture.
+- Added optional Vitest coverage evidence from the in-memory coverage map, with JSON summary and LCOV artifact fallbacks.
+- Added configurable coverage thresholds for lines, branches, functions, and statements; threshold misses are Viewer warnings and do not change test status.
+
+### Changed
+
+- Changed package exports to ESM-only because Vitest 4 cannot be loaded through CommonJS `require()`.
+- Reorganized SDK tests into capability-focused sections so the suite doubles as clearer living documentation.
+- Expanded the packaged AI skill with boundary-first test selection, false-green checks, rule-violation self-correction, web-runtime guidance, tag-scoped partial runs, LiveDoc-specific anti-patterns, and a consent-gated workflow for reporting verified LiveDoc framework defects upstream.
+- Added OpenAI Codex and comma-separated multi-tool selection to the repository-local AI skill installer.
+- Set the default published project name to `livedoc` so multiple projects are easier to distinguish in the viewer.
+- Improved viewer autodiscovery by probing the local viewer when the temporary server metadata file is unavailable.
+
+### Fixed
+
+- Fixed invalid nested LiveDoc declarations so feature, scenario, outline, background, specification, and rule nesting fails explicitly instead of silently dropping executable coverage.
+- Fixed dynamic execution resets so each run retains LiveDoc's recommended default rule configuration without leaking caller overrides.
+- Fixed the optional `@swedevtools/livedoc-server` peer range so the Vitest SDK accepts the companion `0.3.0` server release.
+- Corrected the Vitest peer range to the tested `>=4.0.16 <5` contract instead of claiming unsupported Vitest 1-3 compatibility.
+- Fixed specification tag rendering and serialization, including slash-style tags such as `@name/name`.
+- Fixed LiveDoc filtering output so filtered tests are omitted from viewer/export results instead of appearing as pending or skipped.
+- Fixed Viewer publication so coverage context, artifact paths, and run type flow through auto-discovered and explicitly configured reporters.

package/LICENSE

@@ -1,21 +1,21 @@
-The MIT License (MIT)
-
-Copyright (c) 2014 dotnetprofessional
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+The MIT License (MIT)
+
+Copyright (c) 2014 dotnetprofessional
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -1,95 +1,160 @@
-<div align="center">
-
-# @swedevtools/livedoc-vitest
-
-### Turn your tests into living documentation
-
-[![npm version](https://img.shields.io/npm/v/@swedevtools/livedoc-vitest.svg)](https://www.npmjs.com/package/@swedevtools/livedoc-vitest)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-
-**Write tests in Gherkin. Get documentation that never goes stale.**
-
-📖 **[Full Documentation →](https://livedoc.swedevtools.com/vitest/learn/getting-started)**
-
-</div>
-
----
-
-## What is LiveDoc?
-
-LiveDoc brings Behavior-Driven Development to Vitest with full Gherkin syntax — **Feature / Scenario / Given / When / Then**, **Specification / Rule**, **Scenario Outlines**, **Tags & Filtering**, and **beautiful reports**.
-
-## Quick Start
-
-### Install
-
-```bash
-npm install --save-dev vitest @swedevtools/livedoc-vitest
-```
-
-### Create a spec
-
-```ts
-// tests/Calculator.Spec.ts
-import { feature, scenario, given, when, Then as then, and } from '@swedevtools/livedoc-vitest';
-
-feature("Calculator", () => {
-  scenario("Adding two numbers", () => {
-    let result = 0;
-
-    given("I have entered '50' into the calculator", (ctx) => {
-      result = ctx.step.values[0];
-    });
-
-    and("I have entered '70' into the calculator", (ctx) => {
-      result += ctx.step.values[0];
-    });
-
-    when("I press add", () => {
-      // Addition already happened above
-    });
-
-    then("the result should be '120'", (ctx) => {
-      expect(result).toBe(ctx.step.values[0]);
-    });
-  });
-});
-```
-
-> **Why `Then as then`?** ES modules treat `then` as a thenable indicator. We export `Then` (uppercase) and you alias it.
-
-### Configure Vitest
-
-```ts
-// vitest.config.ts
-import { defineConfig } from 'vitest/config';
-import { LiveDocSpecReporter } from '@swedevtools/livedoc-vitest/reporter';
-
-export default defineConfig({
-  test: {
-    globals: true,
-    include: ['**/*.Spec.ts'],
-    reporters: [new LiveDocSpecReporter()],
-  },
-});
-```
-
-### Run
-
-```bash
-npx vitest run
-```
-
----
-
-## Documentation
-
-📖 **[Full documentation at livedoc.swedevtools.com →](https://livedoc.swedevtools.com/vitest/learn/getting-started)**
-
-Covers getting started, BDD & Specification patterns, data extraction, scenario outlines, tags & filtering, reporters, viewer integration, CI/CD, troubleshooting, and more.
-
----
-
-## License
-
-MIT
+<div align="center">
+
+# @swedevtools/livedoc-vitest
+
+### Turn your tests into living documentation
+
+[![npm version](https://img.shields.io/npm/v/@swedevtools/livedoc-vitest.svg)](https://www.npmjs.com/package/@swedevtools/livedoc-vitest)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Write tests in Gherkin. Get documentation that never goes stale.**
+
+📖 **[Full Documentation →](https://livedoc.swedevtools.com/vitest/learn/getting-started)**
+
+</div>
+
+---
+
+## What is LiveDoc?
+
+LiveDoc brings Behavior-Driven Development to Vitest with full Gherkin syntax — **Feature / Scenario / Given / When / Then**, **Specification / Rule**, **Scenario Outlines**, **Tags & Filtering**, and **beautiful reports**.
+
+## Quick Start
+
+### Install
+
+```bash
+npm install --save-dev vitest@^4.0.16 @swedevtools/livedoc-vitest
+```
+
+### Fastest Setup: Point Your AI at the Bootstrap URL
+
+Tell your assistant:
+
+> Read https://livedoc.swedevtools.com/ai/setup.md and configure this Vitest
+> project for LiveDoc. Inspect it first, ask me one configuration question at a
+> time, and wait for approval before making changes.
+
+No LiveDoc package or skill needs to be installed first.
+[AI project setup →](https://livedoc.swedevtools.com/guides/ai-project-setup)
+
+AI setup installs version-matched skills inside the repository for every
+selected tool. Run `npx livedoc-vitest-setup --tool copilot,codex,claude` later
+to refresh them or add another tool. It also adds `test:livedoc` and, when
+coverage is enabled, `test:livedoc:coverage` package scripts.
+
+### Create a spec
+
+```ts
+// tests/Calculator.Spec.ts
+import { feature, scenario, given, when, Then as then, and } from '@swedevtools/livedoc-vitest';
+
+feature("Calculator", () => {
+  scenario("Adding two numbers", () => {
+    let result = 0;
+
+    given("I have entered '50' into the calculator", (ctx) => {
+      result = ctx.step.values[0];
+    });
+
+    and("I have entered '70' into the calculator", (ctx) => {
+      result += ctx.step.values[0];
+    });
+
+    when("I press add", () => {
+      // Addition already happened above
+    });
+
+    then("the result should be '120'", (ctx) => {
+      expect(result).toBe(ctx.step.values[0]);
+    });
+  });
+});
+```
+
+> **Why `Then as then`?** ES modules treat `then` as a thenable indicator. We export `Then` (uppercase) and you alias it.
+
+### Configure Vitest
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import { LiveDocSpecReporter } from '@swedevtools/livedoc-vitest/reporter';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    include: ['**/*.Spec.ts'],
+    reporters: [new LiveDocSpecReporter()],
+  },
+});
+```
+
+### Run
+
+```bash
+npx vitest run
+```
+
+### Publish a focused partial run
+
+After publishing one full baseline, mark an isolated development run as partial so the Viewer keeps the complete latest-known picture:
+
+```bash
+LIVEDOC_RUN_TYPE=partial npx vitest run features/Login.Spec.ts
+```
+
+You can also set `publish.runType` or `LiveDocViewerReporter({ runType: 'partial' })` in configuration. Partial runs require a running LiveDoc server and a completed full baseline for the same project and environment. Direct JSON/static partial export is not supported; release and production exports should use a full run.
+
+### Add coverage evidence
+
+LiveDoc can attach Vitest coverage as optional run evidence. It does not change the test run status; threshold misses appear as warnings in the viewer.
+
+Install the V8 provider on the same version as Vitest:
+
+```bash
+npm install --save-dev @vitest/coverage-v8
+```
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import { LiveDocSpecReporter } from '@swedevtools/livedoc-vitest/reporter';
+
+export default defineConfig({
+  test: {
+    reporters: [
+      new LiveDocSpecReporter({
+        coverage: { enabled: true, thresholds: { lines: 80 } },
+      }),
+    ],
+    coverage: {
+      enabled: true,
+      provider: 'v8',
+      reporter: ['text', 'html', 'json-summary'],
+    },
+  },
+});
+```
+
+```bash
+npx vitest run --coverage
+```
+
+LiveDoc consumes Vitest's in-memory coverage map before the run is published. It also auto-detects `coverage/coverage-summary.json` and `coverage/lcov.info` as fallbacks. For custom artifact paths, set `coverage.artifactPath` in the reporter or use `LIVEDOC_COVERAGE_PATH`.
+
+See the [Code Coverage guide](https://livedoc.swedevtools.com/viewer/guides/code-coverage) for provider choices, thresholds, troubleshooting, and the Viewer module hierarchy.
+
+---
+
+## Documentation
+
+📖 **[Full documentation at livedoc.swedevtools.com →](https://livedoc.swedevtools.com/vitest/learn/getting-started)**
+
+Covers getting started, BDD & Specification patterns, data extraction, scenario outlines, tags & filtering, reporters, viewer integration, CI/CD, troubleshooting, and more.
+
+---
+
+## License
+
+MIT

package/dist/{RuleContext-BZhuy-zS.d.cts → RuleContext-DQ8o_n1D.d.ts}

@@ -1,67 +1,67 @@
 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;
-    }
+/**
+ * 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;
+    }
 }
 
 /**

package/dist/globals.d.ts

@@ -1,104 +1,104 @@
-import { F as FeatureContext, S as ScenarioContext, a as StepContext, B as BackgroundContext, b as SpecificationContext, R as RuleContext } from './RuleContext-BZhuy-zS.js';
+import { F as FeatureContext, S as ScenarioContext, a as StepContext, B as BackgroundContext, b as SpecificationContext, R as RuleContext } from './RuleContext-DQ8o_n1D.js';
 import '@swedevtools/livedoc-schema';
 
-/**
- * The context object passed to all LiveDoc test functions.
- * Provides access to feature, scenario, step, example, and background contexts.
- */
-interface LiveDocTestContext {
-    /** Framework metadata about the current feature */
-    feature?: FeatureContext;
-    /** Framework metadata about the current scenario */
-    scenario?: ScenarioContext;
-    /** Framework metadata about the current step */
-    step?: StepContext;
-    /** Framework metadata about the current scenario outline example */
-    example?: ScenarioContext;
-    /** Framework metadata about the background */
-    background?: BackgroundContext;
-}
-
-/**
- * The context object passed to Specification pattern test functions.
- */
-interface SpecificationTestContext {
-    /** Framework metadata about the current specification */
-    specification?: SpecificationContext;
-    /** Framework metadata about the current rule */
-    rule?: RuleContext;
-    /** Example data for rule outlines */
-    example?: Record<string, any>;
-}
-
-declare global {
-    /**
-     * Define a Gherkin feature
-     */
-    function feature(title: string, fn: (ctx: LiveDocTestContext) => void): void;
-
-    /**
-     * Define a scenario within a feature
-     */
-    function scenario(title: string, fn: (ctx: LiveDocTestContext) => void | Promise<void>): void;
-
-    /**
-     * Define a scenario outline (data-driven test)
-     * Examples are extracted from the title string by the parser
-     */
-    function scenarioOutline(title: string, fn: (ctx: LiveDocTestContext) => void): void;
-
-    /**
-     * Define background steps that run before each scenario
-     */
-    function background(title: string, fn: (ctx: LiveDocTestContext & {
-        afterBackground: (fn: () => void | Promise<void>) => void;
-    }) => void): void;
-
-    /**
-     * Define a given step (precondition)
-     */
-    function given(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
-
-    /**
-     * Define a when step (action)
-     */
-    function when(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
-
-    /**
-     * Define a then step (assertion)
-     * Available as lowercase global when using globals mode.
-     */
-    function then(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
-
-    /**
-     * Define an and step (continuation)
-     */
-    function and(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
-
-    /**
-     * Define a but step (continuation with contrast)
-     */
-    function but(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
-
-    // ============================================
-    // Specification Pattern Globals
-    // ============================================
-
-    /**
-     * Define a specification (container for rules)
-     */
-    function specification(title: string, fn: (ctx: SpecificationTestContext) => void): void;
-
-    /**
-     * Define a rule within a specification
-     */
-    function rule(title: string, fn: (ctx: SpecificationTestContext) => void | Promise<void>): void;
-
-    /**
-     * Define a rule outline (data-driven rules)
-     * Examples are extracted from the title string by the parser
-     */
-    function ruleOutline(title: string, fn: (ctx: SpecificationTestContext) => void | Promise<void>): void;
+/**
+ * The context object passed to all LiveDoc test functions.
+ * Provides access to feature, scenario, step, example, and background contexts.
+ */
+interface LiveDocTestContext {
+    /** Framework metadata about the current feature */
+    feature?: FeatureContext;
+    /** Framework metadata about the current scenario */
+    scenario?: ScenarioContext;
+    /** Framework metadata about the current step */
+    step?: StepContext;
+    /** Framework metadata about the current scenario outline example */
+    example?: ScenarioContext;
+    /** Framework metadata about the background */
+    background?: BackgroundContext;
+}
+
+/**
+ * The context object passed to Specification pattern test functions.
+ */
+interface SpecificationTestContext {
+    /** Framework metadata about the current specification */
+    specification?: SpecificationContext;
+    /** Framework metadata about the current rule */
+    rule?: RuleContext;
+    /** Example data for rule outlines */
+    example?: Record<string, any>;
+}
+
+declare global {
+    /**
+     * Define a Gherkin feature
+     */
+    function feature(title: string, fn: (ctx: LiveDocTestContext) => void): void;
+
+    /**
+     * Define a scenario within a feature
+     */
+    function scenario(title: string, fn: (ctx: LiveDocTestContext) => void | Promise<void>): void;
+
+    /**
+     * Define a scenario outline (data-driven test)
+     * Examples are extracted from the title string by the parser
+     */
+    function scenarioOutline(title: string, fn: (ctx: LiveDocTestContext) => void): void;
+
+    /**
+     * Define background steps that run before each scenario
+     */
+    function background(title: string, fn: (ctx: LiveDocTestContext & {
+        afterBackground: (fn: () => void | Promise<void>) => void;
+    }) => void): void;
+
+    /**
+     * Define a given step (precondition)
+     */
+    function given(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
+
+    /**
+     * Define a when step (action)
+     */
+    function when(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
+
+    /**
+     * Define a then step (assertion)
+     * Available as lowercase global when using globals mode.
+     */
+    function then(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
+
+    /**
+     * Define an and step (continuation)
+     */
+    function and(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
+
+    /**
+     * Define a but step (continuation with contrast)
+     */
+    function but(title: string, fn?: (ctx: LiveDocTestContext) => void | Promise<void>, passedParam?: object | Function): void;
+
+    // ============================================
+    // Specification Pattern Globals
+    // ============================================
+
+    /**
+     * Define a specification (container for rules)
+     */
+    function specification(title: string, fn: (ctx: SpecificationTestContext) => void): void;
+
+    /**
+     * Define a rule within a specification
+     */
+    function rule(title: string, fn: (ctx: SpecificationTestContext) => void | Promise<void>): void;
+
+    /**
+     * Define a rule outline (data-driven rules)
+     * Examples are extracted from the title string by the parser
+     */
+    function ruleOutline(title: string, fn: (ctx: SpecificationTestContext) => void | Promise<void>): void;
 }
 
 export type { LiveDocTestContext, SpecificationTestContext };