Add parameters to compiler for specifying input and output

Author: sethmlarson

.github/workflows/gh-pages-report.yml

@@ -27,7 +27,7 @@ jobs:
 
     - name: Generate output
       run: |
-        npm run generate-schema --prefix compiler
+        make generate
 
     - name: Generate graph
       run: |

.github/workflows/output-check.yml

@@ -22,7 +22,7 @@ jobs:
 
     - name: Generate output
       run: |
-        npm run generate-schema --prefix compiler
+        make generate
         npm run start --prefix typescript-generator
 
     - name: Validate TS output

.gitignore

@@ -62,3 +62,6 @@ output/schema/routes.go
 
 # Editor lockfiles
 .*.swp
+
+# Test suite outputs
+compiler/test/**/output/

Makefile

@@ -8,7 +8,7 @@ validate-no-cache: ## Validate a given endpoint request or response without loca
 
 generate:	  ## Generate the output spec
 	@echo ">> generating the spec .."
-	@npm run generate-schema --prefix compiler
+	@npm run generate-schema --prefix compiler -- --spec ../specification/ --output ../output/
 	@npm run start --prefix typescript-generator
 
 compile:	## Compile the specification

compiler/src/compiler.ts

@@ -17,7 +17,7 @@
  * under the License.
  */
 
-import { writeFile } from 'fs/promises'
+import { writeFile, mkdir } from 'fs/promises'
 import { join } from 'path'
 import stringify from 'safe-stable-stringify'
 import { Model } from './model/metamodel'
