Add a script capable to check for backwards compatibility differences…

… between .matter files (#29349)

* Start defining a compatibility checker with unit tests

* Enumeration validation passes

* Restyle

* Mark unimplemented items with TODO

* Add some cluster validation tests

* Add validation for bitmap statuses and unit tests for that

* Mild restyle and clearer code

* Take into consideration cluster sides

* Update naming a bit

* More detailed messages for code entry changes

* Use sub-tests to mark clearly what failures occur where

* Fix typing and common logic

* Add implementation and tests for event backward compatibility

* Restyle

* Add command backwards compatibility checks and tests, better error reporting

* Less noisy output for unit tests

* Restyle

* Fixed types

* Split tests so we have better split and execution report - 23 tests instead of just 5

* Add minor unit test

* Added struct handling and unit tests

* Restyle

* Attribute validation

* Restyle

* Fix typo

* Add some extra logic to not detect renames in fields

* Additional tests for renames of fields

* Add struct tests for reorder and renames

* Add cluster names for error reports

* Restyle

* Fix test comments

* Move defs outside init into separate file, update build scripts

* Move to single file for use as an import instead of a module directory

* Remove unused import

* Rename some global methods to pep8

* Move more methods to pep8

* Remove unused import

* Make sure unit test is run as part of standard tests

* Update comment

* Ensure click argument for choice is list of str instead of a dictionary view (makes mypy happy)

---------

Co-authored-by: Andrei Litvin <andreilitvin@google.com>

scripts/backwards_compatibility_checker.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2023 Project CHIP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#
+import logging
+import sys
+
+import click
+
+try:
+ import coloredlogs
+ _has_coloredlogs = True
+except ImportError:
+ _has_coloredlogs = False
+
+try:
+ from matter_idl.matter_idl_parser import CreateParser
+except ImportError:
+ import os
+ sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), 'py_matter_idl')))
+ from matter_idl.matter_idl_parser import CreateParser
+
+from matter_idl.backwards_compatibility import is_backwards_compatible
+
+# Supported log levels, mapping string values required for argument
+# parsing into logging constants
+__LOG_LEVELS__ = {
+ 'debug': logging.DEBUG,
+ 'info': logging.INFO,
+ 'warn': logging.WARN,
+ 'fatal': logging.FATAL,
+}
+
+
+@click.command()
+@click.option(
+ '--log-level',
+ default='INFO',
+ type=click.Choice(list(__LOG_LEVELS__.keys()), case_sensitive=False),
+ help='Determines the verbosity of script output')
+@click.argument(
+ 'old_idl',
+ type=click.Path(exists=True))
+@click.argument(
+ 'new_idl',
+ type=click.Path(exists=True))
+def main(log_level, old_idl, new_idl):
+ """
+ Parses MATTER IDL files (.matter) and validates that <new_idl> is backwards compatible
+ when compared to <old_idl>.
+
+ Generally additions are safe, but not deletes or id changes. Actual set of rules
+ defined in `backwards_compatibility` module.
+ """
+ if _has_coloredlogs:
+ coloredlogs.install(level=__LOG_LEVELS__[
+ log_level], fmt='%(asctime)s %(levelname)-7s %(message)s')
+ else:
+ logging.basicConfig(
+ level=__LOG_LEVELS__[log_level],
+ format='%(asctime)s %(levelname)-7s %(message)s',
+ datefmt='%Y-%m-%d %H:%M:%S'
+ )
+
+ logging.info("Parsing OLD idl from %s" % old_idl)
+ old_tree = CreateParser().parse(open(old_idl, "rt").read())
+
+ logging.info("Parsing NEW idl from %s" % new_idl)
+ new_tree = CreateParser().parse(open(new_idl, "rt").read())
+
+ if not is_backwards_compatible(original=old_tree, updated=new_tree):
+ sys.exit(1)
+
+ sys.exit(0)
+
+
+if __name__ == '__main__':
+ main(auto_envvar_prefix='CHIP')

scripts/py_matter_idl/BUILD.gn

@@ -59,6 +59,7 @@ pw_python_package("matter_idl") {
  sources = matter_idl_generator_sources
 
  tests = [
+ "matter_idl/test_backwards_compatibility.py",
  "matter_idl/test_matter_idl_parser.py",
  "matter_idl/test_generators.py",
  "matter_idl/test_xml_parser.py",

scripts/py_matter_idl/files.gni

@@ -21,6 +21,7 @@ matter_idl_generator_templates = [
 
 matter_idl_generator_sources = [
  "${chip_root}/scripts/py_matter_idl/matter_idl/__init__.py",
+ "${chip_root}/scripts/py_matter_idl/matter_idl/backwards_compatibility.py",
  "${chip_root}/scripts/py_matter_idl/matter_idl/generators/__init__.py",
  "${chip_root}/scripts/py_matter_idl/matter_idl/generators/cpp/__init__.py",
  "${chip_root}/scripts/py_matter_idl/matter_idl/generators/cpp/application/__init__.py",
@@ -34,6 +35,7 @@ matter_idl_generator_sources = [
  "${chip_root}/scripts/py_matter_idl/matter_idl/lint/types.py",
  "${chip_root}/scripts/py_matter_idl/matter_idl/matter_idl_parser.py",
  "${chip_root}/scripts/py_matter_idl/matter_idl/matter_idl_types.py",
+ "${chip_root}/scripts/py_matter_idl/matter_idl/test_backwards_compatibility.py",
  "${chip_root}/scripts/py_matter_idl/matter_idl/test_generators.py",
  "${chip_root}/scripts/py_matter_idl/matter_idl/test_matter_idl_parser.py",
  "${chip_root}/scripts/py_matter_idl/matter_idl/test_xml_parser.py",