feat: recognize historical README projects

scripts/readme_entries.py

@@ -13,6 +13,8 @@ BADGE_RE = re.compile(r"\s*!\[[^\]]*\]\([^)]*\)\s*")
 LANGUAGE_PREFIX_RE = re.compile(r"^((?:`[^`]+`\s*)+)-\s*(.*)$")
 GITHUB_LINK_RE = re.compile(r"\[GitHub\]\((https://github\.com/[\w-]+/[-\w.]+)\)")
 MARKDOWN_URL_RE = re.compile(r"\[[^\]]+\]\(([^)]+)\)")
+HISTORICAL_SECTION = "Historical & Archived Projects"
+HISTORICAL_TAG = "Historical"
 
 NO_LANGUAGE_REQUIRED_SECTIONS = {
     "Commercial & Proprietary Services",
@@ -39,6 +41,7 @@ VALID_SECTIONS = [
     "Cross-Language Frameworks",
     "Reproducing Works, Training & Books",
     "Commercial & Proprietary Services",
+    HISTORICAL_SECTION,
     "Related Lists",
 ]
 

scripts/validate_readme.py

@@ -24,6 +24,8 @@ from scripts.readme_entries import (
     ENTRY_RE,
     GITHUB_LINK_RE,
     HEADING_RE,
+    HISTORICAL_SECTION,
+    HISTORICAL_TAG,
     MARKDOWN_URL_RE,
     NO_LANGUAGE_REQUIRED_SECTIONS,
     VALID_SECTIONS,
@@ -138,6 +140,26 @@ def validate_entry(
             )
         )
 
+    if entry.section == HISTORICAL_SECTION:
+        if HISTORICAL_TAG not in entry.languages:
+            issues.append(
+                Issue(
+                    "error",
+                    line,
+                    "historical-tag",
+                    "Historical & Archived Projects entries must include the `Historical` tag",
+                )
+            )
+        if not any(tag != HISTORICAL_TAG for tag in entry.languages):
+            issues.append(
+                Issue(
+                    "error",
+                    line,
+                    "language",
+                    "Historical & Archived Projects entries require a language or runtime tag",
+                )
+            )
+
     if entry.languages:
         _languages, clean_description = extract_languages(entry.tail)
         if clean_description == entry.tail:

tests/test_historical_projects.py

@@ -0,0 +1,47 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from scripts.readme_entries import HISTORICAL_SECTION, iter_readme_entries
+from scripts.validate_readme import build_duplicate_indexes, validate_entry
+
+
+class HistoricalProjectContractTests(unittest.TestCase):
+    def validate_single_entry(self, line):
+        with tempfile.TemporaryDirectory() as directory:
+            readme = Path(directory) / "README.md"
+            readme.write_text(
+                f"## {HISTORICAL_SECTION}\n{line}\n",
+                encoding="utf-8",
+            )
+            entry = next(iter_readme_entries(readme))
+            names, urls = build_duplicate_indexes([entry])
+            return validate_entry(
+                entry,
+                duplicate_names=names,
+                duplicate_urls=urls,
+                strict_duplicates=True,
+                strict_urls=True,
+                strict_format=True,
+            )
+
+    def test_accepts_tagged_entry(self):
+        issues = self.validate_single_entry(
+            "- [Example](https://github.com/example/project) - "
+            "`Python` `Historical` - Archived example retained for its early design."
+        )
+        self.assertEqual(issues, [])
+
+    def test_requires_historical_tag(self):
+        issues = self.validate_single_entry(
+            "- [Example](https://github.com/example/project) - "
+            "`Python` - Archived example retained for its early design."
+        )
+        self.assertIn("historical-tag", {issue.code for issue in issues})
+
+    def test_requires_non_status_tag(self):
+        issues = self.validate_single_entry(
+            "- [Example](https://github.com/example/project) - "
+            "`Historical` - Archived example retained for its early design."
+        )
+        self.assertIn("language", {issue.code for issue in issues})