CI: devicetree: linting to check_compliance.py

Use dts-linter to check each touched file in PR

Signed-off-by: Kyle Micallef Bonnici <[email protected]>

Author: kylebonnici

.github/workflows/compliance.yml

@@ -60,6 +60,16 @@ jobs:
         west config manifest.group-filter -- +ci,-optional
         west update -o=--depth=1 -n 2>&1 1> west.update.log || west update -o=--depth=1 -n 2>&1 1> west.update2.log
 
+    - name: Setup Node.js
+      uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
+      with:
+        node-version: "lts/*"
+        cache: npm
+        check-latest: true
+
+    - name: Install Node dependencies
+      run: npm ci
+
     - name: Run Compliance Tests
       continue-on-error: true
       id: compliance
@@ -86,6 +96,14 @@ jobs:
         name: compliance.xml
         path: compliance.xml
 
+    - name: Upload dts linter patch
+      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+      continue-on-error: true
+      if: hashFiles('dts_linter.patch') != ''
+      with:
+        name: dts_linter.patch
+        path: dts_linter.patch
+
     - name: check-warns
       run: |
         if [[ ! -s "compliance.xml" ]]; then

.gitignore

@@ -76,6 +76,7 @@ target/
 
 # CI output
 compliance.xml
+dts_linter.patch
 _error.types
 
 # Tag files
@@ -118,3 +119,6 @@ TextEncoding.txt
 YAMLLint.txt
 ZephyrModuleFile.txt
 # zephyr-keep-sorted-stop
+
+# Node dependecies
+node_modules

doc/contribute/style/devicetree.rst

@@ -4,6 +4,7 @@ Devicetree Style Guidelines
 ###########################
 
   * Indent with tabs.
+  * Tab size is 8 characters.
   * Follow the Devicetree specification conventions and rules.
   * If the Linux kernel rules in
     `Devicetree Sources (DTS) Coding Style <https://docs.kernel.org/devicetree/bindings/dts-coding-style.html>`_

doc/contribute/style/index.rst

@@ -87,3 +87,35 @@ When there are differences between the `Coding Style Guidelines`_ guidelines and
 formatting generated by code formatting tools, the `Coding Style Guidelines`_ guidelines
 take precedence. If there is ambiguity between formatting tools and the
 guidelines, maintainers may decide which style should be adopted.
+
+dts-linter
+============
+
+The `dts-linter <https://www.npmjs.com/package/dts-linter>`_ can be helpful
+to quickly reformat large amounts of devicetree files to our `Coding Style Guidelines`_
+standards. You can also run it manually like this:
+
+For individual files
+.. code-block:: bash
+
+   npx dts-linter --format --file board.dts --file board_pinctrl.dtsi --patchFile diff.patch
+   git apply diff.patch
+
+You can omit ``--file`` and this will format all files under the directory where the command
+has been called. Alternatively ``--cwd`` can also be passed set the base dir where the tool
+should look for files. This option is also used to make the paths relative in the patch file.
+
+You can also fix in place with
+.. code-block:: bash
+
+   npx dts-linter --formatFixAll
+
+
+Editor Integration
+~~~~~~~~~~~~~~~~~~
+
+* For VS Code: Install the extension from the `VS Code Marketplace <https://marketplace.visualstudio.com/items?itemName=KyleMicallefBonnici.dts-lsp>`_ or `Open VSIX <https://open-vsx.org/extension/KyleMicallefBonnici/dts-lsp>`_
+* For other editors with LSP Client support: Use the devicetree-language-server `devicetree-language-server <https://www.npmjs.com/package/devicetree-language-server>`_
+
+Make sure you follow `Devicetree Style Guidelines <https://docs.zephyrproject.org/latest/contribute/style/devicetree.html>`_
+requirements to configure the editor correctly.

package-lock.json

@@ -0,0 +1,6 @@
+{
+  "private": true,
+  "dependencies": {
+    "dts-linter": "^0.3.0"
+  }
+}

