@dolphy-app/extension-sdk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @dolphy-app/extension-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK автора расширений: defineExtension, defineAnswerElement, помощники тестирования
+
+Версия пакетов равна версии приложения Dolphy, из релиза которого они опубликованы (0.2.0).
+
+`@dolphy-app/extension-sdk` — код расширения (`defineExtension`,
+`defineExerciseType`), элемент ответа (`defineAnswerElement`) и помощники
+тестов (`@dolphy-app/extension-sdk/testing`).
+
+```ts
+import { defineExtension } from '@dolphy-app/extension-sdk';
+import { loadExerciseType } from '@dolphy-app/extension-sdk/testing';
+```
+
+## Установка
+
+```sh
+npm install @dolphy-app/extension-sdk
+```
+
+## Документация
+
+[Расширения Dolphy](https://github.com/dolphy-app/dolphy/blob/main/docs/design/extensions.md).

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { AnswerElementProps, ExerciseTypeHandler, ExtensionContext, ExtensionModule, GradePolicyHandler, MarkdownRenderContext, MarkdownRendererModule } from "@dolphy-app/extension-api";
+export * from "@dolphy-app/extension-api";
+//#region packages/extension-sdk/src/define-extension.d.ts
+interface ExtensionDefinition {
+  exerciseTypes?: Readonly<Record<string, ExerciseTypeHandler>>;
+  gradePolicies?: Readonly<Record<string, GradePolicyHandler>>;
+  /** Вызывается после регистрации `exerciseTypes` и `gradePolicies`. */
+  activate?(context: ExtensionContext): void | Promise<void>;
+  deactivate?(): void | Promise<void>;
+}
+export declare const defineExerciseType: <Spec, Answer, View>(handler: ExerciseTypeHandler<Spec, Answer, View>) => ExerciseTypeHandler<Spec, Answer, View>;
+export declare const defineExtension: (definition: ExtensionDefinition) => ExtensionModule;
+//#endregion
+//#region packages/extension-sdk/src/answer-element.d.ts
+interface AnswerElementApi {
+  readonly root: ShadowRoot;
+  /** `aria-label` хост-элемента, выставленный приложением; `null`, если нет. */
+  readonly label: string | null;
+  /** Сообщает приложению текущий ответ: событие `dolphy-answer-change`. */
+  setAnswer(value: unknown, complete: boolean): void;
+  /** Просит приложение отправить ответ: событие `dolphy-answer-submit`. */
+  submit(): void;
+}
+interface AnswerElementInstance {
+  /** Вызывается при изменении `view`/`value`/`disabled`/`verdict`. */
+  update(props: AnswerElementProps): void;
+  destroy?(): void;
+}
+type MountAnswerElement = (api: AnswerElementApi, props: AnswerElementProps) => AnswerElementInstance;
+export declare const defineAnswerElement: (tag: string, mount: MountAnswerElement) => void;
+//#endregion
+//#region packages/extension-sdk/src/markdown-renderer.d.ts
+/** `export default defineMarkdownRenderer(...)` в модуле рендерера содержимого. */
+export declare const defineMarkdownRenderer: (render: (source: string, container: HTMLElement, context: MarkdownRenderContext) => void | Promise<void>) => MarkdownRendererModule<HTMLElement>;
+//#endregion
+export type { AnswerElementApi, AnswerElementInstance, ExtensionDefinition, MountAnswerElement };

package/dist/index.js

@@ -0,0 +1,166 @@
+import { ANSWER_EVENT, ELEMENT_NAME_PATTERN } from "@dolphy-app/extension-api";
+
+export * from "@dolphy-app/extension-api"
+
+//#region packages/extension-sdk/src/define-extension.ts
+const defineExerciseType = (handler) => handler;
+const disposeInReverse = async (registrations) => {
+	const errors = [];
+	for (const registration of registrations.splice(0).reverse()) try {
+		await registration.dispose();
+	} catch (error) {
+		errors.push(error);
+	}
+	return errors;
+};
+const defineExtension = (definition) => {
+	const registrations = [];
+	const register = (context) => {
+		const entries = Object.entries(definition.exerciseTypes ?? {});
+		for (const [type, handler] of entries) registrations.push(context.registerExerciseType(type, handler));
+		for (const [id, handler] of Object.entries(definition.gradePolicies ?? {})) registrations.push(context.registerGradePolicy(id, handler));
+	};
+	const activate = async (context) => {
+		try {
+			register(context);
+			await definition.activate?.(context);
+		} catch (error) {
+			const disposalErrors = await disposeInReverse(registrations);
+			if (disposalErrors.length === 0) throw error;
+			throw new AggregateError([error, ...disposalErrors], "activation failed and rollback was incomplete");
+		}
+	};
+	const deactivate = async () => {
+		const failures = [];
+		try {
+			await definition.deactivate?.();
+		} catch (error) {
+			failures.push(error);
+		}
+		const disposalErrors = await disposeInReverse(registrations);
+		if (disposalErrors.length > 0) failures.push(new AggregateError(disposalErrors, "failed to dispose contributions"));
+		if (failures.length === 1) throw failures[0];
+		if (failures.length > 1) throw new AggregateError(failures, "failed to deactivate extension");
+	};
+	return {
+		activate,
+		deactivate
+	};
+};
+
+//#endregion
+//#region packages/extension-sdk/src/answer-element.ts
+const logFailure = (tag, message, error) => {
+	console.error({
+		error,
+		tag
+	}, message);
+};
+const createAnswerElementClass = (tag, mount) => class AnswerElement extends HTMLElement {
+	#root = this.attachShadow({ mode: "open" });
+	#props = {
+		view: void 0,
+		value: void 0,
+		disabled: false,
+		verdict: null
+	};
+	#instance = null;
+	#isFlushScheduled = false;
+	get view() {
+		return this.#props.view;
+	}
+	set view(view) {
+		this.#change({ view });
+	}
+	get value() {
+		return this.#props.value;
+	}
+	set value(value) {
+		this.#change({ value });
+	}
+	get disabled() {
+		return this.#props.disabled;
+	}
+	set disabled(disabled) {
+		this.#change({ disabled });
+	}
+	get verdict() {
+		return this.#props.verdict;
+	}
+	set verdict(verdict) {
+		this.#change({ verdict });
+	}
+	connectedCallback() {
+		if (this.#instance !== null) return;
+		const readLabel = () => this.getAttribute("aria-label");
+		const api = {
+			root: this.#root,
+			get label() {
+				return readLabel();
+			},
+			setAnswer: (value, complete) => {
+				const detail = {
+					value,
+					complete
+				};
+				this.#emit(ANSWER_EVENT.change, detail);
+			},
+			submit: () => this.#emit(ANSWER_EVENT.submit, void 0)
+		};
+		try {
+			this.#instance = mount(api, Object.freeze({ ...this.#props }));
+		} catch (error) {
+			logFailure(tag, "answer element failed to mount", error);
+		}
+	}
+	disconnectedCallback() {
+		const instance = this.#instance;
+		this.#instance = null;
+		if (instance === null) return;
+		try {
+			instance.destroy?.();
+		} catch (error) {
+			logFailure(tag, "answer element failed to destroy", error);
+		}
+		this.#root.replaceChildren();
+	}
+	#change(patch) {
+		this.#props = {
+			...this.#props,
+			...patch
+		};
+		if (this.#instance === null || this.#isFlushScheduled) return;
+		this.#isFlushScheduled = true;
+		queueMicrotask(() => this.#flush());
+	}
+	#flush() {
+		this.#isFlushScheduled = false;
+		const instance = this.#instance;
+		if (instance === null) return;
+		try {
+			instance.update(Object.freeze({ ...this.#props }));
+		} catch (error) {
+			logFailure(tag, "answer element failed to update", error);
+		}
+	}
+	#emit(name, detail) {
+		this.dispatchEvent(new CustomEvent(name, {
+			detail,
+			bubbles: true,
+			composed: true
+		}));
+	}
+};
+const defineAnswerElement = (tag, mount) => {
+	if (!ELEMENT_NAME_PATTERN.test(tag)) throw new TypeError(`invalid custom element name '${tag}'`);
+	if (customElements.get(tag) !== void 0) return;
+	customElements.define(tag, createAnswerElementClass(tag, mount));
+};
+
+//#endregion
+//#region packages/extension-sdk/src/markdown-renderer.ts
+/** `export default defineMarkdownRenderer(...)` в модуле рендерера содержимого. */
+const defineMarkdownRenderer = (render) => ({ render });
+
+//#endregion
+export { defineAnswerElement, defineExerciseType, defineExtension, defineMarkdownRenderer };

package/dist/testing.d.ts

@@ -0,0 +1,40 @@
+import { ExtensionLogger, ExtensionModule, GradePolicyInput, GradeResult, GradeValue, JsonSchema, LibraryReader } from "@dolphy-app/extension-api";
+//#region packages/extension-sdk/src/testing.d.ts
+export declare const createMemoryLibrary: (files: Readonly<Record<string, string>>) => LibraryReader;
+export declare const createSchemaValidator: (schema: JsonSchema) => (value: unknown) => string[];
+export interface LoadedExerciseType {
+  project(spec: unknown, options?: {
+    exerciseId?: string;
+  }): Promise<unknown>;
+  grade(input: {
+    spec: unknown;
+    answer: unknown;
+    exerciseId?: string;
+    timeoutMs?: number;
+    authorMode?: boolean;
+  }): Promise<GradeResult>;
+  referenceAnswer(spec: unknown, options?: {
+    exerciseId?: string;
+  }): Promise<{
+    found: true;
+    answer: unknown;
+  } | {
+    found: false;
+  }>;
+  /** Деактивирует модуль расширения. */
+  dispose(): Promise<void>;
+}
+export declare const loadExerciseType: (module: ExtensionModule, type: string, options?: {
+  library?: LibraryReader;
+  logger?: ExtensionLogger;
+}) => Promise<LoadedExerciseType>;
+export interface LoadedGradePolicy {
+  evaluate(input: GradePolicyInput): Promise<GradeValue | null>;
+  /** Деактивирует модуль расширения. */
+  dispose(): Promise<void>;
+}
+export declare const loadGradePolicy: (module: ExtensionModule, id: string, options?: {
+  library?: LibraryReader;
+  logger?: ExtensionLogger;
+}) => Promise<LoadedGradePolicy>;
+//#endregion

package/dist/testing.js

@@ -0,0 +1,163 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+
+//#region packages/extension-sdk/src/testing.ts
+const MAX_MESSAGES = 6;
+const MAX_REASON_CHARS = 100;
+const MAX_TEXT_CHARS = 4e3;
+const DEFAULT_EXERCISE_ID = "test::lesson::exercise";
+const DEFAULT_TIMEOUT_MS = 2e3;
+const silentLogger = {
+	debug: () => void 0,
+	info: () => void 0,
+	warn: () => void 0,
+	error: () => void 0
+};
+const createMemoryLibrary = (files) => {
+	const entries = new Map(Object.entries(files));
+	return {
+		readText: async (path) => {
+			const text = entries.get(path);
+			if (text === void 0) throw new Error(`ENOENT: ${path}`);
+			return text;
+		},
+		stat: async (path) => {
+			const text = entries.get(path);
+			if (text === void 0) return null;
+			return {
+				kind: "file",
+				bytes: Buffer.byteLength(text),
+				mtimeMs: 0
+			};
+		}
+	};
+};
+const createSchemaValidator = (schema) => {
+	const validate = new Ajv2020({
+		allErrors: true,
+		strict: false
+	}).compile(schema);
+	return (value) => {
+		if (validate(value)) return [];
+		return (validate.errors ?? []).slice(0, MAX_MESSAGES).map((error) => `${error.instancePath || "/"} ${error.message}`);
+	};
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const OUTCOME_KEYS = {
+	passed: [
+		"outcome",
+		"feedback",
+		"data"
+	],
+	failed: [
+		"outcome",
+		"reason",
+		"feedback",
+		"detail",
+		"data"
+	],
+	error: [
+		"outcome",
+		"reason",
+		"feedback",
+		"data"
+	]
+};
+const textProblem = (result, key) => {
+	const value = result[key];
+	if (value === void 0) return null;
+	if (typeof value !== "string") return `'${key}' must be a string`;
+	if (value.length > MAX_TEXT_CHARS) return `'${key}' is longer than ${MAX_TEXT_CHARS} characters`;
+	return null;
+};
+const reasonProblem = (result) => {
+	const { reason } = result;
+	if (typeof reason !== "string" || reason.length === 0) return `'reason' must be a non-empty string`;
+	if (reason.length > MAX_REASON_CHARS) return `'reason' is longer than ${MAX_REASON_CHARS} characters`;
+	return null;
+};
+const findGradeResultProblem = (result) => {
+	if (!isRecord(result)) return "result must be an object";
+	const { outcome } = result;
+	if (outcome !== "passed" && outcome !== "failed" && outcome !== "error") return `unknown outcome ${JSON.stringify(outcome)}`;
+	const allowed = OUTCOME_KEYS[outcome];
+	const extra = Object.keys(result).find((key) => !allowed.includes(key));
+	if (extra !== void 0) return `unexpected key '${extra}'`;
+	return (outcome === "passed" ? null : reasonProblem(result)) ?? textProblem(result, "feedback") ?? textProblem(result, "detail");
+};
+const loadExerciseType = async (module, type, options = {}) => {
+	const handlers = /* @__PURE__ */ new Map();
+	const context = {
+		extensionId: "test",
+		logger: options.logger ?? silentLogger,
+		library: options.library ?? createMemoryLibrary({}),
+		registerExerciseType: (registeredType, handler) => {
+			handlers.set(registeredType, handler);
+			return { dispose: () => void handlers.delete(registeredType) };
+		},
+		registerGradePolicy: () => ({ dispose: () => void 0 })
+	};
+	await module.activate(context);
+	const handler = handlers.get(type);
+	if (handler === void 0) throw new Error(`exercise type '${type}' was not registered`);
+	return {
+		project: async (spec, { exerciseId = DEFAULT_EXERCISE_ID } = {}) => handler.project({
+			exerciseId,
+			spec
+		}),
+		grade: async ({ spec, answer, exerciseId = DEFAULT_EXERCISE_ID, timeoutMs = DEFAULT_TIMEOUT_MS, authorMode = false }) => {
+			const result = await handler.grade({
+				exerciseId,
+				spec,
+				answer,
+				timeoutMs,
+				authorMode
+			});
+			const problem = findGradeResultProblem(result);
+			if (problem !== null) throw new Error(`invalid grade result: ${problem}`);
+			return result;
+		},
+		referenceAnswer: async (spec, { exerciseId = DEFAULT_EXERCISE_ID } = {}) => {
+			const answer = await handler.referenceAnswer?.({
+				exerciseId,
+				spec
+			});
+			return answer === void 0 ? { found: false } : {
+				found: true,
+				answer
+			};
+		},
+		dispose: async () => {
+			await module.deactivate?.();
+		}
+	};
+};
+const isGradeValue = (value) => Number.isInteger(value) && value >= 1 && value <= 5;
+const loadGradePolicy = async (module, id, options = {}) => {
+	const handlers = /* @__PURE__ */ new Map();
+	const context = {
+		extensionId: "test",
+		logger: options.logger ?? silentLogger,
+		library: options.library ?? createMemoryLibrary({}),
+		registerExerciseType: () => ({ dispose: () => void 0 }),
+		registerGradePolicy: (registeredId, handler) => {
+			handlers.set(registeredId, handler);
+			return { dispose: () => void handlers.delete(registeredId) };
+		}
+	};
+	await module.activate(context);
+	const handler = handlers.get(id);
+	if (handler === void 0) throw new Error(`grade policy '${id}' was not registered`);
+	return {
+		evaluate: async (input) => {
+			const result = await handler(input);
+			if (result !== null && !isGradeValue(result)) throw new Error(`invalid grade policy result: ${JSON.stringify(result)} is not an integer 1..5 or null`);
+			return result;
+		},
+		dispose: async () => {
+			await module.deactivate?.();
+		}
+	};
+};
+
+//#endregion
+export { createMemoryLibrary, createSchemaValidator, loadExerciseType, loadGradePolicy };

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@dolphy-app/extension-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "SDK автора расширений: defineExtension, defineAnswerElement, помощники тестирования",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@dolphy-app/extension-api": "0.2.0",
+    "ajv": "^8"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dolphy-app/dolphy.git",
+    "directory": "packages/extension-sdk"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}