@illuminis/comprism 0.1.0

package/out/graph/read-python.js

@@ -0,0 +1,115 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findPython = findPython;
+exports.readPython = readPython;
+/**
+ * Run the Python reader and collect its facts.
+ *
+ * The parsing is done by Python itself, because the only reader that agrees
+ * with the language is the language's own. A regular expression reader would
+ * produce a map that disagrees with the code, and a map that disagrees with the
+ * code is worse than no map at all: the agent trusts it.
+ *
+ * A machine with no Python interpreter gets an honest answer rather than a
+ * guessed one. The map then says it covers no Python files, and the count is
+ * visible everywhere the map is described.
+ */
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/** The reader script, beside the built code in both a checkout and an install. */
+function scriptPath() {
+    return path.resolve(__dirname, "..", "..", "scripts", "read_python.py");
+}
+let interpreter;
+/** Which Python this machine has, or null. Asked once per process. */
+function findPython() {
+    if (interpreter !== undefined)
+        return interpreter;
+    for (const candidate of ["python3", "python"]) {
+        try {
+            const probe = (0, child_process_1.spawnSync)(candidate, ["-c", "import ast,sys;print(sys.version_info[0])"], { encoding: "utf8", timeout: 10_000 });
+            if (probe.status === 0 && String(probe.stdout).trim() === "3") {
+                interpreter = candidate;
+                return interpreter;
+            }
+        }
+        catch {
+            /* try the next one */
+        }
+    }
+    interpreter = null;
+    return interpreter;
+}
+function readPython(root, rels) {
+    if (!rels.length)
+        return { facts: {}, failures: [], available: true };
+    const python = findPython();
+    const script = scriptPath();
+    if (!python || !fs.existsSync(script)) {
+        return { facts: {}, failures: [], available: false };
+    }
+    // The file list goes in a file, not on the command line. A project with three
+    // thousand Python files produces a command line longer than the operating
+    // system will accept, and the failure is a confusing one: the process simply
+    // does not start.
+    const listFile = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "comprism-map-")), "files.txt");
+    try {
+        fs.writeFileSync(listFile, `${rels.join("\n")}\n`, "utf8");
+        const out = (0, child_process_1.spawnSync)(python, [script, root, listFile], {
+            encoding: "utf8",
+            maxBuffer: 512 * 1024 * 1024,
+            timeout: 300_000,
+        });
+        if (out.status !== 0 || !out.stdout) {
+            return { facts: {}, failures: [], available: false };
+        }
+        const parsed = JSON.parse(out.stdout);
+        return { facts: parsed.facts || {}, failures: parsed.failures || [], available: true };
+    }
+    catch {
+        return { facts: {}, failures: [], available: false };
+    }
+    finally {
+        try {
+            fs.rmSync(path.dirname(listFile), { recursive: true, force: true });
+        }
+        catch {
+            /* a temporary folder that will not delete is not worth failing a job over */
+        }
+    }
+}

package/out/graph/read-typescript.d.ts

@@ -0,0 +1,16 @@
+import type { FactSet } from "./facts";
+type Ts = any;
+/** The TypeScript compiler, or null when this installation has none. */
+export declare function loadCompiler(): Ts | null;
+/** Read every named file. A file that cannot be parsed is REPORTED, never
+ *  silently dropped: a map that quietly covers less than it claims is the one
+ *  failure mode worth engineering against. */
+export declare function readTypeScript(root: string, rels: string[]): {
+    facts: Record<string, FactSet>;
+    failures: {
+        file: string;
+        reason: string;
+    }[];
+    available: boolean;
+};
+export {};

package/out/graph/read-typescript.js

