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.

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.py
new file mode 100644
index 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.py
index 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: str
is_template: bool
freshness_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
@property
def 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.py
index 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 records
diff --git a/packages/core/src/repowise/core/persistence/crud/pages.py b/packages/core/src/repowise/core/persistence/crud/pages.py
index 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.py
index 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 from
diff --git a/packages/core/src/repowise/core/pipeline/scoped_generation.py b/packages/core/src/repowise/core/pipeline/scoped_generation.py
index 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 select
from 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.py
index 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 PinDocResponse
from repowise.server.schemas.git import file_attribution_fields
router = 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_row
diff --git a/packages/server/src/repowise/server/schemas/files.py b/packages/server/src/repowise/server/schemas/files.py
new file mode 100644
index 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: bool
diff --git a/packages/types/src/files.ts b/packages/types/src/files.ts
index 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.ts
index 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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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"