Adding versioning check for TypeSpec init template

common/changes/@typespec/compiler/inittemplateversion_2023-06-30-07-32.json

@@ -0,0 +1,10 @@
+{
+ "changes": [
+ {
+ "packageName": "@typespec/compiler",
+ "comment": "**Breaking change** Updating tsp init template schema for future extensibility. Older tsp version will fail validation.",
+ "type": "none"
+ }
+ ],
+ "packageName": "@typespec/compiler"
+}

packages/compiler/package.json

@@ -81,6 +81,7 @@
  "mustache": "~4.2.0",
  "prettier": "~2.8.7",
  "prompts": "~2.4.1",
+ "semver": "^7.3.8",
  "vscode-languageserver": "~8.1.0",
  "vscode-languageserver-textdocument": "~1.0.1",
  "yargs": "~17.7.1",
@@ -95,6 +96,7 @@
  "@types/node": "~18.11.9",
  "@types/prettier": "2.6.0",
  "@types/prompts": "~2.4.3",
+ "@types/semver": "^7.3.13",
  "@types/yargs": "~17.0.24",
  "@typespec/eslint-config-typespec": "workspace:~0.7.0",
  "@typespec/internal-build-utils": "workspace:~0.4.2",

packages/compiler/src/core/schema-validator.ts

