codetopo / log /index.html
Nrupal Akolkar
Mirror of nrupala/codetopo@32dcb72181941df9a5e12197e71dce7d0a9472f3
15313a2
Raw History Blame Contribute Delete
15.2 kB
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>codetopo β€” development log</title>
<style>
:root { color-scheme: dark; }
body { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
margin: 0 auto; max-width: 880px; padding: 24px 16px 48px;
background: #0d1117; color: #e6edf3; line-height: 1.5; }
h1 { font-size: 28px; margin: 0 0 4px; }
h2 { font-size: 17px; margin: 28px 0 8px; }
h3 { font-size: 15px; margin: 22px 0 6px; }
.sub { color: #9da7b3; margin: 0 0 16px; }
.when { color: #9da7b3; font-weight: 400; }
a { color: #58a6ff; }
footer { margin-top: 40px; color: #9da7b3; font-size: 13px; }
</style>
</head>
<body>
<h1>codetopo β€” development log</h1>
<p class="sub">How codetopo got here, and where it is going β€” in plain words.</p>
<p>codetopo turns a source repository into a queryable code graph β€” symbols,
calls, references, structure β€” with answers an AI coding agent can act on
directly. This page is the public story of the build: what shipped, what it
means if you use codetopo, and what is being worked on next. It is kept with
the releases β€” every release adds its entry here in the same change. The demo
itself is on the <a href="../">front page</a>.</p>
<h2>The story so far</h2>
<h3><span class="when">November 2, 2026 β€”</span> 0.9.0: the analytics engine</h3>
<p>codetopo's ranking learns the classic graph measures. Where it once
ranked symbols four ways, it now answers nine: the original four, unchanged
to the byte, plus five measures every network-science textbook defines β€”
which symbols everything flows through, which sit closest to all the rest,
and which matter because important things point at them. Three new tools
join the seventeen, on the command line, over HTTP, and through the agent
tools alike: one finds the natural communities inside a codebase and scores
how cleanly they separate; one lays the graph out in dependency order; and
one draws it β€” a force-directed map as SVG, drawn identically every time it
is asked. Every number still travels with its method and its settings;
where a measure honestly cannot converge on a very large graph, codetopo
says so, with the reason, instead of returning half an answer. The proof is
pinned in the open: the new measures were checked against the standard
reference implementations (networkx and igraph) and agree to the last
decimal places that matter, twice-run outputs are byte-identical, and on a
graph of forty thousand symbols the slowest measure finishes in about half
a minute. The schema stays at 1.2 β€” nothing stored changes, and snapshots
keep reading. All eight crates move to 0.9.0 together. 0.9.0 is a release
candidate since November 2, 2026 β€” it graduates after a clean watched
week.</p>
<h3><span class="when">November 2, 2026 β€”</span> 0.8.0: Python joins</h3>
<p>codetopo now reads Python. Files ending .py and .pyi are indexed through
the same contract as Rust and TypeScript/JavaScript: packages and modules
(an __init__.py stands for its package), classes, functions and methods,
module-level variables, and imports β€” absolute, relative, and future β€”
resolved at module level. Protocol classes are recognised as interfaces.
Every Python symbol carries the measured fields the analytics engine feeds
on β€” its signature, its line span, and its counted decision points β€” so
complexity, coupling, and ranking work on Python code exactly as they do on
the other languages, on the command line, over HTTP, and through the
seventeen agent tools alike. The schema that describes all of this rises
to 1.2, additively: snapshots written by older versions keep reading.
Where Python defines a name twice β€” an overload, a property and its
setter β€” the index says so, with both locations, instead of silently
picking one. The proof is pinned in the open: hand-counted fixtures, a
known-answer package whose expected graph is published arithmetic, and a
cross-check against a real-world codebase (pallets/click) reconciled
row-for-row against CPython's own count of its definitions. All eight
crates move to 0.8.0 together. 0.8.0 is a release candidate since
November 2, 2026 β€” it graduates after a clean watched week.</p>
<h3><span class="when">October 30, 2026 β€”</span> Listing copy brought current</h3>
<p>A housekeeping pass over the pages that directories and agents read:
the launch guide, the Gemini extension manifest, and the agent install
guide still described the twelve tools of an older release. They now
name all seventeen, including the diagnostics, ranking, comparison,
metrics, and history tools the analytics work added. No code changed.</p>
<h3><span class="when">October 25, 2026 β€”</span> 0.7.0: the analytics engine, complete</h3>
<p>codetopo now measures what it indexes. Every function and method carries
its size in lines and its cyclomatic complexity β€” counted decision points
plus one, with the counting rules published and the method stated wherever
the number appears. Types carry coupling and cohesion measurements: how
many other types they touch, what they can reach, and how far their methods
share the type's own state. Packages carry their dependency balance β€”
what depends on them, what they depend on, and how much of that points
outward β€” with links to external libraries counted separately, never merged
in. And on your own machine, codetopo reads a repository's git history to
find its hotspots β€” the files that change often and are complex at once,
both factors always shown β€” and the files that change together, reported as
the counts themselves. Hosted indexes carry no history, and there the
answer is honestly "not measured", never an invented number. Every one of
these is a measurement with a stated method; codetopo still ships no
verdicts about whether code is good. All of it arrives on the same three
doors β€” command line, HTTP, and the agent tools β€” and all eight crates move
to 0.7.0 together. 0.7.0 is a release candidate since October 25, 2026 β€”
it graduates after a clean watched week; the published packages and the
hosted service pick it up at graduation.</p>
<h3><span class="when">October 20, 2026 β€”</span> 0.6.0: the analytics get deeper</h3>
<p>codetopo's answers grow a layer. Asking about one symbol now returns its
dossier β€” the symbol itself plus every connection it has, grouped by kind,
with the counts stated first β€” the shape the design specified from the
start. The warnings recorded while an index was built (dependency cycles,
symbols defined twice, calls that resolve to nothing) can now be read by
agents too, not only printed by the command line. Symbols can be ranked by
how much depends on them, how much they depend on, and how much breaks if
they change β€” measurements, with the method stated beside the numbers,
never a score of whether code is good. And two indexes can be compared
directly: what was added, what was removed, what changed, and how the
blast radius of every touched symbol moved. All of it arrives on the same
three doors β€” command line, HTTP, and the agent tools β€” and all eight
crates move to 0.6.0 together. 0.6.0 is a release candidate since
October 20, 2026 β€” it graduates on October 27, 2026 after a clean watched
week; the published packages and the hosted service pick it up at
graduation.</p>
<h3><span class="when">October 18–19, 2026 β€”</span> The hosted API goes live</h3>
<p>codetopo Hosted is a real thing you can buy now: US$19 a month for a hosted
key β€” up to 25 indexes of your own and 10,000 queries a month β€” without
running a server yourself. Before it opened, the whole trip was walked the way
a customer walks it: pay, claim the key (it is shown exactly once), ask the API
real questions about a real repository, cancel, and watch the key stop working.
It all held.</p>
<h3><span class="when">October 14, 2026 β€”</span> 0.5.0: one version everywhere</h3>
<p>All seven crates moved onto a single version line, 0.5.0, and were published
together: crates.io, the GitHub release, and the official MCP Registry all say
the same number. Before this, different pieces of codetopo carried three
different versions at once; now, whatever you install agrees with everything
else.</p>
<h3><span class="when">October 14, 2026 β€”</span> A hosted service, built in stages</h3>
<p>Underneath the launch, the hosted path was assembled piece by piece, each
piece tested before the next landed: a real key store, where your indexes
belong to your key β€” another key asking for your index gets the same answer as
asking for one that does not exist; hosted ingest, where you hand the API a
public repository URL or an archive instead of a path on a machine; plan
limits, the envelope that keeps one key from eating the host; and a billing
bridge that turns a payment into a key and a cancellation into a revocation.
When the first customer-walk found a rough edge β€” the claim page arrived blank
and made you hunt down a session id β€” the page learned to arrive pre-filled.</p>
<h3><span class="when">October 14, 2026 β€”</span> The release gate, and fixing what it found</h3>
<p>codetopo went through the same release gate every product here faces, and
the fixes shipped the same day. API errors no longer leak internal detail. The
quickstart no longer plants a published example password β€” it generates a
random one, and the server refuses a keys file still carrying the example.
Older indexes stop being readable by every key once a second key exists. And
the README says plainly how to delete your data and how to export it.</p>
<h3><span class="when">October 14, 2026 β€”</span> Listed where agents look</h3>
<p>Glama approved the listing after inspecting the running server itself β€” all
twelve tools, live. The Smithery bundle was refreshed at 0.5.0, and a Gemini
CLI extension in the repository puts codetopo in the Gemini extensions
gallery. Whichever door your agent uses, it finds the same codetopo.</p>
<h3><span class="when">October 13, 2026 β€”</span> 0.3.5: tools that introduce themselves</h3>
<p>Every MCP tool gained a human-readable title and honest annotations β€” what
it does, that it is read-only β€” so agent clients and directories can present
the tools properly. The README gained a Privacy Policy section the same day.</p>
<h3><span class="when">October 11, 2026 β€”</span> 0.3.4: Windows works</h3>
<p>The MCP server had never compiled on Windows β€” one part of it used
Unix-only plumbing. It has a proper Win32 implementation now, and CI builds
the shipped binaries on Windows so this cannot silently break again. Found,
fittingly, by making the first Windows build in the project's history.</p>
<h3><span class="when">October 10, 2026 β€”</span> 0.4.0: a trust setup for editor agents</h3>
<p>Agents that speak the Agent Client Protocol gained
<code>codetopo-trust-setup</code>: a one-time setup in your terminal that
creates a local proof-verification key. Snapshots the agent takes can then be
signed, and its answers can cite who stands behind them. codetopo still has no
accounts β€” the only secret is a key that never leaves your machine.</p>
<h3><span class="when">October 10, 2026 β€”</span> 0.3.0: published, and measured at 10,000 files</h3>
<p>All seven crates reached crates.io for the first time; a few small listing
releases followed over the next day to get the registry pages rendering right.
The same stretch brought <code>codetopo render</code> β€” a picture of your
graph that is a pure function of the data, byte-identical on any machine β€” a
self-hosted Docker container, and a demo snapshot that re-captures itself on
every merge, so this site never goes stale. And the scale gate: a
10,000-file repository indexed in about 3.5 seconds. The gate earned its
keep β€” a very deep call chain crashed the cycle detector, which is now built
so depth is limited by memory, not by a stack.</p>
<h3><span class="when">October 5, 2026 β€”</span> 0.2.0: the first public release</h3>
<p>One engine, four doors. The core turns a repository into a graph β€” symbols,
calls, references, structure β€” stored with a tamper-evident audit log. On top
of it: a command-line tool, an HTTP API, an MCP server for agents, and an ACP
agent for editors. All four answer the same questions with the same answers,
because all four are thin doors over the same core.</p>
<h2>What is coming</h2>
<p>Drawn from the design in the repository (<code>DESIGN.md</code>).
Directions, not promises β€” and no dates, because honest phase words beat
invented deadlines.</p>
<h3><span class="when">Next β€”</span> Deeper still: richer extraction</h3>
<p>The design's derived views β€” complexity among them β€” need the extractors
to capture more of each symbol than they do today: where it ends, its
signature, its branching. With that in hand, codetopo can report coupling
and complexity the same way it now reports structure: the measurement and
its method, never a grade. That work is designed and waiting its turn.</p>
<h3><span class="when">After the hosted launch settles β€”</span> A working graph you can shape</h3>
<p>The design's surgical operations β€” expand, collapse, annotate, prune β€” let
an agent grow and trim a working view of a codebase instead of re-asking from
scratch every time.</p>
<h3><span class="when">Later β€”</span> More languages</h3>
<p>Rust, TypeScript/JavaScript, and Python are parsed today. Each language is a front
end against one shared contract, so new languages slot in without changing
the questions you can ask.</p>
<h3><span class="when">Later β€”</span> Always-fresh maps for your repository</h3>
<p>This demo already redraws codetopo's own map on every push. The design aims
the same trick at your repository: current architecture maps in your docs and
pull requests, rebuilt by CI, never stale.</p>
<h3><span class="when">Exploring β€”</span> A fuzzy layer beside the exact one</h3>
<p>The design leaves room for an optional embeddings overlay β€” fuzzy search
next to the exact graph, never instead of it. It stays optional, and it stays
later.</p>
<footer>
<p>Source of truth: <a href="https://github.com/nrupala/codetopo">github.com/nrupala/codetopo</a> (this Space is an automated mirror). The developer-grade record is the repository's <code>CHANGELOG.md</code>; this page is its plain-words companion.</p>
<p>Owned by <a href="https://nrupalakolkar.com">Nrupal Akolkar</a> Β· Built with <a href="https://muse.ai/join">Muse by Meta</a>.</p>
</footer>
<!--
Copyright (C) 2026 2351485 ALBERTA INC.
SPDX-License-Identifier: AGPL-3.0-or-later
Part of codetopo β€” Owned by 2351485 ALBERTA INC. (https://nrupalakolkar.com) Β· Built with Muse by Meta (https://muse.ai/join).
Public development log for codetopo. Content is distilled only from the
repository's verified records (CHANGELOG.md, the GitHub release record,
DESIGN.md for what is ahead) β€” nothing here carries a date or a claim
those records do not carry. Kept with the releases: every release adds
its entry in the same change (rule in CONTRIBUTING.md).
-->
</body>
</html>