@ti-engine/web-framework 1.25.0 → 1.26.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 This document will contain the list of changes made to the framework. The format is based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
 
+## Version 1.26.0
+
+* feat(config-management): report stored documents that no longer satisfy their registered schema.
+  `ConfigService.listSchemaViolations()` returns one entry per registered document whose **stored** value fails its
+  schema, and `ConfigRegistry.validateSchema( configKey, value )` exposes the schema half of validation on its own.
+  Nothing validated a stored value on the way out before this: the store hands back whatever it holds and a consumer
+  freezes it into its config exports, so a release that tightens a schema — adding a required top-level key, say —
+  leaves any deployment seeded before the change serving a document that can no longer be saved. The failure used to
+  surface much later, as an admin edit rejected for a key the admin never touched, in a screen unrelated to the
+  change. Schema-only by design: a semantic validator may need a `ValidatorContext` the caller has no reason to
+  build, and several are about an *edit* rather than the document standing alone. Read-only by design too —
+  reconciling a stale document is the drift panel's job, under audit; an automatic repair here would write config
+  outside the change-set machinery. A document that has never been stored is not a violation.
+* refactor(config-management): `ConfigRegistry.validate()` now delegates its schema step to `validateSchema()`, so
+  the two can never disagree about what is structurally admissible.
+
+## Version 1.25.1
+
+* fix(ti-framework): resolve a label key whose own name contains a literal dot. `getLabel` split the key on every
+  dot and descended one object level per segment, so a group storing flat dotted keys — because the key IS a dotted
+  path in the consuming application's domain, e.g. audit-log field labels keyed by employee field path
+  (`"personal.workSite"`, `"career.roleFamily"`) — could never be reached. The miss was silent: the caller's
+  fallback rendered instead, which is why competence's Employee Management audit tab had shown every changed field
+  as its raw field path for as long as those labels have existed. Resolution now tries the longest literal key that
+  matches at each level, shortens a segment at a time, and backtracks when a matched branch turns out not to hold
+  the rest of the key — so a purely nested catalogue resolves exactly as before, a literal dotted key wins over the
+  nested path of the same name, and a genuinely absent key still returns the fallback
+* test(ti-framework): cover `tiApplication.getLabel` against the store the browser actually gets. `ti-framework.js`
+  is a plain browser script with no module exports, so `test/helpers/ti-framework-sandbox.js` loads it in a Node
+  sandbox, fires `alpine:init` and hands back the registered stores — exercising the shipped resolver rather than
+  asserting against its source text, which is what let this defect sit unnoticed
+
 ## Version 1.25.0
 
 * feat(config-management): surface a `driftTracked` flag on the `getDrift` / `listDrift` payloads, defaulting to

package/bin/static/scripts/ti-framework.js

