Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 | 12x 12x 12x 12x 12x 12x 18x 18x 1x 18x 1x 36x 34x 34x 34x 12x 12x 12x 19x 1x 19x 1x 19x 1x 19x 1x 19x 19x 46x 46x 20x 15x 1x 14x 14x 14x 13x 1x 13x 13x 8x 5x 46x 46x 46x 20x 20x 1x 19x 2x 17x 17x 17x 17x 17x 17x 17x 17x 16x 16x 16x 16x 16x 1x 15x 5x 17x 17x 10x 14x 1x 20x 20x 20x 20x 41x 41x 21x 21x 14x 1916x 1x 1x 1x 1x 13x | import { parse as parseYaml } from "yaml";
import { z } from "zod";
export const EMBEDDED_TUTOR_ANNOTATION_MAX_BYTES = 16 * 1024;
const OPENING_MARKER = "/* @unosim-tutor";
const CLOSING_MARKER = "@end-unosim-tutor */";
const SAFE_TUTOR_ID = /^[a-z][a-z0-9-]{0,63}$/;
const CONTROL_CHARACTER = /\p{Cc}/u;
const learningObjectiveSchema = z.preprocess(
(value) => typeof value === "string" ? value.trim() : value,
z.string().min(1).superRefine((value, context) => {
if ([...value].length > 500) {
context.addIssue({ code: z.ZodIssueCode.too_big, maximum: 500, type: "string", inclusive: true, message: "Objective is too long" });
}
if (CONTROL_CHARACTER.test(value)) {
context.addIssue({ code: z.ZodIssueCode.custom, message: "Objective contains a control character" });
}
}),
);
const SAFE_TEXT = (max: number) => z.string().trim().min(1)
.refine((value) => [...value].length <= max, `Text is longer than ${max} characters`)
.refine((value) => !CONTROL_CHARACTER.test(value), "Text contains a control character")
.refine((value) => !/https?:\/\//i.test(value), "URLs are not allowed in Tutor annotations");
const focusQuestionSchema = z.object({
kind: z.enum(["recall", "concept", "application", "prediction", "transfer"]),
text: SAFE_TEXT(500),
}).strict();
/** A teacher-authored focus area: a few questions the Tutor prefers to ask for this Example. */
const focusAreaSchema = z.object({
id: z.string().regex(SAFE_TUTOR_ID),
title: SAFE_TEXT(160),
objective: SAFE_TEXT(500),
questions: z.array(focusQuestionSchema).min(1).max(6),
}).strict();
export type ExampleFocusArea = z.infer<typeof focusAreaSchema>;
export const embeddedTutorAnnotationSchema = z.object({
schemaVersion: z.union([z.literal(1), z.literal(2)]),
focus: z.array(focusAreaSchema).min(1).max(8).optional(),
afterFocus: z.enum(["free", "topics"]).optional(),
topics: z.array(z.string().regex(SAFE_TUTOR_ID)).min(1).max(32).optional(),
primaryTopic: z.string().regex(SAFE_TUTOR_ID).optional(),
strategy: z.string().regex(SAFE_TUTOR_ID).optional(),
learningObjectives: z.array(learningObjectiveSchema).min(1).max(10).optional(),
}).strict().superRefine((value, context) => {
if (value.schemaVersion === 1 && (value.focus !== undefined || value.afterFocus !== undefined)) {
context.addIssue({ code: z.ZodIssueCode.custom, path: ["focus"], message: "focus and afterFocus require schemaVersion 2" });
}
if (value.afterFocus !== undefined && value.focus === undefined) {
context.addIssue({ code: z.ZodIssueCode.custom, path: ["afterFocus"], message: "afterFocus requires focus" });
}
if (value.focus !== undefined && new Set(value.focus.map(({ id }) => id)).size !== value.focus.length) {
context.addIssue({ code: z.ZodIssueCode.custom, path: ["focus"], message: "focus ids must be unique" });
}
if (value.primaryTopic !== undefined && value.topics === undefined) {
context.addIssue({ code: z.ZodIssueCode.custom, path: ["primaryTopic"], message: "primaryTopic requires topics" });
}
Iif (value.primaryTopic !== undefined && value.topics !== undefined && !value.topics.includes(value.primaryTopic)) {
context.addIssue({ code: z.ZodIssueCode.custom, path: ["primaryTopic"], message: "primaryTopic must be listed in topics" });
}
Iif (value.topics !== undefined && new Set(value.topics).size !== value.topics.length) {
context.addIssue({ code: z.ZodIssueCode.custom, path: ["topics"], message: "topics must be unique" });
}
});
export type ExampleTutorAnnotation = z.infer<typeof embeddedTutorAnnotationSchema>;
export type EmbeddedTutorAnnotationResult =
| { readonly status: "absent"; readonly cleanedSource: string }
| { readonly status: "valid"; readonly cleanedSource: string; readonly annotation: ExampleTutorAnnotation }
| { readonly status: "invalid"; readonly cleanedSource: string; readonly reason: string };
type AnnotationBoundary = {
readonly opening: number;
readonly payloadStart: number;
readonly closing: number;
readonly closingEnd: number;
};
type AnnotationBoundaryResult =
| { readonly status: "absent" }
| { readonly status: "invalid"; readonly cleanedSource: string; readonly reason: string }
| { readonly status: "found"; readonly boundary: AnnotationBoundary };
export function extractEmbeddedTutorAnnotation(
source: string,
fileName: string,
options?: { readonly isMainFile: boolean },
): EmbeddedTutorAnnotationResult {
const boundary = findAnnotationBoundary(source, fileName, options?.isMainFile ?? fileName.toLowerCase().endsWith(".ino"));
if (boundary.status === "absent") return { status: "absent", cleanedSource: source };
if (boundary.status === "invalid") return boundary;
if (Buffer.byteLength(source.slice(boundary.boundary.opening, boundary.boundary.closingEnd), "utf8") > EMBEDDED_TUTOR_ANNOTATION_MAX_BYTES) {
return invalidResult("Tutor annotation exceeds the byte limit", cleanFrom(source, boundary.boundary.opening));
}
let parsed: unknown;
try {
const payload = source.slice(boundary.boundary.payloadStart, boundary.boundary.closing);
if (containsYamlTag(payload)) throw new Error("YAML tags are not allowed");
parsed = parseYaml(payload, { schema: "core", uniqueKeys: true });
} catch {
return invalidResult("Tutor annotation YAML is invalid", cleanFrom(source, boundary.boundary.opening));
}
const annotation = embeddedTutorAnnotationSchema.safeParse(parsed);
if (!annotation.success) {
return invalidResult("Tutor annotation schema is invalid", cleanFrom(source, boundary.boundary.opening));
}
return {
status: "valid",
cleanedSource: cleanTerminalSource(source.slice(0, boundary.boundary.opening)),
annotation: annotation.data,
};
}
function findAnnotationBoundary(source: string, fileName: string, isMainFile: boolean): AnnotationBoundaryResult {
const firstOpening = source.indexOf(OPENING_MARKER);
const firstClosing = source.indexOf(CLOSING_MARKER);
if (firstOpening < 0 && firstClosing < 0) return { status: "absent" };
Iif (firstOpening < 0) return invalidBoundary("Malformed Tutor annotation marker", "");
if (countOccurrences(source, OPENING_MARKER) !== 1) {
return invalidBoundary("Tutor annotation is duplicated", cleanFrom(source, firstOpening));
}
if (!isMainFile || !fileName.toLowerCase().endsWith(".ino")) {
return invalidBoundary("Tutor annotation is not in the declared main .ino file", cleanFrom(source, firstOpening));
}
const openingLineStart = source.lastIndexOf("\n", firstOpening - 1) + 1;
Iif (source.slice(openingLineStart, firstOpening).trim() !== "") {
return invalidBoundary("Tutor annotation must start on its own line", cleanFrom(source, firstOpening));
}
const afterOpening = firstOpening + OPENING_MARKER.length;
const lineBreakLength = getLineBreakLength(source, afterOpening);
Iif (lineBreakLength === 0) {
return invalidBoundary("Tutor annotation opening marker is malformed", cleanFrom(source, firstOpening));
}
const payloadStart = afterOpening + lineBreakLength;
const closing = source.indexOf(CLOSING_MARKER, payloadStart);
if (closing < 0) return invalidBoundary("Tutor annotation is unterminated", cleanFrom(source, firstOpening));
const closingLineStart = source.lastIndexOf("\n", closing - 1) + 1;
const closingEnd = closing + CLOSING_MARKER.length;
const trailing = source.slice(closingEnd);
const closingIsOnOwnLine = source.slice(closingLineStart, closing).trim() === "";
if (!closingIsOnOwnLine || /\S/u.test(trailing)) {
return invalidBoundary("Tutor annotation is not terminal", cleanWithoutBlock(source, firstOpening, closingEnd));
}
return { status: "found", boundary: { opening: firstOpening, payloadStart, closing, closingEnd } };
}
function invalidBoundary(reason: string, cleanedSource: string): AnnotationBoundaryResult {
return { status: "invalid", reason, cleanedSource: cleanTerminalSource(cleanedSource) };
}
function getLineBreakLength(source: string, offset: number): number {
Iif (source.startsWith("\r\n", offset)) return 2;
Eif (source[offset] === "\n") return 1;
return 0;
}
function invalidResult(reason: string, cleanedSource: string): EmbeddedTutorAnnotationResult {
return { status: "invalid", reason, cleanedSource: cleanTerminalSource(cleanedSource) };
}
function cleanFrom(source: string, start: number): string {
return source.slice(0, start);
}
function cleanWithoutBlock(source: string, start: number, end: number): string {
return `${source.slice(0, start)}${source.slice(end)}`;
}
function cleanTerminalSource(source: string): string {
Eif (source.length === 0 || source.endsWith("\n")) return source;
return `${source}\n`;
}
function countOccurrences(source: string, marker: string): number {
let count = 0;
let offset = 0;
while (true) {
const index = source.indexOf(marker, offset);
if (index < 0) return count;
count += 1;
offset = index + marker.length;
}
}
function containsYamlTag(source: string): boolean {
for (let index = 0; index < source.length; index += 1) {
if (source[index] !== "!") continue;
const previous = source[index - 1];
Iif (previous !== undefined && !/\s|,|:|\{|\}|\[|\]/u.test(previous)) continue;
const next = source[index + 1];
Eif (next === "!" || next === "<" || (next !== undefined && /[A-Za-z]/u.test(next))) return true;
}
return false;
}
|