Refactor: structured INPUT parameter availability (Phase 1)

docs/generate_input_main.py

@@ -141,6 +141,36 @@ def format_description(desc: str) -> str:
     return result.strip()
 
 
+def _availability_display(param):
+    """Return a display string for a parameter's availability.
+
+    Prefers the exported structured fields (availability_kind / label) when
+    present; otherwise falls back to the raw ``availability`` string (e.g. for
+    older parameters.yaml files that only carry the string).
+    """
+    # The raw string is already the canonical, user-facing representation
+    # (a boolean expression for Expression items, the human text otherwise).
+    return str(param.get('availability', ''))
+
+
+def _availability_kind(param, parse_legacy):
+    """Return the structured availability kind for a parameter.
+
+    Prefers ``availability_kind`` from the YAML. When it is absent (legacy
+    dump), classifies the raw string with the provided parser function.
+    """
+    kind = param.get('availability_kind')
+    if kind in ('Expression', 'Label', 'Unstructured'):
+        return kind
+    avail = (param.get('availability', '') or '').strip()
+    if not avail:
+        return None
+    if parse_legacy is None:
+        return 'Unstructured'
+    parsed = parse_legacy(avail)
+    return parsed.kind if parsed.kind in ('Expression', 'Label', 'Unstructured') else 'Unstructured'
+
+
 def generate_parameter_markdown(param: Dict[str, str]) -> str:
     """
     Generate markdown for a single parameter.
@@ -154,7 +184,7 @@ def generate_parameter_markdown(param: Dict[str, str]) -> str:
 
     # Availability (before description, as in original format)
     if param.get('availability', '') != '':
-        availability_text = escape_md_text(str(param['availability']))
+        availability_text = escape_md_text(_availability_display(param))
         lines.append(f"- **Availability**: *{availability_text}*")
 
     # Description
@@ -232,9 +262,60 @@ def generate_toc(sorted_categories: OrderedDict) -> str:
     return '\n'.join(lines)
 
 
-def generate(yaml_path: Path, output: Path, verbose: bool = False):
+def _report_availability(all_params):
+    """Classify every non-empty availability string and summarise the result.
+
+    Uses tools/03_code_analysis/availability_parser.py. This is a status
+    report only; it does not modify the generated documentation.
+    """
+    # Prefer the structured availability_kind exported by abacus; only fall
+    # back to the text parser for older dumps that do not carry the field.
+    parse_legacy = None
+    if not any(p.get('availability_kind') for p in all_params if p.get('availability')):
+        try:
+            sys.path.insert(0, str(DOC_FOLDER.parent / 'tools' / '03_code_analysis'))
+            from availability_parser import parse_availability
+            parse_legacy = parse_availability
+        except ImportError:
+            print("[availability] parser not found; skipping availability check")
+            return
+
+    counts = {"Expression": 0, "Label": 0, "Unstructured": 0}
+    unstructured = []
+    labelled = 0
+    for p in all_params:
+        avail = p.get('availability', '')
+        if not avail:
+            continue
+        kind = _availability_kind(p, parse_legacy)
+        if kind in counts:
+            counts[kind] += 1
+        if kind == "Unstructured":
+            unstructured.append((p.get('name', '?'), avail))
+        elif kind == "Label":
+            labelled += 1
+
+    print("[availability] non-empty:", sum(counts.values()),
+          " Expression:", counts["Expression"],
+          " Label:", counts["Label"],
+          " Unstructured:", counts["Unstructured"])
+    if unstructured:
+        print("[availability] parameters with unstructured availability"
+              " waiting for review (%d):" % len(unstructured))
+        for name, text in unstructured:
+            print(f"  {name}: {text}")
+
+
+def generate(yaml_path: Path, output: Path, verbose: bool = False,
+             check_availability: bool = False):
     """
     Core generation logic. Can be called from conf.py or CLI.
+
+    When ``check_availability`` is True, additionally report how many INPUT
+    ``availability`` strings are machine-parsable conditions, applicability
+    labels, or unstructured prose waiting for review (see
+    tools/03_code_analysis/availability_parser.py). It does not alter the
+    generated markdown.
     """
     yaml_path = Path(yaml_path)
     output = Path(output)
@@ -248,6 +329,9 @@ def generate(yaml_path: Path, output: Path, verbose: bool = False):
     all_params = data.get('parameters', [])
     print(f"Total: {len(all_params)} documented parameters")
 
+    if check_availability:
+        _report_availability(all_params)
+
     # Group by category
     by_category: Dict[str, List[Dict[str, str]]] = OrderedDict()
     for param in all_params:
@@ -313,9 +397,15 @@ def main():
         action='store_true',
         help='Print verbose output'
     )
+    parser.add_argument(
+        '--check-availability',
+        action='store_true',
+        help='Report how many INPUT availability strings are parseable '
+             'conditions vs. labels vs. unstructured text (no doc changes)'
+    )
 
     args = parser.parse_args()
-    generate(args.yaml_file, args.output, args.verbose)
+    generate(args.yaml_file, args.output, args.verbose, args.check_availability)
 
 
 if __name__ == '__main__':