@foss.global/gitmanager 2.0.0 → 2.1.0

package/ts/classes.gitmanagererror.ts

@@ -0,0 +1,28 @@
+import type { TGitManagerErrorCode } from './models.js';
+
+const gitManagerErrorCodes: ReadonlySet<string> = new Set<TGitManagerErrorCode>([
+  'invalidObjectId',
+  'objectNotFound',
+  'objectNotCommit',
+  'ancestryBudgetExceeded',
+  'archiveLimitExceeded',
+  'archiveRejected',
+]);
+
+export const isGitManagerErrorCode = (valueArg: unknown): valueArg is TGitManagerErrorCode =>
+  typeof valueArg === 'string' && gitManagerErrorCodes.has(valueArg);
+
+/**
+ * A failure callers can branch on through its stable `code`. Other failures,
+ * such as an unknown repository or an engine that is not running, remain
+ * plain errors.
+ */
+export class GitManagerError extends Error {
+  public readonly code: TGitManagerErrorCode;
+
+  constructor(codeArg: TGitManagerErrorCode, messageArg: string, optionsArg?: ErrorOptions) {
+    super(messageArg, optionsArg);
+    this.name = 'GitManagerError';
+    this.code = codeArg;
+  }
+}

package/ts/index.ts

@@ -2,3 +2,5 @@ export * from './models.js';
 export * from './rust-gitmanager-bridge.js';
 export * from './classes.gitmanager.js';
 export * from './classes.repositoryservice.js';
+export * from './classes.gitmanagererror.js';
+export { gitManagerArchivePathMetadataCeilingBytes } from './classes.archiveinspection.js';

package/ts/models.ts

@@ -89,6 +89,71 @@ export interface IGitManagerRepositoryArchive
   entryCount: number;
 }
 
