workspace-tools 0.38.4 → 0.38.6

package/lib/getPackageInfo.d.ts

@@ -0,0 +1,13 @@
+import type { PackageInfo } from "./types/PackageInfo";
+/**
+ * Read package.json from the given path if it exists.
+ * Logs a warning if it doesn't exist, or there's an error reading or parsing it.
+ * @returns The package info, or undefined if it doesn't exist or can't be read
+ */
+export declare function getPackageInfo(cwd: string): PackageInfo | undefined;
+/**
+ * Read package.json from the given path if it exists.
+ * Logs a warning if it doesn't exist, or there's an error reading or parsing it.
+ * @returns The package info, or undefined if it doesn't exist or can't be read
+ */
+export declare function getPackageInfoAsync(cwd: string): Promise<PackageInfo | undefined>;

package/lib/getPackageInfo.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPackageInfoAsync = exports.getPackageInfo = void 0;
+const fs_1 = __importDefault(require("fs"));
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const infoFromPackageJson_1 = require("./infoFromPackageJson");
+const logging_1 = require("./logging");
+/**
+ * Read package.json from the given path if it exists.
+ * Logs a warning if it doesn't exist, or there's an error reading or parsing it.
+ * @returns The package info, or undefined if it doesn't exist or can't be read
+ */
+function getPackageInfo(cwd) {
+    const packageJsonPath = path_1.default.join(cwd, "package.json");
+    try {
+        if (!fs_1.default.existsSync(packageJsonPath)) {
+            (0, logging_1.logVerboseWarning)(`File does not exist: ${packageJsonPath}`);
+            return undefined;
+        }
+        const packageJson = JSON.parse(fs_1.default.readFileSync(packageJsonPath, "utf-8"));
+        return (0, infoFromPackageJson_1.infoFromPackageJson)(packageJson, packageJsonPath);
+    }
+    catch (e) {
+        (0, logging_1.logVerboseWarning)(`Error reading or parsing ${packageJsonPath}: ${e?.message || e}`);
+    }
+}
+exports.getPackageInfo = getPackageInfo;
+/**
+ * Read package.json from the given path if it exists.
+ * Logs a warning if it doesn't exist, or there's an error reading or parsing it.
+ * @returns The package info, or undefined if it doesn't exist or can't be read
+ */
+async function getPackageInfoAsync(cwd) {
+    const packageJsonPath = path_1.default.join(cwd, "package.json");
+    try {
+        if (!fs_1.default.existsSync(packageJsonPath)) {
+            (0, logging_1.logVerboseWarning)(`File does not exist: ${packageJsonPath}`);
+            return undefined;
+        }
+        const packageJson = JSON.parse(await promises_1.default.readFile(packageJsonPath, "utf-8"));
+        return (0, infoFromPackageJson_1.infoFromPackageJson)(packageJson, packageJsonPath);
+    }
+    catch (e) {
+        (0, logging_1.logVerboseWarning)(`Error reading or parsing ${packageJsonPath}: ${e?.message || e}`);
+    }
+}
+exports.getPackageInfoAsync = getPackageInfoAsync;
+//# sourceMappingURL=getPackageInfo.js.map

package/lib/getPackageInfo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getPackageInfo.js","sourceRoot":"","sources":["../src/getPackageInfo.ts"],"names":[],"mappings":";;;;;;AAAA,4CAAoB;AACpB,2DAAqC;AACrC,gDAAwB;AAExB,+DAA4D;AAC5D,uCAA8C;AAE9C;;;;GAIG;AACH,SAAgB,cAAc,CAAC,GAAW;IACxC,MAAM,eAAe,GAAG,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IACvD,IAAI;QACF,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE;YACnC,IAAA,2BAAiB,EAAC,wBAAwB,eAAe,EAAE,CAAC,CAAC;YAC7D,OAAO,SAAS,CAAC;SAClB;QAED,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,YAAE,CAAC,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC;QAC1E,OAAO,IAAA,yCAAmB,EAAC,WAAW,EAAE,eAAe,CAAC,CAAC;KAC1D;IAAC,OAAO,CAAC,EAAE;QACV,IAAA,2BAAiB,EAAC,4BAA4B,eAAe,KAAM,CAAW,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC;KACjG;AACH,CAAC;AAbD,wCAaC;AAED;;;;GAIG;AACI,KAAK,UAAU,mBAAmB,CAAC,GAAW;IACnD,MAAM,eAAe,GAAG,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IACvD,IAAI;QACF,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE;YACnC,IAAA,2BAAiB,EAAC,wBAAwB,eAAe,EAAE,CAAC,CAAC;YAC7D,OAAO,SAAS,CAAC;SAClB;QAED,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,kBAAU,CAAC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC;QACpF,OAAO,IAAA,yCAAmB,EAAC,WAAW,EAAE,eAAe,CAAC,CAAC;KAC1D;IAAC,OAAO,CAAC,EAAE;QACV,IAAA,2BAAiB,EAAC,4BAA4B,eAAe,KAAM,CAAW,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC;KACjG;AACH,CAAC;AAbD,kDAaC"}

