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(generation): folder documentation floors with --folder-coverage (#2040)
Nehal Kf71bbcf7cd0a
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.mdindex 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.mdindex 39c8a3b38..4e3bdfde1 100644--- a/docs/reference/CONFIG.md+++ b/docs/reference/CONFIG.md@@ -53,6 +53,7 @@ wiki_style: comprehensivelanguage: enenable_onboarding: truemax_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 alsodiff --git a/packages/cli/src/repowise/cli/commands/init_cmd/_finish.py b/packages/cli/src/repowise/cli/commands/init_cmd/_finish.pyindex 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.pyindex 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 Noneplans = 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 breakdownlang_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) -> Noneonboarding=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.pyindex 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: boolverbose: boolprogress: str+ # Raw ``GLOB=PCT`` rules, validated by the option callback.+ folder_coverage_rules: tuple[str, ...] = ()@dataclassdiff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.pyindex 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_errorfrom repowise.cli.exit_codes import EXIT_CODES_HELPfrom repowise.cli.helpers import resolve_repo_pathfrom repowise.core.analysis.health.coverage import PARSERS as COVERAGE_PARSERS+from repowise.core.generation.folder_coverage import parse_folder_coveragefrom repowise.core.generation.languages import SUPPORTED_LANGUAGESfrom repowise.core.generation.styles import list_styles, resolve_stylefrom 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.pyindex 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.pyindex 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.pyindex 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: strcount: intlevel: int+ # file_page only: ``(glob, documented, eligible)`` per folder-coverage rule.+ folder_coverage: list[tuple[str, int, int]] = field(default_factory=list)@dataclassdiff --git a/packages/core/src/repowise/core/generation/folder_coverage.py b/packages/core/src/repowise/core/generation/folder_coverage.pynew file mode 100644index 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.pyindex 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 = 1skip_trivial_files: bool = Truededupe_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.pyindex 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 = 0effective_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 generatorand 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.pyindex 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.pyindex 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 = Nonefile_page_min_symbols: int = 1max_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.pynew file mode 100644index 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.pyindex 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.pynew file mode 100644index 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.pyindex 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}),