@mutates/cli 2.1.0

package/src/session/ref-table.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RefTable = void 0;
+const error_codes_1 = require("../proto/error-codes");
+const jsonrpc_1 = require("../proto/jsonrpc");
+/**
+ * Mints opaque `@nN` refs that resolve back to live ts-morph nodes.
+ *
+ * Each file owns its own monotonic id counter (`nextId`) and its own
+ * monotonic `generation` counter. Mutating a file (`invalidateFile`)
+ * bumps the generation; any ref minted at an older generation resolves
+ * as STALE.
+ *
+ * Per-process; refs are not portable across sessions.
+ */
+class RefTable {
+    records = new Map();
+    fileState = new Map();
+    /**
+     * Mint a fresh `@nN` ref for `node`. The id is sequential within
+     * `file` and is reset by {@link resetFile}.
+     */
+    mint(node, file) {
+        const state = this.ensureFile(file);
+        const id = state.nextId++;
+        const ref = `@n${id}`;
+        this.records.set(ref, {
+            weak: new WeakRef(node),
+            file,
+            generation: state.generation,
+            kind: node.getKindName(),
+        });
+        return ref;
+    }
+    /**
+     * Resolve `ref` back to its live node and originating file. Throws
+     * `RpcError(StaleRef)` if the ref is unknown, points into an
+     * invalidated generation, or the underlying node was forgotten.
+     */
+    resolve(ref) {
+        const record = this.records.get(ref);
+        if (!record) {
+            throw new jsonrpc_1.RpcError(error_codes_1.ErrorCode.StaleRef, `ref ${ref} is unknown`, { ref });
+        }
+        const state = this.fileState.get(record.file);
+        if (!state || state.generation !== record.generation) {
+            throw new jsonrpc_1.RpcError(error_codes_1.ErrorCode.StaleRef, `ref ${ref} is stale; re-snapshot ${record.file}`, {
+                ref,
+                file: record.file,
+            });
+        }
+        const node = record.weak.deref();
+        if (!node || node.wasForgotten()) {
+            throw new jsonrpc_1.RpcError(error_codes_1.ErrorCode.StaleRef, `ref ${ref} is stale; re-snapshot ${record.file}`, {
+                ref,
+                file: record.file,
+            });
+        }
+        return { node, file: record.file };
+    }
+    /**
+     * Bump the generation for `file`. Every previously minted ref pointing
+     * into this file will now fail `resolve` with `StaleRef`. Used after
+     * any mutation that may shift node identity.
+     */
+    invalidateFile(file) {
+        const state = this.fileState.get(file);
+        if (state)
+            state.generation += 1;
+        else
+            this.fileState.set(file, { generation: 1, nextId: 1 });
+    }
+    /**
+     * Reset the id counter and generation for `file` so the next mint
+     * starts at `@n1`. Called by the snapshot renderer at the start of a
+     * fresh top-level walk.
+     */
+    resetFile(file) {
+        const state = this.fileState.get(file);
+        if (state) {
+            state.generation += 1;
+            state.nextId = 1;
+        }
+        else {
+            this.fileState.set(file, { generation: 1, nextId: 1 });
+        }
+    }
+    ensureFile(file) {
+        let state = this.fileState.get(file);
+        if (!state) {
+            state = { generation: 1, nextId: 1 };
+            this.fileState.set(file, state);
+        }
+        return state;
+    }
+}
+exports.RefTable = RefTable;
+//# sourceMappingURL=ref-table.js.map

package/src/session/ref-table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-table.js","sourceRoot":"","sources":["../../../../../packages/cli/src/session/ref-table.ts"],"names":[],"mappings":"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"}

package/src/session/session.d.ts

