@sdods/core 0.17.0 → 0.19.0

package/dist/api/client.js

@@ -179,7 +179,9 @@ export class ApiClient {
             const reqFile = scenario.file(scenarioFiles.apiJson(stepIndex, n, 'request'));
             const resFile = scenario.file(scenarioFiles.apiJson(stepIndex, n, 'response'));
             writeFileSync(reqFile, JSON.stringify(redact(snap.request), null, 2));
-            writeFileSync(resFile, JSON.stringify({ ...snap.response, rawBody: undefined }, null, 2));
+            // Response bodies carry login tokens and session ids, and run_get_scenario hands this file to
+            // agents, so it is redacted by key name like the request.
+            writeFileSync(resFile, JSON.stringify(redact({ ...snap.response, rawBody: undefined }), null, 2));
             void testInfo.attach(attachmentNames.api(stepIndex, n, 'request'), {
                 path: reqFile,
                 contentType: 'application/json',

package/dist/config/defaults.js

@@ -16,7 +16,13 @@ export const FRAMEWORK_DEFAULTS = {
         viewport: { width: 1280, height: 720 },
         onlyOnFailure: false,
     },
-    heal: { enabled: true, primaryTimeoutMs: 3000, probeTimeoutMs: 1500, minScore: 0.6 },
+    heal: {
+        enabled: true,
+        primaryTimeoutMs: 3000,
+        probeTimeoutMs: 1500,
+        minScore: 0.6,
+        ciMode: 'warn',
+    },
     timeouts: { test: 60_000, expect: 10_000, action: 15_000, navigation: 30_000, api: 15_000 },
     retries: { ci: 2, local: 0, byTag: {} },
 };

package/dist/config/resolve.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { basename, join, resolve as resolvePath } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { ZodError } from 'zod';
-import { EnvConfigSchema, ProjectConfigSchema, newRunId, } from '@sdods/contracts';
+import { EnvConfigSchema, ProjectConfigSchema, isRunId, newRunId, } from '@sdods/contracts';
 import { SdodsConfigError } from '../errors.js';
 import { DEFAULT_ARTIFACTS_DIR, ENV_TO_CONFIG_PATH, FRAMEWORK_DEFAULTS, PROJECT_FILE, } from './defaults.js';
 import { loadDotEnvLayer } from './env-files.js';
@@ -146,6 +146,11 @@ export function resolveConfig(opts) {
     // runtime finalisation
     const rt = interpolated.runtime;
     rt.runId = rt.runId || newRunId();
+    // runDir is `<artifactsDir>/<runId>`; a `..` id would point it (and its cleanup) elsewhere.
+    if (!isRunId(rt.runId))
+        throw new SdodsConfigError(`Invalid run id "${rt.runId}".`, {
+            hint: 'Use letters, digits, ".", "_" or "-", not starting with ".".',
+        });
     rt.retries = rt.retries ?? (rt.ci ? projectMerged.retries.ci : projectMerged.retries.local);
     rt.harMode = rt.harMode ?? 'off';
     rt.artifactsDir = resolvePath(opts.rootDir, rt.artifactsDir || DEFAULT_ARTIFACTS_DIR);

package/dist/config/runner.d.ts

@@ -1,6 +1,11 @@
 import { type PlaywrightTestConfig } from '@playwright/test';
 import { type BrowserName, type Layer, type ProcessConfig, type ProjectConfig, type SetupConfig } from '@sdods/contracts';
 import type { ProjectRegistry } from './registry.js';
+/**
+ * allure-playwright, resolved from @sdods/core rather than from the generated runner config: with
+ * bun's isolated linker a workspace or a global install does not see core's dependencies.
+ */
+export declare function allureReporterPath(): string;
 export interface RunnerSelection {
     project?: string;
     env?: string;

package/dist/config/runner.js

@@ -1,10 +1,23 @@
 import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { join, resolve as resolvePath } from 'node:path';
 import { devices } from '@playwright/test';
 import { cucumberReporter, defineBddConfig } from 'playwright-bdd';
 import { EVIDENCE_DEFAULTS, RUNNER_SETUP_PHASE, runnerProjectName, runFiles, } from '@sdods/contracts';
 import { coreStepsPatterns } from '../steps/glob.js';
 import { combineTagExpr, normalizeTagExpr } from './tags.js';
+/**
+ * allure-playwright, resolved from @sdods/core rather than from the generated runner config: with
+ * bun's isolated linker a workspace or a global install does not see core's dependencies.
+ */
+export function allureReporterPath() {
+    try {
+        return createRequire(import.meta.url).resolve('allure-playwright');
+    }
+    catch {
+        return 'allure-playwright';
+    }
+}
 const DEVICE_FOR_BROWSER = {
     chromium: 'Desktop Chrome',
     edge: 'Desktop Edge',
@@ -259,6 +272,8 @@ export function buildRunnerConfig(registry, sel = {}) {
     // land inside the run directory.
     const extra = (sel.reporters ?? []).map((r) => {
         const [name, file] = r.split('=');
+        if (file && (name === 'allure' || name === 'allure-playwright'))
+            return [allureReporterPath(), { resultsDir: file }];
         if (file)
             return [name, name === 'blob' ? { outputDir: file } : { outputFile: file }];
         if (name === 'blob')
@@ -267,6 +282,8 @@ export function buildRunnerConfig(registry, sel = {}) {
             return ['json', { outputFile: join(runDir, 'runner-results.extra.json') }];
         if (name === 'junit')
             return ['junit', { outputFile: join(runDir, runFiles.junit) }];
+        if (name === 'allure' || name === 'allure-playwright')
+            return [allureReporterPath(), { resultsDir: file ?? join(runDir, 'allure-results') }];
         return [name];
     });
     {
@@ -294,7 +311,7 @@ export function buildRunnerConfig(registry, sel = {}) {
                 outputFile: join(runDir, 'cucumber-report.html'),
             }));
         if (sel.allure || first?.project.reports.allure)
-            reporter.push(['allure-playwright', { resultsDir: join(runDir, 'allure-results') }]);
+            reporter.push([allureReporterPath(), { resultsDir: join(runDir, 'allure-results') }]);
     }
     for (const r of extra) {
         if (reporter.some((d) => d[0] === r[0]))

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 /** Structured errors: every CLI/MCP/server surface renders `{ code, message, hint, docsUrl }`. */
-export type SdodsErrorCode = 'CONFIG_INVALID' | 'CONFIG_NOT_FOUND' | 'CONFIG_SECRET_LITERAL' | 'CONFIG_UNRESOLVED_VAR' | 'PROJECT_NOT_FOUND' | 'ENV_NOT_FOUND' | 'DATASET_NOT_FOUND' | 'DATASET_ROW_NOT_FOUND' | 'USER_POOL_EXHAUSTED' | 'USER_POOL_TOO_SMALL' | 'HEAL_FAILED' | 'LINT_FAILED' | 'RUN_FAILED' | 'GATE_FAILED' | 'HAR_MISS' | 'DB_REQUIRED' | 'MAIL_REQUIRED' | 'MAIL_NOT_RECEIVED' | 'AUTH_FAILED' | 'NOT_SUPPORTED' | 'INTERNAL';
+export type SdodsErrorCode = 'CONFIG_INVALID' | 'CONFIG_NOT_FOUND' | 'CONFIG_SECRET_LITERAL' | 'CONFIG_UNRESOLVED_VAR' | 'PROJECT_NOT_FOUND' | 'ENV_NOT_FOUND' | 'DATASET_NOT_FOUND' | 'DATASET_ROW_NOT_FOUND' | 'USER_POOL_EXHAUSTED' | 'USER_POOL_TOO_SMALL' | 'HEAL_FAILED' | 'HEAL_BLOCKED_IN_CI' | 'LINT_FAILED' | 'RUN_FAILED' | 'GATE_FAILED' | 'HAR_MISS' | 'DB_REQUIRED' | 'MAIL_REQUIRED' | 'MAIL_NOT_RECEIVED' | 'AUTH_FAILED' | 'NOT_SUPPORTED' | 'INTERNAL';
 export declare const DOCS_BASE_URL = "https://docs.sdods.com";
 export interface SdodsErrorOptions {
     hint?: string;

package/dist/fixtures/test.js

@@ -257,6 +257,7 @@ export const test = base.extend({
     heal: async ({ config, healHistory, scenario, $bddContext }, use, testInfo) => {
         await use(new Healer({
             config: config.project.heal,
+            ci: config.runtime.ci,
             history: healHistory,
             scenario,
             testInfo,

package/dist/heal/healer.d.ts

@@ -5,12 +5,21 @@ import type { HealAction, HealContext } from './types.js';
 import type { HealHistory } from './history.js';
 export interface HealerDeps {
     config: HealConfig;
+    /** True under CI; `config.ciMode` then decides whether healing warns, fails or is off. */
+    ci?: boolean;
     history?: HealHistory;
     scenario?: ScenarioMeta;
     testInfo?: TestInfo;
     stepIndex?: () => number;
     runId?: string;
 }
+/** What the healer does for this run: heal quietly (local), or the CI mode. */
+export type HealMode = 'heal' | 'warn' | 'fail' | 'off';
+/**
+ * Local runs heal as they always have. Under CI the configured `ciMode` applies (default `warn`),
+ * because a heal in CI means the application changed under the suite and must be visible.
+ */
+export declare function effectiveHealMode(config: Pick<HealConfig, 'enabled' | 'ciMode'>, ci: boolean): HealMode;
 /** Locator wrapper: every action goes through the healer. */
 export declare class HealedLocator {
     private readonly healer;

package/dist/heal/healer.js

@@ -4,6 +4,17 @@ import { attachmentNames, scenarioFiles } from '@sdods/contracts';
 import { Logger } from '../logger.js';
 import { SdodsError } from '../errors.js';
 import { buildCandidates, disambiguationCandidates, rolesFor } from './strategies.js';
+/**
+ * Local runs heal as they always have. Under CI the configured `ciMode` applies (default `warn`),
+ * because a heal in CI means the application changed under the suite and must be visible.
+ */
+export function effectiveHealMode(config, ci) {
+    if (!config.enabled)
+        return 'off';
+    if (!ci)
+        return 'heal';
+    return config.ciMode ?? 'warn';
+}
 /** Locator wrapper: every action goes through the healer. */
 export class HealedLocator {
     healer;
@@ -109,7 +120,8 @@ export class Healer {
      */
     async resolve(primary, ctx, action) {
         const cfg = this.deps.config;
-        const healable = cfg.enabled && cfg.actions.includes(action);
+        const mode = effectiveHealMode(cfg, Boolean(this.deps.ci));
+        const healable = mode !== 'off' && cfg.actions.includes(action);
         try {
             await primary.first().waitFor({ state: 'visible', timeout: cfg.primaryTimeoutMs });
         }
@@ -162,6 +174,9 @@ export class Healer {
             durationMs: Date.now() - t0,
             at: new Date().toISOString(),
         };
+        const blocked = Boolean(best) && effectiveHealMode(cfg, Boolean(this.deps.ci)) === 'fail';
+        if (blocked)
+            event.blockedInCi = true;
         this.record(event);
         const probed = ranked.map((p) => `${p.strategy}=${p.score.toFixed(2)}`).join(', ') || 'none';
         if (!best) {
@@ -175,6 +190,13 @@ export class Healer {
                 cause: why.cause,
             });
         }
+        if (blocked) {
+            throw new SdodsError('HEAL_BLOCKED_IN_CI', `"${ctx.description}" (${String(primary)}) no longer matches, and heal.ciMode is "fail", so the step fails instead of healing to ${best.selector}.`, {
+                hint: `Update the page object to ${best.selector} (found via ${best.strategy}, score ${best.score.toFixed(2)}), or set heal.ciMode to "warn".`,
+                details: { candidates: event.candidates },
+                cause: why.cause,
+            });
+        }
         this.log.warn(`healed "${ctx.description}": ${String(primary)}${ambiguous ? ` (matched ${why.matched})` : ''} → ${best.selector} via ${best.strategy} (score ${best.score.toFixed(2)}, ${event.durationMs} ms). Update the page object.`);
         return best.locator.first();
     }

package/dist/heal/report.d.ts

@@ -13,4 +13,21 @@ export interface HealReportRow {
 /** Recursively collect heal.jsonl files under a run dir (or all runs). */
 export declare function collectHealEvents(root: string): HealEvent[];
 export declare function summarizeHealEvents(events: HealEvent[]): HealReportRow[];
+/** What a CI run prints about healing: GitHub annotations and a step-summary section. */
+export interface CiHealSummary {
+    healed: number;
+    blocked: number;
+    /** `::warning` / `::error` workflow commands, one per distinct locator. */
+    annotations: string[];
+    /** Markdown for `$GITHUB_STEP_SUMMARY`. */
+    markdown: string;
+    /** One plain line for any CI. */
+    line: string;
+}
+/**
+ * Healing in CI must never hide a regression, so every heal in a CI run is surfaced: a heal that
+ * passed (`ciMode: warn`) becomes a warning, a heal that was refused (`ciMode: fail`) an error.
+ * Undefined when nothing healed.
+ */
+export declare function ciHealSummary(events: HealEvent[]): CiHealSummary | undefined;
 //# sourceMappingURL=report.d.ts.map

package/dist/heal/report.js

@@ -61,4 +61,41 @@ export function summarizeHealEvents(events) {
     }
     return [...byKey.values()].sort((a, b) => b.occurrences - a.occurrences);
 }
+const escapeCommand = (s) => s.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+/**
+ * Healing in CI must never hide a regression, so every heal in a CI run is surfaced: a heal that
+ * passed (`ciMode: warn`) becomes a warning, a heal that was refused (`ciMode: fail`) an error.
+ * Undefined when nothing healed.
+ */
+export function ciHealSummary(events) {
+    const found = events.filter((e) => e.succeeded);
+    if (found.length === 0)
+        return undefined;
+    const blocked = found.filter((e) => e.blockedInCi).length;
+    const healed = found.length - blocked;
+    const rows = summarizeHealEvents(found);
+    const annotations = rows.map((r) => {
+        const level = found.some((e) => e.blockedInCi &&
+            e.description === r.description &&
+            e.originalSelector === r.originalSelector)
+            ? 'error'
+            : 'warning';
+        const text = `"${r.description}": ${r.originalSelector} no longer matches; ${level === 'error' ? 'would heal' : 'healed'} to ${r.suggestedSelector ?? '?'} (${r.occurrences}x in ${r.scenarios.length} scenario(s)). Update the page object.`;
+        return `::${level} title=SDODS self-healing::${escapeCommand(text)}`;
+    });
+    const line = `self-healing: ${healed} locator heal(s) passed with a warning` +
+        (blocked ? `, ${blocked} refused (heal.ciMode=fail)` : '') +
+        '. The application changed under the suite; update the page objects.';
+    const markdown = [
+        '### SDODS self-healing',
+        '',
+        line,
+        '',
+        '| Locator | Original | Healed to | Times |',
+        '|---|---|---|---|',
+        ...rows.map((r) => `| ${r.description} | \`${r.originalSelector}\` | \`${r.suggestedSelector ?? '?'}\` | ${r.occurrences} |`),
+        '',
+    ].join('\n');
+    return { healed, blocked, annotations, markdown, line };
+}
 //# sourceMappingURL=report.js.map

package/dist/import/cucumber.d.ts

@@ -0,0 +1,74 @@
+export type ImportLayer = 'ui' | 'api' | 'hybrid';
+export interface SourceStep {
+    keyword: string;
+    /** A Cucumber expression, or a regular expression's source when `regex` is true. */
+    expression: string;
+    regex: boolean;
+    file: string;
+    line: number;
+    /** Raw source of the definition, for the stub's comment. */
+    body: string;
+    kind: 'ui' | 'api' | 'unknown';
+}
+export interface ImportedFeature {
+    /** Path inside the project, e.g. `features/checkout/cart.feature`. */
+    path: string;
+    content: string;
+    scenarios: number;
+}
+export interface ScenarioMapping {
+    feature: string;
+    scenario: string;
+    layer: ImportLayer;
+    layerInferred: boolean;
+    suite: string;
+}
+export interface CucumberImportPlan {
+    slug: string;
+    sourceDir: string;
+    features: ImportedFeature[];
+    layers: ImportLayer[];
+    extraTags: string[];
+    /** `steps/imported.steps.ts`, or undefined when every step is covered by the core library. */
+    stepsFile?: string;
+    mappings: ScenarioMapping[];
+    steps: {
+        total: number;
+        core: string[];
+        stubbed: string[];
+        undefined: string[];
+    };
+    manual: Array<{
+        what: string;
+        file: string;
+        line: number;
+    }>;
+    warnings: string[];
+    report: string;
+}
+/** What a step definition's body touches, by the libraries it names. */
+export declare function classifyStepBody(body: string): SourceStep['kind'];
+/**
+ * Step definitions in a Cucumber-JS source file: `Given('…', fn)`, `When(/…/, fn)`, `Then("…")`,
+ * and `defineStep`. Read as text; the body is everything up to the next definition.
+ */
+export declare function extractStepDefinitions(file: string, text: string): SourceStep[];
+/** Patterns of the SDODS core step library, read from its source like the source suite's. */
+export declare function coreStepExpressions(dir?: string): string[];
+/** Literal string values from a Cucumber config file, without running it. */
+export declare function readCucumberConfig(text: string): {
+    paths: string[];
+    requires: string[];
+    tags?: string;
+};
+export interface PlanOptions {
+    slug: string;
+    /** Module folder under `features/`; default `imported`. */
+    module?: string;
+    /** Override the core step expressions (tests). */
+    coreExpressions?: string[];
+}
+export declare function planCucumberImport(sourceDir: string, opts: PlanOptions): CucumberImportPlan;
+/** Parameters a step expression passes: `{…}` in a Cucumber expression, capture groups in a regex. */
+export declare function argumentCount(step: Pick<SourceStep, 'expression' | 'regex'>): number;
+//# sourceMappingURL=cucumber.d.ts.map