@karagoz/hayali 0.0.0-stage → 0.6.0

package/dist/src/main.d.ts

@@ -0,0 +1,3 @@
+import '@karagoz/shared/dist/karagoz-shared.css';
+import '@karagoz/sandbox/dist/karagoz-sandbox.css';
+import './style.css';

package/dist/src/parse/blocks.d.ts

@@ -0,0 +1,31 @@
+import type { Lesson, LineSpec, Step } from '../types';
+export type BlockRule = 'invalid-value' | 'malformed-yaml' | 'unknown-key';
+export declare const BLOCK_PREFIX = "krgz-";
+export declare const LESSON_BLOCK = "krgz-lesson";
+export declare const STEP_BLOCK = "krgz-step";
+/** A problem inside a YAML block; `line` is 0-based in the lesson file. */
+export interface BlockIssue {
+    rule: BlockRule;
+    line: number;
+    column: number;
+    message: string;
+}
+type Where = Pick<BlockIssue, 'line' | 'column'>;
+interface ParsedBlock {
+    data: Record<string, unknown> | undefined;
+    /** Position of every key and list item, by dotted path such as `editor.highlight.0.lines`. */
+    at: (path: string) => Where;
+}
+/** Parses the YAML of a block. `firstLine` is the 0-based lesson line the YAML text starts on. */
+export declare const parseYamlBlock: (text: string, firstLine: number, issues: BlockIssue[]) => ParsedBlock;
+/** `1-7, 13-17` to a `LineSpec`, or `undefined` if it is not that shorthand. */
+export declare const parseLinesShorthand: (text: string) => LineSpec | undefined;
+/** Reports a problem at the key or list item with this dotted path. */
+export type NoteBlockIssue = (rule: BlockRule, path: string, message: string) => void;
+export declare const readLessonBlock: (data: Record<string, unknown>, report: NoteBlockIssue) => Pick<Lesson, "immutable">;
+/** The directives of a step block: `Step` fields, plus `carry`, which only the parser acts on. */
+export type StepBlock = Partial<Pick<Step, 'removals' | 'locks' | 'editor' | 'preview'>> & {
+    carry?: string;
+};
+export declare const readStepBlock: (data: Record<string, unknown>, report: NoteBlockIssue) => StepBlock;
+export {};

package/dist/src/parse/body.d.ts

@@ -0,0 +1,7 @@
+/** A 0-based `[start, end)` range of lines. */
+export type LineRange = [start: number, end: number];
+/**
+ * The Markdown of `lines[start, end)` without the `cuts` (the fences that became files and blocks), trimmed. A cut
+ * between two blank lines does not leave a double gap.
+ */
+export declare const sliceBody: (lines: string[], start: number, end: number, cuts: LineRange[]) => string;

package/dist/src/parse/fenceInfo.d.ts

@@ -0,0 +1,8 @@
+export interface FenceInfo {
+    /** Bare words in order, e.g. `['css']` or `['yaml', 'krgz-step']`. */
+    words: string[];
+    /** `key=value` pairs; a bare `file` counts as `file=` with an empty value. Later keys win. */
+    attrs: Map<string, string>;
+}
+/** Splits a fence info string into words, with `key=value` pairs where the value may be quoted. */
+export declare const parseFenceInfo: (info: string) => FenceInfo;

package/dist/src/parse/fileSource.d.ts

@@ -0,0 +1,18 @@
+import type { FileSource } from './resolve';
+import type { ParseIssueRule } from './types';
+export interface FileSourceContext {
+    /** Reports an issue on the fence being read. */
+    fail: (rule: ParseIssueRule, message: string) => void;
+    resolveSrc?: (path: string) => string | undefined;
+    /** Collects the normalized `src=` paths asked of `resolveSrc`, once each. */
+    srcPaths: string[];
+}
+/**
+ * Where a file fence gets its content: its body, `from=` or `src=`, never more than one. Reports why and returns
+ * `undefined` when the fence cannot be used.
+ */
+export declare const readFileSource: (fence: {
+    attrs: Map<string, string>;
+    content: string;
+    path: string;
+}, { fail, resolveSrc, srcPaths }: FileSourceContext) => FileSource | undefined;

package/dist/src/parse/index.d.ts

@@ -0,0 +1,2 @@
+export { parseLesson } from './parseLesson';
+export type { ParseIssue, ParseIssueRule, ParseLessonOptions, ParseLessonResult, } from './types';

package/dist/src/parse/parseLesson.d.ts

