@e2edev/e2e 0.2.0

package/dist/internal/errors.d.ts

@@ -0,0 +1,98 @@
+/** Runner-owned error taxonomy and exit-code mapping (spec 06-cli.md). */
+import { type BackendErrorCode } from '../backend/contract.ts';
+/** Message of an arbitrary thrown value, for diagnostics that must not throw. */
+export declare function errorMessage(cause: unknown): string;
+export type ErrorCategory = 'test' | 'configuration' | 'infrastructure' | 'internal' | 'interrupted';
+export type ErrorPhase = 'config' | 'collection' | 'launch' | 'beforeAll' | 'beforeEach' | 'body' | 'afterEach' | 'afterAll' | 'cleanup' | 'report';
+export interface SerializedError {
+    category: ErrorCategory;
+    code: string;
+    message: string;
+    retryable: boolean;
+    phase?: ErrorPhase;
+    scopeId?: string;
+    stack?: string;
+}
+/** Marks classified errors so instances survive isolated module realms. */
+declare const E2E_ERROR_MARKER: unique symbol;
+/**
+ * Normalizes a backend failure, including one thrown by another copy of the
+ * backend module.
+ *
+ * A backend imported by a config file is loaded through a different module
+ * registry than the runner, so its `BackendError` is a different class and
+ * `instanceof` misses it. Detection is therefore structural, keyed on the
+ * closed code set: without this, every out-of-tree backend's typed failures
+ * silently degrade to a generic error and lose their taxonomy. A foreign
+ * instance is held to the same retryability rule as the local class.
+ */
+export declare function asBackendError(value: unknown): {
+    code: BackendErrorCode;
+    message: string;
+    retryable: boolean;
+} | undefined;
+/** Base class for every runner-classified error. */
+export declare class E2EError extends Error {
+    readonly category: ErrorCategory;
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly [E2E_ERROR_MARKER] = true;
+    constructor(category: ErrorCategory, code: string, message: string, options?: {
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+/** Detects an E2EError created by another copy of this module. */
+export declare function isForeignE2EError(value: unknown): value is Error & {
+    category: ErrorCategory;
+    code: string;
+    retryable: boolean;
+};
+export declare class ConfigurationError extends E2EError {
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class CollectionError extends ConfigurationError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class InfrastructureError extends E2EError {
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class TestError extends E2EError {
+    constructor(code: string, message: string, options?: {
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+export declare class TestTimeoutError extends TestError {
+    constructor(message: string);
+}
+/** Maps a category to its process exit code per 06-cli.md. */
+export declare function exitCodeForCategory(category: ErrorCategory): 0 | 1 | 2 | 3 | 4 | 130;
+/** Combines exit codes for mixed outcomes using precedence 130 > 4 > 3 > 2 > 1 > 0. */
+export declare function combineExitCodes(codes: readonly number[]): 0 | 1 | 2 | 3 | 4 | 130;
+/**
+ * Canonical BackendError -> runner taxonomy mapping.
+ * Applies to every backend surface: lifecycle, app, screen, artifacts,
+ * state capture/restore, and observation. Non-BackendError causes become
+ * non-retryable infrastructure BACKEND_FAILURE.
+ */
+export declare function translateBackendError(cause: unknown, suffix?: string): E2EError;
+/** Classifies an arbitrary thrown value into an E2EError; unknown values become test failures. */
+export declare function classifyError(value: unknown): E2EError;
+/** Serializes an error into the bounded report-1 error shape. */
+export declare function serializeError(error: E2EError, extras?: {
+    phase?: ErrorPhase;
+    scopeId?: string;
+}): SerializedError;
+/** Strips C0/C1 control characters except tab and newline. */
+export declare function sanitizeText(text: string): string;
+/** Truncates a string so its UTF-8 encoding fits maxBytes without splitting a code point. */
+export declare function truncateUtf8(text: string, maxBytes: number): string;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/internal/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"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"}

package/dist/internal/errors.js

@@ -0,0 +1,212 @@
+/** Runner-owned error taxonomy and exit-code mapping (spec 06-cli.md). */
+import { BACKEND_ERROR_CODES, BackendError, RETRYABLE_BACKEND_ERROR_CODES, } from '../backend/contract.js';
+/** Message of an arbitrary thrown value, for diagnostics that must not throw. */
+export function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/** Marks classified errors so instances survive isolated module realms. */
+const E2E_ERROR_MARKER = Symbol.for('e2e.error.v1');
+/**
+ * Normalizes a backend failure, including one thrown by another copy of the
+ * backend module.
+ *
+ * A backend imported by a config file is loaded through a different module
+ * registry than the runner, so its `BackendError` is a different class and
+ * `instanceof` misses it. Detection is therefore structural, keyed on the
+ * closed code set: without this, every out-of-tree backend's typed failures
+ * silently degrade to a generic error and lose their taxonomy. A foreign
+ * instance is held to the same retryability rule as the local class.
+ */
+export function asBackendError(value) {
+    if (value instanceof BackendError)
+        return value;
+    if (!(value instanceof Error) || value.name !== 'BackendError')
+        return undefined;
+    const code = value.code;
+    if (!isBackendErrorCode(code))
+        return undefined;
+    const retryable = value.retryable === true;
+    if (retryable && !RETRYABLE_BACKEND_ERROR_CODES.has(code)) {
+        return { code: 'BACKEND_FAILURE', message: value.message, retryable: false };
+    }
+    return { code, message: value.message, retryable };
+}
+function isBackendErrorCode(value) {
+    return typeof value === 'string' && BACKEND_ERROR_CODES.includes(value);
+}
+/** Base class for every runner-classified error. */
+export class E2EError extends Error {
+    category;
+    code;
+    retryable;
+    [E2E_ERROR_MARKER] = true;
+    constructor(category, code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'E2EError';
+        this.category = category;
+        this.code = code;
+        this.retryable = options.retryable ?? false;
+    }
+}
+const CATEGORIES = new Set([
+    'test',
+    'configuration',
+    'infrastructure',
+    'internal',
+    'interrupted',
+]);
+/** Detects an E2EError created by another copy of this module. */
+export function isForeignE2EError(value) {
+    return (value instanceof Error &&
+        value[E2E_ERROR_MARKER] === true &&
+        CATEGORIES.has(value.category) &&
+        typeof value.code === 'string');
+}
+export class ConfigurationError extends E2EError {
+    constructor(code, message, options = {}) {
+        super('configuration', code, message, options);
+        this.name = 'ConfigurationError';
+    }
+}
+export class CollectionError extends ConfigurationError {
+    constructor(message, options = {}) {
+        super('COLLECTION_ERROR', message, options);
+        this.name = 'CollectionError';
+    }
+}
+export class InfrastructureError extends E2EError {
+    constructor(code, message, options = {}) {
+        super('infrastructure', code, message, options);
+        this.name = 'InfrastructureError';
+    }
+}
+export class TestError extends E2EError {
+    constructor(code, message, options = {}) {
+        super('test', code, message, options);
+        this.name = 'TestError';
+    }
+}
+export class TestTimeoutError extends TestError {
+    constructor(message) {
+        super('TEST_TIMEOUT', message);
+        this.name = 'TestTimeoutError';
+    }
+}
+/** Maps a category to its process exit code per 06-cli.md. */
+export function exitCodeForCategory(category) {
+    switch (category) {
+        case 'test':
+            return 1;
+        case 'configuration':
+            return 2;
+        case 'infrastructure':
+            return 3;
+        case 'internal':
+            return 4;
+        case 'interrupted':
+            return 130;
+    }
+}
+/** Combines exit codes for mixed outcomes using precedence 130 > 4 > 3 > 2 > 1 > 0. */
+export function combineExitCodes(codes) {
+    const precedence = [130, 4, 3, 2, 1, 0];
+    for (const candidate of precedence) {
+        if (codes.includes(candidate))
+            return candidate;
+    }
+    return 0;
+}
+/**
+ * Canonical BackendError -> runner taxonomy mapping.
+ * Applies to every backend surface: lifecycle, app, screen, artifacts,
+ * state capture/restore, and observation. Non-BackendError causes become
+ * non-retryable infrastructure BACKEND_FAILURE.
+ */
+export function translateBackendError(cause, suffix = '') {
+    if (cause instanceof E2EError)
+        return cause;
+    const backendError = asBackendError(cause);
+    if (backendError !== undefined) {
+        switch (backendError.code) {
+            case 'NODE_STALE':
+                return new TestError('LOCATOR_NOT_FOUND', `node became stale${suffix}`, { cause });
+            case 'FRAME_NOT_FOUND':
+                return new TestError('LOCATOR_NOT_FOUND', `${backendError.message}${suffix}`, { cause });
+            case 'FRAME_AMBIGUOUS':
+                return new TestError('LOCATOR_AMBIGUOUS', `${backendError.message}${suffix}`, { cause });
+            case 'NOT_ACTIONABLE':
+                return new TestError('ACTION_FAILED', `${backendError.message}${suffix}`, { cause });
+            case 'ACTION_MAY_HAVE_COMMITTED':
+                return new TestError('ACTION_FAILED', `${backendError.message}${suffix}`, { cause });
+            case 'OPERATION_TIMEOUT':
+                return new TestError('ACTION_FAILED', `operation timed out${suffix}`, { cause });
+            case 'CANCELLED':
+                return new E2EError('infrastructure', 'CANCELLED', 'operation cancelled', { cause });
+            case 'UNSUPPORTED_CAPABILITY':
+                return new E2EError('configuration', 'UNSUPPORTED_CAPABILITY', backendError.message, { cause });
+            case 'INVALID_STATE':
+                return new TestError('APP_NOT_OPEN', backendError.message, { cause });
+            case 'BACKEND_FAILURE':
+                return new E2EError('infrastructure', 'BACKEND_FAILURE', backendError.message, { cause });
+        }
+    }
+    return new E2EError('infrastructure', 'BACKEND_FAILURE', errorMessage(cause), { cause });
+}
+/** Classifies an arbitrary thrown value into an E2EError; unknown values become test failures. */
+export function classifyError(value) {
+    if (value instanceof E2EError)
+        return value;
+    if (isForeignE2EError(value)) {
+        return new E2EError(value.category, value.code, value.message, {
+            retryable: value.retryable,
+            cause: value,
+        });
+    }
+    if (asBackendError(value) !== undefined) {
+        return translateBackendError(value);
+    }
+    if (value instanceof Error) {
+        return new TestError('ERROR', value.message, { cause: value });
+    }
+    return new TestError('ERROR', String(value));
+}
+const MAX_MESSAGE_BYTES = 8192;
+/** Serializes an error into the bounded report-1 error shape. */
+export function serializeError(error, extras = {}) {
+    const serialized = {
+        category: error.category,
+        code: error.code,
+        message: truncateUtf8(sanitizeText(error.message), MAX_MESSAGE_BYTES),
+        retryable: error.retryable,
+    };
+    if (extras.phase !== undefined)
+        serialized.phase = extras.phase;
+    if (extras.scopeId !== undefined)
+        serialized.scopeId = extras.scopeId;
+    const stack = (error.cause instanceof Error ? error.cause.stack : undefined) ?? error.stack;
+    if (stack !== undefined)
+        serialized.stack = truncateUtf8(sanitizeText(stack), 65536);
+    return serialized;
+}
+/** C0/C1 control characters except tab and newline. */
+// oxlint-disable-next-line no-control-regex -- the control range is the point
+const CONTROL_PATTERN = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+const UTF8 = new TextEncoder();
+const UTF8_DECODER = new TextDecoder();
+/** Strips C0/C1 control characters except tab and newline. */
+export function sanitizeText(text) {
+    return text.replace(CONTROL_PATTERN, '\uFFFD');
+}
+/** Truncates a string so its UTF-8 encoding fits maxBytes without splitting a code point. */
+export function truncateUtf8(text, maxBytes) {
+    const bytes = UTF8.encode(text);
+    if (bytes.byteLength <= maxBytes)
+        return text;
+    // Back up off any UTF-8 continuation bytes (10xxxxxx) so the cut lands on a
+    // code point boundary; the lead byte at the cut is excluded with its tail.
+    let end = Math.max(0, maxBytes);
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end -= 1;
+    return UTF8_DECODER.decode(bytes.subarray(0, end));
+}
+//# sourceMappingURL=errors.js.map

package/dist/internal/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"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"}

package/dist/internal/globs.d.ts

@@ -0,0 +1,29 @@
+/** Test glob grammar per 05-config.md. */
+interface CompiledGlob {
+    readonly segments: readonly GlobSegment[];
+}
+type GlobSegment = {
+    kind: 'globstar';
+} | {
+    kind: 'pattern';
+    regexp: RegExp;
+    allowsDot: boolean;
+};
+/**
+ * Compiles one glob string. Supported: `*` (zero or more non-`/`), `?` (one
+ * non-`/`), a complete `**` segment (zero or more path segments). Braces,
+ * extglobs, and `!` exclusions are unsupported.
+ */
+export declare function compileGlob(pattern: string): CompiledGlob;
+/** Matches one already-normalized relative path (with `/` separators). */
+export declare function matchesGlob(glob: CompiledGlob, relativePath: string): boolean;
+/**
+ * Discovers regular files under `root` matching any glob. Matching is
+ * case-sensitive, does not follow directory symlinks, and results are sorted
+ * by Unicode code point.
+ */
+export declare function discoverFiles(root: string, patterns: readonly string[]): string[];
+/** Sorts strings by Unicode code point as required by 11-lifecycle.md. */
+export declare function compareCodePoints(a: string, b: string): number;
+export {};
+//# sourceMappingURL=globs.d.ts.map

package/dist/internal/globs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"globs.d.ts","sourceRoot":"","sources":["../../src/internal/globs.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAO1C,UAAU,YAAY;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAC3C;AAED,KAAK,WAAW,GACZ;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC;AAE5D;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAoBzD;AAaD,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAG7E;AA2BD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAajF;AA0BD,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAS9D"}

package/dist/internal/globs.js

@@ -0,0 +1,126 @@
+/** Test glob grammar per 05-config.md. */
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+import { ConfigurationError } from './errors.js';
+import { escapeRegexpChar } from './regexp.js';
+/**
+ * Compiles one glob string. Supported: `*` (zero or more non-`/`), `?` (one
+ * non-`/`), a complete `**` segment (zero or more path segments). Braces,
+ * extglobs, and `!` exclusions are unsupported.
+ */
+export function compileGlob(pattern) {
+    if (pattern.length === 0)
+        throw new ConfigurationError('INVALID_GLOB', 'empty glob pattern');
+    if (pattern.startsWith('!')) {
+        throw new ConfigurationError('INVALID_GLOB', `leading '!' exclusions are unsupported: ${pattern}`);
+    }
+    const segments = pattern.split('/').map((segment) => {
+        if (segment === '**')
+            return { kind: 'globstar' };
+        if (segment.includes('**')) {
+            throw new ConfigurationError('INVALID_GLOB', `'**' must be a complete path segment: ${pattern}`);
+        }
+        return {
+            kind: 'pattern',
+            regexp: compileSegment(segment),
+            allowsDot: segment.startsWith('.'),
+        };
+    });
+    return { segments };
+}
+function compileSegment(segment) {
+    let source = '^';
+    for (let i = 0; i < segment.length; i += 1) {
+        const ch = segment[i];
+        if (ch === '*')
+            source += '[^/]*';
+        else if (ch === '?')
+            source += '[^/]';
+        else
+            source += escapeRegexpChar(ch);
+    }
+    return new RegExp(`${source}$`);
+}
+/** Matches one already-normalized relative path (with `/` separators). */
+export function matchesGlob(glob, relativePath) {
+    const parts = relativePath.split('/');
+    return matchFrom(glob.segments, 0, parts, 0);
+}
+function matchFrom(segments, segmentIndex, parts, partIndex) {
+    if (segmentIndex === segments.length)
+        return partIndex === parts.length;
+    const segment = segments[segmentIndex];
+    if (segment.kind === 'globstar') {
+        for (let skip = 0; skip <= parts.length - partIndex; skip += 1) {
+            for (let i = 0; i < skip; i += 1) {
+                const part = parts[partIndex + i];
+                if (part.startsWith('.'))
+                    return false;
+            }
+            if (matchFrom(segments, segmentIndex + 1, parts, partIndex + skip))
+                return true;
+        }
+        return false;
+    }
+    if (partIndex >= parts.length)
+        return false;
+    const part = parts[partIndex];
+    if (part.startsWith('.') && !segment.allowsDot)
+        return false;
+    if (!segment.regexp.test(part))
+        return false;
+    return matchFrom(segments, segmentIndex + 1, parts, partIndex + 1);
+}
+/**
+ * Discovers regular files under `root` matching any glob. Matching is
+ * case-sensitive, does not follow directory symlinks, and results are sorted
+ * by Unicode code point.
+ */
+export function discoverFiles(root, patterns) {
+    const compiled = patterns.map(compileGlob);
+    // No pattern segment can match a dot-directory unless it was spelled with
+    // a leading dot, so `.git`, `.e2e`, and friends are pruned at the walk
+    // instead of being read and rejected file by file.
+    const visitDotDirectories = compiled.some((glob) => glob.segments.some((segment) => segment.kind === 'pattern' && segment.allowsDot));
+    const matched = new Set();
+    walk(root, '', visitDotDirectories, (relative) => {
+        if (compiled.some((glob) => matchesGlob(glob, relative)))
+            matched.add(relative);
+    });
+    return [...matched].toSorted(compareCodePoints);
+}
+function walk(absoluteDir, relativeDir, visitDotDirectories, onFile) {
+    let entries;
+    try {
+        entries = readdirSync(absoluteDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const relative = relativeDir === '' ? entry.name : `${relativeDir}/${entry.name}`;
+        if (entry.isDirectory()) {
+            if (entry.name === 'node_modules')
+                continue;
+            if (!visitDotDirectories && entry.name.startsWith('.'))
+                continue;
+            walk(path.join(absoluteDir, entry.name), relative, visitDotDirectories, onFile);
+        }
+        else if (entry.isFile()) {
+            onFile(relative);
+        }
+    }
+}
+/** Sorts strings by Unicode code point as required by 11-lifecycle.md. */
+export function compareCodePoints(a, b) {
+    const aPoints = [...a];
+    const bPoints = [...b];
+    const length = Math.min(aPoints.length, bPoints.length);
+    for (let i = 0; i < length; i += 1) {
+        const diff = aPoints[i].codePointAt(0) - bPoints[i].codePointAt(0);
+        if (diff !== 0)
+            return diff;
+    }
+    return aPoints.length - bPoints.length;
+}
+//# sourceMappingURL=globs.js.map

package/dist/internal/globs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"globs.js","sourceRoot":"","sources":["../../src/internal/globs.ts"],"names":[],"mappings":"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"}

package/dist/internal/ids.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Percent-encodes one title per 11-lifecycle.md: RFC 3986 unreserved characters
+ * stay literal, every other UTF-8 byte becomes uppercase %HH.
+ */
+export declare function encodeTitle(title: string): string;
+/** Validates one raw title per 11-lifecycle.md (1..512 UTF-8 bytes after NFC, no NUL). */
+export declare function validateTitle(title: string): string | null;
+/** Builds a stable test ID: `<normalized-relative-file>::<encoded-title-path>`. */
+export declare function testId(relativeFile: string, titlePath: readonly string[]): string;
+/**
+ * Canonical collision-free map key for a title path. Joins with NUL, which
+ * `validateTitle` forbids inside titles, so distinct paths never collide.
+ */
+export declare function titlePathKey(titlePath: readonly string[]): string;
+/** Builds a setup-test ID: `setup::<test-id>`. */
+export declare function setupTestId(relativeFile: string, titlePath: readonly string[]): string;
+/** SHA-256 of a UTF-8 string, lowercase hex. */
+export declare function sha256Hex(input: string | Uint8Array): string;
+/**
+ * RFC 8785 (JCS) canonical JSON serialization for JSON-safe values.
+ * Numbers must be finite; non-JSON values throw.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** SHA-256 over the RFC 8785 canonical form, lowercase hex. */
+export declare function canonicalDigest(value: unknown): string;
+/** Result ID per 13-reporting.md: SHA-256/JCS of `{ testId, targetId }`. */
+export declare function resultId(test: string, targetId: string): string;
+/** Generates one lowercase UUIDv7 string. */
+export declare function uuidv7(now?: number): string;
+/** RFC 3339 UTC timestamp with exactly millisecond precision. */
+export declare function timestamp(date?: Date): string;
+//# sourceMappingURL=ids.d.ts.map

package/dist/internal/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/internal/ids.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqBjD;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ1D;AAED,mFAAmF;AACnF,wBAAgB,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEjF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEjE;AAED,kDAAkD;AAClD,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEtF;AAED,gDAAgD;AAChD,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAE5D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAuBpD;AAYD,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,6CAA6C;AAC7C,wBAAgB,MAAM,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM,CAavD;AAED,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,IAAI,GAAE,IAAiB,GAAG,MAAM,CAEzD"}

package/dist/internal/ids.js

@@ -0,0 +1,124 @@
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * Percent-encodes one title per 11-lifecycle.md: RFC 3986 unreserved characters
+ * stay literal, every other UTF-8 byte becomes uppercase %HH.
+ */
+export function encodeTitle(title) {
+    const normalized = title.normalize('NFC');
+    const bytes = new TextEncoder().encode(normalized);
+    let out = '';
+    for (const byte of bytes) {
+        const ch = String.fromCharCode(byte);
+        if ((byte >= 0x41 && byte <= 0x5a) ||
+            (byte >= 0x61 && byte <= 0x7a) ||
+            (byte >= 0x30 && byte <= 0x39) ||
+            ch === '-' ||
+            ch === '.' ||
+            ch === '_' ||
+            ch === '~') {
+            out += ch;
+        }
+        else {
+            out += `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+        }
+    }
+    return out;
+}
+/** Validates one raw title per 11-lifecycle.md (1..512 UTF-8 bytes after NFC, no NUL). */
+export function validateTitle(title) {
+    const normalized = title.normalize('NFC');
+    const bytes = new TextEncoder().encode(normalized).byteLength;
+    if (bytes < 1 || bytes > 512) {
+        return `title must be 1 through 512 UTF-8 bytes after NFC, got ${bytes}`;
+    }
+    if (normalized.includes('\u0000'))
+        return 'title must not contain NUL';
+    return null;
+}
+/** Builds a stable test ID: `<normalized-relative-file>::<encoded-title-path>`. */
+export function testId(relativeFile, titlePath) {
+    return `${relativeFile}::${titlePath.map(encodeTitle).join('::')}`;
+}
+/**
+ * Canonical collision-free map key for a title path. Joins with NUL, which
+ * `validateTitle` forbids inside titles, so distinct paths never collide.
+ */
+export function titlePathKey(titlePath) {
+    return titlePath.join('\u0000');
+}
+/** Builds a setup-test ID: `setup::<test-id>`. */
+export function setupTestId(relativeFile, titlePath) {
+    return `setup::${testId(relativeFile, titlePath)}`;
+}
+/** SHA-256 of a UTF-8 string, lowercase hex. */
+export function sha256Hex(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+/**
+ * RFC 8785 (JCS) canonical JSON serialization for JSON-safe values.
+ * Numbers must be finite; non-JSON values throw.
+ */
+export function canonicalJson(value) {
+    if (value === null)
+        return 'null';
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'number': {
+            if (!Number.isFinite(value))
+                throw new TypeError('non-finite number in canonical JSON');
+            return JSON.stringify(value);
+        }
+        case 'string':
+            return JSON.stringify(value);
+        case 'object': {
+            if (Array.isArray(value)) {
+                return `[${value.map((item) => canonicalJson(item === undefined ? null : item)).join(',')}]`;
+            }
+            const entries = Object.entries(value)
+                .filter(([, v]) => v !== undefined)
+                .toSorted(([a], [b]) => compareStrings(a, b));
+            return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+        }
+        default:
+            throw new TypeError(`value of type ${typeof value} is not JSON-safe`);
+    }
+}
+/**
+ * Orders strings by UTF-16 code unit, the ordering RFC 8785 requires. Locale
+ * collation must never be used here: it is environment-dependent, and a digest
+ * that depends on the host locale is not canonical.
+ */
+function compareStrings(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+/** SHA-256 over the RFC 8785 canonical form, lowercase hex. */
+export function canonicalDigest(value) {
+    return sha256Hex(canonicalJson(value));
+}
+/** Result ID per 13-reporting.md: SHA-256/JCS of `{ testId, targetId }`. */
+export function resultId(test, targetId) {
+    return canonicalDigest({ testId: test, targetId });
+}
+/** Generates one lowercase UUIDv7 string. */
+export function uuidv7(now = Date.now()) {
+    const bytes = randomBytes(16);
+    const ts = BigInt(now);
+    bytes[0] = Number((ts >> 40n) & 0xffn);
+    bytes[1] = Number((ts >> 32n) & 0xffn);
+    bytes[2] = Number((ts >> 24n) & 0xffn);
+    bytes[3] = Number((ts >> 16n) & 0xffn);
+    bytes[4] = Number((ts >> 8n) & 0xffn);
+    bytes[5] = Number(ts & 0xffn);
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Buffer.from(bytes).toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** RFC 3339 UTC timestamp with exactly millisecond precision. */
+export function timestamp(date = new Date()) {
+    return date.toISOString();
+}
+//# sourceMappingURL=ids.js.map