@theoremjs/studio 0.0.0-stage → 0.3.2

package/server/project-source.js

@@ -0,0 +1,1042 @@
+/**
+ * The project's own source, read as syntax: where each `defineProfile` and
+ * `registerTool` call is written, so Save can change a value in the builder's
+ * file. It starts at the setup module and follows the project's relative
+ * imports. Nothing is loaded or run.
+ *
+ * @module
+ */
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import ts from 'typescript';
+import { definitionOfFactory } from "../providers.js";
+/** Where the project's files write each thing of `kind`. */
+export function definedAs(project, kind) {
+    if (kind === 'profile')
+        return project.profiles;
+    return kind === 'tool' ? project.tools : project.providers;
+}
+const EXTENSIONS = ['', '.ts', '.tsx', '.mts', '.js', '.mjs', '/index.ts', '/mod.ts'];
+/** Whether `path` is `root` or inside it. */
+export function isInside(root, path) {
+    const from = relative(root, path);
+    return from === '' || (!from.startsWith('..') && !isAbsolute(from));
+}
+/** The file a relative import names, or undefined when it is not one of the project's. */
+function importedFile(from, specifier, exists, root) {
+    if (!specifier.startsWith('./') && !specifier.startsWith('../'))
+        return undefined;
+    const base = resolve(dirname(from), specifier);
+    // `./tools.js` in a TypeScript project names `./tools.ts`.
+    const bases = /\.[cm]?js$/.test(base) ? [base, base.replace(/\.([cm]?)js$/, '.$1ts')] : [base];
+    for (const candidate of bases) {
+        for (const extension of EXTENSIONS) {
+            const path = candidate + extension;
+            if (!isInside(root, path) || path.includes('/node_modules/'))
+                continue;
+            if (exists(path))
+                return path;
+        }
+    }
+    return undefined;
+}
+/** The setup module's `export const <name>`, when it writes one. */
+export function setupExport(source, name) {
+    for (const statement of source.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        if (!statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword))
+            continue;
+        const found = statement.declarationList.declarations.find((declaration) => ts.isIdentifier(declaration.name) && declaration.name.text === name);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/** `expression` without the wrappers that do not change its value. */
+export function unwrapped(expression) {
+    let node = expression;
+    while (ts.isParenthesizedExpression(node) ||
+        ts.isAsExpression(node) ||
+        ts.isSatisfiesExpression(node) ||
+        ts.isNonNullExpression(node))
+        node = node.expression;
+    return node;
+}
+/** The name a property is written under, when it is a plain one. */
+export function propertyName(property) {
+    const { name } = property;
+    if (!name)
+        return undefined;
+    if (ts.isIdentifier(name) || ts.isStringLiteralLike(name) || ts.isNumericLiteral(name))
+        return name.text;
+    return undefined;
+}
+/** The module specifier of each import, export-from, and literal `import()` in a file. */
+function specifiers(source) {
+    const found = [];
+    const visit = (node) => {
+        if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier) {
+            if (ts.isStringLiteralLike(node.moduleSpecifier))
+                found.push(node.moduleSpecifier.text);
+        }
+        else if (ts.isCallExpression(node) &&
+            node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+            node.arguments[0] &&
+            ts.isStringLiteralLike(node.arguments[0]))
+            found.push(node.arguments[0].text);
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return found;
+}
+/** The kernel's package, however a specifier names it: bare, `npm:`, or `jsr:`, with a version, or a path in it. */
+const KERNEL_PACKAGE = /^(?:npm:|jsr:)?@theoremjs\/agents(?:@[^/]*)?(?:\/|$)/;
+/** Whether an import from `specifier` may bring in the kernel: its package, or a path, which may lead to it. Another package does not. */
+function mayBeKernel(specifier) {
+    return KERNEL_PACKAGE.test(specifier) || /^(?:\.|\/|file:)/.test(specifier);
+}
+const bound = new WeakMap();
+function bindingsOf(source) {
+    const held = bound.get(source);
+    if (held)
+        return held;
+    const names = new Map();
+    for (const statement of source.statements) {
+        if (ts.isImportDeclaration(statement) && ts.isStringLiteralLike(statement.moduleSpecifier)) {
+            const module = statement.moduleSpecifier.text;
+            const clause = statement.importClause;
+            if (clause?.name)
+                names.set(clause.name.text, { module, imported: undefined });
+            const bindings = clause?.namedBindings;
+            if (bindings && ts.isNamespaceImport(bindings))
+                names.set(bindings.name.text, { module, imported: '*' });
+            else if (bindings) {
+                for (const element of bindings.elements) {
+                    names.set(element.name.text, {
+                        module,
+                        imported: (element.propertyName ?? element.name).text,
+                    });
+                }
+            }
+        }
+        else if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) &&
+            statement.name) {
+            names.set(statement.name.text, 'own');
+        }
+        else if (ts.isVariableStatement(statement)) {
+            for (const { name } of statement.declarationList.declarations)
+                if (ts.isIdentifier(name))
+                    names.set(name.text, 'own');
+        }
+    }
+    bound.set(source, names);
+    return names;
+}
+/**
+ * The kernel function a call calls, by what its name is bound to: `defineProfile(...)`, `reg(...)`
+ * after `import { registerProfile as reg }`, `theorem.defineProfile(...)` after `import * as theorem`.
+ * A name another package exports, or the file declares itself, is not the kernel's.
+ */
+export function calleeName(call) {
+    const callee = call.expression;
+    const names = bindingsOf(call.getSourceFile());
+    if (ts.isIdentifier(callee)) {
+        const binding = names.get(callee.text);
+        if (binding === undefined)
+            return callee.text;
+        if (binding === 'own' ||
+            !mayBeKernel(binding.module) ||
+            !binding.imported ||
+            binding.imported === '*')
+            return undefined;
+        return binding.imported;
+    }
+    if (ts.isPropertyAccessExpression(callee)) {
+        const binding = ts.isIdentifier(callee.expression)
+            ? names.get(callee.expression.text)
+            : undefined;
+        if (binding && binding !== 'own' && !mayBeKernel(binding.module))
+            return undefined;
+        return callee.name.text;
+    }
+    return undefined;
+}
+/** Whether `at` is a name its file imports from the kernel by name, such as a protocol: Save rewrites it in place. */
+export function isKernelName(at) {
+    const node = unwrapped(at.node);
+    if (!ts.isIdentifier(node) || at.env?.bound.has(node.text))
+        return false;
+    const binding = bindingsOf(at.source).get(node.text);
+    return (binding !== undefined &&
+        binding !== 'own' &&
+        binding.imported !== '*' &&
+        binding.imported !== undefined &&
+        mayBeKernel(binding.module));
+}
+/** Where `source` imports the kernel's `name` from, and the name it is called by there. */
+export function kernelImportOf(source, name) {
+    for (const [local, binding] of bindingsOf(source)) {
+        if (binding !== 'own' && binding.imported === name && mayBeKernel(binding.module))
+            return { specifier: binding.module, local };
+    }
+    return undefined;
+}
+/** The calls a profile's options are written in: where it is defined, or where it is registered without being defined first. */
+const PROFILE_CALLS = new Set(['defineProfile', 'registerProfile']);
+/** Whether a call is one a profile's options may be written straight into. */
+function takesProfile(call) {
+    return PROFILE_CALLS.has(calleeName(call) ?? '');
+}
+/** How far a name is followed, through constants and calls. */
+const MAX_DEPTH = 8;
+/** A value the files leave out: a key an object does not write, a parameter a call gives no argument. */
+const MISSING = Symbol('missing');
+/** What a function returns, when returning it is all the function does. */
+function returned(fn) {
+    const { body } = fn;
+    const plainCall = !fn.asteriskToken &&
+        !fn.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword);
+    if (!body || !plainCall)
+        return undefined;
+    if (!ts.isBlock(body))
+        return body;
+    const [only] = body.statements;
+    return body.statements.length === 1 && only && ts.isReturnStatement(only)
+        ? only.expression
+        : undefined;
+}
+/** `fn` as a function the studio follows: plain parameters, and one value returned. */
+function followable(name, source, fn) {
+    const value = returned(fn);
+    if (!value ||
+        fn.parameters.some((parameter) => !ts.isIdentifier(parameter.name) || parameter.dotDotDotToken)) {
+        return undefined;
+    }
+    return {
+        name,
+        source,
+        parameters: fn.parameters.map((parameter) => parameter.name.text),
+        defaults: fn.parameters.map((parameter) => parameter.initializer),
+        value,
+    };
+}
+/** Each top-level `const` of a file that is set to something, by its name. */
+function constsOf(source) {
+    return source.statements
+        .filter((statement) => ts.isVariableStatement(statement) &&
+        Boolean(statement.declarationList.flags & ts.NodeFlags.Const))
+        .flatMap((statement) => [...statement.declarationList.declarations])
+        .flatMap(({ name, initializer }) => initializer && ts.isIdentifier(name) ? [{ name: name.text, initializer }] : []);
+}
+const isFunctionValue = (node) => ts.isArrowFunction(node) || ts.isFunctionExpression(node);
+/** Each top-level function of a file: a declaration, or a `const` set to one. */
+function functionsOf(source) {
+    const declared = source.statements
+        .filter((statement) => ts.isFunctionDeclaration(statement))
+        .flatMap((fn) => (fn.name ? [{ name: fn.name.text, fn }] : []));
+    const held = constsOf(source).flatMap(({ name, initializer }) => {
+        const value = unwrapped(initializer);
+        return isFunctionValue(value) ? [{ name, fn: value }] : [];
+    });
+    return [...declared, ...held];
+}
+/** The function a name in `source` calls: one declared there, or one a relative import brings in. */
+function functionOf(project, source, name) {
+    const declared = (file, called) => {
+        const held = functionsOf(file).filter((each) => each.name === called);
+        return held.length === 1 && held[0] ? followable(called, file, held[0].fn) : undefined;
+    };
+    const here = declared(source, name);
+    if (here)
+        return here;
+    const from = importOf(source, name);
+    const origin = from && sourceOf(project, source, from.specifier);
+    return origin && from ? declared(origin, from.name) : undefined;
+}
+/** What a call of a project function returns, with its parameters standing for the call's arguments. */
+function calledValue(project, call, at) {
+    const callee = call.expression;
+    if (!ts.isIdentifier(callee) || at.env?.bound.has(callee.text))
+        return undefined;
+    const depth = (at.env?.depth ?? 0) + 1;
+    const fn = depth > MAX_DEPTH ? undefined : functionOf(project, at.source, callee.text);
+    if (!fn || call.arguments.some(ts.isSpreadElement))
+        return undefined;
+    const bound = new Map();
+    fn.parameters.forEach((name, index) => {
+        const argument = call.arguments[index];
+        const preset = fn.defaults[index];
+        if (argument)
+            bound.set(name, { node: argument, source: at.source, env: at.env });
+        else
+            bound.set(name, preset ? { node: preset, source: fn.source } : undefined);
+    });
+    return { node: fn.value, source: fn.source, env: { bound, depth } };
+}
+/** The calls a registered provider makes a model with. */
+const MODEL_CALLS = new Set(['model', 'decisionModel']);
+/**
+ * A registered provider's `model(protocol, apiId, settings)` or `decisionModel(…)`: it returns the
+ * settings with the protocol, the provider's id and the API id.
+ */
+function isModelCall(node) {
+    return (ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        MODEL_CALLS.has(node.expression.name.text) &&
+        (node.arguments.length === 2 || node.arguments.length === 3) &&
+        !node.arguments.some(ts.isSpreadElement));
+}
+/** What a call stands for, when the studio reads through it: `defineProfile`'s options, a project function's value. */
+function seenThrough(project, call, at) {
+    const [first] = call.arguments;
+    if (calleeName(call) === 'defineProfile' &&
+        call.arguments.length === 1 &&
+        first &&
+        !ts.isSpreadElement(first)) {
+        return { node: first, source: at.source, env: at.env };
+    }
+    return calledValue(project, call, at);
+}
+/** The name a property is written under: a plain one, or a computed one that names a constant's text. */
+function keyOf(project, property, at, depth) {
+    const plainName = propertyName(property);
+    if (plainName !== undefined || !property.name || !ts.isComputedPropertyName(property.name))
+        return plainName;
+    const held = step(project, { node: property.name.expression, source: at.source, env: at.env }, depth + 1);
+    if (held === MISSING)
+        return undefined;
+    return ts.isStringLiteralLike(held.node) || ts.isNumericLiteral(held.node)
+        ? held.node.text
+        : undefined;
+}
+/** Where a provider's id is written: the `id` of the `registerProvider` call the name stands for. */
+function providerId(project, at, depth) {
+    const held = step(project, at, depth + 1);
+    if (held === MISSING ||
+        !ts.isCallExpression(held.node) ||
+        calleeName(held.node) !== 'registerProvider')
+        return undefined;
+    const [, options] = held.node.arguments;
+    const id = options && ts.isObjectLiteralExpression(options)
+        ? options.properties.findLast((property) => propertyName(property) === 'id')
+        : undefined;
+    return id && ts.isPropertyAssignment(id)
+        ? { node: id.initializer, source: held.source, env: held.env }
+        : undefined;
+}
+/**
+ * The object an expression writes out: an object literal, or a provider's `model()` call. Each
+ * spread is followed to the object it names. Undefined for anything else.
+ */
+export function shapeOf(project, at, depth = 0) {
+    const node = unwrapped(at.node);
+    if (depth > MAX_DEPTH || !(ts.isObjectLiteralExpression(node) || isModelCall(node)))
+        return undefined;
+    const shape = { entries: new Map() };
+    const inside = (inner) => ({
+        node: inner,
+        source: at.source,
+        env: at.env,
+    });
+    const put = (entry) => {
+        shape.entries.delete(entry.key);
+        shape.entries.set(entry.key, entry);
+        shape.open?.after.add(entry.key);
+    };
+    const spread = (from, written) => {
+        const inner = step(project, inside(from), depth + 1);
+        // A spread of nothing adds nothing.
+        if (inner === MISSING)
+            return;
+        const held = shapeOf(project, inner, depth + 1);
+        if (!held) {
+            shape.open = { node: written, source: at.source, after: new Set() };
+            return;
+        }
+        const sure = held.open?.after;
+        if (held.open)
+            shape.open = { ...held.open, after: new Set() };
+        for (const entry of held.entries.values()) {
+            shape.entries.delete(entry.key);
+            shape.entries.set(entry.key, entry);
+            if (!sure || sure.has(entry.key))
+                shape.open?.after.add(entry.key);
+        }
+    };
+    if (ts.isObjectLiteralExpression(node)) {
+        shape.own = { node, source: at.source };
+        for (const property of node.properties) {
+            if (ts.isSpreadAssignment(property)) {
+                spread(property.expression, property);
+                continue;
+            }
+            const key = keyOf(project, property, at, depth);
+            if (key === undefined) {
+                shape.open = { node: property, source: at.source, after: new Set() };
+                continue;
+            }
+            const value = ts.isPropertyAssignment(property)
+                ? property.initializer
+                : ts.isShorthandPropertyAssignment(property)
+                    ? property.name
+                    : undefined;
+            put({ key, property, source: at.source, ...(value ? { value: inside(value) } : {}) });
+        }
+        return shape;
+    }
+    const [protocol, apiId, settings] = node.arguments;
+    if (settings) {
+        spread(settings, settings);
+        const direct = unwrapped(settings);
+        if (ts.isObjectLiteralExpression(direct))
+            shape.own = { node: direct, source: at.source };
+    }
+    const receiver = inside(node.expression.expression);
+    const provider = providerId(project, receiver, depth);
+    put({ key: 'provider', source: at.source, receiver, ...(provider ? { value: provider } : {}) });
+    if (protocol)
+        put({ key: 'protocol', source: at.source, value: inside(protocol) });
+    if (apiId)
+        put({ key: 'apiId', source: at.source, value: inside(apiId) });
+    return shape;
+}
+/** Whether an expression writes a value that is surely there: not `undefined`, not `null`. */
+function isWritten(node) {
+    return (ts.isStringLiteralLike(node) ||
+        ts.isNumericLiteral(node) ||
+        ts.isObjectLiteralExpression(node) ||
+        ts.isArrayLiteralExpression(node) ||
+        node.kind === ts.SyntaxKind.TrueKeyword ||
+        node.kind === ts.SyntaxKind.FalseKeyword ||
+        isModelCall(node));
+}
+/** A key read off an object: what the object holds there. */
+function stepAccess(project, node, here, depth) {
+    const owner = step(project, { ...here, node: node.expression }, depth + 1);
+    const shape = owner === MISSING ? undefined : shapeOf(project, owner, depth + 1);
+    if (!shape)
+        return here;
+    const held = shape.entries.get(node.name.text);
+    if (shape.open && !(held && shape.open.after.has(held.key)))
+        return here;
+    if (!held)
+        return MISSING;
+    return held.value ? step(project, held.value, depth + 1) : here;
+}
+/** A name: the argument a followed function was called with, or the `const` it names. */
+function stepName(project, node, here, depth) {
+    if (here.env?.bound.has(node.text)) {
+        const argument = here.env.bound.get(node.text);
+        return argument ? step(project, argument, depth + 1) : MISSING;
+    }
+    const binding = bindingOf(project, here.source, node.text);
+    return binding
+        ? step(project, { node: binding.initializer, source: binding.source }, depth + 1)
+        : here;
+}
+/** Whether a followed condition is written out as true or false. Undefined when the files do not say. */
+function truthOf(when) {
+    if (when === MISSING)
+        return false;
+    if (when.node.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    return when.node.kind === ts.SyntaxKind.FalseKeyword ? false : undefined;
+}
+/** A condition the files write out as true or false picks its side. */
+function stepCondition(project, node, here, depth) {
+    const truth = truthOf(step(project, { ...here, node: node.condition }, depth + 1));
+    if (truth === undefined)
+        return here;
+    return step(project, { ...here, node: truth ? node.whenTrue : node.whenFalse }, depth + 1);
+}
+/** `left ?? right`: the right when the left is not there, the left when it is written out. */
+function stepFallback(project, node, here, depth) {
+    const left = step(project, { ...here, node: node.left }, depth + 1);
+    if (left === MISSING)
+        return step(project, { ...here, node: node.right }, depth + 1);
+    return isWritten(left.node) ? left : here;
+}
+/** A copy of one list is that list. */
+function stepCopy(project, node, here, depth) {
+    const [only] = node.elements;
+    if (node.elements.length !== 1 || !only || !ts.isSpreadElement(only))
+        return here;
+    const copied = step(project, { ...here, node: only.expression }, depth + 1);
+    return copied !== MISSING && ts.isArrayLiteralExpression(copied.node) ? copied : here;
+}
+/** One expression followed as far as the files say what it is, or `MISSING` when they say it is not there. */
+function step(project, at, depth) {
+    const node = unwrapped(at.node);
+    const here = { ...at, node };
+    if (depth > MAX_DEPTH)
+        return here;
+    if (ts.isPropertyAccessExpression(node))
+        return stepAccess(project, node, here, depth);
+    if (ts.isIdentifier(node))
+        return stepName(project, node, here, depth);
+    if (ts.isCallExpression(node)) {
+        const seen = seenThrough(project, node, at);
+        return seen ? step(project, seen, depth + 1) : here;
+    }
+    if (ts.isConditionalExpression(node))
+        return stepCondition(project, node, here, depth);
+    if (ts.isBinaryExpression(node) &&
+        node.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken) {
+        return stepFallback(project, node, here, depth);
+    }
+    return ts.isArrayLiteralExpression(node) ? stepCopy(project, node, here, depth) : here;
+}
+/**
+ * Follows an expression to what it stands for: a `const` in the same file or one a relative
+ * import brings in, a key of an object, an argument of a call, what a project function returns.
+ * Anything else (a `let`, a package's export, code that computes) stays as it is.
+ */
+export function followed(project, at) {
+    const held = step(project, at, 0);
+    return held === MISSING ? { ...at, node: unwrapped(at.node) } : held;
+}
+/** The file of the project a relative import in `source` names. */
+export function sourceOf(project, source, specifier) {
+    const file = importedFile(source.fileName, specifier, (path) => project.files.has(path), project.root);
+    return file ? project.files.get(file) : undefined;
+}
+/** The constant a name in `source` stands for: one declared there, or one a relative import brings in. */
+function bindingOf(project, source, name) {
+    const declared = constant(source, name);
+    if (declared)
+        return { name, source, initializer: declared };
+    const from = importOf(source, name);
+    const origin = from && sourceOf(project, source, from.specifier);
+    const exported = origin && from && constant(origin, from.name);
+    return origin && from && exported
+        ? { name: from.name, source: origin, initializer: exported }
+        : undefined;
+}
+/**
+ * The constant whose value holds `at`: the top-level `const` it is written inside. A function that
+ * only returns a value holds what it returns, as a constant does.
+ */
+export function holderOf(at) {
+    const holds = (value) => value.pos <= at.node.pos && at.node.end <= value.end;
+    for (const { name, fn } of functionsOf(at.source)) {
+        if (!holds(fn))
+            continue;
+        const value = returned(fn);
+        return value && holds(value)
+            ? { name, source: at.source, initializer: value, returns: true }
+            : undefined;
+    }
+    const held = constsOf(at.source).find(({ initializer }) => holds(initializer));
+    return held && { ...held, source: at.source };
+}
+/**
+ * Where a name's value is written, and the constant that holds it. No holder when the name could
+ * not be followed to a constant: an argument, a call, a module the project does not own.
+ */
+export function namedValue(project, at) {
+    const origin = followed(project, at);
+    return {
+        origin,
+        holder: origin.node === unwrapped(at.node) && origin.source === at.source
+            ? undefined
+            : holderOf(origin),
+    };
+}
+/** Whether an identifier reads a value: not a declaration's name, a property's name, an import, or a type. */
+export function isRead(node) {
+    const { parent } = node;
+    if (ts.isShorthandPropertyAssignment(parent))
+        return true;
+    if (ts.isPropertyAccessExpression(parent))
+        return parent.expression === node;
+    if (ts.isImportSpecifier(parent) || ts.isExportSpecifier(parent) || ts.isTypeNode(parent))
+        return false;
+    return parent.name !== node;
+}
+/** Each import in `source` that names what it brings in, with where it brings it from. */
+function* namedImports(source) {
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteralLike(statement.moduleSpecifier))
+            continue;
+        const bindings = statement.importClause?.namedBindings;
+        if (bindings && ts.isNamedImports(bindings))
+            yield { specifier: statement.moduleSpecifier.text, elements: bindings.elements };
+    }
+}
+/** The name `source` knows a constant by: its own, or the one an import gives it. */
+function localName(project, source, binding) {
+    if (source === binding.source)
+        return binding.name;
+    for (const { specifier, elements } of namedImports(source)) {
+        const element = elements.find((each) => (each.propertyName ?? each.name).text === binding.name);
+        if (element && sourceOf(project, source, specifier) === binding.source)
+            return element.name.text;
+    }
+    return undefined;
+}
+/** Each place the project's code reads a constant. */
+function readsOf(project, binding) {
+    const reads = [];
+    for (const source of project.files.values()) {
+        const name = localName(project, source, binding);
+        if (name === undefined)
+            continue;
+        const visit = (node) => {
+            if (ts.isIdentifier(node) && node.text === name && isRead(node))
+                reads.push({ node, source });
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    return reads;
+}
+/**
+ * The methods of a schema that return the schema again, changed: `LIMITS.optional()` and
+ * `RESULT.extend({ … })` still write `LIMITS` and `RESULT` out.
+ */
+const SCHEMA_METHODS = new Set([
+    'describe',
+    'meta',
+    'optional',
+    'nullable',
+    'nullish',
+    'default',
+    'array',
+    'extend',
+    'partial',
+    'required',
+    'pick',
+    'omit',
+    'strict',
+    'passthrough',
+    'loose',
+    'catchall',
+    'refine',
+    'superRefine',
+    'check',
+    'brand',
+    'readonly',
+    'or',
+    'and',
+]);
+/** Whether a call writes `child` out: an argument of a call the studio reads through, the project function called, or a schema a method is called on. */
+function passes(project, call, child) {
+    const callee = call.expression;
+    const ours = ts.isIdentifier(callee) && functionOf(project, call.getSourceFile(), callee.text) !== undefined;
+    if (child === callee)
+        return ours || (ts.isPropertyAccessExpression(callee) && SCHEMA_METHODS.has(callee.name.text));
+    if (!call.arguments.some((argument) => argument === child))
+        return false;
+    return ours || isModelCall(call) || takesProfile(call);
+}
+/** Whether `node` is part of the value `value` writes out, not something a function or a call inside it reads. */
+function isWrittenIn(project, node, value) {
+    let child = node;
+    for (let at = node.parent; at !== value.parent; child = at, at = at.parent) {
+        if (ts.isCallExpression(at)) {
+            if (!passes(project, at, child))
+                return false;
+            continue;
+        }
+        const data = ts.isObjectLiteralExpression(at) ||
+            ts.isArrayLiteralExpression(at) ||
+            ts.isPropertyAssignment(at) ||
+            ts.isShorthandPropertyAssignment(at) ||
+            ts.isSpreadAssignment(at) ||
+            ts.isSpreadElement(at) ||
+            ts.isPropertyAccessExpression(at) ||
+            ts.isParenthesizedExpression(at) ||
+            ts.isAsExpression(at) ||
+            ts.isSatisfiesExpression(at) ||
+            ts.isNonNullExpression(at);
+        if (!data)
+            return false;
+    }
+    return true;
+}
+/**
+ * The constant the provider `id` is defined under: the top-level `const` its one definition is
+ * set to. None for a provider written straight into its registration, or written twice.
+ */
+export function providerNamed(project, id) {
+    const targets = project.providers.get(id) ?? [];
+    const [target] = targets;
+    if (!target || targets.length > 1)
+        return undefined;
+    const call = target.options.parent;
+    const declaration = ts.isCallExpression(call) ? unwrappedParent(call) : undefined;
+    if (!declaration || !ts.isVariableDeclaration(declaration) || !ts.isIdentifier(declaration.name))
+        return undefined;
+    const statement = declaration.parent.parent;
+    const top = ts.isVariableStatement(statement) &&
+        ts.isSourceFile(statement.parent) &&
+        (declaration.parent.flags & ts.NodeFlags.Const) !== 0;
+    if (!top)
+        return undefined;
+    const exported = statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+    return { name: declaration.name.text, source: target.source, exported };
+}
+/** What holds an expression once the wrappers that leave its value alone are passed: `as`, `satisfies`, brackets. */
+function unwrappedParent(node) {
+    const { parent } = node;
+    const wraps = ts.isParenthesizedExpression(parent) ||
+        ts.isAsExpression(parent) ||
+        ts.isSatisfiesExpression(parent) ||
+        ts.isNonNullExpression(parent);
+    return wraps ? unwrappedParent(parent) : parent;
+}
+/** Whether the top level of `source` already gives `name` a meaning: a declaration, or an import. */
+export function declares(source, name) {
+    return source.statements.some((statement) => {
+        if (ts.isVariableStatement(statement)) {
+            return statement.declarationList.declarations.some((held) => ts.isIdentifier(held.name) && held.name.text === name);
+        }
+        if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement))
+            return statement.name?.text === name;
+        if (!ts.isImportDeclaration(statement))
+            return false;
+        const clause = statement.importClause;
+        const bindings = clause?.namedBindings;
+        if (clause?.name?.text === name)
+            return true;
+        if (bindings && ts.isNamespaceImport(bindings))
+            return bindings.name.text === name;
+        return bindings?.elements.some((element) => element.name.text === name) ?? false;
+    });
+}
+/** The extension the project's relative imports end in: `.ts`, `.js`, or none. `fallback` is read when it has none. */
+export function importExtension(project, fallback) {
+    const relatives = [...project.files.values()].flatMap((source) => source.statements.flatMap((statement) => ts.isImportDeclaration(statement) &&
+        ts.isStringLiteralLike(statement.moduleSpecifier) &&
+        statement.moduleSpecifier.text.startsWith('.')
+        ? [statement.moduleSpecifier.text]
+        : []));
+    const model = relatives[0] ?? fallback;
+    return /\.[cm]?[jt]sx?$/.exec(model)?.[0].replace('tsx', 'ts') ?? '';
+}
+/** How `from` imports `to`: a relative path, ending as the project's imports do. */
+export function specifierTo(from, to, extension) {
+    const path = relative(dirname(from), to).replace(/\.ts$/, extension);
+    return path.startsWith('.') ? path : `./${path}`;
+}
+/**
+ * Whether a value other code reads is a name that code knows something by: a profile's id, or the
+ * id a provider is defined with. The studio does not rename those.
+ */
+export function isHeldId(kind, path, at) {
+    if (kind !== 'tool' && path.length === 1 && path[0] === 'id')
+        return true;
+    const property = at.node.parent;
+    const call = property.parent.parent;
+    return (ts.isPropertyAssignment(property) &&
+        propertyName(property) === 'id' &&
+        ts.isCallExpression(call) &&
+        calleeName(call) === 'registerProvider');
+}
+/** Whether `at` is written inside a call's options. */
+export function isInTarget(target, at) {
+    return (target.source === at.source &&
+        target.options.pos <= at.node.pos &&
+        at.node.end <= target.options.end);
+}
+/** Whether `at` is written in the arguments of the call that makes `target`: the target's alone. */
+export function isInCall(target, at) {
+    const { call } = target;
+    return (!!call &&
+        call.source === at.source &&
+        call.node.pos <= at.node.pos &&
+        at.node.end <= call.node.end);
+}
+/** Each profile or tool whose options write `at` out as a value. A read inside a handler is code. */
+function targetsOf(project, targets, at) {
+    const names = [];
+    for (const [name, held] of targets) {
+        if (held.some((target) => isInTarget(target, at) && isWrittenIn(project, at.node, target.options)))
+            names.push(name);
+    }
+    return names;
+}
+const USERS = new WeakMap();
+/**
+ * Follows a constant to everything it sets: a profile, tool, or provider that reads it, and through a
+ * constant that reads it, whatever reads that one. The answer is the project's: do not change it.
+ */
+export function usersOf(project, binding) {
+    const known = USERS.get(project) ?? new Map();
+    USERS.set(project, known);
+    const cached = known.get(binding.initializer);
+    if (cached)
+        return cached;
+    const users = {
+        profiles: new Set(),
+        tools: new Set(),
+        providers: new Set(),
+        code: false,
+        readBy: [],
+    };
+    const seen = new Set();
+    const follow = (each) => {
+        if (seen.has(each.initializer))
+            return;
+        seen.add(each.initializer);
+        const reads = readsOf(project, each);
+        // A function nothing here calls is there for code the studio does not read.
+        if (each.returns && !reads.length)
+            users.code = true;
+        for (const read of reads) {
+            const profiles = targetsOf(project, project.profiles, read);
+            const tools = profiles.length ? [] : targetsOf(project, project.tools, read);
+            const providers = profiles.length || tools.length ? [] : targetsOf(project, project.providers, read);
+            const target = profiles.length || tools.length || providers.length;
+            const held = target ? undefined : holderOf(read);
+            const holder = held && isWrittenIn(project, read.node, held.initializer) ? held : undefined;
+            for (const profile of profiles)
+                users.profiles.add(profile);
+            for (const tool of tools)
+                users.tools.add(tool);
+            for (const provider of providers)
+                users.providers.add(provider);
+            if (holder)
+                follow(holder);
+            else if (!target) {
+                users.code = true;
+                users.readBy.push(read);
+            }
+        }
+    };
+    follow(binding);
+    known.set(binding.initializer, users);
+    return users;
+}
+/** Each top-level `const` of a file that is set to a value, not a function. */
+function constantsOf(source) {
+    return constsOf(source)
+        .filter(({ initializer }) => !isFunctionValue(unwrapped(initializer)))
+        .map((held) => ({ ...held, source }));
+}
+/** `STANDARD_GUARDRAILS` and `standardGuardrails` as "Standard guardrails". */
+export function readableName(name) {
+    const words = name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[\s_]+/)
+        .filter(Boolean)
+        .map((word) => word.toLowerCase());
+    const text = words.join(' ');
+    return text ? text[0]?.toUpperCase() + text.slice(1) : name;
+}
+/**
+ * The profile key a constant fills: set when every read of it is the whole value of that one key,
+ * written in a profile's own options. A constant read any other way has none.
+ */
+function wholeKey(project, binding) {
+    const keys = new Set();
+    for (const read of readsOf(project, binding)) {
+        let value = read.node;
+        while (ts.isParenthesizedExpression(value.parent) ||
+            ts.isAsExpression(value.parent) ||
+            ts.isSatisfiesExpression(value.parent))
+            value = value.parent;
+        const held = value.parent;
+        const whole = ts.isShorthandPropertyAssignment(held) ||
+            (ts.isPropertyAssignment(held) && held.initializer === value);
+        const own = whole &&
+            [...project.profiles.values()].flat().some((target) => target.options === held.parent);
+        keys.add(own ? propertyName(held) : undefined);
+    }
+    const [key] = keys;
+    return keys.size === 1 ? key : undefined;
+}
+/**
+ * The project's shared settings: each constant that more than one profile or tool reads, with
+ * who reads it. One that a single profile reads is a part of that profile, and is not listed.
+ */
+export function sharedSettings(project) {
+    const shared = [];
+    for (const source of project.files.values()) {
+        for (const binding of constantsOf(source)) {
+            const users = usersOf(project, binding);
+            if (users.profiles.size + users.tools.size < 2)
+                continue;
+            const key = users.tools.size ? undefined : wholeKey(project, binding);
+            shared.push({
+                name: binding.name,
+                label: readableName(binding.name),
+                file: source.fileName,
+                line: source.getLineAndCharacterOfPosition(binding.initializer.parent.getStart(source)).line +
+                    1,
+                ...(key === undefined ? {} : { key }),
+                profiles: [...users.profiles],
+                tools: [...users.tools],
+                readByCode: users.code,
+            });
+        }
+    }
+    return shared;
+}
+/** The initializer of the one top-level `const name = ...` in a file. */
+function constant(source, name) {
+    const found = [];
+    for (const statement of source.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        if (!(statement.declarationList.flags & ts.NodeFlags.Const))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isIdentifier(declaration.name) &&
+                declaration.name.text === name &&
+                declaration.initializer) {
+                found.push(declaration.initializer);
+            }
+        }
+    }
+    return found.length === 1 ? found[0] : undefined;
+}
+/** Where a file imports `name` from, and what it is called there. */
+function importOf(source, name) {
+    for (const { specifier, elements } of namedImports(source)) {
+        const element = elements.find((each) => each.name.text === name);
+        if (element)
+            return { specifier, name: (element.propertyName ?? element.name).text };
+    }
+    return undefined;
+}
+/** The text a property of `options` holds, following a constant; undefined when it is not plain text. */
+function textOf(project, target, key) {
+    const held = target.options.properties.find((property) => propertyName(property) === key);
+    if (!held || !ts.isPropertyAssignment(held))
+        return undefined;
+    const { node } = followed(project, {
+        node: held.initializer,
+        source: target.source,
+        env: target.env,
+    });
+    return ts.isStringLiteralLike(node) ? node.text : undefined;
+}
+/** The type a profile or a tool is written with, when the file says it in words. */
+export function writtenType(project, target) {
+    return textOf(project, target, 'type');
+}
+/**
+ * The names a function gives the call it makes, one for each place the project calls the function.
+ * None unless every one of those calls says the name: the studio does not write what it cannot name.
+ */
+function madeBy(project, target, key) {
+    const maker = holderOf({ node: target.options, source: target.source });
+    const fn = maker && functionOf(project, target.source, maker.name);
+    if (!maker || !fn || fn.value !== maker.initializer)
+        return [];
+    const named = [];
+    for (const read of readsOf(project, maker)) {
+        const call = read.node.parent;
+        const value = ts.isCallExpression(call) && call.expression === read.node
+            ? calledValue(project, call, read)
+            : undefined;
+        if (!value?.env || !ts.isCallExpression(call))
+            return [];
+        const made = {
+            ...target,
+            env: value.env,
+            call: { node: call, source: read.source },
+        };
+        const name = textOf(project, made, key);
+        if (name === undefined)
+            return [];
+        named.push([name, made]);
+    }
+    return named;
+}
+/**
+ * Walks the project's files from `entry`, the setup module, following each import. Yields each
+ * file as it is read, so a caller can say where the walk is. Returns every file read.
+ */
+export function* walkProject(entry, root, read) {
+    const files = new Map();
+    const queue = [{ file: resolve(entry) }];
+    for (let step = queue.shift(); step !== undefined; step = queue.shift()) {
+        const path = step.file;
+        if (files.has(path))
+            continue;
+        const text = read(path);
+        if (text === undefined)
+            continue;
+        const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true);
+        files.set(path, source);
+        yield step;
+        for (const specifier of specifiers(source)) {
+            const next = importedFile(path, specifier, (file) => read(file) !== undefined, root);
+            if (next && !files.has(next))
+                queue.push({ file: next, from: path });
+        }
+    }
+    return files;
+}
+/** Reads the project from `entry`, the setup module. `read` returns a file's text, or undefined. */
+export function readProjectSource(entry, root, read) {
+    const walk = walkProject(entry, root, read);
+    let step = walk.next();
+    while (!step.done)
+        step = walk.next();
+    return projectOf(step.value, entry, root);
+}
+/** The project the walked `files` hold: its profiles and tools, where each is made. */
+export function projectOf(files, entry, root) {
+    const project = {
+        root,
+        entry: resolve(entry),
+        files,
+        profiles: new Map(),
+        tools: new Map(),
+        providers: new Map(),
+    };
+    const calls = [];
+    for (const source of project.files.values()) {
+        const visit = (node) => {
+            if (ts.isCallExpression(node) && node.arguments[0]) {
+                const name = calleeName(node);
+                // A tool has no define call of its own, so one written as a constant is followed to it.
+                const written = name === 'registerTool'
+                    ? followed(project, { node: node.arguments[0], source })
+                    : { node: unwrapped(node.arguments[0]), source };
+                const options = written.node;
+                if (ts.isObjectLiteralExpression(options) && !written.env) {
+                    const target = { file: written.source.fileName, source: written.source, options };
+                    if (takesProfile(node))
+                        calls.push({ into: project.profiles, key: 'id', target });
+                    if (name === 'registerTool')
+                        calls.push({ into: project.tools, key: 'name', target });
+                }
+            }
+            // A provider's settings follow its definition; left without an id, it has the definition's.
+            const settings = ts.isCallExpression(node) && calleeName(node) === 'registerProvider' && node.arguments[1]
+                ? unwrapped(node.arguments[1])
+                : undefined;
+            if (settings && ts.isObjectLiteralExpression(settings)) {
+                const target = { file: source.fileName, source, options: settings };
+                const definition = unwrapped(node.arguments[0]);
+                const unnamed = !settings.properties.some((property) => propertyName(property) === 'id');
+                const own = unnamed && ts.isIdentifier(definition) ? definitionOfFactory(definition.text) : undefined;
+                if (own)
+                    project.providers.set(own, [...(project.providers.get(own) ?? []), target]);
+                else
+                    calls.push({ into: project.providers, key: 'id', target });
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    // Every file is read before a name is followed, so a constant from another file is found.
+    const made = [];
+    for (const { into, key, target } of calls) {
+        const named = textOf(project, target, key);
+        if (named !== undefined)
+            into.set(named, [...(into.get(named) ?? []), target]);
+        else
+            made.push({ into, key, target });
+    }
+    // A function that makes the call names it by a parameter: each call of the function is one.
+    for (const { into, key, target } of made) {
+        for (const [named, each] of madeBy(project, target, key))
+            into.set(named, [...(into.get(named) ?? []), each]);
+    }
+    return project;
+}