@usearazzo/validator 0.0.0-stage → 1.0.1-alpha.6

package/src/validators/validate.cjs

@@ -0,0 +1,121 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.defaultLanguageServiceContext = void 0;
+exports.validate = validate;
+var _vscodeLanguageserverTypes = require("vscode-languageserver-types");
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _apiLanguageservice = require("@speclynx/api-languageservice");
+var _ramda = require("ramda");
+var _jsonSchemaProvider = require("./json-schema-provider.cjs");
+/**
+ * Default language service context for validation.
+ *
+ * Controls validation behavior: semantic validation, reference validation and
+ * semantic linting are enabled, JSON Schema validation is opt-in.
+ *
+ * @public
+ */
+const defaultLanguageServiceContext = exports.defaultLanguageServiceContext = {
+  logLevel: _apiLanguageservice.LogLevel.NONE,
+  defaultContentLanguage: {
+    namespace: 'arazzo',
+    version: '1.0.1',
+    mediaType: _apidomNsArazzo.mediaTypes.findBy('1.0.1')
+  },
+  // the language service registers no providers of its own, so each Arazzo version whose JSON
+  // Schema should be checked needs one here; a version without one is silently skipped
+  validatorProviders: [new _jsonSchemaProvider.Arazzo1JsonSchemaValidationProvider(), new _jsonSchemaProvider.Arazzo11JsonSchemaValidationProvider()],
+  // semantic validation, reference validation and semantic linting are always
+  // on, while JSON Schema (AJV) validation is opt-in. `betterAjvErrors` is kept
+  // on so opting in also gets the friendlier AJV messages.
+  validationContext: {
+    jsonSchemaValidation: false,
+    semanticValidation: true,
+    referenceValidation: true,
+    semanticLinting: true,
+    betterAjvErrors: true
+  },
+  parseContext: {
+    // regex patterns, not glob strings - picomatch's glob matching never matches a dotfile
+    // basename (e.g. .petstore.yaml) without `dot: true`, which FileResolver does not set,
+    // and `*` would admit any file at all. FileResolver accepts RegExp at runtime even though
+    // api-languageservice types the option as string[].
+    fileAllowList: [/\.json$/i, /\.ya?ml$/i],
+    arazzo: {
+      sourceDescriptionsResolution: true
+    }
+  }
+};
+
+/**
+ * Validates an Arazzo Document from a TextDocument.
+ *
+ * This is a lower-level API for advanced use cases such as IDE integrations
+ * or when you already have document content in memory.
+ *
+ * @param textDocument - The TextDocument containing the Arazzo Document content
+ * @param context - Optional language service context override (deep merged with defaults)
+ * @returns Promise resolving to an array of Diagnostic objects
+ *
+ * @example
+ * Basic usage
+ * ```typescript
+ * import { validate, TextDocument, DiagnosticSeverity, ARAZZO_LANGUAGE_ID, DEFAULT_DOCUMENT_VERSION } from '@usearazzo/validator';
+ *
+ * const textDocument = TextDocument.create(
+ *   'file:///path/to/arazzo.yaml',
+ *   ARAZZO_LANGUAGE_ID,
+ *   DEFAULT_DOCUMENT_VERSION,
+ *   content
+ * );
+ * const diagnostics = await validate(textDocument);
+ * const errors = diagnostics.filter((d) => d.severity === DiagnosticSeverity.Error);
+ * ```
+ *
+ * @example
+ * Enable JSON Schema validation (opt-in)
+ * ```typescript
+ * const diagnostics = await validate(textDocument, {
+ *   validationContext: { jsonSchemaValidation: true }
+ * });
+ * ```
+ * @public
+ */
+async function validate(textDocument, context = {}) {
+  const content = textDocument.getText();
+  // classify with the language service's own detector so the two cannot diverge.
+  // `defaultContentLanguage` is deliberately not passed - it would make arrays,
+  // empty files and plain objects fall back to Arazzo.
+  const {
+    namespace
+  } = await (0, _apiLanguageservice.findNamespace)(content);
+  if (namespace !== 'arazzo') {
+    const lastChar = textDocument.positionAt(content.length);
+    return [{
+      range: {
+        start: {
+          line: 0,
+          character: 0
+        },
+        end: {
+          line: lastChar.line,
+          character: lastChar.character
+        }
+      },
+      message: 'Document content is not recognized as an Arazzo Specification',
+      severity: _vscodeLanguageserverTypes.DiagnosticSeverity.Error,
+      code: _apiLanguageservice.ApilintCodes.ARAZZO_NOT_DETECTED,
+      source: 'apilint'
+    }];
+  }
+  const mergedContext = (0, _ramda.mergeDeepRight)(defaultLanguageServiceContext, context);
+  const languageService = (0, _apiLanguageservice.getLanguageService)(mergedContext);
+  try {
+    return await languageService.doValidation(textDocument);
+  } finally {
+    languageService.terminate();
+  }
+}

