Update check_guideline

.github/scripts/README.md

@@ -109,36 +109,69 @@ source .github/scripts/check_for_missing_readme_md.sh
 
 ### Prerequisites
 
-- the script must be run while being in the root directory (/hdl)
-- clean the repository to remove the files generated by Vivado
-- it will be run only on Verilog files that do not contain "tb" in their path
-- doesn't run on SystemVerilog files
-- uses Python 3.x
+* the script must be run while being in the root directory (/hdl)
+* clean the repository to remove the files generated by Vivado
+* runs on Verilog (.v) and SystemVerilog (.sv) files, except those containing
+"tb" in their path/name (testbenches are ignored)
+* uses Python 3.x
 
 ### Rules that are checked
 
 These rules can be found in the [HDL coding guidelines](https://analogdevicesinc.github.io/hdl/user_guide/hdl_coding_guidelines.html).
 
 #### 1. License header
 
-It checks if the license header is up-to-date, containing the current year in
-the year range. Exceptions are the JESD files and the ones specified in the
-`avoid_list` string list.
+It checks that the copyright years after Copyright (C) are up-to-date and properly
+formatted.
+Supported forms: a single year, a range (YYYY-YYYY), or a comma-separated list
+combining singles and/or ranges. 
+Exceptions are the JESD files and the ones specified in the `avoid_list` string list.
+
+The following checks are performed (only the last year and, if present, the
+penultimate year are considered):
+ * If the last year equals the current year:
+   * If a penultimate year exists and current - penultimate == 1, it must be a range (-).
+   * If it is written as a list (, current), the script warns and merges to ...-current.
+   * If a penultimate year exists and current - penultimate > 1, a list is correct; only formatting may be normalized.
+   * If there is no penultimate year, a single current year is OK.
+ * If the last year is not the current year:
+   * If current - last == 1, it extends the last token into a range ending at the current year.
+   * If current - last > 1, it appends , current.
+
+Examples:
+```
+2013-2024          -> 2013-2025
+2013-2020          -> 2013-2020, 2025
+2024               -> 2024-2025
+2022               -> 2022, 2025
+2013, 2024         -> 2013, 2024-2025
+2013-2024, 2025    -> 2013-2025        (warn: wrong delimiter; merged)
+2013-2020, 2025    -> 2013-2020, 2025  (ok as list; spacing normalized)
+```
+
 If `-e` option is added, the script can update the year range.
 
-#### 2. Two or more consecutive empty lines
+#### 2. Empty lines
 
-It checks in the whole file if there are two or more consecutive empty lines.
-If `-e` option is added, the script can remove them and leave only one empty line.
+It checks if the file contains empty line issues:
+* Two or more consecutive empty lines.
+* An empty line at the beginning of the file.
+* An empty line at the end of the file.
+
+If `-e` option is added, the script removes redundant empty lines and ensures
+that at most one empty line is kept, while also removing any leading or trailing
+empty lines.
 
 #### 3. Trailing whitespace
 
 It checks if there are whitespace characters at the end of the lines.
+
 If `-e` option is added, then they can be removed.
 
-#### 4. Lines after `endmodule` tag
+#### 4. Lines after end token
+
+It checks if there are lines after end token (`endmodule` or `endpackage`).
 
-It checks if there are  lines after it.
 If `-e` option is added, the script can remove them.
 
 #### 5. Parentheses around the module declaration
@@ -147,66 +180,135 @@ It checks if the parentheses around the module declaration (meaning `) (` for
 the parameters' list) are on an empty line, right after the last parameter.
 It also checks for the closing parenthesis at the module declaration (meaning `);`)
 to be on an empty line, at the beginning, right after the last I/O port line.
+
 If `-e` option is added, the script can put them in their proper place.
 
 #### 6. Indentation of code
 
-It checks if all lines (except for the ones that are commented) have an indentation
-of two or multiple of two spaces.
-Other exceptions to this are the `module` line, the `endmodule` line, the `) (`
-and the `);` from the module declaration.
+It checks that indentation is done with spaces in multiples of 2 (minimum 2).
+This applies to parameters, ports, and code inside modules or packages.
 
 #### 7. Position of the module instances
 
 It checks if the parameters' list (if that's the case) is in proper position,
 meaning that the position of `#` is checked, the parameters to be specified each
-on its own line, the parentheses around the instance name and the closing parenthesis
-of the module instance.
+on its own line, the parentheses around the instance name and the closing
+parenthesis of the module instance.
 
 _NOTE_: these rules are marked in the script with **GC** (stands for Guideline Check)
 in the comments.
 
-### Changes done by the script to your files
+#### 8. SystemVerilog packages
+
+It checks if SystemVerilog packages are defined correctly:
+* `package <name>;` starts at column 0, with no extra spaces before or after ;.
+* `endpackage` is alone on its line at column 0.
+* Exactly one newline follows `endpackage`.
+* Inside the package, typedefs and localparams follow the same indentation and alignment rules.
+
+If `-e` option is added, the script rewrites these to the guideline-compliant
+format.
+
+#### 9. Localparams
+
+It checks if localparam declarations follow the rules:
+* Indented by a multiple of 2 spaces (minimum 2).
+* **List form:** each item is on a new line, `=` operator is aligned, and the last
+item has no comma.
+* **Concatenation form ({ … }):**
+  * The first element is on the same line as `{`.
+  * Following elements are indented +2 spaces.
+  * Inline comments are aligned at least 4 spaces after the longest element.
+  * The closing `};` is attached to the last element.
+
+If `-e` option is added, the script normalizes the block automatically.
+
+#### 10. Typedefs
+
+It checks if typedef blocks are formatted correctly:
+* They are not written as one-liners, each item is on its own line.
+* Base indentation is a multiple of 2 and at least 2.
+* Inner items are indented +2.
+* Closing `} type_name;` is aligned with the opening `typedef`.
+* Inline comments after the closing are moved to a separate line.
+
+If `-e` option is added, the script rewrites the block to the guideline-compliant
+format.
+
+#### 11. Project name vs. path
 
-If one wants the script to make changes in files, they will be regarding:
+It checks that in each system_project.tcl, the project name used in `adi_project`
+matches the relative project path under `projects/`.
 
-- license header, except for JESD files and the ones specified in `avoid_list`
-- two or more consecutive empty lines
-- trailing whitespaces
-- lines after `endmodule` tag
-- parentheses around the module declaration (meaning `) (` for the parameters'
+Example:
+```
+projects/ad9783_ebz/zcu102 ⇒ adi_project ad9783_ebz_zcu102
+```
+
+If `-e` option is added, the script updates the project name automatically.
+
+### Changes done by the script to your files
+
+If edits are enabled (-e), the script may modify:
+* license header, except for files specified in `avoid_list`
+* empty lines (two or more consecutive, or at file start/end)
+* trailing whitespaces
+* lines after `endmodule`/`endpackage` tag
+* parentheses around the module declaration (meaning `) (` for the parameters'
   list and `);` for when closing the declaration)
+* typedefs and localparams — rewritten into a guideline-compliant format
+* SystemVerilog packages — normalizes `package <name>;` / `endpackage` placement
+and ensures exactly one newline after `endpackage`
+* project name inside `system_project.tcl` (to match the relative project path)
 
 ### Ways to run the script
 
+The script supports several modes of execution, depending on what files you want
+to check and whether edits are allowed:
+
 1. With no arguments: `python3 check_guideline.py`
-Checks all files with the properties specified above.
-Does not modify the files.
+Runs on all HDL files under `library/` and `projects/`, in check-only mode (does
+not modify the files).
 
 2. With arguments:
-    1. `-e` with no file specified
-      Checks all files with the properties specified above. Additionally,
-      it modifies the module definition parentheses according to the guideline.
-    2. `-m`
-      Checks files that are given as arguments (by their names including the
-      extension).
-    3. `-me`
-      Checks files that are given as arguments (by their names including the
-      extension) and modifies the files where the guideline is not respected.
-    4. `-p`
-      Checks files that are given as arguments (by their relative path) and
-      modifies the files where the guideline is not respected.
-    5. `-pe`
-      Checks files that are given as arguments (by their relative path) and
-      modifies the files where the guideline is not respected.
+  1. `-e` with no file specified: `python3 check_guideline.py -e`
+    Checks all files with the properties specified above and applies fixes
+    according to the guideline.
+
+  2. `-m`
+    Checks files that are given as arguments (by their names including the
+    extension).
+
+  3. `-me`
+    Checks files that are given as arguments (by their names including the
+    extension) and modifies the files where the guideline is not respected.
+
+  4. `-p`
+    Checks files that are given as arguments (by their relative path) and
+    modifies the files where the guideline is not respected.
+
+  5. `-pe`
+    Checks files that are given as arguments (by their relative path) and
+    modifies the files where the guideline is not respected.
 
 ### Examples of running
 
 ```
+# Check all files in the repo, no modifications
 python3 check_guideline.py     >> warnings.txt
+
+# Check and edit every HDL file in the repo
 python3 check_guideline.py -e  >> warnings.txt
+
+# Check a specific file given by name, no modifications
 python3 check_guideline.py -m  axi_ad9783.v >> warnings.txt
+
+# Check and edit a specific files by name
 python3 check_guideline.py -me axi_ad9783.v axi_ad9783_if.v up_adc_common.v >> warnings.txt
+
+# Check specific files given by absolute/relative paths, no modifications
 python3 check_guideline.py -p  ./library/axi_ad9783/axi_ad9783.v ./library/common/up_adc_common.v >> warnings.txt
+
+# Check and edit a specific file given by absolute/relative path
 python3 check_guideline.py -pe ./library/axi_ad9783/axi_ad9783_if.v >> warnings.txt
 ```