first steps to better scanning of repos

src/repo_registry/candidate_graph/generator.py

@@ -63,7 +63,8 @@ class CandidateGraphGenerator:
             return []
         chunks = chunks or []
 
-        docs = self._facts(facts, "documentation")
+        scope_docs = self._facts(facts, "scope")
+        docs = scope_docs + self._facts(facts, "documentation")
         tests = self._facts(facts, "test")
         examples = self._facts(facts, "example")
         interfaces = self._facts(facts, "interface")
@@ -660,8 +661,8 @@ class CandidateGraphGenerator:
         return f"Support {self._humanize_identifier(repository.name)}"
 
     def _document_purpose_sentence(self, chunks: list[ContentChunk]) -> str:
-        for chunk in chunks:
-            if chunk.kind != "documentation":
+        for chunk in self._documentation_chunks(chunks):
+            if chunk.kind not in {"scope", "documentation"}:
                 continue
             lines = [line.strip() for line in chunk.text.splitlines() if line.strip()]
             paragraph = next((line for line in lines if not line.startswith("#")), "")
@@ -731,9 +732,7 @@ class CandidateGraphGenerator:
         )
 
     def _document_summary(self, chunks: list[ContentChunk]) -> str:
-        for chunk in chunks:
-            if chunk.kind != "documentation":
-                continue
+        for chunk in self._documentation_chunks(chunks):
             lines = [line.strip() for line in chunk.text.splitlines() if line.strip()]
             if not lines:
                 continue
@@ -744,6 +743,12 @@ class CandidateGraphGenerator:
             return heading or paragraph
         return ""
 
+    def _documentation_chunks(self, chunks: list[ContentChunk]) -> list[ContentChunk]:
+        return sorted(
+            [chunk for chunk in chunks if chunk.kind in {"scope", "documentation"}],
+            key=lambda chunk: (0 if chunk.kind == "scope" else 1, chunk.path, chunk.start_line),
+        )
+
     def _interface_summary(self, chunks: list[ContentChunk]) -> str:
         for chunk in chunks:
             if chunk.kind != "interface":