@specverse/engines 4.3.4 → 5.0.0

package/libs/instance-factories/tools/templates/vscode/vscode-extension-generator.ts

@@ -10,11 +10,28 @@
  */
 
 import type { TemplateContext } from '@specverse/types';
-import { readFileSync, existsSync, readdirSync, statSync, mkdirSync, writeFileSync, copyFileSync } from 'fs';
+import { readFileSync, existsSync, readdirSync, statSync, mkdirSync, writeFileSync, copyFileSync, unlinkSync } from 'fs';
 import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
 
 const __generatorDir = dirname(fileURLToPath(import.meta.url));
+const __require = createRequire(import.meta.url);
+
+/**
+ * Resolve the live composed SpecVerse JSON schema from @specverse/entities.
+ * The schema is composed at entities build-time from per-module fragments;
+ * copying it into the extension at realize time keeps jsonValidation in sync
+ * with the real language grammar (rather than shipping a frozen static copy).
+ */
+function resolveComposedSchemaPath(): string | null {
+  try {
+    const entitiesPkg = __require.resolve('@specverse/entities/package.json');
+    const schemaPath = join(dirname(entitiesPkg), 'schema', 'SPECVERSE-SCHEMA.json');
+    if (existsSync(schemaPath)) return schemaPath;
+  } catch {}
+  return null;
+}
 
 export default function generateVSCodeExtension(context: TemplateContext): string {
   const { spec, outputDir } = context;
@@ -25,17 +42,58 @@ export default function generateVSCodeExtension(context: TemplateContext): strin
   // 1. Check for distribution spec (new entity type)
   const distribution = extractDistribution(spec);
 
-  // 2. Extract CLI commands — from distribution, spec, or standard defaults
-  let cliCommands: Array<{ command: string; title: string; category: string }> = [];
+  // 2. Extract CLI commands — from distribution, spec, or standard defaults.
+  // Commands with subcommands in the spec (e.g. `realize`, `gen`, `dev`) are
+  // auto-expanded into their leaf form (`realize.all`, `gen.diagrams`, …) so
+  // they can be invoked independently; the parent name survives as a
+  // `submenu` marker for the context-menu generator below.
+  type CliCmd = { command: string; title: string; category: string; submenu?: string; submenuLabel?: string };
+  let cliCommands: CliCmd[] = [];
+  const submenuDefs: Array<{ id: string; label: string }> = [];
   if (distribution?.commands) {
-    cliCommands = distribution.commands.map((cmd: any) => {
+    const specCommandsByName = buildCLICommandMap(spec);
+    const standardByName = new Map(
+      getStandardCommands().map(c => [c.command, c])
+    );
+
+    cliCommands = distribution.commands.flatMap((cmd: any): CliCmd[] => {
       const parts = (cmd.from || cmd.command || '').split('.');
       const name = parts[parts.length - 1] || 'unknown';
-      return {
-        command: `specverse.${name}`,
-        title: cmd.title || `${capitalize(name)}: ${cmd.description || ''}`,
+
+      // If the referenced spec command has subcommands, expand into leaves
+      // and declare a submenu so the right-click shows `<Parent> ▶ <child>`.
+      const specNode = findSpecCommand(spec, cmd.from || name);
+      const subs = specNode?.subcommands as Record<string, any> | undefined;
+      if (subs && Object.keys(subs).length > 0) {
+        const submenuId = `specverse.${name}`;
+        const submenuLabel = cmd.title || specNode?.description || capitalize(name);
+        submenuDefs.push({ id: submenuId, label: capitalize(name) });
+        return Object.entries(subs).map(([childName, childDef]: [string, any]) => ({
+          command: `specverse.${name}.${childName}`,
+          title: `${capitalize(name)} ${capitalize(childName)}`,
+          category: 'SpecVerse',
+          submenu: submenuId,
+          submenuLabel,
+        }));
+      }
+
+      // Leaf command.
+      const commandId = `specverse.${name}`;
+      let title = cmd.title;
+      if (!title && cmd.from) {
+        const specCmd = specCommandsByName.get(cmd.from);
+        if (specCmd?.description) title = specCmd.description;
+      }
+      if (!title) {
+        const std = standardByName.get(commandId);
+        if (std) title = std.title;
+      }
+      if (!title) title = capitalize(name);
+      return [{
+        command: commandId,
+        title,
         category: 'SpecVerse',
-      };
+      }];
     });
   }
   if (cliCommands.length === 0) {
@@ -73,6 +131,75 @@ export default function generateVSCodeExtension(context: TemplateContext): strin
           scopeName: lang.grammar,
           path: `./syntaxes/${lang.id}.tmLanguage.json`,
         }));
+      // Activation: leave activationEvents empty — modern VSCode (1.74+)
+      // auto-generates activation from `contributes.languages`, and an explicit
+      // entry triggers the extension-editing linter's "can be removed" hint.
+      packageJson.activationEvents = [];
+      const fileMatch = distribution.languages
+        .flatMap((lang: any) => (lang.extensions || []).map((ext: string) => `*${ext}`));
+      if (fileMatch.length > 0) {
+        packageJson.contributes.jsonValidation = [{
+          fileMatch,
+          url: './schemas/specverse-schema.json',
+        }];
+      }
+
+      // Right-click menus. Leaf commands become direct entries; commands
+      // with children collapse into a submenu keyed by the parent id
+      // (declared in `contributes.submenus`). The gating uses
+      // `resourceExtname` for the sidebar's explorer/context and
+      // `editorLangId` for the file's editor/context.
+      const extnames = distribution.languages
+        .flatMap((lang: any) => lang.extensions || []) as string[];
+      const langIds = distribution.languages.map((lang: any) => lang.id) as string[];
+      const explorerWhen = extnames.map(e => `resourceExtname == ${e}`).join(' || ');
+      const editorWhen = langIds.map(id => `editorLangId == ${id}`).join(' || ');
+
+      // Ordered top-level entries: walk distribution.commands in spec order,
+      // emit a submenu ref for expanded parents and a command ref for leaves.
+      const seenSubmenus = new Set<string>();
+      type TopEntry = { submenu?: string; command?: string };
+      const topEntries: TopEntry[] = [];
+      for (const c of cliCommands) {
+        if (c.submenu) {
+          if (!seenSubmenus.has(c.submenu)) {
+            seenSubmenus.add(c.submenu);
+            topEntries.push({ submenu: c.submenu });
+          }
+        } else {
+          topEntries.push({ command: c.command });
+        }
+      }
+
+      if (topEntries.length > 0 && (explorerWhen || editorWhen)) {
+        const explorerMenu = topEntries.map((e, i) => ({
+          ...(e.submenu ? { submenu: e.submenu } : { command: e.command }),
+          when: explorerWhen,
+          group: `specverse@${i + 1}`,
+        }));
+        const editorMenu = topEntries.map((e, i) => ({
+          ...(e.submenu ? { submenu: e.submenu } : { command: e.command }),
+          when: editorWhen,
+          group: `specverse@${i + 1}`,
+        }));
+        const menus: Record<string, any[]> = {
+          'explorer/context': explorerMenu,
+          'editor/context': editorMenu,
+        };
+        // Children under each submenu id.
+        for (const sub of submenuDefs) {
+          menus[sub.id] = cliCommands
+            .filter(c => c.submenu === sub.id)
+            .map(c => ({ command: c.command }));
+        }
+        packageJson.contributes.menus = menus;
+        if (submenuDefs.length > 0) {
+          packageJson.contributes.submenus = submenuDefs.map(s => ({
+            id: s.id,
+            label: s.label,
+          }));
+        }
+      }
     }
 
     // Themes from distribution
