docomet

☄️ 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

sample.js

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' ] }

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

Keyword	Description
TYPE	Type of operation to execute.
`(LANGUAGE)`	Language identifier for the code block.
`ARGS...`	Arguments required for `TYPE`. Possible values are explained 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 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 <<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>
  }
  class DocometError {
    deleteStack() DocometError
    static toErrorString(error:unknown) string
  }
  class DocometClassMap {
    base() string <<getter>>
    dir() string <<getter>>
    ext() string <<getter>>
    name() string <<getter>>
    static rootPath() string <<getter>>
    DocometClassMap(dir:string,name:string,ext:string) DocometClassMap
    toJSON() string
    toPosixString() string
    toString() string
    with(updates:Partial<#123;dir:string,ext:string,name:string#125;>) 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<void>
  }
  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.