@teambit/harmony 0.0.0-19ea14143ef7d5f4e4daa6e8ac8a8c97c9d683d5

package/extension-graph/from-extension.ts

@@ -0,0 +1,72 @@
+import { ExtensionManifest } from '../extension';
+import { extensionFactory } from '../factory';
+import ExtensionPotentialCircular from '../exceptions/extension-potential-circular';
+import { Extension } from '../extension';
+import { DependencyGraphOptions, Edge } from './extension-graph';
+
+function getName(manifest: any) {
+  return Reflect.getMetadata('harmony:name', manifest) || manifest.id || manifest.name;
+}
+
+/**
+ * build vertices and edges from the given extension
+ */
+export function fromExtension(extension: ExtensionManifest, options: DependencyGraphOptions = {}) {
+  const vertices: { [id: string]: Extension } = {};
+  let edges: { sourceId: string; targetId: string; edge: Edge }[] = [];
+
+  function iterate(root: ExtensionManifest) {
+    const id = options.getName ? options.getName(root) : getName(root);
+    if (vertices[id]) return;
+
+    const instance = extensionFactory(root);
+    const validDeps = instance.dependencies.filter(dep => dep).map(dep => extensionFactory(dep));
+    if (instance.dependencies.length > validDeps.length) {
+      throw new ExtensionPotentialCircular(instance, validDeps);
+    }
+    vertices[id] = instance;
+    const newEdges = validDeps.map(dep => {
+      return {
+        sourceId: id,
+        targetId: dep.name,
+        edge: {
+          type: 'dependency'
+        }
+      };
+    });
+
+    edges = edges.concat(newEdges);
+
+    // @ts-ignore
+    instance.dependencies.forEach(dep => iterate(dep));
+  }
+
+  iterate(extension);
+
+  let vertexArray: { id: string; node: Extension }[] = [];
+  for (let [key, value] of Object.entries(vertices)) {
+    vertexArray.push({ id: key, node: value });
+  }
+
+  return {
+    vertices: vertexArray,
+    edges
+  };
+}
+
+/**
+ * build vertices and edges from the given list of extensions
+ */
+export function fromExtensions(extensions: ExtensionManifest[], options: DependencyGraphOptions = {}) {
+  const perExtension = extensions.map(ext => fromExtension(ext, options));
+
+  return perExtension.reduce(
+    (acc, subgraph) => {
+      acc.edges = acc.edges.concat(subgraph.edges);
+      acc.vertices = acc.vertices.concat(subgraph.vertices);
+
+      return acc;
+    },
+    { vertices: [], edges: [] }
+  );
+}

package/extension-graph/index.ts

@@ -0,0 +1 @@
+export { default as DependencyGraph } from './extension-graph';

package/factory/extension-factory.ts

@@ -0,0 +1,8 @@
+import { ExtensionManifest } from '../extension/extension-manifest';
+import { Extension } from '../extension/extension';
+
+export function extensionFactory(manifest: ExtensionManifest) {
+  // to allow the use of `provide` as an alias to `provider` in ExtensionManifest
+  if (manifest.provide) manifest.provider = manifest.provide;
+  return new Extension(manifest);
+}

package/factory/index.ts

@@ -0,0 +1 @@
+export { extensionFactory } from './extension-factory';

package/fixtures/aspects/babel/babel.aspect.ts

@@ -0,0 +1,14 @@
+import type { BabelCLI } from './babel.cli';
+import { Aspect } from '../../../aspect';
+
+export type { BabelCLI };
+
+export const BabelAspect = Aspect.create({
+  id: '@teambit/babel',
+  dependencies: [],
+  files: [
+    require.resolve('./babel.cli')
+  ]
+});
+
+export default BabelAspect;

package/fixtures/aspects/babel/babel.cli.ts

