@accordproject/concerto-linter 1.0.0

package/dist/config-loader.js

@@ -0,0 +1,52 @@
+"use strict";
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRulesetPath = resolveRulesetPath;
+const find_up_1 = __importDefault(require("find-up"));
+// Valid Spectral ruleset filenames in priority order
+const SPECTRAL_RULESET_FILES = [
+    '.spectral.yaml',
+    '.spectral.yml',
+    '.spectral.json',
+    '.spectral.js',
+];
+/**
+ * Searches for a Spectral ruleset configuration file in the current and parent directories.
+ * @returns {Promise<string | null>} Path to found ruleset file or null if none exists
+ */
+async function findLocalRuleset() {
+    for (const fileName of SPECTRAL_RULESET_FILES) {
+        const foundPath = await (0, find_up_1.default)(fileName);
+        if (foundPath) {
+            return foundPath;
+        }
+    }
+    return null;
+}
+/**
+ * Resolves the Spectral ruleset location based on user input or directory search
+ * @param {string} [customPath] User-provided ruleset path
+ * @returns {Promise<string | null>} Path to custom ruleset, null for default ruleset
+ */
+async function resolveRulesetPath(customPath) {
+    if (!customPath) {
+        return await findLocalRuleset();
+    }
+    return customPath;
+}
+//# sourceMappingURL=config-loader.js.map

package/dist/config-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loader.js","sourceRoot":"","sources":["../src/config-loader.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;;;AA6BH,gDAMC;AAjCD,sDAA6B;AAE7B,qDAAqD;AACrD,MAAM,sBAAsB,GAAG;IAC3B,gBAAgB;IAChB,eAAe;IACf,gBAAgB;IAChB,cAAc;CACjB,CAAC;AAEF;;;GAGG;AACH,KAAK,UAAU,gBAAgB;IAC3B,KAAK,MAAM,QAAQ,IAAI,sBAAsB,EAAE,CAAC;QAC5C,MAAM,SAAS,GAAG,MAAM,IAAA,iBAAM,EAAC,QAAQ,CAAC,CAAC;QACzC,IAAI,SAAS,EAAE,CAAC;YAAA,OAAO,SAAS,CAAC;QAAA,CAAC;IACtC,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,kBAAkB,CAAC,UAAmB;IACxD,IAAI,CAAC,UAAU,EAAE,CAAC;QACd,OAAO,MAAM,gBAAgB,EAAE,CAAC;IACpC,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+interface options {
+    /** Path to a custom Spectral ruleset or 'default' to use the built-in ruleset */
+    ruleset?: string;
+    /** One or more namespaces to exclude from linting results */
+    excludeNamespaces?: string | string[];
+}
+interface lintResult {
+    /** Unique rule identifier (e.g. 'no-reserved-keywords') */
+    code: string;
+    /** Human-readable description of the violation */
+    message: string;
+    /** Severity level ('error' | 'warning' | 'info' | 'hint') */
+    severity: string;
+    /**
+     * JSONPath-style pointer as an array of keys/indices
+     * (e.g. ['declarations', 3])
+     */
+    path: Array<string | number>;
+    /** Namespace where the violation occurred */
+    namespace: string;
+}
+/**
+ * Lints Concerto models using Spectral and Concerto rules.
+ * @param {string | object} model - The Concerto model to lint, either as a CTO string or a parsed AST object. Note: No external dependency resolution is performed.
+ * @param {options} [config] - Configuration options for customizing the linting process.
+ * @param {string} [config.ruleset] - Path to a custom Spectral ruleset file or 'default' to use the built-in ruleset.
+ * @param {string | string[]} [config.excludeNamespaces] - One or more namespaces to exclude from linting results (defaults to 'concerto.*' and 'org.accord.*').
+ * @returns {Promise<lintResult[]>} Promise resolving to an array of formatted linting results as a JSON object.
+ * @throws {Error} Throws an error if linting or model conversion fails.
+ */
+export declare function lintModel(model: string | object, config?: options): Promise<lintResult[]>;
+export {};

package/dist/index.js

