@lumenflow/core 1.0.0

package/dist/usecases/get-suggestions.usecase.d.ts

@@ -0,0 +1,100 @@
+/**
+ * GetSuggestions Use Case
+ *
+ * Applies orchestration rules to generate recommendations for next actions.
+ * Combines WU progress analysis with code path detection.
+ *
+ * @module get-suggestions.usecase
+ * @see {@link ../orchestration-rules.ts} - Rule functions
+ * @see {@link ../ports/metrics-collector.port.ts} - Port interface
+ */
+import type { IMetricsCollector } from '../ports/metrics-collector.port.js';
+import type { Suggestion } from '../domain/orchestration.types.js';
+/**
+ * Bottleneck scores mapping WU IDs to their impact scores.
+ * Impact score = number of downstream WUs blocked by this WU.
+ */
+export type BottleneckScores = Record<string, number>;
+/**
+ * Options for the GetSuggestions use case.
+ */
+export interface GetSuggestionsOptions {
+    /**
+     * Code paths to analyse for mandatory agent triggers.
+     * When provided, detects which agents should be invoked.
+     */
+    codePaths?: string[];
+    /**
+     * Bottleneck impact scores from flow:bottlenecks analysis.
+     * When provided, suggestions for high-impact WUs are ranked higher
+     * within the same priority level.
+     *
+     * @see flow-bottlenecks.mjs for score calculation
+     */
+    bottleneckScores?: BottleneckScores;
+}
+/**
+ * Use case for generating orchestration suggestions.
+ *
+ * Combines two sources of suggestions:
+ * 1. WU progress analysis - suggests agents based on current state
+ * 2. Code path analysis - detects mandatory agents from file patterns
+ *
+ * @example
+ * const collector = new FileSystemMetricsCollector(basePath);
+ * const useCase = new GetSuggestionsUseCase(collector);
+ *
+ * // Get suggestions based on current WU state
+ * const suggestions = await useCase.execute();
+ *
+ * // Get suggestions including code path analysis
+ * const suggestionsWithPaths = await useCase.execute({
+ *   codePaths: ['supabase/migrations/001.sql', 'src/prompts/system.ts']
+ * });
+ */
+export declare class GetSuggestionsUseCase {
+    private readonly metricsCollector;
+    constructor(metricsCollector: IMetricsCollector);
+    /**
+     * Execute the use case to generate suggestions.
+     *
+     * @param options - Optional configuration including code paths and bottleneck scores
+     * @returns Promise resolving to prioritised suggestions
+     * @throws Error if collector methods fail
+     */
+    execute(options?: GetSuggestionsOptions): Promise<Suggestion[]>;
+    /**
+     * Enrich suggestions with impact score information in reason field.
+     *
+     * @param suggestions - Suggestions to enrich
+     * @param bottleneckScores - WU ID to impact score mapping
+     * @returns Enriched suggestions
+     */
+    private enrichWithImpactScores;
+    /**
+     * Extract WU ID from a suggestion command.
+     *
+     * @param command - Command string containing WU ID
+     * @returns WU ID or null if not found
+     */
+    private extractWuIdFromCommand;
+    /**
+     * Sort suggestions by priority, then by impact score within same priority.
+     *
+     * @param suggestions - Suggestions to sort
+     * @param bottleneckScores - WU ID to impact score mapping
+     * @returns Sorted suggestions
+     */
+    private sortSuggestions;
+    /**
+     * Generate suggestions for mandatory agents detected from code paths.
+     *
+     * Avoids duplicating suggestions that already exist from WU progress analysis.
+     *
+     * @param mandatoryAgents - Agents detected from code paths
+     * @param existingSuggestions - Suggestions already generated
+     * @param wuId - WU ID for the suggestion
+     * @returns Additional suggestions for mandatory agents
+     */
+    private generateMandatoryAgentSuggestions;
+}

package/dist/usecases/get-suggestions.usecase.js

