@scenarist/core 0.2.1 → 0.3.1

package/dist/domain/response-selector.js

@@ -1,9 +1,11 @@
-import { ResponseSelectionError } from "../ports/driven/response-selector.js";
+import { ScenaristError, ErrorCodes } from "../types/errors.js";
 import { extractFromPath } from "./path-extraction.js";
 import { applyTemplates } from "./template-replacement.js";
 import { matchesRegex } from "./regex-matching.js";
 import { createStateResponseResolver } from "./state-response-resolver.js";
 import { deepEquals } from "./deep-equals.js";
+import { noOpLogger } from "../adapters/index.js";
+import { LogCategories, LogEvents } from "./log-events.js";
 const SPECIFICITY_RANGES = {
     MATCH_CRITERIA_BASE: 100,
     SEQUENCE_FALLBACK: 1,
@@ -21,26 +23,41 @@ const SPECIFICITY_RANGES = {
  * @param options.stateManager - Optional state manager for capture/injection (Phase 3)
  */
 export const createResponseSelector = (options = {}) => {
-    const { sequenceTracker, stateManager } = options;
+    const { sequenceTracker, stateManager, logger = noOpLogger } = options;
     return {
         selectResponse(testId, scenarioId, context, mocks) {
+            const logContext = { testId, scenarioId };
+            // Log the number of candidate mocks
+            logger.debug(LogCategories.MATCHING, LogEvents.MOCK_CANDIDATES_FOUND, logContext, {
+                count: mocks.length,
+            });
             let bestMatch = null;
+            // Track if we skipped any exhausted sequences (for better error messages)
+            let skippedExhaustedSequences = false;
             // Find all matching mocks and score them by specificity
             for (let mockIndex = 0; mockIndex < mocks.length; mockIndex++) {
-                // Index is guaranteed in bounds by loop condition (0 <= mockIndex < length)
+                // eslint-disable-next-line security/detect-object-injection -- Index bounded by loop (0 <= i < length)
                 const mockWithParams = mocks[mockIndex];
                 const mock = mockWithParams.mock;
                 // Skip exhausted sequences (repeat: 'none' that have been exhausted)
                 if (mock.sequence && sequenceTracker) {
                     const { exhausted } = sequenceTracker.getPosition(testId, scenarioId, mockIndex);
                     if (exhausted) {
+                        skippedExhaustedSequences = true;
                         continue; // Skip to next mock, allowing fallback to be selected
                     }
                 }
                 // Check if this mock has match criteria
                 if (mock.match) {
                     // If match criteria exists, check if it matches the request
-                    if (matchesCriteria(context, mock.match, testId, stateManager)) {
+                    const matched = matchesCriteria(context, mock.match, testId, stateManager);
+                    // Log the evaluation result
+                    logger.debug(LogCategories.MATCHING, LogEvents.MOCK_MATCH_EVALUATED, logContext, {
+                        mockIndex,
+                        matched,
+                        hasCriteria: true,
+                    });
+                    if (matched) {
                         // Match criteria always have higher priority than fallbacks
                         // Base specificity ensures even 1 field beats any fallback
                         const specificity = SPECIFICITY_RANGES.MATCH_CRITERIA_BASE +
@@ -55,6 +72,15 @@ export const createResponseSelector = (options = {}) => {
                     continue;
                 }
                 // No match criteria = fallback mock (always matches)
+                // Log fallback evaluation with response type info for debugging Issue #328
+                logger.debug(LogCategories.MATCHING, LogEvents.MOCK_MATCH_EVALUATED, logContext, {
+                    mockIndex,
+                    matched: true,
+                    hasCriteria: false,
+                    hasSequence: !!mock.sequence,
+                    hasStateResponse: !!mock.stateResponse,
+                    hasResponse: !!mock.response,
+                });
                 // Dynamic response types (sequence, stateResponse) get higher priority than simple responses
                 // This ensures they are selected over simple fallback responses
                 // Both sequence and stateResponse get the same specificity (Issue #316 fix)
@@ -74,14 +100,29 @@ export const createResponseSelector = (options = {}) => {
             }
             // Return the best matching mock
             if (bestMatch) {
-                const { mockWithParams, mockIndex } = bestMatch;
+                const { mockWithParams, mockIndex, specificity } = bestMatch;
                 const mock = mockWithParams.mock;
+                // Log successful selection
+                logger.info(LogCategories.MATCHING, LogEvents.MOCK_SELECTED, logContext, {
+                    mockIndex,
+                    specificity,
+                });
                 // Select response (single, sequence, or stateResponse)
-                const response = selectResponseFromMock(testId, scenarioId, mockIndex, mock, sequenceTracker, stateManager);
+                const response = selectResponseFromMock(testId, scenarioId, mockIndex, mock, sequenceTracker, stateManager, logger);
                 if (!response) {
                     return {
                         success: false,
-                        error: new ResponseSelectionError(`Mock has neither response nor sequence field`),
+                        error: new ScenaristError(`Mock has neither response nor sequence field`, {
+                            code: ErrorCodes.VALIDATION_ERROR,
+                            context: {
+                                testId,
+                                scenarioId,
+                                mockInfo: {
+                                    index: mockIndex,
+                                },
+                                hint: "Each mock must have a 'response', 'sequence', or 'stateResponse' field.",
+                            },
+                        }),
                     };
                 }
                 // Phase 3: Capture state from request if configured
@@ -103,13 +144,54 @@ export const createResponseSelector = (options = {}) => {
                 // Apply afterResponse.setState to mutate state for subsequent requests
                 if (mock.afterResponse?.setState && stateManager) {
                     stateManager.merge(testId, mock.afterResponse.setState);
+                    logger.debug(LogCategories.STATE, LogEvents.STATE_SET, logContext, {
+                        setState: mock.afterResponse.setState,
+                    });
                 }
                 return { success: true, data: finalResponse };
             }
-            // No mock matched
+            // No mock matched - determine specific error type
+            if (skippedExhaustedSequences) {
+                // All matching mocks were exhausted sequences
+                logger.warn(LogCategories.SEQUENCE, LogEvents.SEQUENCE_EXHAUSTED, logContext, {
+                    url: context.url,
+                    method: context.method,
+                });
+                return {
+                    success: false,
+                    error: new ScenaristError(`Sequence exhausted for ${context.method} ${context.url}. All responses have been consumed and repeat mode is 'none'.`, {
+                        code: ErrorCodes.SEQUENCE_EXHAUSTED,
+                        context: {
+                            testId,
+                            scenarioId,
+                            requestInfo: {
+                                method: context.method,
+                                url: context.url,
+                            },
+                            hint: "Add a fallback mock to handle requests after sequence exhaustion, or use repeat: 'last' or 'cycle' instead of 'none'.",
+                        },
+                    }),
+                };
+            }
+            logger.warn(LogCategories.MATCHING, LogEvents.MOCK_NO_MATCH, logContext, {
+                url: context.url,
+                method: context.method,
+                candidateCount: 0,
+            });
             return {
                 success: false,
-                error: new ResponseSelectionError(`No mock matched for ${context.method} ${context.url}`),
+                error: new ScenaristError(`No mock matched for ${context.method} ${context.url}`, {
+                    code: ErrorCodes.NO_MOCK_FOUND,
+                    context: {
+                        testId,
+                        scenarioId,
+                        requestInfo: {
+                            method: context.method,
+                            url: context.url,
+                        },
+                        hint: "Add a fallback mock (without match criteria) to handle unmatched requests, or add a mock with matching criteria.",
+                    },
+                }),
             };
         },
     };
@@ -123,9 +205,11 @@ export const createResponseSelector = (options = {}) => {
  * @param mock - The mock definition
  * @param sequenceTracker - Optional sequence tracker for Phase 2
  * @param stateManager - Optional state manager for stateResponse
+ * @param logger - Logger for debugging
  * @returns ScenaristResponse or null if mock has no response type
  */
-const selectResponseFromMock = (testId, scenarioId, mockIndex, mock, sequenceTracker, stateManager) => {
+const selectResponseFromMock = (testId, scenarioId, mockIndex, mock, sequenceTracker, stateManager, logger) => {
+    const logContext = { testId, scenarioId };
     // Phase 2: If mock has a sequence, use sequence tracker
     if (mock.sequence) {
         if (!sequenceTracker) {
@@ -137,6 +221,7 @@ const selectResponseFromMock = (testId, scenarioId, mockIndex, mock, sequenceTra
         // Get response at current position
         // Note: Exhausted sequences are skipped during matching phase,
         // so position should always be valid here
+        // eslint-disable-next-line security/detect-object-injection -- Position bounded by sequence tracker
         const response = mock.sequence.responses[position];
         // Advance position for next call
         const repeatMode = mock.sequence.repeat || "last";
@@ -145,7 +230,7 @@ const selectResponseFromMock = (testId, scenarioId, mockIndex, mock, sequenceTra
     }
     // State-aware response: evaluate conditions against current state
     if (mock.stateResponse) {
-        return resolveStateResponse(testId, mock.stateResponse, stateManager);
+        return resolveStateResponse(testId, mock.stateResponse, stateManager, logger, logContext);
     }
     // Phase 1: Single response
     if (mock.response) {
@@ -163,18 +248,36 @@ const selectResponseFromMock = (testId, scenarioId, mockIndex, mock, sequenceTra
  * @param testId - Test ID for state isolation
  * @param stateResponse - The stateResponse configuration
  * @param stateManager - Optional state manager for state lookup
+ * @param logger - Logger for debugging
+ * @param logContext - Context for log messages
  * @returns The resolved response (matching condition or default)
  */
-const resolveStateResponse = (testId, stateResponse, stateManager) => {
+const resolveStateResponse = (testId, stateResponse, stateManager, logger, logContext) => {
     // Without stateManager, always return default
     if (!stateManager) {
+        logger.debug(LogCategories.STATE, LogEvents.STATE_RESPONSE_RESOLVED, logContext, {
+            result: "default",
+            reason: "no_state_manager",
+        });
         return stateResponse.default;
     }
     // Get current state for this test
     const currentState = stateManager.getAll(testId);
     // Create resolver and evaluate conditions
     const resolver = createStateResponseResolver();
-    return resolver.resolveResponse(stateResponse, currentState);
+    const response = resolver.resolveResponse(stateResponse, currentState);
+    // Log which response was selected and why
+    const isDefault = response === stateResponse.default;
+    const matchedCondition = isDefault
+        ? null
+        : stateResponse.conditions.find((c) => resolver.resolveResponse({ default: stateResponse.default, conditions: [c] }, currentState) !== stateResponse.default);
+    logger.debug(LogCategories.STATE, LogEvents.STATE_RESPONSE_RESOLVED, logContext, {
+        result: isDefault ? "default" : "condition",
+        currentState,
+        conditionsCount: stateResponse.conditions.length,
+        matchedWhen: matchedCondition?.when ?? null,
+    });
+    return response;
 };
 /**
  * Calculate specificity score for match criteria.
@@ -276,6 +379,7 @@ const matchesState = (stateCriteria, testId, stateManager) => {
             return false;
         }
         // Deep equality check for values (handles primitives, null, objects)
+        // eslint-disable-next-line security/detect-object-injection -- Key from Object.entries iteration
         if (!deepEquals(currentState[key], expectedValue)) {
             return false;
         }
@@ -296,6 +400,7 @@ const matchesBody = (requestBody, criteriaBody) => {
     const body = requestBody;
     // Check all required fields exist in request body with matching values
     for (const [key, criteriaValue] of Object.entries(criteriaBody)) {
+        // eslint-disable-next-line security/detect-object-injection -- Key from Object.entries iteration
         const requestValue = body[key];
         // Convert to string for matching (type coercion like headers/query)
         const stringValue = requestValue == null ? "" : String(requestValue);
@@ -378,6 +483,7 @@ const matchesHeaders = (requestHeaders, criteriaHeaders) => {
     const normalizedRequest = createNormalizedHeaderMap(requestHeaders);
     for (const [key, value] of Object.entries(criteriaHeaders)) {
         const normalizedKey = normalizeHeaderName(key);
+        // eslint-disable-next-line security/detect-object-injection -- Key normalized from Object.entries iteration
         const requestValue = normalizedRequest[normalizedKey];
         if (!requestValue || !matchesValue(requestValue, value)) {
             return false;
@@ -392,6 +498,7 @@ const matchesHeaders = (requestHeaders, criteriaHeaders) => {
 const matchesQuery = (requestQuery, criteriaQuery) => {
     // Check all required query params exist with exact matching values
     for (const [key, value] of Object.entries(criteriaQuery)) {
+        // eslint-disable-next-line security/detect-object-injection -- Key from Object.entries iteration
         const requestValue = requestQuery[key];
         if (!requestValue || !matchesValue(requestValue, value)) {
             return false;

package/dist/domain/scenario-manager.d.ts

@@ -1,4 +1,4 @@
-import type { ScenarioManager, ScenarioRegistry, ScenarioStore, SequenceTracker, StateManager } from "../ports/index.js";
+import type { ScenarioManager, ScenarioRegistry, ScenarioStore, SequenceTracker, StateManager, Logger } from "../ports/index.js";
 /**
  * Factory function to create a ScenarioManager implementation.
  *
@@ -8,13 +8,15 @@ import type { ScenarioManager, ScenarioRegistry, ScenarioStore, SequenceTracker,
  * - Any registry implementation (in-memory, Redis, files, remote)
  * - Any store implementation (in-memory, Redis, database)
  * - Any state manager implementation (in-memory, Redis, database)
+ * - Any logger implementation (console, file, remote)
  * - Proper testing with mock dependencies
  * - True hexagonal architecture
  */
-export declare const createScenarioManager: ({ registry, store, stateManager, sequenceTracker, }: {
+export declare const createScenarioManager: ({ registry, store, stateManager, sequenceTracker, logger, }: {
     registry: ScenarioRegistry;
     store: ScenarioStore;
     stateManager?: StateManager;
     sequenceTracker?: SequenceTracker;
+    logger?: Logger;
 }) => ScenarioManager;
 //# sourceMappingURL=scenario-manager.d.ts.map

package/dist/domain/scenario-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scenario-manager.d.ts","sourceRoot":"","sources":["../../src/domain/scenario-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,YAAY,EACb,MAAM,mBAAmB,CAAC;AAkC3B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GAAI,qDAKnC;IACD,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,KAAG,eAgFH,CAAC"}
+{"version":3,"file":"scenario-manager.d.ts","sourceRoot":"","sources":["../../src/domain/scenario-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,MAAM,EACP,MAAM,mBAAmB,CAAC;AAwC3B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,GAAI,6DAMnC;IACD,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,KAAG,eAwHH,CAAC"}

package/dist/domain/scenario-manager.js

@@ -1,24 +1,25 @@
+import { noOpLogger } from "../adapters/index.js";
 import { ScenaristScenarioSchema } from "../schemas/index.js";
-class ScenarioNotFoundError extends Error {
-    constructor(scenarioId) {
-        super(`Scenario '${scenarioId}' not found. Did you forget to register it?`);
-        this.name = "ScenarioNotFoundError";
-    }
-}
-class DuplicateScenarioError extends Error {
-    constructor(scenarioId) {
-        super(`Scenario '${scenarioId}' is already registered. Each scenario must have a unique ID.`);
-        this.name = "DuplicateScenarioError";
-    }
-}
-class ScenarioValidationError extends Error {
-    validationErrors;
-    constructor(message, validationErrors) {
-        super(message);
-        this.validationErrors = validationErrors;
-        this.name = "ScenarioValidationError";
-    }
-}
+import { ScenaristError, ErrorCodes } from "../types/errors.js";
+import { LogCategories, LogEvents } from "./log-events.js";
+const createDuplicateScenarioError = (scenarioId) => {
+    return new ScenaristError(`Scenario '${scenarioId}' is already registered. Each scenario must have a unique ID.`, {
+        code: ErrorCodes.DUPLICATE_SCENARIO,
+        context: {
+            scenarioId,
+            hint: "Use a different scenario ID, or remove the existing scenario before registering a new one.",
+        },
+    });
+};
+const createScenarioValidationError = (scenarioId, validationErrors) => {
+    return new ScenaristError(`Invalid scenario definition for '${scenarioId}': ${validationErrors.join(", ")}`, {
+        code: ErrorCodes.VALIDATION_ERROR,
+        context: {
+            scenarioId,
+            hint: `Check your scenario definition. Validation errors: ${validationErrors.join("; ")}`,
+        },
+    });
+};
 /**
  * Factory function to create a ScenarioManager implementation.
  *
@@ -28,10 +29,11 @@ class ScenarioValidationError extends Error {
  * - Any registry implementation (in-memory, Redis, files, remote)
  * - Any store implementation (in-memory, Redis, database)
  * - Any state manager implementation (in-memory, Redis, database)
+ * - Any logger implementation (console, file, remote)
  * - Proper testing with mock dependencies
  * - True hexagonal architecture
  */
-export const createScenarioManager = ({ registry, store, stateManager, sequenceTracker, }) => {
+export const createScenarioManager = ({ registry, store, stateManager, sequenceTracker, logger = noOpLogger, }) => {
     return {
         registerScenario(definition) {
             // Validate scenario definition at trust boundary
@@ -39,7 +41,7 @@ export const createScenarioManager = ({ registry, store, stateManager, sequenceT
             if (!validationResult.success) {
                 const errorMessages = validationResult.error.issues.map((err) => `${err.path.join(".")}: ${err.message}`);
                 const scenarioId = definition?.id || "<unknown>";
-                throw new ScenarioValidationError(`Invalid scenario definition for '${scenarioId}': ${errorMessages.join(", ")}`, errorMessages);
+                throw createScenarioValidationError(scenarioId, errorMessages);
             }
             const existing = registry.get(definition.id);
             // Allow re-registering the exact same scenario object (idempotent)
@@ -48,16 +50,30 @@ export const createScenarioManager = ({ registry, store, stateManager, sequenceT
             }
             // Prevent registering a different scenario with the same ID
             if (existing) {
-                throw new DuplicateScenarioError(definition.id);
+                throw createDuplicateScenarioError(definition.id);
             }
             registry.register(definition);
+            logger.debug(LogCategories.SCENARIO, LogEvents.SCENARIO_REGISTERED, {}, {
+                scenarioId: definition.id,
+                mockCount: definition.mocks.length, // mocks is required by ScenaristScenarioSchema
+            });
         },
         switchScenario(testId, scenarioId) {
             const definition = registry.get(scenarioId);
             if (!definition) {
+                logger.error(LogCategories.SCENARIO, LogEvents.SCENARIO_NOT_FOUND, { testId }, {
+                    requestedScenarioId: scenarioId,
+                });
                 return {
                     success: false,
-                    error: new ScenarioNotFoundError(scenarioId),
+                    error: new ScenaristError(`Scenario '${scenarioId}' not found. Did you forget to register it?`, {
+                        code: ErrorCodes.SCENARIO_NOT_FOUND,
+                        context: {
+                            testId,
+                            scenarioId,
+                            hint: "Make sure to register the scenario before switching to it. Use manager.registerScenario(definition) first.",
+                        },
+                    }),
                 };
             }
             const activeScenario = {
@@ -72,6 +88,7 @@ export const createScenarioManager = ({ registry, store, stateManager, sequenceT
             if (stateManager) {
                 stateManager.reset(testId);
             }
+            logger.info(LogCategories.SCENARIO, LogEvents.SCENARIO_SWITCHED, { testId, scenarioId }, {});
             return { success: true, data: undefined };
         },
         getActiveScenario(testId) {
@@ -82,6 +99,7 @@ export const createScenarioManager = ({ registry, store, stateManager, sequenceT
         },
         clearScenario(testId) {
             store.delete(testId);
+            logger.debug(LogCategories.SCENARIO, LogEvents.SCENARIO_CLEARED, { testId }, {});
         },
         getScenarioById(id) {
             return registry.get(id);

package/dist/domain/state-condition-evaluator.js

@@ -32,6 +32,7 @@ const stateMatchesCondition = (state, when) => {
         if (!(key in state)) {
             return false;
         }
+        // eslint-disable-next-line security/detect-object-injection -- Key from Object.entries iteration
         const actualValue = state[key];
         if (!deepEquals(actualValue, expectedValue)) {
             return false;

package/dist/domain/template-replacement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template-replacement.d.ts","sourceRoot":"","sources":["../../src/domain/template-replacement.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,OAAO,EACd,cAAc,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACpC,OA8DF,CAAC"}
+{"version":3,"file":"template-replacement.d.ts","sourceRoot":"","sources":["../../src/domain/template-replacement.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,OAAO,EACd,cAAc,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACpC,OA+DF,CAAC"}

package/dist/domain/template-replacement.js

@@ -49,6 +49,7 @@ export const applyTemplates = (value, templateData) => {
     if (typeof value === "object" && value !== null) {
         const result = {};
         for (const [key, val] of Object.entries(value)) {
+            // eslint-disable-next-line security/detect-object-injection -- Key from Object.entries iteration
             result[key] = applyTemplates(val, normalizedData);
         }
         return result;
@@ -67,6 +68,7 @@ export const applyTemplates = (value, templateData) => {
  */
 const resolveTemplatePath = (templateData, prefix, path) => {
     // Get the root object (state or params)
+    // eslint-disable-next-line security/detect-object-injection -- Prefix validated as 'state' or 'params' by regex
     const root = templateData[prefix];
     // Guard: Prefix doesn't exist (e.g., no params provided)
     if (root === undefined || typeof root !== "object" || root === null) {
@@ -86,6 +88,7 @@ const resolveTemplatePath = (templateData, prefix, path) => {
         }
         // Traverse object
         const record = current;
+        // eslint-disable-next-line security/detect-object-injection -- Segment from split() iteration
         current = record[segment];
         // Guard: Return undefined if property doesn't exist
         if (current === undefined) {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export type * from "./types/index.js";
+export { ScenaristError, ErrorCodes } from "./types/errors.js";
 export * from "./schemas/index.js";
 export * from "./constants/index.js";
 export type * from "./ports/index.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,kBAAkB,CAAC;AAGtC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,sBAAsB,CAAC;AAGrC,mBAAmB,kBAAkB,CAAC;AAGtC,mBAAmB,sBAAsB,CAAC;AAG1C,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,kBAAkB,CAAC;AAGtC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/D,cAAc,oBAAoB,CAAC;AAGnC,cAAc,sBAAsB,CAAC;AAGrC,mBAAmB,kBAAkB,CAAC;AAGtC,mBAAmB,sBAAsB,CAAC;AAG1C,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,3 +1,5 @@
+// Error classes and constants (runtime values, not just types)
+export { ScenaristError, ErrorCodes } from "./types/errors.js";
 // Schemas (runtime validation)
 export * from "./schemas/index.js";
 // Constants

package/dist/ports/driven/logger.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Log levels ordered by verbosity (ascending).
+ * Each level includes all less verbose levels.
+ *
+ * - silent: No output (production default)
+ * - error: Critical failures preventing operation
+ * - warn: Potential issues that may cause problems
+ * - info: Operation flow and key events
+ * - debug: Detailed decision logic
+ * - trace: Request/response bodies, verbose details
+ */
+export type LogLevel = "silent" | "error" | "warn" | "info" | "debug" | "trace";
+/**
+ * Log categories for filtering specific areas of concern.
+ * Users can enable/disable categories independently.
+ */
+export type LogCategory = "lifecycle" | "scenario" | "matching" | "sequence" | "state" | "template" | "request";
+/**
+ * Base context included in all log events.
+ * Enables filtering and correlation by test ID.
+ */
+export type LogContext = {
+    readonly testId?: string;
+    readonly scenarioId?: string;
+    readonly requestUrl?: string;
+    readonly requestMethod?: string;
+};
+/**
+ * Structured log entry for capture and serialization.
+ */
+export type LogEntry = {
+    readonly level: Exclude<LogLevel, "silent">;
+    readonly category: LogCategory;
+    readonly message: string;
+    readonly context: LogContext;
+    readonly data?: Record<string, unknown>;
+    readonly timestamp: number;
+};
+/**
+ * Logger port for structured logging.
+ *
+ * This is a driven (secondary) port - domain logic calls out to it,
+ * implementations are injected via dependency injection.
+ *
+ * Implementations must handle:
+ * - Level filtering (only emit logs at or above configured level)
+ * - Category filtering (optionally filter by category)
+ * - Output formatting (console, JSON, custom)
+ *
+ * This port enables:
+ * - NoOpLogger: Zero overhead when disabled (production, silent mode)
+ * - ConsoleLogger: Human-readable or JSON output (development)
+ * - TestLogger: Capture logs for assertion in tests
+ * - Custom loggers: User-provided implementations (Winston, Pino, etc.)
+ *
+ * All methods return void - logging is fire-and-forget.
+ * Implementations should never throw.
+ */
+export interface Logger {
+    /**
+     * Log at error level - critical failures preventing operation.
+     *
+     * @param category - Area of concern for filtering
+     * @param message - Human-readable event description
+     * @param context - Request context for correlation (testId, scenarioId, etc.)
+     * @param data - Optional structured data for the event
+     */
+    error(category: LogCategory, message: string, context: LogContext, data?: Record<string, unknown>): void;
+    /**
+     * Log at warn level - potential issues that may cause problems.
+     *
+     * @param category - Area of concern for filtering
+     * @param message - Human-readable event description
+     * @param context - Request context for correlation
+     * @param data - Optional structured data for the event
+     */
+    warn(category: LogCategory, message: string, context: LogContext, data?: Record<string, unknown>): void;
+    /**
+     * Log at info level - operation flow and key events.
+     *
+     * @param category - Area of concern for filtering
+     * @param message - Human-readable event description
+     * @param context - Request context for correlation
+     * @param data - Optional structured data for the event
+     */
+    info(category: LogCategory, message: string, context: LogContext, data?: Record<string, unknown>): void;
+    /**
+     * Log at debug level - detailed decision logic.
+     *
+     * @param category - Area of concern for filtering
+     * @param message - Human-readable event description
+     * @param context - Request context for correlation
+     * @param data - Optional structured data for the event
+     */
+    debug(category: LogCategory, message: string, context: LogContext, data?: Record<string, unknown>): void;
+    /**
+     * Log at trace level - request/response bodies, verbose details.
+     *
+     * @param category - Area of concern for filtering
+     * @param message - Human-readable event description
+     * @param context - Request context for correlation
+     * @param data - Optional structured data for the event
+     */
+    trace(category: LogCategory, message: string, context: LogContext, data?: Record<string, unknown>): void;
+    /**
+     * Check if a specific level would be logged.
+     * Enables conditional expensive operations before logging.
+     *
+     * @example
+     * if (logger.isEnabled('trace')) {
+     *   logger.trace('request', 'body', ctx, { body: JSON.stringify(large) });
+     * }
+     *
+     * @param level - The log level to check
+     * @returns true if logging at this level is enabled
+     */
+    isEnabled(level: Exclude<LogLevel, "silent">): boolean;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/ports/driven/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/ports/driven/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEhF;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,UAAU,GACV,UAAU,GACV,UAAU,GACV,OAAO,GACP,UAAU,GACV,SAAS,CAAC;AAEd;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,MAAM;IACrB;;;;;;;OAOG;IACH,KAAK,CACH,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAAC;IAER;;;;;;;OAOG;IACH,IAAI,CACF,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAAC;IAER;;;;;;;OAOG;IACH,IAAI,CACF,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAAC;IAER;;;;;;;OAOG;IACH,KAAK,CACH,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAAC;IAER;;;;;;;OAOG;IACH,KAAK,CACH,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAAC;IAER;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC;CACxD"}

package/dist/ports/driven/logger.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/driven/response-selector.d.ts

@@ -1,6 +1,8 @@
 import type { ScenaristMockWithParams, ScenaristResponse, HttpRequestContext, ScenaristResult } from "../../types/index.js";
+import { ScenaristError } from "../../types/errors.js";
 /**
  * Error type for response selection failures.
+ * @deprecated Use ScenaristError with ErrorCodes.NO_MOCK_FOUND instead
  */
 export declare class ResponseSelectionError extends Error {
     constructor(message: string);
@@ -29,6 +31,6 @@ export interface ResponseSelector {
      * @param mocks - Candidate mocks with extracted params (already filtered by URL/method)
      * @returns ScenaristResult with selected ScenaristResponse or error if no match found
      */
-    selectResponse(testId: string, scenarioId: string, context: HttpRequestContext, mocks: ReadonlyArray<ScenaristMockWithParams>): ScenaristResult<ScenaristResponse, ResponseSelectionError>;
+    selectResponse(testId: string, scenarioId: string, context: HttpRequestContext, mocks: ReadonlyArray<ScenaristMockWithParams>): ScenaristResult<ScenaristResponse, ScenaristError>;
 }
 //# sourceMappingURL=response-selector.d.ts.map

package/dist/ports/driven/response-selector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response-selector.d.ts","sourceRoot":"","sources":["../../../src/ports/driven/response-selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,cAAc,CACZ,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,aAAa,CAAC,uBAAuB,CAAC,GAC5C,eAAe,CAAC,iBAAiB,EAAE,sBAAsB,CAAC,CAAC;CAC/D"}
+{"version":3,"file":"response-selector.d.ts","sourceRoot":"","sources":["../../../src/ports/driven/response-selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,cAAc,CACZ,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,aAAa,CAAC,uBAAuB,CAAC,GAC5C,eAAe,CAAC,iBAAiB,EAAE,cAAc,CAAC,CAAC;CACvD"}

package/dist/ports/driven/response-selector.js

@@ -1,5 +1,6 @@
 /**
  * Error type for response selection failures.
+ * @deprecated Use ScenaristError with ErrorCodes.NO_MOCK_FOUND instead
  */
 export class ResponseSelectionError extends Error {
     constructor(message) {

package/dist/ports/index.d.ts

@@ -5,4 +5,5 @@ export type { RequestContext } from "./driven/request-context.js";
 export type { ResponseSelector } from "./driven/response-selector.js";
 export type { SequenceTracker, SequencePosition, } from "./driven/sequence-tracker.js";
 export type { StateManager } from "./driven/state-manager.js";
+export type { Logger, LogLevel, LogCategory, LogContext, LogEntry, } from "./driven/logger.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/ports/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAGrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,YAAY,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,YAAY,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAGrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,YAAY,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,YAAY,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,YAAY,EACV,MAAM,EACN,QAAQ,EACR,WAAW,EACX,UAAU,EACV,QAAQ,GACT,MAAM,oBAAoB,CAAC"}