Normalize terminology to fit other standards (#23)

* Updated to more closely follow best practices in coding guidelines

* Update guideline template generator to comply with guidelines spec changes

* Added ability to use flag --update-spec-lock-file to update the spec lock file: spec.lock

Author: PLeVasseur

builder/build_cli.py

@@ -11,11 +11,14 @@
 import argparse
 import subprocess
 import sys
-
+import requests
+import json
 
 # Automatically watch the following extra directories when --serve is used.
 EXTRA_WATCH_DIRS = ["exts", "themes"]
 
+SPEC_CHECKSUM_URL = "https://spec.ferrocene.dev/paragraph-ids.json"
+SPEC_LOCKFILE = "spec.lock"
 
 def build_docs(root, builder, clear, serve, debug):
     dest = root / "build"
@@ -60,6 +63,34 @@ def build_docs(root, builder, clear, serve, debug):
 
     return dest / builder
 
+def update_spec_lockfile(spec_checksum_location, lockfile_location):
+
+    try:
+        response = requests.get(spec_checksum_location, stream=True)
+
+        response.raise_for_status()
+
+        with open(lockfile_location, 'wb') as file:
+            for chunk in response.iter_content(chunk_size=8192):
+                if chunk:
+                    file.write(chunk)
+
+        with open(lockfile_location, 'r') as file:
+            data = json.load(file)
+
+        print("-- read in --")
+
+        with open(lockfile_location, 'w') as outfile:
+            json.dump(data, outfile, indent=4, sort_keys=True)
+
+        print("-- wrote back out --")
+
+        return True
+
+    except Exception as e:
+        print(f"Error downloading file: {e}")
+        return False
+
 def main(root):
     root = Path(root)
 
@@ -68,6 +99,11 @@ def main(root):
         "-c", "--clear", help="disable incremental builds", action="store_true"
     )
     group = parser.add_mutually_exclusive_group()
+    parser.add_argument(
+        "--update-spec-lock-file",
+        help="update fls.lock file",
+        action="store_true"
+    )
     group.add_argument(
         "-s",
         "--serve",
@@ -87,6 +123,9 @@ def main(root):
     )
     args = parser.parse_args()
 
+    if args.update_spec_lock_file:
+        update_spec_lockfile(SPEC_CHECKSUM_URL, root / "src" / SPEC_LOCKFILE)
+
     rendered = build_docs(
         root, "xml" if args.xml else "html", args.clear, args.serve, args.debug
     )

exts/coding_guidelines/fls_checks.py

@@ -58,7 +58,7 @@ def check_fls(app, env):
 
 def read_fls_ignore_list(app):
     """Read the list of FLS IDs to ignore from a file"""
-    ignore_file_path = app.confdir / 'fls_ignore_list.txt'
+    ignore_file_path = app.confdir / 'spec_ignore_list.txt'
     ignore_list = []
 
     if ignore_file_path.exists():
@@ -276,7 +276,7 @@ def check_fls_lock_consistency(app, env, fls_raw_data):
         - List of difference descriptions with affected guidelines (for error reporting)
     """
     logger.info("Checking FLS lock file consistency")
-    lock_path = app.confdir / 'fls.lock'
+    lock_path = app.confdir / 'spec.lock'
 
     # Get the needs data to find affected guidelines
     data = SphinxNeedsData(env)

exts/coding_guidelines/write_guidelines_ids.py

@@ -70,8 +70,8 @@ def write_guidelines_ids(app):
                 "link": f"{doc_uri}#{need['id']}",
                 "checksum": checksum,
                 "rationale": None,
-                "bad_example": None,
-                "good_example": None
+                "non_compliant_example": None,
+                "compliant_example": None
             }
 
             # Look for associated elements using parent_needs_back
@@ -101,18 +101,18 @@ def write_guidelines_ids(app):
                     # Add to the appropriate field based on type
                     if related_type == 'rationale':
                         guideline_data["rationale"] = related_data
-                    elif related_type == 'bad_example':
-                        guideline_data["bad_example"] = related_data
-                    elif related_type == 'good_example':
-                        guideline_data["good_example"] = related_data
+                    elif related_type == 'non_compliant_example':
+                        guideline_data["non_compliant_example"] = related_data
+                    elif related_type == 'compliant_example':
+                        guideline_data["compliant_example"] = related_data
 
             # Check for missing elements
             if guideline_data["rationale"] is None:
                 missing_elements.append("rationale")
-            if guideline_data["bad_example"] is None:
-                missing_elements.append("bad_example")
-            if guideline_data["good_example"] is None:
-                missing_elements.append("good_example")
+            if guideline_data["non_compliant_example"] is None:
+                missing_elements.append("non_compliant_example")
+            if guideline_data["compliant_example"] is None:
+                missing_elements.append("compliant_example")
 
             # Track incomplete guidelines
             if missing_elements:

generate-guideline-templates.py

@@ -20,16 +20,17 @@ def generate_guideline_template():
     # Generate IDs for all sections
     guideline_id = generate_id("gui")
     rationale_id = generate_id("rat")
-    bad_example_id = generate_id("bad_ex")
-    good_example_id = generate_id("good_ex")
+    non_compliant_example_id = generate_id("non_compl_ex")
+    compliant_example_id = generate_id("compl_ex")
 
     template = f""".. guideline:: Title Here
    :id: {guideline_id}
