sciogen 0.1.2__tar.gz → 0.1.4__tar.gz

{sciogen-0.1.2 → sciogen-0.1.4}/.gitignore

@@ -22,6 +22,7 @@ env/
 htmlcov/
 tools/
 .claude/
+blog/
 
 # Local tool settings
 .claude/settings.local.json
@@ -38,3 +39,6 @@ CLAUDE.md
 RELEASING.md
 site/_artifact_*.html
 docs/api.md
+
+# Local change log (personal, uncommitted)
+CHANGELOG.local.md

{sciogen-0.1.2 → sciogen-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sciogen
-Version: 0.1.2
+Version: 0.1.4
 Summary: Codebase intelligence layer — a queryable knowledge graph over your code.
 Project-URL: Homepage, https://ayanbag.github.io/sciogen/
 Project-URL: Repository, https://github.com/ayanbag/sciogen
@@ -36,6 +36,12 @@ Description-Content-Type: text/markdown
 
 <img src="site/public/logo.png" alt="Image" width="100%" />
 
+
+
+
+
+
+
 <div align="center">
   <p>
     <a href="https://pypi.org/project/sciogen/"><img alt="PyPI" src="https://img.shields.io/pypi/v/sciogen.svg"></a>

{sciogen-0.1.2 → sciogen-0.1.4}/README.md

@@ -1,5 +1,11 @@
 <img src="site/public/logo.png" alt="Image" width="100%" />
 
+
+
+
+
+
+
 <div align="center">
   <p>
     <a href="https://pypi.org/project/sciogen/"><img alt="PyPI" src="https://img.shields.io/pypi/v/sciogen.svg"></a>

{sciogen-0.1.2 → sciogen-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sciogen"
-version = "0.1.2"
+version = "0.1.4"
 description = "Codebase intelligence layer — a queryable knowledge graph over your code."
 readme = "README.md"
 requires-python = ">=3.10"

{sciogen-0.1.2 → sciogen-0.1.4}/sciogen/__init__.py

@@ -19,6 +19,6 @@ Public entry point::
 
 from sciogen.api import SciogenGraph, open  # noqa: A004 - deliberate, mirrors sqlite3.connect ergonomics
 
-__version__ = "0.1.1"
+__version__ = "0.1.4"
 
 __all__ = ["SciogenGraph", "open", "__version__"]

{sciogen-0.1.2 → sciogen-0.1.4}/sciogen/cli/explore/template.html

@@ -284,7 +284,8 @@ GRAPH.edges.forEach(e => {
   if (adjacency.has(e.dst)) adjacency.get(e.dst).push(e);
 });
 const degree = id => GRAPH.in_degrees[id] || 0;
-const maxDegree = Math.max(1, ...Object.values(GRAPH.in_degrees));
+let maxDegree = 1;
+for (const v of Object.values(GRAPH.in_degrees)) if (v > maxDegree) maxDegree = v;
 const nodeSize = id => 22 + 36 * Math.sqrt(degree(id) / maxDegree);
 const shortLabel = n => n.kind === "FileNode" ? n.name.split("/").pop() : (n.name.split(".").pop() || n.name);
 
@@ -293,6 +294,8 @@ const visible = new Set(GRAPH.nodes.filter(n => n.kind === "FileNode").map(n =>
 const revealedBy = new Map();
 const expanded = new Set();
 const hiddenKinds = new Set();
+const savedPos = new Map();          // id → {x,y}; lets nodes reappear where they were
+const LAYOUT_ANIM_MAX = 700;         // above this many visible nodes, layout runs without animation
 let minConf = 0;
 let currentLayout = "force";
 let shownEdges = 0;
@@ -374,45 +377,129 @@ const cy = cytoscape({
   wheelSensitivity: 0.25,
 });
 
-/* stagger-fade the initial file nodes in */
+/* persist node positions after any layout or manual drag, so incremental
+   updates never re-simulate — reappearing nodes land where they were */
+cy.on("layoutstop", () => {
+  cy.nodes().forEach(n => savedPos.set(n.id(), { x: n.position("x"), y: n.position("y") }));
+});
+cy.on("dragfree", "node", e =>
+  savedPos.set(e.target.id(), { x: e.target.position("x"), y: e.target.position("y") }));
+
+/* fade the initial file nodes in as one group (not one timer per node) */
 if (!reduce) {
-  cy.nodes().forEach((n, i) => {
-    n.style("opacity", 0);
-    setTimeout(() => n.animate({ style: { opacity: 1 } }, { duration: 260, easing: "ease-out" }), 24 * i);
+  const first = cy.nodes();
+  first.style("opacity", 0);
+  first.animate({ style: { opacity: 1 } }, { duration: 300, easing: "ease-out" });
+}
+
+/* Desired on-screen sets. Edges are collected by walking only the adjacency
+   of visible nodes — never the full GRAPH.edges array — so cost scales with
+   what's shown, not with the size of the whole codebase. */
+function computeWanted() {
+  const wantNodes = new Set();
+  for (const id of visible) {
+    const n = nodesById.get(id);
+    if (n && !hiddenKinds.has(n.kind)) wantNodes.add(id);
+  }
+  const wantEdges = new Map();
+  for (const id of wantNodes) {
+    const adj = adjacency.get(id);
+    if (!adj) continue;
+    for (const e of adj) {
+      if (e.kind === "DEFINES" || e.kind === "PART_OF") continue;
+      if (e.confidence < minConf) continue;
+      if (!wantNodes.has(e.src) || !wantNodes.has(e.dst)) continue;
+      const key = e.src + "→" + e.dst + "→" + e.kind;
+      if (!wantEdges.has(key)) wantEdges.set(key, e);
+    }
+  }
+  shownEdges = wantEdges.size;
+  return { wantNodes, wantEdges };
+}
+
+/* Place freshly-revealed nodes in a ring around whatever expanded them —
+   no physics, no global relayout, existing nodes never move. */
+function positionNew(added, curNodes) {
+  const groups = new Map();
+  added.forEach(n => {
+    const id = n.id();
+    if (savedPos.has(id)) { n.position(savedPos.get(id)); return; }
+    const by = revealedBy.get(id) || "__root";
+    (groups.get(by) || groups.set(by, []).get(by)).push(n);
   });
+  // position groups whose anchor already existed first, so anchors added in
+  // this same batch are themselves placed before their children reference them
+  const order = [...groups.keys()].sort((a, b) =>
+    (curNodes.has(a) ? 0 : 1) - (curNodes.has(b) ? 0 : 1));
+  for (const by of order) {
+    const members = groups.get(by);
+    const anchor = by !== "__root" ? cy.getElementById(by) : null;
+    const has = anchor && anchor.nonempty();
+    const cx = has ? anchor.position("x") : cy.width() / 2;
+    const cyy = has ? anchor.position("y") : cy.height() / 2;
+    const r = 55 + members.length * 7;
+    members.forEach((m, i) => {
+      const a = (2 * Math.PI * i) / members.length - Math.PI / 2;
+      m.position({ x: cx + r * Math.cos(a), y: cyy + r * Math.sin(a) });
+      savedPos.set(m.id(), { x: m.position("x"), y: m.position("y") });
+    });
+  }
 }
 
+/* Incremental reconciliation: diff current vs wanted, add/remove only the
+   delta inside one batched frame. No cy.json() teardown, no relayout. */
 function refresh(opts) {
   opts = opts || {};
-  const before = new Set(cy.nodes().map(n => n.id()));
-  const els = buildElements();
-  const after = new Set(els.filter(e => !e.data.source).map(e => e.data.id));
-
-  const doUpdate = () => {
-    cy.json({ elements: els });
-    cy.style(cyStyle());
-    if (!reduce) {
-      cy.nodes().forEach(n => {
-        if (!before.has(n.id())) {
-          n.style("opacity", 0);
-          n.animate({ style: { opacity: 1 } }, { duration: 240, easing: "ease-out" });
-        }
-      });
+  const { wantNodes, wantEdges } = computeWanted();
+  const curNodes = new Set(cy.nodes().map(n => n.id()));
+  const curEdges = new Set(cy.edges().map(e => e.id()));
+
+  let remove = cy.collection();
+  cy.nodes().forEach(n => {
+    if (!wantNodes.has(n.id())) {
+      savedPos.set(n.id(), { x: n.position("x"), y: n.position("y") });
+      remove = remove.union(n);
     }
-    cy.layout(LAYOUTS[currentLayout]).run();
-    if (opts.fit) cy.animate({ fit: { padding: 40 }, duration: reduce ? 0 : 350, easing: "ease-out" });
-    updateStats();
-    if (opts.then) opts.then();
-  };
+  });
+  cy.edges().forEach(e => { if (!wantEdges.has(e.id())) remove = remove.union(e); });
+
+  const addNodes = [], addEdges = [];
+  for (const id of wantNodes) {
+    if (curNodes.has(id)) continue;
+    const n = nodesById.get(id);
+    addNodes.push({ group: "nodes", data: { id, label: shortLabel(n), kind: n.kind, size: nodeSize(id) } });
+  }
+  for (const [key, e] of wantEdges) {
+    if (curEdges.has(key)) continue;
+    addEdges.push({ group: "edges", data: { id: key, source: e.src, target: e.dst, kind: e.kind, confidence: e.confidence }, classes: edgeClass(e.confidence) });
+  }
+
+  let added = cy.collection();
+  cy.batch(() => {
+    if (remove.nonempty()) cy.remove(remove);
+    if (addNodes.length) { added = cy.add(addNodes); positionNew(added, curNodes); }
+    if (addEdges.length) cy.add(addEdges);
+  });
 
-  // fade out nodes that are leaving before the graph snaps
-  const leaving = cy.nodes().filter(n => !after.has(n.id()));
-  if (!reduce && leaving.length && leaving.length < 80) {
-    leaving.animate({ style: { opacity: 0 } }, { duration: 150, easing: "ease-in" });
-    setTimeout(doUpdate, 160);
-  } else {
-    doUpdate();
+  if (!reduce && added.nonempty()) {
+    added.style("opacity", 0);
+    added.animate({ style: { opacity: 1 } }, { duration: 240, easing: "ease-out" });
   }
+  if (opts.fit) cy.animate({ fit: { padding: 40 }, duration: reduce ? 0 : 350, easing: "ease-out" });
+  updateStats();
+  if (opts.then) opts.then();
+}
+
+/* Explicit, user-triggered global relayout (layout buttons, expand-all).
+   Skips animation past LAYOUT_ANIM_MAX so big graphs snap instead of grind. */
+function runLayout(opts) {
+  opts = opts || {};
+  const big = cy.nodes().length > LAYOUT_ANIM_MAX;
+  const cfg = Object.assign({}, LAYOUTS[currentLayout], {
+    animate: (reduce || big) ? false : (currentLayout === "force" ? "end" : true),
+    fit: !!opts.fit,
+  });
+  cy.layout(cfg).run();
 }
 
 function updateStats() {
@@ -497,8 +584,7 @@ function esc(s) { const d = document.createElement("div"); d.textContent = s; re
 cy.on("mouseover", "node", evt => {
   const n = evt.target;
   const hood = n.closedNeighborhood();
-  cy.elements().not(hood).addClass("dim");
-  hood.addClass("hot");
+  cy.batch(() => { cy.elements().not(hood).addClass("dim"); hood.addClass("hot"); });
   tip.innerHTML = nodeTip(n);
   tip.classList.add("show");
   moveTip(evt);
@@ -506,15 +592,17 @@ cy.on("mouseover", "node", evt => {
 });
 cy.on("mouseover", "edge", evt => {
   const e = evt.target;
-  cy.elements().not(e.connectedNodes().union(e)).addClass("dim");
-  e.addClass("hot"); e.connectedNodes().addClass("hot");
+  cy.batch(() => {
+    cy.elements().not(e.connectedNodes().union(e)).addClass("dim");
+    e.addClass("hot"); e.connectedNodes().addClass("hot");
+  });
   tip.innerHTML = edgeTip(e);
   tip.classList.add("show");
   moveTip(evt);
 });
 cy.on("mousemove", "node, edge", moveTip);
 cy.on("mouseout", "node, edge", () => {
-  cy.elements().removeClass("dim hot");
+  cy.batch(() => cy.elements().removeClass("dim hot"));
   tip.classList.remove("show");
   document.getElementById("cy").style.cursor = "";
 });
@@ -651,15 +739,15 @@ searchInput.addEventListener("blur", () => setTimeout(closeSug, 150));
 
 /* ---------------------------------------------------- toolbar controls */
 document.getElementById("btn-expand").onclick = () => {
-  GRAPH.nodes.forEach(n => visible.add(n.id));
-  GRAPH.nodes.forEach(n => expanded.add(n.id));
-  refresh({ fit: true });
+  GRAPH.nodes.forEach(n => { visible.add(n.id); expanded.add(n.id); });
+  refresh();                 // add the full delta incrementally (no layout inside)
+  runLayout({ fit: true });  // one explicit relayout to arrange the whole graph
 };
 document.getElementById("btn-collapse").onclick = () => {
   visible.clear(); revealedBy.clear(); expanded.clear();
   GRAPH.nodes.filter(n => n.kind === "FileNode").forEach(n => visible.add(n.id));
   hidePanel();
-  refresh({ fit: true });
+  refresh({ fit: true });    // file nodes stay put on their saved positions
 };
 document.getElementById("btn-fit").onclick = () =>
   cy.animate({ fit: { padding: 40 }, duration: reduce ? 0 : 350, easing: "ease-out" });
@@ -669,16 +757,18 @@ function setLayout(name) {
   currentLayout = name;
   btnForce.classList.toggle("active", name === "force");
   btnHier.classList.toggle("active", name === "hier");
-  refresh({ fit: true });
+  runLayout({ fit: true });  // relayout existing nodes in place — no rebuild
 }
 btnForce.onclick = () => setLayout("force");
 btnHier.onclick = () => setLayout("hier");
 
 const confSlider = document.getElementById("conf"), confVal = document.getElementById("conf-val");
+let confTimer = null;
 confSlider.addEventListener("input", () => {
   minConf = parseFloat(confSlider.value);
   confVal.textContent = minConf.toFixed(2);
-  refresh();
+  clearTimeout(confTimer);
+  confTimer = setTimeout(refresh, 90);  // debounce; only edges change, nodes never move
 });
 
 /* ------------------------------------------------------ legend filters */

{sciogen-0.1.2 → sciogen-0.1.4}/sciogen/mcp/server.py

@@ -18,11 +18,49 @@ MCP config::
 
 from __future__ import annotations
 
+import functools
 from pathlib import Path
 
 from mcp.server.fastmcp import FastMCP
 
 from sciogen.api import SciogenGraph
+from sciogen.query.engine import NotIndexedError, SymbolNotFound
+
+
+def _safe(fn):
+    """Turn query failures into structured, *terminal* tool results.
+
+    A raised exception reaches the agent as an opaque error string it cannot
+    act on — so it retries, greps, and loops. Returning a typed result with a
+    concrete ``next`` step (and near-name ``suggestions`` on a miss) gives the
+    agent something to stop on and one clear thing to do. index_codebase is
+    left unwrapped — it builds the graph, so it cannot hit these states.
+    """
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except NotIndexedError as exc:
+            return {
+                "error": "not_indexed",
+                "message": str(exc),
+                "next": "Call index_codebase(path) once for this project, then retry.",
+            }
+        except SymbolNotFound as exc:
+            return {
+                "found": False,
+                "error": "symbol_not_found",
+                "message": str(exc),
+                "suggestions": exc.suggestions,
+                "next": (
+                    "Retry with one of `suggestions` (they are exact ids), or call "
+                    "search(query, mode='hybrid') to locate it by meaning. Do NOT fall "
+                    "back to grep — the graph is indexed, this name just did not match."
+                ),
+            }
+
+    return wrapper
 
 
 def build_server(project_root: str | Path) -> FastMCP:
@@ -61,6 +99,7 @@ def build_server(project_root: str | Path) -> FastMCP:
         }
 
     @mcp.tool()
+    @_safe
     def get_symbol(name: str, file: str = "") -> dict:
         """Look up a symbol by name INSTEAD OF grepping for it. Returns the
         typed node (kind, file, exact line range, params, docstring) plus its
@@ -69,6 +108,7 @@ def build_server(project_root: str | Path) -> FastMCP:
         return graph.get_symbol(name, file or None).to_dict()
 
     @mcp.tool()
+    @_safe
     def get_callers(symbol: str, depth: int = 1, min_confidence: float = 0.0) -> dict:
         """Who calls this symbol — use BEFORE changing a signature or behavior
         so you know every call site without opening files. `depth` walks
@@ -78,12 +118,14 @@ def build_server(project_root: str | Path) -> FastMCP:
         return graph.get_callers(symbol, depth, min_confidence).to_dict()
 
     @mcp.tool()
+    @_safe
     def get_dependencies(file: str) -> dict:
         """What a file imports — direct files, transitive files, and external
         modules. Use BEFORE moving code between files or touching imports."""
         return graph.get_dependencies(file).to_dict()
 
     @mcp.tool()
+    @_safe
     def analyze_impact(symbol: str, max_depth: int = 5, min_confidence: float = 0.0) -> dict:
         """Blast radius of changing this symbol: transitive callers plus
         direct subclasses, implementors, tests, and mutators. Use BEFORE any
@@ -92,6 +134,7 @@ def build_server(project_root: str | Path) -> FastMCP:
         return graph.analyze_impact(symbol, max_depth, min_confidence).to_dict()
 
     @mcp.tool()
+    @_safe
     def search(query: str, mode: str = "semantic", granularity: str = "", k: int = 10) -> dict:
         """Find code by meaning ('password hashing logic') INSTEAD OF grep
         when you don't know exact names. mode='hybrid' also pulls in graph
@@ -100,6 +143,7 @@ def build_server(project_root: str | Path) -> FastMCP:
         return graph.search(query, mode, granularity or None, k).to_dict()
 
     @mcp.tool()
+    @_safe
     def get_diff_impact(unified_diff: str) -> dict:
         """Impact of a whole change set at once: feed a unified diff (e.g.
         `git diff` output) and get every touched symbol plus the union blast
@@ -108,6 +152,7 @@ def build_server(project_root: str | Path) -> FastMCP:
         return graph.get_diff_impact(unified_diff).to_dict()
 
     @mcp.tool()
+    @_safe
     def get_context_for_task(description: str, k: int = 15) -> dict:
         """START HERE for any broad task ('add rate limiting to login'):
         returns the ranked files and key symbols relevant to the intent, so

{sciogen-0.1.2 → sciogen-0.1.4}/sciogen/query/engine.py

@@ -45,7 +45,25 @@ _CACHE_SIZE = 128
 
 
 class SymbolNotFound(LookupError):
-    """Raised when a named symbol has no match in the graph."""
+    """Raised when a named symbol has no match in the graph.
+
+    Carries ``suggestions`` — near-name matches the caller can retry with, so
+    an agent corrects in one hop instead of guessing name variants in a loop.
+    """
+
+    def __init__(self, message: str, suggestions: list[str] | None = None) -> None:
+        super().__init__(message)
+        self.suggestions = suggestions or []
+
+
+class NotIndexedError(RuntimeError):
+    """Raised when a query runs against an index that was never built.
+
+    Distinct from :class:`SymbolNotFound` on purpose: an empty index makes
+    *every* lookup miss, which is indistinguishable from a genuine not-found
+    unless we signal it separately. Without this an agent reads one miss as
+    'the tool knows nothing' and falls back to grep for the whole session.
+    """
 
 
 class QueryEngine:
@@ -60,6 +78,11 @@ class QueryEngine:
 
     def _cached(self, key: tuple, compute):
         version = self.meta.index_version
+        if version == 0:
+            raise NotIndexedError(
+                "The knowledge graph is empty — this project has not been indexed yet. "
+                "Call index_codebase(path) once, then retry this query."
+            )
         if version != self._cache_version:
             self._cache.clear()
             self._cache_version = version
@@ -78,7 +101,8 @@ class QueryEngine:
         rows = self.graph.find_by_name(name, file)
         if not rows:
             raise SymbolNotFound(
-                f"No symbol named '{name}'" + (f" in {file}" if file else "") + " in the index."
+                f"No symbol named '{name}'" + (f" in {file}" if file else "") + " in the index.",
+                suggestions=self.meta.suggest_symbol_ids(name),
             )
         # Exact qualname beats suffix match; shorter qualname beats deeper nesting.
         rows.sort(key=lambda r: (r["name"] != name, len(r["name"])))
@@ -160,7 +184,10 @@ class QueryEngine:
 
     def _get_dependencies(self, file: str, max_depth: int) -> DependencyInfo:
         if self.graph.get_node(file) is None:
-            raise SymbolNotFound(f"File '{file}' is not in the index.")
+            raise SymbolNotFound(
+                f"File '{file}' is not in the index.",
+                suggestions=self.meta.suggest_files(file),
+            )
         direct = self.graph.out_edges(file, EdgeKind.IMPORTS)
         reachable = self.graph.traverse(
             [file], EdgeKind.IMPORTS, direction="out", max_depth=max_depth

{sciogen-0.1.2 → sciogen-0.1.4}/sciogen/stores/meta.py

@@ -199,6 +199,47 @@ class MetaStore:
         table.files = {row[0] for row in self.conn.execute("SELECT path FROM files")}
         return table
 
+    def suggest_symbol_ids(self, name: str, limit: int = 5) -> list[str]:
+        """Best-effort near-name matches for a symbol miss.
+
+        Narrows with a SQL ``LIKE`` on the simple name before ranking with
+        difflib, so a typo ('Rollng' -> 'Rolling') or a partial name still
+        surfaces the real qualname the agent should retry with — instead of a
+        bare 'not found' that sends it back to grep.
+        """
+        import difflib
+
+        frag = name.rsplit(".", 1)[-1]
+        rows = self._like_symbols(f"%{frag}%")
+        if not rows and len(frag) >= 3:
+            rows = self._like_symbols(f"{frag[:3]}%")
+        if not rows:
+            return []
+        rows.sort(
+            key=lambda r: difflib.SequenceMatcher(None, frag.lower(), r[1].lower()).ratio(),
+            reverse=True,
+        )
+        return [rid for rid, _simple in rows[:limit]]
+
+    def _like_symbols(self, pattern: str, cap: int = 500) -> list[tuple[str, str]]:
+        return self.conn.execute(
+            "SELECT id, simple_name FROM symbols WHERE simple_name LIKE ? LIMIT ?",
+            (pattern, cap),
+        ).fetchall()
+
+    def suggest_files(self, path: str, limit: int = 5) -> list[str]:
+        """Near-path matches for a file miss, ranked by difflib."""
+        import difflib
+
+        base = path.replace("\\", "/").rsplit("/", 1)[-1]
+        rows = self.conn.execute(
+            "SELECT path FROM files WHERE path LIKE ? LIMIT 500", (f"%{base}%",)
+        ).fetchall()
+        if not rows:
+            rows = self.conn.execute("SELECT path FROM files LIMIT 2000").fetchall()
+        paths = [r[0] for r in rows]
+        return difflib.get_close_matches(path.replace("\\", "/"), paths, n=limit, cutoff=0.3)
+
     def replace_symbols(self, file: str, rows: list[tuple[str, str, str]]) -> None:
         """rows: (id, simple_name, kind)."""
         self.conn.execute("DELETE FROM symbols WHERE file = ?", (file,))

{sciogen-0.1.2 → sciogen-0.1.4}/site/docs.html

@@ -325,6 +325,43 @@
   footer.site { border-top: 1px solid var(--line-soft); padding: 36px 24px 56px; }
   .foot-in { max-width: var(--maxw); margin: 0 auto; display: flex; flex-wrap: wrap; gap: 16px; justify-content: space-between; color: var(--fg-3); font-size: 13px; }
   .foot-in a:hover { color: var(--accent); }
+
+  /* ---------- mobile refinements ---------- */
+  @media (max-width: 640px) {
+    .nav-in { height: 56px; padding: 0 18px; }
+    .nav-right { gap: 12px; }
+    .nav-cta { padding: 7px 12px; font-size: 12px; }
+    .icon-btn { width: 34px; height: 34px; }
+
+    .shell { padding: 0 18px; }
+
+    /* TOC: a compact wrapping row of links above the content, not a tall list */
+    aside.toc { padding: 18px 0; }
+    .toc .group { margin-bottom: 14px; }
+    .toc .group-label { margin-bottom: 6px; }
+    .toc .group > a { display: inline-block; border-left: 0; padding: 5px 10px; }
+
+    main.doc { padding: 32px 0 90px; }
+    .doc .lede { font-size: 1.06rem; max-width: 100%; }
+    .doc section.block { padding-top: 60px; }
+    .doc p, .doc ul, .doc ol { max-width: 100%; }
+
+    .callout { padding: 20px 20px; }
+    .code pre { padding: 16px; font-size: 12.5px; }
+    .dd-inner { padding: 0 16px; }
+    .dd-head { padding: 14px 16px; }
+
+    /* prev/next stack instead of squeezing side by side */
+    .doc-nav { flex-direction: column; margin-top: 60px; }
+    .doc-nav a { max-width: 100%; }
+    .doc-nav a.next { text-align: left; margin-left: 0; }
+  }
+
+  @media (max-width: 400px) {
+    .shell { padding: 0 14px; }
+    .brand .crumb { display: none; }
+    .nav-right { gap: 8px; }
+  }
 </style>
 </head>
 <body>
@@ -367,6 +404,10 @@
       <a href="#cli">CLI reference</a>
       <a href="#configuration">Configuration</a>
     </div>
+    <div class="group">
+      <div class="group-label">Community</div>
+      <a href="#contributing">Contributing</a>
+    </div>
   </aside>
 
   <main class="doc">
@@ -569,7 +610,7 @@
         <div class="pstage"><div class="pn">05 · DIFF</div><div class="pt">SHA256 differ</div><div class="pd">Only changed files re-run next time</div></div>
       </div>
 
-      <h3 class="reveal">The full system, interactive</h3>
+      <h3 class="reveal">The full system</h3>
       <p class="reveal">Everything on one map — the indexing pipeline, the triple store, and the query side. Click any component to see what it does, or play a flow to watch how data moves.</p>
 
       <div class="arch reveal" id="archmap">
@@ -817,10 +858,63 @@
           <tr><td><code>SCIOGEN_DATA_DIR</code></td><td>Override the index location (default <code>&lt;project&gt;/.sciogen</code>)</td></tr>
         </tbody>
       </table></div>
+    </section>
+
+    <!-- ============================ CONTRIBUTING ============================ -->
+    <section class="block" id="contributing">
+      <h2 class="reveal">Contributing <a class="hash" href="#contributing">#</a></h2>
+      <p class="reveal">sciogen is open source and contributions are welcome — bug reports, language-normalizer improvements, docs, and features all move it forward. The complete guide lives in <a href="https://github.com/ayanbag/sciogen/blob/master/CONTRIBUTING.md" target="_blank" rel="noopener">CONTRIBUTING.md</a>; the essentials are below.</p>
+
+      <h3 class="reveal">Set up a dev environment</h3>
+      <p class="reveal">sciogen targets <b>Python 3.10+</b> and builds with hatchling. Install it <b>editable</b> (<code>-e</code>) so source edits — including the version and CLI banner — take effect immediately, with no reinstall:</p>
+      <div class="code reveal"><span class="lang">shell</span><button class="copy" type="button" data-copy='git clone https://github.com/ayanbag/sciogen && cd sciogen && pip install -e ".[dev,embeddings]"' aria-label="Copy"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="9" y="9" width="12" height="12" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg></button>
+<pre><span class="g">$</span> git clone https://github.com/ayanbag/sciogen
+<span class="g">$</span> cd sciogen
+<span class="g">$</span> pip install -e ".[dev,embeddings]"</pre></div>
+      <p class="reveal">Then confirm your environment is live — both must print the <b>same</b> version; if they disagree you're running a stale install:</p>
+      <div class="code reveal"><span class="lang">shell</span><button class="copy" type="button" data-copy='python -c "import sciogen; print(sciogen.__version__)" && python -m sciogen --version' aria-label="Copy"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="9" y="9" width="12" height="12" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg></button>
+<pre><span class="g">$</span> python -c "import sciogen; print(sciogen.__version__)"
+<span class="g">$</span> python -m sciogen --version</pre></div>
+
+      <h3 class="reveal">Run the tests</h3>
+      <p class="reveal">Every change should keep the suite green. New behavior needs a test; a bug fix should add a regression test that fails before and passes after.</p>
+      <div class="code reveal"><span class="lang">shell</span><button class="copy" type="button" data-copy="pytest" aria-label="Copy"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="9" y="9" width="12" height="12" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg></button>
+<pre><span class="g">$</span> pytest                <span class="mut"># full suite</span>
+<span class="g">$</span> pytest -p no:randomly <span class="mut"># deterministic order</span></pre></div>
+
+      <div class="callout reveal">
+        <span class="t">What belongs in sciogen</span>
+        <p>sciogen is a static index, not a generative tool. A few constraints are non-negotiable, and a PR that breaks one will be asked to change: <b>no LLM calls</b> anywhere; <b>no token counting or context-window logic</b>; query methods return <b>typed nodes, never raw source</b>; the pipeline <b>writes every edge</b> and confidence is filtered at query time, not at write time. Language-specific logic lives in exactly one place — the <b>AST normalizer</b> — so everything downstream stays language-agnostic.</p>
+      </div>
+
+      <h3 class="reveal">Branch off master</h3>
+      <p class="reveal">Work on a branch, never on <code>master</code> itself. Start from an up-to-date <code>master</code> and name the branch <code>type/short-description</code> — a prefix that says what the change is, then a few kebab-case words:</p>
+      <div class="code reveal"><span class="lang">shell</span><button class="copy" type="button" data-copy="git checkout master && git pull && git checkout -b fix/login-caller-resolution" aria-label="Copy"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="9" y="9" width="12" height="12" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg></button>
+<pre><span class="g">$</span> git checkout master
+<span class="g">$</span> git pull                <span class="mut"># start from an up-to-date master</span>
+<span class="g">$</span> git checkout -b <span class="hi">fix/login-caller-resolution</span></pre></div>
+      <div class="tbl-wrap reveal"><table>
+        <thead><tr><th>Prefix</th><th>For</th></tr></thead>
+        <tbody>
+          <tr><td><code>fix/</code></td><td>A bug fix</td></tr>
+          <tr><td><code>feat/</code></td><td>A new feature or capability</td></tr>
+          <tr><td><code>docs/</code></td><td>Documentation only</td></tr>
+          <tr><td><code>refactor/</code></td><td>Internal change, no behavior difference</td></tr>
+          <tr><td><code>test/</code></td><td>Adding or reworking tests</td></tr>
+          <tr><td><code>chore/</code></td><td>Tooling, CI, packaging, dependencies</td></tr>
+        </tbody>
+      </table></div>
+      <p class="reveal">Keep one branch to one logical change — small, focused branches review faster and revert cleanly. If <code>master</code> moves while you work, rebase on top of it so history stays linear:</p>
+      <div class="code reveal"><span class="lang">shell</span><button class="copy" type="button" data-copy="git fetch origin && git rebase origin/master" aria-label="Copy"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="9" y="9" width="12" height="12" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg></button>
+<pre><span class="g">$</span> git fetch origin
+<span class="g">$</span> git rebase origin/master</pre></div>
+
+      <h3 class="reveal">Versioning</h3>
+      <p class="reveal">The version is declared in <b>two places that must stay in sync</b>: <code>version</code> in <code>pyproject.toml</code> (the packaged version on PyPI) and <code>__version__</code> in <code>sciogen/__init__.py</code> (imported by the CLI banner). Bump <b>both</b> to the same value — the publish workflow asserts the release tag matches the package version, so a mismatch fails the release.</p>
 
       <div class="doc-nav reveal">
         <a href="index.html"><span class="lbl">← Back</span><div class="ttl">sciogen home</div></a>
-        <a class="next" href="https://github.com/ayanbag/sciogen" target="_blank" rel="noopener"><span class="lbl">Source →</span><div class="ttl">GitHub repository</div></a>
+        <a class="next" href="https://github.com/ayanbag/sciogen/blob/master/CONTRIBUTING.md" target="_blank" rel="noopener"><span class="lbl">Full guide →</span><div class="ttl">CONTRIBUTING.md</div></a>
       </div>
     </section>
   </main>

{sciogen-0.1.2 → sciogen-0.1.4}/site/index.html

@@ -369,6 +369,55 @@
     transition: all .3s var(--ease); z-index: 100;
   }
   .toast.show { opacity: 1; transform: translateX(-50%) translateY(0); }
+
+  /* ---------- mobile refinements ---------- */
+  @media (max-width: 640px) {
+    .wrap { padding: 0 18px; }
+
+    /* nav: tighten so brand + theme + two pills never overflow narrow phones */
+    .nav-in { height: 56px; }
+    .nav-links { gap: 12px; }
+    .nav-cta { padding: 7px 12px; font-size: 12px; }
+    .icon-btn { width: 34px; height: 34px; }
+
+    /* hero: shorter, no forced viewport height, text spans full column */
+    .hero { min-height: 0; }
+    .hero-in { padding: 46px 0 64px; }
+    .hero h1 { max-width: 100%; font-weight: 680; }
+    .hero p.lede { margin-top: 20px; max-width: 100%; }
+    .hero-actions { margin-top: 30px; gap: 12px; }
+    /* stack the install command + primary button full-width */
+    .hero-actions .cmd { width: 100%; justify-content: space-between; }
+    .hero-actions .btn-primary { width: 100%; justify-content: center; }
+    .chips { margin-top: 32px; gap: 12px 22px; }
+
+    /* sections: reduce the large vertical rhythm on small screens */
+    section { padding: 60px 0; }
+    .why-grid, .pipe, .caps, .conf-grid, .duo, .stores, .demo-wrap { margin-top: 40px; }
+    .sec-head p { font-size: 1.02rem; }
+
+    /* confidence rows wrap instead of squeezing the label */
+    .conf-row { flex-wrap: wrap; gap: 8px 14px; }
+    .conf-svg { width: 72px; }
+    .conf-row .cval { width: auto; }
+
+    .use { padding: 24px; }
+    .cost { padding: 22px; }
+    .store { padding: 22px; }
+
+    /* cta command + button also stack full-width */
+    .cta .hero-actions .cmd,
+    .cta .hero-actions .btn-primary { width: 100%; }
+  }
+
+  @media (max-width: 380px) {
+    .wrap { padding: 0 14px; }
+    .brand { font-size: 15px; }
+    .nav-links { gap: 8px; }
+    /* drop the Docs pill on the tightest screens — it lives in the footer too */
+    .nav-links .nav-cta[href="docs.html"] { display: none; }
+    .cmd { font-size: 13.5px; padding: 12px 14px; }
+  }
 </style>
 </head>
 <body>

sciogen-0.1.4/tests/test_mcp_server.py

@@ -0,0 +1,42 @@
+"""MCP layer: query failures come back as structured, terminal results.
+
+The wrappers must never let a query exception escape as an opaque error
+string — an agent cannot act on that and falls back to grep or loops. Each
+failure maps to a dict with a concrete ``next`` step (and ``suggestions`` on a
+miss) so the agent has one clear thing to do.
+"""
+
+from __future__ import annotations
+
+from sciogen.mcp.server import _safe
+from sciogen.query.engine import NotIndexedError, SymbolNotFound
+
+
+def test_safe_maps_not_indexed_to_structured_result():
+    @_safe
+    def tool():
+        raise NotIndexedError("empty")
+
+    result = tool()
+    assert result["error"] == "not_indexed"
+    assert "index_codebase" in result["next"]
+
+
+def test_safe_maps_symbol_miss_with_suggestions():
+    @_safe
+    def tool():
+        raise SymbolNotFound("no such symbol", suggestions=["pkg/mod.py:Real.name"])
+
+    result = tool()
+    assert result["found"] is False
+    assert result["error"] == "symbol_not_found"
+    assert result["suggestions"] == ["pkg/mod.py:Real.name"]
+    assert "grep" in result["next"].lower()  # explicitly steers off grep
+
+
+def test_safe_passes_success_through_unchanged():
+    @_safe
+    def tool():
+        return {"node": {"id": "x"}}
+
+    assert tool() == {"node": {"id": "x"}}

{sciogen-0.1.2 → sciogen-0.1.4}/tests/test_pipeline_and_query.py

@@ -111,6 +111,39 @@ def test_unknown_symbol_raises(indexed_project):
         indexed_project.get_symbol("does_not_exist_anywhere")
 
 
+def test_symbol_miss_carries_suggestions(indexed_project):
+    """A near-miss name surfaces the real qualname to retry with, so an agent
+    corrects in one hop instead of looping over grep."""
+    from sciogen.query.engine import SymbolNotFound
+
+    with pytest.raises(SymbolNotFound) as exc:
+        indexed_project.get_symbol("logn")  # typo for AuthService.login
+    assert "src/auth/service.py:AuthService.login" in exc.value.suggestions
+
+
+def test_file_miss_carries_path_suggestions(indexed_project):
+    from sciogen.query.engine import SymbolNotFound
+
+    with pytest.raises(SymbolNotFound) as exc:
+        indexed_project.get_dependencies("src/auth/servcie.py")  # typo
+    assert "src/auth/service.py" in exc.value.suggestions
+
+
+def test_query_on_unindexed_graph_signals_not_indexed(tmp_path: Path):
+    """An empty index must raise NotIndexedError, not a generic miss —
+    otherwise every lookup looks like 'symbol not found' and an agent gives up
+    on the tools entirely."""
+    from sciogen.query.engine import NotIndexedError
+
+    write_sample_project(tmp_path)
+    graph = sciogen.open(tmp_path)  # constructed but never indexed
+    try:
+        with pytest.raises(NotIndexedError):
+            graph.get_symbol("AuthService.login")
+    finally:
+        graph.close()
+
+
 # ------------------------------------------------------------- incremental
 
 def test_incremental_reindex(tmp_path: Path):