docs: add docstrings

Co-authored-by: Copilot <copilot@github.com>

Author: MichaelCurrin

src/cli/diffIndexGenerate.ts

@@ -18,6 +18,15 @@ Options:
   --verbose       Show debug output for this run.
 `;
 
+/**
+ * Get the current repository by running git command.
+ *
+ * Executes git command to determine the root directory of the current Git
+ * repository.
+ *
+ * @returns A Repository object with the root URI of the current Git repository.
+ * @throws Error if not in a Git repository or if the git command fails.
+ */
 function _getCurrentRepository(): Repository {
   return {
     rootUri: {

src/cli/diffIndexGenerateCommit.ts

@@ -21,7 +21,14 @@ Options:
 `;
 
 /**
- * Command-line entry-point.
+ * Generate a commit message and execute a Git commit with that message.
+ *
+ * Steps:
+ *   1. Check Git changes and generate a commit message.
+ *   2. Run `git commit` with the generated message.
+ *   3. On failure, retry with current directory specified.
+ *
+ * @param argv Command-line arguments.
  */
 async function main(argv: string[]): Promise<void> {
   if (shouldShowHelp(argv)) {

src/cli/generate.ts

@@ -11,6 +11,8 @@
  */
 import { generateMsg } from "../prepareCommitMsg";
 
+import { shouldShowHelp } from "./utils";
+
 const HELP_TEXT: string = `Usage: auto_commit_msg_generate DIFF_INDEX_OUTPUT
 
 Generate a commit message from given input.
@@ -22,14 +24,15 @@ Options:
   --help, -h            Show this help and exit.`;
 
 /**
- * Command-line entry-point.
+ * Generate a commit message from Git diff-index output.
  *
- * Returns a suitable generated commit message as text.
- */
-import { shouldShowHelp } from "./utils";
-
-/**
- * Entry-point for the CLI. Handles help flag and input validation.
+ * Parses the provided diff-index output and generates a suitable commit message.
+ * Throws an error if no arguments or no changes are found.
+ *
+ * @param args Command-line arguments. First argument should be the diff-index
+ *   output.
+ * @throws Error if no arguments provided or no file changes found in the
+ *   output.
  */
 function main(args: string[]): void {
   if (shouldShowHelp(args)) {

src/cli/utils.ts

@@ -6,8 +6,7 @@
  * Determine whether help should be displayed.
  *
  * @param argv Command-line arguments passed to the CLI.
- *
- * @returns boolean True when `--help` or `-h` is present.
+ * @returns True when `--help` or `-h` is present in the arguments.
  */
 export function shouldShowHelp(argv: string[]): boolean {
   return argv.includes("--help") || argv.includes("-h");

src/extension.ts

@@ -9,6 +9,12 @@ import { API, Repository } from "./api/git";
 import { makeAndFillCommitMsg } from "./autofill";
 import { getGitExtension } from "./gitExtension";
 
+/**
+ * Validate that the Git extension is available and at least one repository is open.
+ *
+ * @param git The Git extension API object.
+ * @throws Error if Git extension is not available or no repositories are found.
+ */
 function _validateFoundRepos(git: API) {
   let msg = "";
 

src/generate/convCommit.ts

@@ -52,12 +52,15 @@ export class ConventionalCommit {
   }
 
   /**
-   * Check if doc-related.
+   * Check if a file is documentation-related.
    *
-   * Return true for `.rst`, README files, and anything in the docs directory.
+   * Return true for `.rst` files, README files, and anything in the docs
+   * directory.
    *
    * TODO: For static sites, not all `.md` files are docs but that could be
    * configured with a global flag. Or recognize presence of Jekyll config file.
+   *
+   * @returns True if the file is documentation-related, false otherwise.
    */
   isDocsRelated(): boolean {
     if (this.extension === ".rst") {
@@ -68,6 +71,14 @@ export class ConventionalCommit {
     return DOC_NAMES.includes(lowerName) || this.dirPath.startsWith("docs");
   }
 
+  /**
+   * Check if a file is test-related.
+   *
+   * Returns true for files in test directories (at any nesting level) or
+   * matching test-related file patterns.
+   *
+   * @returns True if the file is test-related, false otherwise.
+   */
   isTestRelated(): boolean {
     const dir = this.dirPath;
     const name = this.name;
@@ -102,17 +113,29 @@ export class ConventionalCommit {
     return false;
   }
 
+  /**
+   * Check if a file is CI/CD configuration-related.
+   *
+   * Returns true for files in CI directories or matching CI configuration file
+   * names.
+   *
+   * @returns True if the file is CI/CD related, false otherwise.
+   */
   isCIRelated(): boolean {
     // Assume flat structure and don't check for nesting in subdirs of
     // `CI_DIRS`.
     return CI_DIRS.includes(this.dirPath) || CI_NAMES.includes(this.name);
   }
 
-  // Broadly match eslint configs with any extension e.g. `.json` or `.yml`.
-  // See https://eslint.org/docs/user-guide/configuring
-  // Same for prettier configs https://prettier.io/docs/en/configuration.html
-  // And `tslint*` as JSON or YAML and `webpack*`.
-  // See https://github.com/vscode-icons/vscode-icons/blob/master/src/iconsManifest/supportedExtensions.ts
+  /**
+   * Check if a file is configuration-related.
+   *
+   * Matches ESLint, Prettier, TSLint, Webpack configs and other configuration
+   * files with various extensions. See https://eslint.org/docs/user-guide/configuring
+   * and https://prettier.io/docs/en/configuration.html for more details.
+   *
+   * @returns True if the file is configuration-related, false otherwise.
+   */
   isConfigRelated(): boolean {
     return (
       CONFIG_EXTENSIONS.includes(this.extension) ||
@@ -127,31 +150,54 @@ export class ConventionalCommit {
     );
   }
 
+  /**
+   * Check if a file is package management-related.
+   *
+   * @returns True if the file is a package manifest file, false otherwise.
+   */
   isPackageRelated(): boolean {
     return PACKAGE_NAMES.includes(this.name);
   }
 
+  /**
+   * Check if a file is build-related.
+   *
+   * @returns True if the file is a build tool configuration or artifact, false
+   *   otherwise.
+   */
   isBuildRelated(): boolean {
     return (
       BUILD_NAMES.includes(this.name) ||
       BUILD_EXTENSIONS.includes(this.extension)
     );
   }
 
+  /**
+   * Check if a file is license-related.
+   *
+   * @returns True if the file is a license file, false otherwise.
+   */
   isLicenseRelated(): boolean {
     return LICENSE_NAMES.includes(this.name);
   }
 
+  /**
+   * Check if a file is chore-related (license or configuration files).
+   *
+   * @returns True if the file is license or configuration-related, false
+   *   otherwise.
+   */
   isChoreRelated(): boolean {
     return this.isLicenseRelated() || this.isConfigRelated();
   }
 
   /**
-   * Return Conventional Commit type.
+   * Determine the Conventional Commit type for this file based on its path and content.
    *
-   * Order of checks is important here.
+   * Order of checks is important here: CI, package management, build, chore,
+   * documentation, and test-related files are checked in that order.
    *
-   * Return the unknown/null value if no rule matches.
+   * @returns A CONVENTIONAL_TYPE value. Returns UNKNOWN if no rule matches.
    */
   getType() {
     if (this.isCIRelated()) {

src/generate/count.ts

@@ -47,6 +47,12 @@ export function _countByAction(changes: FileChange[]) {
   return result;
 }
 
+/**
+ * Return the appropriate plural suffix based on a count.
+ *
+ * @param count The count value.
+ * @returns An empty string if count is 1, otherwise 's' for plural.
+ */
 export function _pluralS(count: number) {
   return count === 1 ? "" : "s";
 }

src/git/cli.ts

@@ -22,6 +22,11 @@ const DIFF_INDEX_OPTIONS = [
 ];
 
 // Allow debug messages to be shown (VS Code extension) or hidden (CLI tool).
+/**
+ * Log debug messages when debugging is enabled via environment variable.
+ *
+ * @param args Arguments to log.
+ */
 function debug(...args: unknown[]): void {
   if (process.env.ACM_DEBUG === "1") {
     console.debug(...args);
@@ -30,6 +35,11 @@ function debug(...args: unknown[]): void {
 
 /**
  * Run a `git` subcommand and return the result, with stdout and stderr available.
+ *
+ * @param cwd The working directory to run the command in.
+ * @param subcommand The git subcommand to execute (e.g., 'diff-index').
+ * @param options Optional array of command-line options to pass to the subcommand.
+ * @returns A promise resolving to the execution result with stdout and stderr.
  */
 function _execute(cwd: string, subcommand: string, options: string[] = []) {
   const command = `git ${QUOTE_PATH} ${subcommand} ${options.join(" ")}`;
@@ -49,7 +59,12 @@ function _execute(cwd: string, subcommand: string, options: string[] = []) {
  * command-line data comes in or got split.
  *
  * The output already seems to never have color info, from testing, but the
- * no-color flagged is added still to be safe.
+ * no-color flag is added still to be safe.
+ *
+ * @param repository The repository to run the command in.
+ * @param options Optional array of additional git options (e.g., ['--cached']).
+ * @returns A promise resolving to an array of non-empty output lines from the
+ *   git diff-index command.
  */
 async function _diffIndex(
   repository: Repository,
@@ -76,7 +91,8 @@ async function _diffIndex(
  * Always excludes untracked files - make sure to stage a file so it becomes
  * tracked, especially in the case of a rename.
  *
- * Returns an array of strings.
+ * @param repository The repository to get changes for.
+ * @returns A promise resolving to an array of strings describing file changes.
  */
 export async function getChanges(repository: Repository) {
   const stagedChanges = await _diffIndex(repository, ["--cached"]);

src/lib/paths.ts

@@ -36,7 +36,13 @@ export function splitPath(filePath: string): SplitPathResult {
   };
 }
 
-/** Format to add quotes if the values contains spaces. */
+/**
+ * Format to add quotes if the value contains spaces.
+ *
+ * @param value The string value to format.
+ * @returns The value wrapped in single quotes if it contains spaces and is not
+ *   the root directory, otherwise the value unchanged.
+ */
 export function quoteForSpaces(value: string) {
   if (value.includes(" ") && value !== ROOT) {
     return `'${value}'`;
@@ -68,7 +74,12 @@ export function friendlyFile(filePath: string) {
 /**
  * Join a list of items using commas and an "and" word.
  *
+ * For example: ['a', 'b', 'c'] becomes 'a, b and c'.
  * These don't have to be file paths but usually are for this project.
+ *
+ * @param items An array of strings to join.
+ * @returns A formatted string with items joined by commas and "and", or an
+ *   empty string if the array is empty.
  */
 export function _join(items: string[]) {
   if (!items.length) {

src/workspace.ts

@@ -1,5 +1,11 @@
 import { workspace } from "vscode";
 
+/**
+ * Get the root folder path of the current workspace.
+ *
+ * @returns The file system path of the first workspace folder, or an empty
+ *   string if no workspace folders are open.
+ */
 export function getWorkspaceFolder(): string {
   const { workspaceFolders } = workspace;