@winkjs/composer 0.0.2 → 0.4.0

package/src/core/semantics/schemas/enum-schema.js

@@ -0,0 +1,153 @@
+// core/semantics/schemas/enum-schema.js
+
+/**
+ * @fileoverview Enum Schema Definition
+ *
+ * Defines the validation schema for enum files used in semantics.
+ * Enums provide human-readable labels for column values of any type.
+ *
+ * Supported key types (as strings, no whitespace):
+ * - Numeric: "0", "1", "-1", "3.14" (for int64/float64 columns)
+ * - Boolean: "true", "false" (for bool columns like isWashing)
+ * - Text codes: "R", "G", "B", "idle" (for string columns)
+ *
+ * Example enum files:
+ *
+ * Numeric states:
+ * {
+ *     "name": "machineState",
+ *     "values": { "0": "Idle", "1": "Running", "2": "Error" }
+ * }
+ *
+ * Boolean states (e.g., for isWashing column):
+ * {
+ *     "name": "washingState",
+ *     "values": { "true": "Washing", "false": "Idle" }
+ * }
+ *
+ * Text codes:
+ * {
+ *     "name": "colorCodes",
+ *     "values": { "R": "Red", "G": "Green", "B": "Blue" }
+ * }
+ */
+
+import { validators } from '../../utils/validate/index.js';
+
+// ============================================================================
+// CUSTOM VALIDATORS
+// ============================================================================
+
+/**
+ * Validates a single enum key.
+ * Keys must be one of:
+ * - Numeric string: Valid finite number in canonical form ("0", "-1", "3.14")
+ * - Boolean string: Exactly "true" or "false"
+ * - Identifier: Valid JS identifier for text codes ("R", "idle", "state_1")
+ *
+ * @param {string} key - Single enum key to validate
+ * @returns {boolean} True if key is valid
+ */
+const validEnumKey = function ( key ) {
+    // Try numeric (most common for machine states)
+    if ( validators.numericString( key ) ) return true;
+    // Try boolean
+    if ( validators.booleanString( key ) ) return true;
+    // Try identifier (text codes)
+    return validators.identifier( key );
+}; // validEnumKey()
+
+/**
+ * Validates that enum values object has valid keys.
+ * Keys must be numeric strings, boolean strings, or valid identifiers.
+ *
+ * @param {Object} values - Enum values object
+ * @returns {boolean} True if all keys are valid
+ */
+const validEnumKeys = function ( values ) {
+    if ( typeof values !== 'object' || values === null ) {
+        return false;
+    }
+
+    const keys = Object.keys( values );
+    if ( keys.length === 0 ) {
+        return false;
+    }
+
+    for ( let i = 0; i < keys.length; i += 1 ) {
+        if ( !validEnumKey( keys[ i ] ) ) {
+            return false;
+        }
+    }
+
+    return true;
+};
+
+/**
+ * Validates that enum values are all non-empty strings.
+ * Values can contain spaces (e.g., "Error State", "In Progress").
+ *
+ * @param {Object} values - Enum values object
+ * @returns {boolean} True if all values are non-empty strings
+ */
+const validEnumValues = function ( values ) {
+    if ( typeof values !== 'object' || values === null ) {
+        return false;
+    }
+
+    const entries = Object.values( values );
+    for ( let i = 0; i < entries.length; i += 1 ) {
+        if ( !validators.nonEmptyString( entries[ i ] ) ) {
+            return false;
+        }
+    }
+
+    return true;
+};
+
+// ============================================================================
+// SCHEMA DEFINITION
+// ============================================================================
+
+/**
+ * Schema for enum JSON files.
+ *
+ * Uses validate module's `keyValidator` and `propertySchema` features
+ * for detailed error messages on individual key/value failures.
+ *
+ * @type {Object}
+ */
+const enumSchema = {
+    _propertyNames: [ 'name', 'description', 'values' ],
+    name: {
+        type: 'string',
+        required: true,
+        validator: validators.identifier,
+        error: 'Enum name must be a valid identifier'
+    },
+    description: {
+        type: 'string',
+        required: false,
+        default: ''
+    },
+    values: {
+        type: 'object',
+        required: true,
+        minProperties: 1,
+        keyValidator: validEnumKey,
+        propertySchema: {
+            type: 'string',
+            validator: validators.nonEmptyString,
+            error: 'Enum values must be non-empty strings'
+        },
+        error: 'Enum values must be an object with valid keys (numeric, boolean, or identifier) and non-empty string values'
+    }
+};
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+export { enumSchema, validEnumKey, validEnumKeys, validEnumValues };
+
+export default enumSchema;