@@ -41,17 +41,19 @@ export default class Compiler {
   jsonSpec: Map<string, JsonSpec>
   errors: ValidationErrors
   specsFolder: string
+  outputFolder: string
 
-  constructor (specsFolder: string) {
+  constructor (specsFolder: string, outputFolder: string) {
     this.queue = []
     this.errors = new ValidationErrors()
     this.specsFolder = specsFolder
+    this.outputFolder = outputFolder
   }
 
   generateModel (): this {
     this.jsonSpec = buildJsonSpec()
     const endpoints = compileEndpoints()
-    this.model = compileSpecification(endpoints, this.specsFolder)
+    this.model = compileSpecification(endpoints, this.specsFolder, this.outputFolder)
     return this
   }
 
@@ -60,16 +62,17 @@ export default class Compiler {
       this.model = await step(this.model, this.jsonSpec, this.errors)
     }
 
+    await mkdir(join(this.outputFolder, 'schema'), { recursive: true })
     await writeFile(
-      join(__dirname, '..', '..', 'output', 'schema', 'schema.json'),
+      join(this.outputFolder, 'schema', 'schema.json'),
       stringify(this.model, null, 2),
       'utf8'
     )
 
     this.errors.log()
 
     await writeFile(
-      join(__dirname, '..', '..', 'output', 'schema', 'validation-errors.json'),
+      join(this.outputFolder, 'schema', 'validation-errors.json'),
       stringify(this.errors, null, 2),
       'utf8'
     )

compiler/src/index.ts

@@ -17,8 +17,9 @@
  * under the License.
  */
 
-import { readFileSync } from 'fs'
-import { join } from 'path'
+import { readFileSync, existsSync, lstatSync } from 'fs'
+import { join, resolve } from 'path'
+import { argv } from 'zx'
 import Compiler from './compiler'
 import validateRestSpec from './steps/validate-rest-spec'
 import addInfo from './steps/add-info'
@@ -36,7 +37,32 @@ if (nodejsMajor !== nvmMajor) {
   process.exit(1)
 }
 
-const compiler = new Compiler(join(__dirname, '..', '..', 'specification'))
+let specsFolder: string|undefined = argv.spec
+if (specsFolder !== '' && specsFolder !== undefined) {
+  // We were given a specification, let's make sure it's a directory.
+  specsFolder = resolve(specsFolder)
+
+  // lstatSync raises an error if there's nothing at the path so we
+  // check that something exists there first before checking it's a directory.
+  const specFolderIsDirectory: boolean = (existsSync(specsFolder) && lstatSync(specsFolder).isDirectory())
+  if (!specFolderIsDirectory) {
+    console.error(`The specification specified at '${specsFolder}' wasn't a valid directory`)
+    process.exit(1)
+  }
+// User didn't specify a spec location so we ask for one.
+} else {
+  console.error('--spec must be specified and be a valid directory path')
+  process.exit(1)
+}
+
+// It's okay if the output folder doesn't exist initially.
+const outputFolder: string|undefined = argv.output
+if (outputFolder === '' || outputFolder === undefined) {
+  console.error('--output must be specified')
+  process.exit(1)
+}
+
+const compiler = new Compiler(specsFolder, outputFolder)
 
 compiler
   .generateModel()

compiler/src/model/build-model.ts

@@ -17,7 +17,7 @@
  * under the License.
  */
 
-import { writeFileSync } from 'fs'
+import { mkdirSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import { STATUS_CODES } from 'http'
 import {
@@ -88,7 +88,7 @@ export function compileEndpoints (): Record<string, model.Endpoint> {
   return map
 }
 
-export function compileSpecification (endpointMappings: Record<string, model.Endpoint>, specsFolder: string): model.Model {
+export function compileSpecification (endpointMappings: Record<string, model.Endpoint>, specsFolder: string, outputFolder: string): model.Model {
   const tsConfigFilePath = join(specsFolder, 'tsconfig.json')
   const project = new Project({ tsConfigFilePath })
 
@@ -123,10 +123,11 @@ export function compileSpecification (endpointMappings: Record<string, model.End
     }
   }
 
+  mkdirSync(join(outputFolder, 'dangling-types'), { recursive: true })
   writeFileSync(
-    join(__dirname, '..', '..', '..', 'output', 'dangling-types', 'dangling.csv'),
+    join(outputFolder, 'dangling-types', 'dangling.csv'),
     definedButNeverUsed.join('\n'),
-    'utf8'
+    { encoding: 'utf8', flag: 'w' }
   )
   for (const api of jsonSpec.keys()) {
     model.endpoints.push(endpointMappings[api])

compiler/test/body-codegen-name/test.ts

@@ -23,9 +23,10 @@ import Compiler from '../../src/compiler'
 import * as Model from '../../src/model/metamodel'
 
 const specsFolder = join(__dirname, 'specification')
+const outputFolder = join(__dirname, 'output')
 
 test('type reference body must have a @codegen_name', t => {
-  const compiler = new Compiler(specsFolder)
+  const compiler = new Compiler(specsFolder, outputFolder)
   const error = t.throws(() => compiler.generateModel())
   t.is(error?.message, 'You should configure a body @codegen_name')
 })

compiler/test/duplicate-body-codegen-name/test.ts

@@ -23,9 +23,10 @@ import Compiler from '../../src/compiler'
 import * as Model from '../../src/model/metamodel'
 
 const specsFolder = join(__dirname, 'specification')
+const outputFolder = join(__dirname, 'output')
 
 test('@codegen_name cannot already exist elsewhere', t => {
-  const compiler = new Compiler(specsFolder)
+  const compiler = new Compiler(specsFolder, outputFolder)
   const error = t.throws(() => compiler.generateModel())
   t.is(error?.message, "The codegen_name 'id' already exists as a property in the path or query.")
 })

compiler/test/no-body/test.ts

@@ -23,9 +23,10 @@ import Compiler from '../../src/compiler'
 import * as Model from '../../src/model/metamodel'
 
 const specsFolder = join(__dirname, 'specification')
+const outputFolder = join(__dirname, 'output')
 
 test("Body cannot be defined if the API methods don't allow it", t => {
-  const compiler = new Compiler(specsFolder)
+  const compiler = new Compiler(specsFolder, outputFolder)
   const error = t.throws(() => compiler.generateModel())
   t.is(error?.message, "_global.info.Request can't have a body, allowed methods: GET")
 })

compiler/test/request-fields/test.ts

@@ -23,9 +23,10 @@ import Compiler from '../../src/compiler'
 import * as Model from '../../src/model/metamodel'
 
 const specsFolder = join(__dirname, 'specification')
+const outputFolder = join(__dirname, 'output')
 
 test('Request definition cannot have unknown properties', t => {
-  const compiler = new Compiler(specsFolder)
+  const compiler = new Compiler(specsFolder, outputFolder)
   const error = t.throws(() => compiler.generateModel())
   t.is(error?.message, 'Unknown request property: headers')
 })

compiler/test/response-exceptions-fields/test.ts

@@ -23,9 +23,10 @@ import Compiler from '../../src/compiler'
 import * as Model from '../../src/model/metamodel'
 
 const specsFolder = join(__dirname, 'specification')
+const outputFolder = join(__dirname, 'output')
 
 test('Response exceptions definition cannot have unknown properties', t => {
-  const compiler = new Compiler(specsFolder)
+  const compiler = new Compiler(specsFolder, outputFolder)
   const error = t.throws(() => compiler.generateModel())
   t.is(error?.message, 'Exception.body and Exception.statusCode are the only Exception properties supported')
 })

compiler/test/response-fields/test.ts

@@ -23,9 +23,10 @@ import Compiler from '../../src/compiler'
 import * as Model from '../../src/model/metamodel'
 
 const specsFolder = join(__dirname, 'specification')
+const outputFolder = join(__dirname, 'output')
 
 test('Response definition cannot have unknown properties', t => {
-  const compiler = new Compiler(specsFolder)
+  const compiler = new Compiler(specsFolder, outputFolder)
   const error = t.throws(() => compiler.generateModel())
   t.is(error?.message, 'Response.body and Response.exceptions are the only Response properties supported')
 })

compiler/test/types/test.ts

@@ -23,7 +23,8 @@ import Compiler from '../../src/compiler'
 import * as Model from '../../src/model/metamodel'
 
 const specsFolder = join(__dirname, 'specification')
-const compiler = new Compiler(specsFolder)
+const outputFolder = join(__dirname, 'output')
+const compiler = new Compiler(specsFolder, outputFolder)
 const { model } = compiler.generateModel()
 
 test('interfaces', t => {

compiler/test/writes-to-output/specification/_global/index/request.ts

@@ -0,0 +1,25 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you 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.
+ */
+
+/**
+ * @rest_spec_name index
+ * @since 0.0.0
+ * @stability stable
+ */
+export interface Request {}

compiler/test/writes-to-output/specification/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../../specification/tsconfig.json",
+  "typeRoots": ["./**/*.ts"],
+  "include": ["./**/*.ts"]
+}

compiler/test/writes-to-output/test.ts

@@ -0,0 +1,37 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you 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 { join } from 'path'
+import { existsSync, lstatSync, rmSync } from 'fs'
+import test from 'ava'
+import Compiler from '../../src/compiler'
+import * as Model from '../../src/model/metamodel'
+
+const specsFolder = join(__dirname, 'specification')
+const outputFolder = join(__dirname, 'output')
+
+test('compiler creates schema directory at outputFolder', async t => {
+  rmSync(outputFolder, {recursive: true, force: true});
+
+  const compiler = new Compiler(specsFolder, outputFolder)
+  await compiler.generateModel().write();
+
+  const schemaFolder = join(outputFolder, 'schema')
+  t.true(existsSync(schemaFolder) && lstatSync(schemaFolder).isDirectory());
+})

compiler/test/wrong-api-name/test.ts

@@ -23,9 +23,10 @@ import Compiler from '../../src/compiler'
 import * as Model from '../../src/model/metamodel'
 
 const specsFolder = join(__dirname, 'specification')
+const outputFolder = join(__dirname, 'output')
 
 test('Wrong rest_spec_name for request definition', t => {
-  const compiler = new Compiler(specsFolder)
+  const compiler = new Compiler(specsFolder, outputFolder)
   const error = t.throws(() => compiler.generateModel())
   t.true(error?.message.startsWith("The api 'foobar' does not exists, did you mean"))
 })

compiler/test/wrong-namespace/test.ts

@@ -23,9 +23,10 @@ import Compiler from '../../src/compiler'
 import * as Model from '../../src/model/metamodel'
 
 const specsFolder = join(__dirname, 'specification')
+const outputFolder = join(__dirname, 'output')
 
 test('Wrong namespace for request definition', t => {
-  const compiler = new Compiler(specsFolder)
+  const compiler = new Compiler(specsFolder, outputFolder)
   const error = t.throws(() => compiler.generateModel())
   t.is(error?.message, 'Cannot find url template for _global.foobar, very likely the specification folder does not follow the rest-api-spec')
 })