@@ -0,0 +1,3 @@
+import type { ParseLessonOptions, ParseLessonResult } from './types';
+/** Never throws: if compiling fails on pathological input, the result is an empty lesson with one issue. */
+export declare const parseLesson: (source: string, options?: ParseLessonOptions) => ParseLessonResult;

package/dist/src/parse/resolve.d.ts

@@ -0,0 +1,37 @@
+import type { AdjustmentsTree } from '../types';
+import type { ParseIssue, ParseIssueRule } from './types';
+export type FileSource = {
+    kind: 'literal';
+    contents: string;
+} | {
+    kind: 'from';
+    ref: string;
+};
+export interface FileEntry {
+    path: string;
+    /** 0-based line of the fence. */
+    line: number;
+    source: FileSource;
+}
+/** The files declared for the base tree or for one step, by normalized path. */
+export interface Scope {
+    chapterId?: string;
+    stepId?: string;
+    entries: Map<string, FileEntry>;
+    /** Normalized paths in the step's `removals`. */
+    removals?: string[];
+    /** The step's `carry:` as written, with the 0-based position of the key. */
+    carry?: {
+        ref: string;
+        line: number;
+        column: number;
+    };
+    /** Set while resolving, once `carry` names a real step and forms no cycle. */
+    carryTarget?: Scope;
+}
+export type Report = (rule: ParseIssueRule, line: number, message: string, extra?: Partial<Pick<ParseIssue, 'chapterId' | 'stepId' | 'path' | 'column' | 'severity'>>) => void;
+/**
+ * Expands every `from=` reference and builds each scope's tree. A file that cannot be resolved is reported and left
+ * out. Only scopes with at least one resolved file appear in the result.
+ */
+export declare const resolveFiles: (base: Scope, steps: Scope[], report: Report) => Map<Scope, AdjustmentsTree>;

package/dist/src/parse/tree.d.ts

@@ -0,0 +1,11 @@
+import type { AdjustmentsTree } from '../types';
+/** Splits a root-relative path into its segments, dropping empty and `.` ones. */
+export declare const segments: (path: string) => string[];
+/** Normalizes a path to `a/b/c`, or `''` when nothing is left. */
+export declare const normalizePath: (path: string) => string;
+/** Whether `path` or one of its parent directories is already a file in `taken`, or it is a directory of one. */
+export declare const conflicts: (taken: Iterable<string>, path: string) => boolean;
+/** Puts a file into the tree, creating directories on the way. The path must not `conflict` with existing ones. */
+export declare const setFile: (tree: AdjustmentsTree, path: string, contents: string) => void;
+/** A `src=` path as a clean relative POSIX path, or `undefined` if it is empty, absolute or escapes the lesson folder. */
+export declare const normalizeSrcPath: (raw: string) => string | undefined;

package/dist/src/parse/types.d.ts

@@ -0,0 +1,32 @@
+import type { Lesson } from '../types';
+import type { BlockRule } from './blocks';
+export type ParseIssueRule = BlockRule | 'file-outside-step' | 'carry-cycle' | 'carry-drops-removals' | 'carry-unknown-step' | 'conflicting-file-source' | 'duplicate-file' | 'duplicate-id' | 'duplicate-lesson-block' | 'duplicate-step-block' | 'empty-chapter' | 'invalid-src' | 'invalid-id' | 'misplaced-lesson-block' | 'misplaced-step-block' | 'missing-file-path' | 'missing-id' | 'parser-failure' | 'ref-cycle' | 'ref-missing-path' | 'ref-unknown-step' | 'ref-with-body' | 'src-with-body' | 'step-outside-chapter' | 'unclosed-fence' | 'unresolved-src' | 'unknown-fence';
+/** A problem found while parsing a lesson file. Distinct from a `LessonIssue`, which is found by `validateLesson`. */
+export interface ParseIssue {
+    rule: ParseIssueRule;
+    severity: 'error' | 'warning';
+    message: string;
+    /** 1-based. */
+    line: number;
+    column?: number;
+    chapterId?: string;
+    stepId?: string;
+    path?: string;
+}
+export interface ParseLessonOptions {
+    /** Reads a `src=` file; the path is relative to the lesson file. Without it any `src=` is unresolved. */
+    resolveSrc?: (path: string) => string | undefined;
+}
+export interface ParseLessonResult {
+    /** Best-effort: whatever could be built, even when `issues` holds errors. */
+    lesson: Lesson;
+    issues: ParseIssue[];
+    /** Normalized `src=` paths asked of `resolveSrc`, for HMR/cache invalidation. */
+    srcPaths: string[];
+    /** 1-based Markdown line of a chapter, step or file, or `undefined` if it is not in the file. */
+    locate(target: {
+        chapterId: string;
+        stepId?: string;
+        path?: string;
+    }): number | undefined;
+}

