docomet

v0.2.0

Published

12 days ago

Documentation updates at comet speed.

0High
0Medium
0Low

mskz-3110

document comment inspectable mtime-check replace class-map

☄️ docomet - Documentation updates at comet speed.

| Feature | Motivation | Solution | | :--- | :--- | :--- | | Inspectable | Want to check static properties and method names by specifying a class in console.log() within REPL | Provides a dedicated class that organizes and outputs the internal structure just by inheriting | | MtimeCheck | Want to prevent "update omissions" where the translated file remains outdated even though the source file has been updated | Provides dedicated methods, classes, and commands to compare update dates and determine if an update is necessary | | Replace | Want to easily update command execution results within a file to the latest state | Provides dedicated methods, classes, and commands to replace content with command execution results within comment tags | | ClassMap | Want to easily visualize class relationships using mermaid | Provides dedicated methods, classes, and commands to generate mermaid formatted text from TSDoc |

🚀 Installation

pnpm install docomet

💖 Quick Start

docomet prioritizes "ease of use" and "implementation comfort" for developers.

Import

// REPL Support (Dynamic Import)
const {docomet} = await import('docomet');

Inspectable

const {DocometInspectableObjectClass} = await import('docomet/docomet-inspectable');

class Sample extends DocometInspectableObjectClass {
  static staticPublicProperty = '';
  static #staticPrivateProperty = '';
  static get staticPrivateProperty() {return Sample.#staticPrivateProperty;}
  static set staticPrivateProperty(value) {Sample.#staticPrivateProperty = value;}
  static staticMethod() {}

  toJSON() {
    return {
      name: this.constructor.name,
    };
  }
}

| Class Output Result (Default) | Class Output Result (DocometInspectableObjectClass) | | :--- | :--- | | $ console.log(Sample);[class Sample] { staticPublicProperty: '' } | $ console.log(Sample);[class Sample] { propertyNames: [ 'staticPublicProperty' ], accessorNames: [ 'staticPrivateProperty' ], methodNames: [ 'staticMethod' ]} |

| Instance Output Result (Default) | Instance Output Result (DocometInspectableObjectClass) | | :--- | :--- | | $ console.log(new Sample());Sample {} | $ console.log(new Sample());{ name: 'Sample'} |

Mixin Based on Classes Other Than Object (such as Array or Map)

const {DocometInspectable} = await import('docomet/docomet-inspectable');
const InspectableArrayClass = DocometInspectable(Array);
const InspectableMapClass = DocometInspectable(Map);

class SampleArray extends InspectableArrayClass {
  ...
}

class SampleMap extends InspectableMapClass {
  ...
}

MtimeCheck

Example command to check if xyz.log is newer than abc.log.

npx docomet-mtime-check -o abc.log -n xyz.log

| Output Type | Output Content | Description | | :--- | :--- | :--- | | Error | Outdated: {path} | The file is outdated. | | Error | NotFoundOlderPath: {path} | The source older file path does not exist. | | Error | NotFoundNewerPath: {path} | The target newer file path does not exist. |

Replace

<!-- docomet:bash node -v -->
<!-- docomet:/bash -->

Example command to execute and replace the node version display command.

npx docomet-replace < <(cat replace_node_version.md)

<!-- docomet:bash node -v -->
vX.Y.Z
<!-- docomet:/bash -->

| Output Type | Output Content | Description | | :--- | :--- | :--- | | Log | Skipped: {path} | Skipped because there are no changes to the file content. | | Log | Replaced: {path} | Replaced with new content because there are differences in the file content. | | Error | Unexpected: {tag} | Tags do not match. | | Error | Unclosed: {tag} | No closing tag. |

Basic Syntax

Parses and executes unique HTML comment tags.

It also recognizes tags within comments such as # or //.

<!-- docomet:TYPE[(LANGUAGE)] [ARGS...] -->
<!-- docomet:/TYPE -->

# <!-- docomet:TYPE[(LANGUAGE)] [ARGS...] -->
# <!-- docomet:/TYPE -->

// <!-- docomet:TYPE[(LANGUAGE)] [ARGS...] -->
// <!-- docomet:/TYPE -->

If LANGUAGE is omitted, the execution result of TYPE is output as is.

<!-- docomet:bash node -v -->
<!-- docomet:/bash -->

↓

<!-- docomet:bash node -v -->
vX.Y.Z
<!-- docomet:/bash -->

If LANGUAGE is specified, the specified string is output as the language identifier for the code block.

<!-- docomet:bash(text) node -v -->
<!-- docomet:/bash -->

↓

<!-- docomet:bash(text) node -v -->
```text
vX.Y.Z
```
<!-- docomet:/bash -->

However, if none is specified, nothing is output.

Use this when you want to execute only the command without outputting the result.

<!-- docomet:bash(none) node -v -->
<!-- docomet:/bash -->

↓

<!-- docomet:bash(none) node -v -->
<!-- docomet:/bash -->

TYPE List

bash

Outputs the execution result of the command specified in ARGS.

<!-- docomet:bash node -v -->
<!-- docomet:/bash -->

↓

<!-- docomet:bash node -v -->
vX.Y.Z
<!-- docomet:/bash -->

file

Outputs the content of the file specified in ARGS.

<!-- docomet:file(javascript) sample.js -->
<!-- docomet:/file -->

↓

<!-- docomet:file(javascript) sample.js -->
```javascript
const {DocometInspectableObjectClass} = await import('docomet/docomet-inspectable');

class Sample extends DocometInspectableObjectClass {
  static staticPublicProperty = '';
  static #staticPrivateProperty = '';
  static get staticPrivateProperty() {return Sample.#staticPrivateProperty;}
  static set staticPrivateProperty(value) {Sample.#staticPrivateProperty = value;}
  static staticMethod() {}

  toJSON() {
    return {
      name: this.constructor.name,
    };
  }
}
```
<!-- docomet:/file -->

ignore

ARGS is not required, and tags enclosed in ignore are ignored.

<!-- docomet:ignore -->
  <!-- docomet:bash node -v -->
  <!-- docomet:/bash -->

  <!-- docomet:file(javascript) sample.js -->
  <!-- docomet:/file -->
<!-- docomet:/ignore -->

ClassMap

Example command to generate a class map for the src directory.

npx docomet-class-map src

| Output Type | Output Content | Description | | :--- | :--- | :--- | | Error | NotFoundProject: {"entryPoints":[""],"rootPath":""} | The specified project does not exist. |

🗺️ Class Map

classDiagram
  class DocometColor {
    static coloring(colorName:string,message:string) string
    static names() string[]
    static set(colorName:string,newFormatter:DocometColorFormatter) DocometColorFormatter
  }
  class DocometCommander {
    baseCommandName() string &lt;&lt;getter&gt;&gt;
    command() Command &lt;&lt;getter&gt;&gt;
    static packageJson() DocometCommanderPackageJson &lt;&lt;getter&gt;&gt;
    DocometCommander(baseCommandName:string) DocometCommander
    addHelpText(text:string) DocometCommander
    addOption(flags:string,description:string,required:boolean,defaultValue:string,choices:string[]) DocometCommander
    toJSON() object
    toString() string
    static new(...args:[baseCommandName:string]) DocometCommander
    static async runAsync(callback:DocometCommanderRunAsyncCallback) Promise&lt;void&gt;
  }
  class DocometError {
    deleteStack() DocometError
    static toErrorString(error:unknown) string
  }
  class DocometClassMap {
    base() string &lt;&lt;getter&gt;&gt;
    dir() string &lt;&lt;getter&gt;&gt;
    ext() string &lt;&lt;getter&gt;&gt;
    name() string &lt;&lt;getter&gt;&gt;
    static rootPath() string &lt;&lt;getter&gt;&gt;
    DocometClassMap(dir:string,name:string,ext:string) DocometClassMap
    toJSON() string
    toPosixString() string
    toString() string
    with(updates:Partial&lt;#123;dir:string,ext:string,name:string#125;&gt;) DocometClassMap
    static absolute(path:string) string
    static doesNotExist(path:string) boolean
    static exists(path:string) boolean
    static findUp(name:string,startPath:string) string|undefined
    static join(...paths:string[]) string
    static joinPosix(...paths:string[]) string
    static new(...args:[dir:string,name?:string,ext?:string]) DocometClassMap
    static parse(path:string) DocometClassMap
    static rebuild(path:string,split:DocometPathSplit,join:DocometPathJoin) string
    static relative(targetPath:string,rootPath:string) string
    static split(path:string) string[]
    static splitPosix(path:string) string[]
  }
  class DocometProcess {
    static logging:DocometLogging
    static abort(message:string) void
    static exit(code:number,message:string) void
    static setupErrorHandlers() void
    static async sleepAsync(delay:number) Promise&lt;void&gt;
  }
  class DocometStat {
    static checkMtime(olderPath:string,newerPath:string) void
    static getMtime(path:string) Date|undefined
    static needsUpdate(olderPath:string,newerPath:string) boolean
  }
  class DocometString {
    static escapeHtml(html:string) string
  }
  DocometError -- DocometColor
  DocometColor -- DocometClassMap
  DocometClassMap -- DocometString
  DocometCommander --> DocometError
  DocometCommander --> DocometClassMap
  DocometCommander --> DocometProcess
  DocometProcess --> DocometColor
  DocometProcess --> DocometError
  DocometStat --> DocometError

📋 Class Summary

{
  color: [class DocometColor] {
    propertyNames: [],
    accessorNames: [],
    methodNames: [
      'names',
      'set',
      'coloring'
    ]
  },
  commander: [class DocometCommander] {
    propertyNames: [],
    accessorNames: [
      'packageJson'
    ],
    methodNames: [
      'runAsync',
      'new'
    ]
  },
  error: [class DocometError] {
    propertyNames: [],
    accessorNames: [],
    methodNames: [
      'toErrorString'
    ]
  },
  path: [class DocometClassMap] {
    propertyNames: [],
    accessorNames: [
      'rootPath'
    ],
    methodNames: [
      'findUp',
      'exists',
      'doesNotExist',
      'absolute',
      'relative',
      'split',
      'splitPosix',
      'join',
      'joinPosix',
      'rebuild',
      'parse',
      'new'
    ]
  },
  process: [class DocometProcess] {
    propertyNames: [
      'logging'
    ],
    accessorNames: [],
    methodNames: [
      'setupErrorHandlers',
      'exit',
      'abort',
      'sleepAsync'
    ]
  },
  stat: [class DocometStat] {
    propertyNames: [],
    accessorNames: [],
    methodNames: [
      'getMtime',
      'needsUpdate',
      'checkMtime'
    ]
  },
  string: [class DocometString] {
    propertyNames: [],
    accessorNames: [],
    methodNames: [
      'escapeHtml'
    ]
  }
}

🤝 Contributing

Feel free to ask questions or consult on SNS.

📜 License

Apache-2.0

❤️ Acknowledgments

Developed with the support of Google AI Studio and Gemini CLI.

It is also supported by the power of wonderful open-source projects.

Heartfelt thanks to all maintainers and contributors.

Other Tools

| Tool Name | Overview | | :--- | :--- | | vhs | A tool for describing terminal operations in code (scripts) and generating high-quality GIF animations or videos. |