Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(health): class a docs site's code samples as docs examples (#2993)

Raghav Chamadiya78c8e1cc0d5e
diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.py
index fbc73d0de..37a043bc7 100644
--- a/packages/core/src/repowise/core/analysis/health/engine.py
+++ b/packages/core/src/repowise/core/analysis/health/engine.py
@@ -1445,6 +1445,7 @@ class HealthAnalyzer:
source,
is_test=bool(pf.file_info.is_test),
project=self._project(),
+ repo_root=self.repo_root,
)
def _installed(self, path: str) -> bool:
diff --git a/packages/core/src/repowise/core/code_origin.py b/packages/core/src/repowise/core/code_origin.py
index c2c60741f..f55ca80cb 100644
--- a/packages/core/src/repowise/core/code_origin.py
+++ b/packages/core/src/repowise/core/code_origin.py
@@ -24,6 +24,7 @@ a caller holding a bare path gets the same answer.
from __future__ import annotations
+import os
import re
from functools import cache, lru_cache
from itertools import pairwise
@@ -492,12 +493,83 @@ def _is_tool_example(name: str, dirs: list[str]) -> bool:
return _SOURCE_ROOT not in dirs[: dirs.index(example_dir)]
-def _is_docs_example(name: str, dirs: list[str]) -> bool:
+# A docs-named folder that is not plainly ``docs`` counts only with evidence:
+# a docs-site generator's config in it or one level down (Writerside keeps its
+# under ``Writerside/``). Without one it may be a shipped package.
+_DOCS_SITE_NAMES = frozenset({"doc", "documentation"})
+# ``documentation-website``, ``docs-site``: a suffixed name is as often a
+# service (``doc-service``, ``docs-api``), so it needs a generator-specific file.
+_DOCS_SITE_SUFFIXED_RE = re.compile(r"^(?:docs?|documentation)[-_.]")
+_DOCS_SITE_MARKERS = frozenset(
+ {
+ "writerside.cfg",
+ "mkdocs.yml",
+ "mkdocs.yaml",
+ "docusaurus.config.js",
+ "docusaurus.config.ts",
+ "docusaurus.config.mjs",
+ "book.toml", # mdBook
+ "antora.yml",
+ "docfx.json",
+ ".vitepress",
+ }
+)
+# Generic config names that mean a docs site only beside the site's own files,
+# and only under a plain ``doc`` / ``documentation`` folder.
+_DOCS_SITE_PAIRED_MARKERS: tuple[tuple[str, frozenset[str]], ...] = (
+ ("conf.py", frozenset({"index.rst", "index.md"})), # Sphinx
+ ("_config.yml", frozenset({"_posts", "_layouts"})), # Jekyll
+)
+
+
+def _has_docs_site_config(names: set[str], paired: bool) -> bool:
+ if names & _DOCS_SITE_MARKERS:
+ return True
+ return paired and any(
+ config in names and names & companions
+ for config, companions in _DOCS_SITE_PAIRED_MARKERS
+ )
+
+
+def _entry_names(folder: str) -> tuple[set[str], list[str]]:
+ """Lower-cased entry names in *folder*, and its subfolders' paths."""
+ try:
+ with os.scandir(folder) as entries:
+ listed = [(e.name.lower(), e.path, e.is_dir()) for e in entries]
+ except OSError:
+ return set(), []
+ return {name for name, _, _ in listed}, [path for _, path, is_dir in listed if is_dir]
+
+
+@lru_cache(maxsize=4096)
+def _is_docs_site(folder: str, paired: bool) -> bool:
+ """Whether *folder* (an absolute path) or a direct subfolder holds a
+ docs-site generator's config."""
+ names, subfolders = _entry_names(folder)
+ return _has_docs_site_config(names, paired) or any(
+ _has_docs_site_config(_entry_names(sub)[0], paired) for sub in subfolders
+ )
+
+
+def _is_docs_example(
+ normalized: str, dirs: list[str], repo_root: str | os.PathLike[str] | None
+) -> bool:
# Anything under a docs root already counts, examples beneath it included.
- return (
+ if (
any(d in _DOCS_ROOT_TOKENS for d in dirs)
or bool(dirs and _is_example_dir(dirs[0]))
- or _is_tool_example(name, dirs)
+ or _is_tool_example(normalized, dirs)
+ ):
+ return True
+ if repo_root is None:
+ return False
+ parts = normalized.split("/")
+ return any(
+ (d in _DOCS_SITE_NAMES or _DOCS_SITE_SUFFIXED_RE.match(d))
+ and _is_docs_site(
+ os.path.join(os.fspath(repo_root), *parts[: i + 1]), d in _DOCS_SITE_NAMES
+ )
+ for i, d in enumerate(dirs)
)
@@ -621,6 +693,7 @@ def code_origin(
*,
is_test: bool | None = None,
project: str | None = None,
+ repo_root: str | os.PathLike[str] | None = None,
) -> CodeOrigin:
"""The one origin of the file at repo-relative *path*.
@@ -634,6 +707,10 @@ def code_origin(
*project* is the repository's name, so its own release banner is not
taken for someone else's.
+
+ *repo_root* lets a docs-named folder other than ``docs`` count as docs
+ when it holds a docs-site generator's config. ``None`` skips that check,
+ so such a folder stays production and only the path rules apply.
"""
split = _split(path)
if split is None:
@@ -651,11 +728,15 @@ def code_origin(
and _third_party_header(header, project)
):
return "vendored"
- return _maintained_origin(normalized, name, dirs, is_test)
+ return _maintained_origin(normalized, name, dirs, is_test, repo_root)
def _maintained_origin(
- normalized: str, name: str, dirs: list[str], is_test: bool | None
+ normalized: str,
+ name: str,
+ dirs: list[str],
+ is_test: bool | None,
+ repo_root: str | os.PathLike[str] | None,
) -> CodeOrigin:
"""The origin of code this repository maintains: build, test, docs or
examples, tooling, or production, in that precedence."""
@@ -663,7 +744,7 @@ def _maintained_origin(
return "build"
if is_test if is_test is not None else is_test_related_path(normalized):
return "test"
- if _is_docs_example(name, dirs):
+ if _is_docs_example(normalized, dirs, repo_root):
return "docs_example"
if _is_tooling(name, dirs):
return "tooling"
diff --git a/tests/unit/test_code_origin.py b/tests/unit/test_code_origin.py
index 3b28e0b33..c7ce78048 100644
--- a/tests/unit/test_code_origin.py
+++ b/tests/unit/test_code_origin.py
@@ -480,3 +480,57 @@ def test_build_rs_under_src_is_a_dead_code_root_but_keeps_its_origin() -> None:
)
def test_deps_benchmarks_and_cargo_examples(path: str, expected: str) -> None:
assert code_origin(path) == expected
+
+
+def _docs_site(tmp_path, folder: str, marker: str) -> None:
+ (tmp_path / folder).mkdir(parents=True)
+ (tmp_path / folder / marker).write_text("")
+
+
+def test_docs_named_folder_with_a_site_config_is_docs(tmp_path) -> None:
+ _docs_site(tmp_path, "documentation-website/Writerside", "writerside.cfg")
+ _docs_site(tmp_path, "doc", "mkdocs.yml")
+ _docs_site(tmp_path, "web/docs-site", "docusaurus.config.ts")
+ snippet = "documentation-website/Writerside/snippets/dao/src/main/kotlin/Tables.kt"
+ assert code_origin(snippet, repo_root=tmp_path) == "docs_example"
+ assert code_origin("doc/gen.go", repo_root=tmp_path) == "docs_example"
+ assert code_origin("web/docs-site/src/a.ts", repo_root=tmp_path) == "docs_example"
+ # Without the repository root only the path rules apply.
+ assert code_origin(snippet) == "production"
+
+
+def test_docs_named_package_without_a_site_config_stays_production(tmp_path) -> None:
+ (tmp_path / "doc").mkdir()
+ (tmp_path / "doc" / "man_docs.go").write_text("package doc\n")
+ (tmp_path / "documentation" / "api").mkdir(parents=True)
+ (tmp_path / "documentation" / "api" / "handlers.go").write_text("")
+ _docs_site(tmp_path, "doctor", "mkdocs.yml") # not a docs name
+ assert code_origin("doc/man_docs.go", repo_root=tmp_path) == "production"
+ assert code_origin("documentation/api/handlers.go", repo_root=tmp_path) == "production"
+ assert code_origin("doctor/check.py", repo_root=tmp_path) == "production"
+
+
+ ("folder", "files", "path"),
+ [
+ ("doc-service/src", ("conf.py", "index.md"), "doc-service/src/conf.py"),
+ ("doc_utils", ("conf.py", "index.rst"), "doc_utils/conf.py"),
+ ("docs-api/app", ("conf.py", "_config.yml", "index.md"), "docs-api/app/conf.py"),
+ ("doc", ("conf.py",), "doc/conf.py"), # Sphinx needs its index beside conf.py
+ ("doc", ("_config.yml",), "doc/site.py"), # Jekyll needs _posts or _layouts
+ ],
+)
+def test_generic_config_names_are_not_docs_site_evidence(tmp_path, folder, files, path) -> None:
+ (tmp_path / folder).mkdir(parents=True)
+ for name in files:
+ (tmp_path / folder / name).write_text("")
+ assert code_origin(path, repo_root=tmp_path) == "production"
+
+
+def test_sphinx_and_jekyll_count_under_a_plain_doc_folder(tmp_path) -> None:
+ _docs_site(tmp_path, "doc/source", "conf.py")
+ (tmp_path / "doc" / "source" / "index.rst").write_text("")
+ _docs_site(tmp_path, "documentation", "_config.yml")
+ (tmp_path / "documentation" / "_layouts").mkdir()
+ assert code_origin("doc/source/ext/roles.py", repo_root=tmp_path) == "docs_example"
+ assert code_origin("documentation/plugins/x.rb", repo_root=tmp_path) == "docs_example"