🧮 Improve emphasize-lines to allow for ranges (#2048)

See jupyter-book/jupyter-book#2361

Author: rowanc1

.changeset/thick-geese-sing.md

@@ -0,0 +1,5 @@
+---
+"myst-directives": patch
+---
+
+Enable ranges in emphasize lines (e.g. "5,7-9") for code blocks in addition to comma-separated line numbers.

packages/myst-directives/src/code.spec.ts

@@ -45,6 +45,44 @@ describe('Code block options', () => {
     expect(opts).toEqual({ emphasizeLines: [3, 5] });
     expect(vfile.messages.length).toEqual(0);
   });
+  test.each([
+    ['3', [3]],
+    ['3,5', [3, 5]],
+    ['3-6, 1', [1, 3, 4, 5, 6]],
+    ['1-3,5', [1, 2, 3, 5]],
+    ['2,4-6', [2, 4, 5, 6]],
+    [' 1 - 2 , 4 ', [1, 2, 4]],
+    ['3,5,4', [3, 4, 5]], // Out of order is fine
+    ['3,,5', [3, 5]], // tolerant to extra comma
+    ['3, ', [3]], // tolerant to trailing comma
+    ['7-7', [7]], // valid single range
+    ['3,3,3-3', [3]], // duplicates removed
+    ['1-3,2', [1, 2, 3]], // duplicates removed
+  ])('parses emphasize-lines="%s" into %j', (input, expected) => {
+    const vfile = new VFile();
+    const opts = getCodeBlockOptionsWrap({ 'emphasize-lines': input }, vfile);
+    expect(opts).toEqual({ emphasizeLines: expected });
+    expect(vfile.messages.length).toEqual(0);
+  });
+  test.each([
+    ['abc'],
+    ['one,two'],
+    ['1-'],
+    ['4--5'],
+    ['1-3-5'],
+    ['-2'], // Must be positive
+    ['6-2'], // must be ascending
+    ['5,6-2,7, 2-4', [2, 3, 4, 5, 7]], // Good numbers are still parsed
+  ])(
+    'invalid emphasize-lines="%s" logs warning and returns empty',
+    (input, expected = undefined) => {
+      const vfile = new VFile();
+      const opts = getCodeBlockOptionsWrap({ 'emphasize-lines': input }, vfile);
+      expect(opts).toEqual({ emphasizeLines: expected });
+      expect(vfile.messages.length).toBeGreaterThan(0);
+      expect(vfile.messages[0].message).toMatch(/Invalid emphasize-lines/i);
+    },
+  );
   // See https://github.com/jupyter-book/jupyterlab-myst/issues/174
   test(':lineno-start: 10, :emphasize-lines: 12,13', () => {
     const vfile = new VFile();

packages/myst-directives/src/code.ts

@@ -8,13 +8,52 @@ import type { VFile } from 'vfile';
 import { select } from 'unist-util-select';
 import { addCommonDirectiveOptions, commonDirectiveOptions } from './utils.js';
 
-function parseEmphasizeLines(emphasizeLinesString?: string | undefined): number[] | undefined {
+function parseEmphasizeLines(
+  data: DirectiveData,
+  vfile: VFile,
+  emphasizeLinesString?: string,
+): number[] | undefined {
+  const { node } = data;
   if (!emphasizeLinesString) return undefined;
-  const emphasizeLines = emphasizeLinesString
-    ?.split(',')
-    .map((val) => Number(val.trim()))
-    .filter((val) => Number.isInteger(val));
-  return emphasizeLines;
+
+  const result = new Set<number>();
+
+  for (const part of emphasizeLinesString.split(',')) {
+    const trimmed = part.trim();
+
+    const rangeMatch = trimmed.match(/^(\d+)\s*-\s*(\d+)$/);
+    if (rangeMatch) {
+      const start = Number(rangeMatch[1]);
+      const end = Number(rangeMatch[2]);
+      if (start <= end) {
+        for (let i = start; i <= end; i++) {
+          result.add(i);
+        }
+        continue;
+      } else {
+        fileWarn(vfile, `Invalid emphasize-lines range "${trimmed}" (start > end)`, {
+          node,
+          source: 'code-block:options',
+          ruleId: RuleId.directiveOptionsCorrect,
+        });
+        continue;
+      }
+    }
+
+    if (/^\d+$/.test(trimmed)) {
+      result.add(Number(trimmed));
+    } else if (trimmed !== '') {
+      fileWarn(vfile, `Invalid emphasize-lines value "${trimmed}"`, {
+        node,
+        source: 'code-block:options',
+        ruleId: RuleId.directiveOptionsCorrect,
+      });
+    }
+  }
+
+  if (result.size === 0) return undefined;
+
+  return Array.from(result).sort((a, b) => a - b);
 }
 
 /** This function parses both sphinx and RST code-block options */
@@ -31,7 +70,11 @@ export function getCodeBlockOptions(
       ruleId: RuleId.directiveOptionsCorrect,
     });
   }
-  const emphasizeLines = parseEmphasizeLines(options?.['emphasize-lines'] as string | undefined);
+  const emphasizeLines = parseEmphasizeLines(
+    data,
+    vfile,
+    options?.['emphasize-lines'] as string | undefined,
+  );
   const numberLines = options?.['number-lines'] as number | undefined;
   // Only include this in mdast if it is `true`
   const showLineNumbers =
@@ -78,7 +121,7 @@ export const CODE_DIRECTIVE_OPTIONS: DirectiveSpec['options'] = {
   },
   'emphasize-lines': {
     type: String,
-    doc: 'Emphasize particular lines (comma-separated numbers), e.g. "3,5"',
+    doc: 'Emphasize particular lines (comma-separated numbers which can include ranges), e.g. "3,5,7-9"',
   },
   filename: {
     type: String,