fix: code quality hardening — CRLF, error handling, types, tests

Bugs fixed:
- Normalize CRLF line endings at file-read boundary
- Error on diff-step + side-by-side (was silently discarding diff)
- Error on diff-reference + diff-step on same block (was silently
  ignoring diff-step)

Code smells addressed:
- Extract parseFlags() helper (eliminates duplicated flag parsing)
- Consolidate resolveRef() last 2 params into opts bag
- Deduplicate LINE_RANGE_RE (export from extract-lines, import in index)
- Add (?:^|\s) anchoring to REF_REGEX, DIFF_REF_REGEX, DIFF_STEP_REGEX
- Remove unnecessary .* prefix from PRESET_STRIP.markers patterns

Project config:
- Add unified as peerDependency
- Add build + CJS smoke test to CI
- Add TypeScript declarations (index.d.mts)
- Document tab groups in README with tabGroupClass in Options table

Test coverage:
- CRLF fixture + region/line-range tests
- Backslash-escaped spaces in file= paths
- CJS entry point regression test (subprocess-based)
- Focused cleanDiffMeta tests (8 tests for order-sensitive stripping)
- Duplicate region name behavior documented in test

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: patricker

.github/workflows/ci.yml

@@ -26,5 +26,11 @@ jobs:
       - name: Lint
         run: npm run lint
 
+      - name: Build
+        run: npm run build
+
+      - name: Verify CJS bundle
+        run: node -e "const p = require('./index.cjs'); if (typeof p !== 'function') { console.error('CJS export is not a function:', typeof p); process.exit(1); }"
+
       - name: Test
         run: npm test

README.md

@@ -378,6 +378,60 @@ The reader sees complete, copyable code at every step -- with green/red highligh
 | Output | Diff only | Full current code with change annotations |
 | Default format | `unified` (+/- prefixes) | `inline-annotations` (Shiki highlights) |
 
+## Tab groups
+
+Group consecutive code fences into tabs using the `tab` attribute. Each fence is processed independently (reference extraction, strip, transmute, diff — everything works), then consecutive `tab` fences are wrapped in a `tabGroup` AST node.
+
+**Multi-language tabs:**
+
+````md
+```python tab="Python" reference="tests/test_sdk.py#create_user"
+```
+
+```javascript tab="Node.js" reference="tests/test_sdk.js#create_user"
+```
+````
+
+**Same-language version comparison:**
+
+````md
+```python tab="SDK v1" reference="tests/v1.py#create_user"
+```
+
+```python tab="SDK v2" reference="tests/v2.py#create_user"
+```
+````
+
+**Inline code tabs (no reference needed):**
+
+````md
+```bash tab="npm"
+npm install myapp
+```
+
+```bash tab="yarn"
+yarn add myapp
+```
+````
+
+Bare `tab` (no value) derives the label from the language tag: `` ```python tab `` → label "Python".
+
+### Sync key
+
+Use `tab-group="id"` to synchronize tab selection across multiple tab groups on a page (like Docusaurus `groupId` or Starlight `syncKey`). Clicking "Python" in one group switches all groups with the same sync key.
+
+```md
+```python tab="Python" tab-group="lang" reference="tests/install.py#pip"
+```
+
+To split adjacent tab groups without visible content between them, use an HTML comment (`<!-- -->`), which creates an invisible node that breaks the consecutive grouping.
+
+### AST output
+
+The plugin emits `tabGroup` wrapper nodes with `data.hName = 'div'` and `data.hProperties.class = 'code-tabs'` (customizable via `tabGroupClass` option). Each child code node gets `data.tabLabel` and `data.hProperties['data-tab']`.
+
+Without a companion plugin, this renders as a `<div class="code-tabs">` wrapping stacked `<pre><code>` blocks. Framework-specific companion plugins (coming soon) will transform these into native Docusaurus `<Tabs>`, Starlight tabs, etc.
+
 ## Auto-dedent
 
 Extracted regions are automatically dedented. Common leading whitespace is removed so that code nested inside test functions or classes renders flush-left in your docs.
@@ -442,6 +496,7 @@ remarkPlugins: [[codeRegion, { clean: false }]],
 | `regionSeparator` | `string` | `'\n\n'` | String inserted between regions in multi-region concatenation. |
 | `preserveFileMeta` | `boolean` | `false` | Keep `file=` in meta after processing (matches remark-code-import behavior). |
 | `diffFormat` | `string` | `'unified'` | Output format for diff blocks: `'unified'`, `'inline-annotations'`, or `'side-by-side'`. |
