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

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@usearazzo/validator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1-alpha.5",
+  "description": "Validator and linter for Arazzo documents: semantic validation, semantic linting, and opt-in JSON Schema validation.",
+  "keywords": [
+    "arazzo",
+    "arazzo-specification",
+    "validator",
+    "validation",
+    "linter",
+    "linting",
+    "workflow",
+    "workflows"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "provenance": false,
+    "tag": "latest"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.10.0"
+  },
+  "unpkg": "./dist/arazzo-validator.browser.min.js",
+  "main": "./src/index.cjs",
+  "exports": {
+    "types": "./types/validator.d.ts",
+    "import": "./src/index.mjs",
+    "require": "./src/index.cjs"
+  },
+  "types": "./types/validator.d.ts",
+  "scripts": {
+    "build": "npm run clean && run-p --max-parallel ${CPU_CORES:-2} typescript:declaration build:es build:cjs build:umd:browser",
+    "build:es": "cross-env BABEL_ENV=es babel src --out-dir src --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward'",
+    "build:cjs": "cross-env BABEL_ENV=cjs babel src --out-dir src --extensions '.ts' --out-file-extension '.cjs' --root-mode 'upward'",
+    "build:umd:browser": "cross-env BABEL_ENV=browser webpack --config config/webpack/browser.config.js --progress",
+    "lint": "eslint ./",
+    "lint:fix": "eslint ./ --fix",
+    "clean": "rimraf --glob 'src/**/*.mjs' 'src/**/*.cjs' 'test/**/*.mjs' ./dist ./types",
+    "typescript:check-types": "tsc --noEmit",
+    "typescript:declaration": "tsc -p tsconfig.declaration.json && api-extractor run -l -c ./config/api-extractor/api-extractor.json",
+    "test": "npm run build:es && cross-env BABEL_ENV=es babel test --out-dir test --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward' && cross-env NODE_ENV=test mocha",
+    "prepack": "copyfiles -u 2 ../../LICENSE . && copyfiles -u 2 ../../NOTICE .",
+    "postpack": "rimraf NOTICE LICENSE"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/usearazzo/arazzo-toolkit.git"
+  },
+  "homepage": "https://usearazzo.com/docs/validator/",
+  "author": "Vladimir Gorej <vladimir.gorej@gmail.com>",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@babel/runtime-corejs3": "^8.0.6",
+    "@speclynx/api-languageservice": "^2.13.2",
+    "@speclynx/apidom-error": "^5.2.6",
+    "@speclynx/apidom-ns-arazzo-1": "^5.2.6",
+    "@speclynx/apidom-reference": "^5.2.6",
+    "@usearazzo/parser": "1.0.1-alpha.5",
+    "ramda": "^0.32.0",
+    "type-fest": "^5.10.0",
+    "vscode-languageserver-textdocument": "^1.0.15",
+    "vscode-languageserver-types": "=3.18.3"
+  },
+  "files": [
+    "src/**/*.mjs",
+    "src/**/*.cjs",
+    "dist/",
+    "types/validator.d.ts",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "CHANGELOG.md"
+  ]
+}

package/src/document.cjs

@@ -0,0 +1,39 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.DEFAULT_DOCUMENT_VERSION = exports.ARAZZO_LANGUAGE_ID = void 0;
+Object.defineProperty(exports, "TextDocument", {
+  enumerable: true,
+  get: function () {
+    return _vscodeLanguageserverTextdocument.TextDocument;
+  }
+});
+exports.createTextDocument = createTextDocument;
+var _vscodeLanguageserverTextdocument = require("vscode-languageserver-textdocument");
+/**
+ * Language ID for Arazzo documents used with TextDocument.
+ *
+ * @public
+ */
+const ARAZZO_LANGUAGE_ID = exports.ARAZZO_LANGUAGE_ID = 'apidom';
+
+/**
+ * Default document version for TextDocument instances.
+ *
+ * @public
+ */
+const DEFAULT_DOCUMENT_VERSION = exports.DEFAULT_DOCUMENT_VERSION = 1;
+
+/**
+ * Creates a TextDocument for Arazzo validation.
+ *
+ * @param uri - The document URI
+ * @param content - The document content
+ * @returns A TextDocument instance
+ * @public
+ */
+function createTextDocument(uri, content) {
+  return _vscodeLanguageserverTextdocument.TextDocument.create(uri, ARAZZO_LANGUAGE_ID, DEFAULT_DOCUMENT_VERSION, content);
+}

package/src/document.mjs

