uncoded 0.5.0__py3-none-any.whl

uncoded/serena_setup.py

@@ -0,0 +1,203 @@
+"""Generate configuration files for Serena + ty LSP integration.
+
+Writes three files that wire a repo up to Serena's MCP bridge with ty as
+the Python language-server backend, in the shape Claude Code picks up
+automatically:
+
+* ``.mcp.json`` — registers the Serena MCP server so Claude Code launches
+  it via ``uvx`` on session start, with the web dashboard disabled.
+* ``.serena/project.yml`` — selects ty over Serena's default backend
+  (pyright), keeps Serena out of uncoded's generated stubs, and narrows
+  Serena's surface to pure LSP operations: memory, onboarding,
+  dashboard, and shell-exec tools are all excluded. uncoded's namespace
+  map and stubs already give agents a project-wide view, so Serena's
+  memory-based project understanding is redundant and noisy alongside
+  it.
+* ``.claude/settings.json`` — enables the Serena server and allowlists
+  the eight LSP tools (symbol lookup, reference search, and the edit
+  family) so they run without a prompt.
+
+JSON files merge into existing content: pre-existing non-Serena MCP
+servers and permissions are preserved, while the Serena entry itself
+refreshes to the current ``SERENA_VERSION`` so re-running after a bump
+propagates the pin. The YAML project file is only written when absent,
+to avoid clobbering hand-edited Serena config.
+"""
+
+import json
+import tomllib
+from pathlib import Path
+
+from uncoded.config import find_pyproject_toml
+
+# Pin the Serena version so every repo that runs setup-serena gets the
+# same, tested integration. On bump, re-run `uncoded setup-serena` to
+# refresh the pin in existing repos — the sync overwrites the serena
+# entry in .mcp.json with the current MCP_SERVER_SERENA value. A
+# dogfooding test in tests/test_serena_setup.py guards against drift.
+SERENA_VERSION = "1.1.2"
+
+MCP_SERVER_SERENA = {
+    "command": "uvx",
+    "args": [
+        "--from",
+        f"serena-agent=={SERENA_VERSION}",
+        "serena",
+        "start-mcp-server",
+        "--context",
+        "claude-code",
+        "--transport",
+        "stdio",
+        "--project-from-cwd",
+        "--open-web-dashboard",
+        "false",
+    ],
+}
+
+SERENA_PROJECT_YML = """\
+project_name: "{project_name}"
+languages: ["python_ty"]
+ignored_paths:
+  - ".uncoded"
+excluded_tools:
+  - execute_shell_command
+  - list_memories
+  - read_memory
+  - write_memory
+  - edit_memory
+  - delete_memory
+  - rename_memory
+  - onboarding
+  - check_onboarding_performed
+  - open_dashboard
+"""
+
+SERENA_ALLOWED_TOOLS = [
+    "mcp__serena__initial_instructions",
+    "mcp__serena__find_symbol",
+    "mcp__serena__find_referencing_symbols",
+    "mcp__serena__get_symbols_overview",
+    "mcp__serena__rename_symbol",
+    "mcp__serena__safe_delete_symbol",
+    "mcp__serena__insert_before_symbol",
+    "mcp__serena__insert_after_symbol",
+    "mcp__serena__replace_symbol_body",
+]
+
+_STATUS_VERB = {
+    "wrote": "Wrote",
+    "updated": "Updated",
+    "unchanged": "Unchanged",
+}
+
+
+def read_project_name() -> str:
+    """Read the project name from pyproject.toml, falling back to the cwd name."""
+    toml_path = find_pyproject_toml()
+    if toml_path is None:
+        return Path.cwd().name
+    with toml_path.open("rb") as f:
+        data = tomllib.load(f)
+    try:
+        return data["project"]["name"]
+    except KeyError:
+        return Path.cwd().name
+
+
+def _sync_mcp_json(path: Path) -> str:
+    """Write or merge Serena into ``.mcp.json``.
+
+    Non-Serena MCP servers already in the file are preserved. The
+    ``serena`` entry itself is always refreshed to ``MCP_SERVER_SERENA``
+    so a ``SERENA_VERSION`` bump flows into existing repos on the next
+    ``setup-serena`` run. Anyone who has hand-customised the ``serena``
+    entry should keep their edits out of this file (add a sibling entry
+    instead, or re-apply after refresh).
+
+    Returns a one-word status: ``wrote``, ``updated``, or ``unchanged``.
+    """
+    if path.exists():
+        data = json.loads(path.read_text())
+        servers = data.setdefault("mcpServers", {})
+        if servers.get("serena") == MCP_SERVER_SERENA:
+            return "unchanged"
+        servers["serena"] = MCP_SERVER_SERENA
+        status = "updated"
+    else:
+        data = {"mcpServers": {"serena": MCP_SERVER_SERENA}}
+        status = "wrote"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n")
+    return status
+
+
+def _sync_serena_project(path: Path, project_name: str) -> str:
+    """Write ``.serena/project.yml`` if absent.
+
+    Returns ``wrote`` or ``unchanged``. An existing file is never touched:
+    YAML merging preserves neither comments nor key order, and a user who
+    has customised their Serena config should keep it.
+    """
+    if path.exists():
+        return "unchanged"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(SERENA_PROJECT_YML.format(project_name=project_name))
+    return "wrote"
+
+
+def _sync_claude_settings(path: Path) -> str:
+    """Write or merge Serena allowlist into ``.claude/settings.json``.
+
+    Returns ``wrote``, ``updated``, or ``unchanged``.
+    """
+    if path.exists():
+        data = json.loads(path.read_text())
+        status = "unchanged"
+    else:
+        data = {}
+        status = "wrote"
+
+    enabled = data.setdefault("enabledMcpjsonServers", [])
+    if "serena" not in enabled:
+        enabled.append("serena")
+        if status == "unchanged":
+            status = "updated"
+
+    permissions = data.setdefault("permissions", {})
+    allow = permissions.setdefault("allow", [])
+    for tool in SERENA_ALLOWED_TOOLS:
+        if tool not in allow:
+            allow.append(tool)
+            if status == "unchanged":
+                status = "updated"
+
+    if status == "unchanged":
+        return status
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n")
+    return status
+
+
+def setup_serena(root: Path | None = None) -> int:
+    """Generate Serena + ty + Claude Code configuration under ``root``.
+
+    JSON files merge into existing content, refreshing the Serena
+    entries so a re-run picks up a bumped ``SERENA_VERSION``. The
+    Serena YAML project file is only written when absent.
+    """
+    if root is None:
+        root = Path.cwd()
+    project_name = read_project_name()
+
+    mcp_path = root / ".mcp.json"
+    serena_path = root / ".serena" / "project.yml"
+    claude_path = root / ".claude" / "settings.json"
+
+    results = [
+        (mcp_path, _sync_mcp_json(mcp_path)),
+        (serena_path, _sync_serena_project(serena_path, project_name)),
+        (claude_path, _sync_claude_settings(claude_path)),
+    ]
+    for path, status in results:
+        print(f"{_STATUS_VERB[status]} {path.relative_to(root)}")
+    return 0

