Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions src/actions/api/validate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
2 changes: 2 additions & 0 deletions src/prompts/api/links.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
export const CONFIGURING_VALIDATION_URL =
'https://docs.apimatic.io/v4/define-validate/validate-lint/configuring-validation';
12 changes: 11 additions & 1 deletion src/prompts/api/validate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<E>(fn: Promise<Result<ValidateApiResult, E>>) {
Expand Down Expand Up @@ -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': {
Expand Down
9 changes: 8 additions & 1 deletion src/prompts/quickstart.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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');
}
Expand Down
31 changes: 31 additions & 0 deletions test/actions/api/validate.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down
41 changes: 41 additions & 0 deletions test/prompts/api/validate.test.ts
Original file line number Diff line number Diff line change
@@ -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");
});
});
});
14 changes: 14 additions & 0 deletions test/prompts/quickstart.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -108,13 +108,19 @@ 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', () => {
prompts.specValidationFailed('url');
write.restore();

expect(howToFix()).to.contain('apimatic api validate --url=<url>');
expect(howToFix()).to.contain('zipped together with your API definition:');
});

it("names validate inline and with no flags for a project's spec/", () => {
Expand All @@ -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');
});
});
});
Loading