@@ -0,0 +1,16 @@
+import { BabelAspect } from './babel.aspect';
+import { CLIRuntime } from '../react/react.aspect';
+
+export class BabelCLI {
+  compile() {
+    console.log('compiled!');
+  }
+
+  static runtime = CLIRuntime;
+
+  static async provider() {
+    return new BabelCLI();
+  }
+}
+
+BabelAspect.addRuntime(BabelCLI);

package/fixtures/aspects/react/react.aspect.ts

@@ -0,0 +1,22 @@
+import { BabelAspect } from '../babel/babel.aspect';
+import { Aspect } from '../../../aspect';
+import { Slot } from '../../../slots';
+import { RuntimeDefinition } from '../../../runtimes';
+import { UIAspect } from '../ui/ui.aspect';
+
+export type Config = {};
+
+export const CLIRuntime = RuntimeDefinition.create({ name: 'cli' })
+
+export const ReactAspect = Aspect.create({
+  id: '@teambit/react',
+  dependencies: [UIAspect],
+  defaultConfig: {},
+  declareRuntime: CLIRuntime,
+  files: [
+    require.resolve('./react.cli'),
+    require.resolve('./react.ui')
+  ]
+});
+
+export default ReactAspect;

package/fixtures/aspects/react/react.cli.ts

@@ -0,0 +1,26 @@
+import ReactAspect, { CLIRuntime } from './react.aspect';
+import BabelAspect, { BabelCLI } from '../babel/babel.aspect';
+import { Slot, SlotRegistry } from '../../../slots';
+
+export class ReactCLI {
+  constructor(
+    private babel: BabelCLI
+  ) {}
+
+  static runtime = CLIRuntime;
+
+  hello() {
+    return this.babel.compile();
+  }
+
+  static dependencies = [BabelAspect];
+
+  static slots = [Slot.withType<string>()];
+
+  static async provider([babelCli]: [BabelCLI], config: {}, [stringSlot]: [SlotRegistry<string>]) {
+    stringSlot.register('hi there');
+    return new ReactCLI(babelCli);
+  }
+}
+
+ReactAspect.addRuntime(ReactCLI);

package/fixtures/aspects/react/react.ui.ts

@@ -0,0 +1,16 @@
+import ReactAspect from './react.aspect';
+import { UIRuntime } from '../ui/ui.aspect';
+
+export class ReactUI {
+  static runtime = UIRuntime;
+
+  render() {
+    return 'rendering something!';
+  }
+
+  static async provider() {
+    return new ReactUI();
+  } 
+}
+
+ReactAspect.addRuntime(ReactUI);

package/fixtures/aspects/ui/ui.aspect.ts

@@ -0,0 +1,13 @@
+import { Aspect } from '../../../aspect';
+import { RuntimeDefinition } from '../../../runtimes';
+
+export const UIRuntime = RuntimeDefinition.create({ name: 'ui' });
+
+export const UIAspect = Aspect.create({
+  id: '@teambit/ui',
+  dependencies: [],
+  declareRuntime: UIRuntime,
+  files: [
+    require.resolve('./ui.ui')
+  ]
+});

package/fixtures/aspects/ui/ui.ui.ts

@@ -0,0 +1,11 @@
+import { UIAspect, UIRuntime } from './ui.aspect';
+
+export class UiUI {
+  static runtime = UIRuntime;
+
+  static async provider() {
+    return new UiUI();
+  }
+}
+
+UIAspect.addRuntime(UiUI);

package/fixtures/babel/babel.extension.ts

@@ -0,0 +1,20 @@
+import { Extension, provider } from '../..';
+import { BaseCompiler } from '../base-compiler';
+
+class Mock {
+
+}
+
+// @Extension({
+  // dependencies: [BaseCompiler]
+// })
+export class Babel {
+  constructor(
+    private mock?: Mock
+  ) {}
+
+  // @provider()
+  async provide([baseCompiler]: [BaseCompiler]) {
+    return new Babel();
+  }
+}

package/fixtures/base-compiler/base-compiler.extension.ts

