monorepoly 0.2.0__py3-none-any.whl

monorepoly/models.py

@@ -0,0 +1,329 @@
+"""Documents stored in MongoDB; each `__bson__` returns pymongo-native types only."""
+
+import dataclasses
+import datetime
+import enum
+import hashlib
+import logging
+import uuid
+
+from monorepoly.exceptions import MonorepolyValueError
+
+_LOGGER = logging.getLogger(__name__)
+_NAMESPACE = uuid.UUID('6f1c9a52-3b0e-4d8a-9a51-2f6c1e7d4b10')
+
+# ':' cannot appear in git branch names, so this never collides with a branch.
+DEFAULT_REF = ':default'
+
+
+def make_id(*parts: str | int) -> str:
+    """Returns a deterministic id for the natural key `parts`."""
+    return str(uuid.uuid5(_NAMESPACE, '\x1f'.join(str(part) for part in parts)))
+
+
+def commit_id(*, project_id: int, sha: str) -> str:
+    """Returns the id of the commit document, without building the commit."""
+    return make_id(ActivityKind.COMMIT, project_id, sha)
+
+
+def utcnow() -> datetime.datetime:
+    """Returns the current time as an aware UTC datetime."""
+    return datetime.datetime.now(datetime.UTC)
+
+
+class SymbolKind(enum.StrEnum):
+    MODULE = 'module'
+    CLASS = 'class'
+    FUNCTION = 'function'
+    METHOD = 'method'
+    CONFIG_FILE = 'config_file'
+    CONFIG_DOCUMENT = 'config_document'
+    CONFIG_KEY = 'config_key'
+
+
+class ActivityKind(enum.StrEnum):
+    BRANCH = 'branch'
+    COMMIT = 'commit'
+    DISCUSSION = 'discussion'
+    ISSUE = 'issue'
+    MERGE_REQUEST = 'merge_request'
+
+
+class CommitCategory(enum.StrEnum):
+    FEATURE = 'feature'
+    FIX = 'fix'
+    CLEANUP = 'cleanup'
+    CONFIGURATION = 'configuration'
+    DEPENDENCIES = 'dependencies'
+    TESTS = 'tests'
+    DOCS = 'docs'
+    OTHER = 'other'
+    MERGE = 'merge'
+
+
+class State(enum.StrEnum):
+    """GitLab issue and merge request states."""
+
+    OPENED = 'opened'
+    CLOSED = 'closed'
+    MERGED = 'merged'
+    LOCKED = 'locked'
+
+
+def _to_bson(value: object) -> object:
+    match value:
+        case enum.Enum():
+            return value.value
+        case str() | int() | float() | datetime.datetime() | None:
+            return value
+        case tuple() | list():
+            return [_to_bson(item) for item in value]
+        case _ if hasattr(value, '__bson__'):
+            return value.__bson__()
+        case _:
+            raise MonorepolyValueError(f'Unsupported BSON value {value!r}!')
+
+
+def _fields(obj: object) -> dict[str, object]:
+    return {field.name: _to_bson(getattr(obj, field.name)) for field in dataclasses.fields(obj)}
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Project:
+    default_branch: str | None
+    empty_repo: bool
+    http_url_to_repo: str
+    id: int
+    # Feature access levels: 'enabled' (anyone who can see the project), 'private' (members
+    # only) or 'disabled'.
+    issues_access_level: str
+    merge_requests_access_level: str
+    path_with_namespace: str
+    repository_access_level: str
+    visibility: str
+    web_url: str
+
+    def __bson__(self) -> dict:
+        return {'_id': self.id, **_fields(self)}
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Symbol:
+    """A module, class, function, method or config part at one ref."""
+
+    docstring: str | None
+    end_line: int
+    kind: SymbolKind
+    path: str
+    project_id: int
+    qualname: str
+    ref: str
+    signature: str
+    source: str
+    start_line: int
+
+    @property
+    def key(self) -> str:
+        """Returns the ref-independent identity that links commits to symbols."""
+        return make_id('symbol', self.project_id, self.path, self.qualname)
+
+    @property
+    def id(self) -> str:
+        return make_id(self.key, self.ref)
+
+    @property
+    def content_hash(self) -> str:
+        content = '\x1f'.join((self.path, self.qualname, self.source))
+        return hashlib.sha256(content.encode()).hexdigest()
+
+    def embedding_input(self) -> tuple[str, str]:
+        """Returns the (title, text) pair to embed."""
+        text = '\n'.join(part for part in (self.signature, self.docstring, self.source) if part)
+        return f'{self.path} {self.qualname}', text
+
+    def __bson__(self) -> dict:
+        return {
+            '_id': self.id,
+            **_fields(self),
+            'content_hash': self.content_hash,
+            'key': self.key,
+        }
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Change:
+    """One file touched by a commit; line ranges are on the new side."""
+
+    line_ranges: tuple[tuple[int, int], ...]
+    path: str
+    qualnames: tuple[str, ...]
+    symbol_keys: tuple[str, ...]
+
+    def __bson__(self) -> dict:
+        return _fields(self)
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Commit:
+    author_email: str
+    author_name: str
+    authored_at: datetime.datetime
+    category: CommitCategory
+    changes: tuple[Change, ...]
+    committed_at: datetime.datetime
+    diff: str
+    message: str
+    parents: tuple[str, ...]
+    project_id: int
+    sha: str
+    web_url: str
+
+    @property
+    def id(self) -> str:
+        return commit_id(project_id=self.project_id, sha=self.sha)
+
+    def embedding_input(self) -> tuple[str, str]:
+        """Returns the (title, text) pair to embed: message plus touched paths and qualnames."""
+        touched = sorted(
+            {*(c.path for c in self.changes), *(q for c in self.changes for q in c.qualnames)}
+        )
+        return self.message.partition('\n')[0], '\n'.join([self.message, *touched])
+
+    def __bson__(self) -> dict:
+        return {
+            '_id': self.id,
+            **_fields(self),
+            'confidential': False,
+            'kind': str(ActivityKind.COMMIT),
+            'state': None,
+            'symbol_keys': sorted({key for c in self.changes for key in c.symbol_keys}),
+            # When it landed: a rebased or cherry-picked commit may have been authored long ago.
+            'updated_at': self.committed_at,
+        }
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Branch:
+    author_email: str
+    author_name: str
+    head_sha: str
+    messages: tuple[str, ...]
+    name: str
+    project_id: int
+    state: State  # Opened, or merged once fully merged into the default branch.
+    symbol_keys: tuple[str, ...]
+    updated_at: datetime.datetime
+    web_url: str
+
+    @property
+    def id(self) -> str:
+        return make_id(ActivityKind.BRANCH, self.project_id, self.name)
+
+    def embedding_input(self) -> tuple[str, str]:
+        """Returns the (title, text) pair to embed."""
+        return self.name, '\n'.join(self.messages)
+
+    def __bson__(self) -> dict:
+        return {
+            '_id': self.id,
+            **_fields(self),
+            'confidential': False,
+            'kind': str(ActivityKind.BRANCH),
+        }
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Issue:
+    assignee_ids: tuple[int, ...]
+    author_id: int | None
+    closed_at: datetime.datetime | None
+    confidential: bool
+    created_at: datetime.datetime | None
+    description: str
+    iid: int
+    labels: tuple[str, ...]
+    project_id: int
+    state: State
+    title: str
+    updated_at: datetime.datetime | None
+    web_url: str
+
+    @property
+    def id(self) -> str:
+        return make_id(ActivityKind.ISSUE, self.project_id, self.iid)
+
+    def embedding_input(self) -> tuple[str, str]:
+        """Returns the (title, text) pair to embed."""
+        return self.title, self.description
+
+    def __bson__(self) -> dict:
+        return {'_id': self.id, **_fields(self), 'kind': str(ActivityKind.ISSUE)}
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class MergeRequest:
+    assignee_ids: tuple[int, ...]
+    author_id: int | None
+    created_at: datetime.datetime | None
+    description: str
+    iid: int
+    merged_at: datetime.datetime | None
+    project_id: int
+    reviewer_ids: tuple[int, ...]
+    source_branch: str
+    state: State
+    symbol_keys: tuple[str, ...]
+    target_branch: str
+    title: str
+    updated_at: datetime.datetime | None
+    web_url: str
+
+    @property
+    def id(self) -> str:
+        return make_id(ActivityKind.MERGE_REQUEST, self.project_id, self.iid)
+
+    def embedding_input(self) -> tuple[str, str]:
+        """Returns the (title, text) pair to embed."""
+        return self.title, self.description
+
+    def __bson__(self) -> dict:
+        return {
+            '_id': self.id,
+            **_fields(self),
+            'confidential': False,
+            'kind': str(ActivityKind.MERGE_REQUEST),
+        }
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Discussion:
+    """One thread of human notes on an issue or merge request."""
+
+    authors: tuple[str, ...]
+    confidential: bool
+    discussion_id: str
+    notes: tuple[str, ...]
+    parent_iid: int
+    parent_kind: ActivityKind
+    parent_title: str
+    project_id: int
+    state: State
+    updated_at: datetime.datetime | None
+    web_url: str
+
+    @property
+    def id(self) -> str:
+        return make_id(
+            ActivityKind.DISCUSSION,
+            self.project_id,
+            self.parent_kind,
+            self.parent_iid,
+            self.discussion_id,
+        )
+
+    def embedding_input(self) -> tuple[str, str]:
+        """Returns the (title, text) pair to embed."""
+        return self.parent_title, '\n\n'.join(self.notes)
+
+    def __bson__(self) -> dict:
+        return {'_id': self.id, **_fields(self), 'kind': str(ActivityKind.DISCUSSION)}

