@theoremjs/studio 0.0.0-stage → 0.3.2

package/server/project-source.d.ts

@@ -0,0 +1,208 @@
+/**
+ * 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 ts from 'typescript';
+import type { SharedSetting } from './save-wire.ts';
+/** One call the studio can write to: its options object, in its file. */
+export interface SourceTarget {
+    file: string;
+    source: ts.SourceFile;
+    options: ts.ObjectLiteralExpression;
+    /** Set when a function of the project makes the call: what its parameters stand for, for this profile. */
+    env?: Env;
+    /** That function's call for this profile. What its arguments write is this profile's alone. */
+    call?: {
+        node: ts.CallExpression;
+        source: ts.SourceFile;
+    };
+}
+/** What a function's parameters stand for in one call of it. */
+export interface Env {
+    /** Each parameter's argument, where the call writes it. Undefined when the call gives none. */
+    bound: ReadonlyMap<string, Located | undefined>;
+    /** How many calls deep this one is. */
+    depth: number;
+}
+export interface ProjectSource {
+    /** The folder the studio may write in. */
+    root: string;
+    /** The setup module, where reading starts. */
+    entry: string;
+    /** Each file read, by absolute path, the setup module first. */
+    files: Map<string, ts.SourceFile>;
+    /** The profiles written out, in `defineProfile` or straight into `registerProfile`, by profile id. An id written twice has two. */
+    profiles: Map<string, SourceTarget[]>;
+    /** The `registerTool` calls, by tool name. */
+    tools: Map<string, SourceTarget[]>;
+    /** The providers registered, each by the settings of its `registerProvider` call, by provider id. */
+    providers: Map<string, SourceTarget[]>;
+}
+/** What the studio reads in a project's files and Save writes: a profile, a tool, or a provider. */
+export type SubjectKind = 'profile' | 'tool' | 'provider';
+/** Where the project's files write each thing of `kind`. */
+export declare function definedAs(project: ProjectSource, kind: SubjectKind): Map<string, SourceTarget[]>;
+/** An expression in the file that holds it. */
+export interface Located {
+    node: ts.Expression;
+    source: ts.SourceFile;
+    /** Set inside a function the studio followed a call into. */
+    env?: Env;
+}
+export type ReadFile = (path: string) => string | undefined;
+/** Whether `path` is `root` or inside it. */
+export declare function isInside(root: string, path: string): boolean;
+/** What the setup module exports for each decision, by profile id: its questions, or its pictures. */
+export type SetupExport = 'questions' | 'images';
+/** The setup module's `export const <name>`, when it writes one. */
+export declare function setupExport(source: ts.SourceFile, name: SetupExport): ts.VariableDeclaration | undefined;
+/** `expression` without the wrappers that do not change its value. */
+export declare function unwrapped(expression: ts.Expression): ts.Expression;
+/** The name a property is written under, when it is a plain one. */
+export declare function propertyName(property: ts.ObjectLiteralElementLike): string | undefined;
+/**
+ * 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 declare function calleeName(call: ts.CallExpression): string | undefined;
+/** Whether `at` is a name its file imports from the kernel by name, such as a protocol: Save rewrites it in place. */
+export declare function isKernelName(at: Located): boolean;
+/** Where `source` imports the kernel's `name` from, and the name it is called by there. */
+export declare function kernelImportOf(source: ts.SourceFile, name: string): {
+    specifier: string;
+    local: string;
+} | undefined;
+/** One key of an object, as the files write it. */
+export interface ShapeEntry {
+    key: string;
+    /** What the key is set to. Undefined when the files write it as a method, or cannot say. */
+    value?: Located;
+    /** The property that writes it. Undefined for what a call's own arguments set. */
+    property?: ts.ObjectLiteralElementLike;
+    /** The file that writes it. */
+    source: ts.SourceFile;
+    /** For a model's provider: the name its `model()` call is made on, which is what a change of provider rewrites. */
+    receiver?: Located;
+}
+/** An object as the files write it out: its own keys, and those of each object it spreads in. */
+export interface ObjectShape {
+    /** Each key by name, in the order written. The last one written of a name is the one held. */
+    entries: Map<string, ShapeEntry>;
+    /** A spread or a computed key the studio could not follow. Only the keys written `after` it are sure. */
+    open?: {
+        node: ts.Node;
+        source: ts.SourceFile;
+        after: Set<string>;
+    };
+    /** The literal a new key is written in. */
+    own?: {
+        node: ts.ObjectLiteralExpression;
+        source: ts.SourceFile;
+    };
+}
+/**
+ * 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 declare function shapeOf(project: ProjectSource, at: Located, depth?: number): ObjectShape | undefined;
+/**
+ * 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 declare function followed(project: ProjectSource, at: Located): Located;
+/** A top-level `const` of the project: its name where it is declared, its file, and what it is set to. */
+export interface Binding {
+    name: string;
+    source: ts.SourceFile;
+    initializer: ts.Expression;
+    /** Set for a function: `initializer` is what it returns. */
+    returns?: true;
+}
+/** The file of the project a relative import in `source` names. */
+export declare function sourceOf(project: ProjectSource, source: ts.SourceFile, specifier: string): ts.SourceFile | 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 declare function holderOf(at: Located): Binding | undefined;
+/**
+ * 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 declare function namedValue(project: ProjectSource, at: Located): {
+    origin: Located;
+    holder?: Binding;
+};
+/** Whether an identifier reads a value: not a declaration's name, a property's name, an import, or a type. */
+export declare function isRead(node: ts.Identifier): boolean;
+/** Who a constant's value reaches: the profiles and tools, and whether other code reads it too. */
+export interface ConstantUsers {
+    profiles: Set<string>;
+    tools: Set<string>;
+    providers: Set<string>;
+    /** Code that is not a profile, a tool, a provider, or another constant reads it. */
+    code: boolean;
+    /** Each place that code reads it. None for a function nothing the studio reads calls. */
+    readBy: Located[];
+}
+/** A provider the project registers under a name: the top-level `const` set to its `registerProvider` call. */
+export interface NamedProvider {
+    name: string;
+    source: ts.SourceFile;
+    /** Whether another file can import the name. */
+    exported: boolean;
+}
+/**
+ * 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 declare function providerNamed(project: ProjectSource, id: string): NamedProvider | undefined;
+/** Whether the top level of `source` already gives `name` a meaning: a declaration, or an import. */
+export declare function declares(source: ts.SourceFile, name: string): boolean;
+/** The extension the project's relative imports end in: `.ts`, `.js`, or none. `fallback` is read when it has none. */
+export declare function importExtension(project: ProjectSource, fallback: string): string;
+/** How `from` imports `to`: a relative path, ending as the project's imports do. */
+export declare function specifierTo(from: string, to: string, extension: string): string;
+/**
+ * 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 declare function isHeldId(kind: SubjectKind, path: readonly string[], at: Located): boolean;
+/** Whether `at` is written inside a call's options. */
+export declare function isInTarget(target: SourceTarget, at: Located): boolean;
+/** Whether `at` is written in the arguments of the call that makes `target`: the target's alone. */
+export declare function isInCall(target: SourceTarget, at: Located): boolean;
+/**
+ * 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 declare function usersOf(project: ProjectSource, binding: Binding): ConstantUsers;
+/** `STANDARD_GUARDRAILS` and `standardGuardrails` as "Standard guardrails". */
+export declare function readableName(name: string): string;
+/**
+ * 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 declare function sharedSettings(project: ProjectSource): SharedSetting[];
+/** The type a profile or a tool is written with, when the file says it in words. */
+export declare function writtenType(project: ProjectSource, target: SourceTarget): string | undefined;
+/** One file of the walk as it is read: its absolute path, and the file whose import led to it. */
+export interface FileStep {
+    file: string;
+    from?: string;
+}
+/**
+ * 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 declare function walkProject(entry: string, root: string, read: ReadFile): Generator<FileStep, Map<string, ts.SourceFile>>;
+/** Reads the project from `entry`, the setup module. `read` returns a file's text, or undefined. */
+export declare function readProjectSource(entry: string, root: string, read: ReadFile): ProjectSource;
+/** The project the walked `files` hold: its profiles and tools, where each is made. */
+export declare function projectOf(files: Map<string, ts.SourceFile>, entry: string, root: string): ProjectSource;