diff --git a/src/actions/api/validate.ts b/src/actions/api/validate.ts index b79fb57b8..40f6f4540 100644 --- a/src/actions/api/validate.ts +++ b/src/actions/api/validate.ts @@ -60,6 +60,9 @@ export class ValidateAction { if (this.hasValidationIssues(linting)) { this.prompts.displayValidationSummary(linting); } + if (!linting.isSuccess) { + this.prompts.lintingFailed(spec.kind()); + } } return validation.isSuccess && linting.isSuccess ? ActionResult.success() diff --git a/src/prompts/api/links.ts b/src/prompts/api/links.ts new file mode 100644 index 000000000..fd88f14eb --- /dev/null +++ b/src/prompts/api/links.ts @@ -0,0 +1,2 @@ +export const CONFIGURING_VALIDATION_URL = + 'https://docs.apimatic.io/v4/define-validate/validate-lint/configuring-validation'; diff --git a/src/prompts/api/validate.ts b/src/prompts/api/validate.ts index 699055275..2e79c1b78 100644 --- a/src/prompts/api/validate.ts +++ b/src/prompts/api/validate.ts @@ -5,9 +5,11 @@ import { ValidationMessages } from '../../types/utils.js'; import { Result } from 'neverthrow'; import { ValidateApiResult, ValidationEntry, ValidationSummary } from '@apimatic/sdk'; import { FilePath } from '../../types/file/filePath.js'; -import { ResolveProblem } from '../../types/resource-context.js'; +import { METADATA_FILE_NAME } from '../../types/project-layout.js'; +import { ResolveProblem, ResourceKind } from '../../types/resource-context.js'; import { format as f } from '../format.js'; import { notZippedForUpload, withSpinner } from '../prompt.js'; +import { CONFIGURING_VALIDATION_URL } from './links.js'; export class ApiValidatePrompts { public async validateApi(fn: Promise>) { @@ -83,6 +85,14 @@ export class ApiValidatePrompts { log.error(error); } + public lintingFailed(kind: ResourceKind): void { + const where = kind === 'project' ? 'beside your API definition' : 'zipped together with your API definition'; + const message = + `If a linting rule doesn't fit your API, turn it off or lower its severity in an ` + + `${f.var(METADATA_FILE_NAME)} ${where}:\n${f.link(CONFIGURING_VALIDATION_URL)}`; + log.info(message); + } + public specUnavailable(problem: ResolveProblem): void { switch (problem.kind) { case 'downloadFailed': { diff --git a/src/prompts/quickstart.ts b/src/prompts/quickstart.ts index 5684204fe..c5618cc2f 100644 --- a/src/prompts/quickstart.ts +++ b/src/prompts/quickstart.ts @@ -11,11 +11,13 @@ import { APIMATIC_CONFIG_FILE_NAME, ConfigFinding, findingClause } from '../type import { PluginConfigWriteFailure } from '../types/plugin-config-context.js'; import { PortalScaffoldProblem, PortalSourceProblem } from '../types/portal/portal-source.js'; import { GENERATED, GITIGNORE, GitignoreFailure } from '../types/project-context.js'; +import { METADATA_FILE_NAME } from '../types/project-layout.js'; import { DownloadProblem, FileReadProblem, ResourceKind } from '../types/resource-context.js'; import { AVAILABLE_LANGUAGES, Language, languageLabel, UPCOMING_LANGUAGES } from '../types/sdk/generate.js'; import { noteWrapped, withSpinner } from './prompt.js'; import { reportAuthorizationFailure } from './portal/authorization.js'; import { convertToOpenApi3, reportSourceProblem, specPath } from './portal/source.js'; +import { CONFIGURING_VALIDATION_URL } from './api/links.js'; const vscodeExtensionUrl = 'https://marketplace.visualstudio.com/items?itemName=apimatic-developers.apimatic-for-vscode'; @@ -134,11 +136,16 @@ Let's get started!`); public specValidationFailed(kind: ResourceKind) { log.error(`Oops, it looks like there are some errors in your API Definition`); + const where = kind === 'project' ? 'beside your API definition' : 'zipped together with your API definition'; const message = [ ...this.validateWithAgent(kind), '', `Or use APIMatic's interactive VS Code Extension:`, - f.link(vscodeExtensionUrl) + f.link(vscodeExtensionUrl), + '', + `If a linting rule doesn't fit your API, turn it off or lower its severity in an ` + + `${f.var(METADATA_FILE_NAME)} ${where}:`, + f.link(CONFIGURING_VALIDATION_URL) ].join('\n'); noteWrapped(message, 'How to fix'); } diff --git a/test/actions/api/validate.test.ts b/test/actions/api/validate.test.ts index 58dbefaa2..3ef51876d 100644 --- a/test/actions/api/validate.test.ts +++ b/test/actions/api/validate.test.ts @@ -111,6 +111,37 @@ describe('ValidateAction', () => { expect(result.getError()).to.equal('invalid'); }); + it('points a spec that fails linting at configuring the rules, naming what kind of spec it was', async () => { + validateViaFile.resolves(ok({ validation: PASSED, linting: FAILED } as never)); + const spec = new FilePath(workingDirectory, new FileName('openapi.yaml')); + fs.writeFileSync(spec.toString(), 'openapi: 3.0.3'); + + const result = await validate(spec); + + expect(result.getError()).to.equal('invalid'); + expect(prompts.lintingFailed.calledOnceWithExactly('file')).to.be.true; + }); + + it('leaves the rules unmentioned when only validation fails, since its rules cannot be turned off', async () => { + validateViaFile.resolves(ok({ validation: FAILED, linting: PASSED } as never)); + const spec = new FilePath(workingDirectory, new FileName('openapi.yaml')); + fs.writeFileSync(spec.toString(), 'openapi: 3.0.3'); + + await validate(spec); + + expect(prompts.lintingFailed.called).to.be.false; + }); + + it('leaves the rules unmentioned when asked not to show the summary, as quickstart does', async () => { + validateViaFile.resolves(ok({ validation: PASSED, linting: FAILED } as never)); + const spec = new FilePath(workingDirectory, new FileName('openapi.yaml')); + fs.writeFileSync(spec.toString(), 'openapi: 3.0.3'); + + await new ValidateAction(workingDirectory, COMMAND_METADATA).execute(spec, false); + + expect(prompts.lintingFailed.called).to.be.false; + }); + it('calls a spec the service refuses outright invalid, and one it never answered for unchecked', async () => { const spec = new FilePath(workingDirectory, new FileName('openapi.yaml')); fs.writeFileSync(spec.toString(), 'openapi: 3.0.3'); diff --git a/test/prompts/api/validate.test.ts b/test/prompts/api/validate.test.ts new file mode 100644 index 000000000..3bedff5f6 --- /dev/null +++ b/test/prompts/api/validate.test.ts @@ -0,0 +1,41 @@ +import { stripVTControlCharacters } from 'node:util'; +import { expect } from 'chai'; +import sinon from 'sinon'; +import { log } from '@clack/prompts'; +import { ApiValidatePrompts } from '../../../src/prompts/api/validate.js'; + +describe('ApiValidatePrompts', () => { + const prompts = new ApiValidatePrompts(); + let info: sinon.SinonStub; + + const printed = () => stripVTControlCharacters(String(info.lastCall.args[0])); + + beforeEach(() => { + info = sinon.stub(log, 'info'); + }); + + afterEach(() => { + sinon.restore(); + }); + + describe('lintingFailed', () => { + it("puts the rules for a project's spec/ in the APIMATIC-META.json beside it", () => { + prompts.lintingFailed('project'); + + expect(printed()).to.equal( + "If a linting rule doesn't fit your API, turn it off or lower its severity in an 'APIMATIC-META.json' " + + 'beside your API definition:\n' + + 'https://docs.apimatic.io/v4/define-validate/validate-lint/configuring-validation' + ); + }); + + // A file or URL is uploaded on its own, so an APIMATIC-META.json next to it is never read. + it('asks for the APIMATIC-META.json in a zip with a spec given as a file or URL', () => { + prompts.lintingFailed('file'); + expect(printed()).to.contain("in an 'APIMATIC-META.json' zipped together with your API definition:\n"); + + prompts.lintingFailed('url'); + expect(printed()).to.contain("in an 'APIMATIC-META.json' zipped together with your API definition:\n"); + }); + }); +}); diff --git a/test/prompts/quickstart.test.ts b/test/prompts/quickstart.test.ts index c862ffebc..e51443e15 100644 --- a/test/prompts/quickstart.test.ts +++ b/test/prompts/quickstart.test.ts @@ -108,6 +108,11 @@ describe('QuickstartPrompts', () => { expect(howToFix()).to.contain( 'https://marketplace.visualstudio.com/items?itemName=apimatic-developers.apimatic-for-vscode' ); + expect(howToFix()).to.contain( + "If a linting rule doesn't fit your API, turn it off or lower its severity in an 'APIMATIC-META.json' " + + 'zipped together with your API definition:' + ); + expect(howToFix()).to.contain('https://docs.apimatic.io/v4/define-validate/validate-lint/configuring-validation'); }); it('suggests validating a spec that came from a URL by its URL', () => { @@ -115,6 +120,7 @@ describe('QuickstartPrompts', () => { write.restore(); expect(howToFix()).to.contain('apimatic api validate --url='); + expect(howToFix()).to.contain('zipped together with your API definition:'); }); it("names validate inline and with no flags for a project's spec/", () => { @@ -124,5 +130,13 @@ describe('QuickstartPrompts', () => { expect(howToFix()).to.contain('Ask an AI coding agent to run apimatic api validate and fix what it reports.'); expect(howToFix()).not.to.contain('--'); }); + + it("puts the rules for a project's spec/ in the APIMATIC-META.json beside it", () => { + prompts.specValidationFailed('project'); + write.restore(); + + expect(howToFix()).to.contain("lower its severity in an 'APIMATIC-META.json' beside your API definition:"); + expect(howToFix()).not.to.contain('zipped'); + }); }); });