parser-lr 0.8.0 → 0.8.1

package/bin/parser-lr.js

@@ -3781,7 +3781,7 @@ const {
   Help,
 } = commander;
 
-var version$1 = "0.8.0";
+var version$1 = "0.8.1";
 var packageDefinition = {
 	version: version$1};
 
@@ -5920,6 +5920,80 @@ function buildLalrGotoTargets(grammar, analysis, lr1Collection, lr1ToLalr) {
     Lr1ItemSetBuilder.buildLr1ToLalrMap = buildLr1ToLalrMap;
 })(Lr1ItemSetBuilder || (Lr1ItemSetBuilder = {}));
 
+/**
+ * Converts a source offset into a 1-based line and column.
+ *
+ * @param source - Full source text.
+ * @param offset - Zero-based UTF-16 code unit offset.
+ * @returns Line and column for the offset, clamped to the source bounds.
+ */
+function offsetToPosition(source, offset) {
+    // Clamp out-of-range offsets to the nearest valid index.
+    const clamped = Math.max(0, Math.min(offset, source.length));
+    let line = 1;
+    let column = 1;
+    // Scan characters before the offset, advancing line on each newline.
+    for (let index = 0; index < clamped; index += 1) {
+        if (source[index] === '\n') {
+            line += 1;
+            column = 1;
+            continue;
+        }
+        column += 1;
+    }
+    return { line, column };
+}
+/**
+ * Returns the start offset from a location or raw offset value.
+ *
+ * @param location - Optional source span.
+ * @param offset - Optional raw offset when no span is available.
+ */
+function resolveDiagnosticOffset(location, offset) {
+    if (location !== null && location !== undefined) {
+        return location.offset;
+    }
+    if (offset === null || offset === undefined) {
+        return null;
+    }
+    return offset;
+}
+
+/**
+ * Formats a diagnostic as `path:line:column: severity: message` when possible.
+ *
+ * @param options - Severity, message, and optional source position inputs.
+ * @returns One diagnostic line without a trailing newline.
+ */
+function formatDiagnostic(options) {
+    const prefix = formatDiagnosticLocationPrefix(options);
+    const body = `${options.severity}: ${options.message}`;
+    if (prefix === null) {
+        return body;
+    }
+    return `${prefix}: ${body}`;
+}
+/**
+ * Builds the `path:line:column` or `path` prefix for a diagnostic.
+ *
+ * @param options - Path and optional source position inputs.
+ * @returns Location prefix, or null when no path is available.
+ */
+function formatDiagnosticLocationPrefix(options) {
+    const path = options.path ?? null;
+    if (path === null || path.length === 0) {
+        return null;
+    }
+    const offset = resolveDiagnosticOffset(options.location, options.offset);
+    const source = options.source ?? null;
+    // Prefer path:line:column when both source text and an offset are known.
+    if (source !== null && offset !== null) {
+        const position = offsetToPosition(source, offset);
+        return `${path}:${String(position.line)}:${String(position.column)}`;
+    }
+    return path;
+}
+
 /**
  * LR parse table with ACTION and GOTO entries plus any detected conflicts.
  */