+/**
+ * Asks whether `ancestorObjectId` is reachable from `descendantObjectId`
+ * (`git merge-base --is-ancestor`; a commit is its own ancestor). Both must be
+ * full lowercase object IDs of commits in the repository; revision
+ * expressions, abbreviations, and tag objects are refused.
+ */
+export interface IGitManagerAncestryRequest extends IGitManagerRepositorySelector {
+  ancestorObjectId: string;
+  descendantObjectId: string;
+  /**
+   * Wall-clock work budget for the object lookup and the history walk,
+   * 1 to 60000 ms, default 10000. Exceeding it throws a `GitManagerError`
+   * with code `ancestryBudgetExceeded`.
+   */
+  timeoutMs?: number;
+}
+
+/**
+ * Limits for inspecting one `tar.gz` archive. Every limit is inclusive.
+ */
+export interface IGitManagerArchiveInspectionRequest {
+  /** The archive bytes, or a stream of them; it is consumed and closed. */
+  archive: Uint8Array | AsyncIterable<Uint8Array>;
+  maxCompressedBytes: number;
+  maxExtractedBytes: number;
+  maxEntries: number;
+  /**
+   * Ceiling for the UTF-8 bytes of every effective entry path and symlink
+   * target, 1 to 134217728 (the fixed ci-spec ceiling, and the default).
+   */
+  maxPathMetadataBytes?: number;
+}
+
+export interface IGitManagerArchiveInspectionOptions {
+  signal?: AbortSignal;
+}
+
+/** Metadata recomputed from an accepted archive; nothing is taken on trust. */
+export interface IGitManagerArchiveInspection {
+  sizeBytes: number;
+  sha256: string;
+  extractedSizeBytes: number;
+  entryCount: number;
+  pathMetadataBytes: number;
+}
+
+/**
+ * Stable codes of `GitManagerError`.
+ *
+ * - `invalidObjectId`: an object ID is not a full lowercase SHA-1 or SHA-256.
+ * - `objectNotFound`: the object does not exist in the repository.
+ * - `objectNotCommit`: the object exists but is not a commit.
+ * - `ancestryBudgetExceeded`: the ancestry check exceeded `timeoutMs`; the
+ *   answer is unknown, never `false`.
+ * - `archiveLimitExceeded`: the archive exceeds a requested limit.
+ * - `archiveRejected`: the archive breaks a format, path, or link rule.
+ */
+export type TGitManagerErrorCode =
+  | 'invalidObjectId'
+  | 'objectNotFound'
+  | 'objectNotCommit'
+  | 'ancestryBudgetExceeded'
+  | 'archiveLimitExceeded'
+  | 'archiveRejected';
+
 export interface IGitManagerRepositoryLfsPointer {
   oid: string;
   sizeBytes: number;

package/ts/rust-gitmanager-bridge.ts

@@ -1,5 +1,7 @@
 import * as plugins from './plugins.js';
+import { GitManagerError, isGitManagerErrorCode } from './classes.gitmanagererror.js';
 import type {
+  IGitManagerAncestryRequest,
   IGitManagerCommitDetail,
   IGitManagerCommitRequest,
   IGitManagerCommitSummary,
@@ -74,6 +76,7 @@ type TGitManagerCommands = {
   mergeRepository: { params: IGitManagerMergeRequest; result: IGitManagerMergeResult };
   listTree: { params: IGitManagerTreeRequest; result: IGitManagerTreeEntry[] };
   readFile: { params: IGitManagerReadFileRequest; result: IGitManagerFileContent };
+  isAncestor: { params: IGitManagerAncestryRequest; result: boolean };
   listCommits: { params: IGitManagerListCommitsRequest; result: IGitManagerCommitSummary[] };
   getCommit: { params: IGitManagerCommitRequest; result: IGitManagerCommitDetail };
   getDiff: { params: IGitManagerDiffRequest; result: IGitManagerDiff };
@@ -109,16 +112,37 @@ function buildLocalPaths(): string[] {
   return paths;
 }
 
+/**
+ * Rethrows a Rust response that carries a stable GitManager error code as a
+ * `GitManagerError`; every other failure is rethrown unchanged.
+ */
+const rethrowCodedError = (errorArg: unknown): never => {
+  if (
+    errorArg instanceof plugins.smartrust.RustBridgeRequestError
+    && isGitManagerErrorCode(errorArg.responseErrorCode)
+  ) {
+    throw new GitManagerError(errorArg.responseErrorCode, errorArg.message, {
+      cause: errorArg,
+    });
+  }
+  throw errorArg;
+};
+
 export class RustGitManagerBridge extends plugins.EventEmitter {
   private bridge: plugins.smartrust.RustBridge<TGitManagerCommands>;
+  private binaryLocator: plugins.smartrust.RustBinaryLocator;
 
   constructor() {
     super();
-    this.bridge = new plugins.smartrust.RustBridge<TGitManagerCommands>({
+    const binaryLocatorOptions: plugins.smartrust.IBinaryLocatorOptions = {
       binaryName: 'rustgitmanager',
       envVarName: 'GITMANAGER_RUST_BINARY',
       platformPackagePrefix: '@foss.global/gitmanager',
       localPaths: buildLocalPaths(),
+    };
+    this.binaryLocator = new plugins.smartrust.RustBinaryLocator(binaryLocatorOptions);
+    this.bridge = new plugins.smartrust.RustBridge<TGitManagerCommands>({
+      ...binaryLocatorOptions,
       requestTimeoutMs: 130000,
       readyTimeoutMs: 10000,
     });
@@ -135,6 +159,15 @@ export class RustGitManagerBridge extends plugins.EventEmitter {
     return this.bridge.spawn();
   }
 
+  /** Resolves the engine binary the bridge spawns, for its one-shot modes. */
+  public async findBinary(): Promise<string> {
+    const binaryPath = await this.binaryLocator.findBinary();
+    if (!binaryPath) {
+      throw new Error('Unable to locate the rustgitmanager binary');
+    }
+    return binaryPath;
+  }
+
   public kill(): void {
     this.bridge.kill();
   }
@@ -304,6 +337,20 @@ export class RustGitManagerBridge extends plugins.EventEmitter {
     return this.bridge.sendCommand('readFile', requestArg);
   }
 
+  public async isAncestor(requestArg: IGitManagerAncestryRequest): Promise<boolean> {
+    const result = await this.bridge.sendCommand('isAncestor', {
+      org: requestArg.org,
+      repo: requestArg.repo,
+      ancestorObjectId: requestArg.ancestorObjectId,
+      descendantObjectId: requestArg.descendantObjectId,
+      ...(requestArg.timeoutMs === undefined ? {} : { timeoutMs: requestArg.timeoutMs }),
+    }).catch(rethrowCodedError);
+    if (typeof result !== 'boolean') {
+      throw new Error('Rust GitManager returned an invalid ancestry result');
+    }
+    return result;
+  }
+
   public async listCommits(requestArg: IGitManagerListCommitsRequest): Promise<IGitManagerCommitSummary[]> {
     return this.bridge.sendCommand('listCommits', requestArg);
   }