Refactor: structured INPUT parameter availability (Phase 1) (deepmodeling#7783)

* Tools: add structured parser for INPUT availability strings

The Input_Item availability field mixes prose and ad-hoc conditions as free
text, which cannot be consumed programmatically for tree-structured docs,
validation or agent tooling.

Add a small dependency-free parser (tools/03_code_analysis/availability_parser.py)
that normalises the historical spellings (==, =, 'is set to', 'contains')
onto a canonical form and classifies each value as an Expression, a bare
Label, or Unstructured prose waiting for review.

- availability_parser.py: parse_availability() -> Availability
- test_availability_parser.py: unit tests
- generate_input_main.py: add --check-availability to report the
  Expression/Label/Unstructured distribution without changing the generated
  markdown.

On the current docs/parameters.yaml this classifies 217 non-empty values as
82 Expression / 84 Label / 51 Unstructured.

* feat(input): structured availability for INPUT parameters (Phase 1)

Make the Input_Item availability field a concrete, machine-readable boolean
condition (single source of truth) so the INPUT docs, validation and tooling
can consume the actual condition instead of free text or bare tags.

- Add AvailabilityKind/AvailabilityCondition/AvailabilityExpr and
  parse_availability() in a new module (availability.{h,cpp}, wired into CMake).
- Input_Item now carries availability_kind + availability_expr and a
  set_availability() helper that keeps the canonical string and the structured
  form in sync (single source of truth).
- Rewrite all 217 non-empty availability registrations to canonical boolean
  syntax; the exported YAML classifies them as 216 Expression / 0 Unstructured.
- Export the structured fields from --generate-parameters-yaml (input_help.cpp).
- Consume the structured fields in generate_input_main.py; extend
  availability_parser.py to the canonical grammar and cover it with tests.
- Regenerate docs/parameters.yaml and input-main.md.

Former bare "label"-style tags (e.g. "OFDFT", "Numerical atomic orbital basis")
are now expressed as concrete conditions (esolver_type==ofdft, basis_type==lcao,
...) so they can be evaluated by validation/error tooling. mixing_tau has no hard
gate, so its availability is empty (always available); its meta-GGA relevance is
kept in the description.

* fix(input): enforce canonical availability metadata

* refactor(input): drop redundant python availability tooling

The strict C++ parse_availability() in Input_Item::set_availability() is now
the single source of truth for the availability grammar (it throws on any
non-canonical non-empty string). The legacy python classifier, its unit tests,
and the --check-availability report plumbing in generate_input_main.py were an
earlier design step and are no longer referenced by any workflow; remove them
to keep a single grammar implementation.

* fix(input): harden availability metadata

* docs(input): keep review context out of repository

* docs(input): generalize availability guide

* fix(input): validate availability prerequisites

* fix(input): quote multi-token availability values

* fix(input): standardize vector containment syntax

* fix(input): keep contains for vector availability

* fix(build): include availability objects in Makefile

* fix(input): align mixing_dmr availability

---------

Co-authored-by: Stardust0831 <169599847+Stardust0831@users.noreply.github.com>

Author: Stardust0831

docs/CONTRIBUTING.md

@@ -172,9 +172,12 @@ An practical example is class [LCAO_Deepks](https://github.com/deepmodeling/abac
 
 ## Documenting INPUT Parameters
 
-ABACUS includes a built-in help system that allows users to query INPUT parameters directly from the command line (e.g., `abacus -h ecutwfc`). Parameter metadata is defined inline in the C++ source files (`source/source_io/module_parameter/read_input_item_*.cpp`) using `Input_Item` registrations.
+ABACUS includes a built-in help system that allows users to query INPUT parameters directly from the command line (e.g., `abacus -h ecutwfc`). Parameter metadata is defined inline in the C++ source files under `source/source_io/module_parameter/` using `Input_Item` registrations.
 
-A checked-in file `docs/parameters.yaml` contains a YAML dump of all parameter metadata, generated from the binary itself. This file is used by Sphinx to produce the online documentation page `input-main.md`.
+The C++ `Input_Item` registrations are the source of truth for parameter metadata. The checked-in `docs/parameters.yaml` and `docs/advanced/input_files/input-main.md` files are generated artifacts: do not edit either file manually. `parameters.yaml` is generated from the binary and is used by Sphinx to produce `input-main.md`.
+
+Availability expressions follow the grammar and invariants in
+[`developers_guide/input_availability.md`](developers_guide/input_availability.md).
 
 ### When to Update `docs/parameters.yaml`
 
@@ -198,13 +201,13 @@ Then verify the YAML is valid:
 python3 -c "import yaml; d=yaml.safe_load(open('docs/parameters.yaml')); print(len(d['parameters']), 'parameters')"
 ```
 
-You can also regenerate the markdown documentation locally:
+Then regenerate the markdown documentation locally:
 
 ```bash
 python3 docs/generate_input_main.py docs/parameters.yaml --output docs/advanced/input_files/input-main.md
 ```
 
-**Important:** Include the updated `docs/parameters.yaml` and `input-main.md` in your commit when submitting a PR that modifies INPUT parameters. Reviewers should verify the YAML changes match the C++ source changes and the `input-main.md` is updated.
+**Important:** Include the updated `docs/parameters.yaml` and `input-main.md` in your commit when submitting a PR that modifies INPUT parameters. CI regenerates both files from the built binary and rejects any mismatch. Do not fix a documentation mismatch by editing either generated file; update the C++ `Input_Item` registration and regenerate them instead.
 
 ### Parameter Documentation Format
 
@@ -218,7 +221,7 @@ When adding or modifying INPUT parameters in C++ source, set the following field
     item.description = "Description of what this parameter does.";
     item.default_value = "0";
     item.unit = "Ry";          // Optional, empty string if no unit
-    item.availability = "";    // Optional, empty string if always available
+    item.set_availability("basis_type==pw"); // Optional; omit if always available
     // ... read_value, reset_value, check_value functions ...
     this->add_item(item);
 }

docs/advanced/input_files/input-main.md

@@ -220,6 +220,10 @@ or parsing behavior should include both:
 - `docs/parameters.yaml`
 - `docs/advanced/input_files/input-main.md`
 
+These files are generated artifacts, not additional sources of truth. Update
+the C++ `Input_Item` registrations and regenerate both files; do not edit the
+YAML or Markdown output by hand.
+
 If the diff touches parameter internals but does not change user-visible INPUT
 behavior, the PR should state why no documentation update is required. Missing
 documentation updates trigger a governance warning (not a block), but maintainers

docs/developers_guide/agent_governance.md

@@ -10,4 +10,5 @@ This section provides guidelines and resources for developers working on the ABA
    :caption: Developer Resources
 
    basic_types_class.md
+   input_availability.md
    agent_governance.md

docs/developers_guide/index.rst

@@ -0,0 +1,71 @@
+# Structured INPUT availability
+
+## Purpose
+
+Input item availability metadata describes when an INPUT parameter is
+applicable. It is used by documentation and tooling; it does not reject or
+alter a user's INPUT based on this condition. Runtime diagnostics, if added,
+must define how explicitly supplied parameters whose conditions are false are
+handled.
+
+## Invariants
+
+- The C++ `Input_Item` registration is the source of truth. YAML and Markdown
+  are generated artifacts.
+- Every non-empty registration is canonical. `set_availability()` rejects
+  syntax errors and non-canonical spelling.
+- The AST is the stored representation; the exported string is serialized from
+  it, so the two forms cannot diverge.
+- Every expression is a complete, independently evaluable predicate. It must
+  include enclosing requirements rather than inheriting them implicitly from a
+  referenced parameter.
+- After all INPUT items are registered, every referenced label, operator and
+  literal is checked against machine-readable parameter type information.
+
+## Grammar and meaning
+
+```text
+expression := or-expression
+or-expression := and-expression ("or" and-expression)*
+and-expression := primary (("and" | ",") primary)*
+primary := condition | "(" expression ")"
+condition := parameter comparison value
+           | parameter "in" "[" value "," value ("," value)* "]"
+           | parameter "contains" value
+comparison := "==" | "!=" | ">" | ">=" | "<" | "<="
+value := token | '"' quoted-value '"'
+```
+
+`and` binds more tightly than `or`. `==` compares one complete value; double
+quotes delimit a complete value containing whitespace, such as
+`relax_method=="cg 2"`. Two or more alternatives use `in [...]`, while
+`parameter contains value` tests whether a vector contains one element, such as
+`td_ttype contains 0`. `/` is an ordinary value character, not another spelling
+of membership. Ordered comparisons require a numeric scalar.
+
+A path that references a parameter must imply that parameter's availability.
+Every `and` operand is required, while satisfying either branch of an `or` is
+sufficient. Repeated `and` or `or` groups are order-independent. Different leaf
+conditions are not related; for example, `mode==a` does not satisfy
+`mode in [a, b]`.
+
+Examples:
+
+```cpp
+item.set_availability("basis_type==pw");
+item.set_availability("vdw_method in [d2, d3_0]");
+item.set_availability("td_ttype contains 2");
+item.set_availability("esolver_type==sdft and method_sto==2");
+```
+
+## Registration and validation workflow
+
+1. Parse and require canonical spelling in `set_availability()`.
+2. Finish registering all `Input_Item` objects.
+3. Validate referenced parameter names, operator compatibility, literal values, and that every referenced parameter carries its own enclosing requirements on the referencing path.
+4. Serialize the AST into `docs/parameters.yaml`.
+5. Generate `docs/advanced/input_files/input-main.md` from that YAML.
+
+Runtime evaluation is outside this metadata contract. Any implementation must
+define evaluation timing, treatment of defaults and reset values, and warning
+behavior for explicitly supplied parameters.

docs/developers_guide/input_availability.md

@@ -140,7 +140,28 @@ def format_description(desc: str) -> str:
     return result.strip()
 
 
-def generate_parameter_markdown(param: Dict[str, str]) -> str:
+def link_availability(availability: str, name_anchors: Dict[str, str]) -> str:
+    """
+    Link parameter names on the left side of a condition.
+
+    This deliberately recognizes the condition boundary instead of linking
+    every identifier: a value such as ``pw`` may happen to have the same name
+    as another parameter, but it is not a parameter reference.
+    """
+    def replace(match):
+        name = match.group(0)
+        anchor = name_anchors.get(name)
+        if anchor:
+            return f"[`{name}`]({anchor})"
+        return name
+    left_parameter = (
+        r'\b[A-Za-z_][A-Za-z0-9_]*\b'
+        r'(?=\s*(?:==|!=|>=|<=|>|<|\bin\b|\bcontains\b))'
+    )
+    return re.sub(left_parameter, replace, availability)
+
+def generate_parameter_markdown(param: Dict[str, str],
+                                name_anchors: Dict[str, str]) -> str:
     """
     Generate markdown for a single parameter.
     """
@@ -153,8 +174,9 @@ 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']))
-        lines.append(f"- **Availability**: *{availability_text}*")
+        lines.append("- **Availability**: *"
+                     + link_availability(str(param['availability']), name_anchors)
+                     + "*")
 
     # Description
     if param.get('description', '') != '':
@@ -184,14 +206,15 @@ def generate_parameter_markdown(param: Dict[str, str]) -> str:
     return '\n'.join(lines)
 
 
-def generate_category_markdown(category: str, params: List[Dict[str, str]]) -> str:
+def generate_category_markdown(category: str, params: List[Dict[str, str]],
+                                name_anchors: Dict[str, str]) -> str:
     """
     Generate markdown for a category section.
     """
     lines = [f"## {category}", ""]
 
     for param in params:
-        lines.append(generate_parameter_markdown(param))
+        lines.append(generate_parameter_markdown(param, name_anchors))
 
     # Keep legacy navigation aid used by downstream tooling/rendering.
     lines.append("[back to top](#full-list-of-input-keywords)")
@@ -266,6 +289,9 @@ def generate(yaml_path: Path, output: Path, verbose: bool = False):
         if cat not in sorted_categories:
             sorted_categories[cat] = by_category[cat]
 
+    name_anchors = {param['name']: '#' + generate_anchor(param['name'])
+                    for param in all_params}
+
     # Generate markdown
     md_parts = [
         "# Full List of INPUT Keywords",
@@ -281,7 +307,7 @@ def generate(yaml_path: Path, output: Path, verbose: bool = False):
     for category, params in sorted_categories.items():
         if verbose:
             print(f"Category '{category}': {len(params)} parameters")
-        md_parts.append(generate_category_markdown(category, params))
+        md_parts.append(generate_category_markdown(category, params, name_anchors))
 
     # Write output
     output_content = '\n'.join(md_parts)