@@ -0,0 +1,135 @@
+"use strict";
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lintModel = lintModel;
+const spectral_core_1 = require("@stoplight/spectral-core");
+const spectral_parsers_1 = require("@stoplight/spectral-parsers");
+const config_loader_1 = require("./config-loader");
+const getRuleset_1 = require("@stoplight/spectral-cli/dist/services/linter/utils/getRuleset");
+const concerto_linter_default_ruleset_1 = __importDefault(require("@accordproject/concerto-linter-default-ruleset"));
+const concerto_cto_1 = require("@accordproject/concerto-cto");
+/**
+ * Converts Concerto model to JSON AST representation
+ * @param {string | object} model - Concerto model as string or parsed object
+ * @returns {string} JSON string of the AST
+ * @throws {Error} For invalid model inputs
+ */
+function convertToJsonAST(model) {
+    try {
+        if (typeof model === 'string') {
+            const modelFile = concerto_cto_1.Parser.parseModels([model]);
+            return JSON.stringify(modelFile);
+        }
+        return JSON.stringify(model);
+    }
+    catch (error) {
+        throw new Error(`Model conversion failed: ${error instanceof Error ? error.message : error}`);
+    }
+}
+/**
+ * Loads Spectral ruleset based on configuration options
+ * @param {string} [ruleset] - Custom ruleset path or 'default'
+ * @returns {Promise<Ruleset | RulesetDefinition>} Loaded ruleset
+ */
+async function loadRuleset(ruleset) {
+    try {
+        if (typeof ruleset === 'string' && ruleset.toLowerCase() === 'default') {
+            return concerto_linter_default_ruleset_1.default;
+        }
+        const rulesetPath = await (0, config_loader_1.resolveRulesetPath)(ruleset);
+        return rulesetPath ? await (0, getRuleset_1.getRuleset)(rulesetPath) : concerto_linter_default_ruleset_1.default;
+    }
+    catch (error) {
+        throw new Error(`Ruleset loading failed: ${error instanceof Error ? error.message : error}`);
+    }
+}
+/**
+ * Formats Spectral linting results by mapping them to a standardized lint result structure,
+ * extracting namespaces from the provided JSON AST, and filtering out results based on excluded namespaces.
+ *
+ * @param spectralResults - An array of Spectral rule results to be formatted.
+ * @param jsonAST - A JSON string representing the AST, used to extract model namespaces.
+ * @param excludeNamespaces - A string or array of strings specifying namespace patterns to exclude from the results.
+ *                            Patterns ending with `.*` will match any namespace starting with the given prefix.
+ *                            Defaults to `['concerto.*', 'org.accord.*']`.
+ * @returns An array of formatted lint results, excluding those matching the specified namespaces.
+ */
+function formatResults(spectralResults, jsonAST, excludeNamespaces = ['concerto.*', 'org.accordproject.*']) {
+    try {
+        const ast = JSON.parse(jsonAST);
+        const severityMap = {
+            0: 'error',
+            1: 'warning',
+            2: 'info',
+            3: 'hint',
+        };
+        const results = spectralResults.map(r => {
+            let namespace = 'unknown';
+            if (Array.isArray(r.path) && r.path.length >= 2 && r.path[0] === 'models') {
+                const modelIndex = r.path[1];
+                const modelEntry = ast.models?.[modelIndex];
+                if (modelEntry && modelEntry.namespace) {
+                    namespace = modelEntry.namespace;
+                }
+            }
+            return {
+                code: r.code,
+                message: r.message,
+                path: r.path,
+                severity: severityMap[r.severity],
+                namespace: namespace,
+            };
+        });
+        const exclusionPatterns = Array.isArray(excludeNamespaces) ? excludeNamespaces : [excludeNamespaces];
+        return results.filter(result => {
+            return !exclusionPatterns.some(pattern => {
+                if (pattern.endsWith('.*')) {
+                    return result.namespace.startsWith(pattern.slice(0, pattern.length - 2));
+                }
+                return result.namespace === pattern;
+            });
+        });
+    }
+    catch (error) {
+        throw new Error(`Formatting lint results failed: ${error instanceof Error ? error.message : error}`);
+    }
+}
+/**
+ * Lints Concerto models using Spectral and Concerto rules.
+ * @param {string | object} model - The Concerto model to lint, either as a CTO string or a parsed AST object. Note: No external dependency resolution is performed.
+ * @param {options} [config] - Configuration options for customizing the linting process.
+ * @param {string} [config.ruleset] - Path to a custom Spectral ruleset file or 'default' to use the built-in ruleset.
+ * @param {string | string[]} [config.excludeNamespaces] - One or more namespaces to exclude from linting results (defaults to 'concerto.*' and 'org.accord.*').
+ * @returns {Promise<lintResult[]>} Promise resolving to an array of formatted linting results as a JSON object.
+ * @throws {Error} Throws an error if linting or model conversion fails.
+ */
+async function lintModel(model, config) {
+    try {
+        const jsonAST = convertToJsonAST(model);
+        const ruleset = await loadRuleset(config?.ruleset);
+        const spectral = new spectral_core_1.Spectral();
+        spectral.setRuleset(ruleset);
+        const document = new spectral_core_1.Document(jsonAST, spectral_parsers_1.Json);
+        const spectralResults = await spectral.run(document);
+        return formatResults(spectralResults, jsonAST, config?.excludeNamespaces);
+    }
+    catch (error) {
+        throw new Error(`Linting process failed: ${error instanceof Error ? error.message : error}`);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/jest.config.js

@@ -0,0 +1,11 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} **/
+module.exports = {
+    testEnvironment: 'node',
+    transform: {
+        '^.+.tsx?$': ['ts-jest', {}],
+    },
+    testPathIgnorePatterns: [
+        './default-ruleset',
+    ],
+
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "@accordproject/concerto-linter",
+    "version": "1.0.0",
+    "description": "Concerto Linter using Spectral rulesets",
+    "homepage": "https://github.com/accordproject/concerto",
+    "engines": {
+        "node": ">=18",
+        "npm": ">=10"
+    },
+    "main": "dist/index.js",
+    "typings": "dist/index.d.ts",
+    "scripts": {
+        "clean": "rimraf dist",
+        "prebuild": "npm-run-all clean && cd ./default-ruleset && npm run build",
+        "build": "tsc -p tsconfig.build.json",
+        "pretest": "npm-run-all lint",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "test": "jest",
+        "test:watch": "jest --watchAll"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/accordproject/concerto.git",
+        "directory": "packages/concerto-linter"
+    },
+    "keywords": [
+        "concerto",
+        "linter",
+        "spectral"
+    ],
+    "author": "accordproject.org",
+    "license": "Apache-2.0",
+    "dependencies": {
+        "ajv": "^8.17.1",
+        "@accordproject/concerto-core": "^4.0.0-alpha.1",
+        "@accordproject/concerto-linter-default-ruleset": "file:./default-ruleset",
+        "@accordproject/concerto-metamodel": "^4.0.0-alpha.1",
+        "find-up": "5.0.0",
+        "@stoplight/spectral-cli": "6.15.0",
+        "@stoplight/spectral-core": "1.20.0",
+        "@stoplight/spectral-parsers": "1.0.5"
+    },
+    "devDependencies": {
+        "eslint": "8.57.1",
+        "@typescript-eslint/eslint-plugin": "^8.46.2",
+        "@typescript-eslint/parser": "^8.46.2",
+        "npm-run-all": "^4.1.5",
+        "rimraf": "^6.0.1",
+        "typescript": "5.7.2",
+        "jest": "^29.7.0",
+        "ts-jest": "^29.2.5"
+    }
+}

package/src/config-loader.ts

@@ -0,0 +1,48 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import findUp from 'find-up';
+
+// Valid Spectral ruleset filenames in priority order
+const SPECTRAL_RULESET_FILES = [
+    '.spectral.yaml',
+    '.spectral.yml',
+    '.spectral.json',
+    '.spectral.js',
+];
+
+/**
+ * Searches for a Spectral ruleset configuration file in the current and parent directories.
+ * @returns {Promise<string | null>} Path to found ruleset file or null if none exists
+ */
+async function findLocalRuleset(): Promise<string | null> {
+    for (const fileName of SPECTRAL_RULESET_FILES) {
+        const foundPath = await findUp(fileName);
+        if (foundPath) {return foundPath;}
+    }
+    return null;
+}
+
+/**
+ * Resolves the Spectral ruleset location based on user input or directory search
+ * @param {string} [customPath] User-provided ruleset path
+ * @returns {Promise<string | null>} Path to custom ruleset, null for default ruleset
+ */
+export async function resolveRulesetPath(customPath?: string): Promise<string | null> {
+    if (!customPath) {
+        return await findLocalRuleset();
+    }
+
+    return customPath;
+}

package/src/index.ts

@@ -0,0 +1,173 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Spectral, Document, IRuleResult, RulesetDefinition, Ruleset } from '@stoplight/spectral-core';
+import { Json as JsonParsers } from '@stoplight/spectral-parsers';
+import { resolveRulesetPath } from './config-loader';
+import { getRuleset } from '@stoplight/spectral-cli/dist/services/linter/utils/getRuleset';
+import  concertoRuleset  from '@accordproject/concerto-linter-default-ruleset';
+import { Parser } from '@accordproject/concerto-cto';
+
+interface options {
+    /** Path to a custom Spectral ruleset or 'default' to use the built-in ruleset */
+    ruleset?: string;
+
+    /** One or more namespaces to exclude from linting results */
+    excludeNamespaces?: string | string[];
+}
+
+interface lintResult {
+  /** Unique rule identifier (e.g. 'no-reserved-keywords') */
+  code: string;
+
+  /** Human-readable description of the violation */
+  message: string;
+
+  /** Severity level ('error' | 'warning' | 'info' | 'hint') */
+  severity: string;
+
+  /**
+   * JSONPath-style pointer as an array of keys/indices
+   * (e.g. ['declarations', 3])
+   */
+  path: Array<string | number>;
+
+  /** Namespace where the violation occurred */
+  namespace: string;
+
+}
+
+/**
+ * Converts Concerto model to JSON AST representation
+ * @param {string | object} model - Concerto model as string or parsed object
+ * @returns {string} JSON string of the AST
+ * @throws {Error} For invalid model inputs
+ */
+function convertToJsonAST(model: string | object): string {
+    try {
+        if (typeof model === 'string') {
+            const modelFile = Parser.parseModels([model]);
+            return JSON.stringify(modelFile);
+        }
+        return JSON.stringify(model);
+    } catch (error) {
+        throw new Error(`Model conversion failed: ${error instanceof Error ? error.message : error}`);
+    }
+}
+
+/**
+ * Loads Spectral ruleset based on configuration options
+ * @param {string} [ruleset] - Custom ruleset path or 'default'
+ * @returns {Promise<Ruleset | RulesetDefinition>} Loaded ruleset
+ */
+async function loadRuleset(ruleset?: string): Promise<Ruleset | RulesetDefinition> {
+    try {
+
+        if (typeof ruleset === 'string' && ruleset.toLowerCase() === 'default') {
+            return concertoRuleset;
+        }
+        const rulesetPath = await resolveRulesetPath(ruleset);
+        return rulesetPath ? await getRuleset(rulesetPath) : concertoRuleset;
+    } catch (error) {
+        throw new Error(`Ruleset loading failed: ${error instanceof Error ? error.message : error}`);
+    }
+}
+
+/**
+ * Formats Spectral linting results by mapping them to a standardized lint result structure,
+ * extracting namespaces from the provided JSON AST, and filtering out results based on excluded namespaces.
+ *
+ * @param spectralResults - An array of Spectral rule results to be formatted.
+ * @param jsonAST - A JSON string representing the AST, used to extract model namespaces.
+ * @param excludeNamespaces - A string or array of strings specifying namespace patterns to exclude from the results.
+ *                            Patterns ending with `.*` will match any namespace starting with the given prefix.
+ *                            Defaults to `['concerto.*', 'org.accord.*']`.
+ * @returns An array of formatted lint results, excluding those matching the specified namespaces.
+ */
+
+function formatResults(
+    spectralResults: IRuleResult[],
+    jsonAST: string,
+    excludeNamespaces: string | string[] = ['concerto.*', 'org.accordproject.*']
+): lintResult[] {
+    try {
+        const ast = JSON.parse(jsonAST);
+
+        const severityMap: { [key: number]: string } = {
+            0: 'error',
+            1: 'warning',
+            2: 'info',
+            3: 'hint',
+        };
+
+        const results: lintResult[] = spectralResults.map(r => {
+            let namespace = 'unknown';
+
+            if (Array.isArray(r.path) && r.path.length >= 2 && r.path[0] === 'models') {
+                const modelIndex = r.path[1] as number;
+                const modelEntry = ast.models?.[modelIndex];
+                if (modelEntry && modelEntry.namespace) {
+                    namespace = modelEntry.namespace;
+                }
+            }
+
+            return {
+                code: r.code as string,
+                message: r.message,
+                path: r.path,
+                severity: severityMap[r.severity],
+                namespace: namespace,
+            };
+        });
+
+        const exclusionPatterns = Array.isArray(excludeNamespaces) ? excludeNamespaces : [excludeNamespaces];
+
+        return results.filter(result => {
+            return !exclusionPatterns.some(pattern => {
+                if (pattern.endsWith('.*')) {
+                    return result.namespace.startsWith(pattern.slice(0, pattern.length - 2));
+                }
+                return result.namespace === pattern;
+            });
+        });
+    } catch (error) {
+        throw new Error(`Formatting lint results failed: ${error instanceof Error ? error.message : error}`);
+    }
+}
+
+/**
+ * Lints Concerto models using Spectral and Concerto rules.
+ * @param {string | object} model - The Concerto model to lint, either as a CTO string or a parsed AST object. Note: No external dependency resolution is performed.
+ * @param {options} [config] - Configuration options for customizing the linting process.
+ * @param {string} [config.ruleset] - Path to a custom Spectral ruleset file or 'default' to use the built-in ruleset.
+ * @param {string | string[]} [config.excludeNamespaces] - One or more namespaces to exclude from linting results (defaults to 'concerto.*' and 'org.accord.*').
+ * @returns {Promise<lintResult[]>} Promise resolving to an array of formatted linting results as a JSON object.
+ * @throws {Error} Throws an error if linting or model conversion fails.
+ */
+export async function lintModel(model: string | object, config?: options): Promise<lintResult[]> {
+    try {
+        const jsonAST = convertToJsonAST(model);
+        const ruleset = await loadRuleset(config?.ruleset);
+
+        const spectral = new Spectral();
+        spectral.setRuleset(ruleset);
+
+        const document = new Document(jsonAST, JsonParsers);
+        const spectralResults = await spectral.run(document);
+        return formatResults(spectralResults, jsonAST, config?.excludeNamespaces);
+
+    } catch (error) {
+        throw new Error(`Linting process failed: ${error instanceof Error ? error.message : error}`);
+    }
+}

