Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(health): count a docs folder as docs only at the root or beside its site config (#4200)
Raghav Chamadiya8b6809c4644f
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.mdindex 56e94494d..fc571d535 100644--- a/docs/architecture/code-health.md+++ b/docs/architecture/code-health.md@@ -699,7 +699,7 @@ reason. These reasons and the performance default queue's are decided in one pla| Reason | What it leaves out ||---|---|-| `test`, `tooling`, `generated`, `vendored`, `docs_example` | Path-role classification. Tooling includes build files by type wherever they sit (Gradle, CMake, Makefiles, Bazel, MSBuild props/targets, root `setup.py`, `noxfile.py`, crate-root `build.rs`, bundler configs) |+| `test`, `tooling`, `generated`, `vendored`, `docs_example` | Path-role classification. Tooling includes build files by type wherever they sit (Gradle, CMake, Makefiles, Bazel, MSBuild props/targets, root `setup.py`, `noxfile.py`, crate-root `build.rs`, bundler configs). Docs means a root `docs/` or `docs_src/` tree, or one beside a docs-site config; a product's own `app/docs/` route is production || `unknown`, `expected`, `no_strategy`, `no_plan` | Performance causes with no classified context, expected repetition, no supported strategy, or no stored safe plan || `below_min_worth` | A refactoring recovering under `MIN_WORTH` (0.5) or with no steps; a loop-built string that is bounded or not in production || `history_only` | Only git-history findings |diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.pyindex 5b36553bb..ac808ce65 100644--- a/packages/core/src/repowise/core/analysis/health/engine.py+++ b/packages/core/src/repowise/core/analysis/health/engine.py@@ -98,6 +98,9 @@ log = structlog.get_logger(__name__)# Not a licence to move a calibrated scoring weight — those are frozen# independently of this stamp.#+# v41 (also): ``docs`` / ``docs_src`` count as a docs root only at the+# repository root or beside a docs-site generator's config, so a product's+# ``app/docs/`` route is production and stored ``code_origin`` is re-read.# v41: ``brain_method`` is advisory, so every stored score that carried one# moves. Parameter counts exclude every comment kind and discover C/C++# declarators and Kotlin lists; cached walks refresh the total, typed and scalardiff --git a/packages/core/src/repowise/core/code_origin.py b/packages/core/src/repowise/core/code_origin.pyindex 135c504ef..0752fb27d 100644--- a/packages/core/src/repowise/core/code_origin.py+++ b/packages/core/src/repowise/core/code_origin.py@@ -523,14 +523,13 @@ def is_build_file(path: str) -> bool:# Docs, examples, tooling# ---------------------------------------------------------------------------# Docs roots count at any depth. Docs are the plural and FastAPI's ``docs_src``-# only: a singular ``doc/`` is as often a shipped package (cobra's ``doc``-# generates man pages) as a documentation tree.+# Plural only: a singular ``doc/`` is as often a shipped package. Where they+# count is :func:`_is_docs_example`'s rule._DOCS_ROOT_TOKENS = frozenset({"docs", "docs_src"})# Examples as ``support_paths`` reads them, less the benchmark harnesses, which# run the system (tooling below). Unlike ``support_paths`` these count only as-# the first segment or directly under a docs root: ``src/pkg/examples/`` is-# as often shipped code (an example registry, a runner) as a sample.+# the first segment or under a docs root: ``src/pkg/examples/`` is as often+# shipped code (an example registry, a runner) as a sample._EXAMPLE_TOKENS = EXAMPLE_DIR_TOKENS - {"bench", "benches", "benchmarks"}_TUTORIAL_PREFIX = "tutorial"@@ -615,20 +614,28 @@ def _is_docs_site(folder: str, paired: bool) -> bool: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.+ """A docs root or example folder as the first segment, a build tool's example+ target, or a docs folder deeper beside a docs-site generator's config. A+ nested ``app/docs/`` with no such config is the product's own docs route."""if (- any(d in _DOCS_ROOT_TOKENS for d in dirs)- or bool(dirs and _is_example_dir(dirs[0]))+ bool(dirs and (dirs[0] in _DOCS_ROOT_TOKENS or _is_example_dir(dirs[0])))or _is_tool_example(normalized, dirs)):return Trueif repo_root is None:return Falseparts = normalized.split("/")+ root = os.fspath(repo_root)++ def site(i: int, paired: bool) -> bool:+ return _is_docs_site(os.path.join(root, *parts[:i]), paired)+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+ # A nested docs root beside its site's config, read from its parent.+ (d in _DOCS_ROOT_TOKENS and site(i, False))+ or (+ (d in _DOCS_SITE_NAMES or _DOCS_SITE_SUFFIXED_RE.match(d))+ and site(i + 1, d in _DOCS_SITE_NAMES))for i, d in enumerate(dirs))diff --git a/tests/unit/test_code_origin.py b/tests/unit/test_code_origin.pyindex 0cfa7baa3..77d407491 100644--- a/tests/unit/test_code_origin.py+++ b/tests/unit/test_code_origin.py@@ -63,6 +63,10 @@ _OWN_HEADER = (("src/tutorials/steps.py", "production"),("examples/a.py", "docs_example"),("docs/examples/a.py", "docs_example"),+ # A product's own docs routes ship; only a root docs tree is docs.+ ("app/docs/page.tsx", "production"),+ ("src/pages/docs/[slug].tsx", "production"),+ ("pkg/docs_src/handler.py", "production"),("examples/tutorial/app.py", "docs_example"),("example/main.go", "docs_example"),("samples/hello/Program.cs", "docs_example"),@@ -730,3 +734,12 @@ def test_cocoapods_target_support_files_are_generated() -> None:def test_a_first_party_pods_package_stays_production() -> None:assert code_origin("internal/k8s/pods/watcher.go") == "production"assert code_origin("pods/support/files.go") == "production"+++def test_a_nested_docs_root_counts_only_beside_its_site_config(tmp_path) -> None:+ _docs_site(tmp_path, "website", "docusaurus.config.js")+ (tmp_path / "website" / "docs").mkdir()+ (tmp_path / "app" / "docs").mkdir(parents=True)+ assert code_origin("website/docs/examples/a.ts", repo_root=tmp_path) == "docs_example"+ assert code_origin("app/docs/page.tsx", repo_root=tmp_path) == "production"+ assert code_origin("docs/guide/a.py", repo_root=tmp_path) == "docs_example"