@@ -0,0 +1,28 @@
+import { TextDocument } from 'vscode-languageserver-textdocument';
+export { TextDocument };
+
+/**
+ * Language ID for Arazzo documents used with TextDocument.
+ *
+ * @public
+ */
+export const ARAZZO_LANGUAGE_ID = 'apidom';
+
+/**
+ * Default document version for TextDocument instances.
+ *
+ * @public
+ */
+export const DEFAULT_DOCUMENT_VERSION = 1;
+
+/**
+ * Creates a TextDocument for Arazzo validation.
+ *
+ * @param uri - The document URI
+ * @param content - The document content
+ * @returns A TextDocument instance
+ * @public
+ */
+export function createTextDocument(uri, content) {
+  return TextDocument.create(uri, ARAZZO_LANGUAGE_ID, DEFAULT_DOCUMENT_VERSION, content);
+}

package/src/errors/ValidateError.cjs

@@ -0,0 +1,19 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _apidomError = require("@speclynx/apidom-error");
+/**
+ * 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
+ */
+class ValidateError extends _apidomError.ApiDOMError {
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+var _default = exports.default = ValidateError;

package/src/errors/ValidateError.mjs

@@ -0,0 +1,14 @@
+import { ApiDOMError } from '@speclynx/apidom-error';
+
+/**
+ * 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
+ */
+class ValidateError extends ApiDOMError {
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+export default ValidateError;

package/src/index.cjs

@@ -0,0 +1,77 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "ARAZZO_LANGUAGE_ID", {
+  enumerable: true,
+  get: function () {
+    return _document.ARAZZO_LANGUAGE_ID;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_DOCUMENT_VERSION", {
+  enumerable: true,
+  get: function () {
+    return _document.DEFAULT_DOCUMENT_VERSION;
+  }
+});
+Object.defineProperty(exports, "Diagnostic", {
+  enumerable: true,
+  get: function () {
+    return _vscodeLanguageserverTypes.Diagnostic;
+  }
+});
+Object.defineProperty(exports, "DiagnosticSeverity", {
+  enumerable: true,
+  get: function () {
+    return _vscodeLanguageserverTypes.DiagnosticSeverity;
+  }
+});
+Object.defineProperty(exports, "TextDocument", {
+  enumerable: true,
+  get: function () {
+    return _document.TextDocument;
+  }
+});
+Object.defineProperty(exports, "ValidateError", {
+  enumerable: true,
+  get: function () {
+    return _ValidateError.default;
+  }
+});
+Object.defineProperty(exports, "createTextDocument", {
+  enumerable: true,
+  get: function () {
+    return _document.createTextDocument;
+  }
+});
+Object.defineProperty(exports, "defaultArazzoResolveOptions", {
+  enumerable: true,
+  get: function () {
+    return _validateUri.defaultArazzoResolveOptions;
+  }
+});
+Object.defineProperty(exports, "defaultLanguageServiceContext", {
+  enumerable: true,
+  get: function () {
+    return _validate.defaultLanguageServiceContext;
+  }
+});
+Object.defineProperty(exports, "validate", {
+  enumerable: true,
+  get: function () {
+    return _validate.validate;
+  }
+});
+Object.defineProperty(exports, "validateURI", {
+  enumerable: true,
+  get: function () {
+    return _validateUri.validateURI;
+  }
+});
+var _vscodeLanguageserverTypes = require("vscode-languageserver-types");
+var _document = require("./document.cjs");
+var _ValidateError = _interopRequireDefault(require("./errors/ValidateError.cjs"));
+var _validate = require("./validators/validate.cjs");
+var _validateUri = require("./validators/validate-uri.cjs");

package/src/index.mjs

@@ -0,0 +1,6 @@
+import { DiagnosticSeverity, Diagnostic } from 'vscode-languageserver-types';
+export { Diagnostic, DiagnosticSeverity };
+export { TextDocument, ARAZZO_LANGUAGE_ID, DEFAULT_DOCUMENT_VERSION, createTextDocument } from "./document.mjs";
+export { default as ValidateError } from "./errors/ValidateError.mjs";
+export { validate, defaultLanguageServiceContext } from "./validators/validate.mjs";
+export { validateURI, defaultArazzoResolveOptions } from "./validators/validate-uri.mjs";

package/src/validators/json-schema-provider.cjs

@@ -0,0 +1,49 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Arazzo1JsonSchemaValidationProvider = exports.Arazzo11JsonSchemaValidationProvider = void 0;
+var _apiLanguageservice = require("@speclynx/api-languageservice");
+/**
+ * Custom JSON Schema validation provider that assigns proper diagnostic codes.
+ *
+ * Extends the base Arazzo1JsonSchemaValidationProvider to set 'json-schema'
+ * as the code for all diagnostics, making them identifiable in CLI output.
+ * Covers Arazzo 1.0.x documents.
+ *
+ * @internal
+ */
+class Arazzo1JsonSchemaValidationProvider extends _apiLanguageservice.Arazzo1JsonSchemaValidationProvider {
+  validate(jsonDocument, originalDocument, isYaml, diagnostics, validationContext) {
+    const startIndex = diagnostics.length;
+    super.validate(jsonDocument, originalDocument, isYaml, diagnostics, validationContext);
+
+    // assign 'json-schema' code only to diagnostics added by this provider
+    for (let i = startIndex; i < diagnostics.length; i++) {
+      diagnostics[i].code = 'json-schema';
+    }
+  }
+}
+
+/**
+ * The Arazzo 1.1.0 counterpart of {@link Arazzo1JsonSchemaValidationProvider}.
+ *
+ * The two upstream providers share no base that carries the Arazzo schema, so
+ * the 'json-schema' code assignment is repeated here rather than inherited.
+ *
+ * @internal
+ */
+exports.Arazzo1JsonSchemaValidationProvider = Arazzo1JsonSchemaValidationProvider;
+class Arazzo11JsonSchemaValidationProvider extends _apiLanguageservice.Arazzo11JsonSchemaValidationProvider {
+  validate(jsonDocument, originalDocument, isYaml, diagnostics, validationContext) {
+    const startIndex = diagnostics.length;
+    super.validate(jsonDocument, originalDocument, isYaml, diagnostics, validationContext);
+
+    // assign 'json-schema' code only to diagnostics added by this provider
+    for (let i = startIndex; i < diagnostics.length; i++) {
+      diagnostics[i].code = 'json-schema';
+    }
+  }
+}
+exports.Arazzo11JsonSchemaValidationProvider = Arazzo11JsonSchemaValidationProvider;

package/src/validators/json-schema-provider.mjs

@@ -0,0 +1,42 @@
+import { Arazzo1JsonSchemaValidationProvider as BaseArazzo1JsonSchemaValidationProvider, Arazzo11JsonSchemaValidationProvider as BaseArazzo11JsonSchemaValidationProvider } from '@speclynx/api-languageservice';
+
+/**
+ * Custom JSON Schema validation provider that assigns proper diagnostic codes.
+ *
+ * Extends the base Arazzo1JsonSchemaValidationProvider to set 'json-schema'
+ * as the code for all diagnostics, making them identifiable in CLI output.
+ * Covers Arazzo 1.0.x documents.
+ *
+ * @internal
+ */
+export class Arazzo1JsonSchemaValidationProvider extends BaseArazzo1JsonSchemaValidationProvider {
+  validate(jsonDocument, originalDocument, isYaml, diagnostics, validationContext) {
+    const startIndex = diagnostics.length;
+    super.validate(jsonDocument, originalDocument, isYaml, diagnostics, validationContext);
+
+    // assign 'json-schema' code only to diagnostics added by this provider
+    for (let i = startIndex; i < diagnostics.length; i++) {
+      diagnostics[i].code = 'json-schema';
+    }
+  }
+}
+
+/**
+ * The Arazzo 1.1.0 counterpart of {@link Arazzo1JsonSchemaValidationProvider}.
+ *
+ * The two upstream providers share no base that carries the Arazzo schema, so
+ * the 'json-schema' code assignment is repeated here rather than inherited.
+ *
+ * @internal
+ */
+export class Arazzo11JsonSchemaValidationProvider extends BaseArazzo11JsonSchemaValidationProvider {
+  validate(jsonDocument, originalDocument, isYaml, diagnostics, validationContext) {
+    const startIndex = diagnostics.length;
+    super.validate(jsonDocument, originalDocument, isYaml, diagnostics, validationContext);
+
+    // assign 'json-schema' code only to diagnostics added by this provider
+    for (let i = startIndex; i < diagnostics.length; i++) {
+      diagnostics[i].code = 'json-schema';
+    }
+  }
+}

package/src/validators/validate-uri.cjs

@@ -0,0 +1,118 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.defaultArazzoResolveOptions = void 0;
+exports.validateURI = validateURI;
+var _parser = require("@usearazzo/parser");
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _ramda = require("ramda");
+var _document = require("../document.cjs");
+var _ValidateError = _interopRequireDefault(require("../errors/ValidateError.cjs"));
+var _validate = require("./validate.cjs");
+/**
+ * Default resolve options for URI resolution in validateURI.
+ *
+ * These options control how files and URLs are fetched when validating
+ * Arazzo documents from URIs.
+ *
+ * @public
+ */
+const defaultArazzoResolveOptions = exports.defaultArazzoResolveOptions = _parser.defaultParseArazzoOptions.resolve;
+
+/**
+ * Canonicalizes a document source (path or URL) into an absolute URI.
+ *
+ * http(s) URLs pass through untouched. A filesystem path (relative or
+ * absolute) or a `file:` URI is resolved against the current working
+ * directory (a no-op when already absolute) and normalized. Uses
+ * `@speclynx/apidom-reference`'s own isomorphic `url` utilities rather than
+ * `node:path`/`node:url`, since this module is also bundled for the browser
+ * target. This canonical URI doubles as the `baseURI` used to resolve
+ * relative external references (e.g. `sourceDescriptions[].url`) within
+ * the document.
+ */
+function canonicalizeDocumentURI(source) {
+  if (_empty.url.isHttpUrl(source)) {
+    return source;
+  }
+  // a leading slash or backslash (UNC, drive-rooted) is already rooted and passes through
+  // untouched; cwd is encoded first so a directory name containing `#`, `?` or `%` survives
+  // URL parsing
+  const absoluteURI = _empty.url.getProtocol(source) !== 'file' && !/^[\\/]/.test(source) ? _empty.url.resolve(_empty.url.fromFileSystemPath(_empty.url.cwd()), source) : source;
+  return _empty.url.sanitize(absoluteURI);
+}
+
+/**
+ * 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
+ */
+async function validateURI(uri, context = {}, resolveOptions = {}) {
+  const canonicalURI = canonicalizeDocumentURI(uri);
+  const mergedOptions = (0, _empty.mergeOptions)(_parser.defaultParseArazzoOptions, {
+    resolve: resolveOptions
+  });
+  let content;
+  try {
+    const buffer = await (0, _empty.readFile)(canonicalURI, mergedOptions);
+    content = new TextDecoder().decode(buffer);
+  } catch (error) {
+    // quote `uri` rather than `canonicalURI` so the message names what the caller passed in
+    throw new _ValidateError.default(`Failed to read Arazzo Document at "${uri}"`, {
+      cause: error
+    });
+  }
+  const textDocument = (0, _document.createTextDocument)(canonicalURI, content);
+
+  // validateURI always has a real, resolvable document location, so it anchors
+  // resolution of relative source descriptions to that location.
+  const uriDefaults = {
+    validationContext: {
+      baseURI: canonicalURI
+    }
+  };
+  return (0, _validate.validate)(textDocument, (0, _ramda.mergeDeepRight)(uriDefaults, context));
+}

package/src/validators/validate-uri.mjs

@@ -0,0 +1,110 @@
+import { defaultParseArazzoOptions } from '@usearazzo/parser';
+import { readFile, mergeOptions, url } from '@speclynx/apidom-reference/configuration/empty';
+import { mergeDeepRight } from 'ramda';
+import { createTextDocument } from "../document.mjs";
+import ValidateError from "../errors/ValidateError.mjs";
+import { validate } from "./validate.mjs";
+/**
+ * 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 const defaultArazzoResolveOptions = defaultParseArazzoOptions.resolve;
+
+/**
+ * Canonicalizes a document source (path or URL) into an absolute URI.
+ *
+ * http(s) URLs pass through untouched. A filesystem path (relative or
+ * absolute) or a `file:` URI is resolved against the current working
+ * directory (a no-op when already absolute) and normalized. Uses
+ * `@speclynx/apidom-reference`'s own isomorphic `url` utilities rather than
+ * `node:path`/`node:url`, since this module is also bundled for the browser
+ * target. This canonical URI doubles as the `baseURI` used to resolve
+ * relative external references (e.g. `sourceDescriptions[].url`) within
+ * the document.
+ */
+function canonicalizeDocumentURI(source) {
+  if (url.isHttpUrl(source)) {
+    return source;
+  }
+  // a leading slash or backslash (UNC, drive-rooted) is already rooted and passes through
+  // untouched; cwd is encoded first so a directory name containing `#`, `?` or `%` survives
+  // URL parsing
+  const absoluteURI = url.getProtocol(source) !== 'file' && !/^[\\/]/.test(source) ? url.resolve(url.fromFileSystemPath(url.cwd()), source) : source;
+  return url.sanitize(absoluteURI);
+}
+
+/**
+ * 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 async function validateURI(uri, context = {}, resolveOptions = {}) {
+  const canonicalURI = canonicalizeDocumentURI(uri);
+  const mergedOptions = mergeOptions(defaultParseArazzoOptions, {
+    resolve: resolveOptions
+  });
+  let content;
+  try {
+    const buffer = await readFile(canonicalURI, mergedOptions);
+    content = new TextDecoder().decode(buffer);
+  } catch (error) {
+    // quote `uri` rather than `canonicalURI` so the message names what the caller passed in
+    throw new ValidateError(`Failed to read Arazzo Document at "${uri}"`, {
+      cause: error
+    });
+  }
+  const textDocument = createTextDocument(canonicalURI, content);
+
+  // validateURI always has a real, resolvable document location, so it anchors
+  // resolution of relative source descriptions to that location.
+  const uriDefaults = {
+    validationContext: {
+      baseURI: canonicalURI
+    }
+  };
+  return validate(textDocument, mergeDeepRight(uriDefaults, context));
+}