V0.3

README.md

@@ -2,6 +2,8 @@
 
 [![NPM](https://img.shields.io/npm/v/plugin-atlas.svg?label=plugin-atlas)](https://www.npmjs.com/package/plugin-atlas) [![Downloads/week](https://img.shields.io/npm/dw/plugin-atlas.svg)](https://npmjs.org/package/plugin-atlas) [![License](https://img.shields.io/badge/License-BSD%203--Clause-brightgreen.svg)](https://raw.githubusercontent.com/salesforcecli/plugin-documentation/main/LICENSE.txt)
 
+<!-- tocstop -->
+
 ## Vision
 
 Atlas is a one-stop shop documentation toolkit for your Salesforce project. It uses all the information stored in your Salesforce metadata files and outputs all that information in a structured, user-readable form, in multiple formats.
@@ -98,28 +100,65 @@ Currently supported metadata types:
 
 <!-- commands -->
 
-- [`sf doc generate atlas`](#sf-doc-generate-atlas)
+- [`sf atlas generate csv`](#sf-atlas-generate-csv)
+- [`sf atlas generate xlsx`](#sf-atlas-generate-xlsx)
+
+## `sf atlas generate csv`
+
+Generate CSV files from the contents of your local project, with a separate file for each supported metadata type.
+
+```
+USAGE
+  $ sf atlas generate csv [--json] [-d <value>]
+
+FLAGS
+  -d, --output-dir=<value>  [default: PROJECT_FOLDER/atlas/csv/YYYYMMDD-HHMMSS/] Folder where the CSV files will be
+                            saved.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Generate CSV files from the contents of your local project, with a separate file for each supported metadata type.
+
+  You must run this command from within a project.
 
-## `sf doc generate atlas`
+EXAMPLES
+  $ sf atlas generate csv
 
-Generate documentation from the contents of your local project.
+FLAG DESCRIPTIONS
+  -d, --output-dir=<value>  Folder where the CSV files will be saved.
+
+    More information about a flag. Don't repeat the summary.
+```
+
+## `sf atlas generate xlsx`
+
+Generate an XLSX spreadsheet from the contents of your local project, with a sheet for each supported metadata type.
 
 ```
 USAGE
-  $ sf doc generate atlas [--json]
+  $ sf atlas generate xlsx [--json] [-f <value>]
+
+FLAGS
+  -f, --output-file=<value>  [default: PROJECT_FOLDER/atlas/xlsx/atlas-YYYYMMDD-HHMMSS.xlsx] Name and path of the XLSX
+                             file to be generated.
 
 GLOBAL FLAGS
   --json  Format output as json.
 
 DESCRIPTION
-  Generate documentation from the contents of your local project.
+  Generate an XLSX spreadsheet from the contents of your local project, with a sheet for each supported metadata type.
 
   You must run this command from within a project.
-  Note that the default behavior is to create an XLSX spreadsheet with a sheet for each supported metadata type. This
-  will change in an upcoming release.
 
 EXAMPLES
-  $ sf doc generate atlas
+  $ sf atlas generate xlsx
+
+FLAG DESCRIPTIONS
+  -f, --output-file=<value>  Name and path of the XLSX file to be generated.
+
+    More information about a flag. Don't repeat the summary.
 ```
 
 <!-- commandsstop -->

messages/atlas.generate.csv.md

@@ -0,0 +1,19 @@
+# summary
+
+Generate CSV files from the contents of your local project, with a separate file for each supported metadata type.
+
+# description
+
+You must run this command from within a project.
+
+# examples
+
+- <%= config.bin %> <%= command.id %>
+
+# flags.output-dir.summary
+
+Folder where the CSV files will be saved.
+
+# flags.output-dir.description
+
+More information about a flag. Don't repeat the summary.

messages/atlas.generate.xlsx.md

@@ -0,0 +1,19 @@
+# summary
+
+Generate an XLSX spreadsheet from the contents of your local project, with a sheet for each supported metadata type.
+
+# description
+
+You must run this command from within a project.
+
+# examples
+
+- <%= config.bin %> <%= command.id %>
+
+# flags.output-file.summary
+
+Name and path of the XLSX file to be generated.
+
+# flags.output-file.description
+
+More information about a flag. Don't repeat the summary.

package.json

@@ -1,25 +1,25 @@
 {
   "name": "plugin-atlas",
-  "description": "A Salesforce CLI plugin to generate documentation from metadata",
-  "version": "0.2.1",
+  "description": "A one-stop shop documentation toolkit for your Salesforce project.",
+  "version": "0.3.0",
   "dependencies": {
-    "@oclif/core": "^3.15.1",
-    "@salesforce/core": "^6.4.3",
-    "@salesforce/sf-plugins-core": "^5.0.13",
-    "@types/shelljs": "^0.8.15",
-    "@types/xml2js": "^0.4.14",
-    "arraysure": "^1.0.1",
+    "@oclif/core": "^3.16.0",
+    "@salesforce/core": "^6.4.4",
+    "@salesforce/sf-plugins-core": "^5.0.5",
+    "csv-writer": "^1.6.0",
     "exceljs": "^4.4.0",
-    "shelljs": "^0.8.5",
+    "glob": "^10.3.10",
     "xml2js": "^0.6.2"
   },
   "devDependencies": {
-    "@oclif/plugin-command-snapshot": "^5.0.5",
-    "@salesforce/cli-plugins-testkit": "^5.1.3",
+    "@oclif/plugin-command-snapshot": "^5.0.2",
+    "@salesforce/cli-plugins-testkit": "^5.1.4",
     "@salesforce/dev-scripts": "^7.1.1",
-    "@types/exceljs": "^1.3.0",
-    "eslint-plugin-sf-plugin": "^1.17.0",
-    "oclif": "^4.1.0",
+    "@types/cli-progress": "^3.11.5",
+    "@types/glob": "^8.1.0",
+    "@types/xml2js": "^0.4.14",
+    "eslint-plugin-sf-plugin": "^1.17.1",
+    "oclif": "^4.1.3",
     "shx": "0.3.4",
     "ts-node": "^10.9.2",
     "typescript": "^5.3.3"
@@ -51,11 +51,11 @@
       "@oclif/plugin-help"
     ],
     "topics": {
-      "doc": {
-        "description": "description for doc",
+      "atlas": {
+        "description": "description for atlas",
         "subtopics": {
           "generate": {
-            "description": "description for doc.generate"
+            "description": "description for atlas.generate"
           }
         }
       }
@@ -71,9 +71,9 @@
     "docs": "sf-docs",
     "format": "wireit",
     "lint": "wireit",
+    "postinstall": "yarn husky install",
     "postpack": "shx rm -f oclif.manifest.json oclif.lock",
     "prepack": "sf-prepack",
-    "prepare": "sf-install && yarn build",
     "test": "wireit",
     "test:nuts": "nyc mocha \"**/*.nut.ts\" --slow 4500 --timeout 600000 --parallel",
     "test:only": "wireit",
@@ -155,7 +155,7 @@
       "output": []
     },
     "test:command-reference": {
-      "command": "ts-node \"./bin/dev.js\" commandreference:generate --erroronwarnings",
+      "command": "\"./bin/dev\" commandreference:generate --erroronwarnings",
       "files": [
         "src/**/*.ts",
         "messages/**",
@@ -166,7 +166,7 @@
       ]
     },
     "test:deprecation-policy": {
-      "command": "ts-node \"./bin/dev.js\" snapshot:compare",
+      "command": "\"./bin/dev\" snapshot:compare",
       "files": [
         "src/**/*.ts"
       ],
@@ -176,7 +176,7 @@
       ]
     },
     "test:json-schema": {
-      "command": "ts-node \"./bin/dev.js\" schema:compare",
+      "command": "\"./bin/dev\" schema:compare",
       "files": [
         "src/**/*.ts",
         "schemas"

src/atlasCommand.ts

@@ -0,0 +1,41 @@
+import { mkdirSync } from 'node:fs';
+import * as path from 'node:path';
+import { SfProject } from '@salesforce/core';
+import { SfCommand } from '@salesforce/sf-plugins-core';
+import { getAllProjectFiles } from './util.js';
+import { MetadataReader } from './metadataReader/metadataReader.js';
+import { WriterType } from './writer/writer.js';
+import { TableWriter } from './writer/tableWriter/tableWriter.js';
+
+export abstract class AtlasCommand<T> extends SfCommand<T> {
+  protected projectPath: string = SfProject.getInstance().getPath();
+  protected allProjectFiles: string[] = [];
+  protected reader: MetadataReader = {} as MetadataReader;
+  protected tableWriter: TableWriter = {} as TableWriter;
+  protected writerType: WriterType = '' as WriterType;
+  protected targetPath: string = '';
+  protected pathTransform: (path: string | undefined) => string = {} as (path: string | undefined) => string;
+
+  protected createFolderStructure(): void {
+    let targetFolder = this.targetPath;
+
+    if (this.writerType === WriterType.XLSX) {
+      targetFolder = path.dirname(this.targetPath);
+    }
+
+    if (targetFolder) {
+      mkdirSync(targetFolder, { recursive: true });
+    }
+  }
+
+  protected async initialize(): Promise<void> {
+    this.allProjectFiles = await getAllProjectFiles(this.projectPath);
+    this.reader = new MetadataReader(this.allProjectFiles);
+    this.tableWriter = new TableWriter(this.reader.album, this.writerType);
+
+    if (this.targetPath === this.pathTransform(undefined)) {
+      this.targetPath = this.pathTransform(this.projectPath);
+    }
+    this.createFolderStructure();
+  }
+}

src/commands/atlas/generate/csv.ts

@@ -0,0 +1,47 @@
+import { Flags } from '@salesforce/sf-plugins-core';
+import { Messages } from '@salesforce/core';
+import { AtlasCommand } from '../../../atlasCommand.js';
+import { generateDefaultCsvDirname } from '../../../util.js';
+import { WriterType } from '../../../writer/writer.js';
+
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('plugin-atlas', 'atlas.generate.csv');
+
+export type AtlasGenerateCsvResult = {
+  path: string;
+};
+
+export default class AtlasGenerateCsv extends AtlasCommand<AtlasGenerateCsvResult> {
+  public static readonly summary = messages.getMessage('summary');
+  public static readonly description = messages.getMessage('description');
+  public static readonly examples = messages.getMessages('examples');
+
+  public static readonly flags = {
+    'output-dir': Flags.directory({
+      summary: messages.getMessage('flags.output-dir.summary'),
+      description: messages.getMessage('flags.output-dir.description'),
+      default: generateDefaultCsvDirname(),
+      aliases: ['dir'],
+      char: 'd',
+    }),
+  };
+
+  protected writerType = WriterType.CSV;
+
+  public async run(): Promise<AtlasGenerateCsvResult> {
+    const { flags } = await this.parse(AtlasGenerateCsv);
+
+    this.targetPath = flags['output-dir'];
+    this.pathTransform = generateDefaultCsvDirname;
+
+    await this.initialize();
+    await this.tableWriter.write(this.targetPath);
+
+    // TODO - move this text to the messages file
+    this.log('Output written to ' + this.targetPath);
+
+    return {
+      path: this.targetPath,
+    };
+  }
+}

src/commands/atlas/generate/xlsx.ts

@@ -0,0 +1,47 @@
+import { Flags } from '@salesforce/sf-plugins-core';
+import { Messages } from '@salesforce/core';
+import { generateDefaultXlsxFilename } from '../../../util.js';
+import { AtlasCommand } from '../../../atlasCommand.js';
+import { WriterType } from '../../../writer/writer.js';
+
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('plugin-atlas', 'atlas.generate.xlsx');
+
+export type AtlasGenerateXlsxResult = {
+  path: string;
+};
+
+export default class AtlasGenerateXlsx extends AtlasCommand<AtlasGenerateXlsxResult> {
+  public static readonly summary = messages.getMessage('summary');
+  public static readonly description = messages.getMessage('description');
+  public static readonly examples = messages.getMessages('examples');
+
+  public static readonly flags = {
+    'output-file': Flags.file({
+      summary: messages.getMessage('flags.output-file.summary'),
+      description: messages.getMessage('flags.output-file.description'),
+      default: generateDefaultXlsxFilename(),
+      aliases: ['file'],
+      char: 'f',
+    }),
+  };
+
+  protected writerType = WriterType.XLSX;
+
+  public async run(): Promise<AtlasGenerateXlsxResult> {
+    const { flags } = await this.parse(AtlasGenerateXlsx);
+
+    this.targetPath = flags['output-file'];
+    this.pathTransform = generateDefaultXlsxFilename;
+
+    await this.initialize();
+    await this.tableWriter.write(this.targetPath);
+
+    // TODO - move this text to the messages file
+    this.log('Output written to ' + this.targetPath);
+
+    return {
+      path: this.targetPath,
+    };
+  }
+}