@md2do/core 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @md2do/core
 
+## 0.3.0
+
+### Minor Changes
+
+- Add comprehensive warning system for markdown validation and VSCode extension
+  - Add warning configuration system with customizable rules
+  - Add VSCode extension with task explorer, diagnostics, hover tooltips, and smart completion
+  - Support for validating malformed checkboxes, missing metadata, duplicate IDs, and more
+  - Add .vsix distribution for beta testing
+
 ## 0.2.3
 
 ### Patch Changes

package/dist/index.d.mts

@@ -47,11 +47,20 @@ interface ScanResult {
         parseErrors: number;
     };
 }
+type WarningSeverity = 'info' | 'warning' | 'error';
+type WarningCode = 'unsupported-bullet' | 'malformed-checkbox' | 'missing-space-after' | 'missing-space-before' | 'relative-date-no-context' | 'missing-due-date' | 'missing-completed-date' | 'duplicate-todoist-id' | 'file-read-error';
 interface Warning {
     file: string;
     line: number;
-    text: string;
-    reason: string;
+    column?: number;
+    severity: WarningSeverity;
+    source: 'md2do';
+    ruleId: WarningCode;
+    message: string;
+    text?: string;
+    url?: string;
+    /** @deprecated Use message instead */
+    reason?: string;
 }
 
 /**
@@ -812,6 +821,58 @@ declare namespace index {
   export { type index_TaskComparator as TaskComparator, index_byAssignee as byAssignee, index_byCompletionStatus as byCompletionStatus, index_byCreatedDate as byCreatedDate, index_byDueDate as byDueDate, index_byFile as byFile, index_byPerson as byPerson, index_byPriority as byPriority, index_byProject as byProject, index_combineComparators as combineComparators, index_reverse as reverse };
 }
 
+interface WarningFilterConfig {
+    enabled?: boolean | undefined;
+    rules?: Record<string, 'error' | 'warn' | 'info' | 'off'> | undefined;
+}
+/**
+ * Filter warnings based on configuration rules
+ *
+ * This function applies warning configuration rules to filter out disabled warnings
+ * and optionally all warnings if globally disabled.
+ *
+ * @param warnings - Array of warnings to filter
+ * @param config - Warning configuration with enabled flag and rule overrides
+ * @returns Filtered array of warnings
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   enabled: true,
+ *   rules: {
+ *     'missing-due-date': 'off',
+ *     'duplicate-todoist-id': 'error',
+ *   },
+ * };
+ *
+ * const filtered = filterWarnings(allWarnings, config);
+ * // Returns warnings except those with ruleId 'missing-due-date'
+ * ```
+ */
+declare function filterWarnings(warnings: Warning[], config?: WarningFilterConfig): Warning[];
+/**
+ * Group warnings by severity
+ *
+ * Useful for displaying warnings in order of importance or
+ * treating errors differently from warnings.
+ *
+ * @param warnings - Array of warnings to group
+ * @returns Object with warnings grouped by severity level
+ *
+ * @example
+ * ```typescript
+ * const grouped = groupWarningsBySeverity(warnings);
+ * console.log(`${grouped.error.length} errors`);
+ * console.log(`${grouped.warning.length} warnings`);
+ * console.log(`${grouped.info.length} info messages`);
+ * ```
+ */
+declare function groupWarningsBySeverity(warnings: Warning[]): {
+    error: Warning[];
+    warning: Warning[];
+    info: Warning[];
+};
+
 /**
  * Parse an absolute date string in various formats
  *
@@ -876,4 +937,4 @@ declare function extractDateFromHeading(line: string): Date | null;
  */
 declare function generateTaskId(file: string, line: number, text: string): string;
 