package/src/core/semantics/schemas/index.js

@@ -0,0 +1,51 @@
+// core/semantics/schemas/index.js
+
+/**
+ * @fileoverview Semantics Schemas Index
+ *
+ * Exports all schema definitions and validators for semantics JSON files.
+ */
+
+// ============================================================================
+// ENUM SCHEMA
+// ============================================================================
+
+export {
+    enumSchema,
+    validEnumKey,
+    validEnumKeys,
+    validEnumValues
+} from './enum-schema.js';
+
+// ============================================================================
+// COLUMN SCHEMA
+// ============================================================================
+
+export {
+    columnSchema,
+    validPhysicalRange,
+    validOperational,
+    validSpecification,
+    validWhen,
+    validContext,
+    validContexts,
+    validColumnType,
+    validInterpretation,
+    validLimitsMutualExclusivity,
+    validLimitsHierarchy,
+    validContextLimitsHierarchy,
+    COLUMN_TYPES,
+    COLUMN_DEFAULTS
+} from './column-schema.js';
+
+// ============================================================================
+// ASSET CLASS SCHEMA
+// ============================================================================
+
+export {
+    assetClassSchema,
+    insightTypeSchema,
+    validColumnsStructure,
+    validInsightType,
+    validInsightTypes
+} from './asset-class-schema.js';

package/src/core/semantics/warnings.js

@@ -0,0 +1,141 @@
+// core/semantics/warnings.js
+
+/**
+ * @fileoverview Warning Infrastructure for Semantic Loading
+ *
+ * Provides warning accumulation and emission utilities for semantic validation.
+ * Warnings are advisory (don't fail validation) but highlight potential issues
+ * in semantic definitions.
+ *
+ * Follows the accumulation pattern used in flow/validate.js:
+ * - Collect all warnings during validation phases
+ * - Emit all accumulated warnings at the end
+ * - Support suppressWarnings option and custom onWarning handler
+ *
+ * @see flow/validate.js for the accumulation pattern
+ * @see core/storage-manager/questdb/persist-plan.js for onWarning callback pattern
+ */
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/**
+ * Standard warning prefix for semantic validation warnings.
+ * @type {string}
+ */
+const WARNING_PREFIX = 'WinkComposer/semantics';
+
+// ============================================================================
+// DEFAULT WARNING HANDLER
+// ============================================================================
+
+/**
+ * Default warning handler for semantic validation issues.
+ * Logs to console in WinkComposer format.
+ *
+ * @param {string} message - Warning message describing the issue
+ */
+const defaultOnWarning = function ( message ) {
+    console.warn( `${WARNING_PREFIX}: ${message}` );
+};
+
+// ============================================================================
+// WARNING COLLECTOR
+// ============================================================================
+
+/**
+ * Creates a warning collector for semantic validation.
+ *
+ * Follows the flow/validate.js accumulation pattern:
+ * - add() accumulates warnings to internal array
+ * - emit() outputs all accumulated warnings
+ * - getWarnings() returns copy of accumulated warnings
+ * - count() returns number of accumulated warnings
+ *
+ * @param {Object} options - Warning options
+ * @param {boolean} [options.suppressWarnings=false] - Suppress all warnings
+ * @param {Function} [options.onWarning] - Custom warning handler
+ * @returns {Object} Warning collector with add, emit, getWarnings, count methods
+ *
+ * @example
+ * // Default: logs to console on emit()
+ * const collector = createWarningCollector( {} );
+ * collector.add( 'Missing interpretation' );
+ * collector.add( 'Missing physicalRange' );
+ * collector.emit();  // Outputs both warnings
+ *
+ * // Suppress all warnings (useful for tests)
+ * const collector = createWarningCollector( { suppressWarnings: true } );
+ *
+ * // Custom handler
+ * const collector = createWarningCollector( {
+ *     onWarning: ( msg ) => logger.warn( msg )
+ * } );
+ */
+const createWarningCollector = function ( options = {} ) {
+    const { suppressWarnings = false, onWarning } = options;
+    const warnings = [];
+
+    /**
+     * Add a warning message to the collector.
+     *
+     * @param {string} message - Warning message
+     */
+    const add = function ( message ) {
+        warnings.push( message );
+    };
+
+    /**
+     * Emit all accumulated warnings.
+     * Does nothing if suppressWarnings is true.
+     */
+    const emit = function () {
+        if ( suppressWarnings ) {
+            return;
+        }
+
+        const handler = onWarning || defaultOnWarning;
+
+        for ( let i = 0; i < warnings.length; i += 1 ) {
+            handler( warnings[ i ] );
+        }
+    };
+
+    /**
+     * Get copy of accumulated warnings.
+     *
+     * @returns {Array<string>} Copy of warnings array
+     */
+    const getWarnings = function () {
+        return [ ...warnings ];
+    };
+
+    /**
+     * Get count of accumulated warnings.
+     *
+     * @returns {number} Number of accumulated warnings
+     */
+    const count = function () {
+        return warnings.length;
+    };
+
+    return {
+        add,
+        emit,
+        getWarnings,
+        count
+    };
+};
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+export {
+    WARNING_PREFIX,
+    defaultOnWarning,
+    createWarningCollector
+};
+
+export default createWarningCollector;

