lens-content-processor 0.83.0 → 0.84.1

package/dist/answer-quotes.d.ts

@@ -0,0 +1,45 @@
+import type { ContentError } from "./index.js";
+import { type UuidEntry } from "./validator/uuid.js";
+export type AnswerQuoteForm = "container" | "leaf" | "text";
+export declare const ANSWER_QUOTE_ATTRIBUTES: readonly ["id", "fallback"];
+export interface AnswerQuoteProblem {
+    kind: "missing-id" | "invalid-id" | "unknown-attribute" | "malformed";
+    /** The attribute name (unknown-attribute), the id (invalid-id) or the attribute text (malformed). */
+    detail?: string;
+}
+export interface AnswerQuote {
+    form: AnswerQuoteForm;
+    /** The directive as written, from its colons to its closing brace. */
+    raw: string;
+    /** Offset of `raw` in the text, and its 1-based line there. */
+    offset: number;
+    line: number;
+    /** The id as written (a well-formed one is a UUID). */
+    id?: string;
+    fallback?: string;
+    problems: AnswerQuoteProblem[];
+}
+/** A well-formed quote's question id (lowercased) and where it is. */
+export interface AnswerQuoteRef {
+    id: string;
+    file: string;
+    line: number;
+}
+/** Every answer quote in `text`, in text order. Code spans, code blocks and math are skipped. */
+export declare function findAnswerQuotes(text: string): AnswerQuote[];
+/**
+ * The per-file check of the answer quotes in `texts`, the authored text
+ * fields of a file whose content is `source`, and the refs of its
+ * well-formed quotes. A quote not found in `source` came from another file
+ * (an embedded question file) and is that file's to report.
+ */
+export declare function checkAnswerQuotes(texts: string[], file: string, source: string): {
+    errors: ContentError[];
+    refs: AnswerQuoteRef[];
+};
+/**
+ * The cross-file check: every quoted id names a question, and not a survey
+ * question (survey answers are stored per survey, apart from question
+ * answers, so a quote cannot show them).
+ */
+export declare function answerQuoteErrors(refs: AnswerQuoteRef[], uuidEntries: UuidEntry[]): ContentError[];

package/dist/answer-quotes.js

