feat: metadata autocompletion

Author: Nemikolh

extensions/vscode/build.mjs

@@ -1,37 +1,60 @@
+import { chapterSchema, lessonSchema, partSchema, tutorialSchema } from '@tutorialkit/types';
+import { watch } from 'chokidar';
 import * as esbuild from 'esbuild';
-import fs from 'node:fs';
 import { execa } from 'execa';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { zodToJsonSchema } from 'zod-to-json-schema';
 
+const require = createRequire(import.meta.url);
 const production = process.argv.includes('--production');
-const watch = process.argv.includes('--watch');
+const isWatch = process.argv.includes('--watch');
 
 async function main() {
   const ctx = await esbuild.context({
-    entryPoints: ['src/extension.ts'],
+    entryPoints: {
+      extension: 'src/extension.ts',
+      server: './src/language-server/index.ts',
+    },
     bundle: true,
     format: 'cjs',
     minify: production,
     sourcemap: !production,
     sourcesContent: false,
+    tsconfig: './tsconfig.json',
     platform: 'node',
-    outfile: 'dist/extension.js',
+    outdir: 'dist',
+    define: { 'process.env.NODE_ENV': production ? '"production"' : '"development"' },
     external: ['vscode'],
-    logLevel: 'silent',
-    plugins: [
-      /* add to the end of plugins array */
-      esbuildProblemMatcherPlugin,
-    ],
+    plugins: [esbuildUMD2ESMPlugin],
   });
 
-  if (watch) {
+  if (isWatch) {
+    const buildMetadataSchemaDebounced = debounce(buildMetadataSchema);
+
+    watch(join(require.resolve('@tutorialkit/types'), 'dist'), {
+      followSymlinks: false,
+    }).on('all', (eventName, path) => {
+      if (eventName !== 'change' && eventName !== 'add' && eventName !== 'unlink') {
+        return;
+      }
+
+      buildMetadataSchemaDebounced();
+    });
+
     await Promise.all([
       ctx.watch(),
-      execa('tsc', ['--noEmit', '--watch', '--project', 'tsconfig.json'], { stdio: 'inherit', preferLocal: true }),
+      execa('tsc', ['--noEmit', '--watch', '--preserveWatchOutput', '--project', 'tsconfig.json'], {
+        stdio: 'inherit',
+        preferLocal: true,
+      }),
     ]);
   } else {
     await ctx.rebuild();
     await ctx.dispose();
 
+    buildMetadataSchema();
+
     if (production) {
       // rename name in package json to match extension name on store:
       const pkgJSON = JSON.parse(fs.readFileSync('./package.json', { encoding: 'utf8' }));
@@ -43,21 +66,24 @@ async function main() {
   }
 }
 
+function buildMetadataSchema() {
+  const schema = tutorialSchema.strict().or(partSchema.strict()).or(chapterSchema.strict()).or(lessonSchema.strict());
+
+  fs.mkdirSync('./dist', { recursive: true });
+  fs.writeFileSync('./dist/schema.json', JSON.stringify(zodToJsonSchema(schema), undefined, 2), 'utf-8');
+}
+
 /**
  * @type {import('esbuild').Plugin}
  */
-const esbuildProblemMatcherPlugin = {
-  name: 'esbuild-problem-matcher',
+const esbuildUMD2ESMPlugin = {
+  name: 'umd2esm',
   setup(build) {
-    build.onStart(() => {
-      console.log('[watch] build started');
-    });
-    build.onEnd((result) => {
-      result.errors.forEach(({ text, location }) => {
-        console.error(`✘ [ERROR] ${text}`);
-        console.error(`    ${location.file}:${location.line}:${location.column}:`);
-      });
-      console.log('[watch] build finished');
+    build.onResolve({ filter: /^(vscode-.*-languageservice|jsonc-parser)/ }, (args) => {
+      const pathUmdMay = require.resolve(args.path, { paths: [args.resolveDir] });
+      const pathEsm = pathUmdMay.replace('/umd/', '/esm/').replace('\\umd\\', '\\esm\\');
+
+      return { path: pathEsm };
     });
   },
 };
@@ -66,3 +92,20 @@ main().catch((error) => {
   console.error(error);
   process.exit(1);
 });
+
+/**
+ * Debounce the provided function.
+ *
+ * @param {Function} fn Function to debounce
+ * @param {number} duration Duration of the debounce
+ * @returns {Function} Debounced function
+ */
+function debounce(fn, duration) {
+  let timeoutId = 0;
+
+  return function () {
+    clearTimeout(timeoutId);
+
+    timeoutId = setTimeout(fn.bind(this), duration, ...arguments);
+  };
+}

extensions/vscode/package.json

@@ -102,7 +102,21 @@
           "when": "view == tutorialkit-lessons-tree && viewItem == part"
         }
       ]
-    }
+    },
+    "languages": [
+      {
+        "id": "markdown",
+        "extensions": [
+          ".md"
+        ]
+      },
+      {
+        "id": "mdx",
+        "extensions": [
+          ".mdx"
+        ]
+      }
+    ]
   },
   "scripts": {
     "__esbuild-base": "esbuild ./src/extension.ts --bundle --outfile=dist/extension.js --external:vscode --format=cjs --platform=node",
@@ -116,15 +130,25 @@
     "package": "pnpm run check-types && node build.mjs --production"
   },
   "dependencies": {
+    "@volar/language-core": "2.3.4",
+    "@volar/language-server": "2.3.4",
+    "@volar/language-service": "2.3.4",
+    "@volar/vscode": "2.3.4",
     "case-anything": "^3.1.0",
-    "gray-matter": "^4.0.3"
+    "gray-matter": "^4.0.3",
+    "volar-service-yaml": "volar-2.3",
+    "vscode-languageclient": "^9.0.1",
+    "vscode-uri": "^3.0.8",
+    "yaml-language-server": "1.15.0"
   },
   "devDependencies": {
-    "@types/mocha": "^10.0.6",
+    "@tutorialkit/types": "workspace:*",
     "@types/node": "20.14.11",
     "@types/vscode": "^1.80.0",
+    "chokidar": "3.6.0",
     "esbuild": "^0.21.5",
     "execa": "^9.2.0",
-    "typescript": "^5.4.5"
+    "typescript": "^5.4.5",
+    "zod-to-json-schema": "3.23.1"
   }
 }