package/src/core/shutdown-manager/index.js

@@ -0,0 +1,289 @@
+// core/shutdown-manager/index.js
+
+/**
+ * @fileoverview Process-layer shutdown manager.
+ *
+ * Per ADR-018, the framework has three layers — adapter, flow, and
+ * process — each owning a distinct concern in the lifecycle. This file
+ * is the process layer.
+ *
+ * What this layer owns:
+ * - **OS signal handlers (SIGINT/SIGTERM)** as the SOLE owner. The flow
+ *   layer (`flow/run.js`) does NOT attach signal handlers; it auto-
+ *   registers each running flow's `handle` here, and this file routes
+ *   signals to `handle.shutdown()` for every registered handle.
+ * - **Top-level forced-shutdown timeout** that bounds the entire
+ *   `handle.shutdown()` drain. If a flow takes longer than
+ *   `ENV_VARS.shutdownForceTimeoutMs` (default 30000ms, matching
+ *   Kubernetes' `terminationGracePeriodSeconds`), this layer logs and
+ *   force-exits with code 1; otherwise exits with code 0 on graceful
+ *   completion. The ADR documents three nested timeouts, each on a
+ *   wider scope: the per-adapter `{ timeout }` (one adapter's drain),
+ *   the per-flow stage budget, and this process-level ceiling on the
+ *   whole exit.
+ *
+ * This layer owns NO storage. The storage-directory cleanup it used to
+ * run (an `fs.rm` of STORAGE_DIR at dev/test shutdown) was removed
+ * 2026-07-09: the emitter's LevelDB store — removed by ADR-021 — was
+ * the only thing that ever wrote there, and a recursive delete with no
+ * producer behind it is a hazard, not a feature.
+ *
+ * What this layer does NOT own:
+ * - Per-flow shutdown orchestration. Each registered handle's
+ *   `handle.shutdown()` runs its own ordered teardown
+ *   (source → emitters → storages) via `flow/run.js`'s closure.
+ *
+ * Idempotent attach. `attachHandlers()` is safe to call multiple times;
+ * the second call is a no-op via the internal `attached` flag. This
+ * closes the `MaxListenersExceededWarning` that earlier accumulated
+ * across test runs (each `flow.run()` had registered its own handlers
+ * without detach).
+ *
+ * Legacy path. The block below labelled "LEGACY PATH — scheduled for
+ * retirement" exists to serve the pre-DSL example flows
+ * (`cpd-run.js`, `rwm-csv-run.js` via their flow files) that wire
+ * emitters via `emitters.wire()` and rely on this manager's
+ * `emitters.shutdown()`. Modern `flow().run()` pipelines do not use
+ * that path — their registries are already drained by
+ * `handle.shutdown()` (called from the registered-handle iteration
+ * above), so the legacy block finds an empty registry and is a benign
+ * no-op for them. The sources half of this path (`wire-sources.js`,
+ * the OPC-UA example runners) was removed 2026-07-07 — see ADR-019.
+ * The emitters half retires when the legacy examples migrate to the
+ * modern flow API.
+ *
+ * @see ADR-018 (flow lifecycle and signal handling)
+ */
+
+import { emitters } from '../wiring/index.js';
+import { ENV_VARS } from '../env-vars.js';
+
+/**
+ * Factory that produces a fresh shutdown-manager instance with isolated
+ * internal state. The default export below calls this once for the
+ * production singleton; tests call it per spec to get an isolated
+ * instance and avoid state bleed across cases. Same shape as the
+ * earlier in-file IIFE; the factoring is purely for testability.
+ *
+ * @returns {{shutdown, attachHandlers, register}} the manager API
+ */
+const createShutdownManager = function () {
+    // ========================================================================
+    // PRIVATE STATE
+    // ========================================================================
+
+    // Guards against re-entry if a signal arrives mid-shutdown.
+    let isShuttingDown = false;
+
+    // `attachHandlers` idempotency flag. Multiple calls (e.g., from
+    // `flow().run()` auto-attach AND from a legacy example's explicit
+    // call) are no-ops after the first.
+    let attached = false;
+
+    // Map of registered flow handles. Keyed by the handle object itself,
+    // so registering the same handle twice is idempotent (a single entry)
+    // and a single unregister fully removes it. Map is purpose-built for
+    // this add/remove-over-time pattern; iteration via `.keys()` is
+    // clean and never deoptimises.
+    const handles = new Map();
+
+    // ========================================================================
+    // REGISTER: Add a flow handle to the shutdown roster
+    // ========================================================================
+    /**
+     * Register a flow `handle` so this manager calls `handle.shutdown()`
+     * on signal. `flow().run()` auto-registers its returned handle so
+     * the caller experience is unchanged from earlier versions.
+     *
+     * Idempotent: registering the same handle twice is a single entry,
+     * and a single unregister fully removes it. The Map is keyed by
+     * the handle object itself — no synthetic IDs needed.
+     *
+     * Returns an unregister function so a flow that has already shut
+     * down (via direct `handle.shutdown()` invocation by the caller)
+     * can detach itself, preventing this manager from re-invoking
+     * `handle.shutdown()` on a torn-down flow.
+     *
+     * @param {{shutdown: function}} handle - flow handle exposing shutdown
+     * @returns {function} unregister
+     */
+    const register = function ( handle ) {
+        handles.set( handle, true );
+        return function () {
+            handles.delete( handle );
+        };
+    };
+
+    // ========================================================================
+    // DRAIN HANDLES: Race per-flow shutdown against the forced timeout
+    // ========================================================================
+    /**
+     * Iterate every registered flow handle, calling `handle.shutdown()`
+     * on each in parallel via `Promise.allSettled`. Race the whole drain
+     * against `timeoutMs`; if the timeout wins, return false so the
+     * caller can log + force-exit with code 1.
+     *
+     * Returns true when no handles are registered (e.g., the legacy
+     * code path with no modern flows in process).
+     */
+    const drainHandles = async function ( timeoutMs ) {
+        if ( handles.size === 0 ) {
+            return true;
+        }
+
+        const drainAll = Promise.allSettled(
+            Array.from( handles.keys() ).map(
+                ( handle ) => Promise.resolve().then( () => handle.shutdown() )
+            )
+        );
+
+        // Distinct sentinel string so we can tell race winner apart from
+        // a Promise.allSettled result array.
+        const TIMED_OUT = '__SHUTDOWN_FORCE_TIMEOUT__';
+        let timerHandle;
+        const timeout = new Promise( ( resolve ) => {
+            timerHandle = setTimeout( () => resolve( TIMED_OUT ), timeoutMs );
+        } );
+
+        const winner = await Promise.race( [ drainAll, timeout ] );
+        // Cancel the loser. Without this, when drainAll wins the
+        // race, the unfired setTimeout still keeps the event loop
+        // alive until it fires (up to `timeoutMs` later) — a real
+        // tail-latency at end of test suites and in any process
+        // that runs the manager and then expects to exit cleanly.
+        // Same canonical pattern used by every source `stopFn`.
+        clearTimeout( timerHandle );
+        return winner !== TIMED_OUT;
+    };
+
+    // ========================================================================
+    // SHUTDOWN: Orchestrate the layered teardown
+    // ========================================================================
+    /**
+     * Run the full process-layer shutdown sequence. Re-entry is guarded
+     * via `isShuttingDown` (a second call returns immediately).
+     *
+     * Order:
+     * 1. Drain registered flow handles (modern path).
+     * 2. Run the legacy path block (clustered for retirement; warns once
+     *    when actually doing work).
+     * 3. Return graceful (true) / forced (false) — the caller decides
+     *    the exit code.
+     *
+     * @returns {Promise<boolean>} true on graceful completion, false on
+     *   forced timeout
+     */
+    const shutdown = async function () {
+        if ( isShuttingDown ) {
+            return true;
+        }
+        isShuttingDown = true;
+
+        const timestamp = new Date().toISOString();
+        console.log( `\n[${timestamp}] Shutdown initiated` );
+
+        // Phase 1 (modern path): drain registered flow handles, racing
+        // against the forced-shutdown timeout.
+        const graceful = await drainHandles( ENV_VARS.shutdownForceTimeoutMs );
+        if ( !graceful ) {
+            console.warn(
+                `  ⚠ Forced shutdown — flow drain exceeded ${ENV_VARS.shutdownForceTimeoutMs}ms; ` +
+                'some adapters may not have completed cleanly'
+            );
+        }
+
+        try {
+            // ================================================================
+            // LEGACY PATH — scheduled for retirement
+            // ================================================================
+            //
+            // The emitters.shutdown() call below serves the pre-DSL
+            // example flows (cpd-run.js, rwm-csv-run.js via their flow
+            // files) that wire emitters manually via emitters.wire()
+            // instead of using the modern flow().run() API.
+            //
+            // Modern flow().run() pipelines drain everything via
+            // handle.shutdown() (called from the registered-handle
+            // iteration above); by the time control reaches this block,
+            // the wire-emitters / wire-storages registries are already
+            // empty for those flows — the call finds nothing to do
+            // (benign no-op).
+            //
+            // The sources half of this path (wire-sources.js and the
+            // OPC-UA example runners) was removed 2026-07-07 (ADR-019).
+            // This remainder retires when the legacy examples migrate
+            // to the modern flow API.
+            // ================================================================
+
+            const emitterResults = await emitters.shutdown();
+            const failedEmitters = emitterResults.filter( ( r ) => r.status === 'rejected' );
+            if ( emitterResults.length > 0 ) {
+                if ( failedEmitters.length > 0 ) {
+                    console.warn( `  ⚠ Warning: ${failedEmitters.length} legacy emitter(s) failed to shutdown cleanly` );
+                } else {
+                    console.log( '  ✓ Legacy message queues flushed' );
+                }
+            }
+
+            // ================================================================
+            // END LEGACY PATH
+            // ================================================================
+
+            console.log( `[${new Date().toISOString()}] Shutdown complete\n` );
+
+            return graceful;
+
+        } catch ( error ) {
+            console.error( '✗ Shutdown error:', error );
+            process.exitCode = 1;
+            return false;
+        }
+    }; // shutdown()
+
+    // ========================================================================
+    // ATTACH HANDLERS: Wire up SIGINT/SIGTERM (idempotent)
+    // ========================================================================
+    /**
+     * Register process-level SIGINT and SIGTERM handlers. Idempotent —
+     * subsequent calls are no-ops via the internal `attached` flag.
+     * Both `flow().run()` (auto-attach) and legacy examples' explicit
+     * calls converge here, so handlers are registered exactly once per
+     * process regardless of caller.
+     *
+     * On signal: runs `shutdown()`, then `process.exit(0)` on graceful
+     * or `process.exit(1)` on forced timeout.
+     */
+    const attachHandlers = function () {
+        if ( attached ) {
+            return;
+        }
+        attached = true;
+
+        const signalHandler = async function ( signalName ) {
+            console.log( `\ncomposer: Received ${signalName}` );
+            const graceful = await shutdown();
+
+            /* c8 ignore next 2 -- fundamentally untestable: invoking the signal handler from a test would call process.exit and kill the test runner. The graceful/forced exit-code mapping is verified by the shutdown() return-value tests above. */
+            // eslint-disable-next-line no-process-exit
+            process.exit( graceful ? 0 : 1 );
+        };
+
+        process.on( 'SIGINT', () => signalHandler( 'SIGINT (Ctrl-C)' ) );
+        process.on( 'SIGTERM', () => signalHandler( 'SIGTERM' ) );
+    }; // attachHandlers()
+
+    // ========================================================================
+    // PUBLIC API
+    // ========================================================================
+    return {
+        shutdown,
+        attachHandlers,
+        register
+    };
+}; // createShutdownManager()
+
+// Production singleton — one instance per process, exported as default.
+const shutdownManager = createShutdownManager();
+
+export default shutdownManager;
+export { createShutdownManager };