+| `tabGroupClass` | `string` | `'code-tabs'` | CSS class for tab group wrapper `<div>`. |
 
 **Exports** (for composing custom configurations):
 

index.d.mts

@@ -0,0 +1,81 @@
+import type { Plugin } from 'unified';
+
+export interface RegionMarker {
+  start: RegExp;
+  end: RegExp;
+}
+
+export interface TransmuteRule {
+  match: RegExp;
+  template: string;
+  argMap?: Record<string, number>;
+}
+
+export interface Options {
+  /** Base directory for resolving reference paths. Defaults to process.cwd(). */
+  rootDir?: string;
+  /** Allow references outside rootDir. Default: false. */
+  allowOutsideRoot?: boolean;
+  /** Region marker pairs. Defaults cover # and // comments. */
+  regionMarkers?: RegionMarker[];
+  /** Patterns to strip. false=disable, undefined=defaults, RegExp[]=custom. */
+  strip?: RegExp[] | false;
+  /** Transmute rules. false/undefined=disabled, array=use rules. */
+  transmute?: TransmuteRule[] | false;
+  /** Cleaning steps. false=disable, undefined=defaults, string[]=custom. */
+  clean?: string[] | false;
+  /** String inserted between concatenated regions. Default: '\n\n'. */
+  regionSeparator?: string;
+  /** Keep file= in meta after processing. Default: false. */
+  preserveFileMeta?: boolean;
+  /** Output format for diff blocks. Default: 'unified'. */
+  diffFormat?: 'unified' | 'inline-annotations' | 'side-by-side';
+  /** CSS class for tab group wrapper div. Default: 'code-tabs'. */
+  tabGroupClass?: string;
+}
+
+declare const remarkCodeRegion: Plugin<[Options?]>;
+export default remarkCodeRegion;
+
+// Preset strip patterns (grouped by language)
+export declare const PRESET_STRIP: {
+  python: RegExp[];
+  rust: RegExp[];
+  java: RegExp[];
+  js: RegExp[];
+  cpp: RegExp[];
+  go: RegExp[];
+  markers: RegExp[];
+};
+
+// Preset transmute rules (grouped by language)
+export declare const PRESET_TRANSMUTE: {
+  python: TransmuteRule[];
+  js: TransmuteRule[];
+  rust: TransmuteRule[];
+  java: TransmuteRule[];
+  go: TransmuteRule[];
+  cpp: TransmuteRule[];
+};
+
+// Preset clean step lists
+export declare const PRESET_CLEAN: {
+  default: string[];
+  compat: string[];
+};
+
+// Preset region markers (grouped by syntax)
+export declare const PRESET_MARKERS: {
+  css: RegionMarker[];
+  html: RegionMarker[];
+  sql: RegionMarker[];
+};
+
+// Default values (unions of all presets)
+export declare const DEFAULT_STRIP_PATTERNS: RegExp[];
+export declare const DEFAULT_TRANSMUTE_RULES: TransmuteRule[];
+export declare const DEFAULT_CLEAN: string[];
+export declare const DEFAULT_REGION_MARKERS: RegionMarker[];
+
+// Language → comment prefix map (70+ entries)
+export declare const COMMENT_PREFIX: Record<string, string>;

index.mjs

@@ -16,7 +16,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { SKIP, visit } from 'unist-util-visit';
 import { formatDiff } from './lib/diff-regions.mjs';
-import { extractLines } from './lib/extract-lines.mjs';
+import { extractLines, LINE_RANGE_RE } from './lib/extract-lines.mjs';
 import { extractRegion } from './lib/extract-region.mjs';
 import {
   DEFAULT_CLEAN,
@@ -27,26 +27,47 @@ import { cleanCode } from './lib/strip-asserts.mjs';
 import { groupTabsInParent, TAB_REGEX } from './lib/tab-groups.mjs';
 
 /** Regex to find reference="..." in code fence meta (not diff-reference). */
-const REF_REGEX = /(?<!-)reference="([^"]+)"/;
+const REF_REGEX = /(?:^|\s)(?<!-)reference="([^"]+)"/;
 
 /** Regex to find file=... (unquoted, backslash-escaped spaces, not diff-file=). */
 const FILE_REGEX = /(?:^|(?<!-)(?<=\s))file=((?:[^\s\\]|\\.)+)/;
 
 /** Regex to find diff-reference="..." in code fence meta. */