@@ -0,0 +1,292 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCompiler = loadCompiler;
+exports.readTypeScript = readTypeScript;
+/**
+ * Read TypeScript and JavaScript files into code map facts, using the
+ * TypeScript compiler's own parser.
+ *
+ * This guesses nothing. Every object and every link is taken from the syntax
+ * tree, so the same file always produces the same facts and two machines
+ * reading the same project agree. Nothing here calls a model, so it costs
+ * nothing and cannot drift.
+ *
+ * The compiler is loaded lazily and by name. A copy of the tool installed
+ * without it still works: the map simply says it covers no TypeScript, which is
+ * an honest answer, and it is a great deal better than a map built by regular
+ * expression that quietly disagrees with the code.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+let compiler;
+/** The TypeScript compiler, or null when this installation has none. */
+function loadCompiler() {
+    if (compiler !== undefined)
+        return compiler;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        compiler = require("typescript");
+    }
+    catch {
+        compiler = null;
+    }
+    return compiler;
+}
+/** The HTTP verbs a call on an API client uses. */
+const HTTP_VERBS = new Set(["get", "post", "put", "patch", "delete", "head", "request"]);
+/** Looks like an API path rather than an ordinary string.
+ *
+ *  Scanning for anything that starts with a slash picks up image URLs, browser
+ *  routes and CSS paths, and a map full of those is a map nobody trusts. */
+function looksLikeEndpoint(value) {
+    if (!value.startsWith("/") || value.length < 2)
+        return false;
+    if (value.includes(" ") || value.includes("\n"))
+        return false;
+    if (/\.(png|jpg|jpeg|svg|css|ico|webp|woff2?|json|js|map|txt|pdf)$/i.test(value))
+        return false;
+    return /^\/[A-Za-z0-9_\-/{}$:.]+$/.test(value);
+}
+function resolveImport(root, fromFile, spec) {
+    if (!spec.startsWith("."))
+        return null;
+    const base = path.resolve(path.dirname(path.join(root, fromFile)), spec);
+    const candidates = [
+        base, `${base}.ts`, `${base}.tsx`, `${base}.js`, `${base}.jsx`,
+        path.join(base, "index.ts"), path.join(base, "index.tsx"),
+        path.join(base, "index.js"), path.join(base, "index.jsx"),
+    ];
+    for (const candidate of candidates) {
+        try {
+            if (fs.statSync(candidate).isFile()) {
+                return path.relative(root, candidate).split(path.sep).join("/");
+            }
+        }
+        catch {
+            /* not this one */
+        }
+    }
+    return null;
+}
+function readOne(ts, root, rel) {
+    const source = fs.readFileSync(path.join(root, rel), "utf8");
+    const kind = rel.endsWith(".tsx") || rel.endsWith(".jsx")
+        ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+    const sf = ts.createSourceFile(rel, source, ts.ScriptTarget.Latest, true, kind);
+    const objects = [];
+    const links = [];
+    const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+    objects.push({
+        id: rel, kind: "file", name: path.basename(rel), file: rel, line: 1,
+        lang: rel.endsWith("x") ? "tsx" : "ts",
+        lines: source.split("\n").length,
+    });
+    const owner = [rel];
+    /** The symbol a call or a rendered tag belongs to. Never empty: `rel` sits at
+     *  the bottom of the stack and is only ever pushed onto. */
+    const holder = () => owner[owner.length - 1] ?? rel;
+    const declare = (name, node, objectKind, extra = {}) => {
+        const id = `${rel}::${name}`;
+        objects.push({ id, kind: objectKind, name, file: rel, line: lineOf(node), ...extra });
+        links.push({ from: rel, kind: "defines", to: id });
+        return id;
+    };
+    const exported = (node) => !!node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    const tagName = (node) => {
+        const tag = node.tagName;
+        if (ts.isIdentifier(tag))
+            return tag.text;
+        if (ts.isPropertyAccessExpression(tag))
+            return tag.getText();
+        return null;
+    };
+    const calleeName = (expr) => {
+        if (ts.isIdentifier(expr))
+            return { leaf: expr.text, full: expr.text };
+        if (ts.isPropertyAccessExpression(expr))
+            return { leaf: expr.name.text, full: expr.getText() };
+        return null;
+    };
+    /** The string value of a literal or a template, holes flattened. */
+    const pathText = (node) => {
+        if (!node)
+            return null;
+        if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+            return node.text;
+        if (ts.isTemplateExpression(node)) {
+            return node.head.text + node.templateSpans
+                .map((span) => `{}${span.literal.text}`).join("");
+        }
+        return null;
+    };
+    function visit(node) {
+        let pushed = false;
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+            const spec = node.moduleSpecifier.text;
+            const resolved = resolveImport(root, rel, spec);
+            links.push({
+                from: rel, kind: "imports", line: lineOf(node),
+                ...(resolved ? { to: resolved } : { to_name: spec }),
+            });
+        }
+        if (ts.isFunctionDeclaration(node) && node.name) {
+            const name = node.name.text;
+            const objectKind = /^[A-Z]/.test(name) && rel.endsWith("x") ? "component" : "function";
+            owner.push(declare(name, node, objectKind, { exported: exported(node) || undefined }));
+            pushed = true;
+        }
+        else if (ts.isClassDeclaration(node) && node.name) {
+            owner.push(declare(node.name.text, node, "class", { exported: exported(node) || undefined }));
+            pushed = true;
+            for (const base of node.heritageClauses || []) {
+                for (const t of base.types || []) {
+                    const name = t.expression?.getText?.();
+                    if (name)
+                        links.push({ from: holder(), kind: "inherits", to_name: name, line: lineOf(node) });
+                }
+            }
+        }
+        else if (ts.isVariableStatement(node)) {
+            for (const decl of node.declarationList.declarations) {
+                if (!ts.isIdentifier(decl.name) || !decl.initializer)
+                    continue;
+                const init = decl.initializer;
+                if (!ts.isArrowFunction(init) && !ts.isFunctionExpression(init))
+                    continue;
+                const name = decl.name.text;
+                const objectKind = /^[A-Z]/.test(name) && rel.endsWith("x") ? "component" : "function";
+                const id = declare(name, decl, objectKind, { exported: exported(node) || undefined });
+                owner.push(id);
+                ts.forEachChild(init, visit);
+                owner.pop();
+            }
+        }
+        if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+            const tag = tagName(node);
+            if (tag && /^[A-Z]/.test(tag)) {
+                links.push({ from: holder(), kind: "renders", to_name: tag, line: lineOf(node) });
+            }
+        }
+        if (ts.isCallExpression(node)) {
+            const callee = calleeName(node.expression);
+            if (callee && !callee.leaf.startsWith("_")) {
+                links.push({
+                    from: holder(), kind: "calls",
+                    to_name: callee.leaf, full_name: callee.full, line: lineOf(node),
+                });
+            }
+            // An API call found by the CALL, never by the string. `api.get("/x")`,
+            // `client.post(...)`, `fetch(...)`. Looking for anything path shaped
+            // picks up image URLs and browser routes and the map stops being worth
+            // trusting.
+            const isFetch = callee && callee.full === "fetch";
+            const isVerb = callee && HTTP_VERBS.has(callee.leaf)
+                && /api|client|http|request/i.test(callee.full);
+            if (isFetch || isVerb) {
+                const value = pathText(node.arguments[0]);
+                if (value && looksLikeEndpoint(value)) {
+                    links.push({
+                        from: holder(), kind: "calls_endpoint",
+                        to_name: value, line: lineOf(node),
+                        ...(isVerb && callee ? { method: callee.leaf.toUpperCase() } : {}),
+                    });
+                }
+            }
+        }
+        // A data fetching slice: { url: "/things" } or query: () => "/things".
+        if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name)) {
+            const key = node.name.text;
+            if (key === "url" || key === "query") {
+                let value = pathText(node.initializer);
+                if (!value && ts.isArrowFunction(node.initializer)
+                    && !ts.isBlock(node.initializer.body)) {
+                    value = pathText(node.initializer.body);
+                }
+                if (value && looksLikeEndpoint(value)) {
+                    links.push({
+                        from: holder(), kind: "calls_endpoint",
+                        to_name: value, line: lineOf(node),
+                    });
+                }
+            }
+            if (key === "path") {
+                const value = pathText(node.initializer);
+                if (value && value.startsWith("/")) {
+                    links.push({
+                        from: holder(), kind: "browser_route",
+                        to_name: value, line: lineOf(node),
+                    });
+                }
+            }
+        }
+        if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name)
+            && node.name.text === "path" && node.initializer) {
+            const inner = ts.isJsxExpression(node.initializer)
+                ? node.initializer.expression : node.initializer;
+            const value = pathText(inner);
+            if (value && value.startsWith("/")) {
+                links.push({
+                    from: holder(), kind: "browser_route",
+                    to_name: value, line: lineOf(node),
+                });
+            }
+        }
+        ts.forEachChild(node, visit);
+        if (pushed)
+            owner.pop();
+    }
+    ts.forEachChild(sf, visit);
+    return { objects, links };
+}
+/** Read every named file. A file that cannot be parsed is REPORTED, never
+ *  silently dropped: a map that quietly covers less than it claims is the one
+ *  failure mode worth engineering against. */
+function readTypeScript(root, rels) {
+    const ts = loadCompiler();
+    if (!ts)
+        return { facts: {}, failures: [], available: false };
+    const facts = {};
+    const failures = [];
+    for (const rel of rels) {
+        try {
+            facts[rel] = readOne(ts, root, rel);
+        }
+        catch (err) {
+            failures.push({ file: rel, reason: err?.name || "Error" });
+        }
+    }
+    return { facts, failures, available: true };
+}

