Calling a ruleset function in a custom function for browser based linting

[OllieTho]

This is building off of my previous issue I posted here: #2323

I have a custom function and I am wanting to use a function included in the oas ruleset provided with spectral inside the custom function. I found a solution using the require() function for linting with spectral-cli by doing the following:
const {oasUnusedComponent} = require('@stoplight/spectral-rulesets/dist/oas/functions');

I'm also needing this to be functional in the browser however and since require() is a Node.js function, this solution does not work there. I'm aware that the oas ruleset exists in the js delivered to the browser, but it has been minified, so the path to calling the function is obfuscated and I'm not sure there's a reliable way to call it from there. Any help is appreciated!

[P0lip]

Hey!
The functions located inside of the OAS ruleset are private and not meant to be used by any ruleset other than the OAS one itself.
I'd suggest forking the function if you need to use it - the import will break at some point for Node.js / CLI usage too once we add package exports.

The source of the function is here. There isn't any meaningful external dependency.

[OllieTho]

Thanks for the response @P0lip ! If I'm forking the function, since it's in typescript, is there a recommended way to transform the function into both Node.js and browser JS? Could the browser transformation be extended to the whole OAS ruleset as well? I'm interested in being able to use a specific version of the OAS ruleset and extending it via sources like unpkg fail in the browser.

extends:
  - https://unpkg.com/@stoplight/[email protected]/dist/oas/index.js

[P0lip]

since it's in typescript, is there a recommended way to transform the function into both Node.js and browser JS?

If it's just one function, you could either strip TS annotations manually or use https://www.typescriptlang.org/play

I'm interested in being able to use a specific version of the OAS ruleset and extending it via sources like unpkg fail in the browser.

What's the error?

[OllieTho]

Responded in the thread below: #2398 (reply in thread)

[OllieTho]

I've been attempting to build this using rollup and I'm running into an issue. I've installed rollup and rollup-plugin-typescript2 via npm. I made a rollup.config.js file that has the target of the oasUnusedComponent.ts file and a tsconfig-custom.build.json file that is similar to tsconfig.json but specifying an es2020 module rather than CommonJS. When I run 'npx rollup -c' in the repo, I get an error about '/karma/fsevents.ts' not being found. The file exists in the base repo but it is empty. In the package-lock.json file there is a reference to fsevents being installed as a node module but it is marked as optional. Fsevents isn't in the node_modules folder created when running rollup. I am testing with release v6.6.0.

I pulled the fsevents package from the url in package-lock.json (the NPM registry) and it has a fsevents.d.ts file. Is it intdended to copy these contents into fsevents.ts? Or is there customized content for the package that needs to be used for the spectral build? This also appears to be an optional package from the package-lock.json file, so why is the rollup command failing on the missing file?

[P0lip]

You don't need to use rollup to bundle that function.
Just run yarn build in the cloned repo, and you'll find the built code under packages/rulesets/dist. You can copy functions from there.

'@stoplight/spectral-formats' is imported as an external by @stoplight/spectral-formats?commonjs-proxy, but is already an existing non-external module id.

I'll look into this one.

[OllieTho]

@P0lip do you have an update on the import conflict?

Additionally, I followed your advice and ran the yarn build command and tried including the oasUnusedComponent.js function from there. I've had success including the build function in my functions folder and then referencing it in my .spectral.yaml file, but I can't quite find the right configuration to reference it within my custom function and have it work in StopLight web. My two primary approaches have been:

To copy the structure of the generated function, but this gives me the error require$$1$1 is not defined which is curious since the compiled oasUnusedComponent.js file is using the same syntax but doesn't throw the error. I've also sometimes seen the error exports is not defined which appears to be caused by the second line, but again is not thrown by the oasUnusedComponent.js file.(Also I renamed the generated oasUnusedComponent.js file and generated function to oasUnusedComponentOverride so I could be sure it was referencing my new function not the ruleset one)

functions/oasCheckPaths.js

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const spectral_core_1 = require("@stoplight/spectral-core");
const oasUnusedComponentOverride = require('oasUnusedComponentOverride');

exports.default = (0, spectral_core_1.createRulesetFunction)({
    input: {
        type: 'object',
        properties: {
            components: {
                type: 'object',
            },
        },
        required: ['components'],
    },
    options: null,
}, function oasCheckPaths(targetVal, opts, context) {
      if (targetVal === void 0 || targetVal.length == 0) {
          return [];
      }

      if ('paths' in targetVal && targetVal['paths']) {
          return oasUnusedComponentOverride.oasUnusedComponentOverride(targetVal, opts, context);
      }

      return [];
});

