@veluai/velu 0.1.11 → 0.1.13

package/src/lib/extract-mdx-error.js

@@ -0,0 +1,170 @@
+// Normalize a thrown error — from a Vite/MDX transform, an SSR render, or a
+// React error boundary — into the shared `issue` shape (see ./issues.js).
+//
+// Isomorphic: no Node `path` import (path handling is string-based) so the
+// browser ErrorBoundary can reuse it. The single hard rule is PATH SAFETY:
+// never surface an absolute path that isn't under the user's project — those
+// are Velu/Vite internals and must be stripped.
+import { makeIssue, suggestComponent } from './issues.js';
+
+// Unwrap a few layers of `err.cause` when the outer message is generic.
+function unwrap(err) {
+  let e = err;
+  let depth = 0;
+  while (e && e.cause && depth < 3) {
+    // Stop if the current layer already carries useful location info.
+    if (e.loc || e.line || /`[^`]+` to be defined/.test(e.message || '')) break;
+    e = e.cause;
+    depth += 1;
+  }
+  return e || err;
+}
+
+const toPosix = (p) => String(p).replace(/\\/g, '/');
+
+// Make an absolute path project-relative; return null for anything that isn't
+// inside the project (i.e. our internals — never shown).
+function rel(rawPath, projectDir) {
+  if (!rawPath) return null;
+  let p = toPosix(rawPath).replace(/[?#].*$/, ''); // drop ?query / #hash
+  const root = projectDir ? toPosix(projectDir).replace(/\/+$/, '') : '';
+  if (root && p.toLowerCase().startsWith(root.toLowerCase())) {
+    return p.slice(root.length).replace(/^\/+/, '');
+  }
+  // Already-relative, project-owned path (no drive letter, no node_modules).
+  if (!/^([a-zA-Z]:\/|\/)/.test(p) && !/node_modules/.test(p)) return p;
+  return null; // absolute and outside the project → hide it
+}
+
+// Strip any absolute path (and node_modules refs) from a message so internals
+// never leak; collapse them to "…".
+function cleanMessage(msg) {
+  if (!msg) return '';
+  return String(msg)
+    .replace(/([a-zA-Z]:\\|\/)[^\s'"()]+/g, (m) => (/node_modules|[\\/]vite[\\/]|@veluai|velu-cli|velu-ui/.test(m) ? '…' : m))
+    .trim();
+}
+
+// Pull a "(line:col)" / "(line:col-line:col)" position out of a message tail.
+// MDX/vfile errors often carry the location only in the message string, with
+// err.line/err.loc left undefined.
+function parseLocFromMessage(msg) {
+  const m = /\((\d+):(\d+)(?:-\d+:\d+)?\)\s*$/.exec(String(msg || ''));
+  return m ? { line: Number(m[1]), column: Number(m[2]) } : null;
+}
+
+// Drop a trailing "(line:col-…)" from a message once we've surfaced it as a
+// separate location, so it isn't shown twice.
+function stripLocSuffix(msg) {
+  return String(msg || '').replace(/\s*\(\d+:\d+(?:-\d+:\d+)?\)\s*$/, '').trim();
+}
+
+// Phrases that mark a genuine MDX *parse* error (vs a runtime throw).
+const MDX_SYNTAX_RE =
+  /closing tag|unexpected closing|could not parse (?:expression|import|export)|unexpected character|unexpected end of|expected a closing|expected the closing|unexpected `|in expression|misnested|before name/i;
+
+// Keep a code frame only when it clearly belongs to a project file; otherwise
+// drop it (an internal frame would leak paths and confuse the author).
+function safeFrame(frame, fileIsProjectOwned) {
+  if (!frame || !fileIsProjectOwned) return null;
+  const text = String(frame);
+  if (/node_modules|[\\/]vite[\\/]|@veluai[\\/]/.test(text)) return null;
+  return text;
+}
+
+export function extractMdxError(rawErr, opts = {}) {
+  const { projectDir = '', knownComponents = [], file: fileHint = null } = opts;
+
+  // A component (runtime) or the compile-time prop check attaches a ready-made
+  // issue. Trust it directly — it already carries plain-language wording, a
+  // suggestion, and (from the compile-time check) a file:line. Walk the cause
+  // chain since Vite/rollup may re-wrap the thrown error.
+  let tagged = null;
+  for (let e = rawErr, depth = 0; e && depth < 6; e = e.cause, depth += 1) {
+    if (e.veluIssue) {
+      tagged = e.veluIssue;
+      break;
+    }
+  }
+  if (tagged) return makeIssue({ ...tagged, file: tagged.file || fileHint });
+
+  const err = unwrap(rawErr) || {};
+  const message = err.message || String(rawErr || '');
+
+  // 1) Unknown component (MDX render: `_missingMdxReference`). The message
+  // tail carries the spot: "...referenced in your code at `7:1-7:54` in
+  // `<abs path>`" — pull the line/column + file out so the author knows
+  // exactly where to look (path relative-ized for safety).
+  const missing = /Expected component `([^`]+)` to be defined/.exec(message);
+  if (missing) {
+    const name = missing[1];
+    const at = /referenced in your code at `(\d+):(\d+)/.exec(message);
+    const inFile = /\bin `([^`]+)`/.exec(message);
+    const relFile = inFile ? rel(inFile[1], projectDir) : null;
+    return makeIssue({
+      category: 'unknown-component',
+      file: relFile || fileHint,
+      line: at ? Number(at[1]) : null,
+      column: at ? Number(at[2]) : null,
+      title: `<${name}> is not a built-in component`,
+      detail: '',
+      hint: 'Components are built in — check the spelling and capitalization (you don’t import them).',
+      suggestion: suggestComponent(name, knownComponents),
+    });
+  }
+
+  // 2) Compile error carrying a source location (Vite plugin / MDX / vfile).
+  // The location may be on err.loc, on err.line/column, or only inside the
+  // message text — try all three.
+  const loc =
+    err.loc ||
+    (err.line != null ? { line: err.line, column: err.column, file: err.file } : null) ||
+    parseLocFromMessage(err.reason || message);
+  const rawFile = err.id || (loc && loc.file) || err.file || null;
+  const file = rel(rawFile, projectDir) || fileHint;
+  const fileIsProjectOwned = Boolean(file) && rel(rawFile, projectDir) != null;
+  const frame = safeFrame(err.frame, fileIsProjectOwned || Boolean(fileHint));
+  const detail = cleanMessage(stripLocSuffix(err.reason || message));
+  const isSyntax = MDX_SYNTAX_RE.test(message);
+  const isFrontmatter =
+    err.source === 'remark-frontmatter' ||
+    /\byaml\b|frontmatter/i.test(message) ||
+    (loc && loc.line === 1 && /unexpected|expected/i.test(message) && /---/.test(message));
+
+  if (loc || isSyntax || (frame && fileIsProjectOwned)) {
+    return makeIssue({
+      category: isFrontmatter ? 'frontmatter' : 'mdx-syntax',
+      file,
+      line: loc ? loc.line : null,
+      column: loc ? loc.column : null,
+      frame,
+      title: detail || (isFrontmatter ? 'Invalid frontmatter' : 'MDX syntax error'),
+      detail: '',
+      hint: isFrontmatter
+        ? 'Check the YAML between the --- markers — indentation, quotes, and colons.'
+        : 'Make sure every <Component> has a matching closing tag and that { } braces are balanced.',
+    });
+  }
+
+  // 3) Bad prop / option that threw at render time.
+  if (/\.map is not a function|is not iterable|reading '|undefined \(reading/i.test(message)) {
+    return makeIssue({
+      category: 'invalid-props',
+      file,
+      title: 'A component received an invalid value',
+      detail,
+      hint: 'Check the props/options you passed to a component on this page.',
+    });
+  }
+
+  // 4) Anything else that threw while rendering.
+  return makeIssue({
+    category: 'render-crash',
+    file,
+    title: 'This page failed to render',
+    detail,
+    hint: 'Set VELU_DEBUG=1 for the full stack trace.',
+  });
+}
+
+export default extractMdxError;

package/src/lib/issues.js

@@ -0,0 +1,159 @@
+// The shared "issue" model used by BOTH the live `velu dev` error surface and
+// the `velu validate` command — so an author sees the same wording whether a
+// problem shows up live in the browser/terminal or in a batch validation run.
+//
+// An issue is a plain object:
+//   {
+//     category,    // see CATEGORY_LABEL keys below
+//     severity,    // 'error' (default) | 'warning' | 'info'
+//     file,        // project-relative path (posix), or null
+//     line, column,// 1-based numbers, or null
+//     frame,       // a caret-annotated code-frame string, or null
+//     title,       // short, plain-language headline
+//     detail,      // the underlying message (already path-stripped)
+//     hint,        // how to fix it
+//     suggestion,  // a "did you mean <X>" component name, or null
+//   }
+//
+// This module is dependency-free and isomorphic (no Node-only imports), so the
+// browser ErrorBoundary can reuse `levenshtein`/`suggestComponent`.
+
+export const CATEGORY_LABEL = {
+  'mdx-syntax': 'MDX syntax',
+  frontmatter: 'Frontmatter',
+  'unknown-component': 'Unknown component',
+  'invalid-props': 'Invalid options',
+  'render-crash': 'Render error',
+  'config-json': 'velu.json',
+  'config-schema': 'velu.json',
+  'config-nav': 'Navigation',
+  'config-asset': 'Asset',
+};
+
+// Fill in defaults so callers only set what they know.
+export function makeIssue(partial) {
+  return {
+    category: 'render-crash',
+    severity: 'error',
+    file: null,
+    line: null,
+    column: null,
+    frame: null,
+    title: 'Something went wrong',
+    detail: '',
+    hint: '',
+    suggestion: null,
+    ...partial,
+  };
+}
+
+// Classic Levenshtein edit distance (small inputs — component names).
+export function levenshtein(a, b) {
+  a = String(a);
+  b = String(b);
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  let cur = new Array(b.length + 1);
+  for (let i = 1; i <= a.length; i++) {
+    cur[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      cur[j] = Math.min(cur[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    [prev, cur] = [cur, prev];
+  }
+  return prev[b.length];
+}
+
+// Closest known component to `name` within a small edit distance, else null.
+// Compared case-insensitively (so a capitalization typo still matches) but the
+// correctly-cased known name is returned.
+export function suggestComponent(name, known = []) {
+  if (!name) return null;
+  const lower = String(name).toLowerCase();
+  let best = null;
+  let bestD = Infinity;
+  for (const k of known) {
+    const d = levenshtein(lower, String(k).toLowerCase());
+    if (d < bestD) {
+      bestD = d;
+      best = k;
+    }
+  }
+  // Allow a little more slack for longer names, capped at 3 edits.
+  const threshold = Math.min(3, Math.max(2, Math.floor(lower.length / 4)));
+  return bestD <= threshold ? best : null;
+}
+
+// ── Terminal formatting ─────────────────────────────────────────────────────
+
+const COLORS = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+};
+const paint = (on, code, s) => (on ? `${code}${s}${COLORS.reset}` : s);
+
+function severityMark(sev, color) {
+  if (sev === 'warning') return paint(color, COLORS.yellow, '⚠');
+  if (sev === 'info') return paint(color, COLORS.cyan, 'ℹ');
+  return paint(color, COLORS.red, '✖');
+}
+
+// Format a single issue as a multi-line terminal block.
+export function formatIssue(issue, { color = false } = {}) {
+  const label = CATEGORY_LABEL[issue.category] || issue.category;
+  const lineCol = issue.line
+    ? `${issue.line}${issue.column ? `:${issue.column}` : ''}`
+    : '';
+  // Keep the line:col even when grouped output has nulled the file (so the
+  // position still shows under a per-file heading in formatReport).
+  const where = issue.file ? `${issue.file}${lineCol ? `:${lineCol}` : ''}` : lineCol;
+  const lines = [];
+  lines.push(
+    `${severityMark(issue.severity, color)} ${paint(color, COLORS.bold, label)}` +
+      (where ? `  ${paint(color, COLORS.dim, where)}` : ''),
+  );
+  if (issue.title) lines.push(`  ${issue.title}`);
+  if (issue.detail && issue.detail !== issue.title) lines.push(`  ${paint(color, COLORS.dim, issue.detail)}`);
+  if (issue.frame) {
+    for (const f of String(issue.frame).split('\n')) lines.push(`  ${f}`);
+  }
+  if (issue.suggestion) lines.push(`  ${paint(color, COLORS.cyan, `Did you mean <${issue.suggestion}>?`)}`);
+  if (issue.hint) lines.push(`  ${paint(color, COLORS.dim, `→ ${issue.hint}`)}`);
+  return lines.join('\n');
+}
+
+// Format a list of issues as a grouped report (used by `velu validate`).
+export function formatReport(issues, { color = false } = {}) {
+  if (!issues.length) {
+    return paint(color, COLORS.cyan, '✓ No issues found.');
+  }
+  // Group by file (config issues with no file group under "velu.json").
+  const groups = new Map();
+  for (const issue of issues) {
+    const key = issue.file || 'velu.json';
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(issue);
+  }
+  const out = [];
+  for (const [file, group] of groups) {
+    out.push(paint(color, COLORS.bold, file));
+    for (const issue of group) {
+      out.push(formatIssue({ ...issue, file: null }, { color }).replace(/^/gm, '  '));
+    }
+    out.push('');
+  }
+  const errors = issues.filter((i) => i.severity !== 'warning' && i.severity !== 'info').length;
+  const warnings = issues.length - errors;
+  const summary =
+    `${errors} error${errors === 1 ? '' : 's'}` +
+    (warnings ? `, ${warnings} warning${warnings === 1 ? '' : 's'}` : '');
+  out.push(paint(color, errors ? COLORS.red : COLORS.yellow, summary));
+  return out.join('\n');
+}

package/src/lib/known-components.js

@@ -0,0 +1,34 @@
+// The capitalized component tags an author may use in `.mdx` content.
+//
+// Kept in sync with velu-ui's `defaultMdxComponents`
+// (packages/velu-ui/src/mdx-components.jsx). Used for "did you mean"
+// suggestions and unknown-component detection on the Node side (dev server +
+// `velu validate`). The browser ErrorBoundary derives the same set directly
+// from `defaultMdxComponents`, so this list only needs to stay roughly in
+// step (a missing entry just costs a suggestion, never correctness).
+export const KNOWN_COMPONENTS = [
+  'Callout',
+  'Card',
+  'CardGroup',
+  'Accordion',
+  'AccordionGroup',
+  'Columns',
+  'Field',
+  'Prompt',
+  'Steps',
+  'Step',
+  'Tree',
+  'Folder',
+  'File',
+  'Image',
+  'CodeBlock',
+  'CodeGroup',
+  'MethodBadge',
+  'ApiPath',
+  'TryItBar',
+  'ApiField',
+  'ApiClient',
+  'ApiSidebar',
+];
+
+export default KNOWN_COMPONENTS;