package.json

@@ -2573,6 +2573,11 @@ sub process {
 			next;
 		}
 
+		# skip package-lock.json and package.json files specifically
+		if ($realfile =~ /package(-lock)?\.json$/) {
+			next;
+		}
+
 #make up the handle for any error we report on this line
 		if ($showfile) {
 			$prefix = "$realfile:$realline: "

scripts/checkpatch.pl

@@ -489,6 +489,105 @@ def required_false_check(self, binding):
                     "'required: false' is redundant, please remove"
                 )
 
+
+class DevicetreeLintingCheck(ComplianceTest):
+    """
+    Checks if we are introducing syntax or formatting issues to devicetree files.
+    """
+    name = "DevicetreeLinting"
+    doc = "See https://docs.zephyrproject.org/latest/contribute/style/devicetree.html for more details."
+
+    def _parse_json_output(self, cmd, cwd=None):
+        """Run command and parse single JSON output with issues array"""
+        result = subprocess.run(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            check=False,
+            text=True,
+            cwd=cwd or GIT_TOP
+        )
+
+        if not result.stdout.strip():
+            return None
+
+        try:
+            json_data = json.loads(result.stdout)
+            return json_data
+        except json.JSONDecodeError as e:
+            raise RuntimeError(f"Failed to parse dts-linter JSON output: {e}")
+
+    def run(self):
+        # Get changed DTS files
+        dts_files = [
+            file for file in get_files(filter="d")
+            if file.endswith((".dts", ".dtsi", ".overlay"))
+        ]
+
+        if not dts_files:
+            self.skip('No DTS')
+
+        temp_patch_files = []
+        batch_size = 500
+
+        for i in range(0, len(dts_files), batch_size):
+            batch = dts_files[i:i + batch_size]
+
+            # use a temporary file for each batch
+            temp_patch = f"dts_linter_{i}.patch"
+            temp_patch_files.append(temp_patch)
+
+            cmd = [
+                "npx", "--no", "dts-linter", "--",
+                "--outputFormat", "json",
+                "--format",
+                "--patchFile", temp_patch,
+            ]
+            for file in batch:
+                cmd.extend(["--file", file])
+
+            try:
+                json_output = self._parse_json_output(cmd)
+
+                if json_output and "issues" in json_output:
+                    cwd = json_output.get("cwd", "")
+                    logging.info(f"Processing issues from: {cwd}")
+
+                    for issue in json_output["issues"]:
+                        level = issue.get("level", "unknown")
+                        message = issue.get("message", "")
+
+                        if level == "info":
+                            logging.info(message)
+                        else:
+                            title = issue.get("title", "")
+                            file = issue.get("file", "")
+                            line = issue.get("startLine", None)
+                            col = issue.get("startCol", None)
+                            end_line = issue.get("endLine", None)
+                            end_col = issue.get("endCol", None)
+                            self.fmtd_failure(level, title, file, line, col, message, end_line, end_col)
+
+            except subprocess.CalledProcessError as ex:
+                stderr_output = ex.stderr if ex.stderr else ""
+                if stderr_output.strip():
+                    self.failure(f"dts-linter found issues:\n{stderr_output}")
+                else:
+                    self.failure("dts-linter failed with no output. "
+                                "Make sure you install Node.JS and then run npm ci inside ZEPHYR_BASE")
+            except RuntimeError as ex:
+                self.failure(f"{ex}")
+
+        # merge all temp patch files into one
+        with open("dts_linter.patch", "wb") as final_patch:
+            for patch in temp_patch_files:
+                with open(patch, "rb") as f:
+                    shutil.copyfileobj(f, final_patch)
+
+        # cleanup
+        for patch in temp_patch_files:
+            os.remove(patch)
+
 class KconfigCheck(ComplianceTest):
     """
     Checks is we are introducing any new warnings/errors with Kconfig,