@optique/git 0.9.0-dev.215 → 0.9.0-dev.227

package/dist/index.d.cts

@@ -1,55 +1,16 @@
 import { ValueParser } from "@optique/core/valueparser";
+import { Message } from "@optique/core/message";
 import { NonEmptyString } from "@optique/core/nonempty";
 import { expandOid, listBranches, listRemotes, listTags, readObject, resolveRef } from "isomorphic-git";
 
 //#region src/index.d.ts
 
-/**
- * Interface for FileSystem operations required by git parsers.
- * This allows custom filesystem implementations for different environments.
- *
- * @since 0.9.0
- */
-interface FileSystem {
-  readFile(path: string): Promise<Uint8Array | string>;
-  writeFile(path: string, data: Uint8Array | string): Promise<void>;
-  mkdir(path: string, options?: {
-    recursive?: boolean;
-  }): Promise<void>;
-  rmdir(path: string, options?: {
-    recursive?: boolean;
-  }): Promise<void>;
-  unlink(path: string): Promise<void>;
-  readdir(path: string): Promise<string[]>;
-  lstat(path: string): Promise<{
-    isSymbolicLink(): boolean;
-    isDirectory(): boolean;
-    isFile(): boolean;
-  }>;
-  stat(path: string): Promise<{
-    isSymbolicLink(): boolean;
-    isDirectory(): boolean;
-    isFile(): boolean;
-  }>;
-  readlink(path: string): Promise<string>;
-  symlink(target: string, path: string): Promise<void>;
-  chmod(path: string, mode: number): Promise<void>;
-  chown(path: string, uid: number, gid: number): Promise<void>;
-  rename(oldPath: string, newPath: string): Promise<void>;
-  copyFile(srcPath: string, destPath: string): Promise<void>;
-  exists(path: string): Promise<boolean>;
-}
 /**
  * Options for creating git value parsers.
  *
  * @since 0.9.0
  */
 interface GitParserOptions {
-  /**
-   * The filesystem implementation to use.
-   * Defaults to node:fs/promises (works in Deno and Node.js).
-   */
-  fs?: FileSystem;
   /**
    * The directory of the git repository.
    * Defaults to the current working directory.
@@ -60,6 +21,43 @@ interface GitParserOptions {
    * Used in help messages to indicate what kind of value this parser expects.
    */
   metavar?: NonEmptyString;
+  /**
+   * Custom error messages for validation failures.
+   *
+   * @since 0.9.0
+   */
+  errors?: GitParserErrors;
+}
+/**
+ * Custom error messages for git value parsers.
+ *
+ * @since 0.9.0
+ */
+interface GitParserErrors {
+  /**
+   * Error message when the git reference (branch, tag, remote, commit) is not found.
+   *
+   * @param input The user-provided input that was not found.
+   * @param available List of available references (if applicable).
+   * @returns A custom error message.
+   */
+  notFound?: (input: string, available?: readonly string[]) => Message;
+  /**
+   * Error message when listing git references fails.
+   * This typically occurs when the directory is not a valid git repository.
+   *
+   * @param dir The directory that was being accessed.
+   * @returns A custom error message.
+   */
+  listFailed?: (dir: string) => Message;
+  /**
+   * Error message when the input format is invalid.
+   * Applies to parsers that validate format (e.g., commit SHA).
+   *
+   * @param input The user-provided input that has invalid format.
+   * @returns A custom error message.
+   */
+  invalidFormat?: (input: string) => Message;
 }
 /**
  * Git parsers factory interface.
@@ -67,11 +65,43 @@ interface GitParserOptions {
  * @since 0.9.0
  */
 interface GitParsers {
+  /**
+   * Creates a value parser that validates local branch names.
+   * @param options Configuration options for the parser.
+   * @returns A value parser that accepts existing branch names.
+   */
   branch(options?: GitParserOptions): ValueParser<"async", string>;
+  /**
+   * Creates a value parser that validates remote branch names.
+   * @param remote The remote name to validate against.
+   * @param options Configuration options for the parser.
+   * @returns A value parser that accepts existing remote branch names.
+   */
   remoteBranch(remote: string, options?: GitParserOptions): ValueParser<"async", string>;
+  /**
+   * Creates a value parser that validates tag names.
+   * @param options Configuration options for the parser.
+   * @returns A value parser that accepts existing tag names.
+   */
   tag(options?: GitParserOptions): ValueParser<"async", string>;
+  /**
+   * Creates a value parser that validates remote names.
+   * @param options Configuration options for the parser.
+   * @returns A value parser that accepts existing remote names.
+   */
   remote(options?: GitParserOptions): ValueParser<"async", string>;
+  /**
+   * Creates a value parser that validates commit SHAs.
+   * @param options Configuration options for the parser.
+   * @returns A value parser that accepts existing commit SHAs.
+   */
   commit(options?: GitParserOptions): ValueParser<"async", string>;
+  /**
+   * Creates a value parser that validates any git reference.
+   * Accepts branch names, tag names, or commit SHAs.
+   * @param options Configuration options for the parser.
+   * @returns A value parser that accepts any git reference.
+   */
   ref(options?: GitParserOptions): ValueParser<"async", string>;
 }
 /**
@@ -116,100 +146,48 @@ declare function gitRemoteBranch(remote: string, options?: GitParserOptions): Va
 /**
  * Creates a value parser that validates tag names.
  *
- * This parser uses isomorphic-git to verify that the provided input
- * matches an existing tag in the repository.
- *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing tag names.
  * @since 0.9.0
- *
- * @example
- * ~~~~ typescript
- * import { gitTag } from "@optique/git";
- * import { option } from "@optique/core/primitives";
- *
- * const parser = option("-t", "--tag", gitTag());
- * ~~~~
  */
 declare function gitTag(options?: GitParserOptions): ValueParser<"async", string>;
 /**
  * Creates a value parser that validates remote names.
  *
- * This parser uses isomorphic-git to verify that the provided input
- * matches an existing remote in the repository.
- *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing remote names.
  * @since 0.9.0
- *
- * @example
- * ~~~~ typescript
- * import { gitRemote } from "@optique/git";
- * import { option } from "@optique/core/primitives";
- *
- * const parser = option("-r", "--remote", gitRemote());
- * ~~~~
  */
 declare function gitRemote(options?: GitParserOptions): ValueParser<"async", string>;
 /**
  * Creates a value parser that validates commit SHAs.
  *
- * This parser uses isomorphic-git to verify that the provided input
- * is a valid commit SHA (full or shortened) that exists in the repository.
+ * This parser resolves the provided commit reference to its full 40-character
+ * OID.
  *
  * @param options Configuration options for the parser.
- * @returns A value parser that accepts valid commit SHAs.
+ * @returns A value parser that accepts existing commit SHAs.
  * @since 0.9.0
- *
- * @example
- * ~~~~ typescript
- * import { gitCommit } from "@optique/git";
- * import { option } from "@optique/core/primitives";
- *
- * const parser = option("-c", "--commit", gitCommit());
- * ~~~~
  */
 declare function gitCommit(options?: GitParserOptions): ValueParser<"async", string>;
 /**
- * Creates a value parser that validates any git reference
- * (branches, tags, or commits).
+ * Creates a value parser that validates any git reference.
  *
- * This parser uses isomorphic-git to verify that the provided input
- * resolves to a valid git reference (branch, tag, or commit SHA).
+ * Accepts branch names, tag names, or commit SHAs and resolves them to the
+ * corresponding commit OID.
  *
  * @param options Configuration options for the parser.
- * @returns A value parser that accepts branches, tags, or commit SHAs.
+ * @returns A value parser that accepts any git reference.
  * @since 0.9.0
- *
- * @example
- * ~~~~ typescript
- * import { gitRef } from "@optique/git";
- * import { option } from "@optique/core/primitives";
- *
- * const parser = option("--ref", gitRef());
- * ~~~~
  */
 declare function gitRef(options?: GitParserOptions): ValueParser<"async", string>;
 /**
- * Creates a factory for git parsers with shared configuration.
- *
- * This function returns an object with methods for creating individual git
- * parsers that share the same configuration (filesystem and directory).
+ * Creates a set of git parsers with shared configuration.
  *
- * @param options Shared configuration options for all parsers.
- * @returns An object with methods for creating individual git parsers.
+ * @param options Shared configuration for the parsers.
+ * @returns An object containing git parsers.
  * @since 0.9.0
- *
- * @example
- * ~~~~ typescript
- * import { createGitParsers } from "@optique/git";
- *
- * const git = createGitParsers({ dir: "/path/to/repo" });
- *
- * const branchParser = git.branch();
- * const tagParser = git.tag();
- * ~~~~
  */
 declare function createGitParsers(options?: GitParserOptions): GitParsers;
 //#endregion
