@matter/model 0.13.0-alpha.0-20250304-d4a7592a4 → 0.13.0-alpha.0-20250311-3eb0af5f2

package/src/logic/cluster-variance/IllegalFeatureCombinations.ts

@@ -73,7 +73,95 @@ function addFeatureNode(
     illegal: IllegalFeatureCombinations,
     choices: Choices,
 ) {
-    function unsupported() {
+    switch (node.type) {
+        case Conformance.Special.Desc:
+        case Conformance.Special.Empty:
+        case Conformance.Flag.Optional:
+        case Conformance.Flag.Provisional:
+            break;
+
+        case Conformance.Flag.Mandatory:
+            illegal.push({ [feature.name]: false });
+            break;
+
+        case Conformance.Flag.Deprecated:
+        case Conformance.Flag.Disallowed:
+            illegal.push({ [feature.name]: true });
+            break;
+
+        case Conformance.Special.Group:
+            node.param.forEach(ast => addFeatureNode(feature, ast, illegal, choices));
+            break;
+
+        case Conformance.Special.Choice:
+            if (node.param.num > 1) {
+                unsupported();
+            }
+            const choice = choices[node.param.name];
+            if (choice) {
+                choice.features.push(feature.name);
+            } else {
+                choices[node.param.name] = choices[node.param.name] = {
+                    exclusive: !node.param.orMore,
+                    features: [feature.name],
+                };
+            }
+            break;
+
+        case Conformance.Special.Name:
+            illegal.push({ [node.param]: true, [feature.name]: false });
+            break;
+
+        case Conformance.Special.OptionalIf:
+            switch (node.param.type) {
+                case Conformance.AND:
+                case Conformance.Special.Name:
+                    addDependencyRequirement(feature.name, node.param);
+                    break;
+
+                case Conformance.OR: {
+                    const flags = FeatureBitmap({ [feature.name]: true });
+                    addExclusivityRequirement(flags, node.param);
+                    illegal.push(flags);
+                    break;
+                }
+
+                case Conformance.Operator.NOT: {
+                    illegal.push({ [feature.name]: true, [extractName(node.param.param)]: true });
+                    break;
+                }
+
+                default:
+                    unsupported();
+            }
+            break;
+
+        case Conformance.Operator.AND: {
+            // Handles simple conjunctions like "FOO & BAR" and "(STA|PAU|FA|CON) & !SFR"
+            const lhsFeatures = extractDisjunctFeatures(node.param.lhs);
+            const rhsFeature = extractFeatureFlag(node.param.rhs);
+
+            for (const lhsFeature in lhsFeatures) {
+                illegal.push({
+                    feature: false,
+                    [lhsFeature]: lhsFeatures[lhsFeature],
+                    ...rhsFeature,
+                });
+            }
+            break;
+        }
+
+        case Conformance.Operator.OR: {
+            const features = extractDisjunctFeatures(node);
+            illegal.push(Object.fromEntries(Object.entries(features).map((k, v) => [k, !v])));
+            break;
+        }
+
+        default:
+            unsupported();
+    }
+
+    function unsupported(): never {
         throw new InternalError(`New rule required to support ${feature.path} conformance "${feature.conformance}"`);
     }
 
@@ -85,7 +173,6 @@ function addFeatureNode(
             return node.param;
         }
         unsupported();
-        return ""; // Unreachable
     }
 
     /**
@@ -134,6 +221,21 @@ function addFeatureNode(
                 addDependencyRequirement(feature, node.param.rhs);
                 break;
 
+            case Conformance.OR:
+                if (
+                    node.param.lhs.type === Conformance.Special.Name &&
+                    node.param.rhs.type === Conformance.Special.Name
+                ) {
+                    illegal.push({ [feature]: true, [node.param.lhs.param]: false, [node.param.rhs.param]: false });
+                }
+                break;
+
+            case Conformance.Operator.NOT:
+                if (node.param.type === Conformance.Special.Name) {
+                    illegal.push({ [feature]: true, [node.param.param]: true });
+                }
+                break;
+
             default:
                 unsupported();
         }
@@ -169,83 +271,4 @@ function addFeatureNode(
 
         return result;
     }
-
-    switch (node.type) {
-        case Conformance.Special.Desc:
-        case Conformance.Special.Empty:
-        case Conformance.Flag.Optional:
-        case Conformance.Flag.Provisional:
-            break;
-
-        case Conformance.Flag.Deprecated:
-        case Conformance.Flag.Disallowed:
-            illegal.push({ [feature.name]: true });
-            break;
-
-        case Conformance.Special.Group:
-            node.param.forEach(ast => addFeatureNode(feature, ast, illegal, choices));
-            break;
-
-        case Conformance.Special.Choice:
-            if (node.param.num > 1) {
-                unsupported();
-            }
-            const choice = choices[node.param.name];
-            if (choice) {
-                choice.features.push(feature.name);
-            } else {
-                choices[node.param.name] = choices[node.param.name] = {
-                    exclusive: !node.param.orMore,
-                    features: [feature.name],
-                };
-            }
-            break;
-
-        case Conformance.Special.Name:
-            illegal.push({ [node.param]: true, [feature.name]: false });
-            break;
-
-        case Conformance.Special.OptionalIf:
-            switch (node.param.type) {
-                case Conformance.AND:
-                case Conformance.Special.Name:
-                    addDependencyRequirement(feature.name, node.param);
-                    break;
-
-                case Conformance.OR: {
-                    const flags = FeatureBitmap({ [feature.name]: true });
-                    addExclusivityRequirement(flags, node.param);
-                    illegal.push(flags);
-                    break;
-                }
-
-                case Conformance.Operator.NOT: {
-                    illegal.push({ [feature.name]: true, [extractName(node.param.param)]: true });
-                    break;
-                }
-
-                default:
-                    unsupported();
-            }
-            break;
-
-        case Conformance.Operator.AND: {
-            // Handles simple conjunctions like "FOO & BAR" and "(STA|PAU|FA|CON) & !SFR"
-            const lhsFeatures = extractDisjunctFeatures(node.param.lhs);
-            const rhsFeature = extractFeatureFlag(node.param.rhs);
-
-            for (const lhsFeature in lhsFeatures) {
-                illegal.push({
-                    feature: false,
-                    [lhsFeature]: lhsFeatures[lhsFeature],
-                    ...rhsFeature,
-                });
-            }
-            break;
-        }
-
-        default:
-            unsupported();
-            break;
-    }
 }

package/src/logic/cluster-variance/InferredComponents.ts

@@ -105,6 +105,14 @@ const VarianceMatchers: VarianceMatcher[] = [
         },
     },
 
+    // [fieldName] (optional, unconditional).  Ignores field reference which can only be enforced at runtime
+    {
+        pattern: pattern("[", FIELD, "]"),
+        processor(add) {
+            add(false);
+        },
+    },
+
     // fieldName > num (optional, unconditional).  Ignores field expression
     {
         pattern: pattern(FIELD, " > ", "\\d+"),
@@ -179,6 +187,14 @@ const VarianceMatchers: VarianceMatcher[] = [
         },
     },
 
+    // FOO & !BAR
+    {
+        pattern: pattern(FEATURE, AND, NOT, FEATURE),
+        processor(add, match) {
+            add(false, { allOf: [match[0]], not: match[1] });
+        },
+    },
+
     // !FOO & BAR
     {
         pattern: pattern(NOT, FEATURE, AND, FEATURE),
@@ -244,6 +260,16 @@ const VarianceMatchers: VarianceMatcher[] = [
             add(true);
         },
     },
+
+    // Handles a bunch of super ugly conformances in deprecated occupancy sensing attributes.  They all effectively
+    // become optional if certain features are enabled.  We use the presence of the "HoldTime" field to reliably detect
+    // these and ensure these rules aren't too greedy
+    {
+        pattern: pattern(".*HoldTime", AND, "\\(?", FEATURE, ".*"),
+        processor(add, match) {
+            add(true, { allOf: [match[0]] });
+        },
+    },
 ];
 
 function addElement(components: InferredComponents, element: ValueModel) {
@@ -267,7 +293,7 @@ function addElement(components: InferredComponents, element: ValueModel) {
 
     if (text === "D") {
         text = "O";
-    } else if (text === "P") {
+    } else if (text === "M, D" || text === "P") {
         text = "M";
     }
 

package/src/logic/definition-validation/ValueValidator.ts

@@ -29,16 +29,16 @@ export class ValueValidator<T extends ValueModel> extends ModelValidator<T> {
             if (name.match(/^[A-Z0-9_$]+$/)) {
                 // Feature lookup
                 const cluster = this.model.owner(ClusterModel);
-                return !!cluster?.features.find(f => f.name === name);
+                return cluster?.features.find(f => f.name === name);
             }
 
             // Field lookup
             for (let model = this.model.parent; model; model = model.parent) {
-                if (model.member(name) !== undefined) {
-                    return true;
+                const member = model.member(name);
+                if (member) {
+                    return member;
                 }
             }
-            return false;
         });
 
         this.validateAspect("constraint");
@@ -259,9 +259,19 @@ export class ValueValidator<T extends ValueModel> extends ModelValidator<T> {
         // Special "reference" object referencing another field by name
         if (typeof def === "object" && FieldValue.is(def, FieldValue.reference)) {
             const reference = (def as FieldValue.Reference).name;
-            const other = this.model.parent?.member(reference);
+
+            // See if the referenced name is a sibling
+            const parent = this.model.parent;
+            let other = parent?.member(reference);
+
             if (!other) {
-                this.error("MEMBER_UNKNOWN", `Default value references unknown property ${reference}`);
+                // We also allow names to reference cluster attributes
+                const cluster = parent?.owner(ClusterModel);
+                other = cluster?.member(reference);
+
+                if (other === undefined) {
+                    this.error("MEMBER_UNKNOWN", `Default value references unknown property ${reference}`);
+                }
             }
             return true;
         }

package/src/models/AttributeModel.ts

@@ -44,10 +44,6 @@ export class AttributeModel extends PropertyModel<AttributeElement> implements A
         super(definition);
     }
 
-    static {
-        Model.types[AttributeElement.Tag] = this;
-    }
-
     static isGlobal(model: Model) {
         return model instanceof AttributeModel && GLOBAL_IDS.has(model.id);
     }
@@ -58,3 +54,5 @@ export class AttributeModel extends PropertyModel<AttributeElement> implements A
 
     static Tag = AttributeElement.Tag;
 }
+
+AttributeModel.register();

package/src/models/ClusterModel.ts

@@ -171,12 +171,10 @@ export class ClusterModel extends ScopeModel<ClusterElement> implements ClusterE
     }
 
     static Tag = ClusterElement.Tag;
-
-    static {
-        Model.types[this.Tag] = this;
-    }
 }
 
+ClusterModel.register();
+
 export namespace ClusterModel {
     export type Definition = ClusterElement.Properties & { supportedFeatures?: FeatureSet.Definition };
 

package/src/models/CommandModel.ts

@@ -7,7 +7,6 @@
 import { Mei } from "../common/Mei.js";
 import { CommandElement } from "../elements/index.js";
 import { ModelTraversal } from "../logic/ModelTraversal.js";
-import { Model } from "./Model.js";
 import { ValueModel } from "./ValueModel.js";
 
 export class CommandModel extends ValueModel<CommandElement> implements CommandElement {
@@ -57,9 +56,7 @@ export class CommandModel extends ValueModel<CommandElement> implements CommandE
         return this.direction;
     }
 
-    static {
-        Model.types[CommandElement.Tag] = this;
-    }
-
     static Tag = CommandElement.Tag;
 }
+
+CommandModel.register();

package/src/models/DatatypeModel.ts

@@ -6,7 +6,6 @@
 
 import { Metatype } from "../common/index.js";
 import { DatatypeElement } from "../elements/DatatypeElement.js";
-import { Model } from "./Model.js";
 import { ValueModel } from "./ValueModel.js";
 
 export class DatatypeModel extends ValueModel<DatatypeElement> implements DatatypeElement {
@@ -23,7 +22,7 @@ export class DatatypeModel extends ValueModel<DatatypeElement> implements Dataty
         return false;
     }
 
-    static {
-        Model.types[DatatypeElement.Tag] = this;
-    }
+    static Tag = DatatypeElement.Tag;
 }
+
+DatatypeModel.register();

package/src/models/DeviceTypeModel.ts

@@ -35,11 +35,11 @@ export class DeviceTypeModel extends Model<DeviceTypeElement> implements DeviceT
         );
     }
 
-    static {
-        Model.types[DeviceTypeElement.Tag] = this;
-    }
+    static Tag = DeviceTypeElement.Tag;
 }
 
+DeviceTypeModel.register();
+
 export namespace DeviceTypeModel {
     export type Child = RequirementModel | FieldModel;
 }

package/src/models/EndpointModel.ts

@@ -25,7 +25,7 @@ export class EndpointModel extends Model<EndpointModel> implements EndpointEleme
         return this.children;
     }
 
-    static {
-        Model.types[EndpointElement.Tag] = this;
-    }
+    static Tag = EndpointElement.Tag;
 }
+
+EndpointModel.register();

package/src/models/EventModel.ts

@@ -6,7 +6,6 @@
 
 import { Mei } from "../common/Mei.js";
 import { EventElement } from "../elements/index.js";
-import { Model } from "./Model.js";
 import { ValueModel } from "./ValueModel.js";
 
 export class EventModel extends ValueModel<EventElement> implements EventElement {
@@ -26,9 +25,7 @@ export class EventModel extends ValueModel<EventElement> implements EventElement
         return { ...super.requiredFields, id: this.id };
     }
 
-    static {
-        Model.types[EventElement.Tag] = this;
-    }
-
     static Tag = EventElement.Tag;
 }
+
+EventModel.register();

package/src/models/FabricModel.ts

@@ -25,7 +25,7 @@ export class FabricModel extends Model<FabricElement> implements FabricElement {
         return this.children;
     }
 
-    static {
-        Model.types[FabricElement.Tag] = this;
-    }
+    static Tag = FabricElement.Tag;
 }
+
+FabricModel.register();

package/src/models/FieldModel.ts

@@ -7,7 +7,6 @@
 import { Mei } from "../common/Mei.js";
 import { Metatype } from "../common/index.js";
 import { FieldElement } from "../elements/index.js";
-import { Model } from "./Model.js";
 import { PropertyModel } from "./PropertyModel.js";
 import { ValueModel } from "./ValueModel.js";
 
@@ -45,7 +44,7 @@ export class FieldModel<T extends FieldElement = FieldElement> extends PropertyM
         return super.key;
     }
 
-    static {
-        Model.types[FieldElement.Tag] = this;
-    }
+    static Tag = FieldElement.Tag;
 }
+
+FieldModel.register();

package/src/models/MatterModel.ts

@@ -106,11 +106,11 @@ export class MatterModel extends ScopeModel<MatterElement> implements MatterElem
         return this.children.filter(child => child.isSeed).map(child => child.clone());
     }
 
-    static {
-        Model.types[MatterElement.Tag] = this;
-    }
+    static Tag = MatterElement.Tag;
 }
 
+MatterModel.register();
+
 export namespace MatterModel {
     export type Child =
         | ClusterModel

package/src/models/Model.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { camelize, decamelize, ImplementationError, InternalError } from "#general";
+import { camelize, decamelize, ImplementationError } from "#general";
 import { DefinitionError, ElementTag, Metatype, Specification } from "../common/index.js";
 import { AnyElement, BaseElement } from "../elements/index.js";
 import { ModelTraversal } from "../logic/ModelTraversal.js";
@@ -12,6 +12,11 @@ import { Children } from "./Children.js";
 
 const inspect = Symbol.for("nodejs.util.inspect.custom");
 
+/**
+ * Thrown when model API is used incorrectly.
+ */
+export class StructuralModelError extends ImplementationError {}
+
 /**
  * A "model" is a class that implements runtime functionality associated with the corresponding element type.
  *
@@ -210,9 +215,25 @@ export abstract class Model<T extends BaseElement = BaseElement> {
     }
 
     /**
-     * Factory support.  Populated by derivatives upon definition.
+     * Factory support.
      */
-    static types = {} as { [type: string]: new (definition: any) => Model };
+    static types = {} as { [type: string]: Model.ConcreteType };
+
+    /**
+     * Add a new model implementation.
+     */
+    static register(this: Model.ConcreteType) {
+        Model.types[this.Tag] = this;
+    }
+
+    /**
+     * All possible tags for registered models of this type.
+     */
+    static get tags() {
+        return Object.values(Model.types)
+            .filter(type => type instanceof this)
+            .map(type => type.Tag);
+    }
 
     /**
      * In some circumstances the base type can be inferred.  This inference happens here.
@@ -289,12 +310,12 @@ export abstract class Model<T extends BaseElement = BaseElement> {
      */
     static create(definition: AnyElement) {
         if (typeof definition !== "object") {
-            throw new InternalError(`Model definition must be object, not ${typeof definition}`);
+            throw new StructuralModelError(`Model definition must be object, not ${typeof definition}`);
         }
         const t = definition["tag"];
         const constructor = Model.types[t];
         if (!constructor) {
-            throw new InternalError(`Unknown element tag "${t}"`);
+            throw new StructuralModelError(`Unknown element tag "${t}"`);
         }
         return new constructor(definition);
     }
@@ -405,6 +426,35 @@ export abstract class Model<T extends BaseElement = BaseElement> {
         return new ModelTraversal().findMember(this, key, allowedTags);
     }
 
+    /**
+     * Access a member that must exist.
+     */
+    require<T extends Model>(type: Model.ConcreteType<T>, key: Children.Selector): T {
+        let member = this.member(key, [type.Tag]);
+        if (member === undefined && typeof key === "string") {
+            member = this.member(camelize(key, true));
+        }
+        if (member !== undefined) {
+            return member as T;
+        }
+
+        let what;
+        switch (typeof key) {
+            case "string":
+                what = `"${key}"`;
+                break;
+
+            case "number":
+                what = `#${key}"`;
+                break;
+
+            default:
+                what = `selected`;
+        }
+
+        throw new StructuralModelError(`No ${type.Tag} ${what} for ${this.tag} ${this.name}`);
+    }
+
     /**
      * Does this model derive from another?
      */
@@ -456,7 +506,7 @@ export abstract class Model<T extends BaseElement = BaseElement> {
 
     constructor(definition: Model<T> | BaseElement.Properties<T>, ...children: Model.Definition<Model>[]) {
         if (typeof definition !== "object") {
-            throw new ImplementationError(`Model definition must be an object, not ${typeof definition}`);
+            throw new StructuralModelError(`Model definition must be an object, not ${typeof definition}`);
         }
 
         const isClone = definition instanceof Model;
@@ -602,6 +652,11 @@ export namespace Model {
      */
     export type Type<T extends Model = Model> = abstract new (...args: any) => T;
 
+    /**
+     * A model constructor for a specific element type.
+     */
+    export type ConcreteType<T extends Model = Model> = (new (definition: any) => T) & { Tag: ElementTag };
+
     export type LookupPredicate<T extends Model> = Type<T> | { type: Type<T>; test: (model: Model) => boolean };
 
     export type PropertyValidation = {

package/src/models/NodeModel.ts

@@ -25,7 +25,7 @@ export class NodeModel extends Model<NodeElement> implements NodeElement {
         return this.children;
     }
 
-    static {
-        Model.types[NodeElement.Tag] = this;
-    }
+    static Tag = NodeElement.Tag;
 }
+
+NodeModel.register();

package/src/models/RequirementModel.ts

@@ -61,10 +61,6 @@ export class RequirementModel extends Model<RequirementElement> implements Requi
         Aspects.setAspect(this, QUALITY, Quality, definition);
     }
 
-    static {
-        Model.types[RequirementElement.Tag] = this;
-    }
-
     get requirements() {
         return this.all(RequirementModel);
     }
@@ -86,8 +82,12 @@ export class RequirementModel extends Model<RequirementElement> implements Requi
     get isMandatory() {
         return this.conformance.isMandatory;
     }
+
+    static Tag = RequirementElement.Tag;
 }
 
+RequirementModel.register();
+
 export namespace RequirementModel {
     export type Child = RequirementModel | FieldModel;
 }

package/src/models/SemanticNamespaceModel.ts

@@ -26,7 +26,7 @@ export class SemanticNamespaceModel extends Model<SemanticNamespaceElement> impl
         return this.children;
     }
 
-    static {
-        Model.types[SemanticNamespaceElement.Tag] = this;
-    }
+    static Tag = SemanticNamespaceElement.Tag;
 }
+
+SemanticNamespaceModel.register();

package/src/models/SemanticTagModel.ts

@@ -20,7 +20,7 @@ export class SemanticTagModel extends Model<SemanticTagElement> implements Seman
         super.children = children;
     }
 
-    static {
-        Model.types[SemanticTagElement.Tag] = this;
-    }
+    static Tag = SemanticTagElement.Tag;
 }
+
+SemanticTagModel.register();

package/src/standard/elements/AcceptedCommandList.ts

@@ -22,8 +22,12 @@ export const AcceptedCommandList = Attribute(
             "This attribute shall be a list of the command IDs for client generated commands that are supported " +
             "and processed by the server." +
             "\n" +
-            "For each client request command in this list that mandates a response from the server, the response " +
-            "command shall be indicated in the GeneratedCommandList attribute.",
+            "For each client request command in this list that mandates a response from the server, the" +
+            "\n" +
+            "response command shall be indicated in the GeneratedCommandList attribute." +
+            "\n" +
+            "If any attribute on a server supports atomic writes, this attribute shall contain the command ID " +
+            "for AtomicRequest.",
 
         xref: { document: "core", section: "7.13.4" }
     },