codecortex 0.18.0__tar.gz → 0.19.0__tar.gz

{codecortex-0.18.0/src/codecortex.egg-info → codecortex-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.18.0
+Version: 0.19.0
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -279,7 +279,7 @@ Then it launches the exact command it registered and drives a real MCP handshake
 ```text
 v claude: registered at /Users/you/.claude.json
 
-v verified: codeintel 0.18.0 — 4 tools (code.query, code.status, code.doctor, code.map)
+v verified: codeintel 0.19.0 — 4 tools (code.query, code.status, code.doctor, code.map)
 ```
 
 If the command is not on `PATH`, or the server fails to start, install says so and exits non-zero
@@ -404,6 +404,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel doctor [project_root] [--deep] [--json]` | Diagnose per-engine health + repo index status, with a fix for each gap |
 | `codeintel map [project_root]` | Generate the `CODE_INTEL.md` orientation file |
 | `codeintel graph [project_root] [--html] [--out FILE] [--limit N]` | Emit the call graph as `{nodes,edges}` JSON, or `--html` a self-contained interactive viewer — see [docs/graph-viewer.md](docs/graph-viewer.md) |
+| `codeintel c4 [project_root] [--out DIR] [--depth N] [--scope PATH] [--include-tests] [--no-index] [--json]` | Write a LikeC4 architecture model (`.c4`) of the repo's file/directory structure and its import graph — committable, diffable, hand-editable source rather than a rendered picture. Indexes the repo first if it has no graph index. See [docs/c4.md](docs/c4.md) |
 | `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear this repo's index — **both** semantic and graph — so it's as if never indexed; `--all` wipes every repo. Recovers from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 

{codecortex-0.18.0 → codecortex-0.19.0}/README.md

@@ -242,7 +242,7 @@ Then it launches the exact command it registered and drives a real MCP handshake
 ```text
 v claude: registered at /Users/you/.claude.json
 
-v verified: codeintel 0.18.0 — 4 tools (code.query, code.status, code.doctor, code.map)
+v verified: codeintel 0.19.0 — 4 tools (code.query, code.status, code.doctor, code.map)
 ```
 
 If the command is not on `PATH`, or the server fails to start, install says so and exits non-zero
@@ -367,6 +367,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel doctor [project_root] [--deep] [--json]` | Diagnose per-engine health + repo index status, with a fix for each gap |
 | `codeintel map [project_root]` | Generate the `CODE_INTEL.md` orientation file |
 | `codeintel graph [project_root] [--html] [--out FILE] [--limit N]` | Emit the call graph as `{nodes,edges}` JSON, or `--html` a self-contained interactive viewer — see [docs/graph-viewer.md](docs/graph-viewer.md) |
+| `codeintel c4 [project_root] [--out DIR] [--depth N] [--scope PATH] [--include-tests] [--no-index] [--json]` | Write a LikeC4 architecture model (`.c4`) of the repo's file/directory structure and its import graph — committable, diffable, hand-editable source rather than a rendered picture. Indexes the repo first if it has no graph index. See [docs/c4.md](docs/c4.md) |
 | `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear this repo's index — **both** semantic and graph — so it's as if never indexed; `--all` wipes every repo. Recovers from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 

{codecortex-0.18.0 → codecortex-0.19.0/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.18.0
+Version: 0.19.0
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -279,7 +279,7 @@ Then it launches the exact command it registered and drives a real MCP handshake
 ```text
 v claude: registered at /Users/you/.claude.json
 
-v verified: codeintel 0.18.0 — 4 tools (code.query, code.status, code.doctor, code.map)
+v verified: codeintel 0.19.0 — 4 tools (code.query, code.status, code.doctor, code.map)
 ```
 
 If the command is not on `PATH`, or the server fails to start, install says so and exits non-zero
@@ -404,6 +404,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel doctor [project_root] [--deep] [--json]` | Diagnose per-engine health + repo index status, with a fix for each gap |
 | `codeintel map [project_root]` | Generate the `CODE_INTEL.md` orientation file |
 | `codeintel graph [project_root] [--html] [--out FILE] [--limit N]` | Emit the call graph as `{nodes,edges}` JSON, or `--html` a self-contained interactive viewer — see [docs/graph-viewer.md](docs/graph-viewer.md) |
+| `codeintel c4 [project_root] [--out DIR] [--depth N] [--scope PATH] [--include-tests] [--no-index] [--json]` | Write a LikeC4 architecture model (`.c4`) of the repo's file/directory structure and its import graph — committable, diffable, hand-editable source rather than a rendered picture. Indexes the repo first if it has no graph index. See [docs/c4.md](docs/c4.md) |
 | `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear this repo's index — **both** semantic and graph — so it's as if never indexed; `--all` wipes every repo. Recovers from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 

{codecortex-0.18.0 → codecortex-0.19.0}/src/codecortex.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ src/codeintel/__init__.py
 src/codeintel/__main__.py
 src/codeintel/agent_prompt.py
 src/codeintel/auth.py
+src/codeintel/c4.py
 src/codeintel/cache.py
 src/codeintel/config.py
 src/codeintel/containment.py
@@ -46,6 +47,7 @@ src/codeintel/term.py
 src/codeintel/verify.py
 src/codeintel/commands/__init__.py
 src/codeintel/commands/_common.py
+src/codeintel/commands/c4.py
 src/codeintel/commands/doctor.py
 src/codeintel/commands/gen_token.py
 src/codeintel/commands/graph.py
@@ -68,6 +70,9 @@ src/codeintel/viewer/__init__.py
 src/codeintel/viewer/graph_template.html
 tests/test_agent_prompt.py
 tests/test_backend_reaper.py
+tests/test_c4.py
+tests/test_c4_model.py
+tests/test_c4_output.py
 tests/test_cache.py
 tests/test_chunking.py
 tests/test_cli_commands.py

codecortex-0.19.0/src/codeintel/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.19.0"

{codecortex-0.18.0 → codecortex-0.19.0}/src/codeintel/__main__.py

@@ -10,15 +10,16 @@ from codeintel import __version__
 # wanted. Each entry is (command, one-line description).
 _COMMAND_GROUPS: list[tuple[str, list[tuple[str, str]]]] = [
     ("Understand your code", [
-        ("query", "Ask one question — search, callers, callees, impact, chain, symbol, hotspots"),
+        ("query", "Ask one question — changed, impact, callers, chain, search"),
         ("map", "Write CODE_INTEL.md — a committable architecture overview"),
-        ("graph", "Interactive call-graph viewer (--html), or the graph as JSON"),
+        ("graph", "Call graph of functions — self-contained HTML, no install"),
+        ("c4", "Architecture map of files/folders — LikeC4 source, needs Node"),
     ]),
     ("Set up", [
-        ("setup", "Prepare backends + index this repo (--all does everything automatable)"),
-        ("index", "Index a project for semantic search"),
-        ("install", "Register codeintel with the AI agents installed on this machine"),
-        ("prompt", "Print a paste-to-your-agent setup prompt, tailored to this machine"),
+        ("setup", "Prepare backends + index this repo (--all does it all)"),
+        ("index", "Build the index every other command reads (semantic + graph)"),
+        ("install", "Register codeintel with the AI agents on this machine"),
+        ("prompt", "Print a paste-to-your-agent setup prompt for this machine"),
     ]),
     ("Check health", [
         ("doctor", "Per-engine health + index status, with the fix for each gap"),
@@ -42,6 +43,7 @@ _MODULES = {
     "query": "query",
     "map": "map",
     "graph": "graph",
+    "c4": "c4",
     "setup": "setup",
     "index": "index",
     "install": "install",
@@ -54,13 +56,30 @@ _MODULES = {
     "gen-token": "gen_token",
 }
 
+# Deliberately NOT a second setup path. `_START_HERE` owns onboarding; these show what the tool is
+# FOR once it works. The two blocks used to disagree — one said `index` first, the other
+# `setup --all` — and neither of the numbered steps mentioned `install`, so following the "New
+# here?" list end to end produced a working CLI and an agent that still greps. README's quickstart
+# is `setup --all` -> `install` -> `query`; `_START_HERE` now matches it.
 _EXAMPLES = [
-    ("codeintel setup --all .", "prepare backends and index this repo"),
-    ("codeintel install", "register with the agents you have"),
-    ("codeintel query --op callers --target my_function", "who calls it?"),
-    ("codeintel doctor", "why is a query coming back empty?"),
+    ('codeintel query --op changed --target ""', "what do my edits break?"),
+    ("codeintel query --op callers --target foo", "who calls it?"),
+    ("codeintel graph . --html", "open the call graph"),
+    ("codeintel doctor", "why is a query empty?"),
 ]
 
+# The ordered path out of an empty state. A first-time user's problem is not "which of 15 commands"
+# but "what do I run first" — the command list answers the former and silently assumes the latter.
+_START_HERE = [
+    ("codeintel setup --all .", "backends + index this repo"),
+    ("codeintel install", "connect it to your AI agent"),
+    ("codeintel doctor", "confirm it works"),
+]
+
+
+HELP_WIDTH = 78              # the width every rendered help line must fit inside
+HELP_GUTTER_CAP = 44         # ceiling on the derived comment column (see `gutter` below)
+
 
 def render_help() -> str:
     """The `codeintel` / `codeintel help` screen: grouped, colored, with real examples.
@@ -72,10 +91,31 @@ def render_help() -> str:
     width = max(len(name) for name in _COMMANDS)
     out = [
         c.bold("codeintel") + c.dim(f" {__version__}")
-        + c.dim("  —  code intelligence for AI agents: graph + LSP + semantic search"),
+        + c.dim("  —  code intelligence for AI agents: graph, LSP, semantic"),
         "",
         c.dim("usage: ") + "codeintel <command> [options]",
     ]
+
+    # ONE comment column across both blocks, derived from the widest entry in either. Two blocks
+    # each self-aligning would ragged the screen into two gutters; the numbered prefix ("1. ") is
+    # part of the measured width so the two blocks' comments still line up.
+    # Capped. Derived-from-content is right, but an unbounded max lets ONE long invocation set the
+    # column for every short row: `codeintel doctor` was paying 38 blank columns and the line
+    # reached 96 chars, so an 80-column terminal wrapped the comment onto its own ragged row —
+    # losing the alignment the gutter exists to create. Past the cap a row keeps its comment one
+    # space away rather than aligned; a ragged row beats a wrapped screen.
+    gutter = min(max(max(len(cmd) + 3 for cmd, _why in _START_HERE),
+                     max(len(cmd) for cmd, _why in _EXAMPLES)) + 2, HELP_GUTTER_CAP)
+    out.append("")
+    # A rule, not a new colour: cyan already means "this is a command name" on this screen, and
+    # diluting that costs more than it buys. The block needed separating from the four command
+    # groups below it — it was bold at the same weight and indent as every group heading, so the
+    # one block a first-time user needs looked like part of the reference list.
+    out.append("  " + c.rule(40))
+    out.append("  " + c.bold("New here?"))
+    for i, (cmd, why) in enumerate(_START_HERE, 1):
+        out.append("    " + f"{i}. {cmd}".ljust(gutter) + c.dim("# " + why))
+
     for group, items in _COMMAND_GROUPS:
         out.append("")
         out.append("  " + c.bold(group))
@@ -84,11 +124,11 @@ def render_help() -> str:
 
     out.append("")
     out.append("  " + c.bold("Examples"))
-    # Width from the content, not a guess — a hardcoded column silently loses its gutter the moment
-    # one example grows past it, and ljust() will not pad below the string's own length.
-    cmd_width = max(len(cmd) for cmd, _why in _EXAMPLES) + 2
+    # Same `gutter` as the New here? block above — width from the content, not a guess. A hardcoded
+    # column silently loses its gutter the moment one example grows past it, and ljust() will not
+    # pad below the string's own length.
     for cmd, why in _EXAMPLES:
-        out.append("    " + cmd.ljust(cmd_width) + c.dim("# " + why))
+        out.append("    " + cmd.ljust(gutter) + c.dim("# " + why))
 
     out.append("")
     out.append("  " + c.dim("codeintel <command> --help") + "   full options for one command")
@@ -118,7 +158,111 @@ def _unknown_command(name: str) -> int:
     return 2
 
 
-def main() -> None:
+# `epilog` text for each subcommand: WHEN to reach for it, and one real invocation. The top-level
+# screen (`render_help`) has grouped output, colour and examples; every `codeintel <cmd> --help`
+# one level down was still stock argparse — flags listed, purpose unexplained, no example. A flag
+# list answers "what can I pass"; it never answers "should I be running this at all".
+#
+# Kept as a table rather than inline `epilog=` kwargs so the wording of every screen is reviewable
+# in one place, and so a command added without an entry degrades to today's behaviour (no epilog)
+# rather than breaking.
+_EPILOGS: dict[str, str] = {
+    "index": """examples:
+  codeintel index .                     index this repo (semantic + graph)
+  codeintel index ~/src/other-repo      index a repo elsewhere
+
+Run this first, and again after big changes. `codeintel status` shows index
+age.""",
+    "query": """examples:
+  codeintel query --op changed
+  codeintel query --op search
+  codeintel query --op impact
+  codeintel query --op callers
+  codeintel query --op chain
+  codeintel query --op overview --target ""
+
+`overview`, `changed` and `hotspots` ignore --target. Prefer this over grep:
+results are ranked by graph importance, not by match order.""",
+    "map": """examples:
+  codeintel map .                       write CODE_INTEL.md
+  codeintel map . --inject              also point CLAUDE.md / AGENTS.md at it
+
+A committable, readable architecture overview — for agents that do not speak
+MCP, and for reading before grepping. Re-run after `codeintel index`.""",
+    "graph": """examples:
+  codeintel graph . --html
+  codeintel graph . > graph.json        the graph as {nodes,edges} JSON
+
+Function-level "what calls what", with nothing to install. For file-level
+architecture instead, see `codeintel c4`.""",
+    "c4": """examples:
+  codeintel c4 .                        write codeintel-c4/model.c4
+  codeintel c4 . --scope src            model only src/
+  codeintel c4 . --depth 2              coarser: fewer, larger boxes
+  codeintel c4 . --json                 inspect the payload, write nothing
+
+File/directory-level "what depends on what". Emits LikeC4 source you can
+commit, diff and hand-edit — viewing it needs Node (`npx likec4 start
+codeintel-c4`). For function-level calls, or if you have no Node, use
+`codeintel graph --html` instead. Indexes the repo first if needed.""",
+    "status": """examples:
+  codeintel status
+
+Shows which of the three engines are ready. If one is not, `codeintel doctor`
+says how to fix it.""",
+    "doctor": """examples:
+  codeintel doctor
+  codeintel doctor --deep
+
+Run this when a query comes back empty — it separates "not indexed" from
+"engine missing" from "nothing to find".""",
+    "setup": """examples:
+  codeintel setup --all
+  codeintel setup
+
+The one-shot path on a new machine.""",
+    "install": """examples:
+  codeintel install
+  codeintel install --dry-run           show what would change, write nothing
+
+Writes the MCP server config so an agent can call codeintel. Then restart the
+agent (or start a new session) — a running host does not reload its MCP
+config. `codeintel doctor` lists what got registered where.""",
+    "prompt": """examples:
+  codeintel prompt
+
+For agents that cannot read an MCP config: paste the output into the
+conversation.""",
+    "reset": """examples:
+  codeintel reset .
+  codeintel reset --all --yes           wipe every repo, no prompt
+
+Recovers from a corrupt or stale index. Re-index afterwards.""",
+    "serve": """examples:
+  codeintel serve                       start the MCP server on stdio
+
+This is what an AI agent launches; you rarely run it by hand. `codeintel
+install` wires it up.""",
+    "serve-http": """examples:
+  codeintel serve-http                  loopback only, no auth
+  codeintel serve-http --token "$(codeintel gen-token)"
+
+Loopback-only unless --allow-remote. Use --token whenever the port is
+reachable by anything else.""",
+    "gen-token": """examples:
+  codeintel gen-token                   print a random bearer token
+
+For `serve-http --token`, or an RBAC auth.toml.""",
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the full argparse surface.
+
+    Split out of `main()` so the registered subcommands can be introspected directly. `--help` is
+    routed to `render_help()`, so argparse's own listing is no longer reachable from the CLI — and
+    that listing was how the help-honesty test proved every advertised command is really wired up.
+    Reading the parser is a stronger source of truth than scraping either screen's text."""
     parser = argparse.ArgumentParser(prog="codeintel")
     parser.add_argument("--version", action="version", version=f"codeintel {__version__}")
     subparsers = parser.add_subparsers(dest="command")
@@ -133,7 +277,7 @@ def main() -> None:
     # index subcommand
     index_parser = subparsers.add_parser(
         "index", parents=[color_parent],
-        help="Index a project for semantic search")
+        help="Build the index every other command reads (semantic + graph)")
     index_parser.add_argument(
         "project_root",
         nargs="?",
@@ -205,7 +349,8 @@ def main() -> None:
 
     # map subcommand
     map_parser = subparsers.add_parser("map", help="Generate CODE_INTEL.md orientation file")
-    map_parser.add_argument("project_root", nargs="?", default=None)
+    map_parser.add_argument("project_root", nargs="?", default=None,
+                            help="Project root (default: cwd)")
     map_parser.add_argument("--inject", action="store_true", help="Inject reference block into CLAUDE.md/AGENTS.md")
     map_parser.add_argument("--budget", type=int, default=32768, help="Byte budget for CODE_INTEL.md (default: 32768)")
 
@@ -219,6 +364,27 @@ def main() -> None:
     graph_parser.add_argument("--out", default=None, help="Output path for --html (default: codeintel-graph.html)")
     graph_parser.add_argument("--limit", type=int, default=220, help="Max call edges to include (default: 220)")
 
+    # c4 subcommand — a LikeC4 model of the Folder/File + IMPORTS slice
+    c4_parser = subparsers.add_parser(
+        "c4", help="Generate a LikeC4 architecture model (.c4) from the import graph")
+    c4_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    c4_parser.add_argument("--out", default=None,
+                           help="Output DIRECTORY (default: codeintel-c4/). LikeC4 merges every "
+                                ".c4 in a directory into one project, so the model gets its own.")
+    c4_parser.add_argument("--depth", type=int, default=None,
+                           help="Directory roll-up depth for elements (default: auto-fit to the "
+                                "100-element view cap; the chosen depth is always reported)")
+    c4_parser.add_argument("--scope", action="append", default=None,
+                           help="Limit the model to this path prefix; repeatable. A scope matching "
+                                "no indexed file is an error, not a silent empty model.")
+    c4_parser.add_argument("--include-tests", action="store_true",
+                           help="Model test directories too (excluded by default — they are not "
+                                "architecture and outnumber source in some repos)")
+    c4_parser.add_argument("--no-index", action="store_true",
+                           help="Fail instead of indexing an un-indexed repo (default: index it "
+                                "first, so one command always produces a model)")
+    c4_parser.add_argument("--json", action="store_true", help="Print the payload; write nothing")
+
     # doctor subcommand
     doctor_parser = subparsers.add_parser("doctor", parents=[color_parent],
                                           help="Diagnose engine health + index status for a repo")
@@ -268,13 +434,33 @@ def main() -> None:
     subparsers.add_parser("gen-token", help="Print a secure random bearer token (for serve-http / RBAC auth.toml)")
     subparsers.add_parser("help", help="Show every command, grouped, with examples")
 
+    # Applied in one pass over the built parser rather than at each `add_parser` call site: an
+    # epilog is presentation, and threading two extra kwargs through fourteen construction sites
+    # would bury the flags that actually define each command. RawDescriptionHelpFormatter goes with
+    # it — argparse otherwise re-wraps the epilog and destroys the aligned example columns.
+    for _name, _sub in (subparsers.choices or {}).items():
+        _epilog = _EPILOGS.get(_name)
+        if _epilog:
+            _sub.epilog = _epilog
+            _sub.formatter_class = argparse.RawDescriptionHelpFormatter
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+
     # Intercept an unrecognized command BEFORE argparse, whose error prints the full choice list and
     # stops — a dead end for a one-character typo. Only a bare word is claimed here; anything
-    # starting with `-` (--version, --help) still goes to argparse.
+    # starting with `-` (--version) still goes to argparse.
     argv = sys.argv[1:]
     if argv and not argv[0].startswith("-") and argv[0] not in [*_COMMANDS, "help"]:
         sys.exit(_unknown_command(argv[0]))
-    if not argv or argv[0] == "help":
+    # `-h`/`--help` only counts as top-level when it is the FIRST token: `codeintel query --help`
+    # has argv[0] == "query", so it still falls through to argparse and gets that command's own
+    # screen. Without this, the command a new user actually types was the ONE path that missed
+    # render_help() and fell back to stock argparse.
+    if not argv or argv[0] in ("help", "-h", "--help"):
         from codeintel import term
         term.configure(no_color=False, ascii_mode=None)
         print(render_help())