@contractkit/plugin-bruno 1.1.0 → 1.3.0

package/src/index.ts

@@ -2,7 +2,7 @@ import { resolve, basename, dirname } from 'node:path';
 import { existsSync, readFileSync, rmSync, readdirSync, rmdirSync } from 'node:fs';
 import { generateOpenCollection, MANIFEST_FILENAME, parseManifest } from './codegen-bruno.js';
 import type { BrunoSecurityScheme } from './codegen-bruno.js';
-import type { ContractKitPlugin } from '@contractkit/core';
+import type { ContractKitPlugin, PluginValue } from '@contractkit/core';
 
 /** Configuration accepted by the Bruno plugin, both via `contractkit.config.json` and `createBrunoPlugin`. */
 export interface BrunoPluginConfig {
@@ -38,9 +38,37 @@ export interface BrunoPluginOptions extends BrunoPluginConfig {
 
 // ─── Default export: loaded via plugins array, reads config from ctx.options ─
 
+/**
+ * Validates a `plugins.bruno` extension entry on an operation. The expected shape is
+ * `{ template?: string }`, where `template` is a YAML fragment to deep-merge into the
+ * generated request file (typically a `file://...` URL whose contents have already
+ * been loaded by the CLI resolver).
+ */
+export function validateBrunoExtension(value: PluginValue): { errors?: string[] } | void {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return { errors: [`expected an object, got ${describe(value)}`] };
+    }
+    const errors: string[] = [];
+    for (const [key, val] of Object.entries(value)) {
+        if (key === 'template') {
+            if (typeof val !== 'string') errors.push(`'template' must be a string, got ${describe(val)}`);
+        } else {
+            errors.push(`unknown field '${key}' (allowed: template)`);
+        }
+    }
+    return errors.length ? { errors } : undefined;
+}
+
+function describe(value: PluginValue): string {
+    if (value === null) return 'null';
+    if (Array.isArray(value)) return 'array';
+    return typeof value;
+}
+
 const plugin: ContractKitPlugin = {
     name: 'bruno',
     cacheKey: 'bruno',
+    validateExtension: validateBrunoExtension,
     async generateTargets({ opRoots, contractRoots }, ctx) {
         const { auth, ...config } = ctx.options as BrunoPluginOptions;
         const base = config.baseDir ? resolve(ctx.rootDir, config.baseDir) : ctx.rootDir;
@@ -85,6 +113,7 @@ export function createBrunoPlugin(
     return {
         name: 'bruno',
         cacheKey: `bruno:${JSON.stringify(config)}`,
+        validateExtension: validateBrunoExtension,
         async generateTargets({ opRoots, contractRoots }, ctx) {
             const base = config.baseDir ? resolve(rootDir, config.baseDir) : rootDir;
             const outDir = resolve(base, config.output ?? 'bruno-collection');

package/tests/codegen-bruno.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { generateOpenCollection, sanitizePath, MANIFEST_FILENAME, parseManifest, mergePluginFile } from '../src/codegen-bruno.js';
+import { validateBrunoExtension } from '../src/index.js';
 import {
     opRoot,
     opRoute,
@@ -671,6 +672,48 @@ describe('generateOpenCollection', () => {
         expect(env!.content).toContain('- name: token');
     });
 
+    describe('alphabetical ordering', () => {
+        function seqOf(content: string): number | undefined {
+            const match = content.match(/seq:\s*(\d+)/);
+            return match ? parseInt(match[1]!, 10) : undefined;
+        }
+
+        it('orders top-level folders alphabetically by area', () => {
+            const usersRoot = opRoot([opRoute('/users', [opOperation('get')])], 'users.op', { area: 'users' });
+            const authRoot = opRoot([opRoute('/auth', [opOperation('post')])], 'auth.op', { area: 'auth' });
+            const paymentsRoot = opRoot([opRoute('/payments', [opOperation('get')])], 'payments.op', { area: 'payments' });
+            // Pass in a non-alphabetical input order to prove the sort is doing the work.
+            const files = generateOpenCollection([usersRoot, authRoot, paymentsRoot], { collectionName: 'API' });
+
+            const auth = files.find(f => f.relativePath === 'auth/folder.yml');
+            const payments = files.find(f => f.relativePath === 'payments/folder.yml');
+            const users = files.find(f => f.relativePath === 'users/folder.yml');
+            expect(seqOf(auth!.content)).toBe(1);
+            expect(seqOf(payments!.content)).toBe(2);
+            expect(seqOf(users!.content)).toBe(3);
+        });
+
+        it('orders requests within a folder alphabetically by request name', () => {
+            const root = opRoot(
+                [
+                    opRoute('/zebras', [opOperation('get', { name: 'Zebra list' })]),
+                    opRoute('/aardvarks', [opOperation('get', { name: 'Aardvark list' })]),
+                    opRoute('/mammals', [opOperation('get', { name: 'Mammal list' })]),
+                ],
+                'zoo.op',
+                { area: 'zoo' },
+            );
+            const files = generateOpenCollection([root], { collectionName: 'API' });
+
+            const aardvark = files.find(f => f.relativePath === 'zoo/aardvark-list.yml');
+            const mammal = files.find(f => f.relativePath === 'zoo/mammal-list.yml');
+            const zebra = files.find(f => f.relativePath === 'zoo/zebra-list.yml');
+            expect(seqOf(aardvark!.content)).toBe(1);
+            expect(seqOf(mammal!.content)).toBe(2);
+            expect(seqOf(zebra!.content)).toBe(3);
+        });
+    });
+
     describe('environments config', () => {
         const root = opRoot([opRoute('/users', [opOperation('get')])], 'users.op');
 
@@ -1074,7 +1117,7 @@ describe('plugin file merges', () => {
             opRoute('/users', [
                 opOperation('get', {
                     responses: [opResponse(200, 'User')],
-                    pluginFiles: { bruno: 'runtime:\n  script:\n    req: |\n      console.log("pre");\n' },
+                    pluginExtensions: { bruno: { template: 'runtime:\n  script:\n    req: |\n      console.log("pre");\n' } },
                 }),
             ]),
         ]);
@@ -1092,17 +1135,19 @@ describe('plugin file merges', () => {
             opRoute('/users', [
                 opOperation('get', {
                     responses: [opResponse(200)],
-                    pluginFiles: {
-                        bruno: [
-                            'runtime:',
-                            '  assertions:',
-                            '    - expression: res.status',
-                            '      operator: eq',
-                            '      value: "200"',
-                            '    - expression: res.headers["x-request-id"]',
-                            '      operator: isDefined',
-                            '      value: ""',
-                        ].join('\n'),
+                    pluginExtensions: {
+                        bruno: {
+                            template: [
+                                'runtime:',
+                                '  assertions:',
+                                '    - expression: res.status',
+                                '      operator: eq',
+                                '      value: "200"',
+                                '    - expression: res.headers["x-request-id"]',
+                                '      operator: isDefined',
+                                '      value: ""',
+                            ].join('\n'),
+                        },
                     },
                 }),
             ]),
@@ -1119,7 +1164,7 @@ describe('plugin file merges', () => {
             opRoute('/users', [
                 opOperation('get', {
                     responses: [opResponse(200)],
-                    pluginFiles: { bruno: 'runtime:\n  script:\n    req: |\n      // pre\n' },
+                    pluginExtensions: { bruno: { template: 'runtime:\n  script:\n    req: |\n      // pre\n' } },
                 }),
             ]),
         ]);
@@ -1130,13 +1175,13 @@ describe('plugin file merges', () => {
         expect(req.content).toContain('url:');
     });
 
-    it('leaves generated content unchanged when pluginFiles is absent', () => {
+    it('leaves generated content unchanged when pluginExtensions is absent', () => {
         const withoutOverride = opRoot([opRoute('/users', [opOperation('get', { responses: [opResponse(200)] })])]);
         const withOverride = opRoot([
             opRoute('/users', [
                 opOperation('get', {
                     responses: [opResponse(200)],
-                    pluginFiles: {},
+                    pluginExtensions: {},
                 }),
             ]),
         ]);
@@ -1151,7 +1196,7 @@ describe('plugin file merges', () => {
             opRoute('/users', [
                 opOperation('get', {
                     responses: [opResponse(200)],
-                    pluginFiles: { bruno: 'just a scalar string' },
+                    pluginExtensions: { bruno: { template: 'just a scalar string' } },
                 }),
             ]),
         ]);
@@ -1164,7 +1209,7 @@ describe('plugin file merges', () => {
         const root = opRoot([
             opRoute('/users', [
                 opOperation('get', {
-                    pluginFiles: { bruno: 'info:\n  name: Custom Name\n' },
+                    pluginExtensions: { bruno: { template: 'info:\n  name: Custom Name\n' } },
                 }),
             ]),
         ]);
@@ -1211,3 +1256,33 @@ describe('mergePluginFile', () => {
     });
 });
 
+describe('validateBrunoExtension', () => {
+    it('accepts an empty object', () => {
+        expect(validateBrunoExtension({})).toBeUndefined();
+    });
+
+    it('accepts { template: <string> }', () => {
+        expect(validateBrunoExtension({ template: 'runtime: {}' })).toBeUndefined();
+    });
+
+    it('rejects a non-object value', () => {
+        const result = validateBrunoExtension('foo') as { errors: string[] };
+        expect(result.errors[0]).toContain('expected an object');
+    });
+
+    it('rejects an array value', () => {
+        const result = validateBrunoExtension(['x']) as { errors: string[] };
+        expect(result.errors[0]).toContain('array');
+    });
+
+    it('rejects template that is not a string', () => {
+        const result = validateBrunoExtension({ template: 7 }) as { errors: string[] };
+        expect(result.errors[0]).toContain("'template' must be a string");
+    });
+
+    it('rejects unknown fields', () => {
+        const result = validateBrunoExtension({ template: 'x', other: 'y' }) as { errors: string[] };
+        expect(result.errors[0]).toContain("unknown field 'other'");
+    });
+});
+