diff --git a/package-lock.json b/package-lock.json index da22ea4..2ae2ba9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,16 +1,16 @@ { "name": "@basketry/typescript-docs", - "version": "0.1.1", + "version": "0.2.0-rc.0", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "@basketry/typescript-docs", - "version": "0.1.1", + "version": "0.2.0-rc.0", "license": "MIT", "dependencies": { - "@basketry/typescript": "^0.1.4", - "basketry": "^0.1.5", + "@basketry/typescript": "^0.2.0", + "basketry": "^0.2.0", "case": "^1.6.3", "prettier": "^2.5.1" }, @@ -562,14 +562,44 @@ "node": ">=6.9.0" } }, + "node_modules/@basketry/ir": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/@basketry/ir/-/ir-0.2.0.tgz", + "integrity": "sha512-jHUGjuj6DlLMPn657PN/+jvzytBU8DBvQ5hJ24Qn2eM0JEUXc6hXAgyowXns8a3/q0AFwNNUwOCiYSULY8SDuw==", + "dependencies": { + "ajv": "^8.17.1" + }, + "funding": { + "url": "https://github.com/sponsors/basketry" + } + }, + "node_modules/@basketry/ir/node_modules/ajv": { + "version": "8.17.1", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz", + "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==", + "dependencies": { + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/@basketry/ir/node_modules/json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==" + }, "node_modules/@basketry/typescript": { - "version": "0.1.4", - "resolved": "https://registry.npmjs.org/@basketry/typescript/-/typescript-0.1.4.tgz", - "integrity": "sha512-yX8Uwd723sMOjXGXAyxLIcCrvi05qAQruh+vtADVP1JfCOclhG4tza8PGhSh5o3MqVswzAGJMKQmAcgDUx5omw==", + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/@basketry/typescript/-/typescript-0.2.0.tgz", + "integrity": "sha512-CF24bt9NiLDccQKqA1iUDYfC+6FMC0IYrd56F2rnXVt9pTkaITk/Rj7IZL8NHHjTLcRw//4EJa/D4eISkbe3xg==", "dependencies": { - "basketry": "^0.1.4", - "case": "^1.6.3", - "prettier": "^2.5.1" + "basketry": "^0.2.0", + "case": "^1.6.3" }, "funding": { "url": "https://github.com/sponsors/basketry" @@ -2193,11 +2223,11 @@ "dev": true }, "node_modules/basketry": { - "version": "0.1.5", - "resolved": "https://registry.npmjs.org/basketry/-/basketry-0.1.5.tgz", - "integrity": "sha512-37bzCSZojSKrL6WCeEopfpOcseiSgvsrKqso506v5o3iftJXZAu1yxh4acvRuqOAyKsIPIvnE/6cgAUUgF3+1g==", + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/basketry/-/basketry-0.2.0.tgz", + "integrity": "sha512-LLd6QdP/2Mnhm2YGDnW5m95/bYaAJJYuuNeDLL/V2ohptorfFJcpnJFrMrfXWMGCnoQDd4ICPTiayKLoXqCkUw==", "dependencies": { - "ajv": "^8.11.0", + "@basketry/ir": "^0.2.0", "case": "^1.6.3", "chalk": "^4.1.2", "ts-node": "^10.7.0", @@ -2211,21 +2241,6 @@ "url": "https://github.com/sponsors/basketry" } }, - "node_modules/basketry/node_modules/ajv": { - "version": "8.17.1", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz", - "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==", - "dependencies": { - "fast-deep-equal": "^3.1.3", - "fast-uri": "^3.0.1", - "json-schema-traverse": "^1.0.0", - "require-from-string": "^2.0.2" - }, - "funding": { - "type": "github", - "url": "https://github.com/sponsors/epoberezkin" - } - }, "node_modules/basketry/node_modules/ansi-styles": { "version": "4.3.0", "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", @@ -2279,11 +2294,6 @@ "node": ">=8" } }, - "node_modules/basketry/node_modules/json-schema-traverse": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", - "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==" - }, "node_modules/basketry/node_modules/supports-color": { "version": "7.2.0", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", @@ -2296,9 +2306,9 @@ } }, "node_modules/brace-expansion": { - "version": "1.1.11", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", - "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "version": "1.1.12", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz", + "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==", "dev": true, "dependencies": { "balanced-match": "^1.0.0", @@ -8099,14 +8109,39 @@ "@babel/helper-validator-identifier": "^7.27.1" } }, + "@basketry/ir": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/@basketry/ir/-/ir-0.2.0.tgz", + "integrity": "sha512-jHUGjuj6DlLMPn657PN/+jvzytBU8DBvQ5hJ24Qn2eM0JEUXc6hXAgyowXns8a3/q0AFwNNUwOCiYSULY8SDuw==", + "requires": { + "ajv": "^8.17.1" + }, + "dependencies": { + "ajv": { + "version": "8.17.1", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz", + "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==", + "requires": { + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2" + } + }, + "json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==" + } + } + }, "@basketry/typescript": { - "version": "0.1.4", - "resolved": "https://registry.npmjs.org/@basketry/typescript/-/typescript-0.1.4.tgz", - "integrity": "sha512-yX8Uwd723sMOjXGXAyxLIcCrvi05qAQruh+vtADVP1JfCOclhG4tza8PGhSh5o3MqVswzAGJMKQmAcgDUx5omw==", + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/@basketry/typescript/-/typescript-0.2.0.tgz", + "integrity": "sha512-CF24bt9NiLDccQKqA1iUDYfC+6FMC0IYrd56F2rnXVt9pTkaITk/Rj7IZL8NHHjTLcRw//4EJa/D4eISkbe3xg==", "requires": { - "basketry": "^0.1.4", - "case": "^1.6.3", - "prettier": "^2.5.1" + "basketry": "^0.2.0", + "case": "^1.6.3" } }, "@bcoe/v8-coverage": { @@ -9337,11 +9372,11 @@ "dev": true }, "basketry": { - "version": "0.1.5", - "resolved": "https://registry.npmjs.org/basketry/-/basketry-0.1.5.tgz", - "integrity": "sha512-37bzCSZojSKrL6WCeEopfpOcseiSgvsrKqso506v5o3iftJXZAu1yxh4acvRuqOAyKsIPIvnE/6cgAUUgF3+1g==", + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/basketry/-/basketry-0.2.0.tgz", + "integrity": "sha512-LLd6QdP/2Mnhm2YGDnW5m95/bYaAJJYuuNeDLL/V2ohptorfFJcpnJFrMrfXWMGCnoQDd4ICPTiayKLoXqCkUw==", "requires": { - "ajv": "^8.11.0", + "@basketry/ir": "^0.2.0", "case": "^1.6.3", "chalk": "^4.1.2", "ts-node": "^10.7.0", @@ -9349,17 +9384,6 @@ "yargs": "^17.4.0" }, "dependencies": { - "ajv": { - "version": "8.17.1", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz", - "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==", - "requires": { - "fast-deep-equal": "^3.1.3", - "fast-uri": "^3.0.1", - "json-schema-traverse": "^1.0.0", - "require-from-string": "^2.0.2" - } - }, "ansi-styles": { "version": "4.3.0", "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", @@ -9395,11 +9419,6 @@ "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==" }, - "json-schema-traverse": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", - "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==" - }, "supports-color": { "version": "7.2.0", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", @@ -9411,9 +9430,9 @@ } }, "brace-expansion": { - "version": "1.1.11", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", - "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "version": "1.1.12", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz", + "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==", "dev": true, "requires": { "balanced-match": "^1.0.0", diff --git a/package.json b/package.json index 51dd3b3..5f45f2d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@basketry/typescript-docs", - "version": "0.1.1", + "version": "0.2.0-rc.0", "description": "Basketry generator for documenting services that have a Typescript language target.", "main": "./lib/index.js", "scripts": { @@ -31,7 +31,7 @@ "bugs": { "url": "https://github.com/basketry/typescript-docs/issues" }, - "homepage": "https://github.com/basketry/typescript-docs#readme", + "homepage": "https://basketry.io/docs/components/@basketry/typescript-docs", "funding": "https://github.com/sponsors/basketry", "devDependencies": { "@types/jest": "^29.5.12", @@ -49,8 +49,8 @@ "typescript": "^4.5.5" }, "dependencies": { - "@basketry/typescript": "^0.1.4", - "basketry": "^0.1.5", + "@basketry/typescript": "^0.2.0", + "basketry": "^0.2.0", "case": "^1.6.3", "prettier": "^2.5.1" } diff --git a/src/interface-info.ts b/src/interface-info.ts index fd2c1fe..90548fd 100644 --- a/src/interface-info.ts +++ b/src/interface-info.ts @@ -92,14 +92,14 @@ export class InterfaceInfo { private init(): void { for (const method of this.int.methods) { for (const param of method.parameters) { - for (const t of this.traverse(param.typeName.value, 'input')) { + for (const t of this.traverse(param.value.typeName.value, 'input')) { // noop } } - if (method.returnType && !method.returnType.isPrimitive) { + if (method.returns?.value.kind === 'ComplexValue') { for (const t of this.traverse( - method.returnType.typeName.value, + method.returns.value.typeName.value, 'output', )) { // noop @@ -132,8 +132,8 @@ export class InterfaceInfo { yield type; for (const prop of type.properties) { - if (!prop.isPrimitive) { - yield* this.traverse(prop.typeName.value, mode); + if (prop.value.kind === 'ComplexValue') { + yield* this.traverse(prop.value.typeName.value, mode); } } } else if (union) { diff --git a/src/readme-factory.test.ts b/src/readme-factory.test.ts index 6c8d818..c4271cd 100644 --- a/src/readme-factory.test.ts +++ b/src/readme-factory.test.ts @@ -1,30 +1,15 @@ import { readFileSync } from 'fs'; import { join } from 'path'; -import { generateDocs } from './readme-factory'; +import { generateFiles } from './snapshot/test-utils'; const pkg = require('../package.json'); const withVersion = `${pkg.name}@${pkg.version}`; const withoutVersion = `${pkg.name}@{{version}}`; describe('InterfaceFactory', () => { - it('recreates a valid snapshot', () => { - // ARRANGE - const service = require('basketry/lib/example-ir.json'); - - // ACT - const files = generateDocs(service, { - sorbet: { - typesModule: 'types', - enumsModule: 'enums', - }, - }); - - // ASSERT - for (const file of [...files]) { - const path = join('src', 'snapshot', ...file.path); - const snapshot = readFileSync(path) - .toString() - .replace(withoutVersion, withVersion); + it('recreates a valid snapshot using the Engine', async () => { + for await (const file of await generateFiles()) { + const snapshot = readFileSync(join(...file.path)).toString(); expect(file.contents).toStrictEqual(snapshot); } }); diff --git a/src/readme-factory.ts b/src/readme-factory.ts index cbd2df5..a360e04 100644 --- a/src/readme-factory.ts +++ b/src/readme-factory.ts @@ -5,13 +5,13 @@ import { getUnionByName, Interface, isRequired, + MemberValue, Method, Parameter, Property, - ReturnType, + ReturnValue, Service, Type, - TypedValue, ValidationRule, warning, } from 'basketry'; @@ -160,32 +160,33 @@ class Builder { yield* this.buildParameter(param); } } - if (method.returnType) { + if (method.returns) { yield ''; - yield `Returns: ${this.buildLinkedTypeName(method.returnType)}${ - method.returnType.isArray ? '[]' : '' + yield `Returns: ${this.buildLinkedTypeName(method.returns)}${ + method.returns.value.isArray ? '[]' : '' }`; } - if (Array.isArray(method.description)) { + if (method.description) { for (const line of method.description) { yield ''; yield line.value; } - } else if (method.description) { - yield ''; - yield method.description.value; } yield ''; } private buildMethodDefinition(method: Method): string { - const hasRequiredParams = !!method.parameters.find(isRequired); + const hasRequiredParams = !!method.parameters.find((p) => + isRequired(p.value), + ); const parameters = method.parameters.length ? `({${sortParameters(method.parameters) .map( (param) => - `${buildParameterName(param)}${isRequired(param) ? '' : '?'}`, + `${buildParameterName(param)}${ + isRequired(param.value) ? '' : '?' + }`, ) .join(', ')}}${hasRequiredParams ? '' : ' | undefined'})` : ''; @@ -196,47 +197,47 @@ class Builder { private *buildParameter(param: Parameter): Iterable { yield `- \`${buildParameterName(param)}\` ${this.buildLinkedTypeName( param, - )}${isRequired(param) ? '' : ' (optional)'}${this.buildParameterDescription( - param, - )}`; + )}${ + isRequired(param.value) ? '' : ' (optional)' + }${this.buildParameterDescription(param)}`; - yield* this.buildRules(param.rules); + yield* this.buildRules(param.value.rules); } private *buildRules(rules: Iterable): Iterable { for (const rule of rules) { switch (rule.id) { - case 'array-max-items': + case 'ArrayMaxItems': yield ` - Max array length: \`${rule.max.value}\``; break; - case 'array-min-items': + case 'ArrayMinItems': yield ` - Min array length: \`${rule.min.value}\``; break; - case 'array-unique-items': + case 'ArrayUniqueItems': yield ` - Values must be unique`; break; - case 'number-gt': + case 'NumberGT': yield ` - Must be greater than \`${rule.value.value}\``; break; - case 'number-gte': + case 'NumberGTE': yield ` - Must be greater than or equal to \`${rule.value.value}\``; break; - case 'number-lt': + case 'NumberLT': yield ` - Must be less than \`${rule.value.value}\``; break; - case 'number-lte': + case 'NumberLTE': yield ` - Must be less than or equal to \`${rule.value.value}\``; break; - case 'number-multiple-of': + case 'NumberMultipleOf': yield ` - Must be a multiple of \`${rule.value.value}\``; break; - case 'string-max-length': + case 'StringMaxLength': yield ` - Max length: \`${rule.length.value}\``; break; - case 'string-min-length': + case 'StringMinLength': yield ` - Min length: \`${rule.length.value}\``; break; - case 'string-pattern': + case 'StringPattern': yield ` - Must match pattern: \`${rule.pattern.value}\``; break; } @@ -244,22 +245,23 @@ class Builder { } private buildLinkedTypeName( - param: Parameter | Property | ReturnType | TypedValue, + param: Parameter | Property | ReturnValue | MemberValue, ): string { - const union = getUnionByName(this.service, param.typeName.value); + const memberValue = getMemberValue(param); + const union = getUnionByName(this.service, memberValue.typeName.value); if (union) { const members = union.members - .map((m: TypedValue) => this.buildLinkedTypeName(m)) + .map((m: MemberValue) => this.buildLinkedTypeName(m)) .join(' | '); - return param.isArray ? `(${members})[]` : members; + return memberValue.isArray ? `(${members})[]` : members; } const typeName = this.buildTypeName(param, true); - if (param.isPrimitive) { + if (memberValue.kind === 'PrimitiveValue') { let uri: string | undefined = undefined; - switch (param.typeName.value) { + switch (memberValue.typeName.value) { case 'string': uri = 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type'; @@ -288,12 +290,14 @@ class Builder { } if (uri) { - return `[<${typeName}${param.isArray ? '[]' : ''}>](${uri})`; + return `[<${typeName}${ + memberValue.isArray ? '[]' : '' + }>](${uri})`; } else { - return `<${typeName}${param.isArray ? '[]' : ''}>`; + return `<${typeName}${memberValue.isArray ? '[]' : ''}>`; } } else { - return `[<${typeName}${param.isArray ? '[]' : ''}>](${anchor( + return `[<${typeName}${memberValue.isArray ? '[]' : ''}>](${anchor( typeName, )})`; } @@ -301,14 +305,11 @@ class Builder { private *buildInterfaceDescription(int: Interface): Iterable { if (int.description) { - if (Array.isArray(int.description)) { + if (int.description) { for (const para of int.description) { yield para.value; yield ''; } - } else { - yield int.description.value; - yield ''; } } } @@ -316,11 +317,7 @@ class Builder { private buildParameterDescription(param: Parameter | Property): string { if (!param.description) return ''; - if (Array.isArray(param.description)) { - return ` - ${param.description.map((line) => line.value).join(' ')}`; - } - - return ` - ${param.description.value}`; + return ` - ${param.description.map((line) => line.value).join(' ')}`; } private *buildTypeDocs(type: Type): Iterable { @@ -332,9 +329,6 @@ class Builder { yield ''; yield line.value; } - } else if (type.description) { - yield ''; - yield type.description.value; } if (type.properties.length) { yield ''; @@ -346,18 +340,20 @@ class Builder { yield ''; yield `#### Map Properties`; yield ''; - yield `- Keys: ${this.buildLinkedTypeName(type.mapProperties.key)}`; - yield `- Values: ${this.buildLinkedTypeName(type.mapProperties.value)}`; + yield `- Keys: ${this.buildLinkedTypeName(type.mapProperties.key.value)}`; + yield `- Values: ${this.buildLinkedTypeName( + type.mapProperties.value.value, + )}`; } yield ''; } private *buildProperty(prop: Property): Iterable { yield `- \`${buildPropertyName(prop)}\` ${this.buildLinkedTypeName(prop)}${ - isRequired(prop) ? '' : ' (optional)' + isRequired(prop.value) ? '' : ' (optional)' }${this.buildParameterDescription(prop)}`; - yield* this.buildRules(prop.rules); + yield* this.buildRules(prop.value.rules); } private *buildEnumDocs(e: Enum): Iterable { @@ -374,11 +370,11 @@ class Builder { yield ''; yield description; } - if (e.values.length) { + if (e.members.length) { yield ''; - for (const value of e.values) { - const valueDescription = valueDescriptions?.[value.content.value]; - yield `- \`${value.content.value}\`${ + for (const member of e.members) { + const valueDescription = valueDescriptions?.[member.content.value]; + yield `- \`${member.content.value}\`${ valueDescription ? ` - ${valueDescription}` : '' }`; } @@ -387,10 +383,10 @@ class Builder { } private buildTypeName( - type: Parameter | Property | ReturnType | TypedValue, + type: Parameter | Property | ReturnValue | MemberValue, skipArrayify: boolean = false, ): string { - const fullyQualifiedName = buildTypeName(type); + const fullyQualifiedName = buildTypeName(getMemberValue(type)); if (fullyQualifiedName.endsWith('[]') && skipArrayify) { return fullyQualifiedName.substring(0, fullyQualifiedName.length - 2); @@ -409,3 +405,11 @@ function sortParameters(parameters: Parameter[]): Parameter[] { function anchor(name: string): string { return `#${name.toLocaleLowerCase().split(' ').join('-')}`; } + +function getMemberValue( + node: Parameter | Property | ReturnValue | MemberValue, +): MemberValue { + return node.kind === 'ComplexValue' || node.kind === 'PrimitiveValue' + ? node + : node.value; +} diff --git a/src/snapshot/create-snapshot.ts b/src/snapshot/create-snapshot.ts index f16711a..bf94732 100644 --- a/src/snapshot/create-snapshot.ts +++ b/src/snapshot/create-snapshot.ts @@ -1,32 +1,12 @@ -import { withGitattributes } from 'basketry'; import { writeFileSync, mkdirSync } from 'fs'; import { join } from 'path'; -import { generateDocs } from '../readme-factory'; -const pkg = require('../../package.json'); -const withVersion = `${pkg.name}@${pkg.version}`; -const withoutVersion = `${pkg.name}@{{version}}`; +import { generateFiles } from './test-utils'; -const service = require('basketry/lib/example-ir.json'); - -const options = { - sorbet: { - typesModule: 'types', - enumsModule: 'enums', - }, -}; - -const snapshotFiles = [...generateDocs(service, options)]; - -for (const file of withGitattributes(snapshotFiles)) { - const path = file.path.slice(0, file.path.length - 1); - const filename = file.path[file.path.length - 1]; - - const fullpath = [process.cwd(), 'src', 'snapshot', ...path]; - - mkdirSync(join(...fullpath), { recursive: true }); - writeFileSync( - join(...fullpath, filename), - file.contents.replace(withVersion, withoutVersion), - ); -} +(async () => { + for await (const file of generateFiles()) { + const directory = join(...file.path.slice(0, file.path.length - 1)); + mkdirSync(directory, { recursive: true }); + writeFileSync(join(...file.path), file.contents); + } +})(); diff --git a/src/snapshot/test-utils.ts b/src/snapshot/test-utils.ts new file mode 100644 index 0000000..d799c0e --- /dev/null +++ b/src/snapshot/test-utils.ts @@ -0,0 +1,35 @@ +import { Engine, File } from 'basketry'; +import { generateDocs } from '../readme-factory'; +import { NamespacedTypescriptOptions } from '@basketry/typescript/lib/types'; + +const pkg = require('../../package.json'); +const withVersion = `${pkg.name}@${pkg.version}`; +const withoutVersion = `${pkg.name}@{{version}}`; + +export async function* generateFiles(): AsyncIterable { + const service = require('@basketry/ir/lib/example.json'); + + const options: NamespacedTypescriptOptions = {}; + + const { engines } = await Engine.load({ + sourcePath: 'source/path.ext', + sourceContent: JSON.stringify(service), + parser: (x) => ({ service: JSON.parse(x), violations: [] }), + generators: [generateDocs], + options, + }); + + for (const engine of engines) { + await engine.runParser(); + await engine.runGenerators(); + + for (const file of engine.files) { + if (file.path[0] !== '.gitattributes') { + yield { + path: [process.cwd(), 'src', 'snapshot', ...file.path], + contents: file.contents.replace(withVersion, withoutVersion), + }; + } + } + } +} diff --git a/src/snapshot/v1/auth-permutation-service.md b/src/snapshot/v1/auth-permutation-service.md index 11834cb..c001ac2 100644 --- a/src/snapshot/v1/auth-permutation-service.md +++ b/src/snapshot/v1/auth-permutation-service.md @@ -9,7 +9,7 @@ To make changes to the contents of this file: 2. Run the Basketry CLI About Basketry: https://basketry.io -About @basketry/typescript-docs: https://github.com/basketry/typescript-docs#readme +About @basketry/typescript-docs: https://basketry.io/docs/components/@basketry/typescript-docs ---> # Auth Permutation Service diff --git a/src/snapshot/v1/exhaustive-service.md b/src/snapshot/v1/exhaustive-service.md index 597d98d..6f0db59 100644 --- a/src/snapshot/v1/exhaustive-service.md +++ b/src/snapshot/v1/exhaustive-service.md @@ -9,7 +9,7 @@ To make changes to the contents of this file: 2. Run the Basketry CLI About Basketry: https://basketry.io -About @basketry/typescript-docs: https://github.com/basketry/typescript-docs#readme +About @basketry/typescript-docs: https://basketry.io/docs/components/@basketry/typescript-docs ---> # Exhaustive Service @@ -18,7 +18,7 @@ About @basketry/typescript-docs: https://github.com/basketry/typescript-docs#rea - [exhaustiveFormats](#exhaustiveformats) - [exhaustiveParams](#exhaustiveparams) - Types - - [ExhaustiveParamsBody](#exhaustiveparamsbody) + - [ExhaustiveParamsString](#exhaustiveparamsstring) - Enums - [ExhaustiveParamsHeaderEnum](#exhaustiveparamsheaderenum) - [ExhaustiveParamsHeaderEnumArray](#exhaustiveparamsheaderenumarray) @@ -45,9 +45,8 @@ About @basketry/typescript-docs: https://github.com/basketry/typescript-docs#rea ### exhaustiveParams -`exhaustiveParams({body?, headerBoolean?, headerBooleanArray?, headerEnum?, headerEnumArray?, headerInteger?, headerIntegerArray?, headerNumber?, headerNumberArray?, headerString?, headerStringArray?, pathBoolean, pathBooleanArray, pathEnum, pathEnumArray, pathInteger, pathIntegerArray, pathNumber, pathNumberArray, pathString, pathStringArray, queryBoolean?, queryBooleanArray?, queryEnum?, queryEnumArray?, queryInteger?, queryIntegerArray?, queryNumber?, queryNumberArray?, queryString?, queryStringArray?})` +`exhaustiveParams({headerBoolean?, headerBooleanArray?, headerEnum?, headerEnumArray?, headerInteger?, headerIntegerArray?, headerNumber?, headerNumberArray?, headerString?, headerStringArray?, pathBoolean, pathBooleanArray, pathEnum?, pathEnumArray?, pathInteger, pathIntegerArray, pathNumber, pathNumberArray, pathString, pathStringArray, queryBoolean?, queryBooleanArray?, queryEnum?, queryEnumArray?, queryInteger?, queryIntegerArray?, queryNumber?, queryNumberArray?, queryString?, queryStringArray?, string?})` -- `body` [<ExhaustiveParamsBody>](#exhaustiveparamsbody) (optional) - `headerBoolean` [<boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type) (optional) - `headerBooleanArray` [<boolean[]>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type) (optional) - `headerEnum` [<ExhaustiveParamsHeaderEnum>](#exhaustiveparamsheaderenum) (optional) @@ -60,8 +59,8 @@ About @basketry/typescript-docs: https://github.com/basketry/typescript-docs#rea - `headerStringArray` [<string[]>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) (optional) - `pathBoolean` [<boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type) - `pathBooleanArray` [<boolean[]>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#boolean_type) -- `pathEnum` [<ExhaustiveParamsPathEnum>](#exhaustiveparamspathenum) -- `pathEnumArray` [<ExhaustiveParamsPathEnumArray[]>](#exhaustiveparamspathenumarray) +- `pathEnum` [<ExhaustiveParamsPathEnum>](#exhaustiveparamspathenum) (optional) +- `pathEnumArray` [<ExhaustiveParamsPathEnumArray[]>](#exhaustiveparamspathenumarray) (optional) - `pathInteger` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type) - `pathIntegerArray` [<number[]>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type) - `pathNumber` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type) @@ -78,12 +77,13 @@ About @basketry/typescript-docs: https://github.com/basketry/typescript-docs#rea - `queryNumberArray` [<number[]>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type) (optional) - `queryString` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) (optional) - `queryStringArray` [<string[]>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) (optional) +- `string` [<ExhaustiveParamsString>](#exhaustiveparamsstring) (optional) ## Types -### ExhaustiveParamsBody +### ExhaustiveParamsString -`ExhaustiveParamsBody` +`ExhaustiveParamsString` - `foo` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) (optional) - `bar` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) (optional) diff --git a/src/snapshot/v1/gizmo-service.md b/src/snapshot/v1/gizmo-service.md index c530cb2..bdae40a 100644 --- a/src/snapshot/v1/gizmo-service.md +++ b/src/snapshot/v1/gizmo-service.md @@ -9,21 +9,18 @@ To make changes to the contents of this file: 2. Run the Basketry CLI About Basketry: https://basketry.io -About @basketry/typescript-docs: https://github.com/basketry/typescript-docs#readme +About @basketry/typescript-docs: https://basketry.io/docs/components/@basketry/typescript-docs ---> # Gizmo Service -Single paragraph description - - Methods - [createGizmo](#creategizmo) - [getGizmos](#getgizmos) - [updateGizmo](#updategizmo) - - [uploadGizmo](#uploadgizmo) - Types + - [GetGizmosResponse](#getgizmosresponse) - [Gizmo](#gizmo) - - [GizmosResponse](#gizmosresponse) - Enums - [CreateGizmoSize](#creategizmosize) - [ProductSize](#productsize) @@ -48,7 +45,7 @@ Has a description in addition to a summary - `search` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) (optional) -Returns: [<GizmosResponse>](#gizmosresponse) +Returns: [<GetGizmosResponse>](#getgizmosresponse) Only has a summary @@ -63,13 +60,13 @@ Only has a summary Returns: [<Gizmo>](#gizmo) -### uploadGizmo +## Types -`uploadGizmo({data})` +### GetGizmosResponse -- `data` <Blob> +`GetGizmosResponse` -## Types +- `data` [<Gizmo[]>](#gizmo) (optional) ### Gizmo @@ -80,17 +77,6 @@ Returns: [<Gizmo>](#gizmo) - `name` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) (optional) - `size` [<ProductSize>](#productsize) (optional) -#### Map Properties - -- Keys: [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) -- Values: [<GizmoMapValue>](#gizmomapvalue) - -### GizmosResponse - -`GizmosResponse` - -- `data` [<Gizmo[]>](#gizmo) - ## Enums ### CreateGizmoSize diff --git a/src/snapshot/v1/widget-service.md b/src/snapshot/v1/widget-service.md index f7249ab..02ed8ab 100644 --- a/src/snapshot/v1/widget-service.md +++ b/src/snapshot/v1/widget-service.md @@ -9,15 +9,11 @@ To make changes to the contents of this file: 2. Run the Basketry CLI About Basketry: https://basketry.io -About @basketry/typescript-docs: https://github.com/basketry/typescript-docs#readme +About @basketry/typescript-docs: https://basketry.io/docs/components/@basketry/typescript-docs ---> # Widget Service -First paragraph of a multi-paragraph description - -Second paragraph of a multi-paragraph description - - Methods - [createWidget](#createwidget) - [deleteWidgetFoo](#deletewidgetfoo) @@ -25,9 +21,8 @@ Second paragraph of a multi-paragraph description - [getWidgets](#getwidgets) - [putWidget](#putwidget) - Types - - [CreateWidgetBody](#createwidgetbody) + - [CreateWidgetString](#createwidgetstring) - [Widget](#widget) - - [WidgetData](#widgetdata) - [WidgetFoo](#widgetfoo) - Enums - [ProductSize](#productsize) @@ -36,22 +31,22 @@ Second paragraph of a multi-paragraph description ### createWidget -`createWidget({body?} | undefined)` +`createWidget({string?} | undefined)` -- `body` [<CreateWidgetBody>](#createwidgetbody) (optional) - The new widget +- `string` [<CreateWidgetString>](#createwidgetstring) (optional) - The new widget ### deleteWidgetFoo -`deleteWidgetFoo({id})` +`deleteWidgetFoo({id?} | undefined)` -- `id` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) - The widget ID +- `id` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) (optional) - The widget ID - Max length: `30` ### getWidgetFoo -`getWidgetFoo({id})` +`getWidgetFoo({id?} | undefined)` -- `id` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) - The widget ID +- `id` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) (optional) - The widget ID - Max length: `30` Returns: [<Widget>](#widget) @@ -68,22 +63,22 @@ Returns: [<Widget>](#widget) ## Types -### CreateWidgetBody +### CreateWidgetString -`CreateWidgetBody` +`CreateWidgetString` -- `name` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) +- `name` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) (optional) ### Widget `Widget` -- `id` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) +- `id` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) (optional) - Max length: `30` - `name` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) (optional) - Max length: `30` - Must match pattern: `[0-9a-fA-F]+` -- `fiz` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type) +- `fiz` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type) (optional) - Must be a multiple of `3` - `buzz` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type) (optional) - Must be a multiple of `5` @@ -91,23 +86,13 @@ Returns: [<Widget>](#widget) - Must be a multiple of `15` - `foo` [<WidgetFoo>](#widgetfoo) (optional) - `size` [<ProductSize>](#productsize) (optional) -- `data` [<WidgetData>](#widgetdata) - -### WidgetData - -`WidgetData` - -#### Map Properties - -- Keys: [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#string_type) -- Values: [<GizmoMapValue>](#gizmomapvalue) ### WidgetFoo `WidgetFoo` -- `fiz` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type) (optional) -- `buzz` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type) +- `fiz` [<123456>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type) (optional) +- `buzz` [<number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type) (optional) ## Enums