massbank 0.0.2 → 0.2.0

package/lib/validator/validator.js

@@ -0,0 +1,159 @@
+import { ParseException, parseRecord } from '../parser/index.js';
+import { RecordValidator } from '../validation/index.js';
+/**
+ * Validate a single MassBank record file
+ * @param filePath - Path to the .txt file
+ * @param options - Validation options (legacy mode, logger)
+ * @returns ValidationResult with errors, warnings, and accession
+ */
+export async function validate(filePath, options = {}) {
+    const errors = [];
+    const warnings = [];
+    const accessions = [];
+    // Log if logger provided
+    if (options.logger) {
+        options.logger.info(`Validating file: ${filePath}`);
+    }
+    // Dynamic import to avoid pulling node:fs/promises into browser bundles
+    const { FileUtils } = await import('./file-utils.js');
+    // Read file
+    let fileContent;
+    try {
+        fileContent = await FileUtils.readFile(filePath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            success: false,
+            errors: [
+                {
+                    file: filePath,
+                    message: `Failed to read file: ${message}`,
+                    type: 'other',
+                },
+            ],
+            warnings: [],
+            accessions: [],
+            filesProcessed: 0,
+        };
+    }
+    // Parse the record
+    let record;
+    try {
+        record = parseRecord(fileContent);
+    }
+    catch (error) {
+        if (error instanceof ParseException) {
+            errors.push({
+                file: filePath,
+                line: error.parseError.line,
+                column: error.parseError.column,
+                message: error.parseError.message,
+                type: 'parse',
+            });
+            return {
+                success: false,
+                errors,
+                warnings,
+                accessions,
+                filesProcessed: 1,
+            };
+        }
+        throw error;
+    }
+    // Apply validation rules
+    const recordValidator = new RecordValidator();
+    const rules = recordValidator.getRules();
+    for (const rule of rules) {
+        const ruleErrors = rule.validate(record, fileContent, filePath, {
+            legacy: options.legacy,
+        });
+        errors.push(...ruleErrors);
+        const ruleWarnings = rule.getWarnings(record, fileContent, filePath, {
+            legacy: options.legacy,
+        });
+        warnings.push(...ruleWarnings);
+    }
+    if (record.ACCESSION) {
+        accessions.push(record.ACCESSION);
+    }
+    const success = errors.length === 0;
+    if (options.logger) {
+        if (success) {
+            options.logger.info(`✓ Validation passed for ${filePath}`);
+        }
+        else {
+            options.logger.error(`✗ Validation failed for ${filePath} with ${errors.length} error(s)`);
+        }
+    }
+    return {
+        success,
+        errors,
+        warnings,
+        accessions,
+        filesProcessed: 1,
+    };
+}
+/**
+ * Validate in-memory MassBank record content
+ * Useful for browser or API use-cases where the record content is not
+ * coming from the filesystem.
+ * @param content - Full record text to validate
+ * @param filename - Logical filename for error reporting (e.g. 'user-upload.txt')
+ * @param options - Validation options (legacy mode, logger)
+ * @returns ValidationResult with errors, warnings, and accession
+ */
+export async function validateContent(content, filename, options = {}) {
+    const errors = [];
+    const warnings = [];
+    const accessions = [];
+    // Parse the record
+    let record;
+    try {
+        record = parseRecord(content);
+    }
+    catch (error) {
+        if (error instanceof ParseException) {
+            errors.push({
+                file: filename,
+                line: error.parseError.line,
+                column: error.parseError.column,
+                message: error.parseError.message,
+                type: 'parse',
+            });
+            return {
+                success: false,
+                errors,
+                warnings,
+                accessions,
+                filesProcessed: 1,
+            };
+        }
+        throw error;
+    }
+    // Apply validation rules
+    const recordValidator = new RecordValidator();
+    const rules = recordValidator.getRules();
+    for (const rule of rules) {
+        const ruleErrors = rule.validate(record, content, filename, {
+            legacy: options.legacy,
+        });
+        errors.push(...ruleErrors);
+        const ruleWarnings = rule.getWarnings(record, content, filename, {
+            legacy: options.legacy,
+        });
+        warnings.push(...ruleWarnings);
+    }
+    if (record.ACCESSION) {
+        accessions.push(record.ACCESSION);
+    }
+    const success = errors.length === 0;
+    return {
+        success,
+        errors,
+        warnings,
+        accessions,
+        filesProcessed: 1,
+    };
+}
+//# sourceMappingURL=validator.js.map

package/lib/validator/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/validator/validator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "massbank",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "license": "MIT",
   "description": "Utilities to submit massbank data",
   "keywords": [],

package/src/index.ts