@@ -0,0 +1,31 @@
+import { Extension } from "../..";
+import { CLI, Command } from '../cli';
+
+// @Extension()
+export class BaseCompiler {
+  constructor(
+    private cli: CLI
+  ) {}
+
+  // @Config()
+  config() {
+    return {
+      cjs: 'blue/green'
+    };
+  }
+
+  // @Command
+  main() {
+    return {
+      synopsis: 'compile <id>',
+      report: () => {
+        return 'compiled in 0.1 secs';
+      }
+    };
+  }
+
+  compile() {
+    this.cli.run();
+    return 'hello world';
+  }
+}

package/fixtures/base-compiler/index.ts

@@ -0,0 +1 @@
+export { BaseCompiler } from './base-compiler.extension';

package/fixtures/cli/cli.extension.ts

@@ -0,0 +1,25 @@
+import { Extension, createHook } from '../..';
+import { HookRegistry, hook } from '../..';
+
+/**
+ * hook for registering new CLI commands.
+ */
+export const Command = createHook();
+
+export type CommandDefinition = {
+  synopsis: string,
+  report: string
+};
+
+// @Extension()
+export class CLI {
+  /**
+   * registry for the commands hook
+   */
+  private commands = HookRegistry.of<CommandDefinition>(Command);
+
+  run() {
+    const commands = this.commands.list();
+    return commands;
+  }
+}

package/fixtures/cli/command.ts

@@ -0,0 +1,6 @@
+interface Command {
+  command(): {
+    synopsis: string,
+    run: () => Promise<any>
+  }
+}

package/fixtures/cli/index.ts

@@ -0,0 +1 @@
+export * from './cli.extension';

package/fixtures/typescript/typescript.ts

@@ -0,0 +1,20 @@
+import { Extension } from '../..';
+import { BaseCompiler } from '../base-compiler';
+
+// @Extension({
+//   name: 'typescript',
+//   dependencies: [BaseCompiler]
+// })
+export class TypeScript {
+  constructor(
+    private compiler: string
+  ) {}
+
+  compile() {
+    return this.compiler;
+  }
+
+  static async provider([baseCompiler]: [BaseCompiler]) {
+    return new TypeScript(baseCompiler.compile());
+  }
+}

package/harmony-config/config-reader.ts

@@ -0,0 +1,18 @@
+import { parse } from 'comment-json';
+import { readFileSync, existsSync } from 'fs';
+import { ReadConfigError } from './exceptions/read-config-error';
+
+export function readConfigFile(path: string, mustExist = true): Record<string, any> {
+  if (!mustExist && !existsSync(path)) {
+    return {};
+  }
+
+  try {
+    const parsed = parse(readFileSync(path, 'utf8'));
+    const json: Record<string, any> = parsed && typeof parsed === 'object' ? (parsed as Record<string, any>) : {};
+    delete json['$schema'];
+    return json;
+  } catch (err) {
+    throw new ReadConfigError(path, err instanceof Error ? err : new Error(String(err)));
+  }
+}

package/harmony-config/exceptions/index.ts

@@ -0,0 +1 @@
+export { ReadConfigError } from './read-config-error';

package/harmony-config/exceptions/read-config-error.ts

@@ -0,0 +1,9 @@
+export class ReadConfigError extends Error {
+  constructor(path: string, private err: Error) {
+    super(`failed to read config from path: ${path}`);
+  }
+
+  get stack() {
+    return this.err.stack;
+  }
+}

package/harmony-config/harmony-config.ts

