🔧 Move dead link need fields to internals (#1119)

Currently, `has_dead_links` and `has_forbidden_dead_links` are set as default "extra options".
This means they are set to default `""` and, in principle, the user can set them to something else.

This commit changes them to be "internal" fields, since this is an internal consistency check:

- when initialised they should always be set to `False` (ignoring any previous value, if they are from an external source)
- In the `check_links` post-processing of the needs, they are then set to `True`, if required

sphinx_needs/api/need.py

@@ -354,6 +354,8 @@ def run():
         "external_css": external_css or "external_link",
         "is_modified": False,  # needed by needextend
         "modifications": 0,  # needed by needextend
+        "has_dead_links": False,
+        "has_forbidden_dead_links": False,
         # these are set later in the analyse_need_locations transform
         "sections": [],
         "section_name": "",

sphinx_needs/data.py

@@ -136,6 +136,14 @@ class NeedsInfoType(TypedDict):
     # these all have value type `list[str]`
     # back links are all set in process_need_nodes (-> create_back_links) transform
 
+    # these default to False and are updated in check_links post-process
+    has_dead_links: bool
+    """True if any links reference need ids that are not found in the need list."""
+    has_forbidden_dead_links: bool
+    """True if any links reference need ids that are not found in the need list,
+    and the link type does not allow dead links.
+    """
+
     # constraints information
     constraints: list[str]
     """List of constraint names, which are defined for this need."""
@@ -173,9 +181,6 @@ class NeedsInfoType(TypedDict):
     duration: str
     completion: str
     # constraints: str  # this is already set in create_need
-    # these are updated in process_need_nodes (-> check_links) transform
-    has_dead_links: str | bool
-    has_forbidden_dead_links: str | bool
     # options from `BaseService.options` get added to every need,
     # via `ServiceManager.register`, which adds them to `extra_options``
     # GithubService

sphinx_needs/layout.py

@@ -728,7 +728,7 @@ def meta_all(
         :param show_empty: If true, also need data with no value will be printed. Mostly useful for debugging.
         :return: docutils nodes
         """
-        default_excludes = INTERNALS.copy()
+        default_excludes = list(INTERNALS)
 
         if exclude is None or not isinstance(exclude, list):
             if defaults:

sphinx_needs/needs.py

@@ -517,8 +517,6 @@ def prepare_env(app: Sphinx, env: BuildEnvironment, _docname: str) -> None:
         "hidden",
         "duration",
         "completion",
-        "has_dead_links",
-        "has_forbidden_dead_links",
         "constraints",
     ]:
         # Check if not already set by user

sphinx_needs/utils.py

@@ -41,7 +41,7 @@ class NeedFunctionsType(TypedDict):
 NEEDS_FUNCTIONS: dict[str, NeedFunctionsType] = {}
 
 # List of internal need option names. They should not be used by or presented to user.
-INTERNALS = [
+INTERNALS = (
     "docname",
     "doctype",
     "lineno",
@@ -82,7 +82,9 @@ class NeedFunctionsType(TypedDict):
     "constraints_results",
     "arch",
     "target_id",
-]
+    "has_dead_links",
+    "has_forbidden_dead_links",
+)
 
 MONTH_NAMES = [
     "January",

tests/__snapshots__/test_basic_doc.ambr

@@ -1,4 +1,3 @@
-# serializer version: 1
 # name: test_build_needs[test_app0]
   dict({
     'current_version': '',
@@ -30,8 +29,8 @@
             'external_css': 'external_link',
             'external_url': None,
             'full_title': 'Test story',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'ST_001',
             'id_prefix': '',
@@ -98,8 +97,8 @@
             'external_css': 'external_link',
             'external_url': None,
             'full_title': 'No ID',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'US_38823',
             'id_prefix': '',

tests/__snapshots__/test_export_id.ambr

@@ -1,4 +1,3 @@
-# serializer version: 1
 # name: test_export_id[test_app0]
   dict({
     'current_version': '1.0',
@@ -136,8 +135,8 @@
             'external_css': 'external_link',
             'external_url': None,
             'full_title': 'My requirement',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'REQ_001',
             'id_prefix': '',
@@ -212,8 +211,8 @@
             'external_css': 'external_link',
             'external_url': None,
             'full_title': 'My requirement 2',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'REQ_002',
             'id_prefix': '',
@@ -285,8 +284,8 @@
             'external_css': 'external_link',
             'external_url': None,
             'full_title': 'My requirement 3',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'REQ_003',
             'id_prefix': '',
@@ -358,8 +357,8 @@
             'external_css': 'external_link',
             'external_url': None,
             'full_title': 'My requirement 4',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'REQ_004',
             'id_prefix': '',
@@ -436,8 +435,8 @@
             'external_css': 'external_link',
             'external_url': None,
             'full_title': 'Req 5',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'REQ_005',
             'id_prefix': '',
@@ -540,8 +539,8 @@
             'external_css': 'external_link',
             'external_url': None,
             'full_title': 'Test of requirements',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'TEST_001',
             'id_prefix': '',
@@ -615,8 +614,8 @@
             'external_css': 'external_link',
             'external_url': None,
             'full_title': 'Test of requirements2',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'TEST_002',
             'id_prefix': '',
@@ -690,8 +689,8 @@
             'external_css': 'external_link',
             'external_url': None,
             'full_title': 'Test of requirements 5',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'TEST_003',
             'id_prefix': '',

tests/__snapshots__/test_external.ambr

@@ -1,4 +1,3 @@
-# serializer version: 1
 # name: test_external_json[test_app0]
   dict({
     'current_version': '1.0',
@@ -30,8 +29,8 @@
             'external_css': 'external_link',
             'external_url': 'http://my_company.com/docs/v1/index.html#TEST_01',
             'full_title': 'TEST_01 DESCRIPTION',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'EXT_TEST_01',
             'id_prefix': '',
@@ -98,8 +97,8 @@
             'external_css': 'external_link',
             'external_url': 'http://my_company.com/docs/v1/index.html#TEST_02',
             'full_title': 'TEST_02 DESCRIPTION',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'EXT_TEST_02',
             'id_prefix': '',
@@ -169,8 +168,8 @@
             'external_css': 'external_link',
             'external_url': None,
             'full_title': 'Test requirement 1',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'REQ_1',
             'id_prefix': '',
@@ -237,8 +236,8 @@
             'external_css': 'external_link',
             'external_url': None,
             'full_title': 'Test specification 1',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'SPEC_1',
             'id_prefix': '',
@@ -307,8 +306,8 @@
             'external_css': 'external_link',
             'external_url': None,
             'full_title': 'Sub-Req',
-            'has_dead_links': '',
-            'has_forbidden_dead_links': '',
+            'has_dead_links': False,
+            'has_forbidden_dead_links': False,
             'hidden': '',
             'id': 'SUB_002',
             'id_prefix': '',