@@ -0,0 +1,153 @@
+/**
+ * GetSuggestions Use Case
+ *
+ * Applies orchestration rules to generate recommendations for next actions.
+ * Combines WU progress analysis with code path detection.
+ *
+ * @module get-suggestions.usecase
+ * @see {@link ../orchestration-rules.ts} - Rule functions
+ * @see {@link ../ports/metrics-collector.port.ts} - Port interface
+ */
+import { detectMandatoryAgents, generateSuggestions } from '../orchestration-rules.js';
+/**
+ * Use case for generating orchestration suggestions.
+ *
+ * Combines two sources of suggestions:
+ * 1. WU progress analysis - suggests agents based on current state
+ * 2. Code path analysis - detects mandatory agents from file patterns
+ *
+ * @example
+ * const collector = new FileSystemMetricsCollector(basePath);
+ * const useCase = new GetSuggestionsUseCase(collector);
+ *
+ * // Get suggestions based on current WU state
+ * const suggestions = await useCase.execute();
+ *
+ * // Get suggestions including code path analysis
+ * const suggestionsWithPaths = await useCase.execute({
+ *   codePaths: ['supabase/migrations/001.sql', 'src/prompts/system.ts']
+ * });
+ */
+export class GetSuggestionsUseCase {
+    metricsCollector;
+    constructor(metricsCollector) {
+        this.metricsCollector = metricsCollector;
+    }
+    /**
+     * Execute the use case to generate suggestions.
+     *
+     * @param options - Optional configuration including code paths and bottleneck scores
+     * @returns Promise resolving to prioritised suggestions
+     * @throws Error if collector methods fail
+     */
+    async execute(options = {}) {
+        const { codePaths = [], bottleneckScores = {} } = options;
+        const [wuProgress, agentMetrics] = await Promise.all([
+            this.metricsCollector.getWUProgress(),
+            this.metricsCollector.getAgentMetrics(),
+        ]);
+        // Generate suggestions from WU progress
+        let progressSuggestions = generateSuggestions(wuProgress, agentMetrics);
+        // Enrich suggestions with impact scores if available (WU-1596)
+        progressSuggestions = this.enrichWithImpactScores(progressSuggestions, bottleneckScores);
+        // Detect mandatory agents from code paths
+        const mandatoryAgents = detectMandatoryAgents(codePaths);
+        // Generate additional suggestions for detected mandatory agents
+        const pathSuggestions = this.generateMandatoryAgentSuggestions(mandatoryAgents, progressSuggestions, wuProgress.length > 0 ? wuProgress[0].wuId : 'current');
+        // Combine and deduplicate suggestions
+        const allSuggestions = [...progressSuggestions, ...pathSuggestions];
+        // Sort by priority (high > medium > low), then by impact score (descending)
+        return this.sortSuggestions(allSuggestions, bottleneckScores);
+    }
+    /**
+     * Enrich suggestions with impact score information in reason field.
+     *
+     * @param suggestions - Suggestions to enrich
+     * @param bottleneckScores - WU ID to impact score mapping
+     * @returns Enriched suggestions
+     */
+    enrichWithImpactScores(suggestions, bottleneckScores) {
+        if (Object.keys(bottleneckScores).length === 0) {
+            return suggestions;
+        }
+        return suggestions.map((suggestion) => {
+            const wuId = this.extractWuIdFromCommand(suggestion.command);
+            if (!wuId) {
+                return suggestion;
+            }
+            const impactScore = bottleneckScores[wuId];
+            if (impactScore === undefined || impactScore === 0) {
+                return suggestion;
+            }
+            // Enrich reason with impact score
+            return {
+                ...suggestion,
+                reason: `${suggestion.reason} (blocks ${impactScore} downstream WU${impactScore === 1 ? '' : 's'})`,
+            };
+        });
+    }
+    /**
+     * Extract WU ID from a suggestion command.
+     *
+     * @param command - Command string containing WU ID
+     * @returns WU ID or null if not found
+     */
+    extractWuIdFromCommand(command) {
+        if (!command) {
+            return null;
+        }
+        const match = command.match(/WU-\d+/);
+        return match ? match[0] : null;
+    }
+    /**
+     * Sort suggestions by priority, then by impact score within same priority.
+     *
+     * @param suggestions - Suggestions to sort
+     * @param bottleneckScores - WU ID to impact score mapping
+     * @returns Sorted suggestions
+     */
+    sortSuggestions(suggestions, bottleneckScores) {
+        const priorityOrder = { high: 0, medium: 1, low: 2 };
+        return suggestions.sort((a, b) => {
+            // First sort by priority
+            const priorityDiff = priorityOrder[a.priority] - priorityOrder[b.priority];
+            if (priorityDiff !== 0) {
+                return priorityDiff;
+            }
+            // Within same priority, sort by impact score (higher score first)
+            const aWuId = this.extractWuIdFromCommand(a.command);
+            const bWuId = this.extractWuIdFromCommand(b.command);
+            const aScore = aWuId ? (bottleneckScores[aWuId] ?? 0) : 0;
+            const bScore = bWuId ? (bottleneckScores[bWuId] ?? 0) : 0;
+            return bScore - aScore; // Descending order (higher score first)
+        });
+    }
+    /**
+     * Generate suggestions for mandatory agents detected from code paths.
+     *
+     * Avoids duplicating suggestions that already exist from WU progress analysis.
+     *
+     * @param mandatoryAgents - Agents detected from code paths
+     * @param existingSuggestions - Suggestions already generated
+     * @param wuId - WU ID for the suggestion
+     * @returns Additional suggestions for mandatory agents
+     */
+    generateMandatoryAgentSuggestions(mandatoryAgents, existingSuggestions, wuId) {
+        const suggestions = [];
+        let nextId = existingSuggestions.length + 1;
+        for (const agentName of mandatoryAgents) {
+            // Check if suggestion already exists for this agent
+            const alreadyExists = existingSuggestions.some((s) => s.action.toLowerCase().includes(agentName));
+            if (!alreadyExists) {
+                suggestions.push({
+                    id: `sug-${(nextId++).toString().padStart(3, '0')}`,
+                    priority: 'high',
+                    action: `Run ${agentName}`,
+                    reason: `Code paths indicate ${agentName} is required`,
+                    command: `pnpm orchestrate:run ${agentName} --wu ${wuId}`,
+                });
+            }
+        }
+        return suggestions;
+    }
+}

