@pretextbook/markdown-style-pretext 0.0.1

package/src/data/directives.ts

@@ -0,0 +1,168 @@
+// Curated table of container directives supported by the PreTeXt conversion.
+//
+// Source of truth (mirror, not import):
+//   packages/remark-pretext/src/lib/directive-map.ts  (DIRECTIVE_SPEC_TABLE)
+// Keep in sync with that file; the drift-guard test (directives.drift.spec.ts)
+// asserts every entry here still converts without an "unsupported" warning.
+//
+// A note on the three directive forms:
+//   - CONTAINER directives (`:::name` … `:::`) have a *fixed* vocabulary — the
+//     table below. An unknown container name will not convert, so lint flags it.
+//   - LEAF directives (`::name{…}`) are the PreTeXt Plus *include* syntax; the
+//     converter turns any `::name` into `<plus:name/>`, so no leaf name is ever
+//     "unknown". `LEAF_DIRECTIVES` below is only a convenience completion list.
+//   - TEXT directives (`:name[…]`) have no converter handler yet (they become
+//     `<TODO>` placeholders), so this package neither completes nor lints them.
+
+import type { DirectiveSpec, DirectiveCategory } from "../types";
+
+/** The mirror of `DIRECTIVE_SPEC_TABLE`, minus fields we derive below. */
+type ContainerSeed = {
+  category: DirectiveCategory;
+  requiresStatement: boolean;
+  hasNestedTasks?: boolean;
+  documentation?: string;
+};
+
+const CONTAINER_SEEDS: Record<string, ContainerSeed> = {
+  // theorem-like (body wrapped in <statement>, proof hoisted to a sibling)
+  theorem: { category: "theorem-like", requiresStatement: true },
+  lemma: { category: "theorem-like", requiresStatement: true },
+  corollary: { category: "theorem-like", requiresStatement: true },
+  proposition: { category: "theorem-like", requiresStatement: true },
+  claim: { category: "theorem-like", requiresStatement: true },
+  fact: { category: "theorem-like", requiresStatement: true },
+  conjecture: { category: "theorem-like", requiresStatement: true },
+  axiom: { category: "theorem-like", requiresStatement: true },
+  principle: { category: "theorem-like", requiresStatement: true },
+  hypothesis: { category: "theorem-like", requiresStatement: true },
+  algorithm: { category: "theorem-like", requiresStatement: true },
+
+  // definition-like (also statement-wrapped)
+  definition: { category: "definition-like", requiresStatement: true },
+  notation: { category: "definition-like", requiresStatement: true },
+
+  // remark-like (no statement wrapping)
+  remark: { category: "remark-like", requiresStatement: false },
+  note: { category: "remark-like", requiresStatement: false },
+  observation: { category: "remark-like", requiresStatement: false },
+  warning: { category: "remark-like", requiresStatement: false },
+  insight: { category: "remark-like", requiresStatement: false },
+  assemblage: { category: "remark-like", requiresStatement: false },
+
+  // example-like (exercise/project/task accept nested :::task children)
+  example: { category: "example-like", requiresStatement: false },
+  question: { category: "example-like", requiresStatement: false },
+  problem: { category: "example-like", requiresStatement: false },
+  exercise: {
+    category: "example-like",
+    requiresStatement: true,
+    hasNestedTasks: true,
+  },
+  activity: { category: "example-like", requiresStatement: false },
+  exploration: { category: "example-like", requiresStatement: false },
+  investigation: { category: "example-like", requiresStatement: false },
+  project: {
+    category: "example-like",
+    requiresStatement: true,
+    hasNestedTasks: true,
+  },
+  task: {
+    category: "example-like",
+    requiresStatement: true,
+    hasNestedTasks: true,
+  },
+
+  // proof-like (no statement wrapping)
+  proof: { category: "proof-like", requiresStatement: false },
+  case: { category: "proof-like", requiresStatement: false },
+
+  // solution-like (no statement wrapping)
+  solution: { category: "solution-like", requiresStatement: false },
+  hint: { category: "solution-like", requiresStatement: false },
+  answer: { category: "solution-like", requiresStatement: false },
+};
+
+/**
+ * Exercise-flavored directives whose meaningful children are hint/answer/
+ * solution. Mirrors the LaTeX package's `EXERCISE_LIKE` set for consistency.
+ */
+const EXERCISE_LIKE = new Set([
+  "exercise",
+  "problem",
+  "question",
+  "task",
+  "activity",
+  "exploration",
+  "investigation",
+]);
+
+/** Derive the boosted child directives for a container from its semantics. */
+function childDirectivesFor(name: string, seed: ContainerSeed): string[] {
+  const children: string[] = [];
+  if (seed.hasNestedTasks) children.push("task");
+  if (EXERCISE_LIKE.has(name)) {
+    children.push("hint", "answer", "solution");
+  } else if (
+    seed.category === "theorem-like" ||
+    seed.category === "definition-like" ||
+    seed.category === "axiom-like"
+  ) {
+    children.push("proof");
+  }
+  return children;
+}
+
+function seedToSpec(name: string, seed: ContainerSeed): DirectiveSpec {
+  const children = childDirectivesFor(name, seed);
+  return {
+    name,
+    type: name,
+    category: seed.category,
+    kind: "container",
+    requiresStatement: seed.requiresStatement,
+    hasNestedTasks: seed.hasNestedTasks,
+    childDirectives: children.length > 0 ? children : undefined,
+    documentation: seed.documentation,
+  };
+}
+
+/** All supported container directives (`:::name` … `:::`). */
+export const CONTAINER_DIRECTIVES: DirectiveSpec[] = Object.entries(
+  CONTAINER_SEEDS,
+).map(([name, seed]) => seedToSpec(name, seed));
+
+/**
+ * Convenience completion list for leaf directives (`::name{…}`). These are the
+ * PreTeXt Plus *include* syntax — a reference expanded by a later assembly step
+ * (`::section{ref="ch-intro"}` → `<plus:section ref="ch-intro"/>`). Any name is
+ * valid, so this list is offered as suggestions but never used for validation.
+ */
+export const LEAF_DIRECTIVES: DirectiveSpec[] = [
+  ["part", "Include a modular part."],
+  ["chapter", "Include a modular chapter."],
+  ["section", "Include a modular section."],
+  ["subsection", "Include a modular subsection."],
+  ["subsubsection", "Include a modular subsubsection."],
+  ["image", "Include an image asset by `ref`."],
+  ["listing", "Include a code listing by `ref`."],
+  ["figure", "Include a figure by `ref`."],
+  ["table", "Include a table by `ref`."],
+].map(([name, documentation]) => ({
+  name,
+  type: name,
+  category: "remark-like" as DirectiveCategory,
+  kind: "leaf" as const,
+  requiresStatement: false,
+  documentation,
+}));
+
+/** Lookup from a container directive name to its spec. */
+export const CONTAINER_BY_NAME: ReadonlyMap<string, DirectiveSpec> = new Map(
+  CONTAINER_DIRECTIVES.map((spec) => [spec.name, spec]),
+);
+
+/** True if `name` is a supported container directive. */
+export function isKnownContainerDirective(name: string): boolean {
+  return CONTAINER_BY_NAME.has(name.toLowerCase());
+}