@@ -4,14 +4,15 @@ import { Diagnostic, JSONSchemaType, JSONSchemaValidator, NoTarget, SourceFile }
 
 export interface JSONSchemaValidatorOptions {
  coerceTypes?: boolean;
+ strict?: boolean;
 }
 
 export function createJSONSchemaValidator<T>(
  schema: JSONSchemaType<T>,
- options: JSONSchemaValidatorOptions = {}
+ options: JSONSchemaValidatorOptions = { strict: true }
 ): JSONSchemaValidator {
  const ajv = new (Ajv as any)({
- strict: true,
+ strict: options.strict,
  coerceTypes: options.coerceTypes,
  });
 

packages/compiler/src/init/init-template.ts

@@ -5,6 +5,7 @@ import { TypeSpecRawConfig } from "../config/types.js";
 export interface InitTemplateFile {
  path: string;
  destination: string;
+ skipGeneration: boolean;
 }
 
 export interface InitTemplateInput {
@@ -24,6 +25,9 @@ export interface InitTemplate {
  */
  description: string;
 
+ /** Minimum Compiler Support Version */
+ compilerVersion: string;
+
  /**
  * List of libraries to include
  */
@@ -57,6 +61,7 @@ export const InitTemplateSchema: JSONSchemaType<InitTemplate> = {
  properties: {
  title: { type: "string" },
  description: { type: "string" },
+ compilerVersion: { type: "string" },
  libraries: { type: "array", items: { type: "string" } },
  skipCompilerPackage: { type: "boolean", nullable: true },
  config: { nullable: true, ...TypeSpecConfigJsonSchema },
@@ -82,16 +87,11 @@ export const InitTemplateSchema: JSONSchemaType<InitTemplate> = {
  properties: {
  path: { type: "string" },
  destination: { type: "string" },
+ skipGeneration: { type: "boolean" },
  },
  required: ["path", "destination"],
  },
  },
  },
- required: ["title", "description"],
-};
-
-export const InitTemplateDefinitionsSchema: JSONSchemaType<Record<string, InitTemplate>> = {
- type: "object",
- additionalProperties: InitTemplateSchema,
- required: [],
+ required: ["title", "description", "compilerVersion"],
 };

packages/compiler/src/init/init.ts

@@ -2,6 +2,7 @@ import { readdir } from "fs/promises";
 import jsyaml from "js-yaml";
 import Mustache from "mustache";
 import prompts from "prompts";
+import * as semver from "semver";
 import { TypeSpecConfigFilename } from "../config/config-loader.js";
 import { formatTypeSpec } from "../core/formatter.js";
 import { createDiagnostic } from "../core/messages.js";
@@ -10,7 +11,8 @@ import { getBaseFileName, getDirectoryPath, joinPaths } from "../core/path-utils
 import { createJSONSchemaValidator } from "../core/schema-validator.js";
 import { CompilerHost, Diagnostic, NoTarget, SourceFile } from "../core/types.js";
 import { readUrlOrPath, resolveRelativeUrlOrPath } from "../core/util.js";
-import { InitTemplate, InitTemplateDefinitionsSchema, InitTemplateFile } from "./init-template.js";
+import { MANIFEST } from "../manifest.js";
+import { InitTemplate, InitTemplateFile, InitTemplateSchema } from "./init-template.js";
 
 interface ScaffoldingConfig extends InitTemplate {
  /**
@@ -70,6 +72,8 @@ interface TemplatesUrl {
  url: string;
  /** The final URL after HTTP redirects. Populated when template is downloaded. */
  finalUrl?: string;
+ /** The actual template file. Populated when template is downloaded. */
+ file?: SourceFile;
 }
 
 const normalizeVersion = function () {
@@ -98,11 +102,25 @@ export async function initTypeSpecProject(
  if (!(await confirmDirectoryEmpty(directory))) {
  return;
  }
- const folderName = getBaseFileName(directory);
 
+ const folderName = getBaseFileName(directory);
  const url: TemplatesUrl | undefined = templatesUrl ? { url: templatesUrl } : undefined;
- const template = await selectTemplate(host, url);
 
+ // Download template configuration and prompt user to select a template
+ // No validation is done until one has been selected
+ const templates = url === undefined ? builtInTemplates : await downloadTemplates(host, url);
+ const templateName = await promptTemplateSelection(templates, url);
+
+ // Validate minimum compiler version for non built-in templates
+ if (url !== undefined && !(await validateTemplate(templates[templateName], url))) {
+ return;
+ }
+
+ const template = templates[templateName] as InitTemplate;
+ if (template.description) {
+ // eslint-disable-next-line no-console
+ console.log(template.description);
+ }
  const { name } = await prompts([
  {
  type: "text",
@@ -128,6 +146,9 @@ export async function initTypeSpecProject(
  normalizePackageName,
  };
  await scaffoldNewProject(host, scaffoldingConfig);
+
+ // eslint-disable-next-line no-console
+ console.log("Project created successfully.");
 }
 
 async function promptCustomParameters(template: InitTemplate): Promise<Record<string, any>> {
@@ -170,10 +191,12 @@ const builtInTemplates: Record<string, InitTemplate> = {
  title: "Empty project",
  description: "Create an empty project.",
  libraries: [],
+ compilerVersion: MANIFEST.version,
  },
  rest: {
  title: "Generic Rest API",
  description: "Create a project representing a generic Rest API",
+ compilerVersion: MANIFEST.version,
  libraries: ["@typespec/rest", "@typespec/openapi3"],
  config: {
  emit: ["@typespec/openapi3"],
@@ -194,11 +217,12 @@ async function confirm(message: string): Promise<boolean> {
 async function downloadTemplates(
  host: CompilerHost,
  templatesUrl: TemplatesUrl
-): Promise<Record<string, InitTemplate>> {
+): Promise<Record<string, unknown>> {
  let file: SourceFile;
  try {
  file = await readUrlOrPath(host, templatesUrl.url);
  templatesUrl.finalUrl = file.path;
+ templatesUrl.file = file;
  } catch (e: any) {
  throw new InitTemplateError([
  createDiagnostic({
@@ -222,35 +246,82 @@ async function downloadTemplates(
  ]);
  }
 
- validateTemplateDefinitions(json, file);
- return json;
-}
-
-async function selectTemplate(
- host: CompilerHost,
- templatesUrl: TemplatesUrl | undefined
-): Promise<InitTemplate> {
- const templates =
- templatesUrl === undefined ? builtInTemplates : await downloadTemplates(host, templatesUrl);
- return promptTemplateSelection(templates);
+ return json as Record<string, unknown>;
 }
 
 async function promptTemplateSelection(
- templates: Record<string, InitTemplate>
-): Promise<InitTemplate> {
+ templates: Record<string, any>,
+ templatesUrl: TemplatesUrl | undefined
+): Promise<string> {
  const { templateName } = await prompts({
  type: "select",
  name: "templateName",
  message: "Please select a template",
  choices: Object.entries(templates).map(([id, template]) => {
- return { value: id, description: template.description, title: template.title };
+ return {
+ value: id,
+ description: template.description,
+ title:
+ template.title +
+ `\tmin compiler ver: ${
+ template.compilerVersion ? template.compilerVersion : "-not specified-"
+ }`,
+ };
  }),
  });
+
  const template = templates[templateName];
  if (!template) {
  throw new Error(`Unexpected error: Cannot find template ${templateName}`);
  }
- return template;
+
+ return templateName;
+}
+
+type ValidationResult = {
+ valid: boolean;
+ diagnostics: readonly Diagnostic[];
+};
+
+async function validateTemplate(template: any, templatesUrl: TemplatesUrl): Promise<boolean> {
+ // After selection, validate the template definition
+ const currentCompilerVersion = MANIFEST.version;
+ const validationTarget = templatesUrl.file as SourceFile;
+ let validationResult: ValidationResult;
+ // 1. If current version > compilerVersion, proceed with strict validation
+ if (template.compilerVersion && semver.gt(currentCompilerVersion, template.compilerVersion)) {
+ validationResult = validateTemplateDefinitions(template, validationTarget, true);
+
+ // 1.1 If strict validation fails, try relaxed validation
+ if (!validationResult.valid) {
+ validationResult = validateTemplateDefinitions(template, validationTarget, false);
+ }
+ } else {
+ // 2. if version mis-match or none specified, warn and prompt user to continue or not
+ const confirmationMessage = template.compilerVersion
+ ? `The template you selected is designed for tsp version ${template.compilerVersion}. You are currently using tsp version ${currentCompilerVersion}.`
+ : `The template you selected did not specify minimum support compiler version. You are currently using tsp version ${currentCompilerVersion}.`;
+ if (
+ await confirm(
+ `${confirmationMessage} The project created may not be correct. Do you want to continue?`
+ )
+ ) {
+ // 2.1 If user choose to continue, proceed with relaxed validation
+ validationResult = validateTemplateDefinitions(template, validationTarget, false);
+ } else {
+ return false;
+ }
+ }
+
+ // 3. If even relaxed validation fails, still prompt user to continue or not
+ if (!validationResult.valid) {
+ logDiagnostics(validationResult.diagnostics);
+
+ return await confirm(
+ "Template schema failed. The project created may not be correct. Do you want to continue?"
+ );
+ }
+ return true;
 }
 
 async function selectLibraries(template: InitTemplate): Promise<string[]> {
@@ -289,6 +360,9 @@ export async function scaffoldNewProject(host: CompilerHost, config: Scaffolding
 }
 
 async function writePackageJson(host: CompilerHost, config: ScaffoldingConfig) {
+ if (isFileSkipGeneration("package.json", config.files ?? [])) {
+ return;
+ }
  const dependencies: Record<string, string> = {};
 
  if (!config.skipCompilerPackage) {
@@ -314,6 +388,9 @@ async function writePackageJson(host: CompilerHost, config: ScaffoldingConfig) {
 }
 
 async function writeConfig(host: CompilerHost, config: ScaffoldingConfig) {
+ if (isFileSkipGeneration(TypeSpecConfigFilename, config.files ?? [])) {
+ return;
+ }
  if (!config.config) {
  return;
  }
@@ -322,6 +399,9 @@ async function writeConfig(host: CompilerHost, config: ScaffoldingConfig) {
 }
 
 async function writeMain(host: CompilerHost, config: ScaffoldingConfig) {
+ if (isFileSkipGeneration("main.tsp", config.files ?? [])) {
+ return;
+ }
  const dependencies: Record<string, string> = {};
 
  for (const library of config.libraries) {
@@ -339,7 +419,9 @@ async function writeFiles(host: CompilerHost, config: ScaffoldingConfig) {
  return;
  }
  for (const file of config.files) {
- await writeFile(host, config, file);
+ if (file.skipGeneration !== true) {
+ await writeFile(host, config, file);
+ }
  }
 }
 
@@ -365,12 +447,29 @@ export class InitTemplateError extends Error {
 }
 
 function validateTemplateDefinitions(
- templates: unknown,
- file: SourceFile
-): asserts templates is Record<string, InitTemplate> {
- const validator = createJSONSchemaValidator(InitTemplateDefinitionsSchema);
- const diagnostics = validator.validate(templates, file);
- if (diagnostics.length > 0) {
- throw new InitTemplateError(diagnostics);
+ template: unknown,
+ templateName: SourceFile,
+ strictValidation: boolean
+): ValidationResult {
+ const validator = createJSONSchemaValidator(InitTemplateSchema, {
+ strict: strictValidation,
+ });
+ const diagnostics = validator.validate(template, templateName);
+ return { valid: diagnostics.length === 0, diagnostics };
+}
+
+function isFileSkipGeneration(fileName: string, files: InitTemplateFile[]): boolean {
+ for (const file of files) {
+ if (file.path === fileName) {
+ return file.skipGeneration;
+ }
  }
+ return false;
+}
+
+function logDiagnostics(diagnostics: readonly Diagnostic[]): void {
+ diagnostics.forEach((diagnostic) => {
+ // eslint-disable-next-line no-console
+ console.log(diagnostic.message);
+ });
 }

packages/compiler/test/init/main.tsp

@@ -0,0 +1,3 @@
+namespace MyTypeSpecLibrary {
+ model Test {}
+}