package/dist/user-normalizer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * WU-1333: User normalizer utilities
+ *
+ * Provides email normalization and domain inference for WU ownership.
+ * Converts plain usernames (e.g., "tom") to email format (e.g., "tom@hellm.ai")
+ * using domain from git config or .lumenflow.config.yaml.
+ */
+/**
+ * Default domain fallback when git config and lumenflow config unavailable
+ */
+export declare const DEFAULT_DOMAIN = "patientpath.co.uk";
+/**
+ * Check if a value is a valid email address (simple check)
+ *
+ * @param {string|null|undefined} value - Value to check
+ * @returns {boolean} True if value is a valid email
+ */
+export declare function isValidEmail(value: any): boolean;
+/**
+ * Infer the default email domain from available sources
+ *
+ * Priority:
+ * 1. Git config user.email domain
+ * 2. .lumenflow.config.yaml OWNER_EMAIL domain
+ * 3. DEFAULT_DOMAIN constant
+ *
+ * @param {string} [cwd] - Working directory for config lookup
+ * @returns {Promise<string>} Inferred domain (never null/undefined)
+ */
+export declare function inferDefaultDomain(cwd?: string): Promise<any>;
+/**
+ * Normalize a username or email to full email format
+ *
+ * If value is already a valid email, returns it unchanged (with normalization).
+ * If value is a plain username, appends the default domain.
+ *
+ * @param {string|null|undefined} value - Username or email
+ * @param {string} [domain] - Optional domain override
+ * @returns {Promise<string>} Normalized email address, or empty string for null/undefined
+ */
+export declare function normalizeToEmail(value: any, domain: any): Promise<string>;

package/dist/user-normalizer.js