package/test/unit/configLoader.test.ts

@@ -0,0 +1,76 @@
+import { resolveRulesetPath } from '../../src/config-loader';
+import findUp from 'find-up';
+
+// Mock the find-up module
+jest.mock('find-up');
+const mockFindUp = findUp as jest.MockedFunction<typeof findUp>;
+
+describe('resolveRulesetPath', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockFindUp.mockReset();
+    });
+
+
+    it('should return the provided path when rulesetOption is a custom path', async () => {
+        const customPath = '/path/to/custom/ruleset.yaml';
+        const result = await resolveRulesetPath(customPath);
+        expect(result).toBe(customPath);
+        expect(mockFindUp).not.toHaveBeenCalled();
+    });
+
+    it('should search for local ruleset when no rulesetOption is provided', async () => {
+        const foundPath = '/project/.spectral.yaml';
+        mockFindUp
+            .mockResolvedValueOnce(foundPath) // First file found
+            .mockResolvedValueOnce(undefined) // Subsequent calls return undefined
+            .mockResolvedValueOnce(undefined)
+            .mockResolvedValueOnce(undefined);
+
+        const result = await resolveRulesetPath();
+
+        expect(result).toBe(foundPath);
+        expect(mockFindUp).toHaveBeenCalledWith('.spectral.yaml');
+        expect(mockFindUp).toHaveBeenCalledTimes(1);
+    });
+
+    it('should try all ruleset files in order when searching locally', async () => {
+        const foundPath = '/project/.spectral.json';
+        mockFindUp
+            .mockResolvedValueOnce(undefined) // .spectral.yaml not found
+            .mockResolvedValueOnce(undefined) // .spectral.yml not found
+            .mockResolvedValueOnce(foundPath)  // .spectral.json found
+            .mockResolvedValueOnce(undefined); // .spectral.js not called
+
+        const result = await resolveRulesetPath();
+
+        expect(result).toBe(foundPath);
+        expect(mockFindUp).toHaveBeenCalledWith('.spectral.yaml');
+        expect(mockFindUp).toHaveBeenCalledWith('.spectral.yml');
+        expect(mockFindUp).toHaveBeenCalledWith('.spectral.json');
+        expect(mockFindUp).toHaveBeenCalledTimes(3);
+    });
+
+    it('should return null when no local ruleset files are found', async () => {
+        mockFindUp.mockResolvedValue(undefined);
+
+        const result = await resolveRulesetPath();
+
+        expect(result).toBeNull();
+        expect(mockFindUp).toHaveBeenCalledTimes(4); // All 4 files checked
+        expect(mockFindUp).toHaveBeenCalledWith('.spectral.yaml');
+        expect(mockFindUp).toHaveBeenCalledWith('.spectral.yml');
+        expect(mockFindUp).toHaveBeenCalledWith('.spectral.json');
+        expect(mockFindUp).toHaveBeenCalledWith('.spectral.js');
+    });
+
+    it('should handle empty string as rulesetOption', async () => {
+        const foundPath = '/project/.spectral.yaml';
+        mockFindUp.mockResolvedValueOnce(foundPath);
+
+        const result = await resolveRulesetPath('');
+
+        expect(result).toBe(foundPath);
+        expect(mockFindUp).toHaveBeenCalledWith('.spectral.yaml');
+    });
+});