@@ -95,6 +222,38 @@ export default function generateVSCodeExtension(context: TemplateContext): strin
     copyRecursive(staticDir, extensionDir);
   }
 
+  // 4a. Drop in the live composed SpecVerse JSON schema as ./schemas/specverse-schema.json
+  // (overrides any static copy so the extension's validation stays in sync
+  // with the real language schema rather than a frozen hand-maintained copy).
+  const schemaSrc = resolveComposedSchemaPath();
+  if (schemaSrc) {
+    const schemasDir = join(extensionDir, 'schemas');
+    if (!existsSync(schemasDir)) mkdirSync(schemasDir, { recursive: true });
+    copyFileSync(schemaSrc, join(schemasDir, 'specverse-schema.json'));
+  }
+
+  // 4b. Rename the copied grammar file to match the distribution's language id.
+  // Static asset is named generically (e.g. `specverse.tmLanguage.json`); the
+  // extension's grammar contribution points to `./syntaxes/<lang.id>.tmLanguage.json`,
+  // so the file on disk must match the id declared in the distribution.
+  if (distribution?.languages && distribution.languages.length > 0) {
+    const syntaxesDir = join(extensionDir, 'syntaxes');
+    if (existsSync(syntaxesDir)) {
+      const langId = distribution.languages[0].id;
+      const targetName = `${langId}.tmLanguage.json`;
+      const targetPath = join(syntaxesDir, targetName);
+      if (!existsSync(targetPath)) {
+        const existing = readdirSync(syntaxesDir).find(
+          f => f.endsWith('.tmLanguage.json') && f !== targetName,
+        );
+        if (existing) {
+          copyFileSync(join(syntaxesDir, existing), targetPath);
+          unlinkSync(join(syntaxesDir, existing));
+        }
+      }
+    }
+  }
+
   // 5. Create src directory and copy extension.ts
   const srcDir = join(extensionDir, 'src');
   if (!existsSync(srcDir)) mkdirSync(srcDir, { recursive: true });
@@ -152,6 +311,83 @@ function extractDistribution(spec: any): any | null {
   return allDistributions.length > 0 ? allDistributions[0] : null;
 }
 
