agentic-qe 3.15.15 → 3.15.17

package/dist/shared/test-runner-project.d.ts

@@ -0,0 +1,119 @@
+/**
+ * #1247: the runner project a test file belongs to.
+ *
+ * Vitest and Jest load their configuration (setup files, aliases, include
+ * patterns, environment) from the directory they are started in. In a
+ * monorepo whose packages have their own config (`apps/webapp/vitest.config.ts`)
+ * a run started at the repository root never loads that package's setup, so
+ * the package's tests fail or produce no report. Each test file is therefore
+ * run from the nearest directory, at or above it, with runner configuration,
+ * but never from above the project root. Only real configuration counts, so a
+ * workspace package without its own config runs from the root that defines
+ * its project.
+ *
+ * A run from the current working directory is kept whenever that directory is
+ * already inside the file's runner project (a single-project repository, or a
+ * server started inside the package), so those runs behave as before.
+ *
+ * #1272: a package with its own config runs from that package, even when the
+ * root config also lists it in `test.projects` (or a `vitest.workspace.*`).
+ * Settings that only the root config adds to that project (its setup files,
+ * aliases or environment) are then not applied; the package's own config is
+ * what runs. A package without its own config still runs from the root.
+ *
+ * #1272: `vite.config.*` counts only when its text contains `test:`. The
+ * config is code, and reading what it exports would mean running it, so a
+ * `test` block built some other way (spread from another module, say) is not
+ * seen and a `test:` that only appears in a comment is. Name the runner config
+ * `vitest.config.*` for an exact match.
+ *
+ * #1248: a Python test file belongs to the nearest directory with pytest
+ * configuration instead (`pytest.ini`, `pyproject.toml` with
+ * `[tool.pytest.ini_options]`, `setup.cfg` with `[tool:pytest]`, `tox.ini`
+ * with `[pytest]`), and JavaScript files ignore that configuration. A
+ * `conftest.py` marks a pytest project for detection but is not a directory
+ * to run from: it is often in `tests/`, and pytest started there would not
+ * have the project root on `sys.path`.
+ */
+import { Result } from './types';
+/**
+ * Files whose presence makes a directory a Vitest or Jest project. A root
+ * workspace file (`vitest.workspace.*`) counts too: its packages run from it.
+ */
+export declare const RUNNER_CONFIG_FILES: readonly string[];
+export interface RunnerProjectOptions {
+    /** Directory runs start in today; defaults to process.cwd(). */
+    cwd?: string;
+    /** Highest directory the search may reach; defaults to findProjectRoot(). */
+    boundary?: string;
+    /** Directories already checked, so files that share a directory check it once. */
+    checked?: Map<string, boolean>;
+}
+/** A set of test files that run together from one directory. */
+export interface RunnerProjectGroup {
+    cwd: string;
+    files: string[];
+}
+/** A runner whose project configuration can be recognised from its files. */
+export type RunnerFramework = 'vitest' | 'jest';
+/** True when `dir` holds a Vitest or Jest configuration. */
+export declare function isRunnerProjectDir(dir: string): boolean;
+/**
+ * #1248: true when `dir` holds pytest configuration; with `conftest`, a
+ * `conftest.py` counts too (see the header note).
+ */
+export declare function isPytestProjectDir(dir: string, conftest?: boolean): boolean;
+/**
+ * #1248: true when `dir`, or a directory above it no higher than `boundary`,
+ * is configured for pytest (including a `conftest.py`).
+ */
+export declare function isPytestProject(dir: string, boundary?: string): boolean;
+/**
+ * #1272: the runner configured by the runner project that `dir` belongs to:
+ * the nearest directory at or above `dir`, no higher than `boundary`, with
+ * runner configuration. Jest config (`jest.config.*`, or a `jest` key in
+ * package.json) means jest; Vitest config (`vitest.config.*`,
+ * `vitest.workspace.*`, a `vite.config.*` with `test`, or a `vitest` key)
+ * means vitest. Undefined when no project is found or it configures both, so
+ * the caller keeps its own choice.
+ */
+export declare function runnerFrameworkFor(dir: string, boundary?: string): RunnerFramework | undefined;
+/**
+ * The nearest directory at or above `file` with runner configuration, searching no
+ * higher than `boundary`. Undefined when the file lies outside the boundary or
+ * no directory on the way has runner configuration.
+ */
+export declare function findRunnerProjectDir(file: string, boundary: string, cwd?: string, checked?: Map<string, boolean>): string | undefined;
+/**
+ * Directory to start the runner in for `file`: its runner project, unless the
+ * current directory is already inside that project (or none is found), in
+ * which case the current directory is kept.
+ */
+export declare function runnerCwdFor(file: string, options?: RunnerProjectOptions): string;
+/**
+ * Group `files` by the directory each must run from, in first-seen order.
+ * Files keep the spelling they were given. #1248: Python files never share a
+ * group with other files, since only pytest runs them.
+ */
+export declare function groupByRunnerProject(files: readonly string[], options?: RunnerProjectOptions): RunnerProjectGroup[];
+/** Test files to run, and the directory to run them from when the caller named one. */
+export interface TestRunTargets {
+    testFiles: string[];
+    projectRoot?: string;
+}
+/**
+ * Handler-side check for an execute-tests payload. `testFiles` must name
+ * files or directories inside the project (#1126). An explicit `projectRoot`
+ * must be a directory inside the project, checked by realpath so `..`, an
+ * outside absolute path or a symlink pointing out is refused; relative test
+ * files are then read from it, and every path is returned absolute.
+ */
+export declare function requireTestRunTargets(taskType: string, testFiles: unknown, projectRoot: unknown): Promise<Result<TestRunTargets, Error>>;
+/**
+ * An explicit `projectRoot` (MCP `test_execute_parallel`, CLI
+ * `aqe test execute --project-root`): a directory inside the project, checked
+ * by realpath so `..`, an outside absolute path or a symlink pointing out is
+ * refused. Returns the absolute directory.
+ */
+export declare function requireRunProjectRoot(taskType: string, projectRoot: unknown): Promise<Result<string, Error>>;
+//# sourceMappingURL=test-runner-project.d.ts.map

