@optique/git 0.9.0-dev.1

package/dist/index.d.cts

@@ -0,0 +1,215 @@
+import { ValueParser } from "@optique/core/valueparser";
+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.
+   */
+  dir?: string;
+  /**
+   * The metavar name for this parser.
+   * Used in help messages to indicate what kind of value this parser expects.
+   */
+  metavar?: NonEmptyString;
+}
+/**
+ * Git parsers factory interface.
+ *
+ * @since 0.9.0
+ */
+interface GitParsers {
+  branch(options?: GitParserOptions): ValueParser<"async", string>;
+  remoteBranch(remote: string, options?: GitParserOptions): ValueParser<"async", string>;
+  tag(options?: GitParserOptions): ValueParser<"async", string>;
+  remote(options?: GitParserOptions): ValueParser<"async", string>;
+  commit(options?: GitParserOptions): ValueParser<"async", string>;
+  ref(options?: GitParserOptions): ValueParser<"async", string>;
+}
+/**
+ * Creates a value parser that validates local branch names.
+ *
+ * This parser uses isomorphic-git to verify that the provided input
+ * matches an existing branch in the repository.
+ *
+ * @param options Configuration options for the parser.
+ * @returns A value parser that accepts existing branch names.
+ * @since 0.9.0
+ *
+ * @example
+ * ~~~~ typescript
+ * import { gitBranch } from "@optique/git";
+ * import { argument } from "@optique/core/primitives";
+ *
+ * const parser = argument(gitBranch());
+ * ~~~~
+ */
+declare function gitBranch(options?: GitParserOptions): ValueParser<"async", string>;
+/**
+ * Creates a value parser that validates remote branch names.
+ *
+ * This parser uses isomorphic-git to verify that the provided input
+ * matches an existing branch on the specified remote.
+ *
+ * @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.
+ * @since 0.9.0
+ *
+ * @example
+ * ~~~~ typescript
+ * import { gitRemoteBranch } from "@optique/git";
+ * import { option } from "@optique/core/primitives";
+ *
+ * const parser = option("-b", "--branch", gitRemoteBranch("origin"));
+ * ~~~~
+ */
+declare function gitRemoteBranch(remote: string, options?: GitParserOptions): ValueParser<"async", string>;
+/**
+ * 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.
+ *
+ * @param options Configuration options for the parser.
+ * @returns A value parser that accepts valid 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).
+ *
+ * This parser uses isomorphic-git to verify that the provided input
+ * resolves to a valid git reference (branch, tag, or commit SHA).
+ *
+ * @param options Configuration options for the parser.
+ * @returns A value parser that accepts branches, tags, or commit SHAs.
+ * @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).
+ *
+ * @param options Shared configuration options for all parsers.
+ * @returns An object with methods for creating individual 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 };

package/dist/index.d.ts

@@ -0,0 +1,215 @@
+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.
+   */
+  dir?: string;
+  /**
+   * The metavar name for this parser.
+   * Used in help messages to indicate what kind of value this parser expects.
+   */
+  metavar?: NonEmptyString;
+}
+/**
+ * Git parsers factory interface.
+ *
+ * @since 0.9.0
+ */
+interface GitParsers {
+  branch(options?: GitParserOptions): ValueParser<"async", string>;
+  remoteBranch(remote: string, options?: GitParserOptions): ValueParser<"async", string>;
+  tag(options?: GitParserOptions): ValueParser<"async", string>;
+  remote(options?: GitParserOptions): ValueParser<"async", string>;
+  commit(options?: GitParserOptions): ValueParser<"async", string>;
+  ref(options?: GitParserOptions): ValueParser<"async", string>;
+}
+/**
+ * Creates a value parser that validates local branch names.
+ *
+ * This parser uses isomorphic-git to verify that the provided input
+ * matches an existing branch in the repository.
+ *
+ * @param options Configuration options for the parser.
+ * @returns A value parser that accepts existing branch names.
+ * @since 0.9.0
+ *
+ * @example
+ * ~~~~ typescript
+ * import { gitBranch } from "@optique/git";
+ * import { argument } from "@optique/core/primitives";
+ *
+ * const parser = argument(gitBranch());
+ * ~~~~
+ */
+declare function gitBranch(options?: GitParserOptions): ValueParser<"async", string>;
+/**
+ * Creates a value parser that validates remote branch names.
+ *
+ * This parser uses isomorphic-git to verify that the provided input
+ * matches an existing branch on the specified remote.
+ *
+ * @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.
+ * @since 0.9.0
+ *
+ * @example
+ * ~~~~ typescript
+ * import { gitRemoteBranch } from "@optique/git";
+ * import { option } from "@optique/core/primitives";
+ *
+ * const parser = option("-b", "--branch", gitRemoteBranch("origin"));
+ * ~~~~
+ */
+declare function gitRemoteBranch(remote: string, options?: GitParserOptions): ValueParser<"async", string>;
+/**
+ * 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.
+ *
+ * @param options Configuration options for the parser.
+ * @returns A value parser that accepts valid 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).
+ *
+ * This parser uses isomorphic-git to verify that the provided input
+ * resolves to a valid git reference (branch, tag, or commit SHA).
+ *
+ * @param options Configuration options for the parser.
+ * @returns A value parser that accepts branches, tags, or commit SHAs.
+ * @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).
+ *
+ * @param options Shared configuration options for all parsers.
+ * @returns An object with methods for creating individual 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 };