@pretextbook/markdown-style-pretext 0.0.1

package/README.md

@@ -0,0 +1,38 @@
+# @pretextbook/markdown-style-pretext
+
+Editor intelligence for **Markdown-style PreTeXt** — CommonMark + GFM plus
+[remark-directive](https://github.com/remarkjs/remark-directive) extensions that convert to
+PreTeXt via [`@pretextbook/remark-pretext`](../remark-pretext).
+
+This package implements the **same** `PretextFlavorLanguage` interface as
+[`@pretextbook/latex-style-pretext`](../latex-style-pretext), so the VS Code LSP server and the
+Monaco editor in `pretext-plus-editor` register it alongside the LaTeX flavor with no adapter
+changes. It returns LSP-shaped values (`vscode-languageserver-types`) and ships raw TypeScript
+with no build step, following the `@pretextbook/completions` precedent.
+
+## What's here
+
+| Module         | Purpose                                                                                               |
+| -------------- | ----------------------------------------------------------------------------------------------------- |
+| `data/`        | Curated table of container directives (mirrors the converter); math re-exported from the LaTeX flavor |
+| `scan/`        | Lightweight linear scanner (math regions, directive stack, fenced code, comments, frontmatter, ids)   |
+| `completions/` | Completion engine (container/leaf directives, cross-references, KaTeX math)                           |
+| `lint/`        | Diagnostics engine (unmatched fences, unknown directives, unknown math macros)                        |
+
+## The directive forms
+
+- **Container fence** (`:::name` … `:::`) — the workhorse; a **fixed** vocabulary (the curated
+  table), so an unknown name is flagged by lint. A fence's open and close must use the **same
+  number of colons** to pair (mirrors `directive-normalizer.ts`); a mismatched close is an error.
+- **Python-style** (`Name:` with an indented body) — opens a directive whose body is the
+  deeper-indented block and closes implicitly on dedent (mirrors `indentation-normalizer.ts`).
+  This dialect disables indented code blocks, so indentation is always directive structure.
+  Recognized only for supported directive names, so it needs no unknown-directive lint.
+- **Leaf** (`::name{…}`) — the PreTeXt Plus **include** syntax; any name becomes `<plus:name/>`,
+  so leaf names are offered as completions but never validated.
+- **Text** (`:name[…]`) — inline; the converter has no handler yet (they become `<TODO>`
+  placeholders), so this flavor neither completes nor lints them.
+
+A drift-guard test (`data/directives.drift.spec.ts`) runs every curated container directive
+through `@pretextbook/remark-pretext` and asserts it still converts without an "unsupported"
+warning, keeping the table honest against the in-repo converter.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pretextbook/markdown-style-pretext",
+  "version": "0.0.1",
+  "description": "Editor intelligence (completions + validation) for Markdown-style PreTeXt documents",
+  "author": "Oscar Levin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PreTeXtBook/pretext-tools.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PreTeXtBook/pretext-tools/issues"
+  },
+  "homepage": "https://github.com/PreTeXtBook/pretext-tools/tree/main/packages/markdown-style-pretext",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/**/*",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --build tsconfig.lib.json",
+    "typecheck": "tsc --build --emitDeclarationOnly",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@pretextbook/latex-style-pretext": "^0.0.1",
+    "vscode-languageserver-types": "^3.17.5"
+  },
+  "devDependencies": {
+    "@pretextbook/remark-pretext": "^0.0.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/completions/get-completions.spec.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect } from "vitest";
+import { getMarkdownCompletions } from "./get-completions";
+import type { CompletionItem } from "vscode-languageserver-types";
+
+/** Run completions at the "|" marker in a fixture. */
+function complete(fixture: string): CompletionItem[] {
+  const offset = fixture.indexOf("|");
+  if (offset === -1) throw new Error("fixture needs a | cursor marker");
+  return getMarkdownCompletions({ text: fixture.replace("|", ""), offset });
+}
+
+const labels = (items: CompletionItem[]) => items.map((i) => i.label);
+const byLabel = (items: CompletionItem[], label: string) =>
+  items.find((i) => i.label === label);
+
+describe("container directive completions", () => {
+  it("offers container directives after `:::`", () => {
+    expect(labels(complete(":::theo|"))).toContain("theorem");
+  });
+
+  it("expands to a full :::name … ::: skeleton", () => {
+    const item = byLabel(complete(":::theo|"), "theorem");
+    expect(item?.textEdit?.newText).toBe("theorem\n\t$0\n:::");
+  });
+
+  it("seeds a nested :::task for task-bearing directives", () => {
+    const item = byLabel(complete(":::exerc|"), "exercise");
+    expect(item?.textEdit?.newText).toContain(":::task");
+  });
+
+  it("boosts child directives of the enclosing container", () => {
+    const items = complete(":::theorem\ntext\n:::pro|\n:::\n");
+    const proof = byLabel(items, "proof");
+    expect(proof?.sortText?.startsWith("0")).toBe(true);
+  });
+
+  it("filters by the typed prefix", () => {
+    const items = complete(":::lem|");
+    expect(labels(items)).toContain("lemma");
+    expect(labels(items)).not.toContain("theorem");
+  });
+});
+
+describe("python-style directive completions", () => {
+  it("completes a bare line-start word into a `Name:` marker", () => {
+    const item = byLabel(complete("Theo|"), "theorem:");
+    expect(item?.textEdit?.newText).toBe("theorem:\n\t$0");
+  });
+
+  it("is case-insensitive and offers indented directives", () => {
+    expect(labels(complete("exerc|"))).toContain("exercise:");
+    const item = byLabel(complete("exerc|"), "exercise:");
+    expect(item?.textEdit?.newText).toContain("task:");
+  });
+
+  it("boosts child directives inside a python-style parent body", () => {
+    const items = complete("Theorem:\n    Statement.\n\n    Proo|\n");
+    const proof = byLabel(items, "proof:");
+    expect(proof?.sortText?.startsWith("0")).toBe(true);
+  });
+
+  it("stays quiet for prose that is not a directive prefix", () => {
+    // "Let" prefixes no directive name, so no popup appears mid-sentence.
+    expect(complete("Let|")).toEqual([]);
+  });
+});
+
+describe("leaf directive completions", () => {
+  it("offers include directives after `::`", () => {
+    const items = complete("::sec|");
+    const section = byLabel(items, "section");
+    expect(section?.textEdit?.newText).toBe('section{ref="$1"}');
+  });
+
+  it("does not offer container directives after only `::`", () => {
+    // `proof` is a container directive; it must not appear in leaf context.
+    expect(labels(complete("::pro|"))).not.toContain("proof");
+  });
+});
+
+describe("math completions", () => {
+  it("switches to KaTeX macros inside math mode", () => {
+    const items = complete("$ x = \\fra| $");
+    expect(labels(items)).toContain("frac");
+    // Directive names must not leak into math completions.
+    expect(labels(items)).not.toContain("theorem");
+  });
+});
+
+describe("cross-reference completions", () => {
+  it("completes `](#…` against harvested ids", () => {
+    const items = complete(":::theorem{#thm:main}\nHi\n:::\n\nSee [it](#thm|");
+    expect(labels(items)).toContain("thm:main");
+  });
+});
+
+describe("suppression", () => {
+  it("suppresses completions inside fenced code", () => {
+    expect(complete("```\n:::theo|\n```\n")).toEqual([]);
+  });
+
+  it("suppresses completions inside HTML comments", () => {
+    expect(complete("<!-- :::theo| -->")).toEqual([]);
+  });
+
+  it("suppresses completions inside frontmatter", () => {
+    expect(complete("---\ndivi|\n---\n")).toEqual([]);
+  });
+});

package/src/completions/get-completions.ts

@@ -0,0 +1,283 @@
+import {
+  CompletionItem,
+  CompletionItemKind,
+  InsertTextFormat,
+  MarkupKind,
+} from "vscode-languageserver-types";
+import type { GetCompletionsParams } from "../types";
+import { scanDocument, contextAt } from "../scan/scan-document";
+import { CONTAINER_DIRECTIVES, LEAF_DIRECTIVES } from "../data/directives";
+import { KATEX_MACROS, EXTRA_MATH_MACROS } from "../data/math";
+import { rangeFromOffsets } from "../util/position";
+import {
+  containerInsertText,
+  leafInsertText,
+  pythonInsertText,
+} from "./snippets";
+
+// A container fence line up to the cursor: leading space, `:::`+, optional name.
+const CONTAINER_CONTEXT_RE = /^[ \t]*:{3,}[ \t]*([A-Za-z][\w-]*)?$/;
+// A leaf directive line up to the cursor: exactly two colons, optional name.
+const LEAF_CONTEXT_RE = /^[ \t]*::(?!:)([A-Za-z][\w-]*)?$/;
+// A python-style marker being typed: a bare word at the start of the line.
+const PYTHON_CONTEXT_RE = /^[ \t]*([A-Za-z][A-Za-z0-9_-]*)$/;
+// A markdown cross-reference link target: `](#id`.
+const XREF_CONTEXT_RE = /\]\(#([\w:.-]*)$/;
+// A math macro being typed: `\name`.
+const MATH_MACRO_RE = /\\([A-Za-z]*)$/;
+
+interface CursorEdit {
+  start: number;
+  end: number;
+}
+
+/**
+ * Main entry point: given the document text and a cursor offset, return the
+ * completions appropriate to the cursor's syntactic context.
+ */
+export function getMarkdownCompletions(
+  params: GetCompletionsParams,
+): CompletionItem[] {
+  const { text, offset } = params;
+  const scan = scanDocument(text);
+  const ctx = contextAt(scan, offset);
+
+  // No completions inside fenced code, HTML comments, or YAML frontmatter.
+  if (ctx.inCode || ctx.inComment || ctx.inFrontmatter) return [];
+
+  const before = text.slice(0, offset);
+  const lineStart = before.lastIndexOf("\n") + 1;
+  const currentLine = before.slice(lineStart);
+
+  // `:::` at the start of a line — container directive names.
+  const container = CONTAINER_CONTEXT_RE.exec(currentLine);
+  if (container && ctx.mode !== "math") {
+    const prefix = container[1] ?? "";
+    const edit: CursorEdit = { start: offset - prefix.length, end: offset };
+    return containerItems(text, edit, prefix, ctx.currentDirective);
+  }
+
+  // `::` at the start of a line — leaf (include) directive names.
+  const leaf = LEAF_CONTEXT_RE.exec(currentLine);
+  if (leaf && ctx.mode !== "math") {
+    const prefix = leaf[1] ?? "";
+    const edit: CursorEdit = { start: offset - prefix.length, end: offset };
+    return leafItems(text, edit, prefix);
+  }
+
+  // A bare word at the start of a line — python-style directive markers. Only
+  // words that prefix a real directive name produce items, so ordinary prose
+  // (which almost never begins with a directive name) stays quiet.
+  const python = PYTHON_CONTEXT_RE.exec(currentLine);
+  if (python && ctx.mode !== "math") {
+    const prefix = python[1];
+    const edit: CursorEdit = { start: offset - prefix.length, end: offset };
+    const items = pythonItems(text, edit, prefix, ctx.currentDirective);
+    if (items.length > 0) return items;
+  }
+
+  // `](#…` — cross-reference against harvested ids.
+  const xref = XREF_CONTEXT_RE.exec(before);
+  if (xref) {
+    const prefix = xref[1];
+    const closer = text[offset] === ")" ? offset + 1 : offset;
+    const edit: CursorEdit = { start: offset - prefix.length, end: closer };
+    return xrefItems(text, edit, scan.labels);
+  }
+
+  // `\macro` inside math — KaTeX macros.
+  if (ctx.mode === "math") {
+    const macro = MATH_MACRO_RE.exec(before);
+    if (macro) {
+      const prefix = macro[1];
+      const edit: CursorEdit = { start: offset - prefix.length, end: offset };
+      return mathMacroItems(text, edit, prefix);
+    }
+  }
+
+  return [];
+}
+
+// --- context-specific item builders ---------------------------------------
+
+function containerItems(
+  text: string,
+  edit: CursorEdit,
+  prefix: string,
+  currentDirective: string | undefined,
+): CompletionItem[] {
+  const boosted = new Set(
+    (currentDirective &&
+      CONTAINER_DIRECTIVES.find((d) => d.name === currentDirective)
+        ?.childDirectives) ||
+      [],
+  );
+
+  const items: CompletionItem[] = [];
+  for (const spec of CONTAINER_DIRECTIVES) {
+    if (prefix && !spec.name.startsWith(prefix)) continue;
+    const detailBits: string[] = [spec.category];
+    if (spec.requiresStatement) detailBits.push("statement");
+    const boost = boosted.has(spec.name);
+    items.push(
+      makeItem({
+        text,
+        edit,
+        label: spec.name,
+        kind: CompletionItemKind.Class,
+        detail: `directive · ${detailBits.join(", ")}`,
+        documentation: spec.documentation,
+        insert: containerInsertText(spec),
+        // Boosted children sort first, then everything alphabetically.
+        sortText: `${boost ? "0" : "1"}${spec.name}`,
+      }),
+    );
+  }
+  return items;
+}
+
+function pythonItems(
+  text: string,
+  edit: CursorEdit,
+  prefix: string,
+  currentDirective: string | undefined,
+): CompletionItem[] {
+  // Case-insensitive: authors write `Theorem:`, the converter lowercases it.
+  const lower = prefix.toLowerCase();
+  const boosted = new Set(
+    (currentDirective &&
+      CONTAINER_DIRECTIVES.find((d) => d.name === currentDirective)
+        ?.childDirectives) ||
+      [],
+  );
+
+  const items: CompletionItem[] = [];
+  for (const spec of CONTAINER_DIRECTIVES) {
+    if (!spec.name.startsWith(lower)) continue;
+    const boost = boosted.has(spec.name);
+    items.push(
+      makeItem({
+        text,
+        edit,
+        label: `${spec.name}:`,
+        kind: CompletionItemKind.Class,
+        detail: `directive (indented) · ${spec.category}`,
+        documentation: spec.documentation,
+        insert: pythonInsertText(spec),
+        sortText: `${boost ? "0" : "1"}${spec.name}`,
+      }),
+    );
+  }
+  return items;
+}
+
+function leafItems(
+  text: string,
+  edit: CursorEdit,
+  prefix: string,
+): CompletionItem[] {
+  const items: CompletionItem[] = [];
+  for (const spec of LEAF_DIRECTIVES) {
+    if (prefix && !spec.name.startsWith(prefix)) continue;
+    items.push(
+      makeItem({
+        text,
+        edit,
+        label: spec.name,
+        kind: CompletionItemKind.Module,
+        detail: "include · plus:" + spec.name,
+        documentation: spec.documentation,
+        insert: leafInsertText(spec),
+      }),
+    );
+  }
+  return items;
+}
+
+function xrefItems(
+  text: string,
+  edit: CursorEdit,
+  labels: { name: string }[],
+): CompletionItem[] {
+  const seen = new Set<string>();
+  const items: CompletionItem[] = [];
+  for (const { name } of labels) {
+    if (seen.has(name)) continue;
+    seen.add(name);
+    items.push(
+      makeItem({
+        text,
+        edit,
+        label: name,
+        kind: CompletionItemKind.Reference,
+        detail: "cross-reference target",
+        insert: name,
+        plainText: true,
+      }),
+    );
+  }
+  return items;
+}
+
+function mathMacroItems(
+  text: string,
+  edit: CursorEdit,
+  prefix: string,
+): CompletionItem[] {
+  const items: CompletionItem[] = [];
+  const push = (name: string, detail: string) => {
+    if (prefix && !name.startsWith(prefix)) return;
+    // KaTeX's list includes single-symbol control words (e.g. `\,`); only offer
+    // letter-named macros through the `\word` completion path.
+    if (!/^[a-zA-Z]/.test(name)) return;
+    items.push(
+      makeItem({
+        text,
+        edit,
+        label: name,
+        kind: CompletionItemKind.Function,
+        detail,
+        insert: name,
+        plainText: true,
+      }),
+    );
+  };
+  for (const name of KATEX_MACROS) push(name, "math macro (KaTeX)");
+  for (const name of EXTRA_MATH_MACROS) push(name, "math macro");
+  return items;
+}
+
+// --- item construction -----------------------------------------------------
+
+function makeItem(args: {
+  text: string;
+  edit: CursorEdit;
+  label: string;
+  kind: CompletionItemKind;
+  detail?: string;
+  documentation?: string;
+  insert: string;
+  sortText?: string;
+  plainText?: boolean;
+}): CompletionItem {
+  const item: CompletionItem = {
+    label: args.label,
+    kind: args.kind,
+    insertTextFormat: args.plainText
+      ? InsertTextFormat.PlainText
+      : InsertTextFormat.Snippet,
+    textEdit: {
+      range: rangeFromOffsets(args.text, args.edit.start, args.edit.end),
+      newText: args.insert,
+    },
+  };
+  if (args.detail) item.detail = args.detail;
+  if (args.sortText) item.sortText = args.sortText;
+  if (args.documentation) {
+    item.documentation = {
+      kind: MarkupKind.Markdown,
+      value: args.documentation,
+    };
+  }
+  return item;
+}

package/src/completions/snippets.ts

@@ -0,0 +1,47 @@
+import type { DirectiveSpec } from "../types";
+
+/**
+ * The text inserted when completing a container directive, assuming the caller
+ * has already typed the opening `:::` (the completion range covers the partial
+ * name after it). Produces the name line, a body tab stop, and the closing
+ * `:::` fence — the framing is always supplied here so an open can never be
+ * generated without its matching close.
+ *
+ * A spec may override the body via `snippet` (body only). Directives with
+ * nested tasks seed a first `:::task` child so the structure is discoverable.
+ */
+export function containerInsertText(spec: DirectiveSpec): string {
+  if (spec.snippet) return `${spec.name}\n${spec.snippet}\n:::`;
+  if (spec.hasNestedTasks) {
+    return `${spec.name}\n:::task\n\t$0\n:::\n:::`;
+  }
+  return `${spec.name}\n\t$0\n:::`;
+}
+
+/** The bare closing fence, offered when a container directive is open. */
+export function closeInsertText(): string {
+  return ":::";
+}
+
+/**
+ * The text inserted when completing a python-style directive, assuming the
+ * caller has typed a bare line-start word (the completion range covers it).
+ * Produces `Name:` and an indented body tab stop; the editor re-indents the
+ * body relative to the marker line, so a single `\t` nests one level deeper.
+ * Task-bearing directives seed a nested `task:` child.
+ */
+export function pythonInsertText(spec: DirectiveSpec): string {
+  if (spec.hasNestedTasks) {
+    return `${spec.name}:\n\ttask:\n\t\t$0`;
+  }
+  return `${spec.name}:\n\t$0`;
+}
+
+/**
+ * The text inserted when completing a leaf directive, assuming the caller has
+ * already typed the opening `::`. Leaf directives are PreTeXt Plus includes, so
+ * they reference a target by `ref`.
+ */
+export function leafInsertText(spec: DirectiveSpec): string {
+  return `${spec.name}{ref="$1"}`;
+}

package/src/data/data.spec.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest";
+import {
+  CONTAINER_DIRECTIVES,
+  CONTAINER_BY_NAME,
+  LEAF_DIRECTIVES,
+  isKnownContainerDirective,
+} from "./directives";
+import { isKnownMathMacro, isKnownMathEnvironment } from "./math";
+
+describe("container directive table", () => {
+  it("resolves canonical directive names", () => {
+    expect(isKnownContainerDirective("theorem")).toBe(true);
+    expect(isKnownContainerDirective("bogus")).toBe(false);
+  });
+
+  it("marks theorem/definition-like directives as requiring a statement", () => {
+    expect(CONTAINER_BY_NAME.get("theorem")?.requiresStatement).toBe(true);
+    expect(CONTAINER_BY_NAME.get("definition")?.requiresStatement).toBe(true);
+    expect(CONTAINER_BY_NAME.get("remark")?.requiresStatement).toBe(false);
+  });
+
+  it("offers proof inside theorems and hint/answer/solution inside exercises", () => {
+    expect(CONTAINER_BY_NAME.get("theorem")?.childDirectives).toContain(
+      "proof",
+    );
+    expect(CONTAINER_BY_NAME.get("exercise")?.childDirectives).toEqual([
+      "task",
+      "hint",
+      "answer",
+      "solution",
+    ]);
+  });
+
+  it("flags exercise/project/task as accepting nested tasks", () => {
+    expect(CONTAINER_BY_NAME.get("exercise")?.hasNestedTasks).toBe(true);
+    expect(CONTAINER_BY_NAME.get("project")?.hasNestedTasks).toBe(true);
+    expect(CONTAINER_BY_NAME.get("theorem")?.hasNestedTasks).toBeUndefined();
+  });
+
+  it("has no duplicate directive names", () => {
+    const seen = new Set<string>();
+    for (const spec of CONTAINER_DIRECTIVES) {
+      expect(seen.has(spec.name), `duplicate: ${spec.name}`).toBe(false);
+      seen.add(spec.name);
+    }
+  });
+});
+
+describe("leaf (include) directives", () => {
+  it("lists division and asset includes but never validates them", () => {
+    const names = LEAF_DIRECTIVES.map((d) => d.name);
+    expect(names).toContain("section");
+    expect(names).toContain("image");
+    // Leaf names are includes: they are not container directives.
+    expect(isKnownContainerDirective("image")).toBe(false);
+  });
+});
+
+describe("shared math support", () => {
+  it("recognizes KaTeX macros and environments via the LaTeX package", () => {
+    expect(isKnownMathMacro("frac")).toBe(true);
+    expect(isKnownMathMacro("systeme")).toBe(true);
+    expect(isKnownMathEnvironment("align")).toBe(true);
+  });
+});

package/src/data/directives.drift.spec.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+import { markdownToPretext } from "@pretextbook/remark-pretext";
+import { CONTAINER_DIRECTIVES } from "./directives";
+
+// Drift-guard: every curated container directive must still be recognized by
+// the real converter. If someone renames or removes a directive in
+// `@pretextbook/remark-pretext`, converting our curated name produces an
+// `unknown directive` TODO placeholder, and this test fails — pointing at the
+// exact entry to reconcile.
+
+describe("curated directives match the converter", () => {
+  it.each(CONTAINER_DIRECTIVES.map((d) => d.name))(
+    "%s converts without an unsupported warning",
+    (name) => {
+      const xml = markdownToPretext(`:::${name}\nSome content.\n:::\n`);
+      expect(xml).not.toContain(`unknown directive "${name}"`);
+      expect(xml).not.toContain("unknown-directive");
+    },
+  );
+});