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(generation): folder documentation floors with --folder-coverage (#2040)

Nehal Kf71bbcf7cd0a
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index f7f603a61..adc493f21 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -116,6 +116,7 @@ Workspaces add repo scanning, per-repo indexing, cross-repo analysis (co-changes
| `--language` | `en`, `ar`, `de`, `es`, `fr`, `hi`, `it`, `ja`, `ko`, `nl`, `pl`, `pt`, `ru`, `tr`, `zh`. Saved for `update`. Code, paths, symbols untranslated. Advanced mode asks. Switch: `init --force`. | `en` |
| `--onboarding` / `--no-onboarding` | Onboarding collection (up to 8 pages); see notes. | on |
| `--max-file-pages` | File-page cap by importance; `0`: no cap, a page per eligible file. Saved to `config.yaml`. | size policy (Page volume) |
+| `--folder-coverage` | `GLOB=PCT` file-page floor for a folder, repeatable: `src/core=1.0` gives every eligible file under `src/core` a page whatever the cap. Adds pages, never displaces. Saved as `folder_coverage` in `config.yaml`. | none |
| `--test-run` | Model docs for top 10 files by PageRank. Not with `--no-prose` or `--mode fast`. | off |
| `--dry-run` | Plan and cost estimate; no wiki. | off |
| `--exclude` / `-x` | Gitignore-style pattern. Repeatable. | |
diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.md
index 39c8a3b38..4e3bdfde1 100644
--- a/docs/reference/CONFIG.md
+++ b/docs/reference/CONFIG.md
@@ -53,6 +53,7 @@ wiki_style: comprehensive
language: en
enable_onboarding: true
max_file_pages: 2000
+folder_coverage: ["src/core=1.0", "src/legacy=0.5"]
exclude_patterns: [vendor/, "*.generated.*", proto/]
distill: {enabled: true}
mcp: {tools: ["+get_execution_flows", "-get_dead_code"]}
@@ -73,6 +74,7 @@ mcp: {tools: ["+get_execution_flows", "-get_dead_code"]}
| `language` | `en` | Wiki output language: `en`, `ar`, `de`, `es`, `fr`, `hi`, `it`, `ja`, `ko`, `nl`, `pl`, `pt`, `ru`, `tr`, `zh`. |
| `enable_onboarding` | `true` | First-run onboarding prompts (CLI and web). |
| `max_file_pages` | unset | Most file pages per run, highest importance first; see [below](#max_file_pages). |
+| `folder_coverage` | `[]` | File-page floors per folder as `"GLOB=PCT"` strings; see [below](#folder_coverage). |
| `forges.hosts` | `{}` | Self-managed git host to forge (`github`, `gitlab`, `azure`, `bitbucket`, `generic`); see [GIT_HOSTS.md](../start/GIT_HOSTS.md#self-managed-hosts). |
Blocks, each with its own section: [`generation_context`](#grounded-generation-context),
@@ -123,6 +125,15 @@ Applies to documentation-generation calls on reasoning-capable chat models.
`generate` honour the recorded value.
- File pages are rendered from structure, so a cap does not reduce model spend.
+### `folder_coverage`
+
+- `"src/core=1.0"` gives every eligible code file under `src/core` a file page
+ whatever its importance or the cap; `"src/legacy=0.5"` gives the top half.
+- A floor, not a cap: pinned files are added to the selection and never
+ displace a global pick, so the estimate rises with them.
+- `init --folder-coverage GLOB=PCT` (repeatable) sets it. Every run reads it,
+ and editing it re-renders the wiki on the next `update`.
+
### `wiki_style`
- Set with `init --wiki-style`, or `repowise restyle <style>`, which also
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/_finish.py b/packages/cli/src/repowise/cli/commands/init_cmd/_finish.py
index 0b15c3eec..1c9195375 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/_finish.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/_finish.py
@@ -89,6 +89,10 @@ def save_run_config(run: InitRun) -> None:
if run.max_file_pages is not None and run.max_file_pages != run.config.get("max_file_pages"):
save_config_partial(repo_path, max_file_pages=run.max_file_pages)
+ # Folder floors (#633): an override is recorded, the default stays unwritten.
+ if opts.folder_coverage_rules:
+ save_config_partial(repo_path, folder_coverage=list(opts.folder_coverage_rules))
+
# Written before the config fingerprint. A template wiki has no style or
# language, and recording one would make `restyle` skip it.
if opts.wiki_style != DEFAULT_STYLE and not run.effective_index_only:
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/_generate.py b/packages/cli/src/repowise/cli/commands/init_cmd/_generate.py
index 48c73fb5f..4cfcc972c 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/_generate.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/_generate.py
@@ -22,6 +22,8 @@ from .generation import (
cost_gate_declined,
embedding_note,
estimate_generation,
+ folder_coverage_lines,
+ folder_coverage_override,
page_type_label,
run_repo_generation,
structural_page_summary,
@@ -39,6 +41,7 @@ def _print_structural_plan(
max_file_pages: int | None,
skip_tests: bool,
skip_infra: bool,
+ folder_coverage_rules: tuple[str, ...] = (),
) -> None:
"""The plan a dry run owes the deterministic branch.
@@ -58,6 +61,7 @@ def _print_structural_plan(
enable_onboarding=onboarding,
wiki_style=wiki_style,
max_file_pages=max_file_pages,
+ **folder_coverage_override(folder_coverage_rules),
)
kg_modules = getattr(getattr(result, "knowledge_graph_result", None), "modules", None) or None
plans = build_generation_plan(
@@ -79,6 +83,8 @@ def _print_structural_plan(
table.add_section()
table.add_row("[bold]Total[/bold]", f"[bold]{total:,}[/bold]")
console.print(table)
+ for line in folder_coverage_lines(plans):
+ console.print(f" [dim]{line}[/dim]")
console.print(" Dry run: every page above is built from code. No documentation written.")
@@ -97,6 +103,7 @@ def _run_deterministic_generation_phase(
resume: bool,
timings: Any | None = None,
warnings: list[str] | None = None,
+ folder_coverage_rules: tuple[str, ...] = (),
) -> str:
"""Render the whole wiki from templates, for ``init --index-only``.
@@ -147,6 +154,7 @@ def _run_deterministic_generation_phase(
enable_onboarding=onboarding,
wiki_style=wiki_style,
max_file_pages=max_file_pages,
+ **folder_coverage_override(folder_coverage_rules),
)
run_repo_generation(
repo_path=repo_path,
@@ -205,6 +213,8 @@ def _print_generation_plan(
f"[bold]{model_pages:,} by model, {est.total_pages - model_pages:,} from code[/bold]",
)
console.print(table)
+ for line in folder_coverage_lines(est.plans):
+ console.print(f" [dim]{line}[/dim]")
# Language breakdown
lang_dist = result.repo_structure.root_language_distribution
@@ -251,6 +261,7 @@ def _run_generation_phase(
test_run: bool,
timings: Any | None = None,
warnings: list[str] | None = None,
+ folder_coverage_rules: tuple[str, ...] = (),
) -> tuple[bool, bool]:
"""Run the LLM generation phase for a single-repo init.
@@ -276,6 +287,7 @@ def _run_generation_phase(
enable_onboarding=onboarding,
wiki_style=wiki_style,
max_file_pages=max_file_pages,
+ **folder_coverage_override(folder_coverage_rules),
)
plans, est = estimate_generation(
result=result,
@@ -347,6 +359,7 @@ def _render_template_wiki(run: InitRun, *, embedder_was_requested: bool) -> None
onboarding=opts.onboarding,
wiki_style=opts.wiki_style,
max_file_pages=run.max_file_pages,
+ folder_coverage_rules=opts.folder_coverage_rules,
embedder_name_resolved=run.embedder_name_resolved,
embedder_was_requested=embedder_was_requested,
resume=opts.resume,
@@ -369,6 +382,7 @@ def _generate_with_model(run: InitRun) -> bool:
onboarding=opts.onboarding,
wiki_style=opts.wiki_style,
max_file_pages=run.max_file_pages,
+ folder_coverage_rules=opts.folder_coverage_rules,
yes=opts.yes,
dry_run=opts.dry_run,
skip_tests=opts.skip_tests,
@@ -428,6 +442,7 @@ def _generate(run: InitRun) -> bool:
onboarding=opts.onboarding,
wiki_style=opts.wiki_style,
max_file_pages=run.max_file_pages,
+ folder_coverage_rules=opts.folder_coverage_rules,
skip_tests=opts.skip_tests,
skip_infra=opts.skip_infra,
)
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/_options.py b/packages/cli/src/repowise/cli/commands/init_cmd/_options.py
index 6608b3141..be4e1a3b1 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/_options.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/_options.py
@@ -60,6 +60,8 @@ class InitOptions:
no_cost_tracking: bool
verbose: bool
progress: str
+ # Raw ``GLOB=PCT`` rules, validated by the option callback.
+ folder_coverage_rules: tuple[str, ...] = ()
@dataclass
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
index d80f61620..356f965d2 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
@@ -20,6 +20,7 @@ from repowise.cli.errors import reasoned_error
from repowise.cli.exit_codes import EXIT_CODES_HELP
from repowise.cli.helpers import resolve_repo_path
from repowise.core.analysis.health.coverage import PARSERS as COVERAGE_PARSERS
+from repowise.core.generation.folder_coverage import parse_folder_coverage
from repowise.core.generation.languages import SUPPORTED_LANGUAGES
from repowise.core.generation.styles import list_styles, resolve_style
from repowise.core.reasoning import REASONING_MODES
@@ -117,6 +118,17 @@ def _run_workspace_init(opts: InitOptions, scan: Any) -> None:
)
+def _check_folder_coverage(
+ _ctx: click.Context, param: click.Parameter, value: tuple[str, ...]
+) -> tuple[str, ...]:
+ """Reject a malformed ``--folder-coverage`` rule before any indexing starts."""
+ try:
+ parse_folder_coverage(value)
+ except ValueError as exc:
+ raise click.BadParameter(str(exc), param=param) from None
+ return value
+
+
@click.command("init", epilog=EXIT_CODES_HELP)
@click.argument("path", required=False, default=None)
@click.option(
@@ -403,6 +415,19 @@ def _run_workspace_init(opts: InitOptions, scan: Any) -> None:
"Saved to config.yaml so later runs keep it."
),
)
+ "--folder-coverage",
+ "folder_coverage_rules",
+ multiple=True,
+ metavar="GLOB=PCT",
+ callback=_check_folder_coverage,
+ help=(
+ "Documentation floor for a folder: 'src/core=1.0' promises every code "
+ "file under src/core gets a file page whatever its importance score; "
+ "'src/legacy=0.5' promises half. Repeatable. Saved to config.yaml so "
+ "later update runs keep the floors."
+ ),
+)
@click.option(
"--coverage-report",
"coverage_report",
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/generation.py b/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
index 72b87f1a0..577fb90ec 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
@@ -158,6 +158,24 @@ def page_type_label(page_type: str) -> str:
return _ROW_LABELS.get(page_type) or page_type.replace("_", " ").capitalize()
+def folder_coverage_override(rules: tuple[str, ...]) -> dict[str, Any]:
+ """``--folder-coverage`` as a GenerationConfig override; absent, config.yaml decides."""
+ if not rules:
+ return {}
+ from repowise.core.generation.folder_coverage import parse_folder_coverage
+
+ return {"folder_coverage": parse_folder_coverage(rules)}
+
+
+def folder_coverage_lines(plans: list[Any]) -> list[str]:
+ """One ``src/core: 12 of 12 files get a page`` line per folder floor (#633)."""
+ return [
+ f"{glob}: {documented:,} of {eligible:,} files get a page"
+ for plan in plans
+ for glob, documented, eligible in getattr(plan, "folder_coverage", None) or []
+ ]
+
+
def structural_page_summary(plans: list[Any]) -> str:
"""Return e.g. ``"3622 pages rendered from structure, free: 2947 file, ..."``.
diff --git a/packages/core/src/repowise/core/cost_estimator/plans.py b/packages/core/src/repowise/core/cost_estimator/plans.py
index 05468ca5a..9bafd3ffa 100644
--- a/packages/core/src/repowise/core/cost_estimator/plans.py
+++ b/packages/core/src/repowise/core/cost_estimator/plans.py
@@ -94,6 +94,9 @@ def build_generation_plan(
page_type=page_type,
count=count,
level=GENERATION_LEVELS[page_type],
+ folder_coverage=(
+ selection.folder_coverage if page_type == "file_page" else []
+ ),
)
)
diff --git a/packages/core/src/repowise/core/cost_estimator/types.py b/packages/core/src/repowise/core/cost_estimator/types.py
index b59e7d2e9..ce103a6fe 100644
--- a/packages/core/src/repowise/core/cost_estimator/types.py
+++ b/packages/core/src/repowise/core/cost_estimator/types.py
@@ -12,6 +12,8 @@ class PageTypePlan:
page_type: str
count: int
level: int
+ # file_page only: ``(glob, documented, eligible)`` per folder-coverage rule.
+ folder_coverage: list[tuple[str, int, int]] = field(default_factory=list)
@dataclass
diff --git a/packages/core/src/repowise/core/generation/folder_coverage.py b/packages/core/src/repowise/core/generation/folder_coverage.py
new file mode 100644
index 000000000..c561dfb14
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/folder_coverage.py
@@ -0,0 +1,78 @@
+"""Folder-coverage rule parsing for GenerationConfig (issue #633).
+
+``folder_coverage`` in .repowise/config.yaml is a list of ``"<glob>=<pct>"``
+strings, e.g.::
+
+ folder_coverage:
+ - "src/core=1.0"
+ - "src/legacy=0.5"
+
+The flag sugar ``--folder-coverage "src/core=1.0"`` (repeatable) maps onto
+the same list. Each rule promises at least ``pct`` of the code files under
+*glob* get a file_page.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+_STR = str
+
+
+def parse_folder_coverage(
+ raw: Any,
+) -> tuple[tuple[str, float], ...]:
+ """Validate and normalize ``folder_coverage`` into ``((glob, pct), ...)``.
+
+ Accepts a list of ``"glob=pct"`` strings (the config.yaml and CLI shape),
+ or a sequence of ``(glob, pct)`` pairs for direct construction. Bad rules
+ raise with the offending entry named, matching the strictness of
+ ``source_evidence_files`` — a typo should fail loudly, not silently drop
+ the folder the user explicitly asked to document.
+ """
+ if raw is None:
+ return ()
+ if isinstance(raw, _STR) or not isinstance(raw, Iterable):
+ raise ValueError(
+ "folder_coverage must be a list of 'glob=pct' strings, "
+ "e.g. 'src/core=1.0'"
+ )
+
+ rules: list[tuple[str, float]] = []
+ for entry in raw:
+ glob_pattern, pct_raw = _split_entry(entry)
+ # Repo paths are relative, so the issue's "./src/core" means "src/core".
+ glob_pattern = glob_pattern.strip().strip('"').strip("'").removeprefix("./")
+ if not glob_pattern:
+ raise ValueError("folder_coverage entries need a non-empty glob")
+ if isinstance(pct_raw, _STR):
+ pct_raw = pct_raw.strip().strip('"').strip("'")
+ try:
+ pct = float(pct_raw)
+ except (TypeError, ValueError):
+ raise ValueError(
+ f"folder_coverage entry {entry!r}: {pct_raw!r} is not a number"
+ ) from None
+ if not 0 <= pct <= 1: # also rejects nan
+ raise ValueError(
+ f"folder_coverage entry {entry!r}: pct must be in [0, 1]"
+ )
+ rules.append((glob_pattern, pct))
+ return tuple(rules)
+
+
+def _split_entry(entry: Any) -> tuple[str, Any]:
+ """``(glob, raw pct)`` from a ``"glob=pct"`` string or a ``(glob, pct)`` pair."""
+ if isinstance(entry, (tuple, list)) and len(entry) == 2:
+ glob_pattern, pct_raw = entry
+ if not isinstance(glob_pattern, _STR):
+ raise ValueError(f"folder_coverage entry {entry!r}: the glob must be a string")
+ return glob_pattern, pct_raw
+ if isinstance(entry, _STR) and "=" in entry:
+ glob_pattern, _, pct_raw = entry.partition("=")
+ return glob_pattern, pct_raw
+ raise ValueError(
+ f"folder_coverage entry {entry!r} must be 'glob=pct' "
+ "(e.g. 'src/core=1.0') or a (glob, pct) pair"
+ )
diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.py
index d2a6d0643..282d46056 100644
--- a/packages/core/src/repowise/core/generation/models.py
+++ b/packages/core/src/repowise/core/generation/models.py
@@ -263,6 +263,13 @@ class GenerationConfig:
# structure and cost no tokens -- it reduces pages, bytes, embedding calls
# and retrieval dilution.
max_file_pages: int | None = None
+ # Folder-specific documentation floors: ``((glob, pct), ...)`` where each
+ # rule promises that at least ``pct`` of the code files under *glob* get a
+ # file_page, whatever their global importance score. A floor, not a cap:
+ # the pinned files are unioned into the selection additively and never
+ # displace global picks. ``src/core=1.0`` means every code file under
+ # src/core gets a page regardless of its score (issue #633).
+ folder_coverage: tuple[tuple[str, float], ...] = field(default_factory=tuple)
file_page_min_symbols: int = 1
skip_trivial_files: bool = True
dedupe_near_clones: bool = True
@@ -388,6 +395,12 @@ class GenerationConfig:
raw_files, label="generation_context.files"
)
+ raw_folder_coverage = config.get("folder_coverage")
+ if raw_folder_coverage is not None:
+ from .folder_coverage import parse_folder_coverage
+
+ values["folder_coverage"] = parse_folder_coverage(raw_folder_coverage)
+
values.update(overrides)
return cls(**values)
diff --git a/packages/core/src/repowise/core/generation/selection/selector.py b/packages/core/src/repowise/core/generation/selection/selector.py
index 2bb55a00c..b79d4eecd 100644
--- a/packages/core/src/repowise/core/generation/selection/selector.py
+++ b/packages/core/src/repowise/core/generation/selection/selector.py
@@ -148,6 +148,8 @@ class Selection:
# cap that actually sliced it. These are reporting facts, not selectors.
eligible_file_pages: int = 0
effective_file_page_cap: int | None = None
+ # ``(glob, documented, eligible)`` per folder-coverage rule (issue #633).
+ folder_coverage: list[tuple[str, int, int]] = field(default_factory=list)
def counts(self) -> dict[str, int]:
"""Per-page-type counts of the pages this run will emit.
@@ -356,10 +358,19 @@ def _passes_importance_floor(parsed: Any) -> bool:
# ---------------------------------------------------------------------------
-def _build_file_candidates(
+def _score_code_files(
inputs: SelectionInputs,
-) -> tuple[list[tuple[float, str]], int, int | None]:
- """Return ``[(score, file_path), ...]`` for code files, descending."""
+) -> list[tuple[float, str]]:
+ """Return ``[(score, file_path), ...]`` for code files, descending, uncapped.
+
+ The folder-coverage pins (issue #633) need the *whole* code-file set under
+ a glob — files that score below the global cutoff must still be pinnable —
+ so the scoring is separated from the global cap. ``select_pages`` calls
+ this once and derives both the capped selection and the uncapped pin
+ candidates from the same ranking, so the two can never disagree.
+ ``_build_file_candidates`` is this + the global cap, kept for its other
+ callers.
+ """
max_pr = max(inputs.pagerank.values(), default=0.0)
max_bet = max(inputs.betweenness.values(), default=0.0)
git = inputs.git_meta_map or {}
@@ -385,6 +396,21 @@ def _build_file_candidates(
if s > 0.0:
scored.append((s, path))
scored.sort(key=lambda x: (-x[0], x[1]))
+ return scored
+
+
+def _build_file_candidates(
+ inputs: SelectionInputs,
+ *,
+ scored: list[tuple[float, str]] | None = None,
+) -> tuple[list[tuple[float, str]], int, int | None]:
+ """Return the capped ranking plus ``(eligible, effective_cap)``.
+
+ ``scored`` lets ``select_pages`` hand in the ranking it already holds, so
+ the cap and the folder-coverage pins slice the same list.
+ """
+ if scored is None:
+ scored = _score_code_files(inputs)
# Three states, because "how many file pages" has three real answers.
#
# unset (None) -> the volume policy decides: untouched below the automatic
@@ -876,7 +902,11 @@ def select_pages(inputs: SelectionInputs) -> Selection:
Deterministic given identical inputs. Safe to call from both the generator
and the cost estimator.
"""
- files, eligible_file_pages, effective_file_page_cap = _build_file_candidates(inputs)
+ scored_files = _score_code_files(inputs)
+ files, eligible_file_pages, effective_file_page_cap = _build_file_candidates(
+ inputs, scored=scored_files
+ )
+
symbols = _build_symbol_candidates(inputs)
concepts = _build_module_groups(inputs)
modules = concepts.scored
@@ -884,8 +914,21 @@ def select_pages(inputs: SelectionInputs) -> Selection:
infras = _build_infra_candidates(inputs)
sccs = _build_scc_candidates(inputs)
+ selected_paths = [p for _, p in files]
+ # Folder-specific documentation floors (issue #633). Each rule promises
+ # ceil(pct * len(folder_code_files)) of the code files under its glob get
+ # a file_page, whatever their global score. Additive union — a floor that
+ # can raise the page count (and therefore the estimate) but never
+ # displaces a global pick. Mirrors how tour landmarks force-include
+ # entry points; these are user-supplied globs instead. Uses the *uncapped*
+ # ranking so files below the global cutoff are pinnable.
+ pinned = _folder_coverage_pins(inputs, scored_files)
+ if pinned:
+ selected_paths = list(dict.fromkeys(selected_paths + pinned))
+ folder_coverage = _folder_coverage_report(inputs, scored_files, selected_paths)
+
sel = Selection(
- file_page_paths=[p for _, p in files],
+ file_page_paths=selected_paths,
symbol_spotlights=[t for _, t in symbols],
module_groups=[m for _, m in modules],
concept_groups=list(concepts.groups),
@@ -896,11 +939,81 @@ def select_pages(inputs: SelectionInputs) -> Selection:
emit_repo_overview=True,
eligible_file_pages=eligible_file_pages,
effective_file_page_cap=effective_file_page_cap,
+ folder_coverage=folder_coverage,
)
- log.info("page_selection.complete", counts=sel.counts())
+ log.info("page_selection.complete", counts=sel.counts(), folder_coverage=folder_coverage)
return sel
+def _folder_rules(inputs: SelectionInputs) -> tuple[tuple[str, float], ...]:
+ return tuple(getattr(inputs.config, "folder_coverage", ()) or ())
+
+
+def _under_glob(path: str, glob_pattern: str) -> bool:
+ """Shell-style match on the repo-relative path, or a path under the folder.
+
+ ``src/core`` matches everything below ``src/core``. ``fnmatch``'s ``*``
+ also crosses ``/``, so ``src/*`` matches the whole ``src`` subtree.
+ """
+ import fnmatch
+
+ return fnmatch.fnmatch(path, glob_pattern) or path.startswith(glob_pattern.rstrip("/") + "/")
+
+
+def _folder_coverage_pins(
+ inputs: SelectionInputs,
+ files: list[tuple[float, str]],
+) -> list[str]:
+ """Return the additive file-page pins for configured folder-coverage rules.
+
+ Each ``(glob, pct)`` rule promises at least ``ceil(pct * n)`` of the code
+ files under *glob* a file_page, chosen highest-importance first from the
+ already-scored candidate list. Files already selected globally are kept
+ (the union dedups), so a rule only ever *adds* pages for files that scored
+ below the global cutoff — a floor, never a displacement (issue #633).
+ Empty rules and non-positive fractions are ignored.
+ """
+ import math
+
+ rules = _folder_rules(inputs)
+ if not rules:
+ return []
+
+ # ``files`` is already ranked (score desc, then path), the order the
+ # global budget uses, so each rule's matches come out highest-score first.
+ pinned: list[str] = []
+ seen: set[str] = set()
+ for glob_pattern, pct in rules:
+ if not glob_pattern or pct is None or pct <= 0:
+ continue
+ matches = [p for _, p in files if _under_glob(p, glob_pattern)]
+ if not matches:
+ continue
+ want = max(1, math.ceil(pct * len(matches))) # ceil, at least 1
+ for p in matches[:want]:
+ if p not in seen:
+ seen.add(p)
+ pinned.append(p)
+ return pinned
+
+
+def _folder_coverage_report(
+ inputs: SelectionInputs,
+ files: list[tuple[float, str]],
+ selected: list[str],
+) -> list[tuple[str, int, int]]:
+ """``(glob, documented, eligible)`` per rule, for the run to show its floors."""
+ rules = _folder_rules(inputs)
+ if not rules:
+ return []
+ chosen = set(selected)
+ report: list[tuple[str, int, int]] = []
+ for glob_pattern, _pct in rules:
+ matches = [p for _, p in files if _under_glob(p, glob_pattern)]
+ report.append((glob_pattern, sum(p in chosen for p in matches), len(matches)))
+ return report
+
+
def summarize_selection(sel: Selection) -> dict[str, int]:
"""Convenience wrapper returning the counts dict.
diff --git a/packages/core/src/repowise/core/repo_config.py b/packages/core/src/repowise/core/repo_config.py
index a05936182..3ebb6a08d 100644
--- a/packages/core/src/repowise/core/repo_config.py
+++ b/packages/core/src/repowise/core/repo_config.py
@@ -34,6 +34,7 @@ CONFIG_DEPENDENCY_KEYS: dict[str, frozenset[str]] = {
"wiki_style",
"language",
"max_file_pages",
+ "folder_coverage",
"generation_context",
"enable_onboarding",
}
diff --git a/tests/unit/cli/test_cost_estimator.py b/tests/unit/cli/test_cost_estimator.py
index 973a5f51d..c0f547d79 100644
--- a/tests/unit/cli/test_cost_estimator.py
+++ b/tests/unit/cli/test_cost_estimator.py
@@ -52,6 +52,9 @@ class FakeConfig:
max_file_pages: int | None = None
file_page_min_symbols: int = 1
max_pages_pct: float = 0.10
+ # Folder floors (issue #633); duck-typed so the selector reads it via
+ # getattr and tests without it still exercise the unset path.
+ folder_coverage: tuple[tuple[str, float], ...] = ()
def _make_graph_builder(files: list[FakeParsedFile]):
@@ -139,6 +142,32 @@ class TestBuildGenerationPlan:
plans = build_generation_plan([pf1, pf2], builder, FakeConfig())
assert any(p.page_type == "scc_page" and p.count == 1 for p in plans)
+ def test_folder_coverage_pin_raises_the_file_page_count(self):
+ """The plan shares select_pages, so folder pins must move the estimate
+ (additive floor, issue #633)."""
+ files = []
+ for i in range(20):
+ fi = FakeFileInfo(path=f"src/core/mod_{i}.py", language="python")
+ files.append(FakeParsedFile(file_info=fi, symbols=[FakeSymbol(name=f"f{i}")]))
+ builder = _make_graph_builder(files)
+
+ # A tight global cap so most files fall outside it; the folder floor
+ # must bring them back regardless of score.
+ unset = build_generation_plan(files, builder, FakeConfig(max_file_pages=5))
+ pinned = build_generation_plan(
+ files,
+ builder,
+ FakeConfig(max_file_pages=5, folder_coverage=(("src/core", 1.0),)),
+ )
+
+ unset_count = next(p.count for p in unset if p.page_type == "file_page")
+ pinned_count = next(p.count for p in pinned if p.page_type == "file_page")
+ assert unset_count == 5
+ assert pinned_count > unset_count
+ assert pinned_count == 20 # every code file under src/core gets a page
+ file_plan = next(p for p in pinned if p.page_type == "file_page")
+ assert file_plan.folder_coverage == [("src/core", 20, 20)]
+
class TestEstimateCost:
def test_mock_provider_zero_cost(self):
diff --git a/tests/unit/cli/test_init_folder_coverage.py b/tests/unit/cli/test_init_folder_coverage.py
new file mode 100644
index 000000000..4946a963e
--- /dev/null
+++ b/tests/unit/cli/test_init_folder_coverage.py
@@ -0,0 +1,66 @@
+"""``--folder-coverage`` flag wiring for ``repowise init`` (issue #633)."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any
+
+from click.testing import CliRunner
+
+from repowise.cli.commands.init_cmd import _generate
+from repowise.cli.main import cli
+
+
+def test_init_help_lists_folder_coverage() -> None:
+ result = CliRunner().invoke(cli, ["init", "--help"])
+ assert result.exit_code == 0
+ assert "--folder-coverage" in result.output
+
+
+def test_malformed_rule_is_a_usage_error(tmp_path: Any) -> None:
+ result = CliRunner().invoke(cli, ["init", str(tmp_path), "--folder-coverage", "src/core"])
+ assert result.exit_code == 2
+ assert "glob=pct" in result.output
+ assert not (tmp_path / ".repowise").exists()
+
+
+def test_flag_rules_override_config_in_generation_config(tmp_path: Any, monkeypatch: Any) -> None:
+ captured: dict[str, Any] = {}
+ monkeypatch.setattr(_generate, "load_config", lambda _p: {"folder_coverage": ["lib=0.5"]})
+ monkeypatch.setattr(_generate, "run_repo_generation", lambda **kw: captured.update(kw))
+
+ def run(rules: tuple[str, ...]) -> Any:
+ _generate._run_deterministic_generation_phase(
+ repo_path=tmp_path,
+ result=SimpleNamespace(repo_name="demo"),
+ total_phases=3,
+ concurrency=1,
+ language="en",
+ onboarding=True,
+ wiki_style="comprehensive",
+ max_file_pages=None,
+ embedder_name_resolved="mock",
+ embedder_was_requested=False,
+ resume=False,
+ folder_coverage_rules=rules,
+ )
+ return captured["gen_config"].folder_coverage
+
+ assert run(("src/core=1.0",)) == (("src/core", 1.0),)
+ assert run(()) == (("lib", 0.5),)
+
+
+def test_config_round_trip_persists_rules(tmp_path: Any) -> None:
+ """save_config_partial must record folder_coverage as a list of strings."""
+ import yaml
+
+ from repowise.cli.helpers import save_config_partial
+
+ repo = tmp_path / "repo"
+ repo.mkdir()
+ (repo / ".repowise").mkdir()
+
+ save_config_partial(repo, folder_coverage=["src/core=1.0"])
+
+ cfg = yaml.safe_load((repo / ".repowise" / "config.yaml").read_text())
+ assert cfg.get("folder_coverage") == ["src/core=1.0"]
diff --git a/tests/unit/cli/test_workspace_deterministic.py b/tests/unit/cli/test_workspace_deterministic.py
index 533f052d6..672d7b0b7 100644
--- a/tests/unit/cli/test_workspace_deterministic.py
+++ b/tests/unit/cli/test_workspace_deterministic.py
@@ -119,6 +119,7 @@ def test_single_repo_deterministic_generation_loads_source_evidence_config(
embedder_name_resolved="mock",
embedder_was_requested=False,
resume=False,
+ folder_coverage_rules=(),
)
config = captured["gen_config"]
diff --git a/tests/unit/generation/test_folder_coverage.py b/tests/unit/generation/test_folder_coverage.py
new file mode 100644
index 000000000..ee3fecefd
--- /dev/null
+++ b/tests/unit/generation/test_folder_coverage.py
@@ -0,0 +1,216 @@
+"""Folder-specific documentation floors (issue #633).
+
+Raghav's spec: a floor, not a cap. ``((glob, pct), ...)`` rules promise at
+least ``pct`` of the code files under each glob get a file_page, whatever
+their global importance score, unioned additively into the selection so the
+cost table stays truthful about what the user asked for.
+
+Key property pinned here: a folder pinned at 1.0 gets full file-page
+coverage even when its files score below the global cutoff (and therefore
+below the cap the folder rule must override).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from repowise.core.generation.models import GenerationConfig
+from repowise.core.generation.selection import SelectionInputs, select_pages
+
+
+@dataclass
+class _FakeFileInfo:
+ path: str
+ language: str = "python"
+ abs_path: str = ""
+ size_bytes: int = 5_000
+ is_test: bool = False
+ is_config: bool = False
+ is_api_contract: bool = False
+ is_entry_point: bool = False
+ git_hash: str = ""
+
+ def __post_init__(self) -> None:
+ if not self.abs_path:
+ self.abs_path = f"/repo/{self.path}"
+
+
+@dataclass
+class _FakeSymbol:
+ name: str
+ qualified_name: str = ""
+ kind: str = "function"
+ visibility: str = "public"
+ signature: str = "()"
+ docstring: str | None = None
+ decorators: list[str] = field(default_factory=list)
+ is_async: bool = False
+ complexity_estimate: int = 1
+ parent_name: str | None = None
+
+ def __post_init__(self) -> None:
+ if not self.qualified_name:
+ self.qualified_name = self.name
+
+
+@dataclass
+class _FakeParsedFile:
+ file_info: _FakeFileInfo
+ symbols: list[_FakeSymbol] = field(default_factory=list)
+ imports: list[object] = field(default_factory=list)
+ exports: list[str] = field(default_factory=list)
+ docstring: str | None = None
+ parse_errors: list[str] = field(default_factory=list)
+
+
+def _build_synthetic_repo(
+ n_files: int,
+) -> tuple[list[_FakeParsedFile], dict[str, float], dict[str, float], dict[str, int]]:
+ """PageRank tapers linearly (top 1.0, bottom ~0.01); every 25 files share
+ a ``pkg{i//25}`` prefix. Each file carries three public symbols so it
+ clears the score floor (same shape as test_selection_contract's fixture)."""
+ parsed: list[_FakeParsedFile] = []
+ pagerank: dict[str, float] = {}
+ betweenness: dict[str, float] = {}
+ community: dict[str, int] = {}
+ for i in range(n_files):
+ path = f"pkg{i // 25}/module_{i}.py"
+ syms = [
+ _FakeSymbol(name=f"func_{i}_{k}", qualified_name=f"module_{i}.func_{i}_{k}")
+ for k in range(3)
+ ]
+ parsed.append(_FakeParsedFile(file_info=_FakeFileInfo(path=path), symbols=syms))
+ pagerank[path] = 1.0 - (i / max(1, n_files - 1)) * 0.99
+ betweenness[path] = 0.0
+ community[path] = i // 25
+ return parsed, pagerank, betweenness, community
+
+
+def _inputs(parsed, pagerank, betweenness, community, cfg):
+ return SelectionInputs(
+ parsed_files=parsed,
+ pagerank=pagerank,
+ betweenness=betweenness,
+ community=community,
+ community_info=None,
+ sccs=[],
+ git_meta_map=None,
+ config=cfg,
+ )
+
+
+def test_folder_pinned_at_1_0_covers_every_code_file_under_the_glob() -> None:
+ """Files below the global cutoff must still be pinnable (the floor)."""
+ parsed, pagerank, betweenness, community = _build_synthetic_repo(50)
+ # Force a tight global cap so most files fall outside it.
+ cfg = GenerationConfig(max_file_pages=10, folder_coverage=(("pkg0", 1.0),))
+ sel = select_pages(_inputs(parsed, pagerank, betweenness, community, cfg))
+
+ assert len(sel.file_page_paths) >= 10 # global pick remains
+ # pkg0 holds files 0..24 (i // 25 == 0); all of them must be present.
+ pinned = {p for p in sel.file_page_paths if p.startswith("pkg0/")}
+ all_pkg0 = {p.file_info.path for p in parsed if p.file_info.path.startswith("pkg0/")}
+ assert pinned == all_pkg0, (
+ "a 1.0 folder floor must pin every code file under the glob, "
+ "including those below the global cutoff"
+ )
+
+
+def test_folder_floor_is_additive_not_displacing() -> None:
+ """The union never removes a global pick — the floor only adds pages."""
+ parsed, pagerank, betweenness, community = _build_synthetic_repo(50)
+ cfg = GenerationConfig(max_file_pages=10, folder_coverage=(("pkg0", 1.0),))
+ sel = select_pages(_inputs(parsed, pagerank, betweenness, community, cfg))
+
+ unpinned = select_pages(
+ _inputs(parsed, pagerank, betweenness, community, GenerationConfig(max_file_pages=10))
+ )
+ global_picks = set(unpinned.file_page_paths)
+ assert global_picks <= set(sel.file_page_paths), (
+ "folder pins must be additive — global picks stay select()ed"
+ )
+
+
+def test_partial_folder_floor_takes_ceil_pct_highest_scored() -> None:
+ parsed, pagerank, betweenness, community = _build_synthetic_repo(80)
+ cfg = GenerationConfig(max_file_pages=5, folder_coverage=(("pkg1", 0.5),))
+ sel = select_pages(_inputs(parsed, pagerank, betweenness, community, cfg))
+
+ # pkg1 holds files 25..49 (i // 25 == 1) → 25 files, half = ceil(12.5) = 13.
+ pkg1 = {p.file_info.path for p in parsed if p.file_info.path.startswith("pkg1/")}
+ got = {p for p in sel.file_page_paths if p in pkg1}
+ assert len(got) == 13
+
+ # The pinned 13 must be the highest-scored of pkg1 (PageRank tapers, so
+ # the top 13 by pagerank, tie-broken by path).
+ ranked = sorted(pkg1, key=lambda p: (-pagerank[p], p))
+ assert got == set(ranked[:13])
+
+
+def test_empty_rules_and_zero_pct_are_no_ops() -> None:
+ parsed, pagerank, betweenness, community = _build_synthetic_repo(30)
+ cfg = GenerationConfig(
+ max_file_pages=5, folder_coverage=(("pkg0", 0.0), ("no/such/dir", 1.0))
+ )
+ sel = select_pages(_inputs(parsed, pagerank, betweenness, community, cfg))
+ unpinned = select_pages(
+ _inputs(parsed, pagerank, betweenness, community, GenerationConfig(max_file_pages=5))
+ )
+ assert sel.file_page_paths == unpinned.file_page_paths
+
+
+def test_folder_rule_glob_shape_matches_subtree() -> None:
+ """``src/core`` (no glob metachars) matches the dir and everything under it."""
+ parsed, pagerank, betweenness, community = _build_synthetic_repo(30)
+ # Rename a slice of the synthetic repo into a subtree.
+ for p in parsed:
+ if p.file_info.path.startswith("pkg1/"):
+ p.file_info.path = "src/core/" + p.file_info.path.removeprefix("pkg1/")
+ pagerank = {("src/core/" + k.removeprefix("pkg1/")) if k.startswith("pkg1/") else k: v for k, v in pagerank.items()}
+
+ cfg = GenerationConfig(max_file_pages=5, folder_coverage=(("src/core", 1.0),))
+ sel = select_pages(_inputs(parsed, pagerank, betweenness, community, cfg))
+
+ under_core = {p.file_info.path for p in parsed if p.file_info.path.startswith("src/core/")}
+ got = {p for p in sel.file_page_paths if p.startswith("src/core/")}
+ assert got == under_core
+
+
+def test_config_yaml_parse_accepts_glob_equals_pct_strings() -> None:
+ cfg = GenerationConfig.from_repo_config(
+ {"folder_coverage": ["src/core=1.0", 'src/other="0.5"']}
+ )
+ assert cfg.folder_coverage == (("src/core", 1.0), ("src/other", 0.5))
+
+
+def test_config_yaml_parse_rejects_bad_rules() -> None:
+ import pytest
+
+ with pytest.raises(ValueError, match="folder_coverage must be a list"):
+ GenerationConfig.from_repo_config({"folder_coverage": "src/core=1.0"})
+ with pytest.raises(ValueError, match="not a number"):
+ GenerationConfig.from_repo_config({"folder_coverage": ["src/core=high"]})
+ with pytest.raises(ValueError, match=r"pct must be in \[0, 1\]"):
+ GenerationConfig.from_repo_config({"folder_coverage": ["src/core=1.5"]})
+
+
+def test_overlapping_rules_pin_each_file_once_and_report_per_folder() -> None:
+ parsed, pagerank, betweenness, community = _build_synthetic_repo(50)
+ cfg = GenerationConfig(
+ max_file_pages=5, folder_coverage=(("pkg0", 1.0), ("pkg0/*", 1.0), ("pkg1", 0.5))
+ )
+ sel = select_pages(_inputs(parsed, pagerank, betweenness, community, cfg))
+
+ assert len(sel.file_page_paths) == len(set(sel.file_page_paths))
+ assert sel.folder_coverage == [("pkg0", 25, 25), ("pkg0/*", 25, 25), ("pkg1", 13, 25)]
+
+
+def test_parse_accepts_dot_slash_and_pairs_and_rejects_nan() -> None:
+ import pytest
+
+ from repowise.core.generation.folder_coverage import parse_folder_coverage
+
+ assert parse_folder_coverage(["./src/core=1"]) == (("src/core", 1.0),)
+ assert parse_folder_coverage([("src/core", 0.5)]) == (("src/core", 0.5),)
+ with pytest.raises(ValueError, match=r"pct must be in \[0, 1\]"):
+ parse_folder_coverage(["src/core=nan"])
diff --git a/tests/unit/test_repo_config_invalidation.py b/tests/unit/test_repo_config_invalidation.py
index 821e9493a..2a15b0013 100644
--- a/tests/unit/test_repo_config_invalidation.py
+++ b/tests/unit/test_repo_config_invalidation.py
@@ -35,6 +35,7 @@ def test_dependency_fingerprints_classify_config_keys(tmp_path: Path) -> None:
("traversal", {"exclude_patterns": ["generated/**"]}),
("generation", {"provider": "openai"}),
("generation", {"enable_onboarding": False}),
+ ("generation", {"folder_coverage": ["src/core=1.0"]}),
("state_only", {"hooks": {"read_skeleton": False}}),
("state_only", {"editor_files": {"claude_md": False}}),
("other", {"future_setting": True}),