@@ -0,0 +1,183 @@
+// src/answer-quotes.ts
+//
+// Answer quotes: course text that shows the learner's own earlier answer to a
+// question, named by the question's id:: (question ids are global,
+// validator/uuid.ts). remark-directive syntax, in three forms:
+//
+//   ::answer{id="<uuid>"}                  leaf, a line of its own
+//   :::answer{id="<uuid>"}  ...  :::       container (the body is ignored)
+//   ... :answer{id="<uuid>"} ...           text, inside a sentence
+//
+// `fallback="text"` is shown while the learner has no answer. A `[label]` is
+// allowed and ignored. Values may be double-quoted, single-quoted or bare.
+//
+// One parser serves every check: the per-file syntax check here
+// (checkAnswerQuotes), the cross-file "does that question exist" check
+// (answerQuoteErrors, run by wholeContentStep in index.ts) and the course-order
+// check (course-graph.ts).
+import { maskCode } from "./same-page-links.js";
+import { sourceLocator } from "./validator/same-lens-links.js";
+import { isValidUuid } from "./validator/uuid.js";
+export const ANSWER_QUOTE_ATTRIBUTES = ["id", "fallback"];
+// `[label]` and `{attributes}` are both optional; the name must end there.
+const TAIL = String.raw `(?:\[[^\]\n]*\])?(?:\{([^}\n]*)\})?(?![\w-])`;
+const BLOCK = new RegExp(String.raw `^ {0,3}(:{2,})answer${TAIL}[ \t]*$`, "gm");
+const TEXT = new RegExp(String.raw `(?<![\w:]):answer${TAIL}`, "g");
+// One attribute: name, name=value, name="value" or name='value'.
+const ATTRIBUTE = /\s*([^\s="'{}]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`{}]+)))?\s*/y;
+/** id and fallback of an attribute text, and what is wrong with it. */
+function readAttributes(attr) {
+    const out = {};
+    const problems = [];
+    let at = 0;
+    const text = attr ?? "";
+    while (at < text.length) {
+        ATTRIBUTE.lastIndex = at;
+        const m = ATTRIBUTE.exec(text);
+        if (!m || m[0] === "") {
+            problems.push({ kind: "malformed", detail: text.slice(at).trim() });
+            break;
+        }
+        at = ATTRIBUTE.lastIndex;
+        const [, key, ...values] = m;
+        const value = values.find((v) => v !== undefined);
+        if (key === "id" || key === "fallback")
+            out[key] = value ?? "";
+        else
+            problems.push({ kind: "unknown-attribute", detail: key });
+    }
+    if (!out.id)
+        problems.unshift({ kind: "missing-id" });
+    else if (!isValidUuid(out.id))
+        problems.unshift({ kind: "invalid-id", detail: out.id });
+    return { ...out, problems };
+}
+/** Every answer quote in `text`, in text order. Code spans, code blocks and math are skipped. */
+export function findAnswerQuotes(text) {
+    if (!text.includes(":answer"))
+        return [];
+    const masked = maskCode(text);
+    const quotes = [];
+    const add = (form, m, attr) => {
+        const offset = m.index + m[0].indexOf(":");
+        const end = m.index + m[0].trimEnd().length;
+        quotes.push({
+            form,
+            raw: text.slice(offset, end),
+            offset,
+            line: text.slice(0, offset).split("\n").length,
+            ...readAttributes(attr),
+        });
+    };
+    for (const m of masked.matchAll(BLOCK))
+        add(m[1].length === 2 ? "leaf" : "container", m, m[2]);
+    // The lookbehind keeps `::answer` and `:::answer` out of the text form.
+    for (const m of masked.matchAll(TEXT))
+        add("text", m, m[1]);
+    return quotes.sort((a, b) => a.offset - b.offset);
+}
+/**
+ * The per-file check of the answer quotes in `texts`, the authored text
+ * fields of a file whose content is `source`, and the refs of its
+ * well-formed quotes. A quote not found in `source` came from another file
+ * (an embedded question file) and is that file's to report.
+ */
+export function checkAnswerQuotes(texts, file, source) {
+    const errors = [];
+    const refs = [];
+    if (!source.includes(":answer"))
+        return { errors, refs };
+    const locate = sourceLocator(source);
+    for (const text of texts) {
+        for (const quote of findAnswerQuotes(text)) {
+            if (!source.includes(quote.raw))
+                continue;
+            const line = locate(quote.raw);
+            const at = { file, line };
+            for (const problem of quote.problems) {
+                errors.push({ ...at, ...problemError(problem, quote.raw) });
+            }
+            if (quote.id && isValidUuid(quote.id)) {
+                refs.push({ ...at, id: quote.id.toLowerCase() });
+            }
+        }
+    }
+    return { errors, refs };
+}
+function problemError(problem, raw) {
+    switch (problem.kind) {
+        case "missing-id":
+            return {
+                code: "answer-quote.id-missing",
+                severity: "error",
+                message: `Answer quote '${raw}' has no id`,
+                suggestion: 'Add the id:: of the question whose answer to show: :answer{id="<question id>"}',
+            };
+        case "invalid-id":
+            return {
+                code: "answer-quote.id-invalid",
+                severity: "error",
+                message: `Answer quote id '${problem.detail}' is not a UUID`,
+                suggestion: "Copy the id:: of the question whose answer to show",
+            };
+        case "unknown-attribute":
+            return {
+                code: "answer-quote.attribute-unknown",
+                severity: "warning",
+                message: `Unknown attribute '${problem.detail}' on answer quote '${raw}'`,
+                suggestion: "An answer quote takes only id and fallback",
+            };
+        case "malformed":
+            return {
+                code: "answer-quote.attributes-malformed",
+                severity: "warning",
+                message: `Cannot read the attributes '${problem.detail}' of answer quote '${raw}'`,
+                suggestion: 'Write attributes as name="value": id and fallback',
+            };
+    }
+}
+/**
+ * The cross-file check: every quoted id names a question, and not a survey
+ * question (survey answers are stored per survey, apart from question
+ * answers, so a quote cannot show them).
+ */
+export function answerQuoteErrors(refs, uuidEntries) {
+    if (refs.length === 0)
+        return [];
+    const questions = new Map();
+    for (const entry of uuidEntries) {
+        const id = entry.uuid.toLowerCase();
+        if (!entry.question || questions.has(id))
+            continue;
+        questions.set(id, entry);
+    }
+    return refs.flatMap(({ id, file, line }) => {
+        const question = questions.get(id);
+        if (!question) {
+            return [
+                {
+                    file,
+                    line,
+                    code: "answer-quote.question-missing",
+                    severity: "error",
+                    message: `Quotes an answer to question ${id}, but no question has that id`,
+                    suggestion: "Copy the id:: of an existing question",
+                },
+            ];
+        }
+        if (question.question.context === "survey") {
+            return [
+                {
+                    file,
+                    line,
+                    code: "answer-quote.survey-question",
+                    severity: "error",
+                    message: `Quotes an answer to question ${id}, a survey question (${question.file}): survey answers cannot be quoted`,
+                    suggestion: "Quote a question of a lens or a test",
+                },
+            ];
+        }
+        return [];
+    });
+}
+//# sourceMappingURL=answer-quotes.js.map

package/dist/answer-quotes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer-quotes.js","sourceRoot":"","sources":["../src/answer-quotes.ts"],"names":[],"mappings":"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"}

package/dist/bundler/article.d.ts

@@ -17,7 +17,7 @@ export interface ExcerptInput {
  * A point in the cleaned body where the prose is interrupted: an inline
  * element (`::video[[...]]`, `![[../widgets/...]]`, `:::question` block) or
  * the edge of a lifted callout (a `:::callout` that holds an element; one
- * holding only prose stays markdown and leaves no marker).
+ * holding only prose stays markdown and is an ArticleFence instead).
  */
 type ArticleMarkerBody = ({
     kind: "element";
@@ -30,11 +30,36 @@ type ArticleMarkerBody = ({
 export type ArticleMarker = {
     offset: number;
 } & ArticleMarkerBody;
+/**
+ * A fence line of a container directive that stays markdown in the body
+ * (`:::callout` holding only prose, `:::note`, `:::hide`, ...), at
+ * body[offset, end). articleText gives a range of the body that starts or
+ * ends inside the container its own opener or closer, so an excerpt never
+ * loses the box it starts in and never shows a stray `:::` line.
+ */
+type ArticleFenceBody = {
+    kind: "open";
+    closer: string;
+    /** A box (callout, note) is reopened in a range that starts inside
+     * it; a hide/collapse container is not. */
+    reopens: boolean;
+} | {
+    kind: "close";
+    opener: number;
+};
+export type ArticleFence = {
+    offset: number;
+    end: number;
+} & ArticleFenceBody;
 export interface ParsedArticleBody {
-    /** Publishable body with element lines and lifted callout fences removed. */
+    /** Publishable body with element lines and lifted callout fences removed.
+     * Render a range of it with articleText. */
     body: string;
     /** Markers in document order, with offsets into the cleaned body. */
     markers: ArticleMarker[];
+    /** Fences of balanced containers that stay markdown, in document order;
+     * a close fence names its opener's index in this list. */
+    fences: ArticleFence[];
 }
 /** A piece of an excerpt that contains markers. */
 export type ArticlePart = {
@@ -83,16 +108,29 @@ export declare function stripFrontmatter(article: string): string;
  * stripped, every valid element removed and recorded as a marker with its
  * character offset into the cleaned body, and every callout that holds an
  * element lifted: its fences are removed too and recorded as open/close
- * markers, so the prose and elements inside carry it as a frame. All
- * downstream work (anchor search, excerpt slicing, collapsed text, word
- * counts) uses this cleaned body, so element lines can never leak into
- * reader-visible text and anchors can never collide with element syntax.
+ * markers, so the prose and elements inside carry it as a frame. The fences
+ * of every other balanced container stay in the body and are recorded as
+ * fences. All downstream work (anchor search, excerpt slicing, collapsed
+ * text, word counts) uses this cleaned body, so element lines can never leak
+ * into reader-visible text and anchors can never collide with element
+ * syntax; the text of a range (excerpt, prose part, collapsed text) comes
+ * from articleText, which balances the fences it cuts.
  *
  * Malformed element lines, and elements inside hide/collapse containers, are
  * left in place as inert prose — parse-time validation
  * (parser/article-elements.ts) reports them.
  */
 export declare function parseArticleBody(article: string, file?: string): ParsedArticleBody;
+/**
+ * The markdown of body[start, end), with its container fences balanced: an
+ * opener for every box open at `start` (outermost first) and a closer for
+ * every container still open at `end`. A `:::hide` (or `:::collapse`) the
+ * range starts in is not reopened: the lens author chose that text to show.
+ * A closer whose opener is not in the text is left out, and so is an added
+ * fence that would make a box holding only whitespace. A fence line the range cuts in
+ * two stays plain text.
+ */
+export declare function articleText({ body, fences }: ParsedArticleBody, start: number, end: number): string;
 /**
  * Extract content from an article between two anchor texts.
  *

package/dist/bundler/article.js

@@ -45,10 +45,13 @@ function publishableArticleBody(article) {
  * stripped, every valid element removed and recorded as a marker with its
  * character offset into the cleaned body, and every callout that holds an
  * element lifted: its fences are removed too and recorded as open/close
- * markers, so the prose and elements inside carry it as a frame. All
- * downstream work (anchor search, excerpt slicing, collapsed text, word
- * counts) uses this cleaned body, so element lines can never leak into
- * reader-visible text and anchors can never collide with element syntax.
+ * markers, so the prose and elements inside carry it as a frame. The fences
+ * of every other balanced container stay in the body and are recorded as
+ * fences. All downstream work (anchor search, excerpt slicing, collapsed
+ * text, word counts) uses this cleaned body, so element lines can never leak
+ * into reader-visible text and anchors can never collide with element
+ * syntax; the text of a range (excerpt, prose part, collapsed text) comes
+ * from articleText, which balances the fences it cuts.
  *
  * Malformed element lines, and elements inside hide/collapse containers, are
  * left in place as inert prose — parse-time validation
@@ -63,8 +66,18 @@ export function parseArticleBody(article, file = "") {
             for (const index of callouts ?? [])
                 lifted.add(index);
     }
+    // Containers that stay markdown: every balanced one that is not lifted.
+    // An unbalanced fence stays in the text, where the validator reports it.
+    const closed = new Set();
+    for (const { marker } of scanned) {
+        if (marker?.kind === "close" && marker.opener >= 0)
+            closed.add(marker.opener);
+    }
     const outLines = [];
     const pending = [];
+    const pendingFences = [];
+    // Scanned line index of each balanced opener -> its index in pendingFences
+    const fenceIndex = new Map();
     const swallowBlankAround = (i, endIndex) => {
         // Removing the line(s) would leave the blank lines around them doubled
         // up; swallow one so the prose keeps a single paragraph break.
@@ -109,6 +122,24 @@ export function parseArticleBody(article, file = "") {
                 i++;
             continue;
         }
+        if (marker?.kind === "open" && closed.has(i)) {
+            fenceIndex.set(i, pendingFences.length);
+            pendingFences.push({
+                kind: "open",
+                closer: ":".repeat(marker.colons),
+                reopens: marker.name !== "hide" && marker.name !== "collapse",
+                outLineIndex: outLines.length,
+                length: line.length,
+            });
+        }
+        else if (marker?.kind === "close" && closed.has(marker.opener)) {
+            pendingFences.push({
+                kind: "close",
+                opener: fenceIndex.get(marker.opener),
+                outLineIndex: outLines.length,
+                length: line.length,
+            });
+        }
         outLines.push(line);
     }
     // Char offset of each retained line in the joined body
@@ -122,17 +153,120 @@ export function parseArticleBody(article, file = "") {
     // Markers at the very start/end leave blank edges behind — trim and shift
     const leading = joined.length - joined.trimStart().length;
     const body = joined.trim();
-    const markers = pending.map((p) => {
-        const rawOffset = p.outLineIndex < lineStartOffsets.length
-            ? lineStartOffsets[p.outLineIndex]
+    const offsetOf = (outLineIndex, delta = 0) => {
+        const rawOffset = outLineIndex < lineStartOffsets.length
+            ? lineStartOffsets[outLineIndex]
             : joined.length;
-        const { outLineIndex: _outLineIndex, ...rest } = p;
-        return {
-            ...rest,
-            offset: Math.min(Math.max(rawOffset - leading, 0), body.length),
-        };
+        return Math.min(Math.max(rawOffset + delta - leading, 0), body.length);
+    };
+    const markers = pending.map(({ outLineIndex, ...rest }) => ({
+        ...rest,
+        offset: offsetOf(outLineIndex),
+    }));
+    const fences = pendingFences.map(({ outLineIndex, length, ...rest }) => ({
+        ...rest,
+        offset: offsetOf(outLineIndex),
+        end: offsetOf(outLineIndex, length),
+    }));
+    return { body, markers, fences };
+}
+/**
+ * The markdown of body[start, end), with its container fences balanced: an
+ * opener for every box open at `start` (outermost first) and a closer for
+ * every container still open at `end`. A `:::hide` (or `:::collapse`) the
+ * range starts in is not reopened: the lens author chose that text to show.
+ * A closer whose opener is not in the text is left out, and so is an added
+ * fence that would make a box holding only whitespace. A fence line the range cuts in
+ * two stays plain text.
+ */
+export function articleText({ body, fences }, start, end) {
+    const fenceLine = (index) => body.slice(fences[index].offset, fences[index].end);
+    const close = (stack, opener) => {
+        const at = stack.indexOf(opener);
+        if (at === -1)
+            return false;
+        stack.splice(at, 1);
+        return true;
+    };
+    // Containers open where the range starts, outermost first
+    const before = [];
+    let k = 0;
+    for (; k < fences.length && fences[k].offset < start; k++) {
+        const fence = fences[k];
+        if (fence.end > start)
+            continue;
+        if (fence.kind === "open")
+            before.push(k);
+        else
+            close(before, fence.opener);
+    }
+    // Containers whose opener is in the text, innermost last
+    const open = before.filter((i) => {
+        const fence = fences[i];
+        return fence.kind === "open" && fence.reopens;
     });
-    return { body, markers };
+    const tokens = open.map((i) => ({
+        fence: fenceLine(i).trim(),
+        opens: true,
+        added: true,
+    }));
+    const pushClose = (line, added) => {
+        // Drop the opener of a box with nothing but whitespace in it.
+        let j = tokens.length - 1;
+        while (j >= 0) {
+            const token = tokens[j];
+            if (!("text" in token) || token.text.trim())
+                break;
+            j--;
+        }
+        const prev = tokens[j];
+        if (prev && "fence" in prev && prev.opens && (prev.added || added))
+            tokens.length = j;
+        else
+            tokens.push({ fence: line, opens: false, added });
+    };
+    let cursor = start;
+    // A reopened box starts right at its text, not at the blank lines the
+    // range may begin with.
+    if (open.length > 0) {
+        const stop = Math.min(end, fences[k]?.offset ?? end);
+        while (cursor < stop && /\s/.test(body[cursor]))
+            cursor++;
+    }
+    for (; k < fences.length && fences[k].end <= end; k++) {
+        const fence = fences[k];
+        tokens.push({ text: body.slice(cursor, fence.offset) });
+        // Fences inside the range stay as written
+        if (fence.kind === "open") {
+            tokens.push({ fence: fenceLine(k), opens: true, added: false });
+            open.push(k);
+        }
+        else if (close(open, fence.opener)) {
+            pushClose(fenceLine(k), false);
+        }
+        cursor = body[fence.end] === "\n" ? fence.end + 1 : fence.end;
+    }
+    tokens.push({ text: body.slice(Math.min(cursor, end), end) });
+    for (const index of [...open].reverse()) {
+        const fence = fences[index];
+        if (fence.kind === "open")
+            pushClose(fence.closer, true);
+    }
+    let out = "";
+    let endsWithFence = false;
+    for (const token of tokens) {
+        if ("text" in token) {
+            out += token.text;
+            if (token.text)
+                endsWithFence = false;
+            continue;
+        }
+        if (out && !out.endsWith("\n"))
+            out += "\n";
+        out += token.fence + "\n";
+        endsWithFence = true;
+    }
+    return endsWithFence ? out.slice(0, -1) : out;
 }
 /**
  * Extract content from an article between two anchor texts.
@@ -149,7 +283,14 @@ export function parseArticleBody(article, file = "") {
  * @returns Extracted content or error
  */
 export function extractArticleExcerpt(article, fromAnchor, toAnchor, file) {
-    return extractExcerptFromBody(parseArticleBody(article, file).body, fromAnchor, toAnchor, file);
+    const parsed = parseArticleBody(article, file);
+    const result = extractExcerptFromBody(parsed.body, fromAnchor, toAnchor, file);
+    if (result.content === undefined)
+        return result;
+    return {
+        ...result,
+        content: articleText(parsed, result.startIndex, result.endIndex),
+    };
 }
 /** Anchor extraction plus the to::-on-heading warning. */
 function extractExcerptFromBody(body, fromAnchor, toAnchor, file) {
@@ -322,7 +463,9 @@ function extractAnchored(body, fromAnchor, toAnchor, file) {
  * @param file - Source file path for error reporting
  */
 export function resolveArticleSource(article, excerpts, file) {
-    const { body, markers } = parseArticleBody(article, file);
+    const parsed = parseArticleBody(article, file);
+    const { body, markers, fences } = parsed;
+    const text = (from, to) => articleText(parsed, from, to);
     const extracted = excerpts.map((excerpt) => extractExcerptFromBody(body, excerpt.from, excerpt.to, file));
     // Whole-article embeds (no anchors anywhere in the group) get no collapsed
     // fields — there is nothing elided to show.
@@ -337,7 +480,7 @@ export function resolveArticleSource(article, excerpts, file) {
         }
         const start = excerpt.startIndex;
         const end = excerpt.endIndex;
-        const result = { content: excerpt.content };
+        const result = { content: text(start, end) };
         if (excerpt.warning)
             result.warning = excerpt.warning;
         if (hasAnchors) {
@@ -346,7 +489,7 @@ export function resolveArticleSource(article, excerpts, file) {
             // its range is unknown.
             if (i === 0) {
                 if (start > 0) {
-                    const collapsedBefore = body.slice(0, start).trim();
+                    const collapsedBefore = text(0, start).trim();
                     if (collapsedBefore.length > 0)
                         result.collapsed_before = collapsedBefore;
                 }
@@ -354,16 +497,18 @@ export function resolveArticleSource(article, excerpts, file) {
             else {
                 const prev = extracted[i - 1];
                 if (!prev.error && prev.endIndex <= start) {
-                    const collapsedBefore = body.slice(prev.endIndex, start).trim();
+                    const collapsedBefore = text(prev.endIndex, start).trim();
                     if (collapsedBefore.length > 0)
                         result.collapsed_before = collapsedBefore;
-                    else if (!markers.some((m) => m.offset >= prev.endIndex && m.offset <= start))
+                    else if (!markers.some((m) => m.offset >= prev.endIndex && m.offset <= start) &&
+                        // A fence at `start` opens or closes inside this excerpt
+                        !fences.some((f) => f.offset >= prev.endIndex && f.offset < start))
                         result.continuesPrevious = true;
                 }
             }
             // collapsed_after: only the last excerpt shows the article's tail
             if (i === extracted.length - 1) {
-                const collapsedAfter = body.slice(end).trim();
+                const collapsedAfter = text(end, body.length).trim();
                 if (collapsedAfter.length > 0)
                     result.collapsed_after = collapsedAfter;
             }
@@ -388,7 +533,7 @@ export function resolveArticleSource(article, excerpts, file) {
             const framed = (part) => frames.length > 0 ? { ...part, frames: [...frames] } : part;
             let cursor = start;
             for (const m of inRange) {
-                const prose = body.slice(cursor, m.offset).trim();
+                const prose = text(cursor, m.offset).trim();
                 if (prose.length > 0) {
                     parts.push(framed({ kind: "prose", content: prose }));
                 }
@@ -405,7 +550,7 @@ export function resolveArticleSource(article, excerpts, file) {
                 }
                 cursor = m.offset;
             }
-            const tail = body.slice(cursor, end).trim();
+            const tail = text(cursor, end).trim();
             if (tail.length > 0)
                 parts.push(framed({ kind: "prose", content: tail }));
             // Contiguity: a prose part separated from another prose part only by