uncoded/skill.py

@@ -0,0 +1,388 @@
+"""Generate the coherence-review skill file for the target repository."""
+
+from pathlib import Path
+
+from uncoded.sync import remove_file, sync_file
+
+SKILL_OUTPUTS = [
+    Path(".claude/skills/coherence-review/SKILL.md"),  # Claude Code
+    Path(".agents/skills/coherence-review/SKILL.md"),  # Codex
+]
+
+LEGACY_SKILL_OUTPUTS = [
+    Path(".claude/skills/uncoded-review/SKILL.md"),  # Claude Code
+    Path(".agents/skills/uncoded-review/SKILL.md"),  # Codex
+]
+
+_SKILL_CONTENT = """\
+---
+name: coherence-review
+description: "Perform a coherence review of a Python codebase: a diagnostic sweep \
+for semantic drift, naming inconsistency, promissory mismatch, and structural \
+incoherence. Produces a Markdown report of findings with verbatim evidence and \
+confidence levels, for human investigation. Assumes uncoded is installed \
+(.uncoded/namespace.yaml and .uncoded/stubs/ present)."
+---
+
+# Coherence Review
+
+A diagnostic sweep of a Python codebase for specific, observable symptoms of
+semantic drift and incoherence. Output is a structured Markdown report of
+candidate regions, each with verbatim evidence and a confidence level, for a
+human to investigate. Not a bug hunt, not a lint pass, not a refactor.
+
+## Why coherence, and what you are looking for
+
+A codebase accumulates corruption differently from how it accumulates bugs. Bugs
+announce themselves — tests fail, users complain, exceptions raise. Corruption
+passes every integrity check. It is the slow divergence between what the code
+claims to mean and what it actually does, between how one part of the codebase
+names a concept and how another names the same concept, between an architecture
+as declared and an architecture as practised. Each local decision that
+contributed to it was reasonable. The accumulation is not.
+
+Corruption's one observable signature is **internal inconsistency**. Not
+absolute wrongness — that requires a reference outside the code, which is not
+available here. Just pairwise disagreement between things that ought to agree:
+a name and its behaviour, two names for the same concept, a docstring and the
+signature it sits on, a declared architecture and the actual import graph. Every
+symptom in the sweeps below is a form of inconsistency. The review's job is to
+find these disagreements — not to diagnose root cause and not to fix them.
+
+## What this skill is not
+
+- **Not a bug-finder.** Bugs are the job of testing and code review. A coherence
+  review can run on code that passes every test and still find plenty.
+- **Not a style pass.** Tabs versus spaces, docstring format, import ordering —
+  irrelevant. Linters exist.
+- **Not a refactor.** No proposing fixes, no suggesting renames, no rewriting
+  code. The output is findings. The human decides what to do with them.
+- **Not a general code review.** Performance, security, correctness — out of
+  scope unless they happen to manifest as a coherence symptom.
+
+## Prerequisites
+
+Verify by reading `.uncoded/namespace.yaml` — if it exists and is non-empty,
+proceed. If not, stop and tell the user to run `uncoded sync` first; the review
+depends on the index.
+
+If Serena MCP tools are available (`mcp__serena__*`), the structural sweep has
+more leverage. The review still works without Serena but will be weaker on
+cross-file reference checks.
+
+## Workflow
+
+The review proceeds in four sweeps, each building on the previous:
+
+1. **Orient** — load the navigation index and form a mental map.
+2. **Lexical sweep** — read the namespace, look for naming-level inconsistency.
+3. **Promissory sweep** — read stubs, check each symbol's name / signature /
+   docstring for internal disagreement.
+4. **Structural sweep** — combine namespace and imports to find boundary and
+   shape symptoms.
+
+Do the sweeps in order. Write findings as you go — do not hold them in memory
+until the end.
+
+## Step 1: Orient
+
+Read `.uncoded/namespace.yaml` in full. This is the map — directories, files,
+classes, methods, functions — in source order. Do not skim. Every public symbol
+in the codebase is listed here, and the shape of the namespace itself is
+evidence.
+
+While reading, note:
+
+- The vocabulary the codebase uses for its core concepts
+- The organisational logic (domain-driven? layered? feature-based? ad hoc?)
+- Anything that surprises you — odd names, asymmetric organisation, suspicious
+  clusters
+
+Also read `CLAUDE.md` if present, and follow any repo-specific navigation
+protocol throughout the review.
+
+Before starting the sweeps, tell the user how many public symbols were indexed.
+Then proceed without asking for further confirmation.
+
+## Step 2: Lexical sweep
+
+Working from the namespace alone, look for four categories of naming-level
+symptom.
+
+**Concept duplication under different names.** The same concept referred to by
+different names in different parts of the codebase. Examples: `fetch_user`,
+`get_user`, `load_user`, `retrieve_user` all appearing as separate functions
+doing substantively the same thing. `compute_*`, `calculate_*`, `derive_*` used
+interchangeably. Two classes called `UserRecord` and `AccountProfile` that
+model the same entity.
+
+Detection: scan the namespace for symbol clusters with verb or noun overlap.
+Where suspicion arises, spot-check the relevant stubs to confirm they overlap
+in meaning.
+
+**Qualifier accretion.** Names carrying modifiers that are fossils of
+iteration: `_new`, `_v2`, `_updated`, `_legacy`, `_real`, `_proper`, `_final`,
+`_fixed`. Also prefix forms: `new_`, `old_`, `real_`. These are almost always
+worth flagging — someone needed to distinguish a new thing from an old thing
+and the distinction was never resolved.
+
+Detection: scan the namespace for these qualifier patterns.
+
+**Vocabulary islands.** A subregion of the codebase (a directory, a module
+cluster) using a distinct vocabulary that doesn't overlap with the rest. Often
+the result of an unintegrated contribution, or a session that added a feature
+without looking outward.
+
+Detection: look for directories whose namespace entries share few word-roots
+with the rest of the codebase.
+
+**Collision with drift.** The same name appearing in multiple places with
+subtly different meanings — visible as different signatures, different docstring
+content, or different domain associations.
+
+Detection: identify name collisions in the namespace, then examine the stubs to
+see whether the uses agree.
+
+## Step 3: Promissory sweep
+
+Working from stubs, examine each public symbol's name / signature / docstring
+triple for internal disagreement.
+
+For each non-trivial public symbol (skip trivial one-liners and `__init__` with
+no meaningful body):
+
+**Name–signature mismatch.** Does the name's verb fit the signature's return? A
+function called `validate_*` that returns the validated object rather than
+raising or returning bool. A `get_*` that mutates. A noun-named thing that is a
+verb's worth of work. A boolean-returning function whose name doesn't start with
+`is_`, `has_`, `can_`, or similar.
+
+**Docstring–signature mismatch.** Does the docstring refer to parameters not in
+the signature, or fail to mention parameters that are? Does the docstring
+describe return behaviour that contradicts the type annotation?
+
+**Docstring–name mismatch.** Does the docstring describe an operation noticeably
+more specific, more general, or simply different from what the name advertises?
+"Normalises and validates the record" on a function called `check_record`.
+
+**Defensive docstrings.** Docstrings that warn about the function rather than
+describe it. "Note: this does not actually X despite the name." "Do not use
+this for Y; use Z instead." These are confessions — someone noticed drift and
+documented it rather than fixing it.
+
+The stub itself is the evidence. Quote the stub excerpt (name, signature,
+first-line docstring) verbatim in the finding.
+
+**When to read source.** The stub is usually sufficient for discovery — the
+inconsistency IS the mismatch between name, signature, and docstring, all of
+which the stub provides. Read the symbol body when a finding is already
+identified but confidence is genuinely uncertain: an undocumented parameter
+where significance depends on what it controls; a name–behaviour mismatch where
+the stub alone doesn't confirm it; a defensive docstring you want to verify is
+accurate. Use Serena's `find_symbol` with `include_body=True` — targeted to the
+symbol, no offset arithmetic, no risk of over-reading. Never read a whole source
+file during this sweep.
+
+## Step 4: Structural sweep
+
+Combine the namespace with the import graph and, if available, Serena's
+reference resolution.
+
+**Overgrown public surfaces / god modules.** A module or class whose public
+namespace is much larger than its siblings, or spans obviously different
+concerns. Look for outlier symbol counts: a file with forty public symbols where
+its neighbours have five; a class with thirty methods covering multiple domains.
+
+**Boundary violations.** One module importing private symbols (leading
+underscore) from another. Scan `from module import _thing` patterns across
+stubs' import sections. Each instance is a finding.
+
+**Cross-vocabulary imports.** Imports that cross domain boundaries in suspicious
+directions — a `core/` or `utils/` module importing from a specific business
+domain; a module in domain A importing from domain B when those domains appear
+meant to be independent. Flag candidates and note the direction; let the human
+decide.
+
+**Zero-caller public symbols.** A public symbol (no leading underscore) with no
+references anywhere in the codebase. Either dead code or an unused API surface.
+
+Check systematically, not by spot-check:
+
+1. From the namespace map, list all public symbols in each source module.
+2. Cross-reference with stub import sections — any symbol imported by another
+   source module is live; remove it from the candidate list. This culls the
+   obvious cases cheaply.
+3. For remaining candidates, use Serena's `find_referencing_symbols` to verify.
+   If Serena is unavailable, note findings as lower confidence.
+4. Distinguish two sub-cases when reporting:
+   - *No callers anywhere* — dead code; highest priority.
+   - *Callers only in tests* — the symbol is tested but not used in source;
+     may be an exposed internal that should be private.
+
+**Redundant public surface.** A public constant and a public parameterless
+function in the same module where the function's sole body is `return
+<constant>`. Both symbols being public exposes an implementation detail
+unnecessarily — only one needs to be public. Detection: use the stubs to find
+public parameterless functions near public constants, then verify each
+candidate body with Serena's `find_symbol` with `include_body=True` before
+reporting.
+
+## Report format
+
+Save the report as `.uncoded/reviews/YYYY-MM-DD-HHMMSS.md`, using today's date
+and current time (timestamped to preserve multiple runs on the same day).
+Create the directory if it does not exist.
+
+Use this structure:
+
+```markdown
+# Coherence Review — <repo name>
+
+**Date:** YYYY-MM-DD
+**Symbols indexed:** N
+**Sweeps run:** lexical, promissory, structural
+**Findings:** N total (N lexical · N promissory · N structural)
+
+## Priority regions
+
+Regions with two or more findings — examine these first:
+
+- `path/to/file.py` — N findings
+- ...
+
+*(Omit this section if no region has more than one finding.)*
+
+## Findings
+
+### 1 · <symptom summary>
+
+**Category:** lexical | promissory | structural
+**Symptom:** concept-duplication | qualifier-accretion | vocabulary-island |
+  collision-with-drift | name-signature-mismatch | docstring-signature-mismatch |
+  docstring-name-mismatch | defensive-docstring | god-module |
+  boundary-violation | cross-vocabulary-import | zero-caller
+**Location:** `path/to/file.py` · `ClassName/method_name`
+**Confidence:** high | medium | low
+
+**Evidence:**
+> Verbatim quote from namespace.yaml, stub, or import statement.
+
+One or two sentences describing the inconsistency. Not a diagnosis. Not a fix.
+
+---
+
+### 2 · ...
+```
+
+## Principles
+
+**Coverage, not filtering.** Report every finding at its confidence level. Do
+not silently drop findings judged low-severity. A low-confidence finding with
+clear evidence is useful — the human can filter. A dropped finding is not.
+
+**Confidence is part of the finding, not a gate.**
+
+- `high` — the inconsistency is explicit; evidence is directly in the stub or
+  namespace
+- `medium` — strongly implied but depends on judgement about intent
+- `low` — pattern-based suspicion that needs human interpretation
+
+**Evidence must be verbatim.** Quote the relevant namespace line, stub excerpt,
+or import statement exactly. A finding the human cannot quickly verify is worse
+than no finding.
+
+**One finding per inconsistency.** If a single symbol has a name–signature
+mismatch and a docstring–name mismatch, that is two findings on the same
+symbol, not one combined finding. Let the report show the density.
+
+**Do not propose fixes.** No renaming suggestions, no refactoring proposals, no
+"this should be moved to". The finding describes what is inconsistent. The
+human owns remediation.
+
+**Do not flag style.** Docstring format, type annotation style, import ordering,
+naming conventions — out of scope. Coherence is about semantic consistency, not
+surface consistency.
+
+**Do not fabricate.** Every finding must be anchored to code you actually
+examined. If a sweep suggests a pattern but you cannot find concrete instances,
+do not include it.
+
+## Scope control
+
+If the codebase has more than ~1000 public symbols:
+
+1. Complete the lexical sweep in full (the namespace is compact enough).
+2. For the promissory sweep, prioritise: core domain modules (identified from
+   the namespace structure), any module that appeared in a lexical finding, and
+   a representative sample of the rest (~30% of remaining stubs).
+3. For the structural sweep, focus on the module and package level first,
+   descending to individual symbols only where the higher-level scan raised
+   flags.
+
+Note the scope chosen in the report summary so the human knows what was and was
+not examined.
+
+## Examples
+
+<example>
+<scenario>Three public functions: `fetch_user(id)`, `get_user_by_id(id)`,
+`load_user(user_id)`, in three different files, all returning a User and all
+doing substantively the same lookup.</scenario>
+<flag>Yes. Concept duplication, high confidence. Evidence: three stub excerpts
+quoted verbatim.</flag>
+</example>
+
+<example>
+<scenario>A function `validate_user(user)` whose signature returns `User` rather
+than `bool` or `None`, and whose docstring says "Validates and returns the user
+if valid, raising UserValidationError otherwise."</scenario>
+<flag>Yes. Name–signature mismatch, medium confidence. The name reads as a
+predicate but the behaviour is a validator-filter. Stub quoted as
+evidence.</flag>
+</example>
+
+<example>
+<scenario>Two modules, `storage/cache.py` and `runtime/memoize.py`, both
+defining functions that wrap callables with LRU caching, with slightly different
+cache-size defaults.</scenario>
+<flag>Yes. Concept duplication, medium confidence. Both stubs quoted. Note the
+difference — the human may determine it is intentional.</flag>
+</example>
+
+<example>
+<scenario>A class `OrderProcessor` with 34 methods spanning order creation,
+validation, payment capture, fulfilment dispatch, refund handling, and
+reporting.</scenario>
+<flag>Yes. God module, high confidence. Method list quoted from
+namespace.</flag>
+</example>
+
+<example>
+<scenario>A function uses `x` as a parameter name in a mathematical formula
+module.</scenario>
+<flag>No. Short variable names in mathematical contexts are conventional and do
+not indicate drift.</flag>
+</example>
+
+<example>
+<scenario>A function is 80 lines of non-trivial logic.</scenario>
+<flag>No, not by itself. Complexity is not incoherence. Flag only if the
+complexity manifests as inconsistency — e.g. the function's behaviour has
+drifted from what its name or docstring promise.</flag>
+</example>
+
+<example>
+<scenario>The codebase uses both `Optional[X]` and `X | None` in different
+files.</scenario>
+<flag>No. Both are valid Python and mean the same thing. Flag only if the
+semantics of absence differ — e.g. some functions return None on failure while
+others raise, for the same kind of operation.</flag>
+</example>
+"""
+
+
+def sync_skill(*, check: bool) -> bool:
+    """Write the coherence-review skill file to all supported agent locations."""
+    results = [sync_file(path, _SKILL_CONTENT, check=check) for path in SKILL_OUTPUTS]
+    results.extend(remove_file(path, check=check) for path in LEGACY_SKILL_OUTPUTS)
+    return any(results)