package/src/data/math.ts

@@ -0,0 +1,11 @@
+// Math-mode support is shared with the LaTeX flavor: both flavors accept the
+// same `$…$`, `$$…$$`, `\(…\)`, `\[…\]` delimiters and validate against the
+// same KaTeX list. Re-export from `@pretextbook/latex-style-pretext` so there is
+// exactly one vendored KaTeX support list across the two packages.
+export {
+  KATEX_MACROS,
+  KATEX_ENVIRONMENTS,
+  EXTRA_MATH_MACROS,
+  isKnownMathMacro,
+  isKnownMathEnvironment,
+} from "@pretextbook/latex-style-pretext";

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./types";
+export * from "./data/directives";
+export * from "./data/math";
+export * from "./scan/scan-document";
+export * from "./util/position";
+export * from "./completions/snippets";
+export * from "./completions/get-completions";
+export * from "./lint/get-diagnostics";
+export * from "./language";

package/src/language.ts

@@ -0,0 +1,27 @@
+import type { CompletionItem, Diagnostic } from "vscode-languageserver-types";
+import type { GetCompletionsParams, PretextFlavorLanguage } from "./types";
+import { getMarkdownCompletions } from "./completions/get-completions";
+import { getMarkdownDiagnostics } from "./lint/get-diagnostics";
+
+/** Language id used by VS Code and Monaco for Markdown-style PreTeXt. */
+export const PRETEXT_MARKDOWN_LANGUAGE_ID = "pretext-markdown";
+
+/**
+ * The concrete `PretextFlavorLanguage` for Markdown-style PreTeXt. It implements
+ * the *same* interface as `pretextLatexLanguage`, so both hosts (the VS Code LSP
+ * server and the Monaco editor in pretext-plus-editor) register it alongside the
+ * LaTeX flavor without any adapter changes.
+ *
+ * `getDiagnostics` is async to match the interface (a future AST-based linter
+ * may load the parser lazily); the current scanner-based implementation is
+ * synchronous and resolves immediately.
+ */
+export const pretextMarkdownLanguage: PretextFlavorLanguage = {
+  languageId: PRETEXT_MARKDOWN_LANGUAGE_ID,
+  getCompletions(params: GetCompletionsParams): CompletionItem[] {
+    return getMarkdownCompletions(params);
+  },
+  async getDiagnostics(text: string): Promise<Diagnostic[]> {
+    return getMarkdownDiagnostics(text);
+  },
+};

