@theoremjs/studio 0.0.0-stage → 0.3.2

package/server/save-new.js

@@ -0,0 +1,514 @@
+/**
+ * What Save writes for a profile or tool the builder added in the studio: a
+ * new file beside the project's others, and the lines in the setup that import
+ * and register it. A scope checks a profile against the tools registered
+ * before it, and an agent tool against the profile it runs, so each line goes
+ * where that order holds.
+ *
+ * @module
+ */
+import { dirname, relative, resolve } from 'node:path';
+import ts from 'typescript';
+import { AGENTS_PACKAGE, agentIdentifier, agentModule, providerModule, toolModule, } from "../source.js";
+import { keySource } from "../tool-schema.js";
+import { calleeName, importExtension, isInside, kernelImportOf, namedValue, setupExport, specifierTo, unwrapped, } from "./project-source.js";
+import { indentAt, indentUnit } from "./save-plan.js";
+/**
+ * The file an id or name is written to: the id itself, with each run of what not every file system
+ * takes made one `-`. None when nothing of it is left.
+ */
+function fileNameOf(of) {
+    const name = of.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[._-]+|-+$/g, '');
+    return name || undefined;
+}
+function registrations(source) {
+    const found = [];
+    const visit = (node) => {
+        if (ts.isExpressionStatement(node)) {
+            const held = ts.isAwaitExpression(node.expression)
+                ? node.expression.expression
+                : node.expression;
+            const call = unwrapped(held);
+            const name = ts.isCallExpression(call) ? calleeName(call) : undefined;
+            if (ts.isCallExpression(call) && (name === 'registerProfile' || name === 'registerTool')) {
+                found.push({ statement: node, call, name });
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return found;
+}
+/** The file whose statements register the project's profiles: the setup, or the first file it reads that does. */
+function registeringFile(project) {
+    const files = [...project.files.values()];
+    return (files.find((source) => registrations(source).some(({ name }) => name === 'registerProfile')) ??
+        files.find((source) => registrations(source).length > 0) ??
+        project.files.get(project.entry));
+}
+/** The id of the profile a `registerProfile` statement registers, when its files write it out. */
+function registeredId(project, source, call) {
+    const [argument] = call.arguments;
+    if (!argument)
+        return undefined;
+    const { origin } = namedValue(project, { node: argument, source });
+    const defined = unwrapped(origin.node);
+    const options = ts.isCallExpression(defined) && defined.arguments[0]
+        ? unwrapped(defined.arguments[0])
+        : defined;
+    for (const [id, targets] of project.profiles) {
+        if (targets.some((target) => target.options === options))
+            return id;
+    }
+    return undefined;
+}
+/** Where a file imports one of the kernel's `names` from, under any name, the first of the project's files that does. */
+function importedFrom(project, names) {
+    for (const [file, source] of project.files) {
+        for (const name of names) {
+            const found = kernelImportOf(source, name);
+            if (found)
+                return { specifier: found.specifier, file };
+        }
+    }
+    return undefined;
+}
+/** A specifier written in `file`, as `to` must write it: a relative one is turned to start from there. */
+function carried(specifier, file, to) {
+    if (!specifier.startsWith('.'))
+        return specifier;
+    const path = relative(dirname(to), resolve(dirname(file), specifier));
+    return path.startsWith('.') ? path : `./${path}`;
+}
+/** The folder most of `files` are in, or `fallback` when there are none. */
+function commonFolder(files, fallback) {
+    const counts = new Map();
+    for (const file of files)
+        counts.set(dirname(file), (counts.get(dirname(file)) ?? 0) + 1);
+    let best = fallback;
+    let most = 0;
+    for (const [folder, count] of counts) {
+        if (count > most)
+            [best, most] = [folder, count];
+    }
+    return best;
+}
+/** `registerLogWatering` for the tool `log_watering`, `registerGemini` for the provider `gemini`: unique among `taken`. */
+function registerName(id, taken) {
+    const words = id.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    const base = `register${words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join('')}`;
+    let name = base;
+    for (let n = 2; taken.has(name); n++)
+        name = `${base}${n}`;
+    taken.add(name);
+    return name;
+}
+/** Every name a file already uses, so a new one does not shadow it. */
+function namesIn(source) {
+    const names = new Set();
+    const visit = (node) => {
+        if (ts.isIdentifier(node))
+            names.add(node.text);
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return names;
+}
+/** The note above each export the studio writes into a setup that has none yet. */
+const SETUP_NOTES = {
+    questions: '/** What each decision profile is asked, by profile id. The studio reads it. */',
+    images: '/** The pictures each decision profile sends, by profile id. The studio reads it. */',
+};
+/** The places in the setup a new line can go, each as the position and the text around the line. */
+class Setup {
+    project;
+    source;
+    taken;
+    edits = [];
+    found;
+    file;
+    /** What this plan imports from the kernel, by its name there, as the name the setup reads. */
+    imported = new Map();
+    /** The lines that go after everything the setup registers, in order. */
+    tail = [];
+    /** What each new decision is asked and sends, as the entries the setup's exports gain. */
+    entries = { questions: [], images: [] };
+    constructor(project, source, taken) {
+        this.project = project;
+        this.source = source;
+        this.taken = taken;
+        this.found = registrations(source);
+        this.file = source.fileName;
+    }
+    /** Whether each registration is a statement of the file or of a function, where a line beside it runs once. */
+    get plain() {
+        return this.found.every(({ statement: { parent } }) => ts.isSourceFile(parent) || (ts.isBlock(parent) && ts.isFunctionLike(parent.parent)));
+    }
+    /** The object the setup's `name` export writes out, when it has the export and writes it so. */
+    held(name) {
+        const value = setupExport(this.source, name)?.initializer;
+        const held = value && unwrapped(value);
+        return held && ts.isObjectLiteralExpression(held) ? held : undefined;
+    }
+    /**
+     * Whether the setup can name what a new decision is asked, or the pictures it sends. The studio
+     * reads them from the module it opens, so that is the file that must hold them: as an object it
+     * writes out, or not yet.
+     */
+    names(name) {
+        if (this.file !== this.project.entry)
+            return false;
+        return this.held(name) !== undefined || !namesIn(this.source).has(name);
+    }
+    /** Names what a new decision profile is asked or sends: `expression`, under the profile's id. */
+    add(name, profile, expression) {
+        this.entries[name].push(`${keySource(profile)}: ${expression}`);
+    }
+    /** The new decisions' entries: more of the `name` export, or the export itself at the end. */
+    place(name) {
+        const added = this.entries[name];
+        const held = this.held(name);
+        if (!held) {
+            const { text } = this.source;
+            const unit = indentUnit(this.source);
+            const entries = added.map((entry) => `${unit}${entry},\n`).join('');
+            const gap = text && !text.endsWith('\n') ? '\n\n' : '\n';
+            return this.insert(text.length, `${gap}${SETUP_NOTES[name]}\nexport const ${name} = {\n${entries}};\n`);
+        }
+        const last = held.properties.at(-1);
+        if (!last)
+            return this.insert(held.getStart(this.source) + 1, ` ${added.join(', ')} `);
+        const indent = indentAt(this.source, last.getStart(this.source));
+        const between = held.getText(this.source).includes('\n') ? `,\n${indent}` : ', ';
+        this.insert(last.end, added.map((entry) => `${between}${entry}`).join(''));
+    }
+    insert(position, text) {
+        this.edits.push({ file: this.file, start: position, end: position, text });
+    }
+    /** The statement that registers `profile`, when the files show which one does. */
+    registers(profile) {
+        return this.found.find(({ name, call }) => name === 'registerProfile' && registeredId(this.project, this.source, call) === profile)?.statement;
+    }
+    after(statement, lines) {
+        const indent = indentAt(this.source, statement.getStart(this.source));
+        this.insert(statement.end, lines.map((line) => `\n${indent}${line}`).join(''));
+    }
+    before(statement, lines) {
+        const start = statement.getStart(this.source);
+        const indent = indentAt(this.source, start);
+        this.insert(start, lines.map((line) => `${line}\n${indent}`).join(''));
+    }
+    /**
+     * The name the setup calls the kernel's `name` by. When the file does not import it yet, it is
+     * added to the import that reads the kernel, or a new one, under another name if the file
+     * already uses `name` for something else.
+     */
+    needs(name, agents) {
+        const known = kernelImportOf(this.source, name)?.local ?? this.imported.get(name);
+        if (known)
+            return known;
+        const local = this.taken.has(name) ? agentIdentifier(`theorem ${name}`, this.taken) : name;
+        if (local === name)
+            this.taken.add(name);
+        this.imported.set(name, local);
+        const binding = local === name ? name : `${name} as ${local}`;
+        for (const statement of this.source.statements) {
+            if (!ts.isImportDeclaration(statement) || !ts.isStringLiteralLike(statement.moduleSpecifier))
+                continue;
+            const bindings = statement.importClause?.namedBindings;
+            if (statement.moduleSpecifier.text !== agents || statement.importClause?.isTypeOnly)
+                continue;
+            const last = bindings && ts.isNamedImports(bindings) ? bindings.elements.at(-1) : undefined;
+            if (last) {
+                this.insert(last.end, `, ${binding}`);
+                return local;
+            }
+        }
+        this.import(`import { ${binding} } from '${agents}';`);
+        return local;
+    }
+    /** After the file's last import, or at its top. */
+    import(line) {
+        const last = this.source.statements.findLast((statement) => ts.isImportDeclaration(statement));
+        if (last)
+            this.insert(last.end, `\n${line}`);
+        else
+            this.insert(0, `${line}\n`);
+    }
+    /** After everything the setup registers. */
+    last(line) {
+        this.tail.push(line);
+    }
+    /** Before the first profile the setup registers, so every profile can allow it. */
+    beforeProfiles(line) {
+        const first = this.found.find(({ name }) => name === 'registerProfile');
+        if (first)
+            this.before(first.statement, [line]);
+        else
+            this.last(line);
+    }
+    /** The last lines: after the last profile, else the last registration, else in the setup's function, else at the end. */
+    placeTail() {
+        const end = this.found.findLast(({ name }) => name === 'registerProfile') ?? this.found.at(-1);
+        if (end)
+            return this.after(end.statement, this.tail);
+        const body = this.source.statements.find((statement) => ts.isFunctionDeclaration(statement) &&
+            statement.body !== undefined &&
+            (ts.getCombinedModifierFlags(statement) & ts.ModifierFlags.Default) !== 0)?.body;
+        const within = body?.statements.at(-1);
+        if (within)
+            return this.after(within, this.tail);
+        if (body) {
+            const unit = indentUnit(this.source);
+            return this.insert(body.getStart(this.source) + 1, `${this.tail.map((line) => `\n${unit}${line}`).join('')}\n`);
+        }
+        const { text } = this.source;
+        this.insert(text.length, `${text && !text.endsWith('\n') ? '\n' : ''}${this.tail.join('\n')}\n`);
+    }
+    /** Every line placed, as edits to the setup. */
+    finish() {
+        if (this.tail.length)
+            this.placeTail();
+        for (const name of ['questions', 'images'])
+            if (this.entries[name].length)
+                this.place(name);
+        return this.edits;
+    }
+}
+const held = (calls, agent) => calls.get(agent) ?? [];
+/** One plan in the making: the files it creates, the setup lines, and what it could not place. */
+class NewPlan {
+    ground;
+    added;
+    plan = { changes: [], edits: [] };
+    setup;
+    taken;
+    claimed = new Set();
+    placed = new Set();
+    extension;
+    zod;
+    folders;
+    isNew;
+    constructor(ground, added) {
+        this.ground = ground;
+        this.added = added;
+        const { project, source, agents } = ground;
+        const folder = (targets) => commonFolder([...targets.values()].flat().map((target) => target.file), dirname(project.entry));
+        this.taken = namesIn(source);
+        this.setup = new Setup(project, source, this.taken);
+        this.extension = importExtension(project, agents.specifier);
+        this.zod = importedFrom(project, ['z']) ?? { specifier: 'zod', file: project.entry };
+        this.folders = {
+            profile: folder(project.profiles),
+            tool: folder(project.tools),
+            provider: folder(project.providers),
+        };
+        this.isNew = new Set(added.profiles);
+    }
+    refuse(kind, of, status, file) {
+        this.plan.changes.push({ kind, of, setting: '', status, file });
+    }
+    nowhere(registration) {
+        this.refuse('tool', registration.name, 'setup', this.ground.project.entry);
+    }
+    /** Nothing can be placed: the setup does not show where it registers. */
+    unplaced() {
+        const { entry } = this.ground.project;
+        for (const id of this.added.profiles)
+            this.refuse('profile', id, 'setup', entry);
+        for (const tool of this.added.tools)
+            this.refuse('tool', tool.name, 'setup', entry);
+        for (const provider of this.added.providers)
+            this.refuse('provider', provider.id, 'setup', entry);
+        return this.plan;
+    }
+    /** The specifiers a new file at `file` imports the kernel and zod by. */
+    from(file) {
+        const { agents } = this.ground;
+        return {
+            agents: carried(agents.specifier, agents.file, file),
+            zod: carried(this.zod.specifier, this.zod.file, file),
+        };
+    }
+    /** The new file for `of`, written and imported. False when it cannot be, with the reason planned. */
+    create(kind, of, text, imports) {
+        const { project, source, exists } = this.ground;
+        const name = fileNameOf(of);
+        const file = resolve(this.folders[kind], `${name}.ts`);
+        const code = name && isInside(project.root, file) ? text(file) : undefined;
+        if (code === undefined) {
+            this.refuse(kind, of, 'setup', project.entry);
+            return false;
+        }
+        if (exists(file) || this.claimed.has(file)) {
+            this.refuse(kind, of, 'taken', file);
+            return false;
+        }
+        this.claimed.add(file);
+        this.plan.edits.push({ file, start: 0, end: 0, text: code });
+        this.setup.import(imports(specifierTo(source.fileName, file, this.extension)));
+        this.plan.changes.push({ kind, of, setting: '', status: 'written', file, line: 1 });
+        return true;
+    }
+    /** A provider's file, and the setup's call of the function in it that registers the provider before every profile. */
+    provider(provider) {
+        const register = registerName(provider.id, this.taken);
+        const made = this.create('provider', provider.id, (file) => providerModule(provider, register, this.from(file).agents), (specifier) => `import { ${register} } from '${specifier}';`);
+        if (made)
+            this.setup.beforeProfiles(`${register}();`);
+    }
+    /** A tool's file, and the setup's call of the function in it that registers the tool. */
+    tool(registration) {
+        const register = registerName(registration.name, this.taken);
+        const made = this.create('tool', registration.name, (file) => toolModule(registration, register, this.from(file)), (specifier) => `import { ${register} } from '${specifier}';`);
+        return made ? [`${register}();`] : [];
+    }
+    /** Where an agent tool goes when an agent the project has allows it: `first` is the earliest of those agents. */
+    call(registration, first, calls) {
+        const { profile } = registration;
+        if (this.isNew.has(profile)) {
+            // An agent the project has calls a new one: the new agent and this tool go right before it.
+            const earlier = calls.hoist.get(profile);
+            calls.hoist.set(profile, earlier && earlier.pos < first.pos ? earlier : first);
+            calls.trail.set(profile, [...held(calls.trail, profile), registration]);
+            return;
+        }
+        const ran = this.setup.registers(profile);
+        if (!ran || ran.end > first.getStart(this.ground.source))
+            return this.nowhere(registration);
+        this.setup.after(ran, this.tool(registration));
+    }
+    /**
+     * Places each new tool. One that calls no agent goes before every profile. An agent tool goes
+     * after the agent it runs and before every agent that allows it, or waits for a new agent's line.
+     */
+    tools() {
+        const calls = { lead: new Map(), trail: new Map(), hoist: new Map() };
+        for (const registration of this.added.tools) {
+            if (registration.type !== 'agent') {
+                for (const line of this.tool(registration))
+                    this.setup.beforeProfiles(line);
+                continue;
+            }
+            const callers = this.added.agents.filter((agent) => agent.customTools.some(({ name }) => name === registration.name));
+            const fresh = callers.find((agent) => this.isNew.has(agent.agentId));
+            const known = callers
+                .filter((agent) => !this.isNew.has(agent.agentId))
+                .map((agent) => this.setup.registers(agent.agentId));
+            const found = known
+                .filter((statement) => statement !== undefined)
+                .toSorted((a, b) => a.pos - b.pos);
+            const [first] = found;
+            // Only new agents allow it, and they are registered last: it goes right before the first of them.
+            if (!known.length && fresh)
+                calls.lead.set(fresh.agentId, [...held(calls.lead, fresh.agentId), registration]);
+            else if (first && found.length === known.length)
+                this.call(registration, first, calls);
+            else
+                this.nowhere(registration);
+        }
+        return calls;
+    }
+    /** A new agent's file and the line that imports it. False when it cannot be written. */
+    profile(agent, name) {
+        // An item rule runs a check the builder's code holds: a file with the rule alone would not load.
+        const [list] = Object.keys(('outputs' in agent.profile && agent.profile.outputs?.validation?.items) || {});
+        if (list !== undefined) {
+            this.plan.changes.push({
+                kind: 'profile',
+                of: agent.agentId,
+                setting: `outputs.validation.items.${list}.check`,
+                status: 'owed',
+            });
+            return false;
+        }
+        // A decision is asked the questions the setup names and sends the pictures it names, so one the setup cannot name them for is not written.
+        if ((agent.questions && !this.setup.names('questions')) ||
+            (agent.images && !this.setup.names('images'))) {
+            this.refuse('profile', agent.agentId, 'setup', this.ground.project.entry);
+            return false;
+        }
+        const { agents } = this.ground;
+        return this.create('profile', agent.agentId, (file) => {
+            const code = agentModule(agent, this.from(file).agents);
+            // The compiled patterns come from a path of the package, which only its own name reaches.
+            return code.includes('compileDetect(') && agents.specifier !== AGENTS_PACKAGE
+                ? undefined
+                : code;
+        }, (specifier) => `import * as ${name} from '${specifier}';`);
+    }
+    /** A new agent's file and its lines in the setup, after any new agent it calls. */
+    agent(agent, calls) {
+        if (this.placed.has(agent.agentId))
+            return;
+        this.placed.add(agent.agentId);
+        const { agents, source } = this.ground;
+        const before = calls.hoist.get(agent.agentId);
+        const waits = held(calls.lead, agent.agentId);
+        for (const registration of waits) {
+            const ran = registration.type === 'agent' && this.isNew.has(registration.profile)
+                ? this.added.agents.find((other) => other.agentId === registration.profile)
+                : undefined;
+            if (ran)
+                this.agent(ran, calls);
+        }
+        const name = agentIdentifier(agent.agentId, this.taken);
+        const made = this.profile(agent, name);
+        const follows = held(calls.trail, agent.agentId);
+        // An agent that goes before one the project has cannot wait for a tool of its own: that tool has no place.
+        if (!made || (before && waits.length)) {
+            for (const registration of [...waits, ...follows])
+                this.nowhere(registration);
+            return;
+        }
+        const kernel = carried(agents.specifier, agents.file, source.fileName);
+        const lines = waits.flatMap((registration) => this.tool(registration));
+        if (agent.questions)
+            this.setup.add('questions', agent.agentId, `${name}.questions`);
+        if (agent.images)
+            this.setup.add('images', agent.agentId, `${name}.images`);
+        if (agent.structured) {
+            const structured = this.setup.needs('registerStructured', kernel);
+            lines.push(`${structured}(${name}.structured.id, ${name}.structured.spec);`);
+        }
+        const register = this.setup.needs('registerProfile', kernel);
+        lines.push(`${register}(${name}.profile);`, ...follows.flatMap((registration) => this.tool(registration)));
+        if (before)
+            this.setup.before(before, lines);
+        else
+            for (const line of lines)
+                this.setup.last(line);
+    }
+    build() {
+        if (!this.setup.plain)
+            return this.unplaced();
+        for (const provider of this.added.providers)
+            this.provider(provider);
+        const calls = this.tools();
+        for (const agent of this.added.agents) {
+            if (this.isNew.has(agent.agentId))
+                this.agent(agent, calls);
+        }
+        this.plan.edits.push(...this.setup.finish());
+        return this.plan;
+    }
+}
+/**
+ * Plans the files and setup lines for what the studio added. `exists` says whether a path is
+ * taken. A change it cannot write says why, and nothing is planned for it.
+ */
+export function planNew(project, added, exists) {
+    if (!added.profiles.length && !added.tools.length && !added.providers.length)
+        return { changes: [], edits: [] };
+    const source = registeringFile(project);
+    const agents = importedFrom(project, ['defineProfile', 'registerProfile', 'registerTool']);
+    if (!source || !agents) {
+        const changes = [
+            ...added.profiles.map((of) => ({ kind: 'profile', of })),
+            ...added.tools.map(({ name }) => ({ kind: 'tool', of: name })),
+            ...added.providers.map(({ id }) => ({ kind: 'provider', of: id })),
+        ].map((change) => ({ ...change, setting: '', status: 'setup', file: project.entry }));
+        return { changes, edits: [] };
+    }
+    return new NewPlan({ project, source, agents, exists }, added).build();
+}

package/server/save-plan.d.ts

@@ -0,0 +1,46 @@
+/**
+ * What Save writes: each changed value of a profile or a tool, found in the
+ * builder's file and rewritten there. A value written in the call is changed in
+ * place. A value from a constant is changed where the constant is set, when
+ * every profile and tool that reads the constant makes the same change, and the
+ * plan says when other code reads the constant too. A value from a constant that
+ * someone leaves as it was, or from code, is not written; the plan says where it
+ * is set and who shares it. A tool's schema is changed in the Zod that writes it,
+ * one part at a time (`zod-edit.ts`).
+ *
+ * @module
+ */
+import ts from 'typescript';
+import { type ProjectSource, type SubjectKind } from './project-source.ts';
+import type { DiffHunk, SaveChange } from './save-wire.ts';
+/** A profile, tool, or provider that changed: its values before and after, as the studio holds them. */
+export interface SaveSubject {
+    kind: SubjectKind;
+    of: string;
+    before: unknown;
+    after: unknown;
+}
+/** One replacement in a file's text. An insertion has `start === end`. */
+export interface SourceEdit {
+    file: string;
+    start: number;
+    end: number;
+    text: string;
+}
+export interface SavePlan {
+    changes: SaveChange[];
+    edits: SourceEdit[];
+}
+export declare const NOT_PLAIN: unique symbol;
+/** The value an expression writes out in full, or `NOT_PLAIN` when it names or computes anything. */
+export declare function plain(expression: ts.Expression): unknown;
+/** The whitespace a line starts with. */
+export declare function indentAt(source: ts.SourceFile, position: number): string;
+/** One level of a file's indentation: a tab, or its narrowest run of spaces. */
+export declare function indentUnit(source: ts.SourceFile): string;
+/** Finds each subject's call in the project and plans its changes. */
+export declare function planSave(project: ProjectSource, subjects: readonly SaveSubject[]): SavePlan;
+/** `text` with the edits made. Throws when two edits touch the same characters. */
+export declare function applyEdits(text: string, edits: readonly SourceEdit[]): string;
+/** The changed lines of one file, from the edits made to it. */
+export declare function diffHunks(text: string, edits: readonly SourceEdit[]): DiffHunk[];