-export { FileSystem, GitParserOptions, GitParsers, createGitParsers, expandOid, gitBranch, gitCommit, gitRef, gitRemote, gitRemoteBranch, gitTag, listBranches, listRemotes, listTags, readObject, resolveRef };
+export { GitParserErrors, GitParserOptions, GitParsers, createGitParsers, expandOid, gitBranch, gitCommit, gitRef, gitRemote, gitRemoteBranch, gitTag, listBranches, listRemotes, listTags, readObject, resolveRef };

package/dist/index.d.ts

@@ -1,55 +1,16 @@
+import { Message } from "@optique/core/message";
 import { NonEmptyString } from "@optique/core/nonempty";
 import { expandOid, listBranches, listRemotes, listTags, readObject, resolveRef } from "isomorphic-git";
 import { ValueParser } from "@optique/core/valueparser";
 
 //#region src/index.d.ts
 
-/**
- * Interface for FileSystem operations required by git parsers.
- * This allows custom filesystem implementations for different environments.
- *
- * @since 0.9.0
- */
-interface FileSystem {
-  readFile(path: string): Promise<Uint8Array | string>;
-  writeFile(path: string, data: Uint8Array | string): Promise<void>;
-  mkdir(path: string, options?: {
-    recursive?: boolean;
-  }): Promise<void>;
-  rmdir(path: string, options?: {
-    recursive?: boolean;
-  }): Promise<void>;
-  unlink(path: string): Promise<void>;
-  readdir(path: string): Promise<string[]>;
-  lstat(path: string): Promise<{
-    isSymbolicLink(): boolean;
-    isDirectory(): boolean;
-    isFile(): boolean;
-  }>;
-  stat(path: string): Promise<{
-    isSymbolicLink(): boolean;
-    isDirectory(): boolean;
-    isFile(): boolean;
-  }>;
-  readlink(path: string): Promise<string>;
-  symlink(target: string, path: string): Promise<void>;
-  chmod(path: string, mode: number): Promise<void>;
-  chown(path: string, uid: number, gid: number): Promise<void>;
-  rename(oldPath: string, newPath: string): Promise<void>;
-  copyFile(srcPath: string, destPath: string): Promise<void>;
-  exists(path: string): Promise<boolean>;
-}
 /**
  * Options for creating git value parsers.
  *
  * @since 0.9.0
  */
 interface GitParserOptions {
-  /**
-   * The filesystem implementation to use.
-   * Defaults to node:fs/promises (works in Deno and Node.js).
-   */
-  fs?: FileSystem;
   /**
    * The directory of the git repository.
    * Defaults to the current working directory.
@@ -60,6 +21,43 @@ interface GitParserOptions {
    * Used in help messages to indicate what kind of value this parser expects.
    */
   metavar?: NonEmptyString;
+  /**
+   * Custom error messages for validation failures.
+   *
+   * @since 0.9.0
+   */
+  errors?: GitParserErrors;
+}
+/**
+ * Custom error messages for git value parsers.
+ *
+ * @since 0.9.0
+ */
+interface GitParserErrors {
+  /**
+   * Error message when the git reference (branch, tag, remote, commit) is not found.
+   *
+   * @param input The user-provided input that was not found.
+   * @param available List of available references (if applicable).
+   * @returns A custom error message.
+   */
+  notFound?: (input: string, available?: readonly string[]) => Message;
+  /**
+   * Error message when listing git references fails.
+   * This typically occurs when the directory is not a valid git repository.
+   *
+   * @param dir The directory that was being accessed.
+   * @returns A custom error message.
+   */
+  listFailed?: (dir: string) => Message;
+  /**
+   * Error message when the input format is invalid.
+   * Applies to parsers that validate format (e.g., commit SHA).
+   *
+   * @param input The user-provided input that has invalid format.
+   * @returns A custom error message.
+   */
+  invalidFormat?: (input: string) => Message;
 }
 /**
  * Git parsers factory interface.
@@ -67,11 +65,43 @@ interface GitParserOptions {
  * @since 0.9.0
  */
 interface GitParsers {
+  /**
+   * Creates a value parser that validates local branch names.
+   * @param options Configuration options for the parser.
+   * @returns A value parser that accepts existing branch names.
+   */
   branch(options?: GitParserOptions): ValueParser<"async", string>;
+  /**
+   * Creates a value parser that validates remote branch names.
+   * @param remote The remote name to validate against.
+   * @param options Configuration options for the parser.
+   * @returns A value parser that accepts existing remote branch names.
+   */
   remoteBranch(remote: string, options?: GitParserOptions): ValueParser<"async", string>;
+  /**
+   * Creates a value parser that validates tag names.
+   * @param options Configuration options for the parser.
+   * @returns A value parser that accepts existing tag names.
+   */
   tag(options?: GitParserOptions): ValueParser<"async", string>;
+  /**
+   * Creates a value parser that validates remote names.
+   * @param options Configuration options for the parser.
+   * @returns A value parser that accepts existing remote names.
+   */
   remote(options?: GitParserOptions): ValueParser<"async", string>;
+  /**
+   * Creates a value parser that validates commit SHAs.
+   * @param options Configuration options for the parser.
+   * @returns A value parser that accepts existing commit SHAs.
+   */
   commit(options?: GitParserOptions): ValueParser<"async", string>;
+  /**
+   * Creates a value parser that validates any git reference.
+   * Accepts branch names, tag names, or commit SHAs.
+   * @param options Configuration options for the parser.
+   * @returns A value parser that accepts any git reference.
+   */
   ref(options?: GitParserOptions): ValueParser<"async", string>;
 }
 /**
@@ -116,100 +146,48 @@ declare function gitRemoteBranch(remote: string, options?: GitParserOptions): Va
 /**
  * Creates a value parser that validates tag names.
  *
- * This parser uses isomorphic-git to verify that the provided input
- * matches an existing tag in the repository.
- *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing tag names.
  * @since 0.9.0
- *
- * @example
- * ~~~~ typescript
- * import { gitTag } from "@optique/git";
- * import { option } from "@optique/core/primitives";
- *
- * const parser = option("-t", "--tag", gitTag());
- * ~~~~
  */
 declare function gitTag(options?: GitParserOptions): ValueParser<"async", string>;
 /**
  * Creates a value parser that validates remote names.
  *
- * This parser uses isomorphic-git to verify that the provided input
- * matches an existing remote in the repository.
- *
  * @param options Configuration options for the parser.
  * @returns A value parser that accepts existing remote names.
  * @since 0.9.0
- *
- * @example
- * ~~~~ typescript
- * import { gitRemote } from "@optique/git";
- * import { option } from "@optique/core/primitives";
- *
- * const parser = option("-r", "--remote", gitRemote());
- * ~~~~
  */
 declare function gitRemote(options?: GitParserOptions): ValueParser<"async", string>;
 /**
  * Creates a value parser that validates commit SHAs.
  *
- * This parser uses isomorphic-git to verify that the provided input
- * is a valid commit SHA (full or shortened) that exists in the repository.
+ * This parser resolves the provided commit reference to its full 40-character
+ * OID.
  *
  * @param options Configuration options for the parser.
- * @returns A value parser that accepts valid commit SHAs.
+ * @returns A value parser that accepts existing commit SHAs.
  * @since 0.9.0
- *
- * @example
- * ~~~~ typescript
- * import { gitCommit } from "@optique/git";
- * import { option } from "@optique/core/primitives";
- *
- * const parser = option("-c", "--commit", gitCommit());
- * ~~~~
  */
 declare function gitCommit(options?: GitParserOptions): ValueParser<"async", string>;
 /**
- * Creates a value parser that validates any git reference
- * (branches, tags, or commits).
+ * Creates a value parser that validates any git reference.
  *
- * This parser uses isomorphic-git to verify that the provided input
- * resolves to a valid git reference (branch, tag, or commit SHA).
+ * Accepts branch names, tag names, or commit SHAs and resolves them to the
+ * corresponding commit OID.
  *
  * @param options Configuration options for the parser.
- * @returns A value parser that accepts branches, tags, or commit SHAs.
+ * @returns A value parser that accepts any git reference.
  * @since 0.9.0
- *
- * @example
- * ~~~~ typescript
- * import { gitRef } from "@optique/git";
- * import { option } from "@optique/core/primitives";
- *
- * const parser = option("--ref", gitRef());
- * ~~~~
  */
 declare function gitRef(options?: GitParserOptions): ValueParser<"async", string>;
 /**
- * Creates a factory for git parsers with shared configuration.
- *
- * This function returns an object with methods for creating individual git
- * parsers that share the same configuration (filesystem and directory).
+ * Creates a set of git parsers with shared configuration.
  *
- * @param options Shared configuration options for all parsers.
- * @returns An object with methods for creating individual git parsers.
+ * @param options Shared configuration for the parsers.
+ * @returns An object containing git parsers.
  * @since 0.9.0
- *
- * @example
- * ~~~~ typescript
- * import { createGitParsers } from "@optique/git";
- *
- * const git = createGitParsers({ dir: "/path/to/repo" });
- *
- * const branchParser = git.branch();
- * const tagParser = git.tag();
- * ~~~~
  */
 declare function createGitParsers(options?: GitParserOptions): GitParsers;
 //#endregion
-export { FileSystem, GitParserOptions, GitParsers, createGitParsers, expandOid, gitBranch, gitCommit, gitRef, gitRemote, gitRemoteBranch, gitTag, listBranches, listRemotes, listTags, readObject, resolveRef };
+export { GitParserErrors, GitParserOptions, GitParsers, createGitParsers, expandOid, gitBranch, gitCommit, gitRef, gitRemote, gitRemoteBranch, gitTag, listBranches, listRemotes, listTags, readObject, resolveRef };