+   :category:
    :status: draft
-   :fls: 
-   :tags: 
-   :category: 
-   :recommendation: 
+   :fls:
+   :decidability:
+   :scope:
+   :tags:
 
    Description of the guideline goes here.
 
@@ -39,28 +40,28 @@ def generate_guideline_template():
 
       Explanation of why this guideline is important.
 
-   .. bad_example:: 
-      :id: {bad_example_id}
+   .. non_compliant_example::
+      :id: {non_compliant_example_id}
       :status: draft
 
       Explanation of code example.
    
       .. code-block:: rust
    
         fn example_function() {{
-            // Bad implementation
+            // Non-compliant implementation
         }}
 
-   .. good_example:: 
-      :id: {good_example_id}
+   .. compliant_example::
+      :id: {compliant_example_id}
       :status: draft
 
       Explanation of code example.
    
       .. code-block:: rust
    
         fn example_function() {{
-            // Bad implementation
+            // Compliant implementation
         }}
 """
     return template

src/coding-guidelines/types-and-traits.rst

@@ -8,17 +8,18 @@ Types and Traits
 
 .. guideline:: Avoid Implicit Integer Wrapping
    :id: gui_xztNdXA2oFNB
+   :category: required
    :status: draft
    :fls: fls_cokwseo3nnr
+   :decidability: decidable
+   :scope: module
    :tags: numerics
-   :category: types
-   :recommendation: required
 
    Code must not rely on Rust's implicit integer wrapping behavior that occurs in release builds. 
    Instead, explicitly handle potential overflows using the standard library's checked, 
    saturating, or wrapping operations.
 
-   .. rationale:: 
+   .. rationale::
       :id: rat_kYiIiW8R2qD1
       :status: draft
 
@@ -30,8 +31,8 @@ Types and Traits
       configurations. Explicit handling of potential overflow conditions improves code clarity,
       maintainability, and reduces the risk of numerical errors in production.
 
-   .. bad_example:: 
-      :id: bad_ex_PO5TyFsRTlWv
+   .. non_compliant_example::
+      :id: non_compl_ex_PO5TyFsRTlWv
       :status: draft
 
        .. code-block:: rust
@@ -41,8 +42,8 @@ Types and Traits
              current + velocity
          }
 
-   .. good_example:: 
-      :id: good_ex_WTe7GoPu5Ez0
+   .. compliant_example::
+      :id: compl_ex_WTe7GoPu5Ez0
       :status: draft
 
        .. code-block:: rust

src/conf.py

@@ -48,16 +48,16 @@
         "style": "node"
     },
     {
-        "directive": "good_example",
-        "title": "Good Example",
-        "prefix": "good_ex_",
+        "directive": "compliant_example",
+        "title": "Compliant Example",
+        "prefix": "compl_ex_",
         "color": "#729FCF", 
         "style": "node"
     },
     {
-        "directive": "bad_example",
-        "title": "Bad Example",
-        "prefix": "bad_ex_",
+        "directive": "non_compliant_example",
+        "title": "Non-Compliant Example",
+        "prefix": "non_compl_ex_",
         "color": "#729FCF", 
         "style": "node"
     }
@@ -69,8 +69,8 @@
         "content": [
             "content",
             "rationale",
-            "good_example",
-            "bad_example"
+            "non_compliant_example",
+            "compliant_example"
         ]
     }
 }
@@ -79,12 +79,12 @@
 needs_render_contexts = {
     "guideline": {
         "content": ["content"],
-        "extra_content": ["rationale", "bad_example", "good_example"]
+        "extra_content": ["rationale", "non_compliant_example", "non_compliant_example"]
     }
 }
 
 # Make sure these sections are included in the JSON
-needs_extra_sections = ["rationale", "good_example", "bad_example"]
+needs_extra_sections = ["rationale", "compliant_example", "non_compliant_example"]
 
 needs_statuses = [
     dict(name="draft", description="This guideline is in draft stage", color="#999999"),
@@ -101,13 +101,26 @@
     dict(name="numerics", description="Numerics-related guideline"),
 ]
 
-needs_recommendations = [
-    dict(name="encouraged", description="This guideline is encouraged", color="#999999"),
+needs_categories = [
+    dict(name="mandatory", description="This guideline is mandatory", color="#999999"),
     dict(name="required", description="This guideline is required", color="#FFCC00"),
+    dict(name="advisory", description="This guideline is advisory, should be followed when able", color="#FFCC00"),
+    dict(name="disapplied", description="This guideline is advisory, should be followed when able", color="#FFCC00"),
+]
+
+needs_decidabilities = [
+    dict(name="decidable", description="This guideline can be automatically checked with tooling", color="#999999"),
+    dict(name="undecidable", description="This guideline cannot be automatically checked with tooling", color="#999999"),
+]
+
+needs_scopes = [
+    dict(name="module", description="This guideline can be checked at the module level", color="#999999"),
+    dict(name="crate", description="This guideline can be checked at the crate level", color="#FFCC00"),
+    dict(name="system", description="This guideline must be checked alongside the entire source", color="#FFCC00"),
 ]
 
 # Enable needs export
-needs_extra_options = ["category", "recommendation", "fls"]
+needs_extra_options = ["category", "recommendation", "fls", "decidability", "scope"]
 
 # -- Options for HTML output -------------------------------------------------