@@ -1,7 +1,15 @@
 /**
- * My module
- * @returns A very important number
+ * MassBank validation library
+ * Main entry point for the package
  */
-export function myModule(): number {
-  return 42;
-}
+
+// Validation functions
+export { validate, validateContent } from './validator/index.js';
+
+// Types for reading validation results
+export type {
+  ValidationError,
+  ValidationOptions,
+  ValidationResult,
+  ValidationWarning,
+} from './types.js';

package/src/parser/exceptions.ts

@@ -0,0 +1,24 @@
+import type { ParseError } from '../types.js';
+
+/**
+ * Exception thrown when parsing fails
+ */
+export class ParseException extends Error {
+  readonly parseError: ParseError;
+  constructor(parseError: ParseError, message?: string) {
+    super(message || parseError.message);
+    this.parseError = parseError;
+    this.name = 'ParseException';
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    const ErrorConstructor = Error as typeof Error & {
+      captureStackTrace?: (
+        error: Error,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        constructor: new (...args: any[]) => Error,
+      ) => void;
+    };
+    if (typeof ErrorConstructor.captureStackTrace === 'function') {
+      ErrorConstructor.captureStackTrace(this, ParseException);
+    }
+  }
+}

package/src/parser/field-parsers.ts

@@ -0,0 +1,237 @@
+import type { Record } from '../record.js';
+
+import type { IFieldParser } from './interfaces.js';
+
+/**
+ * Base class for field parsers
+ */
+abstract class BaseFieldParser implements IFieldParser {
+  abstract canParse(key: string): boolean;
+  abstract parse(key: string, value: string, record: Record): void;
+}
+
+/**
+ * Header field parser
+ */
+export class HeaderFieldParser extends BaseFieldParser {
+  canParse(key: string): boolean {
+    const headerFields = [
+      'ACCESSION',
+      'RECORD_TITLE',
+      'DATE',
+      'AUTHORS',
+      'LICENSE',
+      'COPYRIGHT',
+      'PUBLICATION',
+      'PROJECT',
+      'COMMENT',
+      'DEPRECATED',
+    ];
+    return headerFields.includes(key);
+  }
+
+  parse(key: string, value: string, record: Record): void {
+    switch (key) {
+      case 'ACCESSION':
+        record.ACCESSION = value;
+        break;
+      case 'RECORD_TITLE':
+        record.RECORD_TITLE = value;
+        break;
+      case 'DATE':
+        record.DATE = value;
+        break;
+      case 'AUTHORS':
+        record.AUTHORS = value;
+        break;
+      case 'LICENSE':
+        record.LICENSE = value;
+        break;
+      case 'COPYRIGHT':
+        record.COPYRIGHT = value;
+        break;
+      case 'PUBLICATION':
+        record.PUBLICATION = value;
+        break;
+      case 'PROJECT':
+        record.PROJECT = value;
+        break;
+      case 'COMMENT':
+        if (!record.COMMENT) {
+          record.COMMENT = [];
+        }
+        record.COMMENT.push(value);
+        break;
+      case 'DEPRECATED':
+        record.DEPRECATED = value;
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+/**
+ * Compound (CH$) field parser
+ */
+export class CompoundFieldParser extends BaseFieldParser {
+  canParse(key: string): boolean {
+    return key.startsWith('CH$');
+  }
+
+  parse(key: string, value: string, record: Record): void {
+    switch (key) {
+      case 'CH$NAME':
+        if (!record.CH$NAME) {
+          record.CH$NAME = [];
+        }
+        record.CH$NAME.push(value);
+        break;
+      case 'CH$COMPOUND_CLASS':
+        record.CH$COMPOUND_CLASS = value;
+        break;
+      case 'CH$FORMULA':
+        record.CH$FORMULA = value;
+        break;
+      case 'CH$EXACT_MASS':
+        record.CH$EXACT_MASS = value;
+        break;
+      case 'CH$SMILES':
+        record.CH$SMILES = value;
+        break;
+      case 'CH$IUPAC':
+        record.CH$IUPAC = value;
+        break;
+      case 'CH$LINK':
+        if (!record.CH$LINK) {
+          record.CH$LINK = [];
+        }
+        record.CH$LINK.push(value);
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+/**
+ * Analytical conditions (AC$) field parser
+ */
+export class AnalyticalConditionsFieldParser extends BaseFieldParser {
+  canParse(key: string): boolean {
+    return key.startsWith('AC$');
+  }
+
+  parse(key: string, value: string, record: Record): void {
+    switch (key) {
+      case 'AC$INSTRUMENT':
+        record.AC$INSTRUMENT = value;
+        break;
+      case 'AC$INSTRUMENT_TYPE':
+        record.AC$INSTRUMENT_TYPE = value;
+        break;
+      case 'AC$MASS_SPECTROMETRY':
+        if (!record.AC$MASS_SPECTROMETRY) {
+          record.AC$MASS_SPECTROMETRY = [];
+        }
+        record.AC$MASS_SPECTROMETRY.push(value);
+        break;
+      case 'AC$CHROMATOGRAPHY':
+        if (!record.AC$CHROMATOGRAPHY) {
+          record.AC$CHROMATOGRAPHY = [];
+        }
+        record.AC$CHROMATOGRAPHY.push(value);
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+/**
+ * Mass spectrometry (MS$) field parser
+ */
+export class MassSpectrometryFieldParser extends BaseFieldParser {
+  canParse(key: string): boolean {
+    return key.startsWith('MS$');
+  }
+
+  parse(key: string, value: string, record: Record): void {
+    switch (key) {
+      case 'MS$FOCUSED_ION':
+        if (!record.MS$FOCUSED_ION) {
+          record.MS$FOCUSED_ION = [];
+        }
+        record.MS$FOCUSED_ION.push(value);
+        break;
+      case 'MS$DATA_PROCESSING':
+        if (!record.MS$DATA_PROCESSING) {
+          record.MS$DATA_PROCESSING = [];
+        }
+        record.MS$DATA_PROCESSING.push(value);
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+/**
+ * Peak (PK$) field parser (non-table fields)
+ */
+export class PeakFieldParser extends BaseFieldParser {
+  canParse(key: string): boolean {
+    return (
+      key.startsWith('PK$') && key !== 'PK$PEAK' && key !== 'PK$ANNOTATION'
+    );
+  }
+
+  parse(key: string, value: string, record: Record): void {
+    switch (key) {
+      case 'PK$SPLASH':
+        record.PK$SPLASH = value;
+        break;
+      case 'PK$NUM_PEAK': {
+        const numPeak = Number.parseInt(value, 10);
+        if (Number.isNaN(numPeak)) {
+          throw new Error(`Invalid PK$NUM_PEAK value: ${value}`);
+        }
+        record.PK$NUM_PEAK = numPeak;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+}
+
+/**
+ * Species (SP$) field parser
+ */
+export class SpeciesFieldParser extends BaseFieldParser {
+  canParse(key: string): boolean {
+    return key.startsWith('SP$');
+  }
+
+  parse(key: string, value: string, record: Record): void {
+    switch (key) {
+      case 'SP$SCIENTIFIC_NAME':
+        record.SP$SCIENTIFIC_NAME = value;
+        break;
+      case 'SP$LINEAGE':
+        record.SP$LINEAGE = value;
+        break;
+      case 'SP$LINK':
+        if (!record.SP$LINK) {
+          record.SP$LINK = [];
+        }
+        record.SP$LINK.push(value);
+        break;
+      case 'SP$SAMPLE':
+        record.SP$SAMPLE = value;
+        break;
+      default:
+        break;
+    }
+  }
+}

package/src/parser/index.ts

@@ -0,0 +1,8 @@
+export { RecordParser, createParser, parseRecord } from './record-parser.js';
+export { ParseException } from './exceptions.js';
+export type {
+  IFieldParser,
+  IRecordParser,
+  ITableParser,
+} from './interfaces.js';
+export { PositionUtils } from './position-utils.js';

package/src/parser/interfaces.ts

@@ -0,0 +1,56 @@
+import type { Record } from '../record.js';
+
+/**
+ * Interface for parsing MassBank records
+ */
+export interface IRecordParser {
+  /**
+   * Parse a MassBank record string into a Record object
+   * @param text - The MassBank record text
+   * @returns The parsed Record object
+   * @throws {import('./exceptions.js').ParseException} if parsing fails
+   */
+  parse(text: string): Record;
+}
+
+/**
+ * Interface for parsing field values
+ */
+export interface IFieldParser {
+  /**
+   * Check if this parser can handle the given key
+   */
+  canParse(key: string): boolean;
+
+  /**
+   * Parse the field value
+   */
+  parse(key: string, value: string, record: Record): void;
+}
+
+/**
+ * Interface for parsing table data (peaks, annotations)
+ */
+export interface ITableParser {
+  /**
+   * Check if this parser can handle the given key
+   */
+  canParse(key: string): boolean;
+
+  /**
+   * Parse table data starting from the given line index
+   * @param key - The field key
+   * @param lines - All lines
+   * @param startIndex - Index of first data line (header is at startIndex - 1)
+   * @param record - Record to populate
+   * @param headerLine - The full header line (e.g., "PK$ANNOTATION: m/z ion")
+   * @returns The number of lines consumed
+   */
+  parse(
+    key: string,
+    lines: string[],
+    startIndex: number,
+    record: Record,
+    headerLine?: string,
+  ): number;
+}

package/src/parser/position-utils.ts

@@ -0,0 +1,130 @@
+import type { ParseError } from '../types.js';
+
+/**
+ * Utility functions for position calculations
+ * Handle position/line/column calculations
+ */
+export const PositionUtils = {
+  /**
+   * Get character position from line and column (both 1-based).
+   * Converts 1-based line/column to a 0-based character offset in the text.
+   * @param text - The full text being parsed (used to determine actual newline lengths)
+   * @param lineIndex - Line number (1-based)
+   * @param column - Column number (1-based)
+   * @returns 0-based character position in the original text
+   */
+  getPosition(text: string, lineIndex: number, column: number): number {
+    // Convert 1-based line/column to 0-based for internal calculation
+    const zeroBasedLine = lineIndex - 1;
+    const zeroBasedColumn = column - 1;
+
+    // Match lines with their actual newline separators to get correct lengths
+    const lineRegex = /^(?<content>.*?)(?<newline>\r\n|\r|\n|$)/gm;
+    let match: RegExpExecArray | null;
+    let offset = 0;
+    let currentLine = 0;
+
+    while ((match = lineRegex.exec(text)) !== null) {
+      if (currentLine === zeroBasedLine) {
+        // Found the target line, add the column offset
+        return offset + zeroBasedColumn;
+      }
+
+      const lineContent = match.groups?.content ?? '';
+      const newlineSeparator = match.groups?.newline ?? '';
+
+      // Move offset past the line content and its newline separator
+      offset += lineContent.length + newlineSeparator.length;
+      currentLine++;
+
+      // If we've processed all text, break to avoid infinite loop
+      if (
+        newlineSeparator === '' ||
+        match.index + match[0].length >= text.length
+      ) {
+        break;
+      }
+    }
+
+    // If we didn't find the line, return the current offset plus column
+    return offset + zeroBasedColumn;
+  },
+
+  /**
+   * Create a ParseError from a 0-based character position.
+   * Converts the position to 1-based line and column numbers.
+   * Clamps position to valid range [0, text.length] to ensure correct line/column calculation.
+   * @param text - The full text being parsed
+   * @param position - 0-based character offset in the text
+   * @param message - Error message describing the problem
+   * @returns ParseError with 1-based line and column
+   */
+  createParseError(
+    text: string,
+    position: number,
+    message: string,
+  ): ParseError {
+    // Clamp position to valid range to prevent invalid line/column calculation
+    const clampedPosition = Math.max(0, Math.min(position, text.length));
+
+    // Delegate to getLineColumn to avoid duplicating logic
+    const { line, column } = this.getLineColumn(text, clampedPosition);
+
+    return {
+      position: clampedPosition,
+      message,
+      line,
+      column,
+    };
+  },
+
+  /**
+   * Get line and column from a 0-based character position.
+   * Converts the position to 1-based line and column numbers.
+   * Clamps position to valid range [0, text.length] and correctly handles the last line.
+   * @param text - The full text being parsed
+   * @param position - 0-based character offset in the text
+   * @returns Object with 1-based line and column
+   */
+  getLineColumn(
+    text: string,
+    position: number,
+  ): { line: number; column: number } {
+    // Clamp position to valid range [0, text.length]
+    const clampedPosition = Math.max(0, Math.min(position, text.length));
+
+    // Match lines with their actual newline separators to get correct lengths
+    // This regex captures line content followed by the newline (CRLF, LF, or CR)
+    const lineRegex = /^(?<content>.*?)(?<newline>\r\n|\r|\n|$)/gm;
+    let match: RegExpExecArray | null;
+    let offset = 0;
+    let lineNumber = 1;
+
+    while ((match = lineRegex.exec(text)) !== null) {
+      const lineContent = match.groups?.content ?? '';
+      const newlineSeparator = match.groups?.newline ?? '';
+      const lineEndOffset = offset + lineContent.length;
+
+      // Check if the position is within this line's content
+      if (clampedPosition <= lineEndOffset) {
+        const column = clampedPosition - offset + 1; // 1-based
+        return { line: lineNumber, column };
+      }
+
+      // Move offset past the line content and its newline separator
+      offset = lineEndOffset + newlineSeparator.length;
+      lineNumber++;
+
+      // If we've processed all text, break to avoid infinite loop
+      if (
+        newlineSeparator === '' ||
+        match.index + match[0].length >= text.length
+      ) {
+        break;
+      }
+    }
+
+    // Fallback for empty text or edge cases: return line 1, column 1
+    return { line: 1, column: 1 };
+  },
+};