@@ -0,0 +1,141 @@
+/**
+ * WU-1333: User normalizer utilities
+ *
+ * Provides email normalization and domain inference for WU ownership.
+ * Converts plain usernames (e.g., "tom") to email format (e.g., "tom@hellm.ai")
+ * using domain from git config or .lumenflow.config.yaml.
+ */
+import { readFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getGitForCwd } from './git-adapter.js';
+/**
+ * Default domain fallback when git config and lumenflow config unavailable
+ */
+export const DEFAULT_DOMAIN = 'patientpath.co.uk';
+/**
+ * Minimum length for a valid email local part
+ */
+const MIN_LOCAL_PART_LENGTH = 1;
+/**
+ * Check if a value is a valid email address (simple check)
+ *
+ * @param {string|null|undefined} value - Value to check
+ * @returns {boolean} True if value is a valid email
+ */
+export function isValidEmail(value) {
+    if (!value || typeof value !== 'string') {
+        return false;
+    }
+    const str = value.trim();
+    // Simple email validation: must have @ with content before and after
+    const atIndex = str.indexOf('@');
+    return atIndex > 0 && atIndex < str.length - 1;
+}
+/**
+ * Extract domain from an email address
+ *
+ * @param {string} email - Email address
+ * @returns {string|null} Domain part or null if invalid
+ */
+function extractDomain(email) {
+    if (!isValidEmail(email)) {
+        return null;
+    }
+    const atIndex = email.indexOf('@');
+    return email.slice(atIndex + 1);
+}
+/**
+ * Try to get domain from git config user.email
+ *
+ * @returns {Promise<string|null>} Domain from git config or null
+ */
+async function getDomainFromGitConfig() {
+    try {
+        const git = getGitForCwd();
+        const email = await git.getConfigValue('user.email');
+        return extractDomain(email?.trim() || '');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Try to get domain from .lumenflow.config.yaml OWNER_EMAIL
+ *
+ * @param {string} [cwd] - Working directory to search from
+ * @returns {Promise<string|null>} Domain from config or null
+ */
+async function getDomainFromLumenflowConfig(cwd = process.cwd()) {
+    const configPath = join(cwd, '.lumenflow.config.yaml');
+    try {
+        await access(configPath);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const content = await readFile(configPath, { encoding: 'utf-8' });
+        // Simple pattern match for OWNER_EMAIL (avoid full YAML parse for performance)
+        // Looking for: OWNER_EMAIL: "email@domain"
+        const match = content.match(/OWNER_EMAIL:\s*["']?([^"'\s]+)["']?/i);
+        if (match && match[1]) {
+            return extractDomain(match[1]);
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Infer the default email domain from available sources
+ *
+ * Priority:
+ * 1. Git config user.email domain
+ * 2. .lumenflow.config.yaml OWNER_EMAIL domain
+ * 3. DEFAULT_DOMAIN constant
+ *
+ * @param {string} [cwd] - Working directory for config lookup
+ * @returns {Promise<string>} Inferred domain (never null/undefined)
+ */
+export async function inferDefaultDomain(cwd = process.cwd()) {
+    // Try git config first
+    const gitDomain = await getDomainFromGitConfig();
+    if (gitDomain) {
+        return gitDomain;
+    }
+    // Try lumenflow config
+    const configDomain = await getDomainFromLumenflowConfig(cwd);
+    if (configDomain) {
+        return configDomain;
+    }
+    // Fallback to default
+    return DEFAULT_DOMAIN;
+}
+/**
+ * Normalize a username or email to full email format
+ *
+ * If value is already a valid email, returns it unchanged (with normalization).
+ * If value is a plain username, appends the default domain.
+ *
+ * @param {string|null|undefined} value - Username or email
+ * @param {string} [domain] - Optional domain override
+ * @returns {Promise<string>} Normalized email address, or empty string for null/undefined
+ */
+export async function normalizeToEmail(value, domain) {
+    // Handle null/undefined/empty
+    if (!value) {
+        return '';
+    }
+    const str = String(value).trim().toLowerCase();
+    if (str.length < MIN_LOCAL_PART_LENGTH) {
+        return '';
+    }
+    // Already a valid email - return as-is (normalized)
+    if (isValidEmail(str)) {
+        return str;
+    }
+    // Plain username - append domain
+    const effectiveDomain = domain || (await inferDefaultDomain());
+    return `${str}@${effectiveDomain}`;
+}

package/dist/validators/phi-constants.d.ts

@@ -0,0 +1,97 @@
+/**
+ * PHI (Protected Health Information) Detection Constants
+ *
+ * Centralized constants for PHI scanner to detect NHS numbers and UK postcodes
+ * in medical context. Uses library-first approach with nhs-number-validator
+ * and postcode packages for validation.
+ *
+ * Part of WU-1404: PHI Scanner Integration
+ *
+ * @see {@link https://digital.nhs.uk/data-and-information/data-tools-and-services/data-services/nhs-number} NHS Number format
+ * @see {@link https://github.com/ideal-postcodes/postcode} Postcode validation library
+ */
+/**
+ * PHI type identifiers for categorizing detected PHI
+ */
+export declare const PHI_TYPES: {
+    /** NHS number (10 digits with Modulus 11 checksum) */
+    NHS_NUMBER: string;
+    /** UK postcode detected in medical context */
+    POSTCODE_MEDICAL_CONTEXT: string;
+};
+/**
+ * Medical context keywords for postcode detection
+ *
+ * Postcodes are only flagged as PHI when they appear within proximity
+ * of these medical context keywords. This reduces false positives from
+ * legitimate postcode usage (e.g., hospital addresses in documentation).
+ */
+export declare const MEDICAL_CONTEXT_KEYWORDS: string[];
+/**
+ * Context window size for medical keyword proximity detection
+ *
+ * When a postcode is found, we search this many characters before
+ * and after the postcode for medical context keywords.
+ */
+export declare const MEDICAL_CONTEXT_WINDOW_SIZE = 100;
+/**
+ * Known test NHS numbers that should not trigger PHI detection
+ *
+ * These are official test NHS numbers or commonly used in test fixtures.
+ * Source: NHS Digital test data guidelines
+ */
+export declare const TEST_NHS_NUMBERS: string[];
+/**
+ * Prefix for NHS test numbers (numbers starting with 999 are reserved for testing)
+ */
+export declare const NHS_TEST_PREFIX = "999";
+/**
+ * Known test postcodes that should not trigger PHI detection
+ *
+ * These are commonly used in examples, documentation, and test fixtures.
+ */
+export declare const TEST_POSTCODES: string[];
+/**
+ * Content markers that indicate test/example data
+ *
+ * Content containing these markers should not trigger PHI detection.
+ */
+export declare const TEST_DATA_MARKERS: string[];
+/**
+ * File path patterns that should be excluded from PHI scanning
+ *
+ * These patterns indicate test/fixture files where PHI patterns
+ * may legitimately appear for testing purposes.
+ */
+export declare const EXCLUDED_PATH_PATTERNS: RegExp[];
+/**
+ * Candidate extraction pattern for NHS numbers
+ *
+ * Extracts 10-digit numeric sequences that could be NHS numbers.
+ * The library validates these with Modulus 11 checksum.
+ *
+ * NHS numbers may appear with or without spaces:
+ * - 1234567890
+ * - 123 456 7890
+ * - 123-456-7890
+ */
+export declare const NHS_CANDIDATE_PATTERN: RegExp;
+/**
+ * PHI detection result structure
+ *
+ * @typedef {Object} PHIMatch
+ * @property {string} type - PHI type from PHI_TYPES
+ * @property {string} value - The matched value (may be masked)
+ * @property {number} startIndex - Start position in content
+ * @property {number} endIndex - End position in content
+ * @property {string} [context] - Surrounding context (optional)
+ * @property {string} [medicalKeyword] - Medical keyword that triggered postcode detection (optional)
+ */
+/**
+ * Scan result structure
+ *
+ * @typedef {Object} PHIScanResult
+ * @property {boolean} hasPHI - Whether PHI was detected
+ * @property {PHIMatch[]} matches - Array of PHI matches found
+ * @property {string[]} warnings - Non-blocking warnings (e.g., test data detected)
+ */

package/dist/validators/phi-constants.js

@@ -0,0 +1,152 @@
+/**
+ * PHI (Protected Health Information) Detection Constants
+ *
+ * Centralized constants for PHI scanner to detect NHS numbers and UK postcodes
+ * in medical context. Uses library-first approach with nhs-number-validator
+ * and postcode packages for validation.
+ *
+ * Part of WU-1404: PHI Scanner Integration
+ *
+ * @see {@link https://digital.nhs.uk/data-and-information/data-tools-and-services/data-services/nhs-number} NHS Number format
+ * @see {@link https://github.com/ideal-postcodes/postcode} Postcode validation library
+ */
+/**
+ * PHI type identifiers for categorizing detected PHI
+ */
+export const PHI_TYPES = {
+    /** NHS number (10 digits with Modulus 11 checksum) */
+    NHS_NUMBER: 'NHS_NUMBER',
+    /** UK postcode detected in medical context */
+    POSTCODE_MEDICAL_CONTEXT: 'POSTCODE_MEDICAL_CONTEXT',
+};
+/**
+ * Medical context keywords for postcode detection
+ *
+ * Postcodes are only flagged as PHI when they appear within proximity
+ * of these medical context keywords. This reduces false positives from
+ * legitimate postcode usage (e.g., hospital addresses in documentation).
+ */
+export const MEDICAL_CONTEXT_KEYWORDS = [
+    'patient',
+    'medical record',
+    'gp surgery',
+    'nhs',
+    'hospital',
+    'clinic',
+    'registered address',
+    'home address',
+    'next of kin',
+    'emergency contact',
+    'admission',
+    'discharge',
+    'referral',
+    'diagnosis',
+    'treatment',
+];
+/**
+ * Context window size for medical keyword proximity detection
+ *
+ * When a postcode is found, we search this many characters before
+ * and after the postcode for medical context keywords.
+ */
+export const MEDICAL_CONTEXT_WINDOW_SIZE = 100;
+/**
+ * Known test NHS numbers that should not trigger PHI detection
+ *
+ * These are official test NHS numbers or commonly used in test fixtures.
+ * Source: NHS Digital test data guidelines
+ */
+export const TEST_NHS_NUMBERS = [
+    '4505577104', // Common test NHS number
+    '9999999999', // Range reserved for testing (999 prefix)
+    '9990000001', // Test range
+    '9990000002',
+    '9990000003',
+];
+/**
+ * Prefix for NHS test numbers (numbers starting with 999 are reserved for testing)
+ */
+export const NHS_TEST_PREFIX = '999';
+/**
+ * Known test postcodes that should not trigger PHI detection
+ *
+ * These are commonly used in examples, documentation, and test fixtures.
+ */
+export const TEST_POSTCODES = [
+    'SW1A 1AA', // Buckingham Palace - often used in examples
+    'SW1A1AA', // Same without space
+    'EC1A 1BB', // Commonly used test postcode
+    'EC1A1BB',
+    'W1A 1AA', // BBC Broadcasting House - frequently in docs
+    'W1A1AA',
+];
+/**
+ * Content markers that indicate test/example data
+ *
+ * Content containing these markers should not trigger PHI detection.
+ */
+export const TEST_DATA_MARKERS = [
+    '[TEST]',
+    '[EXAMPLE]',
+    '[PLACEHOLDER]',
+    '[SAMPLE]',
+    '// test data',
+    '/* test data */',
+    '# test data',
+    'test-data',
+    'testData',
+    'TEST_DATA',
+    'example-data',
+    'sample-data',
+    'mock-data',
+    'fixture',
+];
+/**
+ * File path patterns that should be excluded from PHI scanning
+ *
+ * These patterns indicate test/fixture files where PHI patterns
+ * may legitimately appear for testing purposes.
+ */
+export const EXCLUDED_PATH_PATTERNS = [
+    /\/__tests__\//i,
+    /\/test\//i,
+    /\/tests\//i,
+    /\.test\./i,
+    /\.spec\./i,
+    /\/fixtures?\//i,
+    /\/mocks?\//i,
+    /\/__mocks__\//i,
+    /\/VCR\/cassettes\//i,
+    /\.md$/i, // Documentation files have different risk profile
+];
+/**
+ * Candidate extraction pattern for NHS numbers
+ *
+ * Extracts 10-digit numeric sequences that could be NHS numbers.
+ * The library validates these with Modulus 11 checksum.
+ *
+ * NHS numbers may appear with or without spaces:
+ * - 1234567890
+ * - 123 456 7890
+ * - 123-456-7890
+ */
+export const NHS_CANDIDATE_PATTERN = /\b(\d{3}[\s-]?\d{3}[\s-]?\d{4})\b/g;
+/**
+ * PHI detection result structure
+ *
+ * @typedef {Object} PHIMatch
+ * @property {string} type - PHI type from PHI_TYPES
+ * @property {string} value - The matched value (may be masked)
+ * @property {number} startIndex - Start position in content
+ * @property {number} endIndex - End position in content
+ * @property {string} [context] - Surrounding context (optional)
+ * @property {string} [medicalKeyword] - Medical keyword that triggered postcode detection (optional)
+ */
+/**
+ * Scan result structure
+ *
+ * @typedef {Object} PHIScanResult
+ * @property {boolean} hasPHI - Whether PHI was detected
+ * @property {PHIMatch[]} matches - Array of PHI matches found
+ * @property {string[]} warnings - Non-blocking warnings (e.g., test data detected)
+ */