@flowscripter/dynamic-cli-framework 1.0.11 → 1.1.0

package/README.md

@@ -9,7 +9,7 @@
 > A framework for developing CLI applications which supports dynamic discovery
 > and installation of new commands
 
-[//]: # (TODO: Remove this when plugin support and compiled binaries available.)
+[//]: # (TODO: Remove this when plugin support.)
 
 NOTE: The dynamic aspect is still in development as it relies upon:
 
@@ -45,8 +45,8 @@ So it isn't really dynamic at the moment! 😜
 - Support (optional) for persisted configuration and environment variables to
   specify command argument defaults.
 - Core (but optional) commands for help, logging level and version management.
-- Core (but optional) services for color output to stdout/stderr and
-  configuration management.
+- Core (but optional) services for color output, syntax highlighting and pretty
+  printing to stdout/stderr and configuration management.
 - Core (but optional) support for dynamic discovery and installation of commands
   and services using
   [dynamic-plugin-framework](https://github.com/flowscripter/dynamic-plugin-framework)
@@ -62,13 +62,12 @@ The following example projects are available:
 
 - [example-cli](https://github.com/flowscripter/example-cli) is an example CLI
   application based on this framework.
+- [mpeg-sdl-tool](https://github.com/flowscripter/mpeg-sdl-tool) is a real world
+  use case CLI application based on this framework.
 
 [//]: # (TODO: Add this when implemented.)
 [//]: # (- [example-cli-plugin](https://github.com/flowscripter/example-cli-plugin) is an)
 [//]: # (  example command and service plugin based on this framework.)
-[//]: # (TODO: Add this when implemented.)
-[//]: # (- [sdl-tool](https://github.com/flowscripter/sdl-tool) is a real world use case CLI)
-[//]: # (  application based on this framework.)
 
 ## Key Concepts
 
@@ -1240,6 +1239,14 @@ Provides:
 - `LogLevelCommand` which allows the log level to be set via the argument
   `--log-level` or the env var `LOG_LEVEL`.
 
+#### `PrettyPrinterServiceProvider`
+
+Provides:
+
+- `PrettyPrinterService` allowing pretty printing of structured data and source
+  code. JSON pretty printing is provided by default and other data or language
+  formats can be added on demand by commands.
+
 #### `SyntaxHighlighterServiceProvider`
 
 Provides:

package/bun.lock

@@ -8,6 +8,7 @@
         "fastest-levenshtein": "^1.0.16",
         "figlet": "^1.8.0",
         "highlight.js": "^11.11.1",
+        "prettier": "^3.5.3",
         "supports-color": "^10.0.0",
         "ts-log": "^2.2.7",
       },
@@ -48,6 +49,8 @@
 
     "lowlight": ["lowlight@3.1.0", "", { "dependencies": { "@types/hast": "^3.0.0", "devlop": "^1.0.0", "highlight.js": "~11.9.0" } }, "sha512-CEbNVoSikAxwDMDPjXlqlFYiZLkDJHwyGu/MfOsJnF3d7f3tds5J3z8s/l9TMXhzfsJCCJEAsD78842mwmg0PQ=="],
 
+    "prettier": ["prettier@3.5.3", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-QQtaxnoDJeAkDvDKWCLiwIXkTgRhwYDEQCghU9Z6q03iyek/rxRh/2lC3HB7P8sWT2xC/y5JDctPLBIGzHKbhw=="],
+
     "supports-color": ["supports-color@10.0.0", "", {}, "sha512-HRVVSbCCMbj7/kdWF9Q+bbckjBHLtHMEoJWlkmYzzdwhYMkjkOwubLM6t7NbWKjgKamGDrWL1++KrjUO1t9oAQ=="],
 
     "ts-log": ["ts-log@2.2.7", "", {}, "sha512-320x5Ggei84AxzlXp91QkIGSw5wgaLT6GeAH0KsqDmRZdVWW2OiSeVvElVoatk3f7nicwXlElXsoFkARiGE2yg=="],

package/package.json

@@ -18,7 +18,7 @@
   ],
   "module": "index.ts",
   "type": "module",
-  "version": "1.0.11",
+  "version": "1.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -33,6 +33,7 @@
     "fastest-levenshtein": "^1.0.16",
     "figlet": "^1.8.0",
     "highlight.js": "^11.11.1",
+    "prettier": "^3.5.3",
     "supports-color": "^10.0.0",
     "ts-log": "^2.2.7"
   }

package/src/api/service/core/PrettyPrinterService.ts

@@ -0,0 +1,42 @@
+export const PRETTY_PRINTER_SERVICE_ID =
+  "@flowscripter/dynamic-cli-framework/pretty-printer-service";
+
+import type { Plugin as PrettierSyntax } from "prettier";
+
+/**
+ * Service providing syntax based pretty printing of text for the CLI using [prettier](https://github.com/prettier/prettier).
+ */
+export default interface PrettyPrinterService {
+  /**
+   * Register a new syntax.
+   *
+   * The recommended way to define a new language syntax plugin is to follow the instructions here:
+   *
+   * https://prettier.io/docs/plugins#developing-plugins
+   *
+   * There is a list of already defined languages available for import here:
+   *
+   * * https://prettier.io/docs/
+   * * https://prettier.io/docs/plugins
+   *
+   * @param syntaxName the name used to refer to the syntax.
+   * @param syntaxDefinition the definition for the syntax conforming to the Prettier plugin syntax.
+   */
+  registerSyntax(
+    syntaxName: string,
+    syntaxDefinition: PrettierSyntax<unknown>,
+  ): Promise<void>;
+
+  /**
+   * Return the names of the currently registered syntaxes.
+   */
+  getRegisteredSyntaxes(): Promise<ReadonlyArray<string>>;
+
+  /**
+   * Return a pretty printed version of the provided text using the specified syntax.
+   *
+   * @param text the text to prettify.
+   * @param syntaxName the syntax to use.
+   */
+  prettify(text: string, syntaxName: string): Promise<string>;
+}

package/src/api/service/core/SyntaxHighlighterService.ts

@@ -1,16 +1,16 @@
 import type { LanguageFn as HighlightSyntax } from "highlight.js";
 
 export const SYNTAX_HIGHLIGHTER_SERVICE_ID =
-  "@flowscripter/dynamic-cli-framework/highlighter-service";
+  "@flowscripter/dynamic-cli-framework/syntax-highlighter-service";
 
 /**
- * Service providing syntax based color highlighting of text for the CLI using [highlight.js](https://highlightjs.org).
+ * Service providing syntax based color highlighting of text for the CLI using [highlight.js](https://github.com/highlightjs/highlight.js).
  */
 export default interface SyntaxHighlighterService {
   /**
    * Register a new syntax.
    *
-   * The recommended way to define a new language syntax is follow the instructions here:
+   * The recommended way to define a new language syntax is to follow the instructions here:
    *
    * * https://highlightjs.readthedocs.io/en/latest/language-contribution.html
    * * https://highlightjs.readthedocs.io/en/latest/building-testing.html
@@ -22,7 +22,7 @@ export default interface SyntaxHighlighterService {
    *
    * @param syntaxName the name used to refer to the syntax.
    * @param syntaxDefinition the definition for the syntax conforming to the Highlight JS
-   * [language definition syntax]().
+   * language definition syntax.
    */
   registerSyntax(syntaxName: string, syntaxDefinition: HighlightSyntax): void;
 
@@ -33,7 +33,7 @@ export default interface SyntaxHighlighterService {
 
   /**
    * Return a syntactically highlighted version of the provided text using the specified syntax.
-   * The returned text will include appropriate ASCII color codes.
+   * The returned text will include appropriate terminal color codes.
    *
    * @param text the text to highlight.
    * @param syntaxName the syntax to use.

package/src/service/prettyPrinter/DefaultPrettyPrinterService.ts

@@ -0,0 +1,67 @@
+import type PrettyPrinterService from "../../api/service/core/PrettyPrinterService.ts";
+import * as prettier from "prettier";
+import type { Plugin as PrettierSyntax } from "prettier";
+
+/**
+ * Default implementation of {@link PrettyPrinterService} which already has syntax definitions
+ * for those built into prettier.
+ */
+export default class DefaultPrettyPrinterService
+  implements PrettyPrinterService {
+  #registeredSyntaxes = new Array<string>();
+  #syntaxNameToDefinitionMap = new Map<string, PrettierSyntax>();
+
+  async #populateBuiltInSyntaxes(): Promise<void> {
+    const languages = (await prettier.getSupportInfo()).languages;
+    this.#registeredSyntaxes = languages.map((language) =>
+      language.name.toLowerCase()
+    );
+  }
+
+  async getRegisteredSyntaxes(): Promise<ReadonlyArray<string>> {
+    if (this.#registeredSyntaxes.length === 0) {
+      await this.#populateBuiltInSyntaxes();
+    }
+
+    return this.#registeredSyntaxes;
+  }
+
+  async prettify(text: string, syntaxName: string): Promise<string> {
+    if (this.#registeredSyntaxes.length === 0) {
+      await this.#populateBuiltInSyntaxes();
+    }
+
+    const name = syntaxName.toLowerCase();
+    if (!this.#registeredSyntaxes.includes(name)) {
+      throw new Error(`Syntax name is not registered: ${name}`);
+    }
+
+    const options: prettier.Options = { parser: syntaxName };
+
+    const syntaxDefinition = this.#syntaxNameToDefinitionMap.get(
+      name,
+    );
+    if (syntaxDefinition) {
+      options.plugins = [syntaxDefinition];
+    }
+
+    return prettier.format(text, options);
+  }
+
+  async registerSyntax(
+    syntaxName: string,
+    syntaxDefinition: PrettierSyntax,
+  ): Promise<void> {
+    if (this.#registeredSyntaxes.length === 0) {
+      await this.#populateBuiltInSyntaxes();
+    }
+
+    const name = syntaxName.toLowerCase();
+    if (this.#registeredSyntaxes.includes(name)) {
+      throw new Error(`Syntax name already registered: ${name}`);
+    }
+
+    this.#registeredSyntaxes.push(name);
+    this.#syntaxNameToDefinitionMap.set(name, syntaxDefinition);
+  }
+}

package/src/service/prettyPrinter/PrettyPrinterServiceProvider.ts

@@ -0,0 +1,40 @@
+import type {
+  ServiceInfo,
+  ServiceProvider,
+} from "../../api/service/ServiceProvider.ts";
+import DefaultPrettyPrinterService from "./DefaultPrettyPrinterService.ts";
+import {
+  PRETTY_PRINTER_SERVICE_ID,
+} from "../../api/service/core/PrettyPrinterService.ts";
+import type Context from "../../api/Context.ts";
+import type CLIConfig from "../../api/CLIConfig.ts";
+
+/**
+ * Provides a {@link PrettyPrinterService}.
+ */
+export default class PrettyPrinterServiceProvider implements ServiceProvider {
+  readonly serviceId: string = PRETTY_PRINTER_SERVICE_ID;
+  readonly #defaultPrettyPrinterService: DefaultPrettyPrinterService;
+
+  /**
+   * Create an instance of the service provider with the specified details.
+   *
+   * @param servicePriority the priority of the service.
+   */
+  public constructor(
+    readonly servicePriority: number,
+  ) {
+    this.#defaultPrettyPrinterService = new DefaultPrettyPrinterService();
+  }
+
+  public provide(_cliConfig: CLIConfig): Promise<ServiceInfo> {
+    return Promise.resolve({
+      service: this.#defaultPrettyPrinterService,
+      commands: [],
+    });
+  }
+
+  initService(_context: Context): Promise<void> {
+    return Promise.resolve(undefined);
+  }
+}

package/tests/fixtures/prettierPluginFoo.ts

@@ -0,0 +1,27 @@
+const languages = [
+  {
+    name: "foo",
+    parsers: ["foo"],
+  },
+];
+
+const parsers = {
+  foo: {
+    astFormat: "foo",
+    parse: () => "",
+    locStart: () => 0,
+    locEnd: () => 0,
+  },
+};
+
+const printers = {
+  "foo": {
+    print: () => "foo",
+  },
+};
+
+export default {
+  languages,
+  parsers,
+  printers,
+};

package/tests/runtime/runner.test.ts

@@ -1224,7 +1224,7 @@ describe("runner tests", () => {
     expect(hasRun).toBeTrue();
   });
 
-  test("Group command as default command is invalid", async () => {
+  test("Group command as default command is invalid", () => {
     const streamString = new StreamString();
     const groupCommand = getGroupCommand();
 
@@ -1232,7 +1232,7 @@ describe("runner tests", () => {
       return Promise.resolve();
     };
 
-    await expect(
+    expect(
       run(
         [],
         new DefaultCommandRegistry([]),

package/tests/service/asciiBannerGenerator/DefaultAsciiBannerGeneratorService.test.ts

@@ -34,11 +34,11 @@ describe("DefaultAsciiBannerGeneratorService tests", () => {
     ]);
   });
 
-  test("Cannot generate with unknown font", async () => {
+  test("Cannot generate with unknown font", () => {
     const asciiBannerGeneratorService =
       new DefaultAsciiBannerGeneratorService();
 
-    await expect(asciiBannerGeneratorService.generate("foo", "small")).rejects
+    expect(asciiBannerGeneratorService.generate("foo", "small")).rejects
       .toThrow();
   });
 

package/tests/service/prettyPrinter/DefaultPrettyPrinterService.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import DefaultPrettyPrinterService from "../../../src/service/prettyPrinter/DefaultPrettyPrinterService";
+import FooSyntax from "../../fixtures/prettierPluginFoo";
+
+describe("DefaultPrettyPrinterService tests", () => {
+  test("JSON registered by default", async () => {
+    const prettyPrinterService = new DefaultPrettyPrinterService();
+
+    expect(await prettyPrinterService.getRegisteredSyntaxes()).toContain(
+      "json",
+    );
+  });
+
+  test("Cannot register a syntax if already registered", () => {
+    const prettyPrinterService = new DefaultPrettyPrinterService();
+
+    expect(prettyPrinterService.registerSyntax("jSon", FooSyntax)).rejects
+      .toThrow();
+  });
+
+  test("Can register new syntax", async () => {
+    const prettyPrinterService = new DefaultPrettyPrinterService();
+
+    prettyPrinterService.registerSyntax("foo", FooSyntax);
+    expect(await prettyPrinterService.getRegisteredSyntaxes()).toContain("foo");
+  });
+
+  test("Cannot pretty print with unknown syntax", () => {
+    const prettyPrinterService = new DefaultPrettyPrinterService();
+
+    expect(() => prettyPrinterService.prettify("foo: 1", "bar"))
+      .toThrow();
+  });
+
+  test("Can pretty print with JSON syntax", async () => {
+    const prettyPrinterService = new DefaultPrettyPrinterService();
+
+    const prettified = await prettyPrinterService.prettify(
+      "{foo:1}",
+      "json",
+    );
+    expect(prettified).toEqual('{ "foo": 1 }\n');
+  });
+
+  test("Can pretty print with newly registered syntax", async () => {
+    const prettyPrinterService = new DefaultPrettyPrinterService();
+
+    prettyPrinterService.registerSyntax("foo", FooSyntax);
+
+    const prettified = await prettyPrinterService.prettify("foo: 1", "foo");
+    expect(prettified).toEqual("foo");
+  });
+});

package/tests/service/prettyPrinter/PrettyPrinterServiceProvider.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import DefaultContext from "../../../src/runtime/DefaultContext.ts";
+import { getCLIConfig } from "../../fixtures/CLIConfig.ts";
+import PrettyPrinterServiceProvider from "../../../src/service/prettyPrinter/PrettyPrinterServiceProvider.ts";
+import { PRINTER_SERVICE_ID } from "../../../src/api/service/core/PrinterService.ts";
+import DefaultPrinterService from "../../../src/service/printer/DefaultPrinterService.ts";
+import StreamString from "../../fixtures/StreamString.ts";
+import TtyTerminal from "../../../src/service/printer/terminal/TtyTerminal.ts";
+import TtyStyler from "../../../src/service/printer/terminal/TtyStyler.ts";
+
+describe("PrettyPrinterServiceProvider tests", () => {
+  test("PrettyPrinterServiceProvider provide and initService works", async () => {
+    const dummyStdout = new StreamString();
+    const dummyStderr = new StreamString();
+    const prettyPrinterServiceProvider = new PrettyPrinterServiceProvider(
+      100,
+    );
+    const cliConfig = getCLIConfig();
+    const context = new DefaultContext(cliConfig);
+
+    context.addServiceInstance(
+      PRINTER_SERVICE_ID,
+      new DefaultPrinterService(
+        dummyStdout.writableStream,
+        dummyStderr.writableStream,
+        true,
+        true,
+        new TtyTerminal(dummyStderr.writeStream),
+        new TtyStyler(3),
+      ),
+    );
+
+    const serviceInfo = await prettyPrinterServiceProvider.provide(
+      cliConfig,
+    );
+    expect(serviceInfo.commands.length).toEqual(0);
+
+    await prettyPrinterServiceProvider.initService(context);
+  });
+});