@polycode-projects/the-mechanical-code-talker 2.11.12 → 3.0.1

package/src/index/extract_ast.py

@@ -0,0 +1,364 @@
+#!/usr/bin/env python3
+"""Deterministic, offline static extraction for tmct (Python).
+
+Stdlib `ast` only — no third-party parser, no model calls. Walks every *.py file
+under repo_path and emits ONE JSON document on stdout:
+
+    {"modules": [
+        {"path": "<repo-relative>", "dotted": "django.utils.text",
+         "imports": ["django.utils.functional", ...],   # candidate dotted targets
+         "defines": [{"name": "slugify", "kind": "function", "lineno": 12,
+                      "decorators": ["register.filter(is_safe=True)"]},
+                     {"name": "Truncator", "kind": "class", "bases": ["object"], ...},
+                     {"name": "Truncator.chars", "kind": "method", ...},
+                     {"name": "Truncator.text", "kind": "attribute", ...}, ...],
+         "calls": ["str.strip", "re.sub", ...]},          # coarse callee names
+        ...
+    ]}
+
+Resolution of import candidates and call targets to internal modules happens in
+buildEntities against the registry of discovered modules — this script stays a
+pure per-file parser. Run: python3 extract_ast.py <repo_path>.
+"""
+
+import ast
+import json
+import os
+import sys
+
+SKIP_DIRS = {".git", ".tmct", ".hg", ".svn", "node_modules", ".venv", "venv",
+             "__pycache__", ".tox", ".mypy_cache", ".pytest_cache", "build", "dist"}
+
+
+def dotted_for(rel_path):
+    """Repo-relative .py path -> dotted module + its package."""
+    parts = rel_path[:-3].split(os.sep)  # drop ".py"
+    if parts and parts[-1] == "__init__":
+        parts = parts[:-1]
+        pkg = ".".join(parts)
+        return pkg, pkg  # a package: dotted == its own package
+    dotted = ".".join(parts)
+    pkg = ".".join(parts[:-1])
+    return dotted, pkg
+
+
+def import_targets(node, pkg):
+    """Candidate dotted module targets for one Import/ImportFrom node."""
+    out = []
+    if isinstance(node, ast.Import):
+        for alias in node.names:
+            out.append(alias.name)  # import a.b.c -> "a.b.c"
+    elif isinstance(node, ast.ImportFrom):
+        if node.level:  # relative: from . / from .mod import x
+            base_parts = pkg.split(".") if pkg else []
+            base_parts = base_parts[: len(base_parts) - (node.level - 1)] if node.level > 1 else base_parts
+            base = ".".join(base_parts)
+            mod = f"{base}.{node.module}" if node.module else base
+        else:
+            mod = node.module or ""
+        if mod:
+            out.append(mod)
+            # `from a.b import c` may import submodule a.b.c — record as a candidate too.
+            for alias in node.names:
+                if alias.name and alias.name != "*":
+                    out.append(f"{mod}.{alias.name}")
+    return out
+
+
+def decorator_str(dec):
+    try:
+        return ast.unparse(dec)
+    except Exception:
+        return ""
+
+
+def names_in_target(tgt):
+    """Plain-name assignment targets (Name, or Name elements of a Tuple/List)."""
+    if isinstance(tgt, ast.Name):
+        return [tgt.id]
+    if isinstance(tgt, (ast.Tuple, ast.List)):
+        out = []
+        for el in tgt.elts:
+            out.extend(names_in_target(el))
+        return out
+    return []
+
+
+# --- mechanical enrichments (deterministic ast facts; no type inference) ----------
+# params, return annotation, raises/catches, self-field access, static/abstract/
+# visibility flags, and the first docstring line. All are free from `ast` alone;
+# everything here stays honest (e.g. raises are the literal `raise` targets, not a
+# resolved type).
+
+def _unparse(node):
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return ""
+
+
+def _exc_name(node):
+    """The named type of a raised/caught exception expression (drop the call args)."""
+    if isinstance(node, ast.Call):
+        node = node.func
+    return _unparse(node)
+
+
+def raised_excs(fn):
+    out = []
+    for n in ast.walk(fn):
+        if isinstance(n, ast.Raise) and n.exc is not None:
+            nm = _exc_name(n.exc)
+            if nm:
+                out.append(nm)
+    return sorted(set(out))
+
+
+def caught_excs(fn):
+    out = []
+    for n in ast.walk(fn):
+        if isinstance(n, ast.ExceptHandler) and n.type is not None:
+            t = n.type
+            elts = t.elts if isinstance(t, (ast.Tuple, ast.List)) else [t]
+            for el in elts:
+                nm = _exc_name(el)
+                if nm:
+                    out.append(nm)
+    return sorted(set(out))
+
+
+def self_field_names(fn):
+    """`self.x` attribute names touched in a method body (read or write)."""
+    out = set()
+    for n in ast.walk(fn):
+        if isinstance(n, ast.Attribute) and isinstance(n.value, ast.Name) and n.value.id == "self":
+            out.add(n.attr)
+    return sorted(out)
+
+
+def calls_in(fn):
+    """Coarse callee names invoked WITHIN one function/method body (for the
+    symbol-granular call graph). Names are the unparsed call target (e.g.
+    'helper', 'self.foo', 're.sub'); resolution to a single in-repo symbol id —
+    and the unique-name discipline — happens in buildEntities. Reuses the existing
+    per-function ast walk (no extra parse pass)."""
+    out = set()
+    for n in ast.walk(fn):
+        if isinstance(n, ast.Call):
+            try:
+                nm = ast.unparse(n.func)
+            except Exception:
+                nm = ""
+            if nm:
+                out.add(nm)
+    return sorted(out)
+
+
+def first_doc_line(node):
+    try:
+        d = ast.get_docstring(node, clean=True)
+    except Exception:
+        d = None
+    if not d:
+        return ""
+    return d.strip().split("\n", 1)[0].strip()[:120]
+
+
+def visibility_of(name):
+    short = name.rsplit(".", 1)[-1]
+    if short.startswith("__") and not short.endswith("__"):
+        return "private"
+    if short.startswith("_") and not short.startswith("__"):
+        return "protected"
+    return ""  # public is the default — omitted to keep the graph lean
+
+
+def func_extras(node, name, decorators, is_method):
+    """Compact, only-when-present enrichment dict for a function/method define."""
+    extras = {}
+    sig = _unparse(node.args)
+    if sig:
+        extras["params"] = sig[:160]
+    if getattr(node, "returns", None) is not None:
+        r = _unparse(node.returns)
+        if r:
+            extras["returns"] = r[:80]
+    raises = raised_excs(node)
+    if raises:
+        extras["raises"] = raises[:12]
+    catches = caught_excs(node)
+    if catches:
+        extras["catches"] = catches[:12]
+    if is_method:
+        fields = self_field_names(node)
+        if fields:
+            extras["self_fields"] = fields[:24]
+    # per-function callee names — the raw material for the symbol-granular
+    # callsSymbol edge (caller fn -> callee fn). Collected here so the subject
+    # (the enclosing def) is known; buildEntities resolves names to symbol ids.
+    callees = calls_in(node)
+    if callees:
+        extras["calls"] = callees[:50]
+    decset = " ".join(decorators)
+    if "staticmethod" in decset or "classmethod" in decset:
+        extras["is_static"] = True
+    if "abstractmethod" in decset or "abstractproperty" in decset:
+        extras["is_abstract"] = True
+    vis = visibility_of(name)
+    if vis:
+        extras["visibility"] = vis
+    doc = first_doc_line(node)
+    if doc:
+        extras["doc"] = doc
+    return extras
+
+
+def parse_module(src, rel_path):
+    dotted, pkg = dotted_for(rel_path)
+    try:
+        tree = ast.parse(src, filename=rel_path)
+    except (SyntaxError, ValueError):
+        return None  # skip unparseable files (py2 fixtures, templates, etc.)
+
+    imports = []
+    defines = []
+    calls = set()
+    globals_seen = set()
+    exports = []  # names in a literal __all__ (the module's declared public surface)
+
+    def string_list(v):
+        # names from a literal list/tuple of string constants (else [])
+        if not isinstance(v, (ast.List, ast.Tuple)):
+            return []
+        out = []
+        for el in v.elts:
+            if isinstance(el, ast.Constant) and isinstance(el.value, str):
+                out.append(el.value)
+        return out
+
+    def end_of(n):
+        return getattr(n, "end_lineno", None) or n.lineno
+
+    def short_value(v):
+        try:
+            s = ast.unparse(v)
+        except Exception:
+            return ""
+        return s.replace("\n", " ")[:80]
+
+    def add_global(name, target_node, value_node):
+        # Module-level "live object" globals (RHS is a call, e.g. register =
+        # template.Library()) and ALL-CAPS constants — the registration anchors and
+        # config values a sibling-adding task must replicate. Skip noisy locals.
+        if name in globals_seen or value_node is None:
+            return
+        is_call = isinstance(value_node, ast.Call)
+        if not (is_call or name.isupper()):
+            return
+        globals_seen.add(name)
+        rec = {"name": name, "kind": "global", "lineno": target_node.lineno,
+               "end_lineno": end_of(target_node), "decorators": [],
+               "value": short_value(value_node)}
+        if name.isupper():
+            rec["is_constant"] = True
+        vis = visibility_of(name)
+        if vis:
+            rec["visibility"] = vis
+        defines.append(rec)
+
+    # Top-level defs/classes, plus one level of class methods (e.g. Truncator.chars).
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            decs = [decorator_str(d) for d in node.decorator_list]
+            defines.append({"name": node.name, "kind": "function", "lineno": node.lineno,
+                            "end_lineno": end_of(node), "decorators": decs,
+                            **func_extras(node, node.name, decs, is_method=False)})
+        elif isinstance(node, ast.ClassDef):
+            cdoc = first_doc_line(node)
+            cvis = visibility_of(node.name)
+            cls_extra = {}
+            if cdoc:
+                cls_extra["doc"] = cdoc
+            if cvis:
+                cls_extra["visibility"] = cvis
+            defines.append({"name": node.name, "kind": "class", "lineno": node.lineno,
+                            "end_lineno": end_of(node),
+                            "bases": [decorator_str(b) for b in node.bases],
+                            "decorators": [decorator_str(d) for d in node.decorator_list],
+                            **cls_extra})
+            seen_attrs = set()
+            for sub in node.body:
+                if isinstance(sub, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    mdecs = [decorator_str(d) for d in sub.decorator_list]
+                    defines.append({"name": f"{node.name}.{sub.name}", "kind": "method",
+                                    "lineno": sub.lineno, "end_lineno": end_of(sub),
+                                    "decorators": mdecs,
+                                    **func_extras(sub, f"{node.name}.{sub.name}", mdecs, is_method=True)})
+                elif isinstance(sub, ast.AnnAssign) and isinstance(sub.target, ast.Name):
+                    if sub.target.id not in seen_attrs:
+                        seen_attrs.add(sub.target.id)
+                        defines.append({"name": f"{node.name}.{sub.target.id}", "kind": "attribute",
+                                        "lineno": sub.lineno, "end_lineno": end_of(sub), "decorators": []})
+                elif isinstance(sub, ast.Assign):
+                    for tgt in sub.targets:
+                        for nm in names_in_target(tgt):
+                            if nm in seen_attrs:
+                                continue
+                            seen_attrs.add(nm)
+                            defines.append({"name": f"{node.name}.{nm}", "kind": "attribute",
+                                            "lineno": sub.lineno, "end_lineno": end_of(sub), "decorators": []})
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            if node.target.id == "__all__" and node.value is not None:
+                exports = string_list(node.value)
+            else:
+                add_global(node.target.id, node, node.value)
+        elif isinstance(node, ast.Assign):
+            if any(isinstance(t, ast.Name) and t.id == "__all__" for t in node.targets):
+                exports = string_list(node.value)
+            else:
+                for tgt in node.targets:
+                    for nm in names_in_target(tgt):
+                        add_global(nm, node, node.value)
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            imports.extend(import_targets(node, pkg))
+        elif isinstance(node, ast.Call):
+            try:
+                name = ast.unparse(node.func)
+            except Exception:
+                name = ""
+            if name:
+                calls.add(name)
+
+    return {"path": rel_path.replace(os.sep, "/"), "dotted": dotted,
+            "imports": sorted(set(imports)), "defines": defines, "calls": sorted(calls),
+            "exports": exports}
+
+
+def main():
+    if len(sys.argv) < 2:
+        sys.stderr.write("usage: extract_ast.py <repo_path>\n")
+        sys.exit(2)
+    root = os.path.abspath(sys.argv[1])
+    modules = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".")]
+        for fn in filenames:
+            if not fn.endswith(".py"):
+                continue
+            abs_path = os.path.join(dirpath, fn)
+            rel_path = os.path.relpath(abs_path, root)
+            try:
+                with open(abs_path, "r", encoding="utf-8") as fh:
+                    src = fh.read()
+            except (OSError, UnicodeDecodeError):
+                continue
+            mod = parse_module(src, rel_path)
+            if mod:
+                modules.append(mod)
+    json.dump({"modules": modules}, sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

package/src/index/index-repo.mjs

@@ -0,0 +1,173 @@
+// The deterministic, offline code-graph PRODUCER. Walks a repo, runs the
+// registered language extractors, reads git history, and assembles the typed
+// `entities` payload via graph-build.mjs's buildEntities() — the one write-path
+// primitive tmct already had but never called against real source. Writes
+// <repo>/.tmct/graph.json, the artifact the provider seam (source.mjs) reads.
+//
+// ZERO model calls: CPU-bound static parsing + git only. This is the write side
+// of the reader/producer boundary source.mjs documents — source.mjs READS a
+// graph, this module PRODUCES one; they are deliberately separate modules.
+
+import { writeFile, mkdir, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { buildEntities } from "../adapters/graph-build.mjs";
+import { ingestSchemaDocs } from "../tools/schema-docs.mjs";
+import { loadIgnores, relPath } from "./walk.mjs";
+import { ingestRepo, LANG_EXTS } from "./registry.mjs";
+import { exec } from "./spawn.mjs";
+
+// Every file extension the index covers — gates the git-log file filters so
+// history is collected for exactly the languages the extractors parsed.
+const INDEXED_EXTS = new Set(LANG_EXTS);
+const isIndexedFile = (f) => {
+  const dot = f.lastIndexOf(".");
+  return dot >= 0 && INDEXED_EXTS.has(f.slice(dot).toLowerCase());
+};
+
+const GIT_LOG_COMMITS = 300;      // module-level history depth (cheap; name-only)
+const HISTORY_SYMBOL_DEPTH = 120; // symbol-level line-range pass depth (the costly one)
+// Git history is the one place this producer shells an unbounded command over
+// arbitrary repo history, so it gets a hard wall-clock timeout: a wedged or
+// pathological `git log` can never hang an index.
+const GIT_TIMEOUT_MS = 300_000;
+
+function gitDepth(env = process.env) {
+  const n = Number(env.TMCT_GIT_DEPTH);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : GIT_LOG_COMMITS;
+}
+function historySymbolDepth(env = process.env) {
+  const raw = env.TMCT_HISTORY_SYMBOL_DEPTH;
+  if (raw === undefined || raw === "") return HISTORY_SYMBOL_DEPTH;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : HISTORY_SYMBOL_DEPTH;
+}
+
+/** A one-line failure reason for a git-history exec, or null on clean success.
+ *  Partial parseable output is ALWAYS kept by the caller — this only records WHY
+ *  the result may be incomplete, so an index never silently loses history edges
+ *  without saying so. */
+function gitPassError({ code, stderr, timedOut, truncated }) {
+  if (timedOut) return "timed out after 300s";
+  if (code !== 0) {
+    const tail = String(stderr || "").trim().split("\n").pop()?.slice(-200) || "";
+    return `git exited ${code}${tail ? `: ${tail}` : ""}`;
+  }
+  if (truncated) return "output truncated — history incomplete";
+  return null;
+}
+
+/** git log → {commits:[{sha, author, date, subject, files[]}], error}. Header
+ *  record fields are \x1e-separated; commits are \x1f-separated. */
+async function runGitLog(repoPath, depth = gitDepth()) {
+  const res = await exec("git",
+    ["log", "-n", String(depth), "--no-renames", "--name-only",
+      "--pretty=format:%x1f%H%x1e%an%x1e%aI%x1e%s"],
+    { cwd: repoPath, timeout: GIT_TIMEOUT_MS });
+  const out = [];
+  for (const chunk of res.stdout.split("\x1f")) {
+    const nl = chunk.indexOf("\n");
+    const header = (nl === -1 ? chunk : chunk.slice(0, nl)).trim();
+    if (!header) continue;
+    const [sha, author = "", date = "", subject = ""] = header.split("\x1e");
+    if (!sha) continue;
+    const files = (nl === -1 ? "" : chunk.slice(nl + 1))
+      .split("\n").map((l) => l.trim()).filter(isIndexedFile);
+    out.push({ sha: sha.trim(), author, date, subject, files });
+  }
+  return { commits: out, error: gitPassError(res) };
+}
+
+/** git log -p --unified=0 → {hunks:[{sha, ranges:{path:[[start,end],…]}}], error}.
+ *  Parses the NEW-side hunk header (`+c,d`) into the changed line range; the
+ *  assembly step intersects those with current symbol spans. Depth 0 → no pass. */
+async function runGitLogHunks(repoPath, depth = historySymbolDepth()) {
+  if (!depth) return { hunks: [], error: null };
+  const res = await exec("git",
+    ["log", "-n", String(depth), "--no-renames", "--no-color", "--unified=0",
+      "--pretty=format:%x1f%H"],
+    { cwd: repoPath, timeout: GIT_TIMEOUT_MS });
+  const out = [];
+  let cur = null;
+  let file = null;
+  for (const line of res.stdout.split("\n")) {
+    if (line.startsWith("\x1f")) {
+      cur = { sha: line.slice(1).trim(), ranges: {} };
+      if (cur.sha) out.push(cur); else cur = null;
+      file = null;
+      continue;
+    }
+    if (!cur) continue;
+    if (line.startsWith("+++ ")) {
+      const m = line.match(/^\+\+\+ b\/(.+?)\s*$/);
+      file = m && isIndexedFile(m[1]) ? m[1] : null;
+      if (file && !cur.ranges[file]) cur.ranges[file] = [];
+      continue;
+    }
+    if (file && line.startsWith("@@")) {
+      const m = line.match(/@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+      if (!m) continue;
+      const start = Number(m[1]);
+      const count = m[2] === undefined ? 1 : Number(m[2]);
+      cur.ranges[file].push(count > 0 ? [start, start + count - 1] : [start, start]);
+    }
+  }
+  return { hunks: out, error: gitPassError(res) };
+}
+
+/** One repo's raw extraction — parsers + git, NO graph assembly. `historyDepth`:
+ *  undefined → defaults; 0 → skip both git passes; N>0 → cap both at N. */
+export async function extractRepo(repoPath, { ignores = true, historyDepth } = {}) {
+  const ignore = ignores ? await loadIgnores(repoPath) : null;
+  const skipHistory = historyDepth === 0;
+  const nameDepth = historyDepth === undefined ? gitDepth() : historyDepth;
+  const symbolDepth = historyDepth === undefined ? historySymbolDepth() : historyDepth;
+  // A git-less repo is a first-class case — no `.git`, no history, silently.
+  const hasGit = skipHistory ? false : await stat(join(repoPath, ".git")).then(() => true).catch(() => false);
+
+  const gitErrors = [];
+  const [langResult, gitLog] = await Promise.all([
+    ingestRepo(repoPath, { ignore }),
+    hasGit ? runGitLog(repoPath, nameDepth) : Promise.resolve({ commits: [], error: null }),
+  ]);
+  if (gitLog.error) gitErrors.push({ pass: "name-only", message: gitLog.error });
+
+  const runSymbol = hasGit && symbolDepth > 0;
+  const hunks = runSymbol ? await runGitLogHunks(repoPath, symbolDepth) : { hunks: [], error: null };
+  if (hunks.error) gitErrors.push({ pass: "symbol-hunk", message: hunks.error });
+
+  return {
+    modules: langResult.modules, perLang: langResult.perLang, failures: langResult.failures,
+    commits: gitLog.commits, symbolHistory: hunks.hunks, gitErrors,
+    historyDepth: { name: hasGit ? nameDepth : 0, symbol: runSymbol ? symbolDepth : 0 },
+  };
+}
+
+/** Assemble the entities payload from a raw extraction. Runs ingestSchemaDocs so
+ *  the written artifact is the writer-ingested form (the same convention the
+ *  committed fixtures carry — schema self-docs are baked in at produce time). */
+export function assembleEntities({ modules, commits = [], symbolHistory = [], generatedAt = "", prose = true }) {
+  const entities = buildEntities(modules, commits, { generatedAt, symbolHistory, prose });
+  ingestSchemaDocs(entities);
+  return entities;
+}
+
+/** Index a repo end to end: extract + assemble + write <repo>/.tmct/graph.json.
+ *  Returns {graphFile, bytes, modules, symbols, perLang, gitErrors, historyDepth}. */
+export async function indexRepository(repoPath, { ignores = true, historyDepth, prose = true, generatedAt } = {}) {
+  const raw = await extractRepo(repoPath, { ignores, historyDepth });
+  const entities = assembleEntities({
+    modules: raw.modules, commits: raw.commits, symbolHistory: raw.symbolHistory,
+    generatedAt: generatedAt ?? new Date().toISOString(), prose,
+  });
+  const graphFile = join(repoPath, ".tmct", "graph.json");
+  await mkdir(dirname(graphFile), { recursive: true });
+  const payload = JSON.stringify(entities);
+  await writeFile(graphFile, payload);
+  const symbols = raw.modules.reduce((n, m) => n + (m.defines?.length || 0), 0);
+  return {
+    graphFile, bytes: payload.length, modules: raw.modules.length, symbols,
+    perLang: raw.perLang, failures: raw.failures, gitErrors: raw.gitErrors, historyDepth: raw.historyDepth,
+  };
+}
+
+export { relPath };

package/src/index/registry.mjs

@@ -0,0 +1,37 @@
+// The extractor REGISTRY — the single place a language backend plugs in. Keyed
+// by language; `exts` is the file-extension surface it owns, `extractor` the
+// module that turns those files into the shared `{modules:[…]}` contract. Every
+// backend emits the SAME shape (path, dotted, imports, defines, calls, exports),
+// so everything downstream (index-repo.mjs, buildEntities) is language-agnostic.
+import * as jsts from "./extract-jsts.mjs";
+import * as python from "./extract-python.mjs";
+
+export const REGISTRY = {
+  "js/ts": { exts: jsts.meta.exts, extractor: jsts },
+  python: { exts: python.meta.exts, extractor: python },
+};
+
+/** The full set of file extensions the registry covers (sorted, lower-cased). */
+export const LANG_EXTS = [...new Set(Object.values(REGISTRY).flatMap((r) => r.exts))].sort();
+
+/** Parse every registered language under `root` and merge the per-language module
+ *  lists into one. Returns {modules, perLang, totalFiles, failures}. A language
+ *  with zero files present is silently absent from `perLang`. */
+export async function ingestRepo(root, { ignore = null } = {}) {
+  const allModules = [];
+  const perLang = {};
+  let totalFiles = 0;
+  const allFailures = [];
+  for (const [lang, { extractor }] of Object.entries(REGISTRY)) {
+    const t0 = Date.now();
+    const { modules, failures, fileCount } = await extractor.ingest(root, { ignore });
+    const ms = Date.now() - t0;
+    if (fileCount === 0) continue; // language not present
+    for (const m of modules) allModules.push(m);
+    totalFiles += fileCount;
+    for (const f of failures) allFailures.push(f);
+    const symbols = modules.reduce((n, m) => n + (m.defines?.length || 0), 0);
+    perLang[lang] = { lib: extractor.meta.lib, files: fileCount, modules: modules.length, symbols, failures: failures.length, ms };
+  }
+  return { modules: allModules, perLang, totalFiles, failures: allFailures };
+}

package/src/index/spawn.mjs

@@ -0,0 +1,35 @@
+// Shared child-process runner for the producer's out-of-process backends (git
+// history, the Python AST extractor). Collects stdout, never rejects, and arms an
+// optional SIGKILL wall-clock so a wedged subprocess can never hang an index.
+
+import { spawn } from "node:child_process";
+
+/** spawn, collect stdout; resolve {code, stdout, stderr, timedOut, truncated}
+ *  (never reject). `timeout` (ms, >0) arms a SIGKILL wall-clock; `truncated` is set
+ *  when stdout exceeded maxBuffer (dropped bytes → an incomplete result the caller
+ *  must NOT treat as authoritative). */
+export function exec(cmd, args, { cwd, maxBuffer = 512 * 1024 * 1024, timeout = 0 } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { cwd });
+    let stdout = "";
+    let stderr = "";
+    let size = 0;
+    let truncated = false;
+    let timedOut = false;
+    const timer = timeout > 0 ? setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, timeout) : null;
+    child.stdout?.on("data", (d) => { size += d.length; if (size <= maxBuffer) stdout += d; else truncated = true; });
+    child.stderr?.on("data", (d) => (stderr += d));
+    child.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      if (timedOut) {
+        resolve({ code: -1, stdout, stderr: stderr + `timed out after ${Math.round(timeout / 1000)}s`, timedOut: true, truncated });
+      } else {
+        resolve({ code: code ?? -1, stdout, stderr, timedOut: false, truncated });
+      }
+    });
+    child.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      resolve({ code: -1, stdout, stderr: stderr + String(err), timedOut, truncated });
+    });
+  });
+}

