☄️ docomet - Documentation updates at comet speed.

| Feature Name | Development Motivation | Solution | | :--- | :--- | :--- | | Inspectable | I want to check static properties and method names by specifying a class in console.log() in the REPL. | Provides a dedicated class that organizes and outputs the internal structure just by inheriting it. | | MtimeCheck | I want to prevent "Update omissions" where the translation source file is updated but the translation destination remains old. | Provides a dedicated method/class/command to determine if an update is necessary by comparing the modification dates of two files. | | Replace | I want to easily update the execution results of commands in a file to the latest state. | Provides a dedicated method/class/command to replace content with the execution results of commands within comment tags. | | ClassMap | I want to easily visualize class relationships using mermaid. | Provides a dedicated method/class/command to generate mermaid format text from TSDoc. |

🚀 Installation

pnpm install docomet

💖 Quick Start

docomet focuses on "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 destination newer file path does not exist. |

Replace

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

Example command to replace by executing 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 in the file content. | | Log | Replaced: {path} | Replaced with new content because there is a difference in the file content. | | Error | Unexpected: {tag} | The tag does not match. | | Error | Unclosed: {tag} | There is no closing tag. |

Basic Syntax

Analyzes and executes custom 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 -->

| Keyword | Description | | :--- | :--- | | TYPE | The type of operation to execute. | | (LANGUAGE) | The language identifier for the code block. | | ARGS... | Arguments required for TYPE.Specifiable values are described along with 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 of 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
  namespace base {
    class DocometBuffer {
    }
    class DocometCount {
      static * down(count:number,start?:number) Generator<number>$
      static * up(count:number,start:number) Generator<number>$
    }
    class DocometEncoding {
      static readonly utf8 : string$
      static decode(buffer:DocometBuffer) string$
      static detectEncoding(buffer:DocometBuffer) string$
    }
    class DocometError {
      DocometError(...args:[message?:string,options?:ErrorOptions]) DocometError
      toJSON() string
      static new(...args:[message?:string,options?:ErrorOptions]) DocometError$
      static normalize(error:unknown) Error$
      static stringify(error:unknown) string$
    }
    class DocometStream {
      static async readAsync(stream:Readable) Promise<string>$
      static readLineAsync(stream:Readable,encoding:string) AsyncGenerator<string>$
      static async readLinesAsync(stream:Readable,encoding:string) Promise<string[]>$
      static async toBufferAsync(stream:Readable) Promise<DocometBuffer>$
    }
    class DocometString {
      static async detectEncodingAsync(string:string) Promise<string>$
      static escapeHtml(html:string) string$
      static joinLines(lines:string[],separator:string) string$
      static replace(string:string,map:DocometStringReplaceMap) string$
      static async splitLinesAsync(string:string,encoding:string) Promise<string[]>$
    }
  }
  namespace cli {
    class DocometCommander {
      baseCommandName() string <<getter>>
      command() Command <<getter>>
      static packageJson() DocometCommanderPackageJson <<getter>>$
      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<void>$
    }
  }
  namespace system {
    class DocometColor {
      static coloring(colorName:string,message:string) string$
      static names() string[]$
      static set(colorName:string,newFormatter:DocometColorFormatter) DocometColorFormatter$
    }
    class DocometDir {
      static async changeAsync(path:string,callback:DocometDirChangeCallback) Promise<void>$
    }
    class DocometFile {
      absolutePath() string <<getter>>
      path() DocometPath <<getter>>
      DocometFile(path:string) DocometFile
      read() string
      async readAsync() Promise<string>
      readLineAsync(size?:number) AsyncGenerator<string>
      async readLinesAsync(size?:number) Promise<string[]>
      toJSON() string
      toString() string
      async writeAsync(data:string|Uint8Array<ArrayBufferLike>|Readable) Promise<void>
      static async detectEncodingAsync(path:string) Promise<string>$
      static new(...args:[path:string]) DocometFile$
    }
    class DocometPath {
      base() string <<getter>>
      dir() string <<getter>>
      ext() string <<getter>>
      name() string <<getter>>
      static rootPath() string <<getter>>$
      DocometPath(dir:string,name?:string,ext?:string) DocometPath
      toJSON() string
      toPosixString() string
      toString() string
      with(updates:Partial<#123;dir:string,ext:string,name:string#125;>) DocometPath
      static absolute(path:string) string$
      static cwd() string$
      static doesNotExist(path:string) boolean$
      static exists(path:string) boolean$
      static findUp(name:string,startPath:string) string|undefined$
      static glob(patterns:string|string[],options?:Options) string[]|Entry[]$
      static async globAsync(patterns:string|string[],options?:Options) Promise<string[]|Entry[]>$
      static join(...paths:string[]) string$
      static joinPosix(...paths:string[]) string$
      static new(...args:[dir:string,name?:string,ext?:string]) DocometPath$
      static normalize(path:string) string$
      static parse(path:string) DocometPath$
      static rebuild(path:string,split:DocometPathSplit,join:DocometPathJoin) string$
      static relative(toPath:string,fromPath: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 getStdin(isTTY:boolean) Readable|undefined$
      static setupErrorHandlers() void$
    }
    class DocometStat {
      static checkMtime(olderPath:string,newerPath:string) void$
      static getMtime(path:string) Date|undefined$
      static needsUpdate(olderPath:string,newerPath:string) boolean$
    }
  }
  DocometBuffer -- DocometCount
  DocometStream --> DocometBuffer
  DocometStream --> DocometEncoding
  DocometString --> DocometEncoding
  DocometString --> DocometStream
  DocometCommander --> DocometError
  DocometCommander --> DocometFile
  DocometCommander --> DocometPath
  DocometCommander --> DocometProcess
  DocometDir --> DocometError
  DocometDir --> DocometPath
  DocometFile --> DocometEncoding
  DocometFile --> DocometPath
  DocometFile --> DocometStream
  DocometProcess --> DocometColor
  DocometProcess --> DocometError
  DocometProcess --> DocometStream
  DocometStat --> DocometError
  DocometStat --> DocometPath

📋 Class Summary

{
  base: {
    buffer: [class DocometBuffer] {
      propertyNames: [],
      accessorNames: [],
      methodNames: []
    },
    count: [class DocometCount] {
      propertyNames: [],
      accessorNames: [],
      methodNames: [
        'up',
        'down'
      ]
    },
    encoding: [class DocometEncoding] {
      propertyNames: [
        'utf8'
      ],
      accessorNames: [],
      methodNames: [
        'detectEncoding',
        'decode'
      ]
    },
    error: [class DocometError] {
      propertyNames: [],
      accessorNames: [],
      methodNames: [
        'stringify',
        'normalize',
        'new'
      ]
    },
    stream: [class DocometStream] {
      propertyNames: [],
      accessorNames: [],
      methodNames: [
        'toBufferAsync',
        'readLineAsync',
        'readLinesAsync',
        'readAsync'
      ]
    },
    string: [class DocometString] {
      propertyNames: [],
      accessorNames: [],
      methodNames: [
        'detectEncodingAsync',
        'replace',
        'escapeHtml',
        'splitLinesAsync',
        'joinLines'
      ]
    }
  },
  cli: {
    commander: [class DocometCommander] {
      propertyNames: [],
      accessorNames: [
        'packageJson'
      ],
      methodNames: [
        'runAsync',
        'new'
      ]
    }
  },
  system: {
    color: [class DocometColor] {
      propertyNames: [],
      accessorNames: [],
      methodNames: [
        'names',
        'set',
        'coloring'
      ]
    },
    dir: [class DocometDir] {
      propertyNames: [],
      accessorNames: [],
      methodNames: [
        'changeAsync'
      ]
    },
    file: [class DocometFile] {
      propertyNames: [],
      accessorNames: [],
      methodNames: [
        'detectEncodingAsync',
        'new'
      ]
    },
    path: [class DocometPath] {
      propertyNames: [],
      accessorNames: [
        'rootPath'
      ],
      methodNames: [
        'cwd',
        'findUp',
        'exists',
        'doesNotExist',
        'absolute',
        'relative',
        'normalize',
        'split',
        'splitPosix',
        'join',
        'joinPosix',
        'rebuild',
        'globAsync',
        'glob',
        'parse',
        'new'
      ]
    },
    process: [class DocometProcess] {
      propertyNames: [
        'logging'
      ],
      accessorNames: [],
      methodNames: [
        'setupErrorHandlers',
        'exit',
        'abort',
        'getStdin'
      ]
    },
    stat: [class DocometStat] {
      propertyNames: [],
      accessorNames: [],
      methodNames: [
        'getMtime',
        'needsUpdate',
        'checkMtime'
      ]
    }
  }
}

🤝 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.

Also supported by the power of wonderful open-source projects.

I sincerely thank all maintainers and contributors.

Other Tools

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