/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { collectDotSegments, Conformance } from "../../aspects/Conformance.js"; import { DeviceClassification } from "../../common/DeviceClassification.js"; import { EndpointComposition } from "../../common/EndpointComposition.js"; import { RequirementElement } from "../../elements/RequirementElement.js"; import { ClusterModel, ConditionModel, DeviceTypeModel, MatterModel, Model, RequirementModel, } from "../../models/index.js"; import { RequirementResolver } from "../RequirementResolver.js"; import { Memo } from "./Memo.js"; const lookups = new WeakMap(); /** * The lookups {@link model} shares with every `DeviceTypeValidationPass` resolved in it, one instance per model: * resolving a requirement to the cluster, feature or element it names, a device type's conditions, and similar. A * tree-derived fact never belongs here. * * Keyed on the model instance, so a model built by {@link MatterModel.withClusters} never sees another model's * entries. * * @internal */ export function lookupsFor(model: MatterModel): ModelLookups { let found = lookups.get(model); if (found === undefined) { found = new ModelLookups(model); lookups.set(model, found); } return found; } /** * The declared names a requirement's conformance may reference. * * @internal */ export interface KnownNames { /** * The conditions reachable unqualified from the requirement's {@link RequirementResolver.EndpointScope} and the * features of its cluster. A name outside them leaves the requirement unjudged. */ all: Set; /** * The features of the requirement's cluster. */ features: Set; } /** * @internal */ class ModelLookups { readonly #model: MatterModel; readonly #deviceTypes = new Memo(); readonly #clusters = new Memo(); readonly #referents = new Memo(); readonly #conditionScopes = new Memo>(); readonly #assertedConditions = new Memo(); readonly #knownNames = new Memo(); readonly #requirements = new Memo(); readonly #components = new Memo(); readonly #composed = new Memo(); readonly #compositions = new Memo(); readonly #base = new Memo(); readonly #aggregator = new Memo(); readonly #bridgedNode = new Memo(); readonly #assertedNames = new Memo>(); readonly #conformanceNames = new Memo>(); constructor(model: MatterModel) { this.#model = model; } /** * The device type {@link id} names, undefined when the model does not define one. */ deviceTypeOf(id: number): DeviceTypeModel | undefined { return this.#deviceTypes.get(id, () => this.#model.deviceTypes(id)); } /** * The requirements {@link parent}, a device type or a requirement, states directly. */ requirementsOf(parent: DeviceTypeModel | RequirementModel): readonly RequirementModel[] { return this.#requirements.get(parent, () => parent.requirements); } /** * The component device type {@link requirement} names, undefined when it is no device type requirement or names * no device type of the model. */ componentOf(requirement: RequirementModel): DeviceTypeModel | undefined { return this.#components.get(requirement, () => RequirementResolver.deviceTypeOf(requirement)); } /** * Whether {@link deviceType} states a device type requirement, which makes its endpoints composed. */ componentsDeclaredBy(deviceType: DeviceTypeModel): boolean { return this.#composed.get(deviceType, () => this.requirementsOf(deviceType).some( ({ element }) => element === RequirementElement.ElementType.DeviceType, ), ); } /** * {@link DeviceTypeModel.effectiveComposition}, resolved once per device type. */ compositionOf(deviceType: DeviceTypeModel): EndpointComposition { return this.#compositions.get(deviceType, () => deviceType.effectiveComposition); } /** * The cluster {@link requirement} names, undefined when it does not resolve in the model. */ clusterOf(requirement: RequirementModel): ClusterModel | undefined { return this.#clusters.get(requirement, () => RequirementResolver.clusterOf(requirement)); } /** * The feature, attribute, command or event model {@link requirement} names, undefined when it does not resolve. */ referentOf(requirement: RequirementModel): Model | undefined { return this.#referents.get(requirement, () => requirement.element === RequirementElement.ElementType.Feature ? RequirementResolver.featureOf(requirement) : RequirementResolver.elementOf(requirement), ); } /** * The condition {@link requirement} asserts, undefined when it asserts none. */ assertedConditionOf(requirement: RequirementModel): ConditionModel | undefined { return this.#assertedConditions.get(requirement, () => RequirementResolver.conditionOf(requirement)); } /** * {@link RequirementResolver.conditionsOf}, resolved once per model and device type. */ conditionScopeOf(deviceType: DeviceTypeModel): Map { return this.#conditionScopes.get(deviceType, () => RequirementResolver.conditionsOf(deviceType)); } /** * The declared names {@link requirement}'s conformance may reference. */ knownNamesOf(requirement: RequirementModel): KnownNames { return this.#knownNames.get(requirement, () => { const { deviceType, cluster } = RequirementResolver.endpointScopeOf(requirement); const features = new Set((cluster?.features ?? []).map(({ name }) => name)); const all = new Set(features); if (deviceType !== undefined) { for (const [key, condition] of this.conditionScopeOf(deviceType)) { // A qualified entry names a condition of any device type, which the requirement cannot reach if (!key.includes(".")) { all.add(condition.name); } } } return { all, features }; }); } /** * The device types the model classifies as Base, whose requirements apply to every endpoint that lists a device * type the model defines. */ get baseDeviceTypes(): readonly DeviceTypeModel[] { return this.#base.get(undefined, () => this.#model.deviceTypes.filter(deviceType => deviceType.classification === DeviceClassification.Base), ); } /** * The names of the conditions a requirement of a device type of the model asserts. */ get assertedConditionNames(): ReadonlySet { return this.#assertedNames.get(undefined, () => { const names = new Set(); for (const deviceType of this.#model.deviceTypes) { for (const requirement of this.requirementsOf(deviceType)) { const condition = this.assertedConditionOf(requirement); if (condition !== undefined) { names.add(condition.name); } } } return names; }); } /** * The names {@link requirement}'s conformance references, qualified ones joined by dots. */ conformanceNamesOf(requirement: RequirementModel): ReadonlySet { return this.#conformanceNames.get(requirement, () => { const names = new Set(); collectNames(requirement.conformance.ast, names); return names; }); } /** * The Aggregator device type, undefined when the model does not define one. */ get aggregator(): DeviceTypeModel | undefined { return this.#aggregator.get(undefined, () => this.#model.deviceTypes("Aggregator")); } /** * The BridgedNode device type, undefined when the model does not define one. */ get bridgedNode(): DeviceTypeModel | undefined { return this.#bridgedNode.get(undefined, () => this.#model.deviceTypes("BridgedNode")); } } function collectNames(ast: Conformance.Ast, names: Set) { switch (ast.type) { case Conformance.Special.Name: case Conformance.Operator.DOT: { const segments = collectDotSegments(ast); if (segments !== undefined) { names.add(segments.join(".")); } else if (ast.type === Conformance.Operator.DOT) { collectNames(ast.param.lhs, names); collectNames(ast.param.rhs, names); } break; } case Conformance.Operator.AND: case Conformance.Operator.OR: case Conformance.Operator.XOR: case Conformance.Operator.EQ: case Conformance.Operator.NE: case Conformance.Operator.GT: case Conformance.Operator.LT: case Conformance.Operator.GTE: case Conformance.Operator.LTE: collectNames(ast.param.lhs, names); collectNames(ast.param.rhs, names); break; case Conformance.Operator.NOT: case Conformance.Special.OptionalIf: collectNames(ast.param, names); break; case Conformance.Special.Choice: collectNames(ast.param.expr, names); break; case Conformance.Special.Otherwise: for (const entry of ast.param) { collectNames(entry, names); } break; } }