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.

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.md
index 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.py
index 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 scalar
diff --git a/packages/core/src/repowise/core/code_origin.py b/packages/core/src/repowise/core/code_origin.py
index 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 True
if repo_root is None:
return False
parts = 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.py
index 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"