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
fix(files): pin a file's doc, scoped to its repository (groundwork for #812) (#2110)
Nehal K92b88a0eb2d2
diff --git a/packages/core/alembic/versions/0119_wiki_pages_pinned.py b/packages/core/alembic/versions/0119_wiki_pages_pinned.pynew file mode 100644index 000000000..eec59610a--- /dev/null+++ b/packages/core/alembic/versions/0119_wiki_pages_pinned.py@@ -0,0 +1,45 @@+"""Add ``wiki_pages.pinned``: a user hand-requested this page's doc.++A pinned page always enters generation selection, so a doc a user asked for+keeps following the code (issue #812). Not null, default false.++Local SQLite stores never run Alembic -- ``init_db``'s reconciler issues+additive DDL for missing columns -- so this migration exists for managed+Postgres.++Revision ID: 0119+Revises: 0118+Create Date: 2026-10-27+"""++from __future__ import annotations++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++# revision identifiers+revision: str = "0119"+down_revision: str | None = "0118"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def _columns() -> set[str]:+ inspector = sa.inspect(op.get_bind())+ return {c["name"] for c in inspector.get_columns("wiki_pages")}+++def upgrade() -> None:+ # Guarded: ``init_db``'s reconciler may already have added it on Postgres.+ if "pinned" not in _columns():+ op.add_column(+ "wiki_pages",+ sa.Column("pinned", sa.Boolean(), nullable=False, server_default=sa.false()),+ )+++def downgrade() -> None:+ if "pinned" in _columns():+ op.drop_column("wiki_pages", "pinned")diff --git a/packages/core/src/repowise/core/generation/page_selection.py b/packages/core/src/repowise/core/generation/page_selection.pyindex 7ed92a029..4eef4db4e 100644--- a/packages/core/src/repowise/core/generation/page_selection.py+++ b/packages/core/src/repowise/core/generation/page_selection.py@@ -49,6 +49,10 @@ class PageRecord:target_path: stris_template: boolfreshness_status: str = "fresh"+ # A user hand-requested this page (UI "Generate doc"): it must be+ # regenerated every run regardless of the selection heuristic (issue+ # #812), so the doc keeps following the code.+ pinned: bool = False@propertydef is_stale(self) -> bool:@@ -137,6 +141,9 @@ def resolve_page_selection()if intent.stale:selected.update(r.page_id for r in records if r.is_stale)+ # Pinned pages are regenerated unconditionally: the user asked for this+ # doc once and it should keep following the code (issue #812).+ selected.update(r.page_id for r in records if r.pinned)if intent.path_globs:selected.update(r.page_id for r in records if _matches_glob(r.target_path, intent.path_globs)diff --git a/packages/core/src/repowise/core/generation/scope.py b/packages/core/src/repowise/core/generation/scope.pyindex f10420929..142a104b6 100644--- a/packages/core/src/repowise/core/generation/scope.py+++ b/packages/core/src/repowise/core/generation/scope.py@@ -88,6 +88,7 @@ def load_page_records(pages: list[Any]) -> list[PageRecord]:target_path=p.target_path,is_template=is_template,freshness_status=getattr(p, "freshness_status", "fresh"),+ pinned=bool(getattr(p, "pinned", False)),))return recordsdiff --git a/packages/core/src/repowise/core/persistence/crud/pages.py b/packages/core/src/repowise/core/persistence/crud/pages.pyindex ceec2efc2..d17e6159c 100644--- a/packages/core/src/repowise/core/persistence/crud/pages.py+++ b/packages/core/src/repowise/core/persistence/crud/pages.py@@ -600,6 +600,22 @@ async def get_page(session: AsyncSession, page_id: str) -> Page | None:return await session.get(Page, page_id)+async def set_page_pinned(session: AsyncSession, page_id: str, pinned: bool) -> Page | None:+ """Set the user-requested pin on a page (issue #812).++ A pinned page is regenerated on every reindex regardless of the normal+ selection heuristic, so the doc a user asked for keeps following the+ code instead of silently disappearing again. Returns None when no such+ page exists.+ """+ page = await get_page(session, page_id)+ if page is None:+ return None+ page.pinned = pinned+ await session.flush()+ return page++async def list_pages(session: AsyncSession,repository_id: str,diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.pyindex 49d6db29a..5254cd6f2 100644--- a/packages/core/src/repowise/core/persistence/models.py+++ b/packages/core/src/repowise/core/persistence/models.py@@ -226,6 +226,11 @@ class Page(Base):metadata_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")# Developer-authored notes that survive LLM re-generation.human_notes: Mapped[str | None] = mapped_column(Text, nullable=True)+ # A user hand-requested this page (UI "Generate doc"): it is regenerated+ # on every reindex regardless of the selection heuristic, so the doc a+ # user asked for keeps following the code instead of silently+ # disappearing again (issue #812).+ pinned: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)# --- Where the page sits in the wiki -----------------------------------# Hierarchy lives here rather than being reassembled by each reader fromdiff --git a/packages/core/src/repowise/core/pipeline/scoped_generation.py b/packages/core/src/repowise/core/pipeline/scoped_generation.pyindex d149788b0..2d90720b5 100644--- a/packages/core/src/repowise/core/pipeline/scoped_generation.py+++ b/packages/core/src/repowise/core/pipeline/scoped_generation.py@@ -86,9 +86,12 @@ def load_kg_context(repo_path: Path) -> Any:async def _load_page_rows(session: Any, repo_id: str) -> list[Any]:"""Every non-tombstoned persisted page, lightweight columns only.- ``load_page_records`` reads just id/type/target/provider/metadata/freshness,- so ``load_only`` keeps the (potentially very large) ``content`` Text column- out of this whole-wiki scan.+ ``load_page_records`` reads just id/type/target/provider/metadata/freshness+ (plus ``pinned``), so ``load_only`` keeps the (potentially very large)+ ``content`` Text column out of this whole-wiki scan. Anything+ ``load_page_records`` reads must be listed here: a deferred column is a+ lazy load, and this session is gone by the time the stale-page decay pass+ reads the records back, so the access raises instead of loading."""from sqlalchemy import selectfrom sqlalchemy.orm import load_only@@ -105,6 +108,7 @@ async def _load_page_rows(session: Any, repo_id: str) -> list[Any]:Page.provider_name,Page.metadata_json,Page.freshness_status,+ Page.pinned,)).where(diff --git a/packages/server/src/repowise/server/routers/files.py b/packages/server/src/repowise/server/routers/files.pyindex 2bef632e9..a82679b74 100644--- a/packages/server/src/repowise/server/routers/files.py+++ b/packages/server/src/repowise/server/routers/files.py@@ -47,6 +47,7 @@ from repowise.server.routers.code_health import (_score_breakdown_from_findings,)from repowise.server.routers.git import _hotspot_from_row+from repowise.server.schemas.files import PinDocResponsefrom repowise.server.schemas.git import file_attribution_fieldsrouter = APIRouter(@@ -232,6 +233,107 @@ async def files_index(}+def _file_exists(repo: Any, file_path: str) -> bool:+ """True when *file_path* is a file inside *repo*'s checkout.++ Resolved and then checked against the checkout root, so a ``..`` segment+ cannot walk out of the repository. The path arrives from a URL, and the row+ this endpoint writes is a claim that a real file needs a doc.++ A repository whose ``local_path`` is not a directory (moved checkout,+ remote-only entry) cannot answer the question, so it is not treated as a+ missing file: the pin proceeds and the generation phase decides, which keeps+ this from turning a storage change into a 404 on a previously working call.+ """+ from pathlib import Path++ root = getattr(repo, "local_path", None)+ if not root:+ return True+ root_path = Path(root)+ if not root_path.is_dir():+ return True+ try:+ target = (root_path / file_path).resolve()+ target.relative_to(root_path.resolve())+ except (ValueError, OSError):+ return False+ return target.is_file()++[email protected]("/{repo_id}/files/{file_path:path}/pin-doc", response_model=PinDocResponse)+async def pin_file_doc(+ repo_id: str,+ file_path: str,+ session: AsyncSession = Depends(get_db_session),+) -> PinDocResponse:+ """Pin a file's doc so every reindex regenerates it (issue #812).++ Called from the Doc tab's "Generate doc" action. A file with no page+ yet gets a lightweight template row marked pinned, so the next+ generation phase knows to produce (and keep) its doc. Returns the+ pinned state for the UI to render.+ """+ from datetime import UTC, datetime++ repo = await crud.get_repository(session, repo_id)+ if repo is None:+ raise HTTPException(status_code=404, detail="Repository not found")++ # The file has to be one this repository actually has. Without this the+ # endpoint pins a row for any string a caller sends: an empty path, a+ # traversal, or a typo all produce a pinned page that no reindex will ever+ # fill, and the UI renders it as a doc the user asked for.+ if not _file_exists(repo, file_path):+ raise HTTPException(status_code=404, detail=f"File not found: {file_path}")++ page_id = f"file_page:{file_path}"+ page = await crud.get_page(session, page_id)+ if page is not None and page.repository_id != repo_id:+ # ``Page.id`` is ``"{page_type}:{target_path}"`` and therefore global, so+ # two repositories holding the same path share one id. The doc tab+ # already refuses to read the other repository's row+ # (``file_detail``); pinning it was still possible, which let one+ # repository's Doc tab mark another repository's page as pinned.+ raise HTTPException(+ status_code=409,+ detail=(+ f"A page for {file_path} already belongs to a different "+ "repository; refusing to pin it"+ ),+ )+ if page is None:+ # Lightweight "wanted" row: template provenance means it reads as+ # unwritten (so the heuristics know there is nothing yet), and the+ # pin is what makes selection always include it.+ page = await crud.upsert_page(+ session,+ page_id=page_id,+ repository_id=repo_id,+ page_type="file_page",+ title=file_path.rsplit("/", 1)[-1],+ content="",+ summary="",+ target_path=file_path,+ source_hash="",+ model_name="template",+ provider_name="template",+ created_at=datetime.now(UTC),+ updated_at=datetime.now(UTC),+ )+ elif page.freshness_status == "tombstone":+ # Generation never loads a tombstoned row, so a pin on one would be+ # recorded and never acted on. The file exists again (checked above),+ # so the old doc is revived as stale: selection picks it up and+ # regenerates it.+ page.freshness_status = "stale"+ page = await crud.set_page_pinned(session, page_id, True)+ if page is None:+ raise HTTPException(status_code=404, detail="Page not found")+ await session.commit()+ return PinDocResponse(file_path=file_path, pinned=page.pinned)++@router.get("/{repo_id}/files/{file_path:path}")async def file_detail(repo_id: str,@@ -298,6 +400,7 @@ async def file_detail("freshness_status": page_row.freshness_status,"confidence": page_row.confidence,"human_notes": page_row.human_notes,+ "pinned": page_row.pinned,"updated_at": page_row.updated_at.isoformat() if page_row.updated_at else None,}if page_rowdiff --git a/packages/server/src/repowise/server/schemas/files.py b/packages/server/src/repowise/server/schemas/files.pynew file mode 100644index 000000000..a33d49576--- /dev/null+++ b/packages/server/src/repowise/server/schemas/files.py@@ -0,0 +1,12 @@+"""Schemas for the file-detail aggregate and the doc-pin action."""++from __future__ import annotations++from pydantic import BaseModel+++class PinDocResponse(BaseModel):+ """Result of pinning a file's doc (issue #812)."""++ file_path: str+ pinned: booldiff --git a/packages/types/src/files.ts b/packages/types/src/files.tsindex f16c3b7d4..418031d8a 100644--- a/packages/types/src/files.ts+++ b/packages/types/src/files.ts@@ -15,6 +15,9 @@ export interface FileWikiPageRef {freshness_status: string;confidence: number;human_notes: string | null;+ /** Hand-requested doc: regenerated on every reindex so it keeps+ following the code (issue #812). */+ pinned: boolean;updated_at: string | null;}diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.tsindex 147b776ac..b4f09b206 100644--- a/packages/types/src/generated/http.ts+++ b/packages/types/src/generated/http.ts@@ -3403,6 +3403,12 @@ export interface PeriodHealthSummaryResponse {net_findings: number;}+/** Result of pinning a file's doc (issue #812). */+export interface PinDocResponse {+ file_path: string;+ pinned: boolean;+}+/** A function's stored size measures; an absent one was not measured. */export interface PlanMeasuresResponse {ccn?: number | null;diff --git a/tests/unit/generation/test_page_selection.py b/tests/unit/generation/test_page_selection.pyindex 9c357cd00..e290099c2 100644--- a/tests/unit/generation/test_page_selection.py+++ b/tests/unit/generation/test_page_selection.py@@ -78,6 +78,20 @@ def test_stale_selects_stale_and_expired() -> None:assert result.page_ids == {"file_page:tests/t.py"}+def test_pinned_selects_hand_requested_docs_always() -> None:+ """A pinned page's doc was asked for once and must keep being+ regenerated regardless of the selection heuristic (issue #812). Empty+ intent — the caller's default — still includes it."""+ records = [+ PageRecord("file_page:src/c.py", "file_page", "src/c.py", is_template=True),+ PageRecord(+ "file_page:src/pinned.py", "file_page", "src/pinned.py", is_template=True, pinned=True+ ),+ ]+ result = resolve_page_selection(records, PageSelectionIntent())+ assert result.page_ids == {"file_page:src/pinned.py"}++def test_path_glob_matches_prefix_and_glob() -> None:# A bare directory prefix matches everything under it.result = resolve_page_selection(_records(), PageSelectionIntent(path_globs=("src",)))diff --git a/tests/unit/persistence/test_wiki_pages_pinned_migration.py b/tests/unit/persistence/test_wiki_pages_pinned_migration.pynew file mode 100644index 000000000..df8ae84dc--- /dev/null+++ b/tests/unit/persistence/test_wiki_pages_pinned_migration.py@@ -0,0 +1,54 @@+"""Migration 0119: the ``pinned`` column on wiki_pages (issue #812)."""++from __future__ import annotations++import asyncio+import sqlite3+from pathlib import Path+++def _columns(db_path: Path) -> set[str]:+ conn = sqlite3.connect(db_path)+ try:+ return {row[1] for row in conn.execute('PRAGMA table_info("wiki_pages")')}+ finally:+ conn.close()+++def _alembic_config(db_path: Path):+ from alembic.config import Config++ root = Path(__file__).resolve().parents[3] / "packages" / "core"+ config = Config()+ config.set_main_option("script_location", str(root / "alembic"))+ config.set_main_option("sqlalchemy.url", f"sqlite+aiosqlite:///{db_path}")+ return config+++def test_the_migration_adds_and_drops_the_column(tmp_path: Path) -> None:+ from alembic import command++ db_path = tmp_path / "wiki.db"+ config = _alembic_config(db_path)+ command.upgrade(config, "0119")+ assert "pinned" in _columns(db_path)+ command.downgrade(config, "0118")+ assert "pinned" not in _columns(db_path)+++def test_the_migration_and_the_model_agree(tmp_path: Path) -> None:+ from alembic import command++ from repowise.core.persistence.database import create_engine, init_db++ migrated = tmp_path / "migrated.db"+ command.upgrade(_alembic_config(migrated), "head")+ declared = tmp_path / "declared.db"++ async def _build() -> None:+ engine = create_engine(f"sqlite+aiosqlite:///{declared}")+ await init_db(engine)+ await engine.dispose()++ asyncio.run(_build())+ assert _columns(migrated) == _columns(declared)diff --git a/tests/unit/server/test_file_pin.py b/tests/unit/server/test_file_pin.pynew file mode 100644index 000000000..775bd76da--- /dev/null+++ b/tests/unit/server/test_file_pin.py@@ -0,0 +1,193 @@+"""Tests for POST /api/repos/{id}/files/{path}/pin-doc (issue #812).++The pin is what makes a hand-requested doc keep being regenerated: pinned+pages always enter the generation selection. The endpoint must (a) pin an+existing page and (b) create + pin a lightweight template row for a file+with no page yet.+"""++from __future__ import annotations++import pytest+from httpx import AsyncClient++from repowise.core.persistence.database import get_session+from repowise.core.persistence.models import Page+from tests.unit.server.conftest import create_test_repo+++async def test_pin_creates_a_wanted_row_for_an_undocumented_file(+ client: AsyncClient, app+) -> None:+ """A file with no page gets a pinned template row so the next+ generation phase produces its doc."""+ repo = await create_test_repo(client)+ # The file has to exist in the checkout: the endpoint now refuses to pin a+ # row for a path the repository does not have.+ _write(repo["local_path"], "src/missing.py")+ resp = await client.post(f"/api/repos/{repo['id']}/files/src/missing.py/pin-doc")+ assert resp.status_code == 200+ assert resp.json()["pinned"] is True++ async with get_session(app.state.session_factory) as session:+ page = await session.get(Page, "file_page:src/missing.py")+ assert page is not None+ assert page.pinned is True+ assert page.provider_name == "template" # reads as unwritten+++async def test_pin_marks_an_existing_page(client: AsyncClient, app) -> None:+ """An existing wiki page is pinned in place, not replaced."""+ repo = await create_test_repo(client)+ _write(repo["local_path"], "src/known.py")+ from datetime import UTC, datetime++ async with get_session(app.state.session_factory) as session:+ session.add(+ Page(+ id="file_page:src/known.py",+ repository_id=repo["id"],+ page_type="file_page",+ title="known.py",+ content="real prose",+ target_path="src/known.py",+ source_hash="abc",+ model_name="claude",+ provider_name="anthropic",+ created_at=datetime.now(UTC),+ updated_at=datetime.now(UTC),+ )+ )+ await session.commit()++ resp = await client.post(f"/api/repos/{repo['id']}/files/src/known.py/pin-doc")+ assert resp.status_code == 200+ assert resp.json()["pinned"] is True++ async with get_session(app.state.session_factory) as session:+ page = await session.get(Page, "file_page:src/known.py")+ assert page is not None+ assert page.pinned is True+ assert page.content == "real prose" # untouched+++async def test_pin_unknown_repo_404s(client: AsyncClient) -> None:+ resp = await client.post("/api/repos/does-not-exist/files/src/a.py/pin-doc")+ assert resp.status_code == 404++def _write(root: str, rel: str) -> None:+ """Create *rel* inside *root*, so the endpoint's existence check passes."""+ from pathlib import Path++ target = Path(root) / rel+ target.parent.mkdir(parents=True, exist_ok=True)+ target.write_text("x = 1\n", encoding="utf-8")+++async def test_pin_404s_for_a_file_that_is_not_there(client: AsyncClient) -> None:+ """Only a real file can be pinned.++ Without this the endpoint writes a pinned page for any string a caller+ sends, and the UI renders it as a doc the user asked for even though no+ reindex will ever fill it.+ """+ repo = await create_test_repo(client)+ resp = await client.post(f"/api/repos/{repo['id']}/files/src/absent.py/pin-doc")+ assert resp.status_code == 404+ assert "not found" in resp.json()["detail"].lower()+++async def test_pin_refuses_a_path_outside_the_checkout(client: AsyncClient) -> None:+ """A ``..`` segment must not reach out of the repository."""+ repo = await create_test_repo(client)+ resp = await client.post(+ f"/api/repos/{repo['id']}/files/../../etc/hosts/pin-doc"+ )+ assert resp.status_code in (404, 400)+++async def test_pin_refuses_a_page_belonging_to_another_repository(+ client: AsyncClient, app+) -> None:+ """``Page.id`` is global, so two repositories sharing a path share an id.++ ``file_detail`` already refuses to *read* the other repository's row; this+ endpoint used to pin it, which let one repository's Doc tab mark another+ repository's page.+ """+ from datetime import UTC, datetime++ first = await create_test_repo(client)+ second = await create_test_repo(client)+ _write(second["local_path"], "src/shared.py")++ async with get_session(app.state.session_factory) as session:+ session.add(+ Page(+ id="file_page:src/shared.py",+ repository_id=first["id"],+ page_type="file_page",+ title="shared.py",+ content="belongs to the first repo",+ target_path="src/shared.py",+ source_hash="abc",+ model_name="claude",+ provider_name="anthropic",+ created_at=datetime.now(UTC),+ updated_at=datetime.now(UTC),+ )+ )+ await session.commit()++ resp = await client.post(+ f"/api/repos/{second['id']}/files/src/shared.py/pin-doc"+ )+ assert resp.status_code == 409++ async with get_session(app.state.session_factory) as session:+ page = await session.get(Page, "file_page:src/shared.py")+ assert page is not None+ assert page.pinned in (False, None), "the other repository's page was pinned"+++async def test_pin_revives_a_tombstoned_page(client: AsyncClient, app) -> None:+ """Generation skips tombstoned rows, so a pin on one would never be acted+ on. The file exists again, so the pin revives the page as stale."""+ from datetime import UTC, datetime++ repo = await create_test_repo(client)+ _write(repo["local_path"], "src/back.py")+ async with get_session(app.state.session_factory) as session:+ session.add(+ Page(+ id="file_page:src/back.py",+ repository_id=repo["id"],+ page_type="file_page",+ title="back.py",+ content="old prose",+ target_path="src/back.py",+ source_hash="abc",+ model_name="claude",+ provider_name="anthropic",+ freshness_status="tombstone",+ created_at=datetime.now(UTC),+ updated_at=datetime.now(UTC),+ )+ )+ await session.commit()++ resp = await client.post(f"/api/repos/{repo['id']}/files/src/back.py/pin-doc")+ assert resp.status_code == 200++ async with get_session(app.state.session_factory) as session:+ page = await session.get(Page, "file_page:src/back.py")+ assert page is not None+ assert page.pinned is True+ assert page.freshness_status == "stale"