package/out/graph/sync.d.ts

@@ -0,0 +1,66 @@
+export interface SyncOutcome {
+    /** Whether the service now holds a map of this project that matches disk. */
+    current: boolean;
+    /** Whether this company uses the map at all. */
+    enabled: boolean;
+    /** What happened, in one sentence a person can read. */
+    message: string;
+    filesRead: number;
+    filesTotal: number;
+    seconds: number;
+    /** Files present that no reader on this machine could read. */
+    unread: number;
+}
+/** What the service holds for this project, and whether it matches disk. */
+export declare function status(root: string, workspace: string, opts?: {
+    withStamps?: boolean;
+}): Promise<{
+    enabled: boolean;
+    autoRefresh: boolean;
+    fresh: boolean;
+    hasMap: boolean;
+    held: Record<string, unknown> | null;
+    reachable: boolean;
+    stamps: Record<string, string> | null;
+    definedNames: string[];
+}>;
+/**
+ * Bring the map up to date, reading only the files that moved.
+ *
+ * `force` reads everything again, which is what the manual refresh does: a
+ * person asking for a rebuild has usually just had an answer they did not
+ * believe, and telling them nothing needed doing is not an answer.
+ */
+export declare function refresh(root: string, workspace: string, opts?: {
+    force?: boolean;
+}): Promise<SyncOutcome>;
+/** What was read and what was not, in one sentence an answer can carry.
+ *
+ *  Said out loud rather than hidden. A map that quietly covers less than it
+ *  claims is the one failure worth engineering against: the agent believes it
+ *  has seen everything, and writes a confident change that misses a caller. */
+export declare function coverageSentence(unread: {
+    python: number;
+    typescript: number;
+}, total: number): string;
+/** What this machine can read at all. Asked before anything else, so a person
+ *  is told why their map is thin rather than left to guess. */
+export declare function readerReport(): string;
+/**
+ * Put ONE file back into the map, now, and wait for it.
+ *
+ * The fast path, and it exists because the slow one loses a race that matters.
+ * An agent writes a file and asks the map about it in the same step, because
+ * asking for several actions at once is what a well behaved agent does. A
+ * refresh started in the background after the write has not finished by the
+ * time the question runs, so the question reaches a map that is one file
+ * behind, and the agent is told the thing it just created does not exist.
+ *
+ * So this is awaited before the write's result goes back. One round trip: the
+ * file's facts and the project's new fingerprint travel together, and the
+ * service stores, stamps and rejoins in that single call.
+ *
+ * Failure is silent on purpose. A map that could not be updated must never turn
+ * a successful write into a failed one; the next check picks the file up.
+ */
+export declare function pushFile(root: string, workspace: string, rels: string[]): Promise<boolean>;