@polycode-projects/the-mechanical-code-talker 2.11.11 → 3.0.0

package/README.md

@@ -1150,8 +1150,10 @@ node bin/tmct.mjs cli tmct_untested '{"repo_path":"examples/mini-webapp"}'
 
 ## The repository interface
 
-tmct is not an indexer, so it consumes a graph through a typed contract any
-producer can implement. That contract is first-class: a **versioned (1.1.0),
+tmct consumes a graph through a typed contract any producer can implement —
+including its own `tmct index` command, which walks a repo's source and writes
+the graph, and any external producer (seonix, a CI indexer, a hand-written JSON
+file) feeding the same seam. That contract is first-class: a **versioned (1.1.0),
 OWL-grounded, machine-readable service definition** (`docs/repository-interface.md`
 plus a JSON schema) of every service, its arguments, result types, and error
 contract. The interface returns a miss as a normal value. It never throws to

package/bin/tmct.mjs

@@ -2,7 +2,8 @@
 // tmct — The Mechanical Code Talker. The headline entry is CHAT: a bare
 // invocation drops you into a tolerant, offline, $0 prompt that guides you
 // toward precision queries about a repository (ELIZA/PARRY-style, but obsessed
-// with software). No model calls; tmct keeps no codebase index of its own.
+// with software). No model calls; tmct indexes a repo on request (tmct index)
+// or reads a graph any other producer wrote.
 //
 //   tmct                                   → interactive chat (the headline)
 //   tmct chat [--repo <abs>] [--plain]     → same, explicit