-const DIFF_REF_REGEX = /diff-reference="([^"]+)"/;
+const DIFF_REF_REGEX = /(?:^|\s)diff-reference="([^"]+)"/;
 
 /** Regex to find diff-file=... in code fence meta. */
 const DIFF_FILE_REGEX = /(?:^|\s)diff-file=((?:[^\s\\]|\\.)+)/;
 
 /** Regex to find diff-step="..." in code fence meta (tutorial step diffing). */
-const DIFF_STEP_REGEX = /diff-step="([^"]+)"/;
-
-/** Regex to detect line-range fragments like L3, L3-L6, L3- */
-const LINE_RANGE_RE = /^L(\d+)(?:-(?:L?(\d+))?)?$/;
+const DIFF_STEP_REGEX = /(?:^|\s)diff-step="([^"]+)"/;
 
 /** Prefix for rootDir-relative file= paths. */
 const ROOT_DIR_PREFIX = '<rootDir>/';
 
+/**
+ * Parse ?flags from a raw reference value (e.g., "file.py#region?noStrip&format=unified").
+ * @param {string} rawValue
+ * @param {'unified'|'inline-annotations'|'side-by-side'} defaultFormat
+ * @returns {{ flagOverrides: { noStrip: boolean, noTransmute: boolean }, effectiveDiffFormat: string }}
+ */
+function parseFlags(rawValue, defaultFormat) {
+  const hashIndex = rawValue.indexOf('#');
+  const fragStr = hashIndex >= 0 ? rawValue.slice(hashIndex + 1) : null;
+  const qIndex = fragStr ? fragStr.indexOf('?') : -1;
+  const flags = qIndex >= 0 ? fragStr.slice(qIndex + 1).split('&') : [];
+  const formatFlag = flags.find((f) => f.startsWith('format='));
+  return {
+    flagOverrides: {
+      noStrip: flags.includes('noStrip'),
+      noTransmute: flags.includes('noTransmute'),
+    },
+    effectiveDiffFormat: formatFlag
+      ? formatFlag.slice('format='.length)
+      : defaultFormat,
+    formatFlag: formatFlag || null,
+  };
+}
+
 /**
  * @typedef {Object} RegionMarker
  * @property {RegExp} start - Regex matching region start. Group 1 = name.
@@ -111,8 +132,9 @@ export default function remarkCodeRegion(options = {}) {
    * @param {string} securityBase - Resolved rootDir for security checks
    * @param {object} vfile - The vfile object (for fail())
    * @param {string} lang - Code fence language tag
-   * @param {object} flagOverrides - Per-block flag overrides { noStrip, noTransmute }
-   * @param {string|null} [fallbackAbsPath] - Abs path to use when rawValue has no file portion
+   * @param {object} [opts] - Optional parameters.
+   * @param {object} [opts.flagOverrides] - Per-block flag overrides { noStrip, noTransmute }
+   * @param {string|null} [opts.fallbackAbsPath] - Abs path to use when rawValue has no file portion
    * @returns {{ code: string, absPath: string }}
    */
   function resolveRef(
@@ -122,9 +144,9 @@ export default function remarkCodeRegion(options = {}) {
     securityBase,
     vfile,
     lang,
-    flagOverrides,
-    fallbackAbsPath = null,
+    opts = {},
   ) {
+    const { flagOverrides = {}, fallbackAbsPath = null } = opts;
     let raw = rawValue;
 
     // Unescape backslash-spaces in file= values
@@ -188,7 +210,7 @@ export default function remarkCodeRegion(options = {}) {
     // Read the source file
     let content;
     try {
-      content = fs.readFileSync(absPath, 'utf-8');
+      content = fs.readFileSync(absPath, 'utf-8').replace(/\r\n/g, '\n');
     } catch (e) {
       const msg = `remark-code-region: cannot read file '${filePath || raw}' (resolved to '${absPath}'): ${e.message}`;
       if (vfile?.fail) {
@@ -270,6 +292,17 @@ export default function remarkCodeRegion(options = {}) {
       const hasDiff = !!(diffRefMatch || diffFileMatch);
       const hasDiffStep = !!diffStepMatch;
 
+      // Mutual exclusion: can't combine diff-reference/diff-file with diff-step
+      if (hasDiff && hasDiffStep) {
+        const msg =
+          'remark-code-region: diff-reference/diff-file and diff-step cannot be used on the same code block';
+        if (file?.fail) {
+          file.fail(msg);
+          return;
+        }
+        throw new Error(msg);
+      }
+
       // If no primary reference and no diff attribute, skip
       if (!refMatch && !fileMatch) {
         // Error if diff attr present without primary
@@ -298,25 +331,11 @@ export default function remarkCodeRegion(options = {}) {
         primaryResolveDir = file?.dirname || file?.cwd || process.cwd();
       }
 
-      // Parse primary flags for per-block overrides
-      const primaryHashIndex = primaryRaw.indexOf('#');
-      const primaryFragStr =
-        primaryHashIndex >= 0 ? primaryRaw.slice(primaryHashIndex + 1) : null;
-      const primaryQIndex = primaryFragStr ? primaryFragStr.indexOf('?') : -1;
-      const primaryFlags =
-        primaryQIndex >= 0
-          ? primaryFragStr.slice(primaryQIndex + 1).split('&')
-          : [];
-      const flagOverrides = {
-        noStrip: primaryFlags.includes('noStrip'),
-        noTransmute: primaryFlags.includes('noTransmute'),
-      };
-
-      // Parse ?format= override for diffs
-      const formatFlag = primaryFlags.find((f) => f.startsWith('format='));
-      const effectiveDiffFormat = formatFlag
-        ? formatFlag.slice('format='.length)
-        : diffFormat;
+      // Parse per-block flag overrides and format from primary reference
+      const { flagOverrides, effectiveDiffFormat, formatFlag } = parseFlags(
+        primaryRaw,
+        diffFormat,
+      );
 
       // Extract and clean the primary reference
       const primary = resolveRef(
@@ -326,7 +345,7 @@ export default function remarkCodeRegion(options = {}) {
         resolvedBase,
         file,
         node.lang || '',
-        flagOverrides,
+        { flagOverrides },
       );
 
       if (hasDiff) {
@@ -352,8 +371,7 @@ export default function remarkCodeRegion(options = {}) {
           resolvedBase,
           file,
           node.lang || '',
-          flagOverrides,
-          primary.absPath,
+          { flagOverrides, fallbackAbsPath: primary.absPath },
         );
 
         // Format the diff
@@ -415,8 +433,7 @@ export default function remarkCodeRegion(options = {}) {
           resolvedBase,
           file,
           node.lang || '',
-          flagOverrides,
-          primary.absPath,
+          { flagOverrides, fallbackAbsPath: primary.absPath },
         );
 
         // Default to inline-annotations for diff-step (shows full code with highlights)
@@ -427,6 +444,16 @@ export default function remarkCodeRegion(options = {}) {
 
         const result = formatDiff(previousStep.code, primary.code, stepFormat);
 
+        if (result.mode === 'side-by-side') {
+          const msg =
+            'remark-code-region: side-by-side format is not supported with diff-step';
+          if (file?.fail) {
+            file.fail(msg);
+            return;
+          }
+          throw new Error(msg);
+        }
+
         if (result.mode === 'unified') {
           node.value = result.value;
           node.lang = 'diff';

lib/extract-lines.mjs

@@ -8,7 +8,7 @@
  * @throws {Error} If the line specification is out of range or reversed.
  */
 
-const LINE_RANGE_RE = /^L(\d+)(?:-(?:L?(\d+))?)?$/;
+export const LINE_RANGE_RE = /^L(\d+)(?:-(?:L?(\d+))?)?$/;
 
 export function extractLines(content, lineSpec, filePath) {
   const m = lineSpec.match(LINE_RANGE_RE);

lib/patterns.mjs

@@ -80,8 +80,8 @@ export const PRESET_STRIP = {
   ],
   /** Matches lines ending with // test-only or # test-only — works in any language. */
   markers: [
-    /.*\/\/\s*test-only\s*$/, // // test-only
-    /.*#\s*test-only\s*$/, // # test-only
+    /\/\/\s*test-only\s*$/, // // test-only
+    /#\s*test-only\s*$/, // # test-only
   ],
 };
 

package.json

@@ -7,13 +7,15 @@
   "module": "./index.mjs",
   "exports": {
     ".": {
+      "types": "./index.d.mts",
       "require": "./index.cjs",
       "import": "./index.mjs"
     }
   },
   "files": [
     "index.mjs",
     "index.cjs",
+    "index.d.mts",
     "lib/"
   ],
   "scripts": {
@@ -49,6 +51,9 @@
   "bugs": {
     "url": "https://github.com/patricker/remark-code-region/issues"
   },
+  "peerDependencies": {
+    "unified": ">=11.0.0"
+  },
   "dependencies": {
     "diff": "^8.0.4",
     "unist-util-visit": "^5.0.0"