package/lib/getPackageInfos.d.ts

@@ -1,3 +1,17 @@
 import { PackageInfos } from "./types/PackageInfo";
+/**
+ * Read all the package.json files in a monorepo. Only works for monorepos which
+ * use a supported workspace manager.
+ * @param cwd Start looking for the workspace manager config from here
+ */
 export declare function getPackageInfos(cwd: string): PackageInfos;
+/**
+ * Read all the package.json files in a monorepo. Only works for monorepos which
+ * use a supported workspace manager.
+ *
+ * NOTE: As of writing, this will start promises to read all package.json files in parallel,
+ * without direct concurrency control.
+ *
+ * @param cwd Start looking for the workspace manager config from here
+ */
 export declare function getPackageInfosAsync(cwd: string): Promise<PackageInfos>;

package/lib/getPackageInfos.js

@@ -1,13 +1,13 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPackageInfosAsync = exports.getPackageInfos = void 0;
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-const infoFromPackageJson_1 = require("./infoFromPackageJson");
 const getWorkspaces_1 = require("./workspaces/getWorkspaces");
+const getPackageInfo_1 = require("./getPackageInfo");
+/**
+ * Read all the package.json files in a monorepo. Only works for monorepos which
+ * use a supported workspace manager.
+ * @param cwd Start looking for the workspace manager config from here
+ */
 function getPackageInfos(cwd) {
     const packageInfos = {};
     const workspacePackages = (0, getWorkspaces_1.getWorkspaces)(cwd);
@@ -17,7 +17,7 @@ function getPackageInfos(cwd) {
         }
     }
     else {
-        const rootInfo = tryReadRootPackageJson(cwd);
+        const rootInfo = (0, getPackageInfo_1.getPackageInfo)(cwd);
         if (rootInfo) {
             packageInfos[rootInfo.name] = rootInfo;
         }
@@ -25,6 +25,15 @@ function getPackageInfos(cwd) {
     return packageInfos;
 }
 exports.getPackageInfos = getPackageInfos;
+/**
+ * Read all the package.json files in a monorepo. Only works for monorepos which
+ * use a supported workspace manager.
+ *
+ * NOTE: As of writing, this will start promises to read all package.json files in parallel,
+ * without direct concurrency control.
+ *
+ * @param cwd Start looking for the workspace manager config from here
+ */
 async function getPackageInfosAsync(cwd) {
     const packageInfos = {};
     const workspacePackages = await (0, getWorkspaces_1.getWorkspacesAsync)(cwd);
@@ -34,7 +43,7 @@ async function getPackageInfosAsync(cwd) {
         }
     }
     else {
-        const rootInfo = tryReadRootPackageJson(cwd);
+        const rootInfo = (0, getPackageInfo_1.getPackageInfo)(cwd);
         if (rootInfo) {
             packageInfos[rootInfo.name] = rootInfo;
         }
@@ -42,16 +51,4 @@ async function getPackageInfosAsync(cwd) {
     return packageInfos;
 }
 exports.getPackageInfosAsync = getPackageInfosAsync;
-function tryReadRootPackageJson(cwd) {
-    const packageJsonPath = path_1.default.join(cwd, "package.json");
-    if (fs_1.default.existsSync(packageJsonPath)) {
-        try {
-            const packageJson = JSON.parse(fs_1.default.readFileSync(packageJsonPath, "utf-8"));
-            return (0, infoFromPackageJson_1.infoFromPackageJson)(packageJson, packageJsonPath);
-        }
-        catch (e) {
-            throw new Error(`Invalid package.json file detected ${packageJsonPath}: ${e?.message || e}`);
-        }
-    }
-}
 //# sourceMappingURL=getPackageInfos.js.map

package/lib/getPackageInfos.js.map

@@ -1 +1 @@
-{"version":3,"file":"getPackageInfos.js","sourceRoot":"","sources":["../src/getPackageInfos.ts"],"names":[],"mappings":";;;;;;AAAA,4CAAoB;AACpB,gDAAwB;AAExB,+DAA4D;AAC5D,8DAA+E;AAE/E,SAAgB,eAAe,CAAC,GAAW;IACzC,MAAM,YAAY,GAAiB,EAAE,CAAC;IACtC,MAAM,iBAAiB,GAAG,IAAA,6BAAa,EAAC,GAAG,CAAC,CAAC;IAE7C,IAAI,iBAAiB,CAAC,MAAM,EAAE;QAC5B,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE;YACnC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC;SAC1C;KACF;SAAM;QACL,MAAM,QAAQ,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,QAAQ,EAAE;YACZ,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;SACxC;KACF;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAhBD,0CAgBC;AAEM,KAAK,UAAU,oBAAoB,CAAC,GAAW;IACpD,MAAM,YAAY,GAAiB,EAAE,CAAC;IACtC,MAAM,iBAAiB,GAAG,MAAM,IAAA,kCAAkB,EAAC,GAAG,CAAC,CAAC;IAExD,IAAI,iBAAiB,CAAC,MAAM,EAAE;QAC5B,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE;YACnC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC;SAC1C;KACF;SAAM;QACL,MAAM,QAAQ,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,QAAQ,EAAE;YACZ,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;SACxC;KACF;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAhBD,oDAgBC;AAED,SAAS,sBAAsB,CAAC,GAAW;IACzC,MAAM,eAAe,GAAG,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IACvD,IAAI,YAAE,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE;QAClC,IAAI;YACF,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,YAAE,CAAC,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC;YAC1E,OAAO,IAAA,yCAAmB,EAAC,WAAW,EAAE,eAAe,CAAC,CAAC;SAC1D;QAAC,OAAO,CAAC,EAAE;YACV,MAAM,IAAI,KAAK,CAAC,sCAAsC,eAAe,KAAM,CAAW,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC;SACzG;KACF;AACH,CAAC"}
+{"version":3,"file":"getPackageInfos.js","sourceRoot":"","sources":["../src/getPackageInfos.ts"],"names":[],"mappings":";;;AACA,8DAA+E;AAC/E,qDAAkD;AAElD;;;;GAIG;AACH,SAAgB,eAAe,CAAC,GAAW;IACzC,MAAM,YAAY,GAAiB,EAAE,CAAC;IACtC,MAAM,iBAAiB,GAAG,IAAA,6BAAa,EAAC,GAAG,CAAC,CAAC;IAE7C,IAAI,iBAAiB,CAAC,MAAM,EAAE;QAC5B,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE;YACnC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC;SAC1C;KACF;SAAM;QACL,MAAM,QAAQ,GAAG,IAAA,+BAAc,EAAC,GAAG,CAAC,CAAC;QACrC,IAAI,QAAQ,EAAE;YACZ,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;SACxC;KACF;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAhBD,0CAgBC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,oBAAoB,CAAC,GAAW;IACpD,MAAM,YAAY,GAAiB,EAAE,CAAC;IACtC,MAAM,iBAAiB,GAAG,MAAM,IAAA,kCAAkB,EAAC,GAAG,CAAC,CAAC;IAExD,IAAI,iBAAiB,CAAC,MAAM,EAAE;QAC5B,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE;YACnC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC;SAC1C;KACF;SAAM;QACL,MAAM,QAAQ,GAAG,IAAA,+BAAc,EAAC,GAAG,CAAC,CAAC;QACrC,IAAI,QAAQ,EAAE;YACZ,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;SACxC;KACF;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAhBD,oDAgBC"}

package/lib/getPackagePaths.d.ts

@@ -1,10 +1,10 @@
 /**
  * Given package folder globs (such as those from package.json `workspaces`) and a workspace root
- * directory, get paths to actual package folders.
+ * directory, get absolute paths to actual package folders.
  */
 export declare function getPackagePaths(root: string, packageGlobs: string[]): string[];
 /**
  * Given package folder globs (such as those from package.json `workspaces`) and a workspace root
- * directory, get paths to actual package folders.
+ * directory, get absolute paths to actual package folders.
  */
 export declare function getPackagePathsAsync(root: string, packageGlobs: string[]): Promise<string[]>;

package/lib/getPackagePaths.js

@@ -15,7 +15,7 @@ const globOptions = {
 };
 /**
  * Given package folder globs (such as those from package.json `workspaces`) and a workspace root
- * directory, get paths to actual package folders.
+ * directory, get absolute paths to actual package folders.
  */
 function getPackagePaths(root, packageGlobs) {
     if ((0, isCachingEnabled_1.isCachingEnabled)() && packagePathsCache[root]) {
@@ -29,7 +29,7 @@ function getPackagePaths(root, packageGlobs) {
 exports.getPackagePaths = getPackagePaths;
 /**
  * Given package folder globs (such as those from package.json `workspaces`) and a workspace root
- * directory, get paths to actual package folders.
+ * directory, get absolute paths to actual package folders.
  */
 async function getPackagePathsAsync(root, packageGlobs) {
     if ((0, isCachingEnabled_1.isCachingEnabled)() && packagePathsCache[root]) {

package/lib/git/gitUtilities.d.ts

@@ -1,41 +1,170 @@
+/**
+ * Get a list of files with untracked changes.
+ * Throws an error on failure.
+ *
+ * @returns An array of file paths with untracked changes
+ */
 export declare function getUntrackedChanges(cwd: string): string[];
+/**
+ * Fetch from the given remote.
+ * Throws an error on failure.
+ */
 export declare function fetchRemote(remote: string, cwd: string): void;
+/**
+ * Fetch from the given remote and branch.
+ * Throws an error on failure.
+ */
 export declare function fetchRemoteBranch(remote: string, remoteBranch: string, cwd: string): void;
 /**
- * Gets all the changes that have not been staged yet
- * @param cwd
+ * Gets file paths with changes that have not been staged yet.
+ * Throws an error on failure.
+ *
+ * @returns An array of relative file paths with unstaged changes
  */
 export declare function getUnstagedChanges(cwd: string): string[];
+/**
+ * Gets file paths with changes between the current branch and the given branch.
+ * Throws an error on failure.
+ *
+ * @returns An array of relative file paths that have changed
+ */
 export declare function getChanges(branch: string, cwd: string): string[];
 /**
- * Gets all the changes between the branch and the merge-base
+ * Gets file paths with changes between the branch and the merge-base.
+ *
+ * @returns An array of relative file paths that have changed
  */
 export declare function getBranchChanges(branch: string, cwd: string): string[];
+/**
+ * Gets file paths with changes between two git references (commits, branches, tags).
+ * Throws an error on failure.
+ *
+ * @param fromRef - The starting reference
+ * @param toRef - The ending reference
+ * @param options - Additional git diff options
+ * @param pattern - Optional file pattern to filter results
+ * @param cwd - The working directory
+ * @returns An array of file paths that have changed
+ */
 export declare function getChangesBetweenRefs(fromRef: string, toRef: string, options: string[], pattern: string, cwd: string): string[];
+/**
+ * Gets all files with staged changes (files added to the index).
+ * Throws an error on failure.
+ *
+ * @returns An array of relative file paths that have been staged
+ */
 export declare function getStagedChanges(cwd: string): string[];
+/**
+ * Gets recent commit messages between the specified branch and HEAD.
+ * Returns an empty array if the operation fails.
+ *
+ * @returns An array of commit message strings
+ */
 export declare function getRecentCommitMessages(branch: string, cwd: string): string[];
+/**
+ * Gets the user email from the git config.
+ * @returns The email string if found, null otherwise
+ */
 export declare function getUserEmail(cwd: string): string | null;
+/**
+ * Gets the current branch name.
+ * @returns The branch name if successful, null otherwise
+ */
 export declare function getBranchName(cwd: string): string | null;
+/**
+ * Gets the full reference path for a given branch.
+ * @param branch - The short branch name (e.g., `branch-name`)
+ * @returns The full branch reference (e.g., `refs/heads/branch-name`) if found, null otherwise
+ */
 export declare function getFullBranchRef(branch: string, cwd: string): string | null;
+/**
+ * Gets the short branch name from a full branch reference.
+ * Note this may not work properly for the current branch.
+ * @param fullBranchRef - The full branch reference (e.g., `refs/heads/branch-name`)
+ * @returns The short branch name if successful, null otherwise
+ */
 export declare function getShortBranchName(fullBranchRef: string, cwd: string): string | null;
+/**
+ * Gets the current commit hash (SHA).
+ * @returns The hash if successful, null otherwise
+ */
 export declare function getCurrentHash(cwd: string): string | null;
 /**
  * Get the commit hash in which the file was first added.
+ * @returns The commit hash if found, undefined otherwise
  */
 export declare function getFileAddedHash(filename: string, cwd: string): string | undefined;
+/**
+ * Initializes a git repository in the specified directory.
+ * Optionally sets user email and username if not already configured.
+ * Throws an error if required email or username is not provided and not already configured.
+ *
+ * @param cwd - The directory to initialize the git repository in
+ * @param email - Optional email to set in git config
+ * @param username - Optional username to set in git config
+ */
 export declare function init(cwd: string, email?: string, username?: string): void;
+/**
+ * Stages files matching the given patterns.
+ */
 export declare function stage(patterns: string[], cwd: string): void;
+/**
+ * Creates a commit with the given message and optional git commit options.
+ * Throws an error on failure.
+ *
+ * @param message - The commit message
+ * @param cwd - The working directory
+ * @param options - Additional git commit options
+ */
 export declare function commit(message: string, cwd: string, options?: string[]): void;
+/**
+ * Stages files matching the given patterns and creates a commit with the specified message.
+ * Convenience function that combines `stage()` and `commit()`.
+ * Throws an error on commit failure.
+ *
+ * @param patterns - File patterns to stage
+ * @param message - The commit message
+ * @param cwd - The working directory
+ * @param commitOptions - Additional git commit options
+ */
 export declare function stageAndCommit(patterns: string[], message: string, cwd: string, commitOptions?: string[]): void;
+/**
+ * Reverts all local changes (both staged and unstaged) by stashing them and then dropping the stash.
+ * @returns True if the revert was successful, false otherwise
+ */
 export declare function revertLocalChanges(cwd: string): boolean;
+/**
+ * Attempts to determine the parent branch of the current branch using `git show-branch`.
+ *
+ * @returns The parent branch name if found, null otherwise
+ */
 export declare function getParentBranch(cwd: string): string | null;
+/**
+ * Gets the remote tracking branch for the specified branch.
+ *
+ * @returns The remote branch name (e.g., `origin/main`) if found, null otherwise
+ */
 export declare function getRemoteBranch(branch: string, cwd: string): string | null;
+/**
+ * Parses a remote branch string (e.g., `origin/main`) into its components.
+ *
+ * @param branch - The remote branch string to parse (e.g., `origin/main`)
+ */
 export declare function parseRemoteBranch(branch: string): {
+    /** Remote name, e.g. `origin` */
     remote: string;
+    /** Remote branch name, e.g. `main` */
     remoteBranch: string;
 };
 /**
  * Gets the default branch based on `git config init.defaultBranch`, falling back to `master`.
  */
 export declare function getDefaultBranch(cwd: string): string;
+/**
+ * Lists all tracked files matching the given patterns.
+ *
+ * @param patterns - File patterns to match (passed to git ls-files)
+ * @param cwd - The working directory
+ * @returns An array of file paths, or an empty array if no files are found
+ */
 export declare function listAllTrackedFiles(patterns: string[], cwd: string): string[];