The other way I've tried to include it is through an import (with various combinations of oasUnusedComponentOverride with and without a leading './' and trailing '.js'. This fails to report errors but prevents linting in StopLight web. Inspecting the console displays an Error running Nimma message:

functions/oasCheckPaths.js

import { oasUnusedComponentOverride } from "./generalasUnusedComponentOverride.js";

export default (targetVal, opts, context) => {
      if (targetVal === void 0 || targetVal.length == 0) {
          return [];
      }

      if ('paths' in targetVal && targetVal['paths']) {
          return oasUnusedComponentOverride(targetVal, opts, context);
      }

      return [];
}

Alternatively I've tried replacing the export default line with module.exports = (targetVal, opts, context) => { and gotten the error 'default' is not exported by p/functions/oasCheckPaths.js, imported by p/spectral.js

For reference, here is the generated oasUnusedComponent.js file that I've included in my functions folder (I also had to comment out the require of utils/isObject in the browser since it was causing an error):

functions/oasUnusedComponentOverride.js

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const spectral_functions_1 = require("@stoplight/spectral-functions");
const spectral_core_1 = require("@stoplight/spectral-core");
//const isObject_1 = require("./utils/isObject");
exports.default = (0, spectral_core_1.createRulesetFunction)({
    input: {
        type: 'object',
        properties: {
            components: {
                type: 'object',
            },
        },
        required: ['components'],
    },
    options: null,
}, function oasUnusedComponentOverride(targetVal, opts, context) {
    const results = [];
    const componentTypes = [
        'schemas',
        'responses',
        'parameters',
        'examples',
        'requestBodies',
        'headers',
        'links',
        'callbacks',
    ];
    for (const type of componentTypes) {
        const value = targetVal.components[type];
        // if (!(0, isObject_1.isObject)(value))
        //     continue;
        const resultsForType = (0, spectral_functions_1.unreferencedReusableObject)(value, { reusableObjectsLocation: `#/components/${type}` }, context);
        if (resultsForType !== void 0 && Array.isArray(resultsForType)) {
            results.push(...resultsForType);
        }
    }
    return results;
});
//# sourceMappingURL=oasUnusedComponent.js.map

Any advice on how to include this generated file in both a browser and cli compatible way?

[OllieTho]

Resolved importing the ruleset function in the custom function. The combination that solved it involved using the same setup as the generated oasUnusedComponent function, but with the filepath in the require and calling the 'default' function in the return statement.

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const spectral_core_1 = require("@stoplight/spectral-core");
const oasUnusedComponentOverride = require('./oasUnusedComponentOverride.js');

exports.default = (0, spectral_core_1.createRulesetFunction)({
    input: {
        type: 'object',
        properties: {
            components: {
                type: 'object',
            },
        },
        required: ['components'],
    },
    options: null,
}, function oasCheckPaths(targetVal, opts, context) {
      if (targetVal === void 0 || targetVal.length == 0) {
          return [];
      }

      if ('paths' in targetVal && targetVal['paths']) {
          return (0, oasUnusedComponentOverride.default)(targetVal, opts, context);
      }

      return [];
});

@P0lip is there any updates on the conflict with the whole ruleset import?

[P0lip]

@P0lip is there any updates on the conflict with the whole ruleset import?

Not yet, I'll try to take a look at it this week.

[P0lip]

I wanted to follow up on the issue with the spectral-rulesets import via unpkg.
In order to make that work we'd need to distribute rulesets in the ESM format, similar to what we do with the new rulesets from us such as spectral-owasp-ruleset.
Feel free to create an issue for that to keep track of it.

[OllieTho]

I've done some digging and learned the fsevents is only compatible with Mac-OS and will cause failures on other systems. I noticed that in the package-lock that while fsevents is marked as optional, there are other packages that have it as a requirement (chokidar, jest-haste-map, and rollup itself).

I tried changing dependencies to optional for both fsevents, and the packages that had it listed as a dependency. I tried using yarn to install the packages and rollup as well and achieved the same error as before. I then tried clearing both yarn and npm caches, deleting the package-lock.json file, and tried again and still hit the same error. Any help would be appreciated.

[OllieTho]

@P0lip we had discussed in our meeting about raising an issue for the conflict error I was getting when importing the oas ruleset at a specific version. I haven't seen that posted here and was curious if that had seen any progress? Thanks!

[P0lip]

I haven't seen that posted here and was curious if that had seen any progress?

Hey! We haven't worked on that yet. Would you mind filing an official issue for that? Could do it here https://github.com/stoplightio/spectral/issues
We'll take it from there.

[OllieTho]

Thanks! Submitted issue here: #2444

[P0lip]

Thank you!