Feat.lint obsolete vars (cylc#5879)

* lint.warn about deprecated templating

* Update changes.d/5879.feat.md

Co-authored-by: Ronnie Dutta <[email protected]>

* Update cylc/flow/scripts/lint.py

Co-authored-by: Ronnie Dutta <[email protected]>

* Clarify templated vars which have to be set in metadata sections.
Fix an rst bug.

* fix broken code

---------

Co-authored-by: Ronnie Dutta <[email protected]>

changes.d/5879.feat.md

@@ -0,0 +1 @@
+`cylc lint` now warns of use of old templated items such as `%(suite)s`

cylc/flow/scripts/lint.py

@@ -67,7 +67,7 @@
         TOMLDecodeError,
     )
 from typing import (
-    TYPE_CHECKING, Any, Callable, Dict, Iterator, List, Union)
+    TYPE_CHECKING, Any, Callable, Dict, Iterator, List, Optional, Union)
 
 from cylc.flow import LOG
 from cylc.flow.exceptions import CylcError
@@ -106,6 +106,31 @@
 }
 
 
+DEPRECATED_STRING_TEMPLATES = {
+    'suite': 'workflow',
+    'suite_uuid': 'uuid',
+    'batch_sys_name': 'job_runner_name',
+    'batch_sys_job_id': 'job_id',
+    'user@host': 'platform_name',
+    'task_url': '``URL`` (if set in :cylc:conf:`[meta]URL`)',
+    'workflow_url': (
+        '``workflow_URL`` (if set in '
+        ':cylc:conf:`[runtime][<namespace>][meta]URL`)'),
+}
+
+
+LIST_ITEM = '    * '
+
+
+deprecated_string_templates = {
+    key: (
+        re.compile(r'%\(' + key + r'\)s'),
+        value
+    )
+    for key, value in DEPRECATED_STRING_TEMPLATES.items()
+}
+
+
 def check_jinja2_no_shebang(
     line: str,
     file: Path,
@@ -233,6 +258,36 @@ def check_for_obsolete_environment_variables(line: str) -> List[str]:
     return [i for i in OBSOLETE_ENV_VARS if i in line]
 
 
+def check_for_deprecated_task_event_template_vars(
+    line: str
+) -> Optional[Dict[str, str]]:
+    """Look for string variables which are no longer supported
+
+    Examples:
+        >>> this = check_for_deprecated_task_event_template_vars
+
+        >>> this('hello = "My name is %(suite)s"')
+        {'list': '    * %(suite)s ⇒ %(workflow)s'}
+
+        >>> expect = {'list': (
+        ...     '    * %(suite)s ⇒ %(workflow)s    * %(task_url)s'
+        ... ' - get ``URL`` (if set in :cylc:conf:`[meta]URL`)')}
+        >>> this('hello = "My name is %(suite)s, %(task_url)s"') == expect
+        True
+    """
+    result = []
+    for key, (regex, replacement) in deprecated_string_templates.items():
+        search_outcome = regex.findall(line)
+        if search_outcome and ' ' in replacement:
+            result.append(f'%({key})s - get {replacement}')
+        elif search_outcome:
+            result.append(f'%({key})s ⇒ %({replacement})s')
+
+    if result:
+        return {'list': LIST_ITEM + LIST_ITEM.join(result)}
+    return None
+
+
 INDENTATION = re.compile(r'^(\s*)(.*)')
 
 
@@ -584,6 +639,23 @@ def check_indentation(line: str) -> bool:
         ),
         FUNCTION: re.compile(r'rose +date').findall,
     },
+    'U015': {
+        'short': (
+            'Deprecated template variables.'),
+        'rst': (
+            'The following template variables, mostly used in event handlers,'
+            'are deprecated, and should be replaced:'
+            + ''.join([
+                f'\n * ``{old}`` ⇒ {new}'
+                for old, new in DEPRECATED_STRING_TEMPLATES.items()
+            ])
+        ),
+        'url': (
+            'https://cylc.github.io/cylc-doc/stable/html/user-guide/'
+            'writing-workflows/runtime.html#task-event-template-variables'
+        ),
+        FUNCTION: check_for_deprecated_task_event_template_vars,
+    }
 }
 RULESETS = ['728', 'style', 'all']
 EXTRA_TOML_VALIDATION = {
@@ -1077,7 +1149,7 @@ def get_cylc_files(
     'section heading': '\n{title}\n{underline}\n',
     'issue heading': {
         'text': '\n{check}:\n    {summary}\n    {url}\n\n',
-        'rst': '\n`{check} <{url}>`_\n{underline}\n{summary}\n\n',
+        'rst': '\n{url}_\n{underline}\n{summary}\n\n',
     },
     'auto gen message': (
         'U998 and U999 represent automatically generated'
@@ -1122,16 +1194,17 @@ def get_reference(linter, output_type):
                 output += '\n'
             output += '\n* ' + summary
         else:
+            check = get_index_str(meta, index)
             template = issue_heading_template
             url = get_url(meta)
+            if output_type == 'rst':
+                url = f'`{check} <{url}>`' if url else f'{check}'
             msg = template.format(
                 title=index,
-                check=get_index_str(meta, index),
+                check=check,
                 summary=summary,
                 url=url,
-                underline=(
-                    len(get_index_str(meta, index)) + len(url) + 6
-                ) * '^'
+                underline=(len(url) + 1) * '^'
             )
             output += msg
     output += '\n'

tests/unit/scripts/test_lint.py

@@ -119,7 +119,7 @@
             submission failed handler = giaSEHFUIHJ
             failed handler = woo
             execution timeout handler = sdfghjkl
-            expired handler = dafuhj
+            expired handler = %(suite_uuid)s %(user@host)s
             late handler = dafuhj
             submitted handler = dafuhj
             started handler = dafuhj