package/src/services/chat-session.mjs

@@ -209,6 +209,13 @@ export async function createSession({
   // the flag/env tiers above stay authoritative when set.
   if (toml?.corpus?.tier === "tier3") liveReferenceOn = true;
 
+  // tmct.toml's [graph] read_only turns any session against this repo into a
+  // read-only one, exactly as --ephemeral does: the graph is read for
+  // structure but nothing (upsert, logs, memory) is written back into the
+  // repo's .tmct/. Committed example fixtures carry it so a plain
+  // `tmct chat --repo examples/<x>` never mutates the hand-stamped graph.
+  if (toml?.graph?.readOnly) ephemeral = true;
+
   // Ephemeral: keep config.graphFile pointing at the READ graph, but divert the
   // write base (repo → logs/memory/sessions) to a throwaway temp dir. The committed
   // target is never touched; the demo's memory simply doesn't persist across runs.
@@ -332,9 +339,9 @@ export async function createSession({
     // no code graph → point at how to GET one (a graph producer / --repo / the shipped
     // example), and at what IS answerable now — `vocabHint` is only ever a term
     // confirmed to resolve in THIS session's actual seed state (see vocabExampleHint),
-    // never a hardcoded example that might not have been seeded. tmct reads graphs;
-    // it never indexes code itself.
-    ...(noCodeGraph ? [`for code structure, point me at a .tmct/graph.json with --repo <path> or try \`npm run example:mini\` (tmct reads graphs, it doesn't index code). ${vocabHint}`] : []),
+    // never a hardcoded example that might not have been seeded. tmct can index a
+    // repo itself (`tmct index`) or read a graph any other producer wrote.
+    ...(noCodeGraph ? [`for code structure, index this repo with \`tmct index\`, or point me at a .tmct/graph.json with --repo <path> (or try \`npm run example:mini\`). ${vocabHint}`] : []),
     "pass --repo <path> to target a different repo",
     "ask a question, or /help for commands (/stats for an overview) — /exit to leave",
   ];

package/src/services/chat.mjs

@@ -602,7 +602,7 @@ export function answerCount(graph, query) {
     // empty — an honest, non-dangling message pointing at how to load one.
     if (!kinds.length) {
       return `I can't count "${noun}" — no code graph is loaded yet, so there's nothing to count ` +
-        `(point me at one with --repo, or run "npm run example:mini").`;
+        `(index this repo with "tmct index", point me at another with --repo, or run "npm run example:mini").`;
     }
     return `I can't count "${noun}". I count: ${kinds.join(", ")}. ` +
       `Try "how many classes are there".`;
@@ -2077,8 +2077,8 @@ function orientationAnswer(templates, graph, vocabHint) {
  *  null), matching the file's "never crash, always degrade to one honest line"
  *  ethos. Kept short and hand-written so it never drifts silently. */
 const ORIENTATION_EMPTY_FALLBACK = "I'm tmct — a deterministic, offline chat assistant (no LLM). "
-  + "For code structure (imports, calls, definitions) point me at a repo with `--repo <path>`, "
-  + "or try the shipped example `npm run example:mini`. tmct reads graphs; it doesn't index code itself. /help for commands.";
+  + "For code structure (imports, calls, definitions) run `tmct index` here, point me at a repo with `--repo <path>`, "
+  + "or try the shipped example `npm run example:mini`. /help for commands.";
 
 /** A dynamic orientation string for the meta/self lane: a /stats-style overview
  *  when a code graph is loaded, else the honest empty-graph orientation — rendered
@@ -13009,8 +13009,8 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       answer = `${answer}\n(I don't know that yet — you can teach me: say "remember: <thing> is a <kind>".)`;
       note(trace, "intermediate: HONEST-EMPTY POLISH — a browser miss points at the teach lane, not the CLI-only --repo remedy");
     } else {
-      answer = `${answer}\n(this repo has no code graph — for structure, point me at a \`.tmct/graph.json\` with \`--repo <path>\` or run \`npm run example:mini\`; tmct doesn't index code itself.)`;
-      note(trace, "intermediate: HONEST-EMPTY POLISH — the loaded graph has 0 modules, so the dead-end got a --repo/tmct init pointer appended");
+      answer = `${answer}\n(this repo has no code graph — index it with \`tmct index\`, point me at a \`.tmct/graph.json\` with \`--repo <path>\`, or run \`npm run example:mini\`.)`;
+      note(trace, "intermediate: HONEST-EMPTY POLISH — the loaded graph has 0 modules, so the dead-end got a tmct index/--repo pointer appended");
     }
   }
   // TEACH-OFFER: a "what is X" miss where X is genuinely unknown EVERYWHERE —