feat: expose available functions to custom functions

docs/guides/custom-functions.md

@@ -2,6 +2,22 @@
 
 If the built-in functions are not enough for your [custom ruleset](../getting-started/rulesets.md), Spectral allows you to write and use your own custom functions.
 
+Please, do keep in mind that for the time being, the code is **not** executed in a sandboxed environment, so be very careful when including external rulesets.
+This indicates that almost any arbitrary code can be executed.
+Potential risks include:
+- data / credentials infiltration,
+- data tampering,
+- running cpu-intensive tasks, i.e. crypto-mining.
+
+While the risk is relatively low, you should be careful about including **external rulesets** you are not in charge of, in particular these that leverage custom functions.
+You are strongly encouraged to review the custom functions a given ruleset provides.
+What you should hunt for is:
+- obfuscated code,
+- calls untrusted external library,
+- places where remote code is executed.
+
+If you notice any weirdness, consider forking the ruleset and removal of any evil-looking code.
+
 A custom function might be any JavaScript function compliant with [IFunction](https://github.com/stoplightio/spectral/blob/90a0864863fa232bf367a26dace61fd9f93198db/src/types/function.ts#L3#L8) type.
 
 ```ts

src/__tests__/__fixtures__/custom-functions-oas-ruleset.json

@@ -2,6 +2,7 @@
   "extends": ["spectral:oas"],
   "functions": [
     "truthy",
+    "validateBar",
     "deepHasIn",
     [
       "hasIn",
@@ -60,6 +61,18 @@
           "path": "/bar.get"
         }
       }
+    },
+    "validate-bar": {
+      "message": "`bar` property should be a string",
+      "given": "$",
+      "then": {
+        "function": "validateBar",
+        "functionOptions": {
+          "schema": {
+            "type": "string"
+          }
+        }
+      }
     }
   }
 }

src/__tests__/__fixtures__/functions/validateBar.js

@@ -0,0 +1,3 @@
+module.exports = function(targetVal, opts, paths, otherValues) {
+  return 'bar' in targetVal ? this.functions.schema(targetVal.bar, opts, paths, otherValues) : void 0;
+};

src/__tests__/linter.jest.test.ts

@@ -96,6 +96,18 @@ describe('Linter', () => {
     ]);
   });
 
+  it('should expose all available functions to custom functions', async () => {
+    await spectral.loadRuleset(customDirectoryFunctionsRuleset);
+    expect(await spectral.run({ bar: 2 })).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'validate-bar',
+          message: '`bar` property should be a string',
+        }),
+      ]),
+    );
+  });
+
   it('should report resolving errors for correct files', async () => {
     spectral = new Spectral({ resolver: httpAndFileResolver });
 

src/functions/index.ts

@@ -1,15 +1,31 @@
+import { alphabetical } from './alphabetical';
+import { casing } from './casing';
+import { enumeration } from './enumeration';
+import { falsy } from './falsy';
+import { length } from './length';
+import { pattern } from './pattern';
+import { schema } from './schema';
+import { schemaPath } from './schema-path';
+import { truthy } from './truthy';
+import { typedEnum } from './typedEnum';
+import { undefined } from './undefined';
+import { unreferencedReusableObject } from './unreferencedReusableObject';
+import { xor } from './xor';
+
 export const functions = {
-  alphabetical: require('./alphabetical').alphabetical,
-  casing: require('./casing').casing,
-  enumeration: require('./enumeration').enumeration,
-  length: require('./length').length,
-  pattern: require('./pattern').pattern,
-  falsy: require('./falsy').falsy,
-  schema: require('./schema').schema,
-  schemaPath: require('./schema-path').schemaPath,
-  truthy: require('./truthy').truthy,
-  undefined: require('./undefined').undefined,
-  xor: require('./xor').xor,
-  unreferencedReusableObject: require('./unreferencedReusableObject').unreferencedReusableObject,
-  typedEnum: require('./typedEnum').typedEnum,
+  alphabetical,
+  casing,
+  enumeration,
+  length,
+  pattern,
+  falsy,
+  schema,
+  schemaPath,
+  truthy,
+  undefined,
+  xor,
+  unreferencedReusableObject,
+  typedEnum,
 };
+
+export type CoreFunctions = typeof functions;

src/rulesets/__tests__/evaluators.test.ts

@@ -1,4 +1,4 @@
-import { evaluateExport } from '../evaluators';
+import { evaluateExport, setFunctionContext } from '../evaluators';
 
 describe('Code evaluators', () => {
   describe('Export evaluator', () => {
@@ -60,4 +60,19 @@ describe('Code evaluators', () => {
       expect(() => evaluateExport(`this.returnExports = {}`, null)).toThrow();
     });
   });
+
+  describe('setFunctionContext', () => {
+    it('binds context to given function', () => {
+      const context = { a: true };
+      const fn = setFunctionContext(context, jest.fn().mockReturnThis());
+      expect(fn()).toStrictEqual({ a: true });
+    });
+
+    it('deep-copies provided context', () => {
+      const context = { a: true };
+      const fn = setFunctionContext(context, jest.fn().mockReturnThis());
+      const fn2 = setFunctionContext(context, jest.fn().mockReturnThis());
+      expect(fn()).not.toBe(fn2());
+    });
+  });
 });

src/rulesets/evaluators.ts

@@ -147,5 +147,13 @@ export const compileExportedFunction = (
     value: name,
   });
 
+  Object.freeze(fn);
   return fn;
 };
+
+export function setFunctionContext(context: unknown, fn: Function) {
+  return Function.prototype.bind.call(
+    fn,
+    Object.freeze(Object.defineProperties({}, Object.getOwnPropertyDescriptors(context))),
+  );
+}

src/spectral.ts

@@ -7,10 +7,10 @@ import { memoize, merge } from 'lodash';
 import { STATIC_ASSETS } from './assets';
 import { Document, IDocument, IParsedResult, isParsedResult, ParsedDocument } from './document';
 import { DocumentInventory } from './documentInventory';
-import { functions as defaultFunctions } from './functions';
+import { CoreFunctions, functions as coreFunctions } from './functions';
 import * as Parsers from './parsers';
 import { readRuleset } from './rulesets';
-import { compileExportedFunction } from './rulesets/evaluators';
+import { compileExportedFunction, setFunctionContext } from './rulesets/evaluators';
 import { mergeExceptions } from './rulesets/mergers/exceptions';
 import { IRulesetReadOptions } from './rulesets/reader';
 import { DEFAULT_SEVERITY_LEVEL, getDiagnosticSeverity } from './rulesets/severity';
@@ -19,6 +19,7 @@ import {
   FormatLookup,
   FunctionCollection,
   IConstructorOpts,
+  IFunctionContext,
   IResolver,
   IRuleResult,
   IRunOpts,
@@ -39,7 +40,7 @@ export * from './types';
 export class Spectral {
   private readonly _resolver: IResolver;
 
-  public functions: FunctionCollection = { ...defaultFunctions };
+  public functions: FunctionCollection & CoreFunctions = { ...coreFunctions };
   public rules: RunRuleCollection = {};
   public exceptions: RulesetExceptionCollection = {};
   public formats: RegisteredFormats;
@@ -110,7 +111,7 @@ export class Spectral {
   public setFunctions(functions: FunctionCollection) {
     empty(this.functions);
 
-    Object.assign(this.functions, { ...defaultFunctions, ...functions });
+    Object.assign(this.functions, { ...coreFunctions, ...functions });
   }
 
   public setRules(rules: RuleCollection) {
@@ -168,11 +169,15 @@ export class Spectral {
             return fns;
           }
 
-          fns[key] = compileExportedFunction(code, name, source, schema);
+          const context: IFunctionContext = {
+            functions: this.functions,
+          };
+
+          fns[key] = setFunctionContext(context, compileExportedFunction(code, name, source, schema));
           return fns;
         },
         {
-          ...defaultFunctions,
+          ...coreFunctions,
         },
       ),
     );

src/types/function.ts

@@ -1,5 +1,10 @@
 import { JsonPath } from '@stoplight/types';
 import { DocumentInventory } from '../documentInventory';
+import { CoreFunctions } from '../functions';
+
+export interface IFunctionContext {
+  functions: CoreFunctions;
+}
 
 export type IFunction<O = any> = (
   targetValue: any,