-export { ASSIGNEE, COMPLETED_DATE, DUE_DATE_ABSOLUTE, DUE_DATE_RELATIVE, DUE_DATE_SHORT, HEADING_DATE_ISO, HEADING_DATE_NATURAL, HEADING_DATE_SLASH, MarkdownScanner, PATTERNS, PRIORITY_HIGH, PRIORITY_NORMAL, PRIORITY_URGENT, type ParsingContext, type Priority, type ScanResult, TAG, TASK_CHECKBOX, TODOIST_ID, type Task, type TaskFilterCriteria, type UpdateTaskOptions, type Warning, type WriteTaskResult, addTask, cleanTaskText, extractAssignee, extractCompletedDate, extractDateFromHeading, extractDueDate, extractPersonFromFilename, extractPriority, extractProjectFromPath, extractTags, extractTodoistId, index$1 as filters, generateTaskId, parseAbsoluteDate, parseTask, resolveRelativeDate, index as sorting, updateTask, updateTasks };
+export { ASSIGNEE, COMPLETED_DATE, DUE_DATE_ABSOLUTE, DUE_DATE_RELATIVE, DUE_DATE_SHORT, HEADING_DATE_ISO, HEADING_DATE_NATURAL, HEADING_DATE_SLASH, MarkdownScanner, PATTERNS, PRIORITY_HIGH, PRIORITY_NORMAL, PRIORITY_URGENT, type ParsingContext, type Priority, type ScanResult, TAG, TASK_CHECKBOX, TODOIST_ID, type Task, type TaskFilterCriteria, type UpdateTaskOptions, type Warning, type WarningCode, type WarningFilterConfig, type WarningSeverity, type WriteTaskResult, addTask, cleanTaskText, extractAssignee, extractCompletedDate, extractDateFromHeading, extractDueDate, extractPersonFromFilename, extractPriority, extractProjectFromPath, extractTags, extractTodoistId, filterWarnings, index$1 as filters, generateTaskId, groupWarningsBySeverity, parseAbsoluteDate, parseTask, resolveRelativeDate, index as sorting, updateTask, updateTasks };

package/dist/index.d.ts

@@ -47,11 +47,20 @@ interface ScanResult {
         parseErrors: number;
     };
 }
+type WarningSeverity = 'info' | 'warning' | 'error';
+type WarningCode = 'unsupported-bullet' | 'malformed-checkbox' | 'missing-space-after' | 'missing-space-before' | 'relative-date-no-context' | 'missing-due-date' | 'missing-completed-date' | 'duplicate-todoist-id' | 'file-read-error';
 interface Warning {
     file: string;
     line: number;
-    text: string;
-    reason: string;
+    column?: number;
+    severity: WarningSeverity;
+    source: 'md2do';
+    ruleId: WarningCode;
+    message: string;
+    text?: string;
+    url?: string;
+    /** @deprecated Use message instead */
+    reason?: string;
 }
 
 /**
@@ -812,6 +821,58 @@ declare namespace index {
   export { type index_TaskComparator as TaskComparator, index_byAssignee as byAssignee, index_byCompletionStatus as byCompletionStatus, index_byCreatedDate as byCreatedDate, index_byDueDate as byDueDate, index_byFile as byFile, index_byPerson as byPerson, index_byPriority as byPriority, index_byProject as byProject, index_combineComparators as combineComparators, index_reverse as reverse };
 }
 
+interface WarningFilterConfig {
+    enabled?: boolean | undefined;
+    rules?: Record<string, 'error' | 'warn' | 'info' | 'off'> | undefined;
+}
+/**
+ * Filter warnings based on configuration rules
+ *
+ * This function applies warning configuration rules to filter out disabled warnings
+ * and optionally all warnings if globally disabled.
+ *
+ * @param warnings - Array of warnings to filter
+ * @param config - Warning configuration with enabled flag and rule overrides
+ * @returns Filtered array of warnings
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   enabled: true,
+ *   rules: {
+ *     'missing-due-date': 'off',
+ *     'duplicate-todoist-id': 'error',
+ *   },
+ * };
+ *
+ * const filtered = filterWarnings(allWarnings, config);
+ * // Returns warnings except those with ruleId 'missing-due-date'
+ * ```
+ */
+declare function filterWarnings(warnings: Warning[], config?: WarningFilterConfig): Warning[];
+/**
+ * Group warnings by severity
+ *
+ * Useful for displaying warnings in order of importance or
+ * treating errors differently from warnings.
+ *
+ * @param warnings - Array of warnings to group
+ * @returns Object with warnings grouped by severity level
+ *
+ * @example
+ * ```typescript
+ * const grouped = groupWarningsBySeverity(warnings);
+ * console.log(`${grouped.error.length} errors`);
+ * console.log(`${grouped.warning.length} warnings`);
+ * console.log(`${grouped.info.length} info messages`);
+ * ```
+ */
+declare function groupWarningsBySeverity(warnings: Warning[]): {
+    error: Warning[];
+    warning: Warning[];
+    info: Warning[];
+};
+
 /**
  * Parse an absolute date string in various formats
  *
@@ -876,4 +937,4 @@ declare function extractDateFromHeading(line: string): Date | null;
  */
 declare function generateTaskId(file: string, line: number, text: string): string;
 
