improve exeution contexts

mProjectsCode · mProjectsCode · commit 6b15260e7e66 · 2025-02-14T22:44:10.000+01:00
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -37,7 +37,7 @@ jobs:
                   bun install
                   bun run build
                   mkdir ${{ env.PLUGIN_NAME }}
-                  cp main.js manifest.json styles.css ${{ env.PLUGIN_NAME }}
+                  cp main.js manifest.json styles.css JsEngine.d.ts ${{ env.PLUGIN_NAME }}
                   zip -r ${{ env.PLUGIN_NAME }}-${{ github.ref_name }}.zip ${{ env.PLUGIN_NAME }}
                   ls
 
diff --git a/JsEngine.d.ts b/JsEngine.d.ts
diff --git a/automation/release.ts b/automation/release.ts
@@ -6,7 +6,7 @@ import { $choice as $choice, $confirm, $seq, CMD_FMT, Verboseness } from 'utils/
 async function runPreconditions(): Promise<void> {
 	// run preconditions
 	await $seq(
-		[`bun run format`, `bun run lint:fix`, `bun run test`],
+		[`bun run types`, `bun run format`, `bun run lint:fix`, `bun run test`],
 		(cmd: string) => {
 			throw new UserError(`precondition "${cmd}" failed`);
 		},
diff --git a/jsEngine/api/Internal.ts b/jsEngine/api/Internal.ts
@@ -5,9 +5,11 @@ import type {
 	ExecutionContext,
 	JsExecutionGlobals,
 	JsExecutionGlobalsConstructionOptions,
-	CodeBlockExecutionContext,
+	MarkdownCodeBlockExecutionContext,
 	JSFileExecutionContext,
 	UnknownExecutionContext,
+	MarkdownCallingJSFileExecutionContext,
+	MarkdownOtherExecutionContext,
 } from 'jsEngine/engine/JsExecution';
 import { ExecutionSource } from 'jsEngine/engine/JsExecution';
 import { ResultRenderer } from 'jsEngine/engine/ResultRenderer';
@@ -16,6 +18,14 @@ import { Component, TFile } from 'obsidian';
 import * as Obsidian from 'obsidian';
 import { z } from 'zod';
 
+export type ExecuteFileEngineExecutionParams = Omit<EngineExecutionParams, 'code' | 'context'> & {
+	context?: JSFileExecutionContext | MarkdownCallingJSFileExecutionContext;
+};
+
+export type ExecuteFileSimpleEngineExecutionParams = Omit<EngineExecutionParams, 'code' | 'component' | 'context'> & {
+	context?: JSFileExecutionContext | MarkdownCallingJSFileExecutionContext;
+};
+
 /**
  * The internal API provides access to some of js engines internals.
  */
@@ -59,20 +69,20 @@ export class InternalAPI {
 	 * @param path
 	 * @param params
 	 */
-	public async executeFile(path: string, params: Omit<EngineExecutionParams, 'code' | 'context'>): Promise<JsExecution> {
+	public async executeFile(path: string, params: ExecuteFileEngineExecutionParams): Promise<JsExecution> {
 		validateAPIArgs(z.object({ path: z.string(), params: this.apiInstance.validators.engineExecutionParamsFile }), { path, params });
 
 		const file = this.apiInstance.app.vault.getAbstractFileByPath(path);
 		if (!file || !(file instanceof TFile)) {
 			throw new Error(`File ${path} not found.`);
 		}
 		return await this.execute({
-			...params,
-			code: await this.apiInstance.app.vault.read(file),
 			context: {
 				executionSource: ExecutionSource.JSFile,
-				file: file,
+				jsFile: file,
 			},
+			...params,
+			code: await this.apiInstance.app.vault.read(file),
 		});
 	}
 
@@ -84,7 +94,7 @@ export class InternalAPI {
 	 * @param path
 	 * @param params
 	 */
-	public async executeFileSimple(path: string, params?: Omit<EngineExecutionParams, 'code' | 'component' | 'context'>): Promise<JsExecution> {
+	public async executeFileSimple(path: string, params?: ExecuteFileSimpleEngineExecutionParams): Promise<JsExecution> {
 		validateAPIArgs(z.object({ path: z.string(), params: this.apiInstance.validators.engineExecutionParamsFileSimple.optional() }), {
 			path,
 			params,
@@ -132,17 +142,10 @@ export class InternalAPI {
 	 * @param path The file path of the markdown file the code block is in.
 	 * @returns
 	 */
-	public async getContextForMarkdownCodeBlock(path: string): Promise<CodeBlockExecutionContext> {
+	public async getContextForMarkdownCodeBlock(path: string): Promise<MarkdownCodeBlockExecutionContext> {
 		validateAPIArgs(z.object({ path: z.string() }), { path });
 
-		const file = this.apiInstance.app.vault.getAbstractFileByPath(path);
-		if (!file || !(file instanceof TFile)) {
-			throw new Error(`File ${path} not found.`);
-		}
-		if (file.extension !== 'md' && file.extension !== '.md') {
-			throw new Error(`File ${path} is not a markdown file. Expected file extension to be ".md".`);
-		}
-
+		const file = this.getFileWithExtension(path, 'md');
 		const metadata = this.apiInstance.app.metadataCache.getFileCache(file);
 
 		return {
@@ -153,6 +156,49 @@ export class InternalAPI {
 		};
 	}
 
+	/**
+	 * Gets the execution context for when a markdown file calls a JS file.
+	 * This adds some extra info about the markdown file into the context, compared to {@link getContextForJSFile}.
+	 *
+	 * @param markdownPath The file path of the markdown file.
+	 * @param jsPath The file path of the JS file.
+	 * @returns
+	 */
+	public async getContextForMarkdownCallingJSFile(markdownPath: string, jsPath: string): Promise<MarkdownCallingJSFileExecutionContext> {
+		validateAPIArgs(z.object({ markdownPath: z.string(), jsPath: z.string() }), { markdownPath, jsPath });
+
+		const markdownFile = this.getFileWithExtension(markdownPath, 'md');
+		const metadata = this.apiInstance.app.metadataCache.getFileCache(markdownFile);
+
+		const jsFile = this.getFileWithExtension(jsPath, 'js');
+
+		return {
+			executionSource: ExecutionSource.MarkdownCallingJSFile,
+			file: markdownFile,
+			metadata: metadata ?? undefined,
+			jsFile: jsFile,
+		};
+	}
+
+	/**
+	 * Gets the execution context for a markdown code block.
+	 *
+	 * @param path The file path of the markdown file the code block is in.
+	 * @returns
+	 */
+	public async getContextForMarkdownOther(path: string): Promise<MarkdownOtherExecutionContext> {
+		validateAPIArgs(z.object({ path: z.string() }), { path });
+
+		const file = this.getFileWithExtension(path, 'md');
+		const metadata = this.apiInstance.app.metadataCache.getFileCache(file);
+
+		return {
+			executionSource: ExecutionSource.MarkdownOther,
+			file: file,
+			metadata: metadata ?? undefined,
+		};
+	}
+
 	/**
 	 * Gets the execution context for a JS file.
 	 *
@@ -162,17 +208,11 @@ export class InternalAPI {
 	public async getContextForJSFile(path: string): Promise<JSFileExecutionContext> {
 		validateAPIArgs(z.object({ path: z.string() }), { path });
 
-		const file = this.apiInstance.app.vault.getAbstractFileByPath(path);
-		if (!file || !(file instanceof TFile)) {
-			throw new Error(`File ${path} not found.`);
-		}
-		if (file.extension !== 'js' && file.extension !== '.js') {
-			throw new Error(`File ${path} is not a JS file. Expected file extension to be ".js".`);
-		}
+		const file = this.getFileWithExtension(path, 'js');
 
 		return {
 			executionSource: ExecutionSource.JSFile,
-			file: file,
+			jsFile: file,
 		};
 	}
 
@@ -228,4 +268,15 @@ export class InternalAPI {
 			await this.executeFileSimple(script);
 		}
 	}
+
+	private getFileWithExtension(path: string, extension: string): TFile {
+		const file = this.apiInstance.app.vault.getAbstractFileByPath(path);
+		if (!file || !(file instanceof TFile)) {
+			throw new Error(`File ${path} not found.`);
+		}
+		if (file.extension !== extension && file.extension !== `.${extension}`) {
+			throw new Error(`File ${path} is not of the expected file type. Expected file extension to be ".${extension}".`);
+		}
+		return file;
+	}
 }
diff --git a/jsEngine/engine/JsExecution.ts b/jsEngine/engine/JsExecution.ts
@@ -14,11 +14,13 @@ export type JsFunc = (...args: unknown[]) => Promise<unknown>;
 
 export enum ExecutionSource {
 	MarkdownCodeBlock = 'markdown-code-block',
+	MarkdownCallingJSFile = 'markdown-calling-js-file',
+	MarkdownOther = 'markdown-other',
 	JSFile = 'js-file',
 	Unknown = 'unknown',
 }
 
-export interface CodeBlockExecutionContext {
+export interface MarkdownCodeBlockExecutionContext {
 	executionSource: ExecutionSource.MarkdownCodeBlock;
 	/**
 	 * The file that the code block is in.
@@ -39,12 +41,40 @@ export interface Block {
 	to: number;
 }
 
+export interface MarkdownCallingJSFileExecutionContext {
+	executionSource: ExecutionSource.MarkdownCallingJSFile;
+	/**
+	 * The markdown file that the JS File is called from.
+	 */
+	file: TFile;
+	/**
+	 * The metadata of the markdown file.
+	 */
+	metadata?: CachedMetadata | undefined;
+	/**
+	 * The JS that is being called.
+	 */
+	jsFile: TFile;
+}
+
+export interface MarkdownOtherExecutionContext {
+	executionSource: ExecutionSource.MarkdownOther;
+	/**
+	 * The file that the code block is in.
+	 */
+	file: TFile;
+	/**
+	 * The metadata of the file.
+	 */
+	metadata?: CachedMetadata | undefined;
+}
+
 export interface JSFileExecutionContext {
 	executionSource: ExecutionSource.JSFile;
 	/**
 	 * The JS that is being executed.
 	 */
-	file: TFile;
+	jsFile: TFile;
 }
 
 export interface UnknownExecutionContext {
@@ -58,7 +88,12 @@ export interface UnknownExecutionContext {
 /**
  * Context provided to a {@link JsExecution}.
  */
-export type ExecutionContext = CodeBlockExecutionContext | JSFileExecutionContext | UnknownExecutionContext;
+export type ExecutionContext =
+	| MarkdownCodeBlockExecutionContext
+	| MarkdownCallingJSFileExecutionContext
+	| MarkdownOtherExecutionContext
+	| JSFileExecutionContext
+	| UnknownExecutionContext;
 
 /**
  * Global variables provided to a {@link JsExecution}.
diff --git a/jsEngine/messages/MessageComponent.svelte b/jsEngine/messages/MessageComponent.svelte
@@ -67,8 +67,13 @@
 						<p>Source ID: {messageWrapper.source.id}</p>
 						{@const executionContext = messageWrapper.source.executionContext}
 						{#if executionContext}
-							<p>Execution Context Type: {executionContext.executionSource}</p>
-							<p>Execution Context File: {executionContext.file?.path ?? 'none'}</p>
+							<p>Execution Type: {executionContext.executionSource}</p>
+							{#if 'file' in executionContext}
+								<p>Execution File: {executionContext.file?.path ?? 'none'}</p>
+							{/if}
+							{#if 'jsFile' in executionContext}
+								<p>Execution JS File: {executionContext.jsFile?.path ?? 'none'}</p>
+							{/if}
 						{/if}
 					{/if}
 				</div>
diff --git a/jsEngine/utils/Validators.ts b/jsEngine/utils/Validators.ts
@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
 import { API } from 'jsEngine/api/API';
+import type { ExecuteFileEngineExecutionParams, ExecuteFileSimpleEngineExecutionParams } from 'jsEngine/api/Internal';
 import { AbstractMarkdownElement } from 'jsEngine/api/markdown/AbstractMarkdownElement';
 import type { TableElementType } from 'jsEngine/api/markdown/AbstractMarkdownElementContainer';
 import type {
@@ -14,7 +15,16 @@ import type {
 	YesNoPromptOptions,
 } from 'jsEngine/api/PromptAPI';
 import type { EngineExecutionParams } from 'jsEngine/engine/Engine';
-import type { Block, ExecutionContext, JsExecutionGlobalsConstructionOptions } from 'jsEngine/engine/JsExecution';
+import type {
+	Block,
+	ExecutionContext,
+	JsExecutionGlobalsConstructionOptions,
+	JSFileExecutionContext,
+	MarkdownCallingJSFileExecutionContext,
+	MarkdownCodeBlockExecutionContext,
+	MarkdownOtherExecutionContext,
+	UnknownExecutionContext,
+} from 'jsEngine/engine/JsExecution';
 import { ExecutionSource } from 'jsEngine/engine/JsExecution';
 import { MessageType } from 'jsEngine/messages/MessageManager';
 import { ErrorLevel, JSEngineValidationError } from 'jsEngine/utils/Errors';
@@ -50,6 +60,11 @@ export class Validators {
 	block: z.ZodType<Block, any, any>;
 	tableElementType: z.ZodType<TableElementType, any, any>;
 	tableElementBody: z.ZodType<TableElementType[][], any, any>;
+	markdownCodeBlockExecutionContext: z.ZodType<MarkdownCodeBlockExecutionContext, any, any>;
+	markdownCallingJSFileExecutionContext: z.ZodType<MarkdownCallingJSFileExecutionContext, any, any>;
+	markdownOtherExecutionContext: z.ZodType<MarkdownOtherExecutionContext, any, any>;
+	jsFileExecutionContext: z.ZodType<JSFileExecutionContext, any, any>;
+	unknownExecutionContext: z.ZodType<UnknownExecutionContext, any, any>;
 	executionContext: z.ZodType<ExecutionContext, any, any>;
 	engineExecutionParams: z.ZodType<EngineExecutionParams, any, any>;
 	engineExecutionParamsFile: z.ZodType<Omit<EngineExecutionParams, 'code' | 'context'>, any, any>;
@@ -81,23 +96,49 @@ export class Validators {
 		);
 		this.tableElementType = schemaForType<TableElementType>()(z.union([z.string(), z.number(), z.boolean(), z.null(), z.undefined()]));
 		this.tableElementBody = schemaForType<TableElementType[][]>()(z.array(z.array(this.tableElementType)));
+		this.markdownCodeBlockExecutionContext = schemaForType<MarkdownCodeBlockExecutionContext>()(
+			z.object({
+				executionSource: z.literal(ExecutionSource.MarkdownCodeBlock),
+				file: this.tFile,
+				metadata: this.cachedMetadata.optional(),
+				block: this.block.optional(),
+			}),
+		);
+		this.markdownCallingJSFileExecutionContext = schemaForType<MarkdownCallingJSFileExecutionContext>()(
+			z.object({
+				executionSource: z.literal(ExecutionSource.MarkdownCallingJSFile),
+				file: this.tFile,
+				metadata: this.cachedMetadata.optional(),
+				jsFile: this.tFile,
+			}),
+		);
+		this.markdownOtherExecutionContext = schemaForType<MarkdownOtherExecutionContext>()(
+			z.object({
+				executionSource: z.literal(ExecutionSource.MarkdownOther),
+				file: this.tFile,
+				metadata: this.cachedMetadata.optional(),
+			}),
+		);
+		this.jsFileExecutionContext = schemaForType<JSFileExecutionContext>()(
+			z.object({
+				executionSource: z.literal(ExecutionSource.JSFile),
+				jsFile: this.tFile,
+			}),
+		);
+		this.unknownExecutionContext = schemaForType<UnknownExecutionContext>()(
+			z.object({
+				executionSource: z.literal(ExecutionSource.Unknown),
+				file: this.tFile.optional(),
+			}),
+		);
 		this.executionContext = schemaForType<ExecutionContext>()(
 			z.discriminatedUnion('executionSource', [
-				z.object({
-					executionSource: z.literal(ExecutionSource.MarkdownCodeBlock),
-					file: this.tFile,
-					metadata: this.cachedMetadata.optional(),
-					block: this.block.optional(),
-				}),
-				z.object({
-					executionSource: z.literal(ExecutionSource.JSFile),
-					file: this.tFile,
-				}),
-				z.object({
-					executionSource: z.literal(ExecutionSource.Unknown),
-					file: this.tFile.optional(),
-				}),
-			]),
+				this.markdownCodeBlockExecutionContext,
+				this.markdownCallingJSFileExecutionContext,
+				this.markdownOtherExecutionContext,
+				this.jsFileExecutionContext,
+				this.unknownExecutionContext,
+			] as any) as z.ZodType<ExecutionContext, any, any>,
 		);
 		this.engineExecutionParams = schemaForType<EngineExecutionParams>()(
 			z.object({
@@ -108,18 +149,18 @@ export class Validators {
 				contextOverrides: z.record(z.unknown()).optional(),
 			}),
 		);
-		this.engineExecutionParamsFile = schemaForType<Omit<EngineExecutionParams, 'code' | 'context'>>()(
+		this.engineExecutionParamsFile = schemaForType<ExecuteFileEngineExecutionParams>()(
 			z.object({
 				component: this.component,
 				container: this.htmlElement.optional(),
-				context: this.executionContext.optional(),
+				context: z.union([this.markdownCallingJSFileExecutionContext, this.jsFileExecutionContext]).optional(),
 				contextOverrides: z.record(z.unknown()).optional(),
 			}),
 		);
-		this.engineExecutionParamsFileSimple = schemaForType<Omit<EngineExecutionParams, 'code' | 'component' | 'context'>>()(
+		this.engineExecutionParamsFileSimple = schemaForType<ExecuteFileSimpleEngineExecutionParams>()(
 			z.object({
 				container: this.htmlElement.optional(),
-				context: this.executionContext.optional(),
+				context: z.union([this.markdownCallingJSFileExecutionContext, this.jsFileExecutionContext]).optional(),
 				contextOverrides: z.record(z.unknown()).optional(),
 			}),
 		);
diff --git a/tsconfig.types.json b/tsconfig.types.json