package/dist/shared/test-runner-project.js

@@ -0,0 +1,301 @@
+/**
+ * #1247: the runner project a test file belongs to.
+ *
+ * Vitest and Jest load their configuration (setup files, aliases, include
+ * patterns, environment) from the directory they are started in. In a
+ * monorepo whose packages have their own config (`apps/webapp/vitest.config.ts`)
+ * a run started at the repository root never loads that package's setup, so
+ * the package's tests fail or produce no report. Each test file is therefore
+ * run from the nearest directory, at or above it, with runner configuration,
+ * but never from above the project root. Only real configuration counts, so a
+ * workspace package without its own config runs from the root that defines
+ * its project.
+ *
+ * A run from the current working directory is kept whenever that directory is
+ * already inside the file's runner project (a single-project repository, or a
+ * server started inside the package), so those runs behave as before.
+ *
+ * #1272: a package with its own config runs from that package, even when the
+ * root config also lists it in `test.projects` (or a `vitest.workspace.*`).
+ * Settings that only the root config adds to that project (its setup files,
+ * aliases or environment) are then not applied; the package's own config is
+ * what runs. A package without its own config still runs from the root.
+ *
+ * #1272: `vite.config.*` counts only when its text contains `test:`. The
+ * config is code, and reading what it exports would mean running it, so a
+ * `test` block built some other way (spread from another module, say) is not
+ * seen and a `test:` that only appears in a comment is. Name the runner config
+ * `vitest.config.*` for an exact match.
+ *
+ * #1248: a Python test file belongs to the nearest directory with pytest
+ * configuration instead (`pytest.ini`, `pyproject.toml` with
+ * `[tool.pytest.ini_options]`, `setup.cfg` with `[tool:pytest]`, `tox.ini`
+ * with `[pytest]`), and JavaScript files ignore that configuration. A
+ * `conftest.py` marks a pytest project for detection but is not a directory
+ * to run from: it is often in `tests/`, and pytest started there would not
+ * have the project root on `sys.path`.
+ */
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import * as path from 'node:path';
+import { findProjectRoot } from '../kernel/project-root.js';
+import { CallerInputError } from './error-utils.js';
+import { requirePayloadFiles, requirePayloadPath } from './io/payload-path-guard.js';
+import { isPythonTestFile } from './pytest-junit-report.js';
+import { safeJsonParse } from './safe-json.js';
+import { runnerFilePath } from './test-runner-args.js';
+import { ok, err } from './types/index.js';
+const CONFIG_EXTENSIONS = ['ts', 'mts', 'cts', 'js', 'mjs', 'cjs'];
+/**
+ * Files whose presence makes a directory a Vitest or Jest project. A root
+ * workspace file (`vitest.workspace.*`) counts too: its packages run from it.
+ */
+export const RUNNER_CONFIG_FILES = [
+    ...CONFIG_EXTENSIONS.map(ext => `vitest.config.${ext}`),
+    ...[...CONFIG_EXTENSIONS, 'json'].map(ext => `vitest.workspace.${ext}`),
+    ...CONFIG_EXTENSIONS.map(ext => `jest.config.${ext}`),
+    'jest.config.json',
+];
+/** Vite configs: a runner project only when they configure `test`. */
+const VITE_CONFIG_FILES = CONFIG_EXTENSIONS.map(ext => `vite.config.${ext}`);
+/** Largest config or package.json read while looking for a runner setup. */
+const MAX_MARKER_BYTES = 1024 * 1024;
+function realDir(dir) {
+    try {
+        return realpathSync(dir);
+    }
+    catch {
+        return path.resolve(dir);
+    }
+}
+/** True when `candidate` is `root` or lies beneath it (both absolute). */
+function isWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+function readSmallFile(file) {
+    try {
+        const stat = statSync(file);
+        if (!stat.isFile() || stat.size > MAX_MARKER_BYTES)
+            return undefined;
+        return readFileSync(file, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Runners a package.json in `dir` configures (a top-level `jest` or `vitest`
+ * key). Listing a runner as a dependency or in `scripts.test` does not count:
+ * in a workspace the packages do that while the root config defines their
+ * projects and setup.
+ */
+function packageRunnerKeys(dir) {
+    const text = readSmallFile(path.join(dir, 'package.json'));
+    if (text === undefined)
+        return [];
+    let pkg;
+    try {
+        pkg = safeJsonParse(text);
+    }
+    catch {
+        return [];
+    }
+    if (!pkg || typeof pkg !== 'object')
+        return [];
+    return ['vitest', 'jest'].filter(key => pkg[key] !== undefined);
+}
+/** True when a `vite.config.*` in `dir` mentions `test:` (see the header note). */
+function viteConfiguresTest(dir) {
+    return VITE_CONFIG_FILES.some(name => {
+        const text = readSmallFile(path.join(dir, name));
+        return text !== undefined && /\btest\s*:/.test(text);
+    });
+}
+/** The runners whose configuration `dir` holds. */
+function configuredRunners(dir) {
+    const runners = new Set(packageRunnerKeys(dir));
+    for (const name of RUNNER_CONFIG_FILES) {
+        if (existsSync(path.join(dir, name)))
+            runners.add(name.startsWith('jest.') ? 'jest' : 'vitest');
+    }
+    if (!runners.has('vitest') && viteConfiguresTest(dir))
+        runners.add('vitest');
+    return runners;
+}
+/** True when `dir` holds a Vitest or Jest configuration. */
+export function isRunnerProjectDir(dir) {
+    return configuredRunners(dir).size > 0;
+}
+/** pytest configuration files, and the section each must contain (none: always). */
+const PYTEST_CONFIG_SECTIONS = [
+    ['pytest.ini', undefined],
+    ['pyproject.toml', /^\s*\[tool\.pytest(?:\.ini_options)?\]/m],
+    ['tox.ini', /^\s*\[pytest\]/m],
+    ['setup.cfg', /^\s*\[tool:pytest\]/m],
+];
+/**
+ * #1248: true when `dir` holds pytest configuration; with `conftest`, a
+ * `conftest.py` counts too (see the header note).
+ */
+export function isPytestProjectDir(dir, conftest = false) {
+    if (conftest && existsSync(path.join(dir, 'conftest.py')))
+        return true;
+    return PYTEST_CONFIG_SECTIONS.some(([name, section]) => {
+        if (!section)
+            return existsSync(path.join(dir, name));
+        const text = readSmallFile(path.join(dir, name));
+        return text !== undefined && section.test(text);
+    });
+}
+/**
+ * #1248: true when `dir`, or a directory above it no higher than `boundary`,
+ * is configured for pytest (including a `conftest.py`).
+ */
+export function isPytestProject(dir, boundary = findProjectRoot()) {
+    const root = realDir(boundary);
+    let current = realDir(dir);
+    const bounded = isWithin(root, current);
+    for (;;) {
+        if (isPytestProjectDir(current, true))
+            return true;
+        if (!bounded || current === root)
+            return false;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
+/**
+ * #1272: the runner configured by the runner project that `dir` belongs to:
+ * the nearest directory at or above `dir`, no higher than `boundary`, with
+ * runner configuration. Jest config (`jest.config.*`, or a `jest` key in
+ * package.json) means jest; Vitest config (`vitest.config.*`,
+ * `vitest.workspace.*`, a `vite.config.*` with `test`, or a `vitest` key)
+ * means vitest. Undefined when no project is found or it configures both, so
+ * the caller keeps its own choice.
+ */
+export function runnerFrameworkFor(dir, boundary = findProjectRoot()) {
+    const root = realDir(boundary);
+    let current = realDir(dir);
+    const bounded = isWithin(root, current);
+    for (;;) {
+        const runners = configuredRunners(current);
+        if (runners.size > 0)
+            return runners.size === 1 ? [...runners][0] : undefined;
+        if (!bounded || current === root)
+            return undefined;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+/**
+ * The nearest directory at or above `file` with runner configuration, searching no
+ * higher than `boundary`. Undefined when the file lies outside the boundary or
+ * no directory on the way has runner configuration.
+ */
+export function findRunnerProjectDir(file, boundary, cwd = process.cwd(), checked = new Map()) {
+    const root = realDir(boundary);
+    let dir = path.dirname(runnerFilePath(file, cwd));
+    if (!isWithin(root, dir))
+        return undefined;
+    // #1248: Python files run from pytest config, other files from Vitest/Jest config.
+    const python = isPythonTestFile(file);
+    for (;;) {
+        const key = python ? `pytest:${dir}` : dir;
+        let isProject = checked.get(key);
+        if (isProject === undefined) {
+            isProject = python ? isPytestProjectDir(dir) : isRunnerProjectDir(dir);
+            checked.set(key, isProject);
+        }
+        if (isProject)
+            return dir;
+        if (dir === root)
+            return undefined;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Directory to start the runner in for `file`: its runner project, unless the
+ * current directory is already inside that project (or none is found), in
+ * which case the current directory is kept.
+ */
+export function runnerCwdFor(file, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const project = findRunnerProjectDir(file, options.boundary ?? findProjectRoot(), cwd, options.checked);
+    if (!project || isWithin(project, realDir(cwd)))
+        return cwd;
+    return project;
+}
+/**
+ * Group `files` by the directory each must run from, in first-seen order.
+ * Files keep the spelling they were given. #1248: Python files never share a
+ * group with other files, since only pytest runs them.
+ */
+export function groupByRunnerProject(files, options = {}) {
+    const resolved = {
+        cwd: options.cwd ?? process.cwd(),
+        boundary: options.boundary ?? findProjectRoot(),
+        checked: options.checked ?? new Map(),
+    };
+    const groups = new Map();
+    for (const file of files) {
+        const cwd = runnerCwdFor(file, resolved);
+        const key = `${isPythonTestFile(file) ? 'py' : 'js'}\0${cwd}`;
+        const group = groups.get(key);
+        if (group)
+            group.files.push(file);
+        else
+            groups.set(key, { cwd, files: [file] });
+    }
+    return [...groups.values()];
+}
+/**
+ * Handler-side check for an execute-tests payload. `testFiles` must name
+ * files or directories inside the project (#1126). An explicit `projectRoot`
+ * must be a directory inside the project, checked by realpath so `..`, an
+ * outside absolute path or a symlink pointing out is refused; relative test
+ * files are then read from it, and every path is returned absolute.
+ */
+export async function requireTestRunTargets(taskType, testFiles, projectRoot) {
+    const fileOptions = { allowMissing: true, allowDirectory: true };
+    if (projectRoot === undefined) {
+        const confined = await requirePayloadFiles(taskType, 'testFiles', testFiles, fileOptions);
+        return confined.success ? ok({ testFiles: confined.value }) : confined;
+    }
+    const checked = await requireRunProjectRoot(taskType, projectRoot);
+    if (!checked.success)
+        return checked;
+    const root = checked.value;
+    const confined = await requirePayloadFiles(taskType, 'testFiles', testFiles, { ...fileOptions, basePath: root });
+    if (!confined.success)
+        return confined;
+    return ok({ testFiles: confined.value.map(file => path.resolve(root, file)), projectRoot: root });
+}
+/**
+ * An explicit `projectRoot` (MCP `test_execute_parallel`, CLI
+ * `aqe test execute --project-root`): a directory inside the project, checked
+ * by realpath so `..`, an outside absolute path or a symlink pointing out is
+ * refused. Returns the absolute directory.
+ */
+export async function requireRunProjectRoot(taskType, projectRoot) {
+    const checked = await requirePayloadPath(taskType, 'projectRoot', projectRoot, { allowDirectory: true });
+    if (!checked.success)
+        return checked;
+    const root = path.resolve(realDir(process.cwd()), checked.value);
+    let isDirectory = false;
+    try {
+        isDirectory = statSync(root).isDirectory();
+    }
+    catch { /* reported below */ }
+    if (!isDirectory) {
+        return err(new CallerInputError(`Invalid ${taskType} payload: 'projectRoot' must be a directory inside the project.`));
+    }
+    return ok(root);
+}
+//# sourceMappingURL=test-runner-project.js.map

package/dist/skills/security-visual-testing/index.d.ts

@@ -84,7 +84,9 @@ export declare class SecurityVisualTestingSkill implements ISecurityVisualTestin
      */
     validateURLSecurity(url: string): Promise<Result<URLSecurityValidation, Error>>;
     /**
-     * Detect PII in screenshot
+     * Detect PII in screenshot.
+     * No OCR scanner is available, so the result says the screenshot was not
+     * scanned (#1228): detected is null and confidence -1, never "no PII found".
      */
     detectPII(screenshotPath: string): Promise<Result<PIIDetectionResult, Error>>;
     private ensureInitialized;

package/dist/skills/security-visual-testing/index.js

@@ -142,20 +142,17 @@ export class SecurityVisualTestingSkill {
                     accessibilityReport = accessibilityResult.value;
                 }
             }
-            // Step 4: Detect PII in screenshots if enabled
+            // Step 4: Detect PII in screenshots if enabled. #1228: no scanner exists,
+            // so each screenshot is reported as not scanned, never as free of PII.
             if (this.config.pii.enabled && options.detectPII !== false) {
-                // In a real implementation, this would scan all captured screenshots
-                // For now, we'll generate a placeholder result
                 for (const url of secureUrls) {
-                    piiDetections.push({
-                        detected: false,
-                        types: [],
-                        locations: [],
-                        screenshot: { original: `${url}-screenshot.png` },
-                        confidence: 0.95,
-                    });
+                    const screenshot = visualReport.results.find((r) => r.url === url)?.screenshot.path.value ?? '';
+                    const detection = await this.detectPII(screenshot);
+                    if (detection.success)
+                        piiDetections.push(detection.value);
                 }
             }
+            const piiScanned = piiDetections.filter((p) => p.measured);
             // Step 5: Generate recommendations
             const recommendations = this.generateRecommendations(urlValidations, visualReport, accessibilityReport, piiDetections);
             // Build report
@@ -166,7 +163,7 @@ export class SecurityVisualTestingSkill {
                     visualTestsPassed: visualReport.passed,
                     visualTestsFailed: visualReport.failed,
                     accessibilityIssues: accessibilityReport?.totalViolations ?? 0,
-                    piiDetections: piiDetections.filter((p) => p.detected).length,
+                    piiDetections: piiScanned.length > 0 ? piiScanned.filter((p) => p.detected === true).length : -1,
                     duration: Date.now() - startTime,
                 },
                 urlValidations,
@@ -216,14 +213,22 @@ export class SecurityVisualTestingSkill {
                 return err(new Error(`Screenshot capture failed: ${screenshotResult.error.message}`));
             }
             const screenshot = screenshotResult.value;
-            // Step 5: Detect PII if enabled
-            let piiDetected = false;
+            // Step 5: Detect PII if enabled. #1228: unscanned is null, not false.
+            let piiDetected = null;
+            let piiNotMeasuredReason = 'PII NOT MEASURED: no PII scan was requested';
             let piiTypes = [];
             let maskedPath;
             if (this.config.pii.enabled && (options.maskPII ?? this.config.pii.autoMask)) {
-                const piiResult = await this.detectPII(screenshot.path || 'screenshot.png');
-                if (piiResult.success && piiResult.value.detected) {
-                    piiDetected = true;
+                const piiResult = await this.detectPII(screenshot.path || '');
+                if (!piiResult.success) {
+                    piiNotMeasuredReason = `PII NOT MEASURED: ${piiResult.error.message}`;
+                }
+                else if (!piiResult.value.measured) {
+                    piiNotMeasuredReason = piiResult.value.notMeasuredReason;
+                }
+                else {
+                    piiDetected = piiResult.value.detected;
+                    piiNotMeasuredReason = undefined;
                     piiTypes = piiResult.value.types;
                     maskedPath = piiResult.value.screenshot.masked;
                 }
@@ -242,6 +247,7 @@ export class SecurityVisualTestingSkill {
                     masked: maskedPath,
                 },
                 piiDetected,
+                ...(piiNotMeasuredReason ? { piiNotMeasuredReason } : {}),
                 piiTypes,
                 securityValidation: validation,
                 timestamp: new Date(),
@@ -270,24 +276,18 @@ export class SecurityVisualTestingSkill {
                 path: result.screenshot.path.value,
                 timestamp: result.screenshot.timestamp,
             }));
+            // #1228: a missing diff is -1 and a new baseline is `new`, not a 0% pass or a failure
             const visualRegressions = visualReport.results.map((result) => ({
                 viewport: result.viewport,
-                diffPercentage: result.diff?.diffPercentage ?? 0,
-                status: result.status === 'passed' ? 'passed' : 'failed',
+                diffPercentage: result.diff?.diffPercentage ?? -1,
+                status: result.status,
             }));
-            // Detect layout shifts if enabled
+            // #1228: element positions are not compared across viewports, so layout
+            // shifts are reported as not measured instead of "no shifts detected".
             const layoutShifts = [];
-            if (options.detectLayoutShifts) {
-                // In a real implementation, this would analyze element positions across viewports
-                // For now, we'll generate placeholder data
-                layoutShifts.push({
-                    viewport: options.viewports[0],
-                    affectedElements: [],
-                    score: 0,
-                    severity: 'low',
-                    description: 'No significant layout shifts detected',
-                });
-            }
+            const layoutShiftsNotMeasured = options.detectLayoutShifts
+                ? { layoutShiftsMeasured: false, layoutShiftsNotMeasuredReason: 'layout shift detection is not implemented: element positions were not compared across viewports' }
+                : {};
             // Generate recommendations
             const recommendations = [];
             if (visualReport.failed > 0) {
@@ -301,6 +301,7 @@ export class SecurityVisualTestingSkill {
                 viewports: options.viewports,
                 screenshots,
                 layoutShifts,
+                ...layoutShiftsNotMeasured,
                 visualRegressions,
                 recommendations,
             };
@@ -367,20 +368,22 @@ export class SecurityVisualTestingSkill {
         }
     }
     /**
-     * Detect PII in screenshot
+     * Detect PII in screenshot.
+     * No OCR scanner is available, so the result says the screenshot was not
+     * scanned (#1228): detected is null and confidence -1, never "no PII found".
      */
     async detectPII(screenshotPath) {
         try {
-            // In a real implementation, this would use OCR and pattern matching
-            // For now, we'll return a placeholder result
             const result = {
-                detected: false,
+                detected: null,
                 types: [],
                 locations: [],
                 screenshot: {
                     original: screenshotPath,
                 },
-                confidence: 0.95,
+                confidence: -1,
+                measured: false,
+                notMeasuredReason: 'PII NOT MEASURED: no screenshot PII scanner (OCR) is available, so the screenshot was not scanned',
             };
             return ok(result);
         }
@@ -454,6 +457,17 @@ export class SecurityVisualTestingSkill {
                 affectedUrls: [], // Would need to track which URLs had PII
             });
         }
+        // #1228: an unscanned screenshot needs a manual check, it is not clean
+        const piiUnscanned = piiDetections.filter((p) => !p.measured);
+        if (piiUnscanned.length > 0) {
+            recommendations.push({
+                type: 'pii',
+                severity: 'medium',
+                description: `PII NOT MEASURED for ${piiUnscanned.length} screenshot(s): ${piiUnscanned[0].notMeasuredReason ?? 'not scanned'}`,
+                action: 'Review the screenshots for PII manually before sharing them',
+                affectedUrls: [],
+            });
+        }
         return recommendations;
     }
 }

package/dist/skills/security-visual-testing/types.d.ts

@@ -27,14 +27,19 @@ export interface SecurityIssue {
  * PII detection result in screenshot
  */
 export interface PIIDetectionResult {
-    detected: boolean;
+    /** null when no scan ran: not scanned is not "no PII found" (#1228). */
+    detected: boolean | null;
     types: PIIType[];
     locations: PIILocation[];
     screenshot: {
         original: string;
         masked?: string;
     };
+    /** -1 when no scan ran (#1228). */
     confidence: number;
+    /** false when the screenshot was not scanned; see notMeasuredReason (#1228). */
+    measured: boolean;
+    notMeasuredReason?: string;
 }
 /**
  * Types of PII that can be detected
@@ -77,6 +82,7 @@ export interface SecurityVisualAuditReport {
         visualTestsPassed: number;
         visualTestsFailed: number;
         accessibilityIssues: number;
+        /** Screenshots with PII found; -1 when no screenshot was scanned (#1228). */
         piiDetections: number;
         duration: number;
     };
@@ -126,7 +132,9 @@ export interface PIISafeScreenshot {
         original: string;
         masked?: string;
     };
-    piiDetected: boolean;
+    /** null when the screenshot was not scanned for PII (#1228). */
+    piiDetected: boolean | null;
+    piiNotMeasuredReason?: string;
     piiTypes: PIIType[];
     securityValidation: URLSecurityValidation;
     timestamp: Date;
@@ -163,10 +171,18 @@ export interface ResponsiveVisualAuditReport {
         timestamp: Date;
     }>;
     layoutShifts: LayoutShift[];
+    /**
+     * false when layout shifts were requested but not measured: an empty
+     * `layoutShifts` list is then not a clean result (#1228).
+     */
+    layoutShiftsMeasured?: boolean;
+    layoutShiftsNotMeasuredReason?: string;
     visualRegressions: Array<{
         viewport: Viewport;
+        /** -1 when no diff was computed, e.g. a new baseline (#1228). */
         diffPercentage: number;
-        status: 'passed' | 'failed';
+        /** `new`: no baseline existed, so nothing was compared. */
+        status: 'passed' | 'failed' | 'new';
     }>;
     recommendations: string[];
 }