-export { ASSIGNEE, COMPLETED_DATE, DUE_DATE_ABSOLUTE, DUE_DATE_RELATIVE, DUE_DATE_SHORT, HEADING_DATE_ISO, HEADING_DATE_NATURAL, HEADING_DATE_SLASH, MarkdownScanner, PATTERNS, PRIORITY_HIGH, PRIORITY_NORMAL, PRIORITY_URGENT, type ParsingContext, type Priority, type ScanResult, TAG, TASK_CHECKBOX, TODOIST_ID, type Task, type TaskFilterCriteria, type UpdateTaskOptions, type Warning, type WriteTaskResult, addTask, cleanTaskText, extractAssignee, extractCompletedDate, extractDateFromHeading, extractDueDate, extractPersonFromFilename, extractPriority, extractProjectFromPath, extractTags, extractTodoistId, index$1 as filters, generateTaskId, parseAbsoluteDate, parseTask, resolveRelativeDate, index as sorting, updateTask, updateTasks };
+export { ASSIGNEE, COMPLETED_DATE, DUE_DATE_ABSOLUTE, DUE_DATE_RELATIVE, DUE_DATE_SHORT, HEADING_DATE_ISO, HEADING_DATE_NATURAL, HEADING_DATE_SLASH, MarkdownScanner, PATTERNS, PRIORITY_HIGH, PRIORITY_NORMAL, PRIORITY_URGENT, type ParsingContext, type Priority, type ScanResult, TAG, TASK_CHECKBOX, TODOIST_ID, type Task, type TaskFilterCriteria, type UpdateTaskOptions, type Warning, type WarningCode, type WarningFilterConfig, type WarningSeverity, type WriteTaskResult, addTask, cleanTaskText, extractAssignee, extractCompletedDate, extractDateFromHeading, extractDueDate, extractPersonFromFilename, extractPriority, extractProjectFromPath, extractTags, extractTodoistId, filterWarnings, index$1 as filters, generateTaskId, groupWarningsBySeverity, parseAbsoluteDate, parseTask, resolveRelativeDate, index as sorting, updateTask, updateTasks };

package/dist/index.js