@@ -800,27 +800,69 @@ const configureApplication = () => {
     const tiToolbox = Alpine.store( "tiToolbox" );
 
     /**
-     * Used to extract a label from a nested labels object.
+     * Marker returned by {@link resolveLabel} when a key is not present in the labels object. A dedicated sentinel
+     * rather than `undefined` so that backtracking can never be confused by a stored value.
+     *
+     * @constant
+     * @private
+     */
+    const LABEL_NOT_FOUND = Object.freeze( {} );
+
+    /**
+     * Resolves a label key against a labels object, trying the longest literal key that matches at each level and
+     * shortening on a miss.
+     * <br/>
+     * A labels catalogue is not always purely nested: a group may store flat keys that themselves contain a dot,
+     * because the key IS a dotted path in the application's own domain — competence keys its audit-log field labels
+     * by employee field path ("personal.workSite", "career.roleFamily"). Descending exactly one object level per dot
+     * can never reach those, and the miss is silent: the caller's fallback renders instead. So each level tries the
+     * whole remaining key first, shortens a segment at a time, and backtracks whenever a matched branch turns out
+     * not to hold the rest of the key.
      *
      * @method
      * @param {Object} labels
      * @param {String[]} keys
-     * @param {String} fallback
-     * @returns {String}
+     * @returns {String|Object} The resolved value, or {@link LABEL_NOT_FOUND}.
      * @private
      */
-    const extractLabel = ( labels, keys, fallback ) => {
-        let key = keys.shift();
-        if ( labels && typeof labels === "object" && key && Object.prototype.hasOwnProperty.call( labels, key ) ) {
+    const resolveLabel = ( labels, keys ) => {
+        if ( !labels || typeof labels !== "object" || keys.length === 0 ) {
+            return LABEL_NOT_FOUND;
+        }
+        for ( let length = keys.length; length > 0; length-- ) {
+            const key = keys.slice( 0, length ).join( "." );
+            if ( !Object.prototype.hasOwnProperty.call( labels, key ) ) {
+                continue;
+            }
             const value = labels[ key ];
+            const remainder = keys.slice( length );
             if ( typeof value === "string" ) {
-                return keys.length === 0 ? value : fallback;
-            }
-            if ( value && typeof value === "object" ) {
-                return extractLabel( value, keys, fallback );
+                if ( remainder.length === 0 ) {
+                    return value;
+                }
+            } else if ( value && typeof value === "object" ) {
+                const resolved = resolveLabel( value, remainder );
+                if ( resolved !== LABEL_NOT_FOUND ) {
+                    return resolved;
+                }
             }
         }
-        return fallback;
+        return LABEL_NOT_FOUND;
+    };
+
+    /**
+     * Used to extract a label from a nested labels object.
+     *
+     * @method
+     * @param {Object} labels
+     * @param {String[]} keys
+     * @param {String} fallback
+     * @returns {String}
+     * @private
+     */
+    const extractLabel = ( labels, keys, fallback ) => {
+        const resolved = resolveLabel( labels, keys );
+        return ( typeof resolved === "string" ) ? resolved : fallback;
     };
 
     /**

package/components/config-registry.js

@@ -197,13 +197,7 @@ class ConfigRegistry {
             return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "unknown-config", configKey: configKey } ) );
         }
 
-        const errors = [];
-        const validateSchema = this.#schemaValidator( registration );
-        if ( !validateSchema( value ) ) {
-            for ( const error of ( validateSchema.errors || [] ) ) {
-                errors.push( { path: error.dataPath || instancePathToDataPath( error.instancePath ), message: error.message || "schema violation", code: "schema", params: error.params } );
-            }
-        }
+        const errors = this.validateSchema( configKey, value ).errors.slice();
 
         return Promise.all( registration.validators.map( ( validator ) => {
             return Promise.resolve( validator( value, context ) ).then( ( issues ) => ( Array.isArray( issues ) ? issues : [] ) );
@@ -217,6 +211,38 @@ class ConfigRegistry {
         } );
     }
 
+    /**
+     * Validates a value against a document's registered schema **only**, skipping the semantic validators.
+     * <br/>
+     * Separate from {@link ConfigRegistry#validate} because the two answer different questions. A semantic validator
+     * may need a {@link ValidatorContext} the caller has no reason to build, and several of them are about an edit
+     * (did the version move? does this removal orphan a reference?) rather than about the document standing alone.
+     * A caller that just wants to know whether a value is structurally admissible — a boot-time check on what the
+     * store already holds, say — needs this half and not the other.
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} value
+     * @returns {{valid: boolean, errors: ConfigValidationIssue[]}}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
+     * @public
+     */
+    validateSchema( configKey, value ) {
+        const registration = this.#registrations.get( configKey );
+        if ( !registration ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "unknown-config", configKey: configKey } );
+        }
+
+        const errors = [];
+        const validateSchema = this.#schemaValidator( registration );
+        if ( !validateSchema( value ) ) {
+            for ( const error of ( validateSchema.errors || [] ) ) {
+                errors.push( { path: error.dataPath || instancePathToDataPath( error.instancePath ), message: error.message || "schema violation", code: "schema", params: error.params } );
+            }
+        }
+        return { valid: errors.length === 0, errors: errors };
+    }
+
     /* Private interface */
 
     /**

package/components/config-service.js

@@ -21,6 +21,7 @@ const configDrift = require( "#config-drift" );
 /** @import ConfigChangeNotifier from "#config-change-notifier" */
 /** @import ConfigRegistry from "#config-registry" */
 /** @import ConfigStore from "#config-store" */
+/** @import { ConfigValidationIssue } from "#config-registry" */
 
 /**
  * Orchestrates validated, versioned configuration edits on top of {@link ConfigStore} and {@link ConfigRegistry}.
@@ -374,6 +375,37 @@ class ConfigService {
         } ) );
     }
 
+    /**
+     * Reports every registered document whose **stored** value no longer satisfies its registered schema.
+     * <br/>
+     * Nothing validates a stored value on the way out: the store hands back whatever it holds, and a consumer
+     * freezes it into its config exports. That is fine until a release tightens a schema — adds a required
+     * top-level key, say — at which point a deployment seeded before the change keeps serving a document that
+     * cannot be saved any more. The failure surfaces much later, as an admin edit rejected for a key the admin
+     * never touched, in a screen that has nothing to do with the change.
+     * <br/>
+     * This answers that question at a moment when it is cheap to act on. It is deliberately schema-only (see
+     * {@link ConfigRegistry#validateSchema}) and deliberately read-only: reconciling a stale document is what the
+     * drift panel is for, and an automatic repair here would write config outside the audited change-set machinery.
+     * A document that has never been stored is not a violation and is omitted.
+     *
+     * @method
+     * @returns {Promise<Array<{configKey: string, errors: ConfigValidationIssue[]}>>} Empty when every stored
+     *          document validates.
+     * @public
+     */
+    listSchemaViolations() {
+        return Promise.all( this.#registry.list().map( ( configKey ) => {
+            return this.#store.getCurrent( configKey ).then( ( current ) => {
+                if ( !current ) {
+                    return null;
+                }
+                const result = this.#registry.validateSchema( configKey, current.value );
+                return result.valid ? null : { configKey: configKey, errors: result.errors };
+            } );
+        } ) ).then( ( results ) => results.filter( Boolean ) );
+    }
+
     /**
      * Applies the registered file defaults for the given documents, as a single validated change-set.
      * <br/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/web-framework",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "description": "A web-framework based on the ti-engine. It provides a customizable ready-to-use web-server microservice and a set of tools for creating web applications. NOTICE: This is still a work in progress and the full architecture, design, and functionality are not available!",
   "keywords": [
     "ti-engine",

package/types/components/config-registry.d.ts

@@ -142,6 +142,26 @@ declare class ConfigRegistry {
         valid: boolean;
         errors: ConfigValidationIssue[];
     }>;
+    /**
+     * Validates a value against a document's registered schema **only**, skipping the semantic validators.
+     * <br/>
+     * Separate from {@link ConfigRegistry#validate} because the two answer different questions. A semantic validator
+     * may need a {@link ValidatorContext} the caller has no reason to build, and several of them are about an edit
+     * (did the version move? does this removal orphan a reference?) rather than about the document standing alone.
+     * A caller that just wants to know whether a value is structurally admissible — a boot-time check on what the
+     * store already holds, say — needs this half and not the other.
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} value
+     * @returns {{valid: boolean, errors: ConfigValidationIssue[]}}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
+     * @public
+     */
+    validateSchema(configKey: string, value: Object): {
+        valid: boolean;
+        errors: ConfigValidationIssue[];
+    };
 }
 declare namespace ConfigRegistry {
     export { instance };

package/types/components/config-service.d.ts

@@ -2,9 +2,11 @@ export = ConfigService;
 import type ConfigChangeNotifier from "#config-change-notifier";
 import type ConfigRegistry from "#config-registry";
 import type ConfigStore from "#config-store";
+import type { ConfigValidationIssue } from "#config-registry";
 /** @import ConfigChangeNotifier from "#config-change-notifier" */
 /** @import ConfigRegistry from "#config-registry" */
 /** @import ConfigStore from "#config-store" */
+/** @import { ConfigValidationIssue } from "#config-registry" */
 /**
  * Orchestrates validated, versioned configuration edits on top of {@link ConfigStore} and {@link ConfigRegistry}.
  *
@@ -223,6 +225,29 @@ declare class ConfigService {
      * @public
      */
     listDrift(): Promise<Array<Object>>;
+    /**
+     * Reports every registered document whose **stored** value no longer satisfies its registered schema.
+     * <br/>
+     * Nothing validates a stored value on the way out: the store hands back whatever it holds, and a consumer
+     * freezes it into its config exports. That is fine until a release tightens a schema — adds a required
+     * top-level key, say — at which point a deployment seeded before the change keeps serving a document that
+     * cannot be saved any more. The failure surfaces much later, as an admin edit rejected for a key the admin
+     * never touched, in a screen that has nothing to do with the change.
+     * <br/>
+     * This answers that question at a moment when it is cheap to act on. It is deliberately schema-only (see
+     * {@link ConfigRegistry#validateSchema}) and deliberately read-only: reconciling a stale document is what the
+     * drift panel is for, and an automatic repair here would write config outside the audited change-set machinery.
+     * A document that has never been stored is not a violation and is omitted.
+     *
+     * @method
+     * @returns {Promise<Array<{configKey: string, errors: ConfigValidationIssue[]}>>} Empty when every stored
+     *          document validates.
+     * @public
+     */
+    listSchemaViolations(): Promise<Array<{
+        configKey: string;
+        errors: ConfigValidationIssue[];
+    }>>;
     /**
      * Applies the registered file defaults for the given documents, as a single validated change-set.
      * <br/>