@@ -49,7 +50,7 @@ process.on("warning", (warning) => {
 const HELP = `tmct — The Mechanical Code Talker
 
 A tolerant, offline, $0 chat that guides you toward precision queries about a
-software repository. No model calls; no codebase index of its own.
+software repository. No model calls; index a repo with \`tmct index\`, or read any producer's graph.
 
 Usage:
 ${renderUsage()}
@@ -986,6 +987,36 @@ async function main() {
     return;
   }
 
+  if (mode === "index") {
+    // `tmct index` — the code-graph PRODUCER. Walks a repo's own source, parses
+    // it (JS/TS today, via the TypeScript compiler API), reads git history, and
+    // writes <repo>/.tmct/graph.json — the same artifact chat/serve/cli read
+    // through the provider seam. This is tmct producing a graph for the first
+    // time; the seam that consumes one is unchanged.
+    const rest = process.argv.slice(3);
+    const { strFlag } = await import("../src/services/cli-args.mjs");
+    const { resolve: resolvePath } = await import("node:path");
+    const { indexRepository } = await import("../src/index/index-repo.mjs");
+    const repoFlag = strFlag(rest, ["--repo"]);
+    const repoRoot = repoFlag ? resolvePath(process.cwd(), repoFlag) : process.cwd();
+    const noHistory = rest.includes("--no-history");
+    const stats = await indexRepository(repoRoot, noHistory ? { historyDepth: 0 } : {});
+    for (const { pass, message } of stats.gitErrors || []) {
+      process.stderr.write(`tmct index: WARNING git history pass '${pass}' — ${message} (graph built without those edges)\n`);
+    }
+    const perLang = Object.entries(stats.perLang)
+      .map(([lang, s]) => `${lang}: ${s.modules} modules, ${s.symbols} symbols`).join("; ");
+    const kib = (stats.bytes / 1024).toFixed(1);
+    process.stdout.write(
+      `tmct index — wrote ${stats.graphFile} (${stats.modules} modules, ${stats.symbols} symbols; ${kib} KiB)\n`
+      + (perLang ? `${perLang}\n` : "no supported source found under the repo\n"),
+    );
+    if (stats.failures?.length) {
+      process.stderr.write(`tmct index: ${stats.failures.length} file(s) failed to parse (skipped): ${stats.failures.slice(0, 5).join(", ")}${stats.failures.length > 5 ? ", …" : ""}\n`);
+    }
+    return;
+  }
+
   if (mode === "import") {
     // `tmct import` — activate+seed into an ALREADY-initialized repo, reusing
     // the SAME resolvePluggableInput/activatePluggableInput seam `init`'s own

package/corpus/tier2/generate.mjs

@@ -173,7 +173,7 @@ export const CORPUSES = {
     ],
   },
 
-  // PLAN_AGENTS.md Phase 1's "wider general-knowledge seed set" bullet: the
+  // The wider general-knowledge seed set: the
   // three corpuses above are all code-domain-specific (a LANGUAGE or a cloud
   // DOMAIN); this one deliberately is NOT — everyday-knowledge concepts (the
   // natural world, weather, food, common objects) with zero code-domain

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.11.11",
+  "version": "3.0.0",
   "private": false,
   "type": "module",
-  "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",
+  "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; indexes a repo on request (tmct index) or reads any producer's graph.",
   "keywords": [
     "chatbot",
     "no-llm",
@@ -78,6 +78,7 @@
     "ink": "^7.1.0",
     "react": "^19.2.7",
     "smol-toml": "^1.7.0",
+    "typescript": "~5.6.2",
     "wink-eng-lite-web-model": "^1.8.1",
     "wink-nlp": "^2.4.0"
   },

package/src/adapters/source.mjs

@@ -3,12 +3,14 @@
 // stub it); in production it reads the JSON artifact the deterministic indexer
 // wrote to config.graphFile. No network, no model calls.
 //
-// This module is the PROVIDER SEAM (docs/adapter-contract.md):
-// any graph producer can feed tmct either by writing the entities-payload JSON
-// where config.graphFile points, or by registering a custom loader with
-// registerProvider() — no indexer is ever imported here. tmct only READS
-// through this seam; its own writes go to .tmct/memory/ (src/memory/), never
-// back into a provider's artifact.
+// This module is the READ SEAM (docs/adapter-contract.md): any graph producer
+// can feed tmct either by writing the entities-payload JSON where
+// config.graphFile points, or by registering a custom loader with
+// registerProvider(). The PRODUCER lives elsewhere — tmct's own `tmct index`
+// (src/index/) is one such producer, and it writes through that same file path,
+// not through this module. Keeping the reader and the producer in separate module
+// trees is deliberate: this module only READS, and tmct's own writes go to
+// .tmct/memory/ (src/memory/), never back into a provider's graph artifact.
 
 import { readFile } from "node:fs/promises";
 import { ToolError } from "./config.mjs";

package/src/adapters/toml-config.mjs

@@ -129,8 +129,9 @@ export async function normalizeConfig(raw, { configDir } = {}) {
 
   // Research-lane knobs (src/services/research.mjs): sparse PASS-THROUGH,
   // same discipline as [games.*] — the raw `[research]` table
-  // (fanout_limit / depth_limit / min_interval_ms, snake_case) rides through
-  // unmodified; clamping and default-filling is resolveResearchConfig's job.
+  // (fanout_limit / max_depth / max_topics / min_interval_ms, snake_case)
+  // rides through unmodified; clamping and default-filling is
+  // resolveResearchConfig's job.
   if (src.research !== undefined) cfg.research = src.research;
 
   const idx = src.index || {};

package/src/domain/cli-verbs.mjs

@@ -68,6 +68,15 @@ export const CLI_VERBS = [
       { flag: "[--memory-backend <default|memory|sqlite>]", prose: ["write tmct.toml's [memory] backend", "(same flag name as `tmct chat`) — a later `tmct chat`", "in this repo picks it up with no flag needed"] },
     ],
   },
+  {
+    mode: "index",
+    errorLabel: "index",
+    usage: "tmct index [--repo <abs>]",
+    prose: ["produce a code graph from a repo's OWN source (default: cwd):"],
+    flags: [
+      { flag: "[--no-history]", prose: ["walk the tree, parse JS/TS with the TypeScript compiler", "API, read git history, and write <repo>/.tmct/graph.json —", "the artifact chat/serve/cli then read. --no-history skips", "the git passes (no commit/touches/cochange edges)"] },
+    ],
+  },
   {
     mode: "import",
     errorLabel: "import",

package/src/domain/grammar/ace.mjs

@@ -528,6 +528,15 @@ export function parseAce(sentence, lexicon = loadLexicon()) {
 const IMPERATIVE_VERBS = new Set(["go", "take", "drop", "open", "unlock", "close", "give", "look", "talk", "examine"]);
 const IMPERATIVE_DIRECTIONS = new Set(["north", "south", "east", "west", "up", "down"]);
 
+// The object pronouns an imperative object slot may carry ("examine it", "take
+// them", "talk to him"). This parser only MARKS such a slot with the bare
+// pronoun as its term — the antecedent lives in the running world, not the
+// sentence, so binding it to a concrete object is the adventure lane's job (it
+// alone holds the session's FOCUS). Kept out of resolveNP's lexicon gate on
+// purpose: a pronoun is never a declared noun, so without this it rides out as
+// residue and mis-declines as an unknown word.
+export const OBJECT_PRONOUNS = new Set(["it", "them", "him", "her"]);
+
 const VERB_SYNONYMS = new Map([
   ["pick up", "take"], ["pick", "take"], ["grab", "take"],
   ["put down", "drop"], ["set down", "drop"], ["leave", "drop"],
@@ -603,8 +612,14 @@ function resolveImperativeVerb(toks) {
   return { ...retried, corrected: { from: first, to: fixedFirst } };
 }
 
-/** Resolve one imperative object phrase to its bare lexicon term. */
+/** Resolve one imperative object phrase to its bare lexicon term. A lone
+ *  object pronoun ("it", "them", "him", "her") rides through as its own term
+ *  for the lane to bind against the session focus — never a lexicon lookup,
+ *  never residue. */
 function imperativeNP(lexicon, tokens) {
+  if (tokens.length === 1 && OBJECT_PRONOUNS.has(tokens[0].toLowerCase())) {
+    return { term: tokens[0].toLowerCase(), unknown: [] };
+  }
   const np = resolveNP(lexicon, tokens);
   if (np.term == null) return { term: null, unknown: np.unknown };
   return { term: local(lexicon, np.term), unknown: [] };

package/src/index/extract-jsts.mjs

@@ -0,0 +1,251 @@
+// JS/TS extractor — TypeScript compiler API (direct `typescript` dep). Uses
+// ts.createSourceFile per file (no Program / no type-checker): the fast,
+// deterministic, offline structural pass. Covers .ts/.tsx/.js/.jsx/.mjs/.cjs.
+// Emits the `{path,dotted,imports,defines,calls,exports}` contract
+// graph-build.mjs's buildEntities() consumes.
+//
+// Both module systems are read: ESM import/export declarations AND a CommonJS
+// pass (top-level CJS require calls with literal specifiers → imports;
+// module.exports / exports.name assignments → exports) — CJS-only repos were
+// producing edge-empty graphs before the CJS pass existed.
+//
+// Fidelity note: params/returns are ANNOTATION strings (Group-A mechanical), not
+// resolved types — the same honesty the Python path keeps ("returns = annotation
+// only"). A type-RESOLVED pass (real Program + checker) is a research horizon,
+// not run here.
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import ts from "typescript";
+import { walk, relPath } from "./walk.mjs";
+
+const EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+const stripExt = (p) => p.replace(/\.(tsx?|jsx?|mjs|cjs)$/i, "");
+
+function scriptKind(path) {
+  if (/\.tsx$/i.test(path)) return ts.ScriptKind.TSX;
+  if (/\.ts$/i.test(path)) return ts.ScriptKind.TS;
+  if (/\.jsx$/i.test(path)) return ts.ScriptKind.JSX;
+  return ts.ScriptKind.JS;
+}
+
+const lineOf = (sf, node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+const endLineOf = (sf, node) => sf.getLineAndCharacterOfPosition(node.getEnd()).line + 1;
+
+/** "(a: string, b = 3)" → "a: string, b = 3" (annotation strings; not resolved). */
+function paramsText(sf, node) {
+  const ps = node.parameters || [];
+  return ps.map((p) => p.getText(sf).replace(/\s+/g, " ").trim()).join(", ").slice(0, 160);
+}
+function returnText(sf, node) {
+  return node.type ? node.type.getText(sf).replace(/\s+/g, " ").trim().slice(0, 80) : "";
+}
+function firstDocLine(sf, node) {
+  const ranges = ts.getLeadingCommentRanges(sf.text, node.getFullStart()) || [];
+  for (const r of ranges) {
+    const raw = sf.text.slice(r.pos, r.end);
+    const m = raw.replace(/^\/\*\*?|\*\/$/g, "").split("\n").map((l) => l.replace(/^\s*\*?\s?/, "").trim()).find(Boolean);
+    if (m) return m.slice(0, 120);
+  }
+  return "";
+}
+const hasMod = (node, kind) => (node.modifiers || []).some((m) => m.kind === kind);
+function visibilityOf(node) {
+  if (hasMod(node, ts.SyntaxKind.PrivateKeyword)) return "private";
+  if (hasMod(node, ts.SyntaxKind.ProtectedKeyword)) return "protected";
+  return "";
+}
+function decoratorsOf(sf, node) {
+  const ds = ts.canHaveDecorators?.(node) ? ts.getDecorators?.(node) : null;
+  return (ds || []).map((d) => d.expression.getText(sf).replace(/\s+/g, " ").slice(0, 80));
+}
+
+/** Collect callee names within a node body (coarse; unparsed call target). */
+function callsIn(sf, node) {
+  const out = new Set();
+  const visit = (n) => {
+    if (ts.isCallExpression(n)) {
+      const t = n.expression;
+      let name = "";
+      if (ts.isIdentifier(t)) name = t.text;
+      else if (ts.isPropertyAccessExpression(t)) name = t.getText(sf);
+      if (name) out.add(name.slice(0, 80));
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(node, visit);
+  return [...out].sort();
+}
+
+export async function extractFile(absPath, root) {
+  const text = await readFile(absPath, "utf8").catch(() => null);
+  if (text == null) return { failed: true, path: relPath(root, absPath) };
+  const path = relPath(root, absPath);
+  let sf;
+  try {
+    sf = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, scriptKind(path));
+  } catch {
+    return { failed: true, path };
+  }
+  const dir = dirname(path);
+  const imports = new Set();
+  const calls = new Set();
+  const defines = [];
+  const exports = new Set();
+
+  const resolveSpecifier = (spec) => {
+    if (!spec || !spec.startsWith(".")) { if (spec) imports.add(spec); return; } // bare/external
+    const joined = join(dir, spec).split(/[\\/]/).join("/");
+    const base = stripExt(joined);
+    imports.add(base);
+    imports.add(`${base}/index`); // dir-import fallback (./foo → ./foo/index)
+  };
+
+  // CommonJS pass: CJS require / module.exports repos were leaving graphs
+  // edge-empty. Top-level statements only, STRICTLY literal arguments — a
+  // computed specifier is skipped, never guessed (the house "no wrong edge" rule).
+  /** A CJS require call with a single literal arg → its specifier, else null. */
+  const requireSpecifier = (node) =>
+    node && ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "require" &&
+    node.arguments.length === 1 && ts.isStringLiteralLike(node.arguments[0])
+      ? node.arguments[0].text
+      : null;
+  /** Peel a `.member` access / parens down to the require call (never enters functions). */
+  const requireIn = (expr) => {
+    let e = expr;
+    while (e && (ts.isPropertyAccessExpression(e) || ts.isParenthesizedExpression(e) || ts.isNonNullExpression?.(e))) e = e.expression;
+    return requireSpecifier(e);
+  };
+  const isModuleExports = (e) =>
+    ts.isPropertyAccessExpression(e) && ts.isIdentifier(e.expression) && e.expression.text === "module" && e.name.text === "exports";
+  const isExportsRef = (e) => isModuleExports(e) || (ts.isIdentifier(e) && e.text === "exports");
+
+  const addFn = (name, node, kind, extra = {}) => {
+    defines.push({
+      name, kind, lineno: lineOf(sf, node), end_lineno: endLineOf(sf, node),
+      decorators: decoratorsOf(sf, node),
+      params: paramsText(sf, node), returns: returnText(sf, node),
+      calls: callsIn(sf, node), doc: firstDocLine(sf, node),
+      ...(visibilityOf(node) ? { visibility: visibilityOf(node) } : {}),
+      ...extra,
+    });
+  };
+
+  for (const stmt of sf.statements) {
+    // imports / re-exports
+    if (ts.isImportDeclaration(stmt) && stmt.moduleSpecifier && ts.isStringLiteral(stmt.moduleSpecifier)) {
+      resolveSpecifier(stmt.moduleSpecifier.text);
+    } else if (ts.isExportDeclaration(stmt) && stmt.moduleSpecifier && ts.isStringLiteral(stmt.moduleSpecifier)) {
+      resolveSpecifier(stmt.moduleSpecifier.text);
+    }
+    const exported = hasMod(stmt, ts.SyntaxKind.ExportKeyword);
+
+    if (ts.isFunctionDeclaration(stmt) && stmt.name) {
+      addFn(stmt.name.text, stmt, "function");
+      if (exported) exports.add(stmt.name.text);
+    } else if (ts.isClassDeclaration(stmt) && stmt.name) {
+      const cname = stmt.name.text;
+      const bases = [];
+      for (const h of stmt.heritageClauses || []) for (const t of h.types) bases.push(t.getText(sf).slice(0, 80));
+      defines.push({
+        name: cname, kind: "class", lineno: lineOf(sf, stmt), end_lineno: endLineOf(sf, stmt),
+        bases, decorators: decoratorsOf(sf, stmt), doc: firstDocLine(sf, stmt),
+      });
+      if (exported) exports.add(cname);
+      for (const mem of stmt.members) {
+        if (ts.isMethodDeclaration(mem) || ts.isConstructorDeclaration(mem) ||
+            ts.isGetAccessor(mem) || ts.isSetAccessor(mem)) {
+          const mn = mem.name ? mem.name.getText(sf) : "constructor";
+          addFn(`${cname}.${mn}`, mem, "method");
+        } else if (ts.isPropertyDeclaration(mem) && mem.name) {
+          defines.push({
+            name: `${cname}.${mem.name.getText(sf)}`, kind: "attribute",
+            lineno: lineOf(sf, mem), end_lineno: endLineOf(sf, mem), decorators: decoratorsOf(sf, mem),
+          });
+        }
+      }
+    } else if (ts.isInterfaceDeclaration(stmt) && stmt.name) {
+      // interfaces map to Class nodes (type surface) — useful for TS-heavy repos
+      defines.push({
+        name: stmt.name.text, kind: "class", subkind: "interface",
+        lineno: lineOf(sf, stmt), end_lineno: endLineOf(sf, stmt),
+        bases: (stmt.heritageClauses || []).flatMap((h) => h.types.map((t) => t.getText(sf).slice(0, 80))),
+        decorators: [], doc: firstDocLine(sf, stmt),
+      });
+      if (exported) exports.add(stmt.name.text);
+    } else if (ts.isVariableStatement(stmt)) {
+      const isConst = (stmt.declarationList.flags & ts.NodeFlags.Const) !== 0;
+      for (const d of stmt.declarationList.declarations) {
+        // CJS import: const X = <require 'spec'> / const {a} = <require 'spec'> /
+        // const Y = <require 'spec'>.member — BEFORE the identifier-only gate so a
+        // destructuring binding still records the import edge.
+        const reqSpec = requireIn(d.initializer);
+        if (reqSpec != null) resolveSpecifier(reqSpec);
+        if (!ts.isIdentifier(d.name)) continue;
+        const vn = d.name.text;
+        const init = d.initializer;
+        // arrow/function assigned to a const → treat as a function define
+        if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+          addFn(vn, init, "function");
+        } else if (isConst && /^[A-Z0-9_]+$/.test(vn)) {
+          defines.push({ name: vn, kind: "global", lineno: lineOf(sf, stmt), end_lineno: endLineOf(sf, stmt),
+            decorators: [], value: (init ? init.getText(sf) : "").replace(/\s+/g, " ").slice(0, 80), is_constant: true });
+        } else if (init && ts.isCallExpression(init)) {
+          // live-object global (e.g. const router = Router()) — a registration anchor
+          defines.push({ name: vn, kind: "global", lineno: lineOf(sf, stmt), end_lineno: endLineOf(sf, stmt),
+            decorators: [], value: init.getText(sf).replace(/\s+/g, " ").slice(0, 80) });
+        }
+        if (exported) exports.add(vn);
+      }
+    } else if (ts.isExportAssignment?.(stmt)) {
+      exports.add("default");
+    } else if (ts.isExpressionStatement(stmt)) {
+      // CJS exports + side-effect/re-export requires. Walk `=` chains so
+      // `exports = module.exports = X` records one default export, and
+      // `module.exports = <require './lib'>` records both the export and the import.
+      let expr = stmt.expression;
+      while (ts.isBinaryExpression(expr) && expr.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+        const lhs = expr.left;
+        if (isExportsRef(lhs)) exports.add("default");
+        else if (ts.isPropertyAccessExpression(lhs) && isExportsRef(lhs.expression)) {
+          exports.add(lhs.name.text);
+        }
+        expr = expr.right;
+      }
+      const reqSpec = requireIn(expr); // covers a bare side-effect require too
+      if (reqSpec != null) resolveSpecifier(reqSpec);
+    }
+  }
+
+  // module-level coarse calls (whole file)
+  const visit = (n) => {
+    if (ts.isCallExpression(n)) {
+      const t = n.expression;
+      let name = "";
+      if (ts.isIdentifier(t)) name = t.text;
+      else if (ts.isPropertyAccessExpression(t)) name = t.getText(sf);
+      if (name) calls.add(name.slice(0, 80));
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(sf, visit);
+
+  return {
+    path, dotted: stripExt(path),
+    imports: [...imports].sort(), defines, calls: [...calls].sort(), exports: [...exports].sort(),
+  };
+}
+
+/** Ingest a whole tree → {modules, failures, fileCount} contract. */
+export async function ingest(root, { ignore = null } = {}) {
+  const files = await walk(root, EXTS, ignore);
+  const modules = [];
+  const failures = [];
+  for (const f of files) {
+    const mod = await extractFile(f, root);
+    if (mod.failed) failures.push(mod.path);
+    else modules.push(mod);
+  }
+  return { modules, failures, fileCount: files.length };
+}
+
+export const meta = { id: "tsc", language: "js/ts", lib: "typescript compiler API", exts: EXTS };

package/src/index/extract-python.mjs

@@ -0,0 +1,46 @@
+// Python extractor — stdlib `ast`, zero npm dependency. Runs extract_ast.py as a
+// subprocess over the whole repo (the script does its own deterministic walk and
+// emits one JSON doc: {modules:[{path,dotted,imports,defines,calls,exports}]} —
+// the same contract the in-process JS/TS extractor emits) and parses the result.
+//
+// Requires a `python3` interpreter at index time (TMCT_PYTHON overrides). This is
+// a runtime tool, not an npm dependency — no parser library ships. When no .py
+// files are present the subprocess never runs; when python3 is missing but .py
+// files exist, the backend degrades: it skips them and reports the count as
+// failures rather than crashing the whole index (JS/TS still produces its graph).
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { walk, relPath } from "./walk.mjs";
+import { exec } from "./spawn.mjs";
+
+const AST_SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "extract_ast.py");
+const EXTS = [".py"];
+const PYTHON = () => process.env.TMCT_PYTHON || "python3";
+
+/** Ingest every .py file under `root` → {modules, failures, fileCount} contract.
+ *  `ignore` prunes the presence check; extract_ast.py applies its own SKIP_DIRS
+ *  when it walks, so the module set follows the script's exclusions. */
+export async function ingest(root, { ignore = null } = {}) {
+  const files = await walk(root, EXTS, ignore);
+  if (files.length === 0) return { modules: [], failures: [], fileCount: 0 };
+
+  const python = PYTHON();
+  const res = await exec(python, [AST_SCRIPT, root]);
+  if (res.code !== 0) {
+    const why = res.stderr.trim().split("\n").pop()?.slice(-200) || `exit ${res.code}`;
+    process.stderr.write(
+      `tmct index: python backend skipped ${files.length} .py file(s) — "${python}" unavailable or failed (${why})\n`,
+    );
+    return { modules: [], failures: files.map((f) => relPath(root, f)), fileCount: files.length };
+  }
+  let parsed;
+  try { parsed = JSON.parse(res.stdout); }
+  catch {
+    process.stderr.write(`tmct index: python backend produced non-JSON (is "${python}" a Python 3.9+ interpreter?)\n`);
+    return { modules: [], failures: files.map((f) => relPath(root, f)), fileCount: files.length };
+  }
+  const modules = Array.isArray(parsed?.modules) ? parsed.modules : [];
+  return { modules, failures: [], fileCount: files.length };
+}
+
+export const meta = { id: "ast", language: "python", lib: "python stdlib ast", exts: EXTS };