@@ -57,8 +57,10 @@ __export(index_exports, {
   extractProjectFromPath: () => extractProjectFromPath,
   extractTags: () => extractTags,
   extractTodoistId: () => extractTodoistId,
+  filterWarnings: () => filterWarnings,
   filters: () => filters_exports,
   generateTaskId: () => generateTaskId,
+  groupWarningsBySeverity: () => groupWarningsBySeverity,
   parseAbsoluteDate: () => parseAbsoluteDate,
   parseTask: () => parseTask,
   resolveRelativeDate: () => resolveRelativeDate,
@@ -216,11 +218,15 @@ function extractDueDate(text, context) {
       return {
         date: void 0,
         warning: {
+          severity: "warning",
+          source: "md2do",
+          ruleId: "relative-date-no-context",
           file: "",
           // Will be filled in by caller
           line: 0,
           // Will be filled in by caller
           text: text.trim(),
+          message: "Relative due date without context date from heading. Add a heading with a date above this task.",
           reason: "Relative due date without context date from heading. Add a heading with a date above this task."
         }
       };
@@ -237,36 +243,52 @@ function parseTask(line, lineNumber, file, context) {
   const warnings = [];
   if (/^\s*[*+]\s+\[[ xX]\]/.test(line)) {
     warnings.push({
+      severity: "warning",
+      source: "md2do",
+      ruleId: "unsupported-bullet",
       file,
       line: lineNumber,
       text: line.trim(),
+      message: "Unsupported bullet marker (* or +). Use dash (-) for task lists.",
       reason: "Unsupported bullet marker (* or +). Use dash (-) for task lists."
     });
     return { task: null, warnings };
   }
   if (/^\s*-\s+\[[xX]\s+\]/.test(line) || /^\s*-\s+\[\s+[xX]\]/.test(line)) {
     warnings.push({
+      severity: "warning",
+      source: "md2do",
+      ruleId: "malformed-checkbox",
       file,
       line: lineNumber,
       text: line.trim(),
+      message: "Malformed checkbox with extra spaces. Use [x] or [ ] without extra spaces.",
       reason: "Malformed checkbox with extra spaces. Use [x] or [ ] without extra spaces."
     });
     return { task: null, warnings };
   }
   if (/^\s*-\s+\[[ xX]\][^\s]/.test(line)) {
     warnings.push({
+      severity: "warning",
+      source: "md2do",
+      ruleId: "missing-space-after",
       file,
       line: lineNumber,
       text: line.trim(),
+      message: 'Missing space after checkbox. Use "- [x] Task" format.',
       reason: 'Missing space after checkbox. Use "- [x] Task" format.'
     });
     return { task: null, warnings };
   }
   if (/^\s*-\[[ xX]\]/.test(line)) {
     warnings.push({
+      severity: "warning",
+      source: "md2do",
+      ruleId: "missing-space-before",
       file,
       line: lineNumber,
       text: line.trim(),
+      message: 'Missing space before checkbox. Use "- [x] Task" format.',
       reason: 'Missing space before checkbox. Use "- [x] Task" format.'
     });
     return { task: null, warnings };
@@ -292,17 +314,25 @@ function parseTask(line, lineNumber, file, context) {
   }
   if (!completed && !dueDateResult.date && !context.currentDate) {
     warnings.push({
+      severity: "info",
+      source: "md2do",
+      ruleId: "missing-due-date",
       file,
       line: lineNumber,
       text: fullText.trim(),
+      message: "Task has no due date. Add [due: YYYY-MM-DD] or place under a heading with a date.",
       reason: "Task has no due date. Add [due: YYYY-MM-DD] or place under a heading with a date."
     });
   }
   if (completed && !completedDate) {
     warnings.push({
+      severity: "info",
+      source: "md2do",
+      ruleId: "missing-completed-date",
       file,
       line: lineNumber,
       text: fullText.trim(),
+      message: "Completed task missing completion date. Add [completed: YYYY-MM-DD].",
       reason: "Completed task missing completion date. Add [completed: YYYY-MM-DD]."
     });
   }
@@ -375,9 +405,13 @@ var MarkdownScanner = class {
           const existing = todoistIds.get(result.task.todoistId);
           if (existing) {
             warnings.push({
+              severity: "error",
+              source: "md2do",
+              ruleId: "duplicate-todoist-id",
               file: filePath,
               line: lineNumber,
               text: result.task.text,
+              message: `Duplicate Todoist ID [todoist:${result.task.todoistId}]. Also found at ${existing.file}:${existing.line}.`,
               reason: `Duplicate Todoist ID [todoist:${result.task.todoistId}]. Also found at ${existing.file}:${existing.line}.`
             });
           } else {
@@ -416,9 +450,13 @@ var MarkdownScanner = class {
           const existing = todoistIds.get(task.todoistId);
           if (existing && existing.file !== task.file) {
             allWarnings.push({
+              severity: "error",
+              source: "md2do",
+              ruleId: "duplicate-todoist-id",
               file: task.file,
               line: task.line,
               text: task.text,
+              message: `Duplicate Todoist ID [todoist:${task.todoistId}] across files. Also found at ${existing.file}:${existing.line}.`,
               reason: `Duplicate Todoist ID [todoist:${task.todoistId}] across files. Also found at ${existing.file}:${existing.line}.`
             });
           } else if (!existing) {
@@ -867,6 +905,32 @@ function combineComparators(comparators) {
 function reverse(comparator) {
   return (a, b) => -comparator(a, b);
 }
+
+// src/warnings/filter.ts
+function filterWarnings(warnings, config = {}) {
+  if (config.enabled === false) {
+    return [];
+  }
+  if (!config.rules) {
+    return warnings;
+  }
+  return warnings.filter((warning) => {
+    const level = config.rules?.[warning.ruleId];
+    if (level === void 0) {
+      return true;
+    }
+    return level !== "off";
+  });
+}
+function groupWarningsBySeverity(warnings) {
+  return warnings.reduce(
+    (acc, warning) => {
+      acc[warning.severity].push(warning);
+      return acc;
+    },
+    { error: [], warning: [], info: [] }
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ASSIGNEE,
@@ -896,8 +960,10 @@ function reverse(comparator) {
   extractProjectFromPath,
   extractTags,
   extractTodoistId,
+  filterWarnings,
   filters,
   generateTaskId,
+  groupWarningsBySeverity,
   parseAbsoluteDate,
   parseTask,
   resolveRelativeDate,

package/dist/index.mjs

@@ -159,11 +159,15 @@ function extractDueDate(text, context) {
       return {
         date: void 0,
         warning: {
+          severity: "warning",
+          source: "md2do",
+          ruleId: "relative-date-no-context",
           file: "",
           // Will be filled in by caller
           line: 0,
           // Will be filled in by caller
           text: text.trim(),
+          message: "Relative due date without context date from heading. Add a heading with a date above this task.",
           reason: "Relative due date without context date from heading. Add a heading with a date above this task."
         }
       };
@@ -180,36 +184,52 @@ function parseTask(line, lineNumber, file, context) {
   const warnings = [];
   if (/^\s*[*+]\s+\[[ xX]\]/.test(line)) {
     warnings.push({
+      severity: "warning",
+      source: "md2do",
+      ruleId: "unsupported-bullet",
       file,
       line: lineNumber,
       text: line.trim(),
+      message: "Unsupported bullet marker (* or +). Use dash (-) for task lists.",
       reason: "Unsupported bullet marker (* or +). Use dash (-) for task lists."
     });
     return { task: null, warnings };
   }
   if (/^\s*-\s+\[[xX]\s+\]/.test(line) || /^\s*-\s+\[\s+[xX]\]/.test(line)) {
     warnings.push({
+      severity: "warning",
+      source: "md2do",
+      ruleId: "malformed-checkbox",
       file,
       line: lineNumber,
       text: line.trim(),
+      message: "Malformed checkbox with extra spaces. Use [x] or [ ] without extra spaces.",
       reason: "Malformed checkbox with extra spaces. Use [x] or [ ] without extra spaces."
     });
     return { task: null, warnings };
   }
   if (/^\s*-\s+\[[ xX]\][^\s]/.test(line)) {
     warnings.push({
+      severity: "warning",
+      source: "md2do",
+      ruleId: "missing-space-after",
       file,
       line: lineNumber,
       text: line.trim(),
+      message: 'Missing space after checkbox. Use "- [x] Task" format.',
       reason: 'Missing space after checkbox. Use "- [x] Task" format.'
     });
     return { task: null, warnings };
   }
   if (/^\s*-\[[ xX]\]/.test(line)) {
     warnings.push({
+      severity: "warning",
+      source: "md2do",
+      ruleId: "missing-space-before",
       file,
       line: lineNumber,
       text: line.trim(),
+      message: 'Missing space before checkbox. Use "- [x] Task" format.',
       reason: 'Missing space before checkbox. Use "- [x] Task" format.'
     });
     return { task: null, warnings };
@@ -235,17 +255,25 @@ function parseTask(line, lineNumber, file, context) {
   }
   if (!completed && !dueDateResult.date && !context.currentDate) {
     warnings.push({
+      severity: "info",
+      source: "md2do",
+      ruleId: "missing-due-date",
       file,
       line: lineNumber,
       text: fullText.trim(),
+      message: "Task has no due date. Add [due: YYYY-MM-DD] or place under a heading with a date.",
       reason: "Task has no due date. Add [due: YYYY-MM-DD] or place under a heading with a date."
     });
   }
   if (completed && !completedDate) {
     warnings.push({
+      severity: "info",
+      source: "md2do",
+      ruleId: "missing-completed-date",
       file,
       line: lineNumber,
       text: fullText.trim(),
+      message: "Completed task missing completion date. Add [completed: YYYY-MM-DD].",
       reason: "Completed task missing completion date. Add [completed: YYYY-MM-DD]."
     });
   }
@@ -318,9 +346,13 @@ var MarkdownScanner = class {
           const existing = todoistIds.get(result.task.todoistId);
           if (existing) {
             warnings.push({
+              severity: "error",
+              source: "md2do",
+              ruleId: "duplicate-todoist-id",
               file: filePath,
               line: lineNumber,
               text: result.task.text,
+              message: `Duplicate Todoist ID [todoist:${result.task.todoistId}]. Also found at ${existing.file}:${existing.line}.`,
               reason: `Duplicate Todoist ID [todoist:${result.task.todoistId}]. Also found at ${existing.file}:${existing.line}.`
             });
           } else {
@@ -359,9 +391,13 @@ var MarkdownScanner = class {
           const existing = todoistIds.get(task.todoistId);
           if (existing && existing.file !== task.file) {
             allWarnings.push({
+              severity: "error",
+              source: "md2do",
+              ruleId: "duplicate-todoist-id",
               file: task.file,
               line: task.line,
               text: task.text,
+              message: `Duplicate Todoist ID [todoist:${task.todoistId}] across files. Also found at ${existing.file}:${existing.line}.`,
               reason: `Duplicate Todoist ID [todoist:${task.todoistId}] across files. Also found at ${existing.file}:${existing.line}.`
             });
           } else if (!existing) {
@@ -810,6 +846,32 @@ function combineComparators(comparators) {
 function reverse(comparator) {
   return (a, b) => -comparator(a, b);
 }
+
+// src/warnings/filter.ts
+function filterWarnings(warnings, config = {}) {
+  if (config.enabled === false) {
+    return [];
+  }
+  if (!config.rules) {
+    return warnings;
+  }
+  return warnings.filter((warning) => {
+    const level = config.rules?.[warning.ruleId];
+    if (level === void 0) {
+      return true;
+    }
+    return level !== "off";
+  });
+}
+function groupWarningsBySeverity(warnings) {
+  return warnings.reduce(
+    (acc, warning) => {
+      acc[warning.severity].push(warning);
+      return acc;
+    },
+    { error: [], warning: [], info: [] }
+  );
+}
 export {
   ASSIGNEE,
   COMPLETED_DATE,
@@ -838,8 +900,10 @@ export {
   extractProjectFromPath,
   extractTags,
   extractTodoistId,
+  filterWarnings,
   filters_exports as filters,
   generateTaskId,
+  groupWarningsBySeverity,
   parseAbsoluteDate,
   parseTask,
   resolveRelativeDate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@md2do/core",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Core parsing, filtering, scanning, and file writing for md2do",
   "keywords": [
     "markdown",

package/src/index.ts

@@ -19,6 +19,9 @@ export * as filters from './filters/index.js';
 // Sorting (export as namespace to avoid conflicts)
 export * as sorting from './sorting/index.js';
 
+// Warnings
+export * from './warnings/filter.js';
+
 // Utilities
 export * from './utils/dates.js';
 export * from './utils/id.js';

package/src/parser/index.ts

@@ -126,9 +126,14 @@ export function extractDueDate(
       return {
         date: undefined,
         warning: {
+          severity: 'warning',
+          source: 'md2do',
+          ruleId: 'relative-date-no-context',
           file: '', // Will be filled in by caller
           line: 0, // Will be filled in by caller
           text: text.trim(),
+          message:
+            'Relative due date without context date from heading. Add a heading with a date above this task.',
           reason:
             'Relative due date without context date from heading. Add a heading with a date above this task.',
         },
@@ -212,9 +217,14 @@ export function parseTask(
   // Check for asterisk/plus bullet markers (not supported)
   if (/^\s*[*+]\s+\[[ xX]\]/.test(line)) {
     warnings.push({
+      severity: 'warning',
+      source: 'md2do',
+      ruleId: 'unsupported-bullet',
       file,
       line: lineNumber,
       text: line.trim(),
+      message:
+        'Unsupported bullet marker (* or +). Use dash (-) for task lists.',
       reason:
         'Unsupported bullet marker (* or +). Use dash (-) for task lists.',
     });
@@ -224,9 +234,14 @@ export function parseTask(
   // Check for extra spaces inside checkbox: [x ] or [ x]
   if (/^\s*-\s+\[[xX]\s+\]/.test(line) || /^\s*-\s+\[\s+[xX]\]/.test(line)) {
     warnings.push({
+      severity: 'warning',
+      source: 'md2do',
+      ruleId: 'malformed-checkbox',
       file,
       line: lineNumber,
       text: line.trim(),
+      message:
+        'Malformed checkbox with extra spaces. Use [x] or [ ] without extra spaces.',
       reason:
         'Malformed checkbox with extra spaces. Use [x] or [ ] without extra spaces.',
     });
@@ -236,9 +251,13 @@ export function parseTask(
   // Check for missing space after checkbox: [x]Task
   if (/^\s*-\s+\[[ xX]\][^\s]/.test(line)) {
     warnings.push({
+      severity: 'warning',
+      source: 'md2do',
+      ruleId: 'missing-space-after',
       file,
       line: lineNumber,
       text: line.trim(),
+      message: 'Missing space after checkbox. Use "- [x] Task" format.',
       reason: 'Missing space after checkbox. Use "- [x] Task" format.',
     });
     return { task: null, warnings };
@@ -247,9 +266,13 @@ export function parseTask(
   // Check for missing space before checkbox: -[x]
   if (/^\s*-\[[ xX]\]/.test(line)) {
     warnings.push({
+      severity: 'warning',
+      source: 'md2do',
+      ruleId: 'missing-space-before',
       file,
       line: lineNumber,
       text: line.trim(),
+      message: 'Missing space before checkbox. Use "- [x] Task" format.',
       reason: 'Missing space before checkbox. Use "- [x] Task" format.',
     });
     return { task: null, warnings };
@@ -288,9 +311,14 @@ export function parseTask(
   // Incomplete tasks without any date (no explicit due date and no context date)
   if (!completed && !dueDateResult.date && !context.currentDate) {
     warnings.push({
+      severity: 'info',
+      source: 'md2do',
+      ruleId: 'missing-due-date',
       file,
       line: lineNumber,
       text: fullText.trim(),
+      message:
+        'Task has no due date. Add [due: YYYY-MM-DD] or place under a heading with a date.',
       reason:
         'Task has no due date. Add [due: YYYY-MM-DD] or place under a heading with a date.',
     });
@@ -299,9 +327,14 @@ export function parseTask(
   // Completed tasks should have completion dates
   if (completed && !completedDate) {
     warnings.push({
+      severity: 'info',
+      source: 'md2do',
+      ruleId: 'missing-completed-date',
       file,
       line: lineNumber,
       text: fullText.trim(),
+      message:
+        'Completed task missing completion date. Add [completed: YYYY-MM-DD].',
       reason:
         'Completed task missing completion date. Add [completed: YYYY-MM-DD].',
     });

package/src/scanner/index.ts

@@ -114,9 +114,13 @@ export class MarkdownScanner {
           const existing = todoistIds.get(result.task.todoistId);
           if (existing) {
             warnings.push({
+              severity: 'error',
+              source: 'md2do',
+              ruleId: 'duplicate-todoist-id',
               file: filePath,
               line: lineNumber,
               text: result.task.text,
+              message: `Duplicate Todoist ID [todoist:${result.task.todoistId}]. Also found at ${existing.file}:${existing.line}.`,
               reason: `Duplicate Todoist ID [todoist:${result.task.todoistId}]. Also found at ${existing.file}:${existing.line}.`,
             });
           } else {
@@ -168,9 +172,13 @@ export class MarkdownScanner {
             // Only add warning if duplicate is in a different file
             // (same-file duplicates are already caught by scanFile)
             allWarnings.push({
+              severity: 'error',
+              source: 'md2do',
+              ruleId: 'duplicate-todoist-id',
               file: task.file,
               line: task.line,
               text: task.text,
+              message: `Duplicate Todoist ID [todoist:${task.todoistId}] across files. Also found at ${existing.file}:${existing.line}.`,
               reason: `Duplicate Todoist ID [todoist:${task.todoistId}] across files. Also found at ${existing.file}:${existing.line}.`,
             });
           } else if (!existing) {

package/src/types/index.ts

@@ -65,9 +65,38 @@ export interface ScanResult {
   };
 }
 
+export type WarningSeverity = 'info' | 'warning' | 'error';
+
+export type WarningCode =
+  | 'unsupported-bullet' // * or + instead of -
+  | 'malformed-checkbox' // [x ] or [ x]
+  | 'missing-space-after' // -[x]Task
+  | 'missing-space-before' // -[x] Task
+  | 'relative-date-no-context' // [due: tomorrow] without heading date
+  | 'missing-due-date' // Incomplete task with no due date
+  | 'missing-completed-date' // [x] without [completed: date]
+  | 'duplicate-todoist-id' // Same Todoist ID in multiple tasks
+  | 'file-read-error'; // Failed to read file
+
 export interface Warning {
+  // Position
   file: string;
   line: number;
-  text: string;
-  reason: string;
+  column?: number;
+
+  // Classification
+  severity: WarningSeverity;
+  source: 'md2do';
+  ruleId: WarningCode;
+
+  // Content
+  message: string; // User-facing message
+  text?: string; // The actual text that triggered it
+
+  // Documentation (optional - for future use)
+  url?: string;
+
+  // Legacy field for backward compatibility (deprecated)
+  /** @deprecated Use message instead */
+  reason?: string;
 }

package/src/warnings/filter.ts

@@ -0,0 +1,93 @@
+import type { Warning } from '../types/index.js';
+
+export interface WarningFilterConfig {
+  enabled?: boolean | undefined;
+  rules?: Record<string, 'error' | 'warn' | 'info' | 'off'> | undefined;
+}
+
+/**
+ * Filter warnings based on configuration rules
+ *
+ * This function applies warning configuration rules to filter out disabled warnings
+ * and optionally all warnings if globally disabled.
+ *
+ * @param warnings - Array of warnings to filter
+ * @param config - Warning configuration with enabled flag and rule overrides
+ * @returns Filtered array of warnings
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   enabled: true,
+ *   rules: {
+ *     'missing-due-date': 'off',
+ *     'duplicate-todoist-id': 'error',
+ *   },
+ * };
+ *
+ * const filtered = filterWarnings(allWarnings, config);
+ * // Returns warnings except those with ruleId 'missing-due-date'
+ * ```
+ */
+export function filterWarnings(
+  warnings: Warning[],
+  config: WarningFilterConfig = {},
+): Warning[] {
+  // If warnings are globally disabled, return empty array
+  if (config.enabled === false) {
+    return [];
+  }
+
+  // If no rules specified, return all warnings
+  if (!config.rules) {
+    return warnings;
+  }
+
+  // Filter based on rule configuration
+  return warnings.filter((warning) => {
+    const level = config.rules?.[warning.ruleId];
+
+    // If rule is not configured, include the warning (default: show)
+    if (level === undefined) {
+      return true;
+    }
+
+    // Exclude if rule is set to 'off'
+    return level !== 'off';
+  });
+}
+
+/**
+ * Group warnings by severity
+ *
+ * Useful for displaying warnings in order of importance or
+ * treating errors differently from warnings.
+ *
+ * @param warnings - Array of warnings to group
+ * @returns Object with warnings grouped by severity level
+ *
+ * @example
+ * ```typescript
+ * const grouped = groupWarningsBySeverity(warnings);
+ * console.log(`${grouped.error.length} errors`);
+ * console.log(`${grouped.warning.length} warnings`);
+ * console.log(`${grouped.info.length} info messages`);
+ * ```
+ */
+export function groupWarningsBySeverity(warnings: Warning[]): {
+  error: Warning[];
+  warning: Warning[];
+  info: Warning[];
+} {
+  return warnings.reduce(
+    (acc, warning) => {
+      acc[warning.severity].push(warning);
+      return acc;
+    },
+    { error: [], warning: [], info: [] } as {
+      error: Warning[];
+      warning: Warning[];
+      info: Warning[];
+    },
+  );
+}