@@ -0,0 +1,51 @@
+import { Project, type SourceFile } from '@mutates/core';
+import { FileStatCache } from './file-stat-cache';
+import { RefTable } from './ref-table';
+export interface SessionOptions {
+    /** Absolute or relative project root. */
+    root: string;
+}
+/**
+ * A live ts-morph project plus the bookkeeping required to mint refs,
+ * detect external file changes, and bridge `@mutates/core`'s
+ * singleton-style `getActiveProject()` API.
+ *
+ * The daemon process owns at most one Session at a time (one project
+ * root per daemon — Req 10.1).
+ */
+export declare class Session {
+    readonly id: string;
+    readonly root: string;
+    readonly openedAt: number;
+    readonly tsconfig: string | null;
+    readonly project: Project;
+    readonly refs: RefTable;
+    readonly stats: FileStatCache;
+    /** Snapshot of each source file's text at load / save time. */
+    private readonly textAtLoad;
+    constructor(opts: SessionOptions);
+    /**
+     * Record the initial fingerprint and text for a source file. Called
+     * during construction and any time the session adopts a new file.
+     */
+    recordLoaded(sourceFile: SourceFile): void;
+    /**
+     * Re-baseline a source file after a successful save: capture the new
+     * text + fingerprint so subsequent dirty checks compare against the
+     * latest "clean" state.
+     */
+    rebaseline(sourceFile: SourceFile, fp: {
+        mtimeMs: number;
+        size: number;
+    }): void;
+    /**
+     * Bridge `@mutates/core`'s singleton: install this session's project
+     * as the active one, run `fn`, restore the previous active project.
+     */
+    withActiveProject<T>(fn: () => T): T;
+    /**
+     * Absolute paths of every source file whose in-memory text differs
+     * from the text captured at load (or last save).
+     */
+    dirtyFiles(): string[];
+}

package/src/session/session.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Session = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const core_1 = require("@mutates/core");
+const file_stat_cache_1 = require("./file-stat-cache");
+const ref_table_1 = require("./ref-table");
+/**
+ * A live ts-morph project plus the bookkeeping required to mint refs,
+ * detect external file changes, and bridge `@mutates/core`'s
+ * singleton-style `getActiveProject()` API.
+ *
+ * The daemon process owns at most one Session at a time (one project
+ * root per daemon — Req 10.1).
+ */
+class Session {
+    id;
+    root;
+    openedAt;
+    tsconfig;
+    project;
+    refs;
+    stats;
+    /** Snapshot of each source file's text at load / save time. */
+    textAtLoad = new Map();
+    constructor(opts) {
+        this.id = (0, node_crypto_1.randomUUID)();
+        this.root = (0, node_path_1.resolve)(opts.root);
+        this.openedAt = Date.now();
+        const tsconfigCandidate = (0, node_path_1.join)(this.root, 'tsconfig.json');
+        this.tsconfig = (0, node_fs_1.existsSync)(tsconfigCandidate) ? tsconfigCandidate : null;
+        this.project = this.tsconfig ? new core_1.Project({ tsConfigFilePath: this.tsconfig }) : new core_1.Project();
+        if (!this.tsconfig) {
+            // No tsconfig — lazily pick up any TS sources under root so a
+            // bare-directory project still has source files to operate on.
+            this.project.addSourceFilesAtPaths((0, node_path_1.join)(this.root, '**/*.{ts,tsx}'));
+        }
+        this.refs = new ref_table_1.RefTable();
+        this.stats = new file_stat_cache_1.FileStatCache();
+        for (const sf of this.project.getSourceFiles()) {
+            this.recordLoaded(sf);
+        }
+    }
+    /**
+     * Record the initial fingerprint and text for a source file. Called
+     * during construction and any time the session adopts a new file.
+     */
+    recordLoaded(sourceFile) {
+        const file = sourceFile.getFilePath();
+        this.textAtLoad.set(file, { text: sourceFile.getFullText() });
+        try {
+            const s = (0, node_fs_1.statSync)(file);
+            this.stats.record(file, { mtimeMs: s.mtimeMs, size: s.size });
+        }
+        catch {
+            // In-memory or otherwise unstattable file — skip the fingerprint;
+            // verify will treat it as stale if save is attempted.
+        }
+    }
+    /**
+     * Re-baseline a source file after a successful save: capture the new
+     * text + fingerprint so subsequent dirty checks compare against the
+     * latest "clean" state.
+     */
+    rebaseline(sourceFile, fp) {
+        const file = sourceFile.getFilePath();
+        this.textAtLoad.set(file, { text: sourceFile.getFullText() });
+        this.stats.record(file, fp);
+    }
+    /**
+     * Bridge `@mutates/core`'s singleton: install this session's project
+     * as the active one, run `fn`, restore the previous active project.
+     */
+    withActiveProject(fn) {
+        const prev = (0, core_1.setActiveProject)(this.project);
+        try {
+            return fn();
+        }
+        finally {
+            if (prev)
+                (0, core_1.setActiveProject)(prev);
+            else
+                (0, core_1.resetActiveProject)();
+        }
+    }
+    /**
+     * Absolute paths of every source file whose in-memory text differs
+     * from the text captured at load (or last save).
+     */
+    dirtyFiles() {
+        const dirty = [];
+        for (const sf of this.project.getSourceFiles()) {
+            const file = sf.getFilePath();
+            const recorded = this.textAtLoad.get(file);
+            if (!recorded) {
+                // Newly added file — treat as dirty so save will pick it up.
+                dirty.push(file);
+                continue;
+            }
+            if (sf.getFullText() !== recorded.text)
+                dirty.push(file);
+        }
+        return dirty;
+    }
+}
+exports.Session = Session;
+//# sourceMappingURL=session.js.map