@@ -5984,13 +6058,19 @@ class LrParseTable {
 function formatParseConflictWarning(conflict) {
     const tokenLabel = formatConflictTokenLabel(conflict.symbol);
     if (conflict.kind === 'shift-reduce') {
-        return `state ${String(conflict.state)}: shift/reduce conflict on ${tokenLabel} resolved as shift`;
+        return formatDiagnostic({
+            severity: 'warning',
+            message: `state ${String(conflict.state)}: shift/reduce conflict on ${tokenLabel} resolved as shift`,
+        });
     }
     const keptProduction = conflict.existing.kind === 'reduce'
         ? conflict.existing.productionId
         : conflict.incoming.productionId;
-    return `state ${String(conflict.state)}: reduce/reduce conflict on ${tokenLabel} `
-        + `resolved using rule ${String(keptProduction)}`;
+    return formatDiagnostic({
+        severity: 'warning',
+        message: `state ${String(conflict.state)}: reduce/reduce conflict on ${tokenLabel} `
+            + `resolved using rule ${String(keptProduction)}`,
+    });
 }
 /**
  * Returns a readable terminal label for conflict warning text.
@@ -7535,6 +7615,42 @@ class ParserLr {
         }
         return parseWithTable(this.table, tokens);
     }
+    /**
+     * Parses a token stream and retains syntax-error offset details.
+     *
+     * @param tokens - Token stream ending with `$eof`.
+     * @returns Tree and optional syntax-error details.
+     */
+    parseResult(tokens) {
+        if (this.table === null) {
+            return {
+                tree: null,
+                errorOffset: 0,
+                errorMessage: 'Parse table has no parser entries',
+            };
+        }
+        const result = parseWithTableResult(this.table, tokens);
+        if (result.cst === null) {
+            return {
+                tree: null,
+                errorOffset: result.errorOffset,
+                errorMessage: result.errorMessage,
+            };
+        }
+        if (this.grammar.transformSchema === null) {
+            return {
+                tree: result.cst,
+                errorOffset: null,
+                errorMessage: null,
+            };
+        }
+        const tree = transformCst(result.cst, this.grammar.transformSchema, this.table);
+        return {
+            tree,
+            errorOffset: tree === null ? result.errorOffset : null,
+            errorMessage: tree === null ? 'AST transform failed' : null,
+        };
+    }
     /**
      * Parses a token stream into an AST when transform rules are declared.
      *
@@ -7542,14 +7658,7 @@ class ParserLr {
      * @returns Transformed AST, CST when no transform section exists, or null on failure.
      */
     parseAst(tokens) {
-        const cst = this.parseCst(tokens);
-        if (cst === null) {
-            return null;
-        }
-        if (this.grammar.transformSchema === null || this.table === null) {
-            return cst;
-        }
-        return transformCst(cst, this.grammar.transformSchema, this.table);
+        return this.parseResult(tokens).tree;
     }
     /**
      * Parses a token stream, applying CST-to-AST transforms when configured.
@@ -7680,6 +7789,15 @@ class ParseContext {
     parse(tokens) {
         return this.parser.parse(tokens);
     }
+    /**
+     * Parses a token stream and retains syntax-error offset details.
+     *
+     * @param tokens - Token stream ending with `$eof`.
+     * @returns Tree and optional syntax-error details.
+     */
+    parseResult(tokens) {
+        return this.parser.parseResult(tokens);
+    }
     /**
      * Lexes and parses source text into an AST, applying transforms when present.
      *
@@ -8031,7 +8149,7 @@ function parseOptionalTransformSection(node) {
 function parseProduction(node) {
     const name = identifierText(requireChild(node, 'identifier'));
     const expression = parseExpressionNode(findExpressionChild(node));
-    return { name, expression };
+    return { name, expression, location: node.location };
 }
 /**
  * Parses one AST type (`identifier = expression ;`).
@@ -8041,7 +8159,7 @@ function parseProduction(node) {
 function parseAstType(node) {
     const name = identifierText(requireChild(node, 'identifier'));
     const expression = parseExpressionNode(findExpressionChild(node));
-    return { name, expression };
+    return { name, expression, location: node.location };
 }
 /**
  * Parses one transform rule.
@@ -8053,6 +8171,7 @@ function parseTransformRule(node) {
     return {
         production,
         alternatives: collectRepeated(node, 'labeled_transform').map(parseLabeledTransform),
+        location: node.location,
     };
 }
 /**
@@ -8063,7 +8182,7 @@ function parseTransformRule(node) {
 function parseLabeledTransform(node) {
     const label = identifierText(requireChild(node, 'identifier'));
     const expression = parseTransformExpr(requireChild(node, 'transform_expr'));
-    return { label, expression };
+    return { label, expression, location: node.location };
 }
 /**
  * Parses a transform expression.
@@ -13539,8 +13658,8 @@ function validateGrammarTable(grammar) {
         for (const rule of grammar.transformSchema.rules) {
             validateTransformProductionExists(rule, bnfProductionNames, issues);
             for (const alternative of rule.alternatives) {
-                validateTransformExpression(grammar, alternative.expression, issues);
-                collectPassCollapseWarnings(grammar, rule, alternative.expression, bnf.productions, issues);
+                validateTransformExpression(grammar, alternative, issues);
+                collectPassCollapseWarnings(grammar, rule, alternative, bnf.productions, issues);
             }
         }
     }
@@ -13559,37 +13678,47 @@ function validateGrammarTable(grammar) {
  */
 function collectDuplicateDefinitionWarnings(grammar, issues) {
     // Flag repeated production names in the grammar section.
-    reportDuplicateNames(grammar.productions.map((production) => production.name), 'grammar', 'production', issues);
+    reportDuplicateDefinitions(grammar.productions.map((production) => ({
+        name: production.name,
+        location: production.location ?? null,
+    })), 'grammar', 'production', issues);
     // Flag repeated ast type names.
     if (grammar.astSchema !== null) {
-        reportDuplicateNames(grammar.astSchema.types.map((type) => type.name), 'ast', 'type', issues);
+        reportDuplicateDefinitions(grammar.astSchema.types.map((type) => ({
+            name: type.name,
+            location: type.location ?? null,
+        })), 'ast', 'type', issues);
     }
     // Flag repeated transform rules for the same production.
     if (grammar.transformSchema !== null) {
-        reportDuplicateNames(grammar.transformSchema.rules.map((rule) => rule.production), 'transform', 'rule', issues);
+        reportDuplicateDefinitions(grammar.transformSchema.rules.map((rule) => ({
+            name: rule.production,
+            location: rule.location ?? null,
+        })), 'transform', 'rule', issues);
     }
 }
 /**
  * Records a warning for each name that appears more than once.
  *
- * @param names - Declared names in source order.
+ * @param definitions - Declared names and locations in source order.
  * @param section - Grammar section name for the message.
  * @param kind - Declaration kind for the message.
  * @param issues - Issue list to append to.
  */
-function reportDuplicateNames(names, section, kind, issues) {
+function reportDuplicateDefinitions(definitions, section, kind, issues) {
     const seen = new Set();
     const reported = new Set();
-    for (const name of names) {
-        if (seen.has(name) && !reported.has(name)) {
+    for (const definition of definitions) {
+        if (seen.has(definition.name) && !reported.has(definition.name)) {
             issues.push({
                 severity: 'warning',
-                message: `duplicate ${section} ${kind} ${JSON.stringify(name)}; `
+                message: `duplicate ${section} ${kind} ${JSON.stringify(definition.name)}; `
                     + `the later definition overrides the earlier one`,
+                location: definition.location,
             });
-            reported.add(name);
+            reported.add(definition.name);
         }
-        seen.add(name);
+        seen.add(definition.name);
     }
 }
 /**
@@ -13612,6 +13741,7 @@ function validateTransformProductionExists(rule, bnfProductionNames, issues) {
         issues.push({
             severity: 'error',
             message: `transform rule for unknown production ${JSON.stringify(rule.production)}`,
+            location: rule.location ?? null,
         });
     }
 }
@@ -13629,18 +13759,20 @@ function syntheticRepeatPrefix(name) {
  * Validates one transform expression against the grammar AST schema.
  *
  * @param grammar - Parsed grammar model.
- * @param expression - Transform expression to validate.
+ * @param alternative - Transform alternative owning the expression.
  * @param issues - Issue list to append to.
  */
-function validateTransformExpression(grammar, expression, issues) {
+function validateTransformExpression(grammar, alternative, issues) {
+    const expression = alternative.expression;
+    const location = alternative.location ?? null;
     switch (expression.kind) {
         case 'build':
-            validateAstTarget(grammar, expression.typeName, expression.variant, issues);
+            validateAstTarget(grammar, expression.typeName, expression.variant, location, issues);
             break;
         case 'foldLeft':
         case 'foldRight':
         case 'flatten':
-            validateAstTarget(grammar, expression.typeName, expression.variant, issues);
+            validateAstTarget(grammar, expression.typeName, expression.variant, location, issues);
             break;
     }
 }
@@ -13650,13 +13782,15 @@ function validateTransformExpression(grammar, expression, issues) {
  * @param grammar - Parsed grammar model.
  * @param typeName - AST type name from a transform expression.
  * @param variant - AST variant label from a transform expression.
+ * @param location - Source span of the transform alternative.
  * @param issues - Issue list to append to.
  */
-function validateAstTarget(grammar, typeName, variant, issues) {
+function validateAstTarget(grammar, typeName, variant, location, issues) {
     if (grammar.astSchema === null) {
         issues.push({
             severity: 'error',
             message: `transform references ${typeName}.${variant} but the grammar has no ast section`,
+            location,
         });
         return;
     }
@@ -13665,6 +13799,7 @@ function validateAstTarget(grammar, typeName, variant, issues) {
         issues.push({
             severity: 'error',
             message: `transform references undefined ast type ${JSON.stringify(typeName)}`,
+            location,
         });
         return;
     }
@@ -13673,6 +13808,7 @@ function validateAstTarget(grammar, typeName, variant, issues) {
         issues.push({
             severity: 'error',
             message: `transform references ${typeName}.${variant} which is not declared in ast`,
+            location,
         });
     }
 }
@@ -13703,11 +13839,12 @@ function collectAstVariants(expression) {
  *
  * @param grammar - Parsed grammar model.
  * @param rule - Parent production transform rule.
- * @param expression - Transform expression for one alternative.
+ * @param alternative - Transform alternative containing the pass expression.
  * @param bnfProductions - Desugared BNF productions.
  * @param issues - Issue list to append to.
  */
-function collectPassCollapseWarnings(grammar, rule, expression, bnfProductions, issues) {
+function collectPassCollapseWarnings(grammar, rule, alternative, bnfProductions, issues) {
+    const expression = alternative.expression;
     if (expression.kind !== 'pass') {
         return;
     }
@@ -13730,6 +13867,7 @@ function collectPassCollapseWarnings(grammar, rule, expression, bnfProductions,
         message: `pass(${expression.reference}) on ${rule.production} binds ${boundSymbol} `
             + `which has no transform rule and can match a single terminal; `
             + `add a transform for ${boundSymbol} or use build`,
+        location: alternative.location ?? null,
     });
 }
 /**
@@ -13786,14 +13924,19 @@ function isTerminalSymbol(symbol) {
     return symbol?.kind === 'terminal' || symbol?.kind === 'token';
 }
 /**
- * Formats validation issues as stderr warning or error lines.
+ * Formats validation issues as stderr diagnostic lines.
  *
  * @param issues - Validation issues to format.
+ * @param options - Optional grammar path and source text for line numbers.
  */
-function formatTableValidationIssues(issues) {
-    return issues.map((issue) => issue.severity === 'error'
-        ? `error: ${issue.message}`
-        : `warning: ${issue.message}`);
+function formatTableValidationIssues(issues, options = {}) {
+    return issues.map((issue) => formatDiagnostic({
+        severity: issue.severity,
+        message: issue.message,
+        path: options.path,
+        source: options.source,
+        location: issue.location,
+    }));
 }
 
 /**
@@ -13829,6 +13972,58 @@ function parseContextFromSources(options) {
     throw new ParseContextError('required: grammar source or table JSON');
 }
 
+/**
+ * Rewrites a thrown source error into a positioned CLI diagnostic error.
+ *
+ * @param error - Thrown value from grammar or input reading.
+ * @param path - Source file path.
+ * @param source - Full source text used for line/column mapping.
+ * @returns Positioned ParserLrError when the failure has an offset; otherwise the original value.
+ */
+function locateSourceError(error, path, source) {
+    const offset = sourceErrorOffset(error);
+    if (offset === null) {
+        return error;
+    }
+    return new ParserLrError(formatDiagnostic({
+        severity: 'error',
+        message: stripEmbeddedOffset(errorMessage(error)),
+        path,
+        source,
+        offset,
+    }));
+}
+/**
+ * Returns a source offset from a known offset-bearing error.
+ *
+ * @param error - Thrown value to inspect.
+ */
+function sourceErrorOffset(error) {
+    if (error instanceof ReadGrammarError || error instanceof LexerError) {
+        return error.offset;
+    }
+    return null;
+}
+/**
+ * Returns a human-readable message from a thrown value.
+ *
+ * @param error - Thrown value.
+ */
+function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+/**
+ * Removes an embedded `at offset N` suffix so the diagnostic formatter owns the position.
+ *
+ * @param message - Original error message.
+ */
+function stripEmbeddedOffset(message) {
+    return message.replace(/\s+at offset \d+\s*$/, '');
+}
+
 /**
  * Reads a UTF-8 text file from disk.
  *
@@ -13892,11 +14087,21 @@ function registerParseCommand(program) {
         }
         const context = await loadContextFromPaths(options);
         logProgress(`lexing ${options.input}`);
-        const tokens = await context.lexChunkStreamAsync(readTextChunks(options.input));
+        const tokens = await lexInputFile(context, options.input);
         logProgress('parsing');
-        const tree = context.parse(tokens);
+        const result = context.parseResult(tokens);
+        if (result.tree === null) {
+            const source = await readTextFile(options.input);
+            throw new ParserLrError(formatDiagnostic({
+                severity: 'error',
+                message: result.errorMessage ?? 'Parse failed',
+                path: options.input,
+                source,
+                offset: result.errorOffset,
+            }));
+        }
         logProgress(`formatting output (${options.format})`);
-        const output = formatParseOutput(tree, options.format);
+        const output = formatParseOutput(result.tree, options.format);
         // Write output to disk or stdout.
         if (options.output !== undefined) {
             logProgress(`writing ${options.output}`);
@@ -13908,6 +14113,21 @@ function registerParseCommand(program) {
         }
     });
 }
+/**
+ * Lexes an input file and rewrites offset-bearing lexer failures with line numbers.
+ *
+ * @param context - Loaded parse context.
+ * @param path - Input file path.
+ */
+async function lexInputFile(context, path) {
+    try {
+        return await context.lexChunkStreamAsync(readTextChunks(path));
+    }
+    catch (error) {
+        const source = await readTextFile(path);
+        throw locateSourceError(error, path, source);
+    }
+}
 /**
  * Reads grammar or table files and builds a parse context.
  *
@@ -13918,8 +14138,13 @@ async function loadContextFromPaths(options) {
     if (options.grammar !== undefined) {
         logProgress(`reading grammar ${options.grammar}`);
         const grammarSource = await readTextFile(options.grammar);
-        logProgress('building parse table');
-        return parseContextFromGrammar(grammarSource);
+        try {
+            logProgress('building parse table');
+            return parseContextFromGrammar(grammarSource);
+        }
+        catch (error) {
+            throw locateSourceError(error, options.grammar, grammarSource);
+        }
     }
     logProgress(`reading table ${options.table}`);
     const tableJson = await readTextFile(options.table);
@@ -13945,9 +14170,9 @@ function registerTableCommands(program) {
         .action(async (options) => {
         logProgress(`reading grammar ${options.grammar}`);
         const grammarSource = await readTextFile(options.grammar);
+        const grammar = readGrammarAtPath(options.grammar, grammarSource);
         logProgress(`building ${options.algorithm} parse table`);
-        const grammar = readGrammar(grammarSource);
-        writeGrammarValidationMessages(grammar, false);
+        writeGrammarValidationMessages(grammar, options.grammar, grammarSource, false);
         const context = parseContextFromSources({
             grammarSource,
             algorithm: options.algorithm,
@@ -13976,27 +14201,45 @@ function registerTableCommands(program) {
         .action(async (options) => {
         logProgress(`reading grammar ${options.grammar}`);
         const grammarSource = await readTextFile(options.grammar);
-        const grammar = readGrammar(grammarSource);
-        const exitCode = writeGrammarValidationMessages(grammar, options.strict === true);
+        const grammar = readGrammarAtPath(options.grammar, grammarSource);
+        const exitCode = writeGrammarValidationMessages(grammar, options.grammar, grammarSource, options.strict === true);
         process.exitCode = exitCode;
     });
 }
+/**
+ * Parses a grammar file and rewrites offset-bearing failures with line numbers.
+ *
+ * @param path - Grammar file path.
+ * @param source - Grammar file text.
+ */
+function readGrammarAtPath(path, source) {
+    try {
+        return readGrammar(source);
+    }
+    catch (error) {
+        throw locateSourceError(error, path, source);
+    }
+}
 /**
  * Writes grammar validation messages to stderr and returns a process exit code.
  *
  * @param grammar - Parsed grammar model.
+ * @param path - Grammar file path for diagnostics.
+ * @param source - Grammar file text for line/column mapping.
  * @param strict - Whether warnings should fail validation.
  */
-function writeGrammarValidationMessages(grammar, strict) {
+function writeGrammarValidationMessages(grammar, path, source, strict) {
     const issues = validateGrammarTable(grammar);
     let hasError = false;
     let hasWarning = false;
-    for (const line of formatTableValidationIssues(issues)) {
+    for (const line of formatTableValidationIssues(issues, { path, source })) {
         process.stderr.write(`${line}\n`);
-        if (line.startsWith('error:')) {
+    }
+    for (const issue of issues) {
+        if (issue.severity === 'error') {
             hasError = true;
         }
-        if (line.startsWith('warning:')) {
+        if (issue.severity === 'warning') {
             hasWarning = true;
         }
     }