monorepoly/search.py

@@ -0,0 +1,284 @@
+"""Query functions behind the MCP tools; every query is filtered by the caller's access."""
+
+import dataclasses
+import datetime
+import enum
+import logging
+from collections.abc import Callable, Sequence
+
+from monorepoly.access import Access
+from monorepoly.embed import Embedder, QueryTask
+from monorepoly.exceptions import MonorepolyValueError
+from monorepoly.judge import RELEVANCE_THRESHOLD, Judge
+from monorepoly.models import DEFAULT_REF, ActivityKind, CommitCategory, State
+from monorepoly.store import Store
+
+_LOGGER = logging.getLogger(__name__)
+
+_CANDIDATES = 30
+_HIDDEN = frozenset({'_id', 'changes', 'diff', 'embedding', 'score', 'symbol_keys'})
+_HISTORY_LIMIT = 50
+_JUDGE_TEXT_CHARS = 2_000
+_LIMIT = 10
+_RECENT = datetime.timedelta(hours=48)
+_RELATED_KINDS = (
+    ActivityKind.BRANCH,
+    ActivityKind.COMMIT,
+    ActivityKind.ISSUE,
+    ActivityKind.MERGE_REQUEST,
+)
+_SNIPPET_LINES = 40
+_TRIM_CHARS = 2_000
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class QueryContext:
+    access: Access
+    embedder: Embedder
+    judge: Judge
+    store: Store
+
+
+def search_code(*, ctx: QueryContext, project: str | None, query: str) -> list[dict]:
+    """Returns the default-branch symbols most relevant to `query`, best first."""
+    clauses = [ctx.access.symbol_filter(), {'ref': DEFAULT_REF}]
+    if project is not None:
+        project_id = ctx.store.project_id_by_path(project)
+        if project_id is None:
+            return []
+        clauses.append({'project_id': project_id})
+    conditions = {'$and': clauses}
+    docs = ctx.store.vector_search(
+        collection='symbols',
+        conditions=conditions,
+        limit=_CANDIDATES,
+        vector=ctx.embedder.query(task=QueryTask.CODE, text=query),
+    )
+    ranked = _rerank(ctx=ctx, docs=docs, query=query, text=_symbol_text)[:_LIMIT]
+    projects = ctx.store.projects_by_id({doc['project_id'] for doc in ranked})
+    return [_present_symbol(doc=doc, project=projects[doc['project_id']]) for doc in ranked]
+
+
+def find_related_work(
+    *, ctx: QueryContext, now: datetime.datetime, topic: str
+) -> dict[str, list[dict]]:
+    """Returns open or recent work by others that Jev judges to be about `topic`, by kind."""
+    conditions = {
+        '$and': [
+            ctx.access.activity_filter(),
+            {'kind': {'$in': [str(kind) for kind in _RELATED_KINDS]}},
+            {'$or': [{'state': str(State.OPENED)}, {'updated_at': {'$gte': now - _RECENT}}]},
+        ]
+    }
+    docs = ctx.store.vector_search(
+        collection='activity',
+        conditions=conditions,
+        limit=_CANDIDATES,
+        vector=ctx.embedder.query(task=QueryTask.SEARCH, text=topic),
+    )
+    others = [doc for doc in docs if _by_someone_else(access=ctx.access, doc=doc)]
+    grouped: dict[str, list[dict]] = {}
+    for doc in _rerank(ctx=ctx, docs=others, query=topic, text=_activity_text):
+        if doc['relevance'] >= RELEVANCE_THRESHOLD:
+            grouped.setdefault(doc['kind'], []).append(_present_activity(doc))
+    return grouped
+
+
+def search_history(
+    *,
+    categories: Sequence[str] | None,
+    ctx: QueryContext,
+    kinds: Sequence[str] | None,
+    query: str,
+    state: str | None,
+) -> list[dict]:
+    """Returns issues, merge requests, discussions, branches and commits relevant to `query`."""
+    clauses = [ctx.access.activity_filter()]
+    if kinds:
+        clauses.append({'kind': {'$in': [_parse(ActivityKind, kind) for kind in kinds]}})
+    if categories:
+        clauses.append({'category': {'$in': [_parse(CommitCategory, c) for c in categories]}})
+    if state:
+        clauses.append({'state': _parse(State, state)})
+    docs = ctx.store.vector_search(
+        collection='activity',
+        conditions={'$and': clauses},
+        limit=_CANDIDATES,
+        vector=ctx.embedder.query(task=QueryTask.SEARCH, text=query),
+    )
+    ranked = _rerank(ctx=ctx, docs=docs, query=query, text=_activity_text)
+    return [_present_activity(doc) for doc in ranked[:_LIMIT]]
+
+
+def symbol_history(*, ctx: QueryContext, symbol_id: str) -> list[dict]:
+    """Returns commits, branches and merge requests touching the symbol, newest first."""
+    symbols = ctx.store.find(
+        collection='symbols',
+        limit=1,
+        query={'$and': [ctx.access.symbol_filter(), {'_id': symbol_id}]},
+    )
+    if not symbols:
+        return []
+    docs = ctx.store.find(
+        collection='activity',
+        limit=_HISTORY_LIMIT,
+        query={'$and': [ctx.access.activity_filter(), {'symbol_keys': symbols[0]['key']}]},
+        sort=[('updated_at', -1)],
+    )
+    return [_present_activity(doc) for doc in docs]
+
+
+def get_item(*, ctx: QueryContext, item_id: str) -> dict | None:
+    """Returns the full symbol or activity item, with discussions for issues and MRs."""
+    # Not found and not accessible look the same, so ids of hidden items cannot be probed.
+    symbols = ctx.store.find(
+        collection='symbols',
+        limit=1,
+        query={'$and': [ctx.access.symbol_filter(), {'_id': item_id}]},
+    )
+    if symbols:
+        return symbols[0]
+    filter_ = ctx.access.activity_filter()
+    items = ctx.store.find(
+        collection='activity', limit=1, query={'$and': [filter_, {'_id': item_id}]}
+    )
+    if not items:
+        return None
+    item = items[0]
+    if item['kind'] in (ActivityKind.ISSUE, ActivityKind.MERGE_REQUEST):
+        item['discussions'] = ctx.store.find(
+            collection='activity',
+            query={
+                '$and': [
+                    filter_,
+                    {
+                        'kind': str(ActivityKind.DISCUSSION),
+                        'parent_iid': item['iid'],
+                        'parent_kind': item['kind'],
+                        'project_id': item['project_id'],
+                    },
+                ]
+            },
+            sort=[('updated_at', 1)],
+        )
+    return item
+
+
+def _rerank(
+    *,
+    ctx: QueryContext,
+    docs: list[dict],
+    query: str,
+    text: Callable[[dict], str],
+) -> list[dict]:
+    scores = ctx.judge.relevance(
+        candidates=[text(doc)[:_JUDGE_TEXT_CHARS] for doc in docs], query=query
+    )
+    for doc, score in zip(docs, scores, strict=True):
+        doc['relevance'] = score
+    return sorted(docs, key=lambda doc: doc['relevance'], reverse=True)
+
+
+def _by_someone_else(*, access: Access, doc: dict) -> bool:
+    match doc['kind']:
+        case ActivityKind.ISSUE:
+            return bool(set(doc['assignee_ids']) - {access.driver_id})
+        case ActivityKind.MERGE_REQUEST:
+            return doc['author_id'] != access.driver_id or bool(
+                set(doc['assignee_ids']) - {access.driver_id}
+            )
+        case ActivityKind.BRANCH | ActivityKind.COMMIT:
+            return doc['author_email'].lower() not in access.driver_emails
+        case kind:
+            raise MonorepolyValueError(f"Unexpected activity kind '{kind}'!")
+
+
+def _parse(enum_type: type[enum.StrEnum], value: str) -> str:
+    try:
+        return str(enum_type(value))
+    except ValueError as err:
+        allowed = ', '.join(member.value for member in enum_type)
+        raise MonorepolyValueError(f"Unknown value '{value}'; expected one of {allowed}!") from err
+
+
+def _symbol_text(doc: dict) -> str:
+    return '\n'.join(
+        filter(None, (doc['qualname'], doc['signature'], doc.get('docstring'), doc['source']))
+    )
+
+
+def _activity_text(doc: dict) -> str:
+    parts = [
+        doc.get(field) for field in ('name', 'title', 'parent_title', 'message', 'description')
+    ]
+    return '\n'.join(filter(None, [*parts, *doc.get('messages', []), *doc.get('notes', [])]))
+
+
+def _present_symbol(*, doc: dict, project: dict) -> dict:
+    lines = f'{doc["start_line"]}-{doc["end_line"]}'
+    return {
+        'docstring': doc.get('docstring'),
+        'id': doc['_id'],
+        'kind': doc['kind'],
+        'lines': lines,
+        'path': doc['path'],
+        'project_id': doc['project_id'],
+        'qualname': doc['qualname'],
+        'relevance': doc['relevance'],
+        'signature': doc['signature'],
+        'snippet': '\n'.join(doc['source'].splitlines()[:_SNIPPET_LINES]),
+        'web_url': (
+            f'{project["web_url"]}/-/blob/{project["default_branch"]}/{doc["path"]}#L{lines}'
+        ),
+    }
+
+
+def _present_activity(doc: dict) -> dict:
+    # Status first: agents otherwise read closed or abandoned work as shipped.
+    return {
+        'id': doc['_id'],
+        'status': _status(doc),
+        **{k: _trim(v) for k, v in doc.items() if k not in _HIDDEN},
+    }
+
+
+def _status(doc: dict) -> str:
+    """Returns whether the item shipped, in words an agent cannot misread."""
+    match doc['kind'], doc.get('state'):
+        case ActivityKind.MERGE_REQUEST, State.MERGED:
+            return 'merged'
+        case ActivityKind.MERGE_REQUEST, State.CLOSED:
+            return 'closed without merging'
+        case ActivityKind.MERGE_REQUEST, State.OPENED:
+            return 'open, not merged yet'
+        case ActivityKind.MERGE_REQUEST, State.LOCKED:
+            return 'locked, not merged'
+        case ActivityKind.ISSUE, State.OPENED:
+            return 'open issue'
+        case ActivityKind.ISSUE, State.CLOSED:
+            return 'closed issue'
+        case ActivityKind.DISCUSSION, _:
+            parent = _status({'kind': doc['parent_kind'], 'state': doc.get('state')})
+            article = 'an' if doc['parent_kind'] == ActivityKind.ISSUE else 'a'
+            noun = 'issue' if doc['parent_kind'] == ActivityKind.ISSUE else 'merge request'
+            return f'thread on {article} {noun}: {parent}'
+        case ActivityKind.BRANCH, State.MERGED:
+            return 'branch merged into the default branch'
+        case ActivityKind.BRANCH, _:
+            return 'unmerged branch'
+        case ActivityKind.COMMIT, _:
+            if doc.get('on_default_branch'):
+                return 'on the default branch'
+            return 'not on the default branch: unmerged or abandoned'
+        case kind, state:
+            raise MonorepolyValueError(f"Unexpected activity '{kind}' in state '{state}'!")
+
+
+def _trim(value: object) -> object:
+    match value:
+        case str() if len(value) > _TRIM_CHARS:
+            return value[:_TRIM_CHARS] + '…'
+        case list():
+            return [_trim(item) for item in value]
+        case _:
+            return value