@@ -0,0 +1,49 @@
+import { stringify, assign } from 'comment-json';
+import { join } from 'path';
+import { readConfigFile } from './config-reader';
+
+const userHome = require('user-home');
+
+export type ConfigOptions = {
+  cwd?: string;
+  global?: GlobalConfigOpts;
+  shouldThrow?: boolean;
+};
+
+export type GlobalConfigOpts = {
+  dir?: string;
+  name: string;
+};
+
+const defaultConfig = {
+  cwd: process.cwd(),
+  shouldThrow: true,
+};
+
+export class HarmonyConfig {
+  constructor(private raw: Record<string, any>) {}
+
+  toObject() {
+    return this.raw;
+  }
+
+  toString() {
+    return stringify(this.raw);
+  }
+
+  static load(fileName: string, opts?: ConfigOptions) {
+    const mergedOpts = Object.assign(defaultConfig, opts);
+    const config = readConfigFile(join(mergedOpts.cwd, fileName), mergedOpts.shouldThrow);
+
+    if (mergedOpts.global) {
+      return HarmonyConfig.loadGlobal(mergedOpts.global, config);
+    }
+
+    return new HarmonyConfig(config);
+  }
+
+  static loadGlobal(globalOpts: GlobalConfigOpts, config: any = {}) {
+    const globalConfig = readConfigFile(join(globalOpts.dir || userHome, globalOpts.name), false);
+    return new HarmonyConfig(assign(config, globalConfig));
+  }
+}

package/harmony-config/index.ts

@@ -0,0 +1 @@
+export { HarmonyConfig as Config, ConfigOptions } from './harmony-config';

package/harmony.docs.mdx

