feat(core): add error line number for yaml and json ruleset validation (#2945)

* feat(core): add error line number for yaml and json ruleset validation

* feat(core): arazzo schema removed from stage

Author: tomek-tursa-sb

packages/cli/src/commands/__tests__/lint.test.ts

@@ -235,6 +235,26 @@ describe('lint', () => {
     expect(process.stderr.write).nthCalledWith(5, `Error #3: ${chalk.red('original exception')}\n`);
   });
 
+  it('prefixes ruleset errors that carry source and range with file:line:col', async () => {
+    (lint as jest.Mock).mockReset();
+    const errorWithLocation = Object.assign(new Error('invalid severity'), {
+      source: '/tmp/ruleset.yaml',
+      range: { start: { line: 7, character: 14 }, end: { line: 7, character: 22 } },
+    });
+    const errorWithSourceOnly = Object.assign(new Error('missing rule'), {
+      source: '/tmp/ruleset.yaml',
+    });
+    (lint as jest.Mock).mockRejectedValueOnce(new AggregateError([errorWithLocation, errorWithSourceOnly]));
+
+    await run(`lint ./__fixtures__/empty-oas2-document.json`);
+
+    expect(process.stderr.write).nthCalledWith(
+      3,
+      `Error #1: /tmp/ruleset.yaml:8:15 — ${chalk.red('invalid severity')}\n`,
+    );
+    expect(process.stderr.write).nthCalledWith(4, `Error #2: /tmp/ruleset.yaml — ${chalk.red('missing rule')}\n`);
+  });
+
   it('given verbose flag, prints each error together with their stacks', async () => {
     (lint as jest.Mock).mockReset();
     (lint as jest.Mock).mockRejectedValueOnce(
@@ -250,13 +270,13 @@ describe('lint', () => {
     expect(process.stderr.write).nthCalledWith(2, `Error #1: ${chalk.red('some unhandled exception')}\n`);
     expect(process.stderr.write).nthCalledWith(
       3,
-      expect.stringContaining(`packages/cli/src/commands/__tests__/lint.test.ts:242`),
+      expect.stringContaining(`packages/cli/src/commands/__tests__/lint.test.ts:262`),
     );
 
     expect(process.stderr.write).nthCalledWith(4, `Error #2: ${chalk.red('another one')}\n`);
     expect(process.stderr.write).nthCalledWith(
       5,
-      expect.stringContaining(`packages/cli/src/commands/__tests__/lint.test.ts:243`),
+      expect.stringContaining(`packages/cli/src/commands/__tests__/lint.test.ts:263`),
     );
 
     expect(process.stderr.write).nthCalledWith(6, `Error #3: ${chalk.red('original exception')}\n`);

packages/cli/src/commands/lint.ts

@@ -252,10 +252,11 @@ const fail = (error: Error | ErrorWithCause<unknown> | AggregateError, verbose:
   for (const [i, error] of errors.entries()) {
     const actualError: unknown = isError(error) && 'cause' in error ? (error as ErrorWithCause<unknown>).cause : error;
     const message = isError(actualError) ? actualError.message : String(actualError);
+    const location = formatErrorLocation(actualError);
 
     const info = `Error #${i + 1}: `;
 
-    process.stderr.write(`${info}${chalk.red(message)}\n`);
+    process.stderr.write(`${info}${location}${chalk.red(message)}\n`);
 
     if (verbose && isError(actualError)) {
       process.stderr.write(`${chalk.red(printErrorStacks(actualError, info.length))}\n`);
@@ -265,6 +266,19 @@ const fail = (error: Error | ErrorWithCause<unknown> | AggregateError, verbose:
   process.exit(2);
 };
 
+function formatErrorLocation(error: unknown): string {
+  if (typeof error !== 'object' || error === null) return '';
+  const source = (error as { source?: unknown }).source;
+  if (typeof source !== 'string') return '';
+
+  const range = (error as { range?: { start?: { line?: unknown; character?: unknown } } }).range;
+  if (typeof range?.start?.line === 'number' && typeof range.start.character === 'number') {
+    return `${source}:${range.start.line + 1}:${range.start.character + 1} — `;
+  }
+
+  return `${source} — `;
+}
+
 function getWidth(ratio: number): number {
   return Math.min(20, Math.floor(ratio * process.stderr.columns));
 }

packages/cli/src/services/linter/utils/getRuleset.ts

@@ -1,5 +1,6 @@
 import { Optional } from '@stoplight/types';
-import { Ruleset, RulesetDefinition } from '@stoplight/spectral-core';
+import { Ruleset, RulesetDefinition, RulesetSourceContext } from '@stoplight/spectral-core';
+import { Json, Yaml } from '@stoplight/spectral-parsers';
 import * as fs from 'fs';
 import * as path from '@stoplight/path';
 import * as process from 'process';
@@ -43,9 +44,13 @@ export async function getRuleset(rulesetFile: Optional<string>): Promise<Ruleset
   }
 
   let ruleset: string;
+  let sourceContext: RulesetSourceContext | undefined;
+  const originalRulesetFile = rulesetFile;
 
   try {
     if (await isBasicRuleset(rulesetFile)) {
+      sourceContext = await buildSourceContext(originalRulesetFile);
+
       const migratedRuleset = await migrateRuleset(rulesetFile, {
         format: 'esm',
         fs,
@@ -76,9 +81,36 @@ export async function getRuleset(rulesetFile: Optional<string>): Promise<Ruleset
   return new Ruleset(load(ruleset, rulesetFile), {
     severity: 'recommended',
     source: rulesetFile,
+    sourceContext,
   });
 }
 
+async function buildSourceContext(rulesetFile: string): Promise<RulesetSourceContext | undefined> {
+  try {
+    const input = await fs.promises.readFile(rulesetFile, 'utf8');
+
+    if (path.extname(rulesetFile) === '.json') {
+      const parserResult = Json.parse(input);
+      return {
+        source: rulesetFile,
+        getLocationForJsonPath(jsonPath) {
+          return Json.getLocationForJsonPath(parserResult, jsonPath);
+        },
+      };
+    }
+
+    const parserResult = Yaml.parse(input);
+    return {
+      source: rulesetFile,
+      getLocationForJsonPath(jsonPath) {
+        return Yaml.getLocationForJsonPath(parserResult, jsonPath);
+      },
+    };
+  } catch {
+    return undefined;
+  }
+}
+
 function load(source: string, uri: string): RulesetDefinition {
   const actualUri = path.isURL(uri) ? uri.replace(/^https?:\//, '') : uri;
   // we could use plain `require`, but this approach has a number of benefits:

packages/core/src/ruleset/index.ts

@@ -1,4 +1,4 @@
-export { assertValidRuleset, RulesetValidationError } from './validation/index';
+export { assertValidRuleset, RulesetSourceContext, RulesetValidationError } from './validation/index';
 export { getDiagnosticSeverity } from './utils/severity';
 export { createRulesetFunction, SchemaDefinition as RulesetFunctionSchemaDefinition } from './function';
 export { Format } from './format';

packages/core/src/ruleset/ruleset.ts

@@ -11,7 +11,7 @@ import type {
   RulesetOverridesDefinition,
   Stringifable,
 } from './types';
-import { assertValidRuleset } from './validation/index';
+import { assertValidRuleset, RulesetSourceContext } from './validation/index';
 import { mergeRule } from './mergers/rules';
 import { DEFAULT_PARSER_OPTIONS, getDiagnosticSeverity } from '..';
 import { mergeRulesets } from './mergers/rulesets';
@@ -26,6 +26,7 @@ const DEFAULT_RULESET_FILE = /^\.?spectral\.(ya?ml|json|m?js)$/;
 type RulesetContext = {
   readonly severity?: FileRulesetSeverityDefinition;
   readonly source?: string;
+  readonly sourceContext?: RulesetSourceContext;
   readonly [STACK_SYMBOL]?: Map<RulesetDefinition, Ruleset>;
   readonly [EXPLICIT_SEVERITY]?: boolean;
 };
@@ -63,10 +64,10 @@ export class Ruleset {
     if (isPlainObject(maybeDefinition) && 'extends' in maybeDefinition) {
       const { extends: _, ...def } = maybeDefinition;
       // we don't want to validate extends - this is going to happen later on (line 29)
-      assertValidRuleset({ extends: [], ...def }, 'js');
+      assertValidRuleset({ extends: [], ...def }, 'js', context?.sourceContext);
       definition = maybeDefinition as RulesetDefinition;
     } else {
-      assertValidRuleset(maybeDefinition, 'js');
+      assertValidRuleset(maybeDefinition, 'js', context?.sourceContext);
       definition = maybeDefinition;
     }
 

packages/core/src/ruleset/validation/__tests__/validation.test.ts

@@ -1295,3 +1295,80 @@ describe('JSON Ruleset Validation', () => {
     ).toThrowAggregateError(new AggregateError(errors));
   });
 });
+
+describe('Ruleset Validation source context', () => {
+  it('attaches range and source to validation errors when sourceContext is provided', () => {
+    const sourceContext = {
+      source: '/tmp/ruleset.yaml',
+      getLocationForJsonPath(jsonPath: ReadonlyArray<string | number>) {
+        if (jsonPath.join('/') === 'rules/rule-with-invalid-enum/severity') {
+          return { range: { start: { line: 7, character: 14 }, end: { line: 7, character: 22 } } };
+        }
+        return undefined;
+      },
+    };
+
+    let caught: AggregateError | undefined;
+    try {
+      assertValidRuleset(invalidRuleset, 'js', sourceContext);
+    } catch (e) {
+      caught = e as AggregateError;
+    }
+
+    expect(caught).toBeInstanceOf(AggregateError);
+
+    const severityError = (caught as AggregateError).errors.find(
+      (e: RulesetValidationError) => e.code === 'invalid-severity',
+    ) as RulesetValidationError;
+    expect(severityError.source).toBe('/tmp/ruleset.yaml');
+    expect(severityError.range).toEqual({
+      start: { line: 7, character: 14 },
+      end: { line: 7, character: 22 },
+    });
+
+    const otherError = (caught as AggregateError).errors.find(
+      (e: RulesetValidationError) => e.code !== 'invalid-severity',
+    ) as RulesetValidationError;
+    expect(otherError.source).toBe('/tmp/ruleset.yaml');
+    expect(otherError.range).toBeUndefined();
+  });
+
+  it('attaches source to early-throw errors when sourceContext is provided', () => {
+    const sourceContext = {
+      source: '/tmp/ruleset.yaml',
+      getLocationForJsonPath() {
+        return { range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } } };
+      },
+    };
+
+    expect(() => assertValidRuleset(null, 'js', sourceContext)).toThrow(
+      expect.objectContaining({
+        code: 'invalid-ruleset-definition',
+        source: '/tmp/ruleset.yaml',
+      }),
+    );
+
+    expect(() => assertValidRuleset({}, 'js', sourceContext)).toThrow(
+      expect.objectContaining({
+        code: 'invalid-ruleset-definition',
+        source: '/tmp/ruleset.yaml',
+        range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
+      }),
+    );
+  });
+
+  it('leaves range and source undefined when sourceContext is omitted', () => {
+    let caught: AggregateError | undefined;
+    try {
+      assertValidRuleset(invalidRuleset, 'js');
+    } catch (e) {
+      caught = e as AggregateError;
+    }
+
+    expect(caught).toBeInstanceOf(AggregateError);
+    for (const e of (caught as AggregateError).errors as RulesetValidationError[]) {
+      expect(e.source).toBeUndefined();
+      expect(e.range).toBeUndefined();
+    }
+  });
+});

packages/core/src/ruleset/validation/assertions.ts

@@ -1,29 +1,38 @@
 import { isPlainObject } from '@stoplight/json';
 import { createValidator } from './ajv';
-import { convertAjvErrors, RulesetValidationError } from './errors';
+import { convertAjvErrors, RulesetSourceContext, RulesetValidationError } from './errors';
 import type { FileRuleDefinition, RuleDefinition, RulesetDefinition } from '../types';
 import AggregateError from 'es-aggregate-error';
 
 export function assertValidRuleset(
   ruleset: unknown,
   format: 'js' | 'json' = 'js',
+  sourceContext?: RulesetSourceContext,
 ): asserts ruleset is RulesetDefinition {
   if (!isPlainObject(ruleset)) {
-    throw new RulesetValidationError('invalid-ruleset-definition', 'Provided ruleset is not an object', []);
+    throw new RulesetValidationError(
+      'invalid-ruleset-definition',
+      'Provided ruleset is not an object',
+      [],
+      sourceContext === undefined ? undefined : { source: sourceContext.source },
+    );
   }
 
   if (!('rules' in ruleset) && !('extends' in ruleset) && !('overrides' in ruleset)) {
     throw new RulesetValidationError(
       'invalid-ruleset-definition',
       'Ruleset must have rules or extends or overrides defined',
       [],
+      sourceContext === undefined
+        ? undefined
+        : { source: sourceContext.source, range: sourceContext.getLocationForJsonPath([])?.range },
     );
   }
 
   const validate = createValidator(format);
 
   if (!validate(ruleset)) {
-    throw new AggregateError(convertAjvErrors(validate.errors ?? []));
+    throw new AggregateError(convertAjvErrors(validate.errors ?? [], sourceContext));
   }
 }
 

packages/core/src/ruleset/validation/errors.ts

@@ -1,5 +1,5 @@
 import type { ErrorObject } from 'ajv';
-import type { IDiagnostic, JsonPath } from '@stoplight/types';
+import type { IDiagnostic, IRange, JsonPath } from '@stoplight/types';
 import { isAggregateError } from '../../guards/isAggregateError';
 
 export type RulesetValidationErrorCode =
@@ -17,24 +17,40 @@ export type RulesetValidationErrorCode =
   | 'undefined-function'
   | 'undefined-alias';
 
+export type RulesetSourceContext = {
+  readonly source: string;
+  getLocationForJsonPath(path: JsonPath): { range: IRange } | undefined;
+};
+
 interface IRulesetValidationSingleError extends Pick<IDiagnostic, 'message' | 'path'> {
   readonly code: RulesetValidationErrorCode;
+  readonly range?: IRange;
+  readonly source?: string;
 }
 
 export class RulesetValidationError extends Error implements IRulesetValidationSingleError {
+  public readonly range?: IRange;
+  public readonly source?: string;
+
   constructor(
     public readonly code: RulesetValidationErrorCode,
     public readonly message: string,
     public readonly path: JsonPath,
+    location?: { range?: IRange; source?: string },
   ) {
     super(message);
+    this.range = location?.range;
+    this.source = location?.source;
   }
 }
 
 const RULE_INSTANCE_PATH = /^\/rules\/[^/]+/;
 const GENERIC_INSTANCE_PATH = /^\/(?:aliases|extends|overrides(?:\/\d+\/extends)?)/;
 
-export function convertAjvErrors(errors: ErrorObject[]): RulesetValidationError[] {
+export function convertAjvErrors(
+  errors: ErrorObject[],
+  sourceContext?: RulesetSourceContext,
+): RulesetValidationError[] {
   const sortedErrors = [...errors]
     .sort((errorA, errorB) => {
       const diff = errorA.instancePath.length - errorB.instancePath.length;
@@ -78,11 +94,18 @@ export function convertAjvErrors(errors: ErrorObject[]): RulesetValidationError[
 
   return filteredErrors.flatMap(error => {
     if (error.keyword === 'x-spectral-runtime') {
-      return flatErrors(error.params.errors);
+      const flat = flatErrors(error.params.errors);
+      const list = Array.isArray(flat) ? flat : [flat];
+      return list.map(e => enrichWithLocation(e, sourceContext));
     }
 
     const path = error.instancePath.slice(1).split('/');
-    return new RulesetValidationError(inferErrorCode(path, error.keyword), error.message ?? 'unknown error', path);
+    return new RulesetValidationError(
+      inferErrorCode(path, error.keyword),
+      error.message ?? 'unknown error',
+      path,
+      resolveLocation(path, sourceContext),
+    );
   });
 }
 
@@ -94,6 +117,31 @@ function flatErrors(error: RulesetValidationError | AggregateError): RulesetVali
   return error;
 }
 
+function resolveLocation(
+  path: JsonPath,
+  sourceContext: RulesetSourceContext | undefined,
+): { range?: IRange; source?: string } | undefined {
+  if (sourceContext === undefined) {
+    return undefined;
+  }
+
+  return {
+    source: sourceContext.source,
+    range: sourceContext.getLocationForJsonPath(path)?.range,
+  };
+}
+
+function enrichWithLocation(
+  error: RulesetValidationError,
+  sourceContext: RulesetSourceContext | undefined,
+): RulesetValidationError {
+  if (sourceContext === undefined || error.source !== undefined || error.range !== undefined) {
+    return error;
+  }
+
+  return new RulesetValidationError(error.code, error.message, error.path, resolveLocation(error.path, sourceContext));
+}
+
 function inferErrorCode(path: string[], keyword: string): RulesetValidationErrorCode {
   if (path.length === 0) {
     return 'generic-validation-error';

packages/core/src/ruleset/validation/index.ts

@@ -1,2 +1,2 @@
-export { RulesetValidationError, RulesetValidationErrorCode } from './errors';
+export { RulesetSourceContext, RulesetValidationError, RulesetValidationErrorCode } from './errors';
 export { assertValidRuleset } from './assertions';