extensions/vscode/src/extension.ts

@@ -1,16 +1,49 @@
+import * as serverProtocol from '@volar/language-server/protocol';
+import { createLabsInfo } from '@volar/vscode';
 import * as vscode from 'vscode';
 import { useCommands } from './commands';
 import { useLessonTree } from './views/lessonsTree';
+import * as lsp from 'vscode-languageclient/node';
 
 export let extContext: vscode.ExtensionContext;
 
-export function activate(context: vscode.ExtensionContext) {
+let client: lsp.BaseLanguageClient;
+
+export async function activate(context: vscode.ExtensionContext) {
   extContext = context;
 
   useCommands();
   useLessonTree();
+
+  const serverModule = vscode.Uri.joinPath(context.extensionUri, 'dist', 'server.js');
+  const runOptions = { execArgv: <string[]>[] };
+  const debugOptions = { execArgv: ['--nolazy', '--inspect=' + 6009] };
+  const serverOptions: lsp.ServerOptions = {
+    run: {
+      module: serverModule.fsPath,
+      transport: lsp.TransportKind.ipc,
+      options: runOptions,
+    },
+    debug: {
+      module: serverModule.fsPath,
+      transport: lsp.TransportKind.ipc,
+      options: debugOptions,
+    },
+  };
+  const clientOptions: lsp.LanguageClientOptions = {
+    documentSelector: [{ language: 'markdown' }, { language: 'mdx' }],
+    initializationOptions: {},
+  };
+  client = new lsp.LanguageClient('tutorialkit-language-server', 'TutorialKit', serverOptions, clientOptions);
+
+  await client.start();
+
+  const labsInfo = createLabsInfo(serverProtocol);
+  labsInfo.addLanguageClient(client);
+
+  return labsInfo.extensionExports;
 }
 
 export function deactivate() {
-  // do nothing
+  return client?.stop();
 }

extensions/vscode/src/language-server/index.ts

@@ -0,0 +1,56 @@
+import { createConnection, createServer, createSimpleProject } from '@volar/language-server/node';
+import { create as createYamlService } from 'volar-service-yaml';
+import { SchemaPriority } from 'yaml-language-server';
+import { frontmatterPlugin } from './languagePlugin';
+import { readSchema } from './schema';
+
+const connection = createConnection();
+const server = createServer(connection);
+
+connection.listen();
+
+connection.onInitialize((params) => {
+  connection.console.debug('CONNECTED' + params.capabilities);
+
+  const yamlService = createYamlService({
+    getLanguageSettings(_context) {
+      const schema = readSchema();
+
+      return {
+        completion: true,
+        validate: true,
+        hover: true,
+        format: true,
+        yamlVersion: '1.2',
+        isKubernetes: false,
+        schemas: [
+          {
+            uri: 'https://tutorialkit.dev/schema.json',
+            schema,
+            fileMatch: [
+              '**/*',
+
+              // TODO: those don't work
+              'src/content/*.md',
+              'src/content/**/*.md',
+              'src/content/**/*.mdx',
+            ],
+            priority: SchemaPriority.Settings,
+          },
+        ],
+      };
+    },
+  });
+
+  delete yamlService.capabilities.codeLensProvider;
+
+  return server.initialize(
+    params,
+    createSimpleProject([frontmatterPlugin(connection.console.debug.bind(connection.console.debug))]),
+    [yamlService],
+  );
+});
+
+connection.onInitialized(server.initialized);
+
+connection.onShutdown(server.shutdown);

extensions/vscode/src/language-server/languagePlugin.ts

@@ -0,0 +1,100 @@
+import { CodeMapping, type LanguagePlugin, type VirtualCode } from '@volar/language-core';
+import type * as ts from 'typescript';
+import type { URI } from 'vscode-uri';
+
+export const frontmatterPlugin = (debug: (message: string) => void) =>
+  ({
+    getLanguageId(uri) {
+      debug('URI: ' + uri.path);
+
+      if (uri.path.endsWith('.md')) {
+        return 'markdown';
+      }
+
+      if (uri.path.endsWith('.mdx')) {
+        return 'mdx';
+      }
+
+      return undefined;
+    },
+    createVirtualCode(_uri, languageId, snapshot) {
+      if (languageId === 'markdown' || languageId === 'mdx') {
+        return new FrontMatterVirtualCode(snapshot);
+      }
+
+      return undefined;
+    },
+  }) satisfies LanguagePlugin<URI>;
+
+export class FrontMatterVirtualCode implements VirtualCode {
+  id = 'root';
+  languageId = 'markdown';
+  mappings: CodeMapping[];
+  embeddedCodes: VirtualCode[] = [];
+
+  constructor(public snapshot: ts.IScriptSnapshot) {
+    this.mappings = [
+      {
+        sourceOffsets: [0],
+        generatedOffsets: [0],
+        lengths: [snapshot.getLength()],
+        data: {
+          completion: true,
+          format: true,
+          navigation: true,
+          semantic: true,
+          structure: true,
+          verification: true,
+        },
+      },
+    ];
+
+    this.embeddedCodes = [...frontMatterCode(snapshot)];
+  }
+}
+
+function* frontMatterCode(snapshot: ts.IScriptSnapshot): Generator<VirtualCode> {
+  const content = snapshot.getText(0, snapshot.getLength());
+
+  let frontMatterStartIndex = content.indexOf('---');
+
+  if (frontMatterStartIndex === -1) {
+    return;
+  }
+
+  frontMatterStartIndex += 3;
+
+  let frontMatterEndIndex = content.indexOf('---', frontMatterStartIndex);
+
+  if (frontMatterEndIndex === -1) {
+    frontMatterEndIndex = snapshot.getLength();
+  }
+
+  const frontMatterText = content.substring(frontMatterStartIndex, frontMatterEndIndex);
+
+  yield {
+    id: 'frontmatter_1',
+    languageId: 'yaml',
+    snapshot: {
+      getText: (start, end) => frontMatterText.slice(start, end),
+      getLength: () => frontMatterText.length,
+      getChangeRange: () => undefined,
+    },
+    mappings: [
+      {
+        sourceOffsets: [frontMatterStartIndex],
+        generatedOffsets: [0],
+        lengths: [frontMatterText.length],
+        data: {
+          completion: true,
+          format: true,
+          navigation: true,
+          semantic: true,
+          structure: true,
+          verification: true,
+        },
+      },
+    ],
+    embeddedCodes: [],
+  };
+}