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 <[email protected]>

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",