package/dist/src/typedoc-entry.d.ts

@@ -0,0 +1,7 @@
+export { calloutPlugin, createCalloutRegistry } from './callouts';
+export type { CalloutDefinition, CalloutRegistry } from './callouts';
+export { i18nMessages } from './locales';
+export type { FullLayoutFrom } from './layout/breakpoints';
+export type { AdjustmentsTree, Chapter, EditorDirective, Lesson, LineSpec, PathPattern, Position, Step, } from './types';
+export { validateLesson } from './validateLesson';
+export type { LessonIssue, LessonIssueRule } from './validateLesson';

package/dist/src/types.d.ts

@@ -0,0 +1,69 @@
+/** Glob-style path pattern, e.g. `package.json` or `src/**`. */
+export type PathPattern = string;
+/** Adjustments tree: nested directories to file contents, as accepted by WebContainer `mount()`. */
+export interface AdjustmentsTree {
+    [name: string]: {
+        file: {
+            contents: string;
+        };
+    } | {
+        directory: AdjustmentsTree;
+    };
+}
+/** 1-based, inclusive: a line, a `[from, to]` range, or a list of either. */
+export type LineSpec = number | [from: number, to: number] | (number | [number, number])[];
+/** Per-step editor instructions, applied on every entry to the step. */
+export interface EditorDirective {
+    /** Files to open; the last one is focused. Optionally with a line to go to. */
+    open?: (string | {
+        path: string;
+        line?: number;
+    })[];
+    /** Files to close, or `'all'`. */
+    close?: string[] | 'all';
+    /** Lines to highlight. */
+    highlight?: {
+        path: string;
+        lines: LineSpec;
+    }[];
+}
+export interface Step {
+    /** Author-supplied, unique within its chapter. Never derived from title text. */
+    id: string;
+    title: string;
+    /** Markdown body. */
+    body: string;
+    /** Files added/changed by this step, overlaid on the lesson base tree. */
+    adjustments?: AdjustmentsTree;
+    /** Paths deleted when entering this step. */
+    removals?: string[];
+    /** Paths locked (UI-only) for this step. */
+    locks?: PathPattern[];
+    /** Editor directives applied on entry to this step. */
+    editor?: EditorDirective;
+    /** Preview to show on entry to this step. `url` is root-relative and may carry a query/hash. */
+    preview?: {
+        url: string;
+    };
+}
+export interface Chapter {
+    /** Author-supplied, unique within the lesson. Never derived from title text. */
+    id: string;
+    title: string;
+    steps: Step[];
+}
+export interface Lesson {
+    chapters: Chapter[];
+    /** Base tree mounted at boot, split into immutable and resettable tiers by `immutable`. */
+    files?: AdjustmentsTree;
+    /** Paths mounted once and never reset. */
+    immutable?: PathPattern[];
+}
+/**
+ * A step within a lesson. Step IDs are unique only within their chapter, so both IDs are needed. A position that
+ * names no existing step falls back to the first step of the lesson.
+ */
+export interface Position {
+    chapterId: string;
+    stepId: string;
+}

package/dist/src/validateLesson.d.ts

@@ -0,0 +1,22 @@
+import type { Lesson } from './types';
+export type LessonIssueRule = 'invalid-path' | 'invalid-preview-url' | 'line-out-of-range' | 'malformed-lines' | 'missing-file' | 'removed-path';
+export interface LessonIssue {
+    rule: LessonIssueRule;
+    chapterId: string;
+    stepId: string;
+    /** Normalized offending path, when the issue is about one. */
+    path?: string;
+    message: string;
+}
+/**
+ * Resolves a LineSpec to inclusive `[from, to]` ranges, or `undefined` if it is malformed. An ascending pair of numbers
+ * is a range; any other non-empty array is a list of lines and `[from, to]` pairs (not nested further).
+ */
+export declare const toRanges: (spec: unknown) => [number, number][] | undefined;
+/**
+ * Checks a lesson for authoring mistakes without a browser. Resolves each step's tree (base files plus the step's own
+ * adjustments, minus its removals; steps are not cumulative) and validates the step's editor directives and preview.
+ *
+ * @returns the issues found; an empty array means the lesson is valid.
+ */
+export declare const validateLesson: (lesson: Lesson) => LessonIssue[];