package/src/validators/validate.mjs

@@ -0,0 +1,114 @@
+import { DiagnosticSeverity } from 'vscode-languageserver-types';
+import { mediaTypes } from '@speclynx/apidom-ns-arazzo-1';
+import { getLanguageService, findNamespace, ApilintCodes, LogLevel } from '@speclynx/api-languageservice';
+import { mergeDeepRight } from 'ramda';
+import { Arazzo1JsonSchemaValidationProvider, Arazzo11JsonSchemaValidationProvider } from "./json-schema-provider.mjs";
+/**
+ * Default language service context for validation.
+ *
+ * Controls validation behavior: semantic validation, reference validation and
+ * semantic linting are enabled, JSON Schema validation is opt-in.
+ *
+ * @public
+ */
+export const defaultLanguageServiceContext = {
+  logLevel: LogLevel.NONE,
+  defaultContentLanguage: {
+    namespace: 'arazzo',
+    version: '1.0.1',
+    mediaType: mediaTypes.findBy('1.0.1')
+  },
+  // the language service registers no providers of its own, so each Arazzo version whose JSON
+  // Schema should be checked needs one here; a version without one is silently skipped
+  validatorProviders: [new Arazzo1JsonSchemaValidationProvider(), new Arazzo11JsonSchemaValidationProvider()],
+  // semantic validation, reference validation and semantic linting are always
+  // on, while JSON Schema (AJV) validation is opt-in. `betterAjvErrors` is kept
+  // on so opting in also gets the friendlier AJV messages.
+  validationContext: {
+    jsonSchemaValidation: false,
+    semanticValidation: true,
+    referenceValidation: true,
+    semanticLinting: true,
+    betterAjvErrors: true
+  },
+  parseContext: {
+    // regex patterns, not glob strings - picomatch's glob matching never matches a dotfile
+    // basename (e.g. .petstore.yaml) without `dot: true`, which FileResolver does not set,
+    // and `*` would admit any file at all. FileResolver accepts RegExp at runtime even though
+    // api-languageservice types the option as string[].
+    fileAllowList: [/\.json$/i, /\.ya?ml$/i],
+    arazzo: {
+      sourceDescriptionsResolution: true
+    }
+  }
+};
+
+/**
+ * Validates an Arazzo Document from a TextDocument.
+ *
+ * This is a lower-level API for advanced use cases such as IDE integrations
+ * or when you already have document content in memory.
+ *
+ * @param textDocument - The TextDocument containing the Arazzo Document content
+ * @param context - Optional language service context override (deep merged with defaults)
+ * @returns Promise resolving to an array of Diagnostic objects
+ *
+ * @example
+ * Basic usage
+ * ```typescript
+ * import { validate, TextDocument, DiagnosticSeverity, ARAZZO_LANGUAGE_ID, DEFAULT_DOCUMENT_VERSION } from '@usearazzo/validator';
+ *
+ * const textDocument = TextDocument.create(
+ *   'file:///path/to/arazzo.yaml',
+ *   ARAZZO_LANGUAGE_ID,
+ *   DEFAULT_DOCUMENT_VERSION,
+ *   content
+ * );
+ * const diagnostics = await validate(textDocument);
+ * const errors = diagnostics.filter((d) => d.severity === DiagnosticSeverity.Error);
+ * ```
+ *
+ * @example
+ * Enable JSON Schema validation (opt-in)
+ * ```typescript
+ * const diagnostics = await validate(textDocument, {
+ *   validationContext: { jsonSchemaValidation: true }
+ * });
+ * ```
+ * @public
+ */
+export async function validate(textDocument, context = {}) {
+  const content = textDocument.getText();
+  // classify with the language service's own detector so the two cannot diverge.
+  // `defaultContentLanguage` is deliberately not passed - it would make arrays,
+  // empty files and plain objects fall back to Arazzo.
+  const {
+    namespace
+  } = await findNamespace(content);
+  if (namespace !== 'arazzo') {
+    const lastChar = textDocument.positionAt(content.length);
+    return [{
+      range: {
+        start: {
+          line: 0,
+          character: 0
+        },
+        end: {
+          line: lastChar.line,
+          character: lastChar.character
+        }
+      },
+      message: 'Document content is not recognized as an Arazzo Specification',
+      severity: DiagnosticSeverity.Error,
+      code: ApilintCodes.ARAZZO_NOT_DETECTED,
+      source: 'apilint'
+    }];
+  }
+  const mergedContext = mergeDeepRight(defaultLanguageServiceContext, context);
+  const languageService = getLanguageService(mergedContext);
+  try {
+    return await languageService.doValidation(textDocument);
+  } finally {
+    languageService.terminate();
+  }
+}

