code-context-control 2.121.0__tar.gz → 2.123.0__tar.gz

{code_context_control-2.121.0/code_context_control.egg-info → code_context_control-2.123.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.121.0
+Version: 2.123.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.121.0 → code_context_control-2.123.0}/cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.121.0"
+__version__ = "2.123.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -271,7 +271,7 @@ _STALE_MCP_TOOLS = {
     "mcp__c3__c3_remember",           # → c3_memory(action='add')
     "mcp__c3__c3_recall",             # → c3_memory(action='recall')
     "mcp__c3__c3_sltm_add",           # → c3_memory(action='add')
-    "mcp__c3__c3_file_map",           # → c3_compress(mode='map')
+    "mcp__c3__c3_file_map",           # → c3_read(file_path) map
     "mcp__c3__c3_extract",            # → c3_read
     "mcp__c3__c3_transcript_search",  # → c3_search(action='transcript')
     "mcp__c3__c3_session_log",        # → c3_session(action='log')
@@ -3971,7 +3971,7 @@ def cmd_benchmark(args):
             "prompt_budget_multiplier": round(_prompt_gain(comp_comp, comp_orig), 2),
         },
         "file_navigation": {
-            "description": "Use c3_compress(mode='map') to choose targeted reads instead of opening whole files blindly.",
+            "description": "Use the c3_read file map to choose targeted reads instead of opening whole files blindly.",
             "performance_metric": "map success rate",
             "with_c3": {"tool": "c3_compress(mode='map')", "total_tokens": file_map_comp, "avg_latency_ms": round(_avg(file_map_c3_latencies), 2), "performance": round((file_map_successes / len(file_map_sample) * 100), 1) if file_map_sample else 0.0},
             "without_c3": {"approach": "read full files into context", "total_tokens": file_map_orig, "avg_latency_ms": round(_avg(file_map_baseline_latencies), 2), "performance": 100.0},
@@ -5005,7 +5005,7 @@ back to native tools as the task progresses.
 
 ## Quick Reference
 - **Search**: `c3_search(query=..., action='code|files|semantic')` — before Grep/Glob
-- **Read**: `c3_compress(mode='map')` then `c3_read(symbols=...)` — before native Read
+- **Read**: `c3_read(file_path)` maps a file (or directory), then `c3_read(symbols=['Class.method'])` — before native Read
 - **Impact**: `c3_impact(target='symbol')` — blast-radius check before editing shared symbols
 - **Edit**: `c3_edit(file_path=..., old_string=..., new_string=...)` — before Edit/Write
 - **Validate**: `c3_validate(file_path=...)` — after every edit (pyright/tsc type check if installed)

{code_context_control-2.121.0 → code_context_control-2.123.0}/cli/commands/common.py

@@ -72,7 +72,7 @@ def cmd_index(args, deps: CommandDeps):
 def cmd_compress(args, deps: CommandDeps):
     """Compress a file and show results."""
     config = deps.load_config()
-    mode = args.mode or "smart"
+    mode = args.mode or "map"
 
     compressor = deps.CodeCompressor(str(Path(config.get("project_path", ".")) / ".c3/cache"))
     result = compressor.compress_file(args.file, mode)

{code_context_control-2.121.0 → code_context_control-2.123.0}/cli/commands/parser.py

@@ -91,7 +91,8 @@ def build_parser(version: str, parse_cli_ide_arg):
 
     p_compress = subparsers.add_parser("compress", help="Compress a file")
     p_compress.add_argument("file", help="File to compress")
-    p_compress.add_argument("--mode", choices=["map", "dense_map", "smart", "diff"], default="smart")
+    p_compress.add_argument("--mode", choices=["map", "smart", "structure", "outline"], default="map",
+                            help="map (default) is the canonical file map; the others are signature summaries")
     p_compress.add_argument("--output", "-o", action="store_true", help="Show compressed output")
 
     p_context = subparsers.add_parser("context", help="Get relevant context for a query")

{code_context_control-2.121.0 → code_context_control-2.123.0}/cli/guide/index.html

@@ -636,7 +636,7 @@
             <span>Discover files / content — never start with Grep/Glob</span>
           </div>
           <div class="quick-item">
-            <code>3. c3_compress(mode='map') + c3_read(symbols=…)</code>
+            <code>3. c3_read(file_path) + c3_read(symbols=…)</code>
             <span>Map then surgically read — never start with native Read</span>
           </div>
           <div class="quick-item">

{code_context_control-2.121.0 → code_context_control-2.123.0}/cli/guide/workflow.html

@@ -315,7 +315,7 @@
           <tr>
             <td><span class="badge badge-blue">3</span></td>
             <td><strong>Map + Read</strong></td>
-            <td><code>c3_compress(mode='map')</code> → <code>c3_read(symbols=…)</code></td>
+            <td><code>c3_read(file_path)</code> (map) → <code>c3_read(symbols=…)</code></td>
             <td>Before reading any file content</td>
           </tr>
           <tr>

{code_context_control-2.121.0 → code_context_control-2.123.0}/cli/hook_pretool_enforce.py

@@ -130,7 +130,7 @@ _VAULT_FILES = frozenset({"config.json", "secrets.enc", "cred_state.json",
 # Redirect messages per native tool
 _REDIRECTS = {
     "Read": (
-        "Use c3_compress(file_path='...', mode='map') to map the file first, "
+        "Use c3_read(file_path='...') to map the file first (one line per symbol), "
         "then c3_read(file_path='...', symbols=['...']) for surgical extraction."
     ),
     "Grep": (

code_context_control-2.123.0/cli/tools/compress.py

@@ -0,0 +1,251 @@
+"""c3_compress — the canonical file map (services/file_map.render_map), one file or a batch.
+
+There is one mode, `map`, and it is the same text c3_read(file_path) serves.
+The modes that existed before 2.122.0 (dense_map, smart, diff, bug_scan,
+ast, structure, outline) were called twice in 3,932 tool calls; a request
+for one of them is answered with the map plus a one-line notice so an old
+prompt keeps working while it says so (docs/file-map.md § Retired modes).
+"""
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+from cli.tools import _grants
+from cli.tools._helpers import finalize_with_tokens, show_token_ratios
+from core import count_tokens
+from services import access_guard
+
+#: Every mode name c3_compress ever accepted, and what to say about it now.
+RETIRED_MODES = {
+    "dense_map": "the map is dense now",
+    "smart": "the map carries full signatures",
+    "structure": "the map carries full signatures",
+    "outline": "the map carries full signatures",
+    "diff": "use `git diff` or the edit ledger (c3_edits)",
+    "bug_scan": "use c3_search(action='exact', query='except ') for handler hotspots",
+    "ast": "project architecture: codebase-memory-mcp `cli get_architecture`, or c3_status",
+}
+RETIRED_IN = "2.122.0"
+
+
+def deprecation_line(requested: str) -> str:
+    hint = RETIRED_MODES.get(requested, "")
+    return (f"[compress:deprecated] mode '{requested}' retired in {RETIRED_IN} — "
+            f"map is the only mode ({hint}); see docs/file-map.md")
+
+
+def map_detail(svc, rel: str, requested_mode: str, *, cache_hit: bool,
+               symbols: int = 0, fallback: str = "") -> dict:
+    """Telemetry `detail` for a map served from file_memory (C0, 2.120.0).
+
+    backend names the code path, parser the extractor that built the record
+    (tree_sitter | regex | generic, "" for a pre-2.120.0 record), cache_hit
+    whether the record was already fresh. `symbols` is how many the caller
+    asked for and `fallback` why a read served a map instead of source.
+    `deprecated_mode` (2.122.0) is set when a retired mode name was asked for.
+    Flat so telemetry.aggregate_tool_telemetry can fold it without a schema.
+    """
+    record = None
+    try:
+        record = svc.file_memory.get(rel)
+    except Exception:
+        record = None
+    if not isinstance(record, dict):
+        record = None
+    detail = {
+        "requested_mode": requested_mode,
+        "backend": "file_memory",
+        "parser": str((record or {}).get("parser") or ""),
+        "cache_hit": bool(cache_hit),
+        "sections": len((record or {}).get("sections") or []),
+    }
+    if symbols:
+        detail["symbols"] = int(symbols)
+    if fallback:
+        detail["fallback"] = fallback
+    if requested_mode not in ("map", "read"):
+        detail["deprecated_mode"] = requested_mode
+    return detail
+
+
+def handle_compress(file_path: str, mode: str, svc,
+                    finalize, maybe_facts) -> str:
+    requested = (mode or "map").strip() or "map"
+    if requested != "map" and requested not in RETIRED_MODES:
+        return finalize("c3_compress", {"file_path": file_path, "mode": requested},
+                        f"[compress:error] Unknown mode '{requested}'. The only mode is 'map'.",
+                        "error")
+    note = deprecation_line(requested) if requested != "map" else ""
+
+    # Batch dispatch: comma-separated paths
+    if "," in file_path:
+        paths = [p.strip() for p in file_path.split(",") if p.strip()]
+        return _compress_batch(paths, requested, note, svc, finalize)
+
+    return _compress_single(file_path, requested, note, svc, finalize)
+
+
+def _build_map(svc, rel: str) -> str:
+    """The canonical map for `rel`, draining any queued watcher updates first."""
+    queued = svc.file_memory.drain_queue()
+    completed = []
+    failed = []
+    for qp in queued[:10]:
+        try:
+            if svc.file_memory.update(qp):
+                completed.append(qp)
+            else:
+                failed.append(qp)
+        except Exception:
+            failed.append(qp)
+    if completed:
+        svc.file_memory.complete_updates(completed)
+    if failed:
+        svc.file_memory.complete_updates(failed, failed=True)
+    return svc.file_memory.get_or_build_map(rel)
+
+
+def _compress_single(file_path: str, requested: str, note: str, svc, finalize) -> str:
+    """Map a single file."""
+    # Access Guard: read verdict up front (docs/access-guard.md §3).
+    _verdict = access_guard.verdict(file_path, "read", svc.project_path)
+    if _verdict.denial and not _grants.allow(svc, _verdict.denial,
+                                             tool="c3_compress", op="read",
+                                             path=file_path):
+        return finalize("c3_compress", {"file_path": file_path, "mode": requested},
+                        access_guard.refusal(_verdict.denial, file_path, "read"),
+                        "access-denied")
+    # Mask Guard: the map is built through file_memory, which reads the RAW
+    # file — a masked path is served from its view instead
+    # (docs/mask-guard.md §6, row 7).
+    if _verdict.masked:
+        from services import mask_mirror
+        try:
+            view = mask_mirror.render_for_path(file_path, svc.project_path)
+        except mask_mirror.MaskUnavailable as exc:
+            return finalize("c3_compress",
+                            {"file_path": file_path, "mode": requested},
+                            f"{access_guard.TAG_MASK_UNSUPPORTED} {exc.message}",
+                            "mask-unavailable")
+        return finalize("c3_compress", {"file_path": file_path, "mode": requested},
+                        view.with_header(file_path), f"masked:{view.preset}")
+
+    full = Path(svc.project_path) / file_path
+    if not full.exists():
+        full = Path(file_path)
+    if not full.exists():
+        return ("[file_map:error] not found. To create a new file use "
+                "c3_edit(file_path=..., old_string='', new_string=<content>).")
+    rel = str(full.resolve().relative_to(Path(svc.project_path).resolve())).replace("\\", "/")
+    # C0 measurement: was the record already fresh before this call?
+    cache_hit = not svc.file_memory.needs_update(rel)
+    res = _build_map(svc, rel)
+    raw_tokens = None
+    map_tokens = 0
+    try:
+        raw_text = full.read_text(encoding="utf-8", errors="replace")
+        raw_tokens = count_tokens(raw_text)
+        map_tokens = count_tokens(res)
+        if map_tokens >= raw_tokens and not res.startswith("[file_map]"):
+            # A map that costs more than the file is worth nothing
+            # (docs/file-map.md § Small files).
+            res = f"[compress:{file_path}] whole file — smaller than its map\n" + raw_text
+            map_tokens = count_tokens(res)
+        summary = "map"
+    except Exception:
+        summary = "mapped"
+    if note:
+        res = note + "\n" + res
+        map_tokens = count_tokens(res)
+    return finalize_with_tokens(
+        finalize, svc, "c3_compress", {"file_path": file_path, "mode": requested},
+        res, summary,
+        raw_tokens=raw_tokens, optimized_tokens=map_tokens or None,
+        response_tokens=map_tokens,
+        detail=map_detail(svc, rel, requested, cache_hit=cache_hit))
+
+
+def _compress_batch(paths: list, requested: str, note: str, svc, finalize) -> str:
+    """Map several files in parallel, return one combined report."""
+    max_files = 10
+    paths = paths[:max_files]
+
+    results = {}
+
+    def _do_one(fp):
+        """Returns (fp, map_text, raw_tokens, map_tokens, error)."""
+        try:
+            # Access Guard: per-member read verdict — the S1 refusal becomes
+            # this member's batch line; other members are still served.
+            _v = access_guard.verdict(fp, "read", svc.project_path)
+            if _v.denial:
+                return fp, None, None, None, access_guard.refusal(_v.denial, fp,
+                                                                  "read")
+            if _v.masked:
+                from services import mask_mirror
+                try:
+                    view = mask_mirror.render_for_path(fp, svc.project_path)
+                except mask_mirror.MaskUnavailable as exc:
+                    return fp, None, None, None, \
+                        f"{access_guard.TAG_MASK_UNSUPPORTED} {exc.message}"
+                text = view.with_header(fp)
+                return fp, text, None, count_tokens(text), None
+            full = Path(svc.project_path) / fp
+            if not full.exists():
+                full = Path(fp)
+            if not full.exists():
+                return fp, None, None, None, "not found"
+            rel = str(full.resolve().relative_to(
+                Path(svc.project_path).resolve())).replace("\\", "/")
+            res = svc.file_memory.get_or_build_map(rel)
+            try:
+                raw_tok = count_tokens(full.read_text(encoding="utf-8", errors="replace"))
+                map_tok = count_tokens(res)
+                return fp, res, raw_tok, map_tok, None
+            except Exception:
+                return fp, res, None, None, None
+        except Exception as e:
+            return fp, None, None, None, str(e)
+
+    with ThreadPoolExecutor(max_workers=min(len(paths), 8)) as pool:
+        futures = {pool.submit(_do_one, fp): fp for fp in paths}
+        for fut in as_completed(futures):
+            fp, text, raw_tok, opt_tok, err = fut.result()
+            results[fp] = (text, raw_tok, opt_tok, err)
+
+    ratios = show_token_ratios(svc)
+    parts = []
+    total_ok = 0
+    total_raw = 0
+    total_opt = 0
+    measured = 0
+    for fp in paths:
+        text, raw_tok, opt_tok, err = results.get(fp, (None, None, None, "unknown"))
+        if text:
+            tag = ""
+            if raw_tok is not None and opt_tok is not None:
+                measured += 1
+                total_raw += raw_tok
+                total_opt += opt_tok
+                if ratios:
+                    tag = f" ({raw_tok}->{opt_tok}tok)"
+            parts.append(f"## {fp}{tag}\n{text}")
+            total_ok += 1
+        else:
+            parts.append(f"## {fp} — ERROR: {err}")
+
+    header = f"[compress:batch] {total_ok}/{len(paths)} files (map)"
+    if note:
+        header = note + "\n" + header
+    body = header + "\n\n" + "\n\n".join(parts)
+    detail = {"requested_mode": requested, "backend": "batch",
+              "files": len(paths), "ok": total_ok}
+    if requested != "map":
+        detail["deprecated_mode"] = requested
+    return finalize_with_tokens(
+        finalize, svc, "c3_compress",
+        {"file_path": ",".join(paths), "mode": requested, "batch": True},
+        body, f"batch {total_ok}/{len(paths)}",
+        raw_tokens=total_raw if measured else None,
+        optimized_tokens=total_opt if measured else None,
+        detail=detail)

{code_context_control-2.121.0 → code_context_control-2.123.0}/cli/tools/read.py

@@ -177,6 +177,22 @@ def handle_read(file_path: str, symbols: Any = None, lines: Any = None,
 
     rel_path = str(full.resolve().relative_to(Path(svc.project_path).resolve())).replace("\\", "/")
 
+    if full.is_dir():
+        # A directory maps to one line per file, budgeted
+        # (docs/file-map.md § Directories). `lines=<int>` sets the budget.
+        from services.dir_map import DEFAULT_MAX_TOKENS, render_directory_map
+        budget = DEFAULT_MAX_TOKENS
+        if isinstance(lines, int) and not isinstance(lines, bool) and lines > 0:
+            budget = lines
+        text, dir_detail = render_directory_map(svc, rel_path, max_tokens=budget)
+        tok = count_tokens(text)
+        if finalize is None:
+            return text
+        return finalize_with_tokens(
+            finalize, svc, "c3_read", {"file": file_path}, text,
+            f"dir:{dir_detail['files']}files->{tok}tok",
+            optimized_tokens=tok, response_tokens=tok, detail=dir_detail)
+
     # Resolve ranges
     ranges = []
 

{code_context_control-2.121.0 → code_context_control-2.123.0/code_context_control.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.121.0
+Version: 2.123.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.121.0 → code_context_control-2.123.0}/code_context_control.egg-info/SOURCES.txt

@@ -217,6 +217,7 @@ services/conversation_store.py
 services/cred_audit.py
 services/cred_telemetry.py
 services/credential_store.py
+services/dir_map.py
 services/doc_index.py
 services/e2e_benchmark.py
 services/e2e_evaluator.py
@@ -345,6 +346,7 @@ tests/test_credentials_tool.py
 tests/test_creds_cli_smoke.py
 tests/test_delegate_cascade.py
 tests/test_delegate_version_probe.py
+tests/test_dir_map_c3.py
 tests/test_e2e_benchmark.py
 tests/test_edit_ledger_deadline.py
 tests/test_edit_ledger_hook.py

{code_context_control-2.121.0 → code_context_control-2.123.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-context-control"
-version = "2.121.0"
+version = "2.123.0"
 description = "Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub."
 readme = "README.md"
 requires-python = ">=3.10"

{code_context_control-2.121.0 → code_context_control-2.123.0}/services/claude_md.py

@@ -32,7 +32,7 @@ When falling back, state which c3_* tool was attempted and why it was insufficie
 ## Workflow (follow this order — do not skip steps)
 1. **RECALL**: `c3_memory(action='recall')` — before any multi-step or context-dependent task. Large memory stores: use `index` first (compact list), then `fetch` for specific IDs
 2. **SEARCH FIRST**: `c3_search(action='code|files|semantic')` — before ANY file discovery or content search. Never start with Grep/Glob
-3. **MAP before READ**: `c3_compress(mode='map')` then `c3_read(symbols=...|lines=...)` — for ANY file read. Never start with native Read. Use `mode='ast'` for knowledge-graph overview (requires codebase-memory-mcp)
+3. **MAP before READ**: `c3_read(file_path)` with no symbols/lines returns the file map (one line per symbol with signature and `[La-Lb]` range, ~10% of the file's tokens; a directory path maps its files), then `c3_read(symbols=['Class.method']|lines=[a,b])` for the source you need. Never start with native Read. `c3_compress` is the same map for a comma-separated batch (legacy; removed in 2.124.0)
 4. **IMPACT** (shared symbols): `c3_impact(target='symbol')` — blast-radius check before editing any function/class used across files
 5. **EDIT via C3**: `c3_edit(file_path, old_string, new_string, summary)` — for ALL edits. Parallel across files; `edits=[]` batch for same file
 6. **FILTER**: `c3_filter(text=...)` — for terminal output >10 lines or log files
@@ -55,7 +55,7 @@ In plan mode, all c3_* read tools (search, read, compress, filter, validate, sta
 ## Anti-patterns (DO NOT do these)
 - Starting with native file search/read/grep without a prior c3_* call
 - Using native Edit when c3_edit is available
-- Reading entire files when c3_compress + c3_read would be more surgical
+- Reading entire files when a c3_read map + a symbol read would be more surgical
 - Skipping c3_validate after making edits"""
 
 # Pointer that replaces the embedded Project Context tree (v2.60.0).
@@ -73,14 +73,14 @@ C3_NANO_WORKFLOW = """\
 ## C3 Tools — MANDATORY
 Native tools BLOCKED unless c3_* called first. State reason when falling back.
 1. c3_search(action='code|files|semantic') — BEFORE any search/grep/glob
-2. c3_compress(mode='map') then c3_read(symbols=...|lines=...) — BEFORE any file read
+2. c3_read(file_path) maps a file (or directory); then c3_read(symbols=['Class.method']|lines=[a,b]) — BEFORE any file read
 3. c3_edit(file_path, old_string, new_string, summary) — for ALL edits; edits=[{...}] batch
 4. c3_filter(text='...') — output >10 lines
 5. c3_validate(file_path) — after edits
 6. c3_session(action='log'|'snapshot') — decisions / before /clear
 7. `[c3-access:confirm]` = PAUSE, not block: a human approves this exact write (agent-config files — .mcp.json, instruction docs, .claude bodies — hold by default). Read the S8 tail: wait on the request it names (c3_override(action='wait', request_id='...', timeout_s=180)), then retry once. Never retry early, never route around it.
 Plan mode: all c3_* read tools work normally — skip edit/delegate steps.
-DO NOT: start with native Read/Grep/Glob/Edit, skip c3_validate, read full files without c3_compress."""
+DO NOT: start with native Read/Grep/Glob/Edit, skip c3_validate, read full files without mapping them first."""
 
 
 # --- Per-IDE workflow adaptation ----------------------------------------------

{code_context_control-2.121.0 → code_context_control-2.123.0}/services/codex_integration.py

@@ -8,7 +8,7 @@ CODEX_WORKFLOW = """# C3 — Codex workflow
 
 Use C3 for repository intelligence and audited changes:
 1. Recall relevant project facts with c3_memory; inspect .c3/MAP.md.
-2. Find candidates with c3_search; map with c3_compress(mode='map'), then
+2. Find candidates with c3_search; map with c3_read(file_path) (no symbols), then
    read exact symbols or lines with c3_read. Check shared changes with c3_impact.
 3. Edit with c3_edit, validate with c3_validate, and record decisions with
    c3_session(action='log'). Preserve unrelated work.