feat: support no long description

Author: amphro

.prettierrc.json

@@ -0,0 +1 @@
+"@salesforce/prettier-config"

package.json

@@ -19,10 +19,11 @@
     "@oclif/plugin-help": "^2.2.3",
     "@oclif/test": "^1.2.5",
     "@salesforce/dev-scripts": "^0.4.2",
+    "@salesforce/prettier-config": "^0.0.1",
     "@semantic-release/changelog": "^5.0.0",
     "@semantic-release/git": "^9.0.0",
     "husky": "^4.2.3",
-    "salesforcedx": "^48.4.1",
+    "salesforcedx": "48.4.1",
     "semantic-release": "^17.0.4"
   },
   "engines": {

src/ditamap/command.ts

@@ -6,9 +6,8 @@
  */
 
 import { asString, Dictionary, ensureJsonMap, ensureObject, ensureString, JsonMap } from '@salesforce/ts-types';
-import chalk = require('chalk');
 import { join } from 'path';
-import { events } from '../utils';
+import { punctuate } from '../utils';
 import { Ditamap } from './ditamap';
 
 export class Command extends Ditamap {
@@ -24,12 +23,7 @@ export class Command extends Ditamap {
       .filter(([, flag]) => !flag.hidden)
       .map(([flagName, flag]) => {
         if (!flag.longDescription) {
-          events.emit(
-            'warning',
-            `No flag longDescription for command "${chalk.bold(command.id)}" on flag "${chalk.bold(
-              flagName
-            )}". That command owner must add the longDescription to the flag definition.`
-          );
+          flag.longDescription = punctuate(flag.description);
         }
         return Object.assign(flag, {
           name: flagName,
@@ -49,12 +43,7 @@ export class Command extends Ditamap {
     }
 
     if (!command.longDescription) {
-      events.emit(
-        'warning',
-        `No longDescription for command ${chalk.bold(
-          command.id
-        )}. That command owner must add the longDescription to the command definition.`
-      );
+      command.longDescription = punctuate(asString(command.description));
     }
 
     let fullName: string;

src/ditamap/main-topic-intro.ts

@@ -5,10 +5,9 @@
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
-import { ensureJsonMap, JsonMap } from '@salesforce/ts-types';
-import chalk = require('chalk');
+import { asString, ensureJsonMap, JsonMap } from '@salesforce/ts-types';
 import { join } from 'path';
-import { events } from '../utils';
+import { punctuate } from '../utils';
 import { Ditamap } from './ditamap';
 
 export class MainTopicIntro extends Ditamap {
@@ -24,17 +23,12 @@ export class MainTopicIntro extends Ditamap {
     }
 
     if (!subTopicMeta.longDescription && !subTopicMeta.external) {
-      events.emit(
-        'warning',
-        `No long description for topic ${chalk.bold(
-          topic + ':' + subtopic
-        )}. That topic owner must add a longDescription to the topic metadata in the oclif section in the package.json file within their plugin.`
-      );
+      subTopicMeta.longDescription = punctuate(asString(subTopicMeta.description));
     }
 
     super(filename, {
       topic: subtopic,
-      longDescription: subTopicMeta.longDescription || subTopicMeta.description,
+      longDescription: subTopicMeta.longDescription,
       isOpenPilotTopic: subTopicMeta.state === 'openPilot',
       isClosedPilotTopic: subTopicMeta.state === 'closedPilot',
       isBetaTopic: subTopicMeta.state === 'beta',

src/docs.ts

@@ -26,7 +26,7 @@ import { Command } from './ditamap/command';
 import { MainTopicIntro } from './ditamap/main-topic-intro';
 import { SubTopicDitamap } from './ditamap/subtopic-ditamap';
 import { TopicDitamap } from './ditamap/topic-ditamap';
-import { copyStaticFile, events } from './utils';
+import { copyStaticFile, events, punctuate } from './utils';
 
 const templatesDir = join(__dirname, '..', 'templates');
 
@@ -46,25 +46,23 @@ export class Docs {
   }
 
   public async populateTopic(topic: string, subtopics: Dictionary<Dictionary | Dictionary[]>) {
-    const topicMeta = ensureJsonMap(this.topicMeta[topic]);
+    const topicMeta = ensureJsonMap(
+      this.topicMeta[topic],
+      `No topic meta for ${topic} - add this topic to the oclif section of the package.json.`
+    );
     let description = asString(topicMeta.longDescription);
     if (!description && !topicMeta.external) {
-      description = asString(topicMeta.description);
+      // Punctuate the description in place of longDescription
+      description = punctuate(asString(topicMeta.description));
       if (!description) {
         events.emit(
           'warning',
-          `No longDescription for topic ${chalk.bold(
+          `No description for topic ${chalk.bold(
             topic
           )}. Skipping until topic owner adds topic metadata, that includes longDescription, in the oclif section in the package.json file within their plugin.`
         );
         return;
       }
-      events.emit(
-        'warning',
-        `No longDescription for topic ${chalk.bold(
-          topic
-        )} but found description. Still generating but topic owner must add topic metadata, that includes longDescription, in the oclif section in the package.json file within their plugin.`
-      );
     }
     await new CLIReferenceTopic(topic, description).write();
 
@@ -229,7 +227,7 @@ export class Docs {
           // Since there is no command meta, just use the command description since that is what oclif does.
           if (!commandMeta.description) {
             commandMeta.description = command.description;
-            commandMeta.longDescription = command.longDescription;
+            commandMeta.longDescription = command.longDescription || punctuate(command.description);
           }
         }
       }

src/utils.ts

@@ -9,6 +9,7 @@ import { fs } from '@salesforce/core';
 import { Dictionary, isObject } from '@salesforce/ts-types';
 import { EventEmitter } from 'events';
 import { copyFileSync } from 'fs';
+import { EOL } from 'os';
 import { join } from 'path';
 
 export const events = new EventEmitter();
@@ -30,3 +31,17 @@ export function mergeDeep(target: Dictionary, source: Dictionary) {
   });
   return target;
 }
+
+export function punctuate(description: string): string {
+  if (!description) return description;
+
+  const lines = description.split(EOL);
+  let mainDescription = lines[0];
+
+  mainDescription = mainDescription.charAt(0).toUpperCase() + mainDescription.substring(1);
+
+  if (mainDescription.charAt(mainDescription.length - 1) !== '.') {
+    mainDescription += '.';
+  }
+  return [mainDescription, ...lines.slice(1)].join(EOL);
+}

test/utils.test.ts

@@ -6,7 +6,8 @@
  */
 
 import { expect } from 'chai';
-import { mergeDeep } from '../src/utils';
+import { EOL } from 'os';
+import { punctuate, mergeDeep } from '../src/utils';
 
 it('merge two shallow objects', () => {
   expect(mergeDeep({ a: 1 }, { b: 2 })).to.deep.equal({ a: 1, b: 2 });
@@ -37,3 +38,19 @@ it('merge two deeply nested objects', () => {
     }
   });
 });
+
+describe('punctuate', () => {
+  it('description to longDescription', () => {
+    expect(punctuate('lowercase oclif description')).to.equal('Lowercase oclif description.');
+  });
+
+  it('multi line descriptions to longDescriptions', () => {
+    expect(punctuate(`lowercase oclif description${EOL}${EOL}some other stuff`)).to.equal(
+      `Lowercase oclif description.${EOL}${EOL}some other stuff`
+    );
+  });
+
+  it('does not add additional punctuation', () => {
+    expect(punctuate('Uppercase longDescription.')).to.equal('Uppercase longDescription.');
+  });
+});