package/types/validator.d.ts

@@ -0,0 +1,170 @@
+import { ApiDOMError } from '@speclynx/apidom-error';
+import { ApiDOMErrorOptions } from '@speclynx/apidom-error';
+import { ApiDOMReferenceResolveOptions } from '@speclynx/apidom-reference/configuration/empty';
+import { Diagnostic } from 'vscode-languageserver-types';
+import { DiagnosticSeverity } from 'vscode-languageserver-types';
+import { LanguageServiceContext } from '@speclynx/api-languageservice';
+import type { PartialDeep } from 'type-fest';
+import { Resolver } from '@speclynx/apidom-reference/configuration/empty';
+import { ResolveStrategy } from '@speclynx/apidom-reference/configuration/empty';
+import { TextDocument } from 'vscode-languageserver-textdocument';
+
+/**
+ * Language ID for Arazzo documents used with TextDocument.
+ *
+ * @public
+ */
+export declare const ARAZZO_LANGUAGE_ID = "apidom";
+
+/**
+ * Creates a TextDocument for Arazzo validation.
+ *
+ * @param uri - The document URI
+ * @param content - The document content
+ * @returns A TextDocument instance
+ * @public
+ */
+export declare function createTextDocument(uri: string, content: string): TextDocument;
+
+/**
+ * Default document version for TextDocument instances.
+ *
+ * @public
+ */
+export declare const DEFAULT_DOCUMENT_VERSION = 1;
+
+/**
+ * Default resolve options for URI resolution in validateURI.
+ *
+ * These options control how files and URLs are fetched when validating
+ * Arazzo documents from URIs.
+ *
+ * @public
+ */
+export declare const defaultArazzoResolveOptions: {
+    baseURI?: string | undefined;
+    resolvers?: Resolver[] | undefined;
+    resolverOpts?: {
+        [x: string]: any;
+    } | undefined;
+    strategies?: ResolveStrategy[] | undefined;
+    strategyOpts?: {
+        [x: string]: any;
+    } | undefined;
+    internal?: boolean | undefined;
+    external?: boolean | undefined;
+    maxDepth?: number | undefined;
+} | undefined;
+
+/**
+ * Default language service context for validation.
+ *
+ * Controls validation behavior: semantic validation, reference validation and
+ * semantic linting are enabled, JSON Schema validation is opt-in.
+ *
+ * @public
+ */
+export declare const defaultLanguageServiceContext: Partial<LanguageServiceContext>;
+
+export { Diagnostic }
+
+export { DiagnosticSeverity }
+
+export { LanguageServiceContext }
+
+export { TextDocument }
+
+/**
+ * Validates an Arazzo Document from a TextDocument.
+ *
+ * This is a lower-level API for advanced use cases such as IDE integrations
+ * or when you already have document content in memory.
+ *
+ * @param textDocument - The TextDocument containing the Arazzo Document content
+ * @param context - Optional language service context override (deep merged with defaults)
+ * @returns Promise resolving to an array of Diagnostic objects
+ *
+ * @example
+ * Basic usage
+ * ```typescript
+ * import { validate, TextDocument, DiagnosticSeverity, ARAZZO_LANGUAGE_ID, DEFAULT_DOCUMENT_VERSION } from '@usearazzo/validator';
+ *
+ * const textDocument = TextDocument.create(
+ *   'file:///path/to/arazzo.yaml',
+ *   ARAZZO_LANGUAGE_ID,
+ *   DEFAULT_DOCUMENT_VERSION,
+ *   content
+ * );
+ * const diagnostics = await validate(textDocument);
+ * const errors = diagnostics.filter((d) => d.severity === DiagnosticSeverity.Error);
+ * ```
+ *
+ * @example
+ * Enable JSON Schema validation (opt-in)
+ * ```typescript
+ * const diagnostics = await validate(textDocument, {
+ *   validationContext: { jsonSchemaValidation: true }
+ * });
+ * ```
+ * @public
+ */
+export declare function validate(textDocument: TextDocument, context?: PartialDeep<LanguageServiceContext>): Promise<Diagnostic[]>;
+
+/**
+ * Error thrown by `validateURI` when the document cannot be fetched. Problems
+ * found in the document itself are reported as diagnostics, not thrown. The
+ * original error is available via the `cause` property.
+ * @public
+ */
+export declare class ValidateError extends ApiDOMError {
+    constructor(message?: string, options?: ApiDOMErrorOptions);
+}
+
+/**
+ * Validates an Arazzo Document from a URI (file path or HTTP(S) URL).
+ *
+ * This is the primary API for validation. It fetches the document from the
+ * specified URI and performs JSON Schema validation, semantic validation,
+ * and linting.
+ *
+ * @param uri - The file system path or HTTP(S) URL to the Arazzo Document
+ * @param context - Optional language service context override (deep merged with defaults)
+ * @param resolveOptions - Optional resolve options for fetching the URI
+ * @returns Promise resolving to an array of Diagnostic objects
+ * @throws ValidateError - When the document cannot be fetched. The original error is available via the `cause` property.
+ *
+ * @example
+ * Validate from file
+ * ```typescript
+ * import { validateURI, DiagnosticSeverity } from '@usearazzo/validator';
+ *
+ * const diagnostics = await validateURI('/path/to/arazzo.yaml');
+ * const errors = diagnostics.filter((d) => d.severity === DiagnosticSeverity.Error);
+ * ```
+ *
+ * @example
+ * Validate from URL
+ * ```typescript
+ * const diagnostics = await validateURI('https://example.com/arazzo.yaml');
+ * ```
+ *
+ * @example
+ * Validate with custom context
+ * ```typescript
+ * const diagnostics = await validateURI('/path/to/arazzo.yaml', {
+ *   validationContext: { jsonSchemaValidation: true }
+ * });
+ * ```
+ *
+ * @example
+ * Validate with custom resolve options
+ * ```typescript
+ * const diagnostics = await validateURI('/path/to/arazzo.yaml', {}, {
+ *   resolverOpts: { timeout: 10000 }
+ * });
+ * ```
+ * @public
+ */
+export declare function validateURI(uri: string, context?: PartialDeep<LanguageServiceContext>, resolveOptions?: PartialDeep<ApiDOMReferenceResolveOptions>): Promise<Diagnostic[]>;
+
+export { }