CLI Layer

Command-line interface parsing and action orchestration

Overview

The CLI layer is the entry point for mint-tsdocs, responsible for parsing user commands and initiating the documentation generation process. Built on @rushstack/ts-command-line, it provides a robust, typed command-line interface.

Entry Point: src/start.ts creates the CLI instance and runs the parser

Component Architecture

start.ts

The Executable Entry Point

src/start.ts

import { DocumenterCli } from './cli/ApiDocumenterCommandLine';

const parser: DocumenterCli = new DocumenterCli();
parser.executeAsync().catch(console.error);

Responsibilities:

• Display version banner
• Create CLI parser instance
• Execute command and handle errors

Execution Flow

Detailed Flow Breakdown

1. Command Invocation

User runs the command:

mint-tsdocs markdown -i ./temp -o ./docs/api --docs-json ./docs/docs.json

• Binary executes lib/start.js
• Version banner is displayed
• DocumenterCli instance is created

2. CLI Parsing

DocumenterCli.executeAsync() processes the command:

• Identifies action: markdown
• Validates required parameters
• Parses all flags and values
• Routes to MarkdownAction.onExecuteAsync()

3. API Model Building

BaseAction.buildApiModel() loads the API data:

const apiModel: ApiModel = new ApiModel();
const inputFolder = this._inputFolderParameter.value || './input';

// Find and load all *.api.json files
for (const filename of FileSystem.readFolderItemNames(inputFolder)) {
  if (filename.match(/\.api\.json$/i)) {
    apiModel.loadPackage(path.join(inputFolder, filename));
  }
}

// Apply @inheritDoc workarounds
this._applyInheritDoc(apiModel, apiModel);

return { apiModel, inputFolder, outputFolder };

4. Documenter Instantiation

MarkdownAction creates and configures the documenter:

const markdownDocumenter = new MarkdownDocumenter({
  apiModel,
  outputFolder,
  docsJsonPath: this._docsJsonParameter.value,
  tabName: this._tabNameParameter.value,
  groupName: this._groupParameter.value,
  enableMenu: this._menuParameter.value,
  convertReadme: this._readmeParameter.value,
  readmeTitle: this._readmeTitleParameter.value || 'README'
});

5. Generation Handoff

Control passes to the generation layer:

markdownDocumenter.generateFiles();

The CLI layer’s work is complete - the generation layer takes over.

Parameter Validation

The CLI layer ensures all parameters are valid before proceeding:

Input Folder Validation

const inputFolder = this._inputFolderParameter.value || './input';
if (!FileSystem.exists(inputFolder)) {
  throw new Error('The input folder does not exist: ' + inputFolder);
}

Error Handling

The CLI layer provides early validation to fail fast with clear error messages

Common errors caught at the CLI layer:

Error	Cause	Solution
Input folder not found	Invalid -i path	Verify path exists
No .api.json files	Wrong input folder	Run api-extractor first
Invalid docs.json	Malformed JSON	Validate JSON syntax
Permission denied	Output folder protected	Check file permissions

Extending the CLI

Adding a New Parameter

1. Define in Action

   this._myParameter = this.defineStringParameter({
     parameterLongName: '--my-option',
     argumentName: 'VALUE',
     description: 'My new option'
   });
   

2. Pass to Documenter

   const markdownDocumenter = new MarkdownDocumenter({
     // ... existing options
     myOption: this._myParameter.value
   });
   

3. Update Interface

   export interface IMarkdownDocumenterOptions {
     // ... existing properties
     myOption?: string;
   }
   

4. Use in Generation

   Use the new option in MarkdownDocumenter logic

Adding a New Command

To add a new command (e.g., yaml):

1. Create YamlAction.ts extending BaseAction
2. Implement onExecuteAsync()
3. Register in ApiDocumenterCommandLine._populateActions()

private _populateActions(): void {
  this.addAction(new MarkdownAction(this));
  this.addAction(new YamlAction(this));  // New command
}

Related Documentation

Generation Layer

See how the CLI hands off to the generation layer

Architecture Overview

Understand the full pipeline