Add extension documentation

.github/workflows/release.yml

@@ -192,4 +192,4 @@ jobs:
       - name: Update v2-latest using rdme
         uses: readmeio/rdme@7.3.0
         with:
-          rdme: docs ./docs --key=${{ secrets.README_API }} --version=2-latest
+          rdme: docs ./docs/*/* --key=${{ secrets.README_API }} --version=2-latest

cli/src/commands/extensions/api.rs

@@ -20,7 +20,7 @@ use tokio::sync::Mutex;
 
 use crate::api::PhylumApi;
 use crate::auth::UserInfo;
-use crate::commands::parse::{get_packages_from_lockfile, LOCKFILE_PARSERS};
+use crate::commands::parse::{self, get_packages_from_lockfile, LOCKFILE_PARSERS};
 use crate::config::get_current_project;
 
 /// Holds either an unawaited, boxed `Future`, or the result of awaiting the
@@ -223,7 +223,18 @@ async fn get_package_details(
 /// Parse a lockfile and return the package descriptors contained therein.
 /// Equivalent to `phylum parse`.
 #[op]
-async fn parse_lockfile(lockfile: String, lockfile_type: String) -> Result<Vec<PackageDescriptor>> {
+async fn parse_lockfile(
+    lockfile: String,
+    lockfile_type: Option<String>,
+) -> Result<Vec<PackageDescriptor>> {
+    // Fallback to automatic parser without lockfile type specified.
+    let lockfile_type = match lockfile_type {
+        Some(lockfile_type) => lockfile_type,
+        None => return Ok(parse::get_packages_from_lockfile(&Path::new(&lockfile))?.0),
+    };
+
+    // Attempt to parse as requested lockfile type.
+
     let parser = LOCKFILE_PARSERS
         .iter()
         .find_map(|(name, parser)| (*name == lockfile_type).then(|| *parser))

cli/src/commands/extensions/mod.rs

@@ -31,7 +31,7 @@ console.log('Hello, World!');
 
 pub fn command<'a>() -> Command<'a> {
     Command::new("extension")
-        .about("Run extensions")
+        .about("Manage extensions")
         .subcommand(
             Command::new("install")
                 .about("Install extension")

cli/src/extension_api.ts

@@ -1,15 +1,33 @@
 export class PhylumApi {
     /// Analyze dependencies in a lockfile.
     ///
-    /// Returns the Job ID, which can later be queried with `getJobStatus`.
-    ///
     /// This expects a `.phylum_project` file to be present if the `project`
     /// parameter is undefined.
+    ///
+    /// # Returns
+    ///
+    /// Analyze Job ID, which can later be queried with `getJobStatus`.
     static async analyze(lockfile: string, project?: string, group?: string): string {
         return await Deno.core.opAsync('analyze', lockfile, project, group);
     }
 
     /// Get info about the logged in user.
+    ///
+    /// # Returns
+    ///
+    /// Object containing user information:
+    ///
+    /// ```
+    /// {
+    ///   email: "user@phylum.io",
+    ///   sub: "af8b5c32-9966-496a-e5ae-9ca9ceb43294",
+    ///   name: "John Doe",
+    ///   given_name: "John",
+    ///   family_name: "Doe",
+    ///   preferred_username: "JD",
+    ///   email_verified: true,
+    /// }
+    /// ```
     static async getUserInfo(): object {
         return await Deno.core.opAsync('get_user_info');
     }
@@ -25,6 +43,54 @@ export class PhylumApi {
     }
 
     /// Get job results.
+    ///
+    /// # Returns
+    ///
+    /// Job analysis results:
+    ///
+    /// ```
+    /// {
+    ///   job_id: "de2d74b1-3925-4de9-9b8f-0c7b27f9b3c8",
+    ///   ecosystem: "npm",
+    ///   user_id: "0f2a8e3d-9f75-49fa-89c7-718c4f87fc93",
+    ///   user_email: "",
+    ///   created_at: 1657106760573,
+    ///   status: "complete",
+    ///   score: 1,
+    ///   pass: true,
+    ///   msg: "Project met threshold requirements",
+    ///   action: "none",
+    ///   num_incomplete: 0,
+    ///   last_updated: 1657106760573,
+    ///   project: "02a8dcdd-69bd-469f-8c39-be76c786fd2b",
+    ///   project_name: "api-docs",
+    ///   label: "uncategorized",
+    ///   thresholds: { author: 0, engineering: 0, license: 0, malicious: 0, total: 0, vulnerability: 0 },
+    ///   packages: [
+    ///     {
+    ///       name: "typescript",
+    ///       version: "4.7.4",
+    ///       status: "complete",
+    ///       last_updated: 1657106208802,
+    ///       license: "Apache-2.0",
+    ///       package_score: 1,
+    ///       num_dependencies: 0,
+    ///       num_vulnerabilities: 0,
+    ///       type: "npm",
+    ///       riskVectors: {
+    ///         author: 1,
+    ///         vulnerabilities: 1,
+    ///         total: 1,
+    ///         engineering: 1,
+    ///         malicious_code: 1,
+    ///         license: 1
+    ///       },
+    ///       dependencies: {},
+    ///       issues: []
+    ///     }
+    ///   ]
+    /// }
+    /// ```
     static async getJobStatus(jobId: string): object {
         return await Deno.core.opAsync('get_job_status', jobId);
     }
@@ -33,6 +99,20 @@ export class PhylumApi {
     ///
     /// This expects a `.phylum_project` file to be present if the `project`
     /// parameter is undefined.
+    ///
+    /// # Returns
+    ///
+    /// Project details:
+    ///
+    /// ```
+    /// {
+    ///   name: "integration-tests",
+    ///   id: "c61344f2-b9c9-44c6-adbb-f4b33dd890bd",
+    ///   ecosystem: "npm",
+    ///   thresholds: { author: 0, engineering: 0, license: 0, malicious: 0, total: 0, vulnerability: 0 },
+    ///   jobs: []
+    /// }
+    /// ```
     static async getProjectDetails(projectName?: string): object {
         return await Deno.core.opAsync('get_project_details', projectName);
     }
@@ -41,12 +121,72 @@ export class PhylumApi {
     ///
     /// This will not start a new package analysis, but only retrieve previous
     /// analysis results.
+    ///
+    /// # Returns
+    ///
+    /// Package analysis results:
+    ///
+    /// ```
+    /// {
+    ///   id: "npm:typescript:4.7.4",
+    ///   name: "typescript",
+    ///   version: "4.7.4",
+    ///   registry: "npm",
+    ///   publishedDate: "2022-06-17T18:21:36+00:00",
+    ///   latestVersion: null,
+    ///   versions: [
+    ///     { version: "4.5.4", total_risk_score: 1 },
+    ///     { version: "3.9.7", total_risk_score: 1 },
+    ///     { version: "4.2.4", total_risk_score: 1 }
+    ///   ],
+    ///   description: "TypeScript is a language for application scale JavaScript development",
+    ///   license: "Apache-2.0",
+    ///   depSpecs: [],
+    ///   dependencies: [],
+    ///   downloadCount: 134637844,
+    ///   riskScores: {
+    ///     total: 1,
+    ///     vulnerability: 1,
+    ///     malicious_code: 1,
+    ///     author: 1,
+    ///     engineering: 1,
+    ///     license: 1
+    ///   },
+    ///   totalRiskScoreDynamics: null,
+    ///   issuesDetails: [],
+    ///   issues: [],
+    ///   authors: [],
+    ///   developerResponsiveness: {
+    ///     open_issue_count: 0,
+    ///     total_issue_count: 0,
+    ///     open_issue_avg_duration: null,
+    ///     open_pull_request_count: 0,
+    ///     total_pull_request_count: 0,
+    ///     open_pull_request_avg_duration: null
+    ///   },
+    ///   issueImpacts: { low: 0, medium: 0, high: 0, critical: 0 },
+    ///   complete: true
+    /// }
+    /// ```
     static async getPackageDetails(name: string, version: string, packageType: string): object {
         return await Deno.core.opAsync('get_package_details', name, version, packageType);
     }
 
     /// Get dependencies inside a lockfile.
-    static async parseLockfile(lockfile: string, lockfileType: string): [object] {
+    ///
+    /// # Returns
+    ///
+    /// List of dependencies:
+    ///
+    /// ```
+    /// [
+    ///   { name: "accepts", version: "1.3.8", type: "npm" },
+    ///   { name: "ms", version: "2.0.0", type: "npm" },
+    ///   { name: "negotiator", version: "0.6.3", type: "npm" },
+    ///   { name: "ms", version: "2.1.3", type: "npm" }
+    /// ]
+    /// ```
+    static async parseLockfile(lockfile: string, lockfileType?: string): [object] {
         return await Deno.core.opAsync('parse_lockfile', lockfile, lockfileType);
     }
 }

docs/phylum_analyze.md → docs/command_line_tool/phylum_analyze.md

@@ -33,6 +33,7 @@ phylum analyze [OPTIONS] <lockfile>
 &emsp; Increase verbosity of API response
 
 ### Examples
+
 ```sh
 # Analyze an npm lock file
 $ phylum analyze package-lock.json

docs/command_line_tool/phylum_extension.md

@@ -0,0 +1,18 @@
+---
+title: phylum extension
+category: 6255e67693d5200013b1fa41
+hidden: true
+---
+
+Manage extensions
+
+```
+phylum extension [SUBCOMMAND]
+```
+
+### Subcommands
+
+* [list](https://docs.phylum.io/docs/phylum_extension_list)
+* [new](https://docs.phylum.io/docs/phylum_extension_new)
+* [install](https://docs.phylum.io/docs/phylum_extension_install)
+* [uninstall](https://docs.phylum.io/docs/phylum_extension_uninstall)

docs/phylum_extension_add.md → docs/command_line_tool/phylum_extension_install.md

@@ -1,18 +1,27 @@
 ---
-title: phylum extension add
+title: phylum extension install
 category: 6255e67693d5200013b1fa3e
 hidden: true
 ---
-To install an extension, run the following command:
+
+Install an extension
 
 ```sh
-phylum extension add path/to/extension
+phylum extension add [OPTIONS] <PATH>
 ```
 
-The extension will be installed under `$XDG_DATA_HOME/phylum/extensions/<ext_name>`.
-If `$XDG_DATA_HOME` is not set, it will default to `$HOME/.local/share/phylum/extensions/<ext_name>`.
+### Options
+
+`-y`, `--yes`
+&emsp; Automatically accept requested permissions
+
+### Details
+
+The extension will be installed under `$XDG_DATA_HOME/phylum/extensions/<EXT_NAME>`.
+If `$XDG_DATA_HOME` is not set, it will default to `$HOME/.local/share/phylum/extensions/<EXT_NAME>`.
+
 Once installed, the extension will be accessible via the Phylum CLI:
 
 ```sh
-phylum <ext_name> [arguments...]
+phylum <EXT_NAME> [OPTIONS]...
 ```

docs/phylum_extension_list.md → docs/command_line_tool/phylum_extension_list.md

@@ -3,7 +3,8 @@ title: phylum extension list
 category: 6255e67693d5200013b1fa3e
 hidden: true
 ---
-To list the currently installed extensions, run the following command:
+
+List installed extensions
 
 ```sh
 phylum extension list

docs/command_line_tool/phylum_extension_uninstall.md

@@ -0,0 +1,11 @@
+---
+title: phylum extension uninstall
+category: 6255e67693d5200013b1fa3e
+hidden: true
+---
+
+Uninstall extension
+
+```sh
+phylum extension uninstall <NAME>
+```

docs/extensions/api.md

@@ -0,0 +1,31 @@
+---
+title: Extension API
+category: 62c5cb137dbdad00536291a6
+hidden: true
+---
+
+Since CLI extensions are built on top of the Deno runtime, they have access to
+two different APIs; the Deno API and the Phylum API.
+
+## Deno API
+
+Deno's API is built into the Deno runtime, providing access to all external
+interfaces like Network, Disk, or the terminal console. All available
+functionality is documented in [Deno's API docs]. This functionality is
+available to all extensions without any imports.
+
+Additionally, Deno also provides a complementary standard library. This includes
+utility functions for several commonly used structures like collections, http,
+and async. These modules can be imported using the URLs documented in Deno's
+standard library documentation or by downloading them and including individual
+modules as files. All standard library functionality is documented in [Deno's
+standard library docs]
+
+[Deno's API docs]: https://doc.deno.land/deno/stable
+[Deno's standard library docs]: https://deno.land/std
+
+## Phylum API
+
+The Phylum extension API is documented in the [TypeScript module file].
+
+[TypeScript module file]: ./cli/src/extension_api.ts