@@ -0,0 +1,250 @@
+---
+description: Harmony is an abstract extension system you can use to make any software extendable and composable. It is the engine that drives Bit extensibility and composability.
+labels: ['aspect', 'composition', 'extendability']
+---
+
+## Basic features
+
+Harmony allows you to implement Aspects as the main building blocks that compose your software. Each Aspect has:
+
+* Dependency declaration - Where you declare other Aspects as dependencies.
+* Dependency injection - An Aspect gets providers for all its dependencies.
+* Slots - An easy way for an Aspect to provide API for another aspect to hook into any of its processes.
+* Multiple runtimes - Aspect can annotate in which runtimes it can run (for example providing functionality to run on the server and on the browser).
+
+## Harmony config file
+
+Use a config file to describe your desired composition of Aspects and their configuration. Harmony uses a basic JSON syntax, where each key is an aspect.
+
+```json
+{
+  "teambit.dependencies/dependency-resolver": {}, // load an Aspect without providing configuration
+  "teambit.workspace/workspace": {                // Load an Aspect with configuration
+    "name": "bit",
+    "icon": "https://static.bit.dev/bit-logo.svg",
+}
+```
+
+## Define an aspect
+
+Harmony Aspect is  an object that implements the `ExtensionManifest` interface
+
+```js
+export type ExtensionManifest = {
+  /**
+   * Aspect's name.
+   */
+  name: string;
+
+  /**
+   * Aspect unique ID.
+   */
+  id?: string;
+
+  /**
+   * Array of dependencies.
+   * These other Aspects to be installed and resolved prior to this Aspect activation.
+   */
+  dependencies?: ExtensionManifest[];
+
+  /**
+   * Reference to the Aspect factory function.
+   */
+  provider?: ProviderFn;
+
+  /**
+   * Default Aspect configuration. 
+   */
+  defaultConfig?: object;
+
+  /**
+   * Alias to the provider.
+   */
+  provide?: ProviderFn;
+
+  /**
+   * Array of slots the Aspect exposes.
+   */
+  slots?: SlotProvider<unknown>[],
+
+  /**
+   * Additional keys which might be expected by other Aspects.
+   */
+  [key: string]: any;
+}
+```
+
+## Programmatic API
+
+### Static API
+
+```js
+// Create instance of harmony with the provided aspects, on specific runtime, with provided config
+static async load(aspects: Aspect[], runtime: string, globalConfig: GlobalConfig) {
+```
+
+### Instance API
+
+```js
+// load an Aspect into the dependency graph
+async load(extensions: ExtensionManifest[])
+
+// set extensions during Harmony runtime.
+async set(extensions: ExtensionManifest[])
+
+export type RequireFn = (aspect: Extension, runtime: RuntimeDefinition) => Promise<void>;
+
+// Start harmony. 
+// The require function is a function that get's the aspect and its runtime, and knows to require/load it
+async run(requireFn?: RequireFn) 
+```
+
+## Assumptions
+
+* Harmony does not allow circular dependencies between Aspects.
+
+{/*
+
+-------------------------for reference only - to remove ------------------
+
+## composition model
+Harmony proposes a graph composition model.
+composition model should allow:
+
+- full control over composition including dependency composition.
+- easy overrides mechanism for configs.
+- full encapsulation of an extension. 
+
+bit.config.js
+```js
+import FlowSchemaPlugin from '@bit/plugins.flow-schema';
+
+export default () => {
+  return [ // returns an array of PluginInstance
+    [FlowSchemaPlugin, {
+
+    }],
+    [ReactSchemaPlugin, {
+      eslintrc: './.eslintrc'
+    }]
+  ];
+}
+```
+
+configured extensions in bit.json
+```json
+{
+  "extensions": {
+    "bit.envs/eslint@0.0.4": {
+      "eslintrc": "./.eslintrc"
+    },
+    "bit.envs/babel@0.0.1": {
+      "babelrc": "./.babelrc",
+      "strict": true,
+      "__alias": "compile"
+    },
+    "bit.envs/webpack@0.0.1": {
+      "config": "./webpack.config.js",
+      "mode": "prod",
+      "__alias": "bundle"
+    },
+    "bit.envs/mocha@0.0.1": {
+      "reporter": "json",
+      "mochaOptions": "./mocha.opts",
+      "__alias": "test-mocha"
+    }
+  },
+  "pipes": {
+    "tag": [""]
+  },
+  "dist": {
+    "target": "",
+    "entry": ""
+  }
+}
+```
+
+### Open questions
+- How do I install a Bit extensions? Where the component is configured?
+- Is the extension installed with Bit/NPM?
+- What's the impl. behind `bit use <plugin/extension name>`
+- maybe an composition model can co-exist as json and js? what are the tradeoffs?
+
+## extension registration
+```js
+import { register } from 'harmony';
+import { DocGen } from '@bit/bit.exts.doc-gen';
+
+const extensions = register([DocGen]);
+```
+
+## lifecycle event invocation
+
+```js
+import { invoke } from 'harmony';
+
+invoke('tag', ...data);
+```
+
+## lifecycle event registration
+```js
+import { Lifecycle } from 'harmony';
+
+@Lifecycle(Tag);
+function tag() {
+  
+}
+```
+
+## state / schema management
+```ts
+@Lifecycle(Tag)
+function tag(component: Component) {
+  const docs = component.get('docs'); // returns `Maybe` type?
+  const docs: Docs = docs.get();
+}
+```
+
+## function extension 
+
+```js
+export default function foo() {
+  context.a
+}
+```
+
+## configuration
+an extension can declaratively ask for configuration type. this can be reflected
+- extensions can be configured during instantiation.
+- configuration types can be built from multiple sources
+
+## context
+- standard context can be shared between all extensions in the same instance.
+
+## extension composition
+- hook invocation from an extension
+- extension dependencies? how can an extension declare a dependency as part of its execution? 
+- contextual/namespaced hooks
+- config api
+
+## extension resolution
+```js
+import { resolve } from 'harmony';
+
+const extension = resolve('doc-gen');
+```
+
+## Questions (?)
+- can extensions be added/configured during runtime? DI
+- is there a difference between extension composition to registration?
+- how to make autocomplete work for hooks?
+- how to avoid unintentional hook invocation (decorators?) 
+- how to declare a new hook..
+- schema validator
+- dev experience of an extension.
+- how do manage different runtime environments? should I? Why is that relevant?
+- runtime capsules?
+- how can one extension run from both server and client? how capsule is related?
+- in which process extensions will run from? also, what will happen from the backend?
+- 
+*/}