Merge pull request #76 from retejs/feature/virtual-templates

feat(app): support extra templates via features object

Author: Ni55aN

.npmignore

@@ -37,3 +37,4 @@ release.config.js
 release.config.js
 release.config.js
 release.config.js
+tmp

assets/app/entry_ts

@@ -4,6 +4,7 @@ import { createEditor as createPerfEditor } from './perf'
 import { createEditor as createCustomEditor } from './customization'
 import { createEditor as create3DEditor } from './3d'
 import { createEditor as createScopesEditor } from './scopes'
+/* {{virtual-imports}} */
 import { isHeadless } from '../headless'
 
 const factory = {
@@ -12,6 +13,7 @@ const factory = {
   'customization': createCustomEditor,
   '3d': create3DEditor,
   'scopes': createScopesEditor
+  /* {{virtual-factory}} */
 }
 
 const query = typeof location !== 'undefined' && new URLSearchParams(location.search)

src/app/features.ts

@@ -1,3 +1,4 @@
+import { throwError } from '../shared/throw'
 import { AppStack } from '.'
 import { AngularVersion } from './stack/angular'
 import { SvelteVersion } from './stack/svelte'
@@ -245,6 +246,114 @@ export function validateFeatures(features: Feature[], options: { stack: AppStack
   }
 }
 
+export function findFeature(name: string, pool: Feature[]) {
+  return pool.find(f => f.name.toLocaleLowerCase() === name.toLocaleLowerCase())
+}
+
+export function resolveFeatures(names: string[], pool: Feature[]) {
+  return names.map(name => {
+    const feature = findFeature(name, pool)
+
+    if (!feature) throwError(`feature ${name} not found`)
+
+    return feature
+  })
+}
+
+export function featureKeys(features: Feature[]) {
+  return features.map(({ templateKeys }) => templateKeys ?? []).flat()
+}
+
 export function getDependencies(features: Feature[]) {
-  return features.map(feature => feature.requiredDependencies || []).flat()
+  const unique = features.filter((feature, index, list) => {
+    return list.findIndex(item => item.name === feature.name) === index
+  })
+
+  return unique.map(feature => feature.requiredDependencies ?? []).flat()
+}
+
+/** `string[]` — shared features. Object — one base `string[]` + optional extras `{ from, features }`. */
+export type FeaturesInput = string[] | Record<string, string[] | { from: string, features: string[] }>
+
+export type TemplateJob = {
+  name: string
+  from: string
+  features: Feature[]
+}
+
+function parseFeaturesObject(
+  features: Exclude<FeaturesInput, string[]>,
+  sources: string[]
+) {
+  let base: string[] | null = null
+  const extras: { name: string, from: string, features: string[] }[] = []
+
+  for (const [name, value] of Object.entries(features)) {
+    if (Array.isArray(value)) {
+      if (base) throwError('features object can contain only one base features array')
+      base = value
+    } else {
+      if (sources.includes(name)) throwError(`template "${name}" already exists`)
+      if (!sources.includes(value.from)) throwError(`template "${name}" from unknown "${value.from}"`)
+      extras.push({ name, from: value.from, features: value.features })
+    }
+  }
+
+  if (!base) throwError('features object must contain a base features array')
+
+  return { base, extras }
+}
+
+function resolveValidated(
+  names: string[],
+  optionalFeatures: Feature[],
+  stack: AppStack,
+  label?: string
+) {
+  const resolved = resolveFeatures(names, optionalFeatures)
+  const { issue } = validateFeatures(resolved, { stack })
+
+  if (issue) {
+    throwError(label
+      ? `template "${label}": ${issue}`
+      : issue)
+  }
+
+  return resolved
+}
+
+/** Build template jobs with resolved features. */
+export function resolveJobs(
+  sources: string[],
+  optionalFeatures: Feature[],
+  stack: AppStack,
+  input: { features: FeaturesInput } | { selected: Feature[] }
+): TemplateJob[] {
+  if ('selected' in input) {
+    const { issue } = validateFeatures(input.selected, { stack })
+
+    if (issue) throwError(issue)
+
+    return sources.map(name => ({ name, from: name, features: input.selected }))
+  }
+
+  const { features } = input
+
+  if (Array.isArray(features)) {
+    const resolved = resolveValidated(features, optionalFeatures, stack)
+
+    return sources.map(name => ({ name, from: name, features: resolved }))
+  }
+
+  const { base, extras } = parseFeaturesObject(features, sources)
+  const shared = resolveValidated(base, optionalFeatures, stack)
+
+  return [
+    ...sources.map(name => ({ name, from: name, features: shared })),
+    ...extras.map(extra => ({
+      name: extra.name,
+      from: extra.from,
+      features: resolveValidated(extra.features, optionalFeatures, stack, extra.name)
+    }))
+  ]
 }

src/app/index.ts

@@ -29,12 +29,13 @@ export const builders = {
 export type AppStack = keyof typeof builders
 export const appStacks = Object.keys(builders) as AppStack[]
 export { Features }
+export type { FeaturesInput } from './features'
 
 type Options = {
   name?: string
   stack?: AppStack
   version?: number
-  features?: string[]
+  features?: Features.FeaturesInput
   depsAlias?: string
   depsLabel?: string
   next?: boolean
@@ -93,47 +94,48 @@ export async function createApp({ name, stack, version, features, depsAlias, for
   ]
   const mandatoryFeatures = featuresList.filter(feature => feature.mandatory)
   const optionalFeatures = featuresList.filter(feature => !feature.mandatory)
-  const selectedFeatures = features?.length
-    ? features.map(featureName => {
-      const feature = optionalFeatures.find(f => f.name.toLocaleLowerCase() === featureName.toLocaleLowerCase())
-
-      if (!feature) throw throwError(`feature ${featureName} not found`)
-
-      return feature
-    })
-    : await select('Select features', optionalFeatures.map(feature => ({
-      name: feature.name,
-      value: feature
-    })), true)
-
-  const { issue } = Features.validateFeatures(selectedFeatures, { stack: selectedStack })
-
-  if (issue) throwError(issue)
+  const sources = await TemplateBuilder.getTemplates()
+  const jobs = Features.resolveJobs(
+    sources,
+    optionalFeatures,
+    selectedStack,
+    features
+      ? { features }
+      : {
+        selected: await select('Select features', optionalFeatures.map(feature => ({
+          name: feature.name,
+          value: feature
+        })), true)
+      }
+  )
 
   const { exists } = await Patch.ensure(appName, selectedStack, selectedVersion)
 
   if (!exists) await builder.create(appName, selectedVersion)
   await Patch.commit(appName, selectedStack, selectedVersion)
 
-  const activeFeatures = [...mandatoryFeatures, ...selectedFeatures]
-  const activeFeaturesKeys = activeFeatures.map(({ templateKeys }) => templateKeys || []).flat()
-  const templateBuilder = new TemplateBuilder<DefaultTemplateKey>(activeFeaturesKeys)
+  const activeFeatures = [...mandatoryFeatures, ...jobs.flatMap(job => job.features)]
+  const templateBuilder = new TemplateBuilder<DefaultTemplateKey>(Features.featureKeys(activeFeatures))
+  const extras = jobs.filter(job => job.name !== job.from).map(job => job.name)
 
   await builder.putAssets(appName, selectedVersion, templateBuilder)
 
-  for (const templateName of await templateBuilder.getTemplates()) {
-    const template = await templateBuilder.load(templateName)
+  for (const job of jobs) {
+    const currentBuilder = new TemplateBuilder<DefaultTemplateKey>(Features.featureKeys([
+      ...mandatoryFeatures,
+      ...job.features
+    ]))
 
     try {
-      const code = await templateBuilder.build(template)
+      const code = await currentBuilder.build(await currentBuilder.load(job.from))
 
-      await builder.putScript(appName, `${templateName}.ts`, code, selectedVersion)
+      await builder.putScript(appName, `${job.name}.ts`, code, selectedVersion)
     } catch (e) {
       console.error(e)
-      throwError(`failed to build template "${templateName}"`)
+      throwError(`failed to build template "${job.name}"`)
     }
   }
-  await builder.putScript(appName, `index.ts`, await templateBuilder.getEntryScript(), selectedVersion)
+  await builder.putScript(appName, `index.ts`, await templateBuilder.getEntryScript(extras), selectedVersion)
 
   await install(appName, Features.getDependencies(activeFeatures), depsAlias, forceInstall)
 }

src/app/template-builder.ts

@@ -1,4 +1,5 @@
 /* eslint-disable @typescript-eslint/naming-convention */
+import Case from 'case'
 import fs from 'fs'
 import { join } from 'path'
 import prettier from 'prettier'
@@ -15,6 +16,10 @@ export type DefaultTemplateKey = 'zoom-at' | 'react-render' | `react${number}` |
   | 'dataflow' | 'arrange' | 'sizes' | 'readonly' | 'order-nodes' | 'selectable'
   | 'context-menu' | 'import-area-extensions' | 'minimap' | 'reroute' | `stack-${string}`
 
+function toCreateEditorName(id: string) {
+  return `create${Case.pascal(id)}Editor`
+}
+
 export class TemplateBuilder<Key extends string> {
   blockCommentRegex = /\/\* \[(!?[\w-]+)\][\r\n ]+(.*?)?[\r\n ]?\[\/\1\] \*\//gs
 
@@ -28,7 +33,7 @@ export class TemplateBuilder<Key extends string> {
     return this.normalizeLineEndings(await fs.promises.readFile(join(templatesPath, name), { encoding: 'utf-8' }))
   }
 
-  async getTemplates() {
+  static getTemplates() {
     return fs.promises.readdir(templatesPath)
   }
 
@@ -49,7 +54,17 @@ export class TemplateBuilder<Key extends string> {
       : code
   }
 
-  async getEntryScript() {
-    return fs.promises.readFile(entryScriptPath, { encoding: 'utf-8' })
+  async getEntryScript(templateIds: string[] = []) {
+    const template = this.normalizeLineEndings(await fs.promises.readFile(entryScriptPath, { encoding: 'utf-8' }))
+    const imports = templateIds
+      .map(id => `import { createEditor as ${toCreateEditorName(id)} } from './${id}'`)
+      .join('\n')
+    const factoryEntries = templateIds
+      .map(id => `  ,'${id}': ${toCreateEditorName(id)}`)
+      .join('\n')
+
+    return template
+      .replace('/* {{virtual-imports}} */', imports)
+      .replace('/* {{virtual-factory}} */', factoryEntries)
   }
 }

src/shared/throw.ts

@@ -1,6 +1,6 @@
 import chalk from 'chalk'
 
-export function throwError(message: string) {
+export function throwError(message: string): never {
   const label = chalk.black.bgRgb(220, 50, 50)(' FAIL ')
 
   console.warn('\n', label, chalk.red(message.replace(/( {1,})/g, ' ').replace(/^ /, '')))

test/features-input.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from '@jest/globals'
+
+import { React, resolveJobs } from '../src/app/features'
+import { TemplateBuilder } from '../src/app/template-builder'
+
+describe('Template jobs', () => {
+  const sources = ['default', 'scopes']
+  const react = new React(18, 'react-vite', false)
+  const optional = [react]
+
+  it('maps array features to all sources', () => {
+    const jobs = resolveJobs(sources, optional, 'react-vite', { features: ['React render'] })
+
+    expect(jobs.map(job => ({ name: job.name, from: job.from }))).toEqual([
+      { name: 'default', from: 'default' },
+      { name: 'scopes', from: 'scopes' }
+    ])
+    expect(jobs.every(job => job.features[0] === react)).toBe(true)
+  })
+
+  it('maps object form to source jobs plus extras', () => {
+    const jobs = resolveJobs(sources, optional, 'react-vite', {
+      features: {
+        base: ['React render'],
+        minimap: { from: 'default', features: ['React render'] }
+      }
+    })
+
+    expect(jobs.map(job => ({ name: job.name, from: job.from }))).toEqual([
+      { name: 'default', from: 'default' },
+      { name: 'scopes', from: 'scopes' },
+      { name: 'minimap', from: 'default' }
+    ])
+  })
+
+  it('uses selected features when input is omitted', () => {
+    const jobs = resolveJobs(sources, optional, 'react-vite', { selected: [react] })
+
+    expect(jobs).toHaveLength(2)
+    expect(jobs.every(job => job.features[0] === react)).toBe(true)
+  })
+})
+
+describe('Entry script', () => {
+  it('keeps base entry script without extras', async () => {
+    const code = await new TemplateBuilder([]).getEntryScript()
+
+    expect(code).toContain("import { createEditor as createDefaultEditor } from './default'")
+    expect(code).toContain("'scopes': createScopesEditor")
+    expect(code).not.toContain('{{virtual-imports}}')
+    expect(code).not.toContain('{{virtual-factory}}')
+    expect(code).not.toContain('minimap')
+  })
+
+  it('fills placeholders with dynamic template snippets', async () => {
+    const code = await new TemplateBuilder([]).getEntryScript(['minimap', 'my-feature'])
+
+    expect(code).toContain("import { createEditor as createMinimapEditor } from './minimap'")
+    expect(code).toContain("import { createEditor as createMyFeatureEditor } from './my-feature'")
+    expect(code).toContain("'minimap': createMinimapEditor")
+    expect(code).toContain("'my-feature': createMyFeatureEditor")
+    expect(code).not.toContain('{{virtual-imports}}')
+    expect(code).not.toContain('{{virtual-factory}}')
+  })
+})