+/**
+ * Build a map of spec-defined CLI commands keyed by their dotted path.
+ *
+ * Handles the spec shape:
+ *   components.CLI.commands.specverse.subcommands.validate.description
+ *
+ * Keys produced: "CLI.validate", "CLI.validate" (from rootCommand),
+ *   "specverse.validate", "validate".
+ *
+ * This lets distribution `from:` refs resolve regardless of which key
+ * flavour the author uses.
+ */
+/**
+ * Look up a spec command by dotted ref (e.g. "CLI.realize" or "realize").
+ * Returns the raw spec node — `{ description, subcommands?, ... }` — or null.
+ * Used to detect whether a distribution command has subcommands to expand.
+ */
+function findSpecCommand(spec: any, ref: string): any | null {
+  if (!ref) return null;
+  const parts = ref.split('.');
+  const target = parts[parts.length - 1];
+  const components = spec?.components || {};
+  const componentList = Array.isArray(components)
+    ? components
+    : Object.entries(components).map(([name, data]) => ({ name, ...(data as any) }));
+  for (const comp of componentList) {
+    const cliCommands = (comp as any)?.commands;
+    if (!cliCommands) continue;
+    for (const [, rootDef] of Object.entries(cliCommands as Record<string, any>)) {
+      const subcommands = (rootDef as any)?.subcommands || {};
+      if (subcommands[target]) return subcommands[target];
+    }
+  }
+  return null;
+}
+
+function buildCLICommandMap(spec: any): Map<string, { description?: string; title?: string }> {
+  const map = new Map<string, { description?: string; title?: string }>();
+  const components = spec?.components || {};
+  const componentList = Array.isArray(components)
+    ? components
+    : Object.entries(components).map(([name, data]) => ({ name, ...(data as any) }));
+
+  for (const comp of componentList) {
+    const compName = (comp as any).name || '';
+    const cliCommands = (comp as any)?.commands;
+    if (!cliCommands) continue;
+
+    for (const [rootName, rootDef] of Object.entries(cliCommands as Record<string, any>)) {
+      const subcommands = (rootDef as any)?.subcommands || {};
+      for (const [subName, subDef] of Object.entries(subcommands as Record<string, any>)) {
+        const sub = subDef as any;
+        const entry = { description: sub.description, title: sub.title };
+        // Register under a few keys so `from: CLI.validate` or `from: specverse.validate` both work
+        if (compName) map.set(`${compName}.${subName}`, entry);
+        map.set(`${rootName}.${subName}`, entry);
+        if (!map.has(subName)) map.set(subName, entry);
+
+        const nestedSubs = sub?.subcommands;
+        if (nestedSubs) {
+          for (const [nestedName, nestedDef] of Object.entries(nestedSubs as Record<string, any>)) {
+            const nestedEntry = {
+              description: (nestedDef as any).description,
+              title: (nestedDef as any).title,
+            };
+            const qualified = `${subName}.${nestedName}`;
+            if (compName) map.set(`${compName}.${qualified}`, nestedEntry);
+            map.set(`${rootName}.${qualified}`, nestedEntry);
+            if (!map.has(qualified)) map.set(qualified, nestedEntry);
+          }
+        }
+      }
+    }
+  }
+  return map;
+}
+
 function extractCLICommands(spec: any): Array<{ command: string; title: string; category: string }> {
   const commands: Array<{ command: string; title: string; category: string }> = [];
 
@@ -221,7 +457,7 @@ function generatePackageJson(
     publisher: 'specverse',
     engines: { vscode: '^1.80.0' },
     categories: ['Programming Languages', 'Linters', 'Snippets'],
-    activationEvents: ['onLanguage:specverse'],
+    activationEvents: [],
     main: './dist/extension.js',
     contributes: {
       languages: [{
@@ -237,7 +473,7 @@ function generatePackageJson(
       }],
       jsonValidation: [{
         fileMatch: ['*.specly', '*.specverse'],
-        url: './schemas/specverse-v3-schema.json',
+        url: './schemas/specverse-schema.json',
       }],
       themes: [
         { label: 'SpecVerse Dark', uiTheme: 'vs-dark', path: './themes/specverse-complete-theme.json' },

package/libs/instance-factories/tools/vscode.yaml

@@ -9,7 +9,7 @@ metadata:
   tags: [vscode, ide, extension, language-support]
 
 compatibility:
-  specverse: "^4.0.0"
+  specverse: ">=4.0.0"
   node: ">=18.0.0"
 
 capabilities:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specverse/engines",
-  "version": "4.3.4",
+  "version": "5.0.0",
   "description": "SpecVerse toolchain — parser, inference, realize, generators, AI, registry",
   "type": "module",
   "main": "dist/index.js",
@@ -42,12 +42,13 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@specverse/types": "^4.1.0",
-    "@specverse/entities": "^4.1.0",
-    "@specverse/runtime": "^4.1.23",
+    "@specverse/entities": "^5.0.0",
+    "@specverse/runtime": "^5.0.0",
+    "@specverse/types": "^5.0.0",
     "ajv": "^8.17.0",
     "ajv-formats": "^2.1.0",
     "glob": "^10.0.0",
+    "handlebars": "^4.7.9",
     "js-yaml": "^4.1.0",
     "semver": "^7.0.0",
     "yaml": "^2.8.1"