monorepoly/skill.py

@@ -0,0 +1,23 @@
+"""Installs the bundled Claude Code skill."""
+
+import logging
+import shutil
+from importlib.resources import as_file, files
+from pathlib import Path
+
+_LOGGER = logging.getLogger(__name__)
+
+SKILLS_DIR = Path.home() / '.claude' / 'skills'
+
+_SKILLS = files('monorepoly') / 'skills'
+
+
+def install_skill(*, dry_run: bool, skills_dir: Path) -> None:
+    """Copies the bundled skills into `skills_dir`, replacing older copies."""
+    with as_file(_SKILLS) as source:
+        names = ', '.join(sorted(f"'{path.name}'" for path in source.iterdir()))
+        if dry_run:
+            _LOGGER.info("Would install skills %s into '%s'.", names, skills_dir)
+            return
+        shutil.copytree(source, skills_dir, dirs_exist_ok=True)
+    _LOGGER.info("Installed skills %s into '%s'.", names, skills_dir)

monorepoly/skills/search/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: search
+description: Use before writing new code, starting a task, filing an issue, or extending existing code in this organisation. Checks for reusable code, in-flight work by others, existing issues, and lessons from earlier attempts through the monorepoly MCP tools.
+---
+
+# Look before you build
+
+The monorepoly MCP server indexes every project in the organisation. Grepping the current
+repository is not enough: the code, issue or lesson you need is usually somewhere else.
+
+1. Before writing new code, call `search_code` with what the code should do. If something close
+   exists, call `symbol_history` on it and prefer extending it over building from scratch.
+   `search_code` covers code and config: CI jobs, Kubernetes objects, other YAML keys, TOML tables and Dockerfile stages too.
+2. Before starting any task, call `find_related_work` with the task's topic. If someone else has
+   an open merge request, branch or assigned issue on it, tell the user before you continue.
+3. Before filing an issue, call `search_history` with `kinds=["issue"]`.
+4. Before trying an approach, call `search_history` with `kinds=["merge_request", "discussion"]`
+   and `state="closed"` to find earlier attempts and why they stopped.
+5. When the user names something vaguely ("the upload thing"), call `search_code` to find out
+   which code they mean before asking them.
+
+Use `get_item` to read a full result. Cite results by their `web_url`.
+
+Every history result starts with a `status`. Read it before you say something shipped: only
+"merged", "on the default branch" and "branch merged into the default branch" mean the change
+is live. "closed without merging", "unmerged branch" and "not on the default branch" are
+abandoned or unfinished work. Say so, and check the current code with `search_code` before
+relying on them. A "closed issue" may be done or rejected (check its labels and thread).