package/src/session/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../../../packages/cli/src/session/session.ts"],"names":[],"mappings":"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"}

package/src/session/snapshot.d.ts

@@ -0,0 +1,26 @@
+import type { Session } from './session';
+/** A single entry in a {@link SnapshotResult}. */
+export interface SnapshotEntry {
+    ref: string;
+    /** Short lowercase kind (`"class"`, `"function"`, ...) — see {@link KIND_BY_SYNTAX}. */
+    kind: string;
+    name?: string;
+    modifiers?: string[];
+    /** Count of children available via drill, when applicable. */
+    children?: number;
+}
+export interface SnapshotResult {
+    file: string;
+    entries: SnapshotEntry[];
+}
+/**
+ * Render the top-level structure of `file`. Resets the file's ref id
+ * counter so the first declaration is always `@n1`.
+ */
+export declare function snapshotFile(session: Session, file: string): SnapshotResult;
+/**
+ * Drill into `parentRef`'s children. Members of classes/interfaces and
+ * statements of functions are surfaced as fresh entries (sharing the
+ * parent's file generation — drill does NOT reset the file).
+ */
+export declare function snapshotChildren(session: Session, parentRef: string): SnapshotResult;

package/src/session/snapshot.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snapshotFile = snapshotFile;
+exports.snapshotChildren = snapshotChildren;
+const core_1 = require("@mutates/core");
+const error_codes_1 = require("../proto/error-codes");
+const jsonrpc_1 = require("../proto/jsonrpc");
+/**
+ * Map ts-morph `SyntaxKind` numeric values to the short lowercase kind
+ * label exposed in `SnapshotEntry.kind`. Anything not in this table
+ * falls back to the long SyntaxKind name (`node.getKindName()`).
+ */
+const KIND_BY_SYNTAX = {
+    [core_1.SyntaxKind.ImportDeclaration]: 'import',
+    [core_1.SyntaxKind.ClassDeclaration]: 'class',
+    [core_1.SyntaxKind.FunctionDeclaration]: 'function',
+    [core_1.SyntaxKind.VariableStatement]: 'variable',
+    [core_1.SyntaxKind.InterfaceDeclaration]: 'interface',
+    [core_1.SyntaxKind.EnumDeclaration]: 'enum',
+    [core_1.SyntaxKind.TypeAliasDeclaration]: 'type',
+    [core_1.SyntaxKind.ExportDeclaration]: 'export',
+    [core_1.SyntaxKind.ExportAssignment]: 'export',
+    [core_1.SyntaxKind.MethodDeclaration]: 'method',
+    [core_1.SyntaxKind.PropertyDeclaration]: 'property',
+    [core_1.SyntaxKind.GetAccessor]: 'getter',
+    [core_1.SyntaxKind.SetAccessor]: 'setter',
+    [core_1.SyntaxKind.Constructor]: 'constructor',
+    [core_1.SyntaxKind.PropertySignature]: 'property',
+    [core_1.SyntaxKind.MethodSignature]: 'method',
+    [core_1.SyntaxKind.IndexSignature]: 'index',
+    [core_1.SyntaxKind.CallSignature]: 'call',
+    [core_1.SyntaxKind.ConstructSignature]: 'construct',
+};
+/**
+ * Render the top-level structure of `file`. Resets the file's ref id
+ * counter so the first declaration is always `@n1`.
+ */
+function snapshotFile(session, file) {
+    const sourceFile = session.project.getSourceFile(file);
+    if (!sourceFile) {
+        throw new jsonrpc_1.RpcError(error_codes_1.ErrorCode.NotFound, `file not found in session: ${file}`, { file });
+    }
+    const absFile = sourceFile.getFilePath();
+    session.refs.resetFile(absFile);
+    const entries = [];
+    for (const node of collectTopLevel(sourceFile)) {
+        entries.push(buildEntry(session, node, absFile));
+    }
+    return { file: absFile, entries };
+}
+/**
+ * Drill into `parentRef`'s children. Members of classes/interfaces and
+ * statements of functions are surfaced as fresh entries (sharing the
+ * parent's file generation — drill does NOT reset the file).
+ */
+function snapshotChildren(session, parentRef) {
+    const { node, file } = session.refs.resolve(parentRef);
+    const entries = [];
+    for (const child of collectChildren(node)) {
+        entries.push(buildEntry(session, child, file));
+    }
+    return { file, entries };
+}
+function collectTopLevel(sourceFile) {
+    const wanted = new Set([
+        core_1.SyntaxKind.ImportDeclaration,
+        core_1.SyntaxKind.ClassDeclaration,
+        core_1.SyntaxKind.FunctionDeclaration,
+        core_1.SyntaxKind.VariableStatement,
+        core_1.SyntaxKind.InterfaceDeclaration,
+        core_1.SyntaxKind.EnumDeclaration,
+        core_1.SyntaxKind.TypeAliasDeclaration,
+        core_1.SyntaxKind.ExportDeclaration,
+        core_1.SyntaxKind.ExportAssignment,
+    ]);
+    return sourceFile.getStatements().filter((s) => wanted.has(s.getKind()));
+}
+function collectChildren(node) {
+    if (core_1.Node.isClassDeclaration(node)) {
+        return node.getMembers();
+    }
+    if (core_1.Node.isInterfaceDeclaration(node)) {
+        return node.getMembers();
+    }
+    if (core_1.Node.isFunctionDeclaration(node)) {
+        const body = node.getBody();
+        if (body && core_1.Node.isBlock(body)) {
+            return body.getStatements();
+        }
+        return [];
+    }
+    return [];
+}
+function buildEntry(session, node, file) {
+    const ref = session.refs.mint(node, file);
+    const kind = shortKind(node);
+    const entry = { ref, kind };
+    const name = nameOf(node);
+    if (name)
+        entry.name = name;
+    const modifiers = modifiersOf(node);
+    if (modifiers.length > 0)
+        entry.modifiers = modifiers;
+    const children = childCount(node);
+    if (children > 0)
+        entry.children = children;
+    return entry;
+}
+function shortKind(node) {
+    return KIND_BY_SYNTAX[node.getKind()] ?? node.getKindName();
+}
+function nameOf(node) {
+    // `getName` may not exist for every node type; guard at runtime.
+    const candidate = node.getName;
+    if (typeof candidate === 'function') {
+        try {
+            const name = candidate.call(node);
+            if (typeof name === 'string' && name.length > 0)
+                return name;
+        }
+        catch {
+            // Unnamed declaration — fall through.
+        }
+    }
+    if (core_1.Node.isVariableStatement(node)) {
+        const first = node.getDeclarations()[0];
+        return first?.getName();
+    }
+    if (core_1.Node.isImportDeclaration(node)) {
+        return node.getModuleSpecifierValue();
+    }
+    if (core_1.Node.isExportDeclaration(node)) {
+        return node.getModuleSpecifierValue();
+    }
+    return undefined;
+}
+function modifiersOf(node) {
+    const mods = [];
+    const exportable = node;
+    if (typeof exportable.isExported === 'function' && exportable.isExported()) {
+        mods.push('exported');
+    }
+    if (typeof exportable.isDefaultExport === 'function' && exportable.isDefaultExport()) {
+        mods.push('default');
+    }
+    const asyncable = node;
+    if (typeof asyncable.isAsync === 'function' && asyncable.isAsync()) {
+        mods.push('async');
+    }
+    return mods;
+}
+function childCount(node) {
+    if (core_1.Node.isClassDeclaration(node))
+        return node.getMembers().length;
+    if (core_1.Node.isInterfaceDeclaration(node))
+        return node.getMembers().length;
+    if (core_1.Node.isFunctionDeclaration(node)) {
+        const body = node.getBody();
+        if (body && core_1.Node.isBlock(body))
+            return body.getStatements().length;
+    }
+    return 0;
+}
+//# sourceMappingURL=snapshot.js.map

package/src/session/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../../../../packages/cli/src/session/snapshot.ts"],"names":[],"mappings":"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"}