(Discussion/Proposals) Consistency regarding annotations of header-implemented functions (#316)

* Open discussion

* Move annotations of header-implemented functions back to `.h` files

* Adjust `README.md`

* Relocate annotation

* linter

* Comment markers in headers only, rename script, update github actions

* type hint compat

* Rename github action, better argparse for linter

* Type hints, working test for byname ignore

* Move annotation

* CI rename and enable warnfail, enforce mode always on

* Two step linting

* or one step

* continue on error

* two jobs instead

* Fixes

---------

Co-authored-by: disinvite <disinvite@users.noreply.github.com>

tools/isledecomp/tests/test_linter.py

@@ -0,0 +1,85 @@
+import pytest
+from isledecomp.parser import DecompLinter
+from isledecomp.parser.error import ParserError
+
+
+@pytest.fixture(name="linter")
+def fixture_linter():
+    return DecompLinter()
+
+
+def test_simple_in_order(linter):
+    lines = [
+        "// FUNCTION: TEST 0x1000",
+        "void function1() {}",
+        "// FUNCTION: TEST 0x2000",
+        "void function2() {}",
+        "// FUNCTION: TEST 0x3000",
+        "void function3() {}",
+    ]
+    assert linter.check_lines(lines, "test.cpp", "TEST") is True
+
+
+def test_simple_not_in_order(linter):
+    lines = [
+        "// FUNCTION: TEST 0x1000",
+        "void function1() {}",
+        "// FUNCTION: TEST 0x3000",
+        "void function3() {}",
+        "// FUNCTION: TEST 0x2000",
+        "void function2() {}",
+    ]
+    assert linter.check_lines(lines, "test.cpp", "TEST") is False
+    assert len(linter.alerts) == 1
+
+    assert linter.alerts[0].code == ParserError.FUNCTION_OUT_OF_ORDER
+    # N.B. Line number given is the start of the function, not the marker
+    assert linter.alerts[0].line_number == 6
+
+
+def test_byname_ignored(linter):
+    """Should ignore lookup-by-name markers when checking order."""
+    lines = [
+        "// FUNCTION: TEST 0x1000",
+        "void function1() {}",
+        "// FUNCTION: TEST 0x3000",
+        "// MyClass::MyMethod",
+        "// FUNCTION: TEST 0x2000",
+        "void function2() {}",
+    ]
+    # This will fail because byname lookup does not belong in the cpp file
+    assert linter.check_lines(lines, "test.cpp", "TEST") is False
+    # but it should not fail for function order.
+    assert all(
+        alert.code != ParserError.FUNCTION_OUT_OF_ORDER for alert in linter.alerts
+    )
+
+
+def test_module_isolation(linter):
+    """Should check the order of markers from a single module only."""
+    lines = [
+        "// FUNCTION: ALPHA 0x0001",
+        "// FUNCTION: TEST 0x1000",
+        "void function1() {}",
+        "// FUNCTION: ALPHA 0x0002",
+        "// FUNCTION: TEST 0x2000",
+        "void function2() {}",
+        "// FUNCTION: ALPHA 0x0003",
+        "// FUNCTION: TEST 0x3000",
+        "void function3() {}",
+    ]
+
+    assert linter.check_lines(lines, "test.cpp", "TEST") is True
+    assert linter.check_lines(lines, "test.cpp", "ALPHA") is True
+
+
+def test_byname_headers_only(linter):
+    """Markers that ar referenced by name with cvdump belong in header files only."""
+    lines = [
+        "// FUNCTION: TEST 0x1000",
+        "// MyClass::~MyClass",
+    ]
+
+    assert linter.check_lines(lines, "test.h", "TEST") is True
+    assert linter.check_lines(lines, "test.cpp", "TEST") is False
+    assert linter.alerts[0].code == ParserError.BYNAME_FUNCTION_IN_CPP