package/src/lint/get-diagnostics.spec.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import { getMarkdownDiagnostics } from "./get-diagnostics";
+import { DiagnosticSeverity } from "vscode-languageserver-types";
+
+const messages = (text: string) =>
+  getMarkdownDiagnostics(text).map((d) => d.message);
+
+describe("directive fence matching", () => {
+  it("accepts a well-formed document", () => {
+    expect(getMarkdownDiagnostics(":::theorem\nHi\n:::\n")).toEqual([]);
+  });
+
+  it("flags an unclosed container fence", () => {
+    const diags = getMarkdownDiagnostics(":::theorem\nHi\n");
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe(DiagnosticSeverity.Error);
+    expect(diags[0].message).toContain("never closed");
+  });
+
+  it("flags a stray closing fence", () => {
+    const diags = getMarkdownDiagnostics("text\n:::\n");
+    expect(diags[0].severity).toBe(DiagnosticSeverity.Error);
+    expect(diags[0].message).toContain("no matching open");
+  });
+
+  it("accepts nested containers written with flexible equal colons", () => {
+    expect(
+      getMarkdownDiagnostics(":::exercise\n:::task\nx\n:::\n:::\n"),
+    ).toEqual([]);
+  });
+
+  it("accepts explicitly-leveled nesting where each pair's counts match", () => {
+    expect(
+      getMarkdownDiagnostics("::::exercise\n:::task\nx\n:::\n::::\n"),
+    ).toEqual([]);
+  });
+
+  it("flags a closing fence whose colon count does not match the open", () => {
+    const diags = getMarkdownDiagnostics("::::theorem\nHi\n:::\n");
+    const mismatch = diags.find((d) => d.message.includes("does not match"));
+    expect(mismatch?.severity).toBe(DiagnosticSeverity.Error);
+    // The unmatched `:::` leaves the theorem open, so that is flagged too.
+    expect(diags.some((d) => d.message.includes("never closed"))).toBe(true);
+  });
+});
+
+describe("python-style directives", () => {
+  it("accepts a well-formed python-style directive", () => {
+    expect(
+      getMarkdownDiagnostics("Theorem:\n    A statement.\n\nAfter.\n"),
+    ).toEqual([]);
+  });
+
+  it("does not require an explicit close for python directives", () => {
+    // Reaches end of document with the directive open; the dedent-close is
+    // implicit, so this is valid (no "never closed" error).
+    expect(getMarkdownDiagnostics("Theorem:\n    A statement.\n")).toEqual([]);
+  });
+
+  it("does not flag a non-directive `Name:` line", () => {
+    expect(getMarkdownDiagnostics("Summary:\n    indented text\n")).toEqual([]);
+  });
+});
+
+describe("unknown directives", () => {
+  it("warns on an unsupported container directive", () => {
+    const diags = getMarkdownDiagnostics(":::bogus\n:::\n");
+    expect(diags[0].severity).toBe(DiagnosticSeverity.Warning);
+    expect(diags[0].message).toContain("not a supported PreTeXt directive");
+  });
+
+  it("never flags leaf (include) directives, whatever the name", () => {
+    expect(getMarkdownDiagnostics('::anything{ref="x"}\n')).toEqual([]);
+  });
+});
+
+describe("unknown math macros", () => {
+  it("validates math macros against the KaTeX list", () => {
+    expect(getMarkdownDiagnostics("Inline $\\frac{1}{2}$ here.")).toEqual([]);
+    expect(messages("$ \\notamacro $")[0]).toContain("KaTeX");
+  });
+
+  it("ignores $ and macros inside fenced code and comments", () => {
+    expect(getMarkdownDiagnostics("```\n$\\notamacro$\n```\n")).toEqual([]);
+    expect(getMarkdownDiagnostics("<!-- $\\notamacro$ -->\n")).toEqual([]);
+  });
+});

package/src/lint/get-diagnostics.ts

@@ -0,0 +1,102 @@
+import { Diagnostic, DiagnosticSeverity } from "vscode-languageserver-types";
+import { scanDocument } from "../scan/scan-document";
+import { isKnownContainerDirective } from "../data/directives";
+import { isKnownMathMacro } from "../data/math";
+import { rangeFromOffsets } from "../util/position";
+
+const SOURCE = "pretext-markdown";
+
+/**
+ * Parse-level validation for Markdown-style PreTeXt. Reports colon fences whose
+ * open/close counts don't match (or that are unmatched), container directives
+ * the conversion does not support, and math macros KaTeX does not know. Nothing
+ * is reported inside fenced code, HTML comments, or frontmatter (the scanner
+ * already excludes those regions).
+ *
+ * Python-style markers (`Name:` with an indented body) close implicitly by
+ * dedent and only exist for names the converter supports, so they are never a
+ * source of fence-matching or unknown-directive diagnostics.
+ *
+ * There is no "unknown macro" text-mode check: markdown has no loose `\macro`
+ * prose to police, and leaf directives (`::name`) accept any name (they become
+ * `<plus:name/>` includes), so they are never flagged.
+ */
+export function getMarkdownDiagnostics(text: string): Diagnostic[] {
+  const scan = scanDocument(text);
+  const diagnostics: Diagnostic[] = [];
+
+  // 1 & 2. Fence matching (colon counts must match) and unknown-directive
+  // checks. Only colon fences participate; python markers pop implicitly.
+  const stack: { name: string; colons: number; start: number; end: number }[] =
+    [];
+  for (const occ of scan.directives) {
+    if (occ.type === "open") {
+      stack.push({
+        name: occ.name,
+        colons: occ.colons,
+        start: occ.start,
+        end: occ.end,
+      });
+      if (occ.style === "fence" && !isKnownContainerDirective(occ.name)) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Warning,
+          range: rangeFromOffsets(text, occ.start, occ.end),
+          source: SOURCE,
+          message: `":::${occ.name}" is not a supported PreTeXt directive and will not convert.`,
+        });
+      }
+    } else if (occ.type === "close") {
+      const top = stack[stack.length - 1];
+      if (occ.style === "python") {
+        stack.pop();
+      } else if (top && top.colons === occ.colons) {
+        stack.pop();
+      } else if (top) {
+        // A colon fence only pairs when its count matches the innermost open;
+        // the converter drops a mismatched close as literal text, leaving the
+        // directive open (directive-normalizer.ts:122).
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          range: rangeFromOffsets(text, occ.start, occ.end),
+          source: SOURCE,
+          message: `Closing fence "${":".repeat(occ.colons)}" (${occ.colons} colons) does not match the open ":::${top.name}" (${top.colons} colons); an open and its close must use the same number of colons.`,
+        });
+      } else {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          range: rangeFromOffsets(text, occ.start, occ.end),
+          source: SOURCE,
+          message: `Closing "${":".repeat(occ.colons)}" fence has no matching open directive.`,
+        });
+      }
+    }
+  }
+  for (const open of stack) {
+    diagnostics.push({
+      severity: DiagnosticSeverity.Error,
+      range: rangeFromOffsets(text, open.start, open.end),
+      source: SOURCE,
+      message: `":::${open.name}" is never closed with a "${":".repeat(open.colons)}" fence.`,
+    });
+  }
+
+  // 3. Unknown math macros inside math regions.
+  const macroRe = /\\([a-zA-Z]+)/g;
+  for (const region of scan.mathRegions) {
+    const body = text.slice(region.start, region.end);
+    let m: RegExpExecArray | null;
+    while ((m = macroRe.exec(body)) !== null) {
+      const name = m[1];
+      if (isKnownMathMacro(name)) continue;
+      const start = region.start + m.index;
+      diagnostics.push({
+        severity: DiagnosticSeverity.Information,
+        range: rangeFromOffsets(text, start, start + m[0].length),
+        source: SOURCE,
+        message: `\\${name} is not a KaTeX-supported math macro; it may not render.`,
+      });
+    }
+  }
+
+  return diagnostics;
+}

package/src/scan/scan-document.spec.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect } from "vitest";
+import { scanDocument, contextAt } from "./scan-document";
+
+/** Offset of the cursor marker "|" in a fixture, and the text with it removed. */
+function cursor(fixture: string): { text: string; offset: number } {
+  const offset = fixture.indexOf("|");
+  if (offset === -1) throw new Error("fixture must contain a | cursor marker");
+  return { text: fixture.replace("|", ""), offset };
+}
+
+function contextIn(fixture: string) {
+  const { text, offset } = cursor(fixture);
+  return contextAt(scanDocument(text), offset);
+}
+
+describe("directive scanning", () => {
+  it("records container open/close occurrences", () => {
+    const { directives } = scanDocument(":::theorem\nHi\n:::\n");
+    expect(directives.map((d) => [d.name, d.type])).toEqual([
+      ["theorem", "open"],
+      ["", "close"],
+    ]);
+  });
+
+  it("records leaf directives without opening a container", () => {
+    const { directives } = scanDocument('::section{ref="ch-1"}\n');
+    expect(directives).toEqual([
+      expect.objectContaining({ name: "section", type: "leaf", colons: 2 }),
+    ]);
+  });
+
+  it("tracks the open container stack, innermost last", () => {
+    const ctx = contextIn(":::exercise\n:::task\nno|w\n:::\n:::\n");
+    expect(ctx.directiveStack).toEqual(["exercise", "task"]);
+    expect(ctx.currentDirective).toBe("task");
+  });
+
+  it("pops the innermost container on a closing fence", () => {
+    const ctx = contextIn(":::exercise\n:::task\n:::\naf|ter\n:::\n");
+    expect(ctx.directiveStack).toEqual(["exercise"]);
+  });
+
+  it("does not count a container whose open line straddles the cursor", () => {
+    const ctx = contextIn(":::theo|rem\n");
+    expect(ctx.directiveStack).toEqual([]);
+  });
+
+  it("pairs a colon fence only when open/close counts match", () => {
+    // The `:::` cannot close the `::::theorem`, so it stays open at the cursor.
+    const ctx = contextIn("::::theorem\n:::\naf|ter\n");
+    expect(ctx.directiveStack).toEqual(["theorem"]);
+  });
+
+  it("closes a deeper-nested fence with its matching count", () => {
+    const ctx = contextIn("::::exercise\n:::task\n:::\nno|w\n::::\n");
+    expect(ctx.directiveStack).toEqual(["exercise"]);
+  });
+});
+
+describe("python-style indented directives", () => {
+  it("opens a directive from a `Name:` marker with an indented body", () => {
+    const ctx = contextIn("Theorem:\n    Let $x$ be re|al.\n");
+    expect(ctx.currentDirective).toBe("theorem");
+  });
+
+  it("nests by indentation and closes on dedent", () => {
+    const doc =
+      "Theorem:\n    Statement.\n\n    Proof:\n        deep| inside\n\nPlain text.\n";
+    expect(contextIn(doc).directiveStack).toEqual(["theorem", "proof"]);
+  });
+
+  it("closes python directives once content outdents", () => {
+    const doc = "Theorem:\n    Statement.\n\nPlain te|xt.\n";
+    expect(contextIn(doc).directiveStack).toEqual([]);
+  });
+
+  it("ignores a `Name:` line with no indented body", () => {
+    // No deeper body, so this is ordinary prose, not a directive.
+    const ctx = contextIn("Theorem:\nNext li|ne at same indent.\n");
+    expect(ctx.directiveStack).toEqual([]);
+  });
+
+  it("ignores a `Name:` line whose name is not a directive", () => {
+    const ctx = contextIn("Summary:\n    some indented te|xt\n");
+    expect(ctx.directiveStack).toEqual([]);
+  });
+});
+
+describe("math-mode detection", () => {
+  it("is math inside $...$", () => {
+    expect(contextIn("text $x + |y$ more").mode).toBe("math");
+  });
+
+  it("is text outside inline math", () => {
+    expect(contextIn("text $x$ mo|re").mode).toBe("text");
+  });
+
+  it("handles \\(...\\) and \\[...\\] and multi-line $$", () => {
+    expect(contextIn("a \\( x |y \\) b").mode).toBe("math");
+    expect(contextIn("$$\nx = |1\n$$\n").mode).toBe("math");
+  });
+
+  it("treats an escaped dollar as literal, not math", () => {
+    expect(contextIn("costs \\$5 and is fi|ne").mode).toBe("text");
+  });
+});
+
+describe("code, comment, and frontmatter suppression", () => {
+  it("marks offsets inside a fenced code block", () => {
+    const ctx = contextIn("```\n:::theorem still co|de\n```\n");
+    expect(ctx.inCode).toBe(true);
+    // A `:::` inside code must not open a directive.
+    expect(ctx.directiveStack).toEqual([]);
+  });
+
+  it("does not open math from a $ inside fenced code", () => {
+    expect(contextIn("```\nprice $5\n```\nplain te|xt").mode).toBe("text");
+  });
+
+  it("flags offsets inside an HTML comment, including its trailing edge", () => {
+    expect(contextIn("text <!-- a comment wi|th $x$ -->\n").inComment).toBe(
+      true,
+    );
+    expect(
+      contextIn("text <!-- multi\nline com|ment\n--> after").inComment,
+    ).toBe(true);
+  });
+
+  it("marks offsets inside YAML frontmatter", () => {
+    const ctx = contextIn("---\ntitle: My Bo|ok\n---\n# Chapter\n");
+    expect(ctx.inFrontmatter).toBe(true);
+  });
+});
+
+describe("id harvesting", () => {
+  it("harvests ids from directive attributes and headings", () => {
+    const { labels } = scanDocument(
+      ":::theorem{#thm:main}\nHi\n:::\n\n## Intro {#sec:intro}\n",
+    );
+    expect(labels.map((l) => l.name)).toEqual(["thm:main", "sec:intro"]);
+  });
+
+  it("harvests xml:id / label attribute forms and frontmatter", () => {
+    const { labels } = scanDocument(
+      '---\nxmlid: root-id\n---\n::section{ref="x" label=lbl-1}\n',
+    );
+    expect(labels.map((l) => l.name)).toContain("root-id");
+    expect(labels.map((l) => l.name)).toContain("lbl-1");
+  });
+});