@remogram/provider-gitea-api 0.1.0-beta.3 → 0.1.0-beta.4

package/index.js

@@ -1,5 +1,6 @@
 import {
   fetchJson,
+  fetchJsonWithMeta,
   sanitizeField,
   sanitizeUrl,
   assertGitRef,
@@ -9,19 +10,39 @@ import {
   gitAheadBehind,
   refsInventory,
   crInventory,
-  mergeBlockersFromFacts,
+  buildMergePlanBodyFromFacts,
+  buildChangeRequestOpenedBody,
   ERROR_CODES,
   forgeError,
   forgeIngestCapabilityFacts,
   checkPaginationCapabilityFacts,
+  idempotencyScanCapabilityFacts,
+  openPullListCapabilityFacts,
   DEFAULT_CHECK_STATUS_PAGE_SIZE,
   MAX_CHECK_STATUS_PAGES,
+  DEFAULT_OPEN_PULL_LIST_PAGE_SIZE,
+  MAX_OPEN_PULL_IDEMPOTENCY_PAGES,
   paginateCheckStatusPages,
   paginateOffsetListPages,
   fetchWithIngestPageBackoff,
   fetchPageWithIngestBackoff,
   withPerPageParam,
   apiProviderCommands,
+  normalizeCrInventorySort,
+  DEFAULT_CR_INVENTORY_SLICE_SORT,
+  parseTotalCountHeader,
+  isCrInventoryFastPathEligible,
+  validateFastPathPageLength,
+  isNumberSortFastPathEligible,
+  isRecentCreatedFastPathEligible,
+  giteaRecentCreatedTailPage,
+  isNumberSortFullCollectRequired,
+  resolveListTruncatedWithTrustedTotal,
+  prepareGiteaOpenPullPageItems,
+  orderOpenPullNumbers,
+  buildOpenPullListMeta,
+  giteaOpenPullSortQuery,
+  appendSortQuery,
 } from '@remogram/core';
 const PUBLIC_GITEA_HOST = 'gitea.com';
 const PUBLIC_GITEA_API = 'https://gitea.com/api/v1';
@@ -34,9 +55,10 @@ const AUTH_CAPABILITIES = [
   'pr_checks',
   'merge_plan',
   'sync_plan',
+  'cr_open',
 ];
 
-const STRUCTURED_COMMANDS = apiProviderCommands();
+const STRUCTURED_COMMANDS = apiProviderCommands({ writeCommandsImplemented: true });
 
 export function giteaToken() {
   return process.env.GITEA_TOKEN || null;
@@ -132,8 +154,32 @@ export async function giteaFetch(config, parsed, path, options = {}) {
   });
 }
 
+export async function giteaFetchWithMeta(config, parsed, path, options = {}) {
+  const token = requireToken();
+  const url = `${apiBase(config, parsed)}${path}`;
+  return fetchJsonWithMeta(url, {
+    ...options,
+    headers: { ...authHeaders(token), ...(options.headers || {}) },
+  });
+}
+
 const MAX_CHECK_PAGES = MAX_CHECK_STATUS_PAGES;
-const GITEA_PAGE_SIZE = 100;
+const GITEA_PAGE_SIZE = DEFAULT_OPEN_PULL_LIST_PAGE_SIZE;
+
+function idempotencyScanIncompleteError(pagesScanned, pageSizeUsed) {
+  return forgeError(
+    ERROR_CODES.IDEMPOTENCY_SCAN_INCOMPLETE,
+    'Cannot prove no open pull exists for head+base within scan limit; use cr inventory or open manually',
+    null,
+    {
+      idempotency_scan: {
+        pages: pagesScanned,
+        max_pages: MAX_OPEN_PULL_IDEMPOTENCY_PAGES,
+        page_size: pageSizeUsed,
+      },
+    },
+  );
+}
 
 export async function giteaFetchPaginated(config, parsed, path) {
   return paginateCheckStatusPages({
@@ -222,13 +268,27 @@ export function providerCapabilities() {
     mergeability_confidence: 'direct',
     host_binding: 'verified_remote_host',
     pagination: 'supported',
-    write_support: false,
+    write_support: true,
+    write_commands: ['cr_open'],
     ...forgeIngestCapabilityFacts(),
     ...checkPaginationCapabilityFacts({
       strategy: 'offset_limit',
       pageSizeParam: 'limit',
       sourceCount: check_sources.length,
     }),
+    ...idempotencyScanCapabilityFacts(),
+    ...openPullListCapabilityFacts({
+      totalCountSource: 'response_header',
+      totalCountHeader: 'X-Total-Count',
+      sliceSortNotes: {
+        recent_created:
+          'sort=oldest; fetches tail page when total exceeds limit; page reversed for newest-first',
+        number_asc:
+          'full-list collect within compliant_max when total exceeds limit, then client sort',
+        number_desc:
+          'full-list collect within compliant_max when total exceeds limit, then client sort',
+      },
+    }),
   };
 }
 
@@ -261,37 +321,273 @@ export async function getPull(ctx, { number }) {
   return giteaFetch(ctx.config, ctx.parsed, repoApiPath(ctx.config, 'pulls', number));
 }
 
-export async function listOpenPullsWithMeta(ctx, opts = {}) {
+/** Paginated open-pull scan for idempotent cr open; fail-closed when scan cap prevents proof of absence. */
+export async function findOpenPullByHeadBase(ctx, head, base) {
   requireToken();
+  const path = `${repoApiPath(ctx.config, 'pulls')}?state=open`;
+  const pageSep = path.includes('?') ? '&' : '?';
+  let activeLimit = GITEA_PAGE_SIZE;
+
+  for (let page = 1; page <= MAX_OPEN_PULL_IDEMPOTENCY_PAGES; page += 1) {
+    const { items, usedLimit } = await fetchPageWithIngestBackoff(
+      async ({ page: pageNum, limit }) => {
+        const body = await giteaFetch(
+          ctx.config,
+          ctx.parsed,
+          `${path}${pageSep}limit=${limit}&page=${pageNum}`,
+        );
+        if (!Array.isArray(body)) {
+          throw Object.assign(new Error('Provider returned non-array open pull list'), {
+            forgeError: forgeError(
+              ERROR_CODES.UNPARSEABLE_PROVIDER_OUTPUT,
+              'Provider returned non-array open pull list',
+            ),
+          });
+        }
+        return body;
+      },
+      page,
+      activeLimit,
+    );
+    activeLimit = usedLimit;
+
+    const match =
+      items.find(
+        (pr) =>
+          String(pr?.state ?? '').toLowerCase() === 'open' &&
+          pr?.head?.ref === head &&
+          pr?.base?.ref === base,
+      ) ?? null;
+    if (match) return match;
+    if (items.length < usedLimit) return null;
+    if (page === MAX_OPEN_PULL_IDEMPOTENCY_PAGES) {
+      throw Object.assign(new Error('Open pull idempotency scan incomplete'), {
+        forgeError: idempotencyScanIncompleteError(page, usedLimit),
+      });
+    }
+  }
+  return null;
+}
+
+export async function crOpen(ctx, { head, base, title, body: prBody }) {
+  assertGitRef(head, 'head');
+  assertGitRef(base, 'base');
+  if (!title || typeof title !== 'string' || !title.trim()) {
+    throw Object.assign(new Error('--title required'), {
+      forgeError: forgeError(ERROR_CODES.INVALID_ARGS, '--title required for cr open'),
+    });
+  }
+  const payload = {
+    title: sanitizeField(title),
+    head: sanitizeField(head),
+    base: sanitizeField(base),
+  };
+  if (prBody != null && String(prBody).trim() !== '') {
+    payload.body = sanitizeField(String(prBody));
+  }
+  const existing = await findOpenPullByHeadBase(ctx, payload.head, payload.base);
+  if (existing) {
+    return buildChangeRequestOpenedBody(existing, { head, base, title }, { reusedExisting: true });
+  }
+  const pull = await giteaFetch(ctx.config, ctx.parsed, repoApiPath(ctx.config, 'pulls'), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+  return buildChangeRequestOpenedBody(pull, { head, base, title });
+}
+
+const GITEA_OPEN_PULL_COMPLIANT_MAX =
+  DEFAULT_OPEN_PULL_LIST_PAGE_SIZE * MAX_CHECK_STATUS_PAGES;
+
+async function probeGiteaOpenPullPageOne(ctx, retainMax, sliceSort) {
+  const maxTrusted = GITEA_OPEN_PULL_COMPLIANT_MAX * 2;
+  let path = `${repoApiPath(ctx.config, 'pulls')}?state=open`;
+  path = appendSortQuery(path, giteaOpenPullSortQuery(sliceSort));
+  const pageSep = path.includes('?') ? '&' : '?';
+  const requestLimit = Math.min(retainMax, GITEA_PAGE_SIZE);
+  try {
+    const { body, headers } = await giteaFetchWithMeta(
+      ctx.config,
+      ctx.parsed,
+      `${path}${pageSep}limit=${requestLimit}&page=1`,
+    );
+    if (!Array.isArray(body)) return null;
+    const totalCount = parseTotalCountHeader(headers, 'X-Total-Count', { maxTrusted });
+    if (totalCount == null) return null;
+    const listTruncated = totalCount > GITEA_OPEN_PULL_COMPLIANT_MAX;
+    return { body, totalCount, listTruncated, requestLimit };
+  } catch {
+    return null;
+  }
+}
+
+function buildGiteaOpenPullMetaFromPage(body, retainMax, sliceSort, totalCount, listTruncated) {
+  const pageItems = prepareGiteaOpenPullPageItems(body, sliceSort);
+  let numbers = orderOpenPullNumbers(pageItems, (pr) => pr?.number, sliceSort);
+  if (numbers.length > retainMax) numbers = numbers.slice(0, retainMax);
+  return buildOpenPullListMeta({
+    totalCount,
+    numbers,
+    listTruncated,
+    sliceSort,
+  });
+}
+
+async function fetchGiteaRecentCreatedTailSlice(ctx, retainMax, sliceSort, totalCount) {
+  const tailPage = giteaRecentCreatedTailPage(totalCount, GITEA_PAGE_SIZE);
+  let path = `${repoApiPath(ctx.config, 'pulls')}?state=open`;
+  path = appendSortQuery(path, giteaOpenPullSortQuery(sliceSort));
+  const pageSep = path.includes('?') ? '&' : '?';
+  let body;
+  try {
+    body = await giteaFetch(
+      ctx.config,
+      ctx.parsed,
+      `${path}${pageSep}limit=${GITEA_PAGE_SIZE}&page=${tailPage}`,
+    );
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(body) || body.length === 0) return null;
+  return buildGiteaOpenPullMetaFromPage(body, retainMax, sliceSort, totalCount, false);
+}
+
+function giteaProbePaginationOpts(probe, extra = {}) {
+  const { body, totalCount, requestLimit } = probe;
+  return {
+    trustedTotalCount: totalCount,
+    seededFirstPage: { items: body, usedLimit: requestLimit },
+    ...extra,
+  };
+}
+
+async function paginateGiteaOpenPullList(ctx, opts, sliceSort, paginationOpts = {}) {
+  const {
+    trustedTotalCount = null,
+    numberSortFullCollect = false,
+    seededFirstPage = null,
+    startPage = 1,
+    maxPages = MAX_CHECK_STATUS_PAGES,
+    suppressFinalPageProbe = false,
+  } = paginationOpts;
   const listLimit =
     opts.limit != null && Number.isInteger(Number(opts.limit)) && Number(opts.limit) > 0
       ? Number(opts.limit)
       : null;
+  const retainMax =
+    listLimit == null &&
+    opts.retain_max != null &&
+    Number.isInteger(Number(opts.retain_max)) &&
+    Number(opts.retain_max) > 0
+      ? Number(opts.retain_max)
+      : null;
   const pageSize =
     listLimit != null ? Math.min(listLimit, GITEA_PAGE_SIZE) : GITEA_PAGE_SIZE;
-  const path = `${repoApiPath(ctx.config, 'pulls')}?state=open`;
+  let path = `${repoApiPath(ctx.config, 'pulls')}?state=open`;
+  path = appendSortQuery(path, giteaOpenPullSortQuery(sliceSort));
   const pageSep = path.includes('?') ? '&' : '?';
-  const { items: all, list_truncated: listTruncated } = await paginateOffsetListPages({
+  const effectiveRetainMax = numberSortFullCollect ? null : retainMax;
+  const {
+    items: all,
+    list_truncated: listTruncated,
+    entry_count: entryCount,
+    walked_count: walkedCount,
+  } = await paginateOffsetListPages({
     pageSize,
     listLimit,
+    retainMax: effectiveRetainMax,
+    trustedEntryCount: trustedTotalCount,
+    seededFirstPage,
+    startPage,
+    maxPages,
+    suppressFinalPageProbe,
     ...(listLimit != null && pageSize < listLimit ? { maxPagesTruncatesWithLimit: true } : {}),
     fetchPage: async ({ page, limit }) => {
-      const body = await giteaFetch(
-        ctx.config,
-        ctx.parsed,
-        `${path}${pageSep}limit=${limit}&page=${page}`,
-      );
-      return Array.isArray(body) ? body : [];
-    },
-  });
-  let numbers = all
-    .map((pr) => pr.number)
-    .filter((number) => Number.isInteger(number))
-    .sort((a, b) => a - b);
-  if (listLimit != null && numbers.length > listLimit) {
-    numbers = numbers.slice(0, listLimit);
+        const body = await giteaFetch(
+          ctx.config,
+          ctx.parsed,
+          `${path}${pageSep}limit=${limit}&page=${page}`,
+        );
+        return Array.isArray(body) ? body : [];
+      },
+    });
+  let numbers = orderOpenPullNumbers(
+    prepareGiteaOpenPullPageItems(all, sliceSort),
+    (pr) => pr?.number,
+    sliceSort,
+  );
+  const outputCap = listLimit ?? retainMax;
+  if (outputCap != null && numbers.length > outputCap) {
+    numbers = numbers.slice(0, outputCap);
+  }
+  return {
+    numbers,
+    list_truncated: resolveListTruncatedWithTrustedTotal({
+      listTruncated,
+      trustedTotalCount,
+      walkedCount,
+      fullCollect: numberSortFullCollect,
+    }),
+    ...(entryCount != null ? { entry_count: entryCount } : {}),
+    slice_sort: sliceSort,
+  };
+}
+
+export async function listOpenPullsWithMeta(ctx, opts = {}) {
+  requireToken();
+  const sliceSort = normalizeCrInventorySort(opts.sort ?? DEFAULT_CR_INVENTORY_SLICE_SORT);
+  if (!isCrInventoryFastPathEligible(opts)) {
+    return paginateGiteaOpenPullList(ctx, opts, sliceSort);
+  }
+
+  const retainMax = Number(opts.retain_max);
+  const probe = await probeGiteaOpenPullPageOne(ctx, retainMax, sliceSort);
+  if (!probe) {
+    return paginateGiteaOpenPullList(ctx, opts, sliceSort);
+  }
+
+  const { body, totalCount, listTruncated, requestLimit } = probe;
+
+  if (listTruncated) {
+    if (body.length === 0) {
+      return paginateGiteaOpenPullList(ctx, opts, sliceSort, giteaProbePaginationOpts(probe));
+    }
+    return buildGiteaOpenPullMetaFromPage(body, retainMax, sliceSort, totalCount, true);
   }
-  return { numbers, list_truncated: listTruncated };
+
+  if (
+    sliceSort === 'recent_created' &&
+    !isRecentCreatedFastPathEligible(totalCount, retainMax, sliceSort, 'gitea-api')
+  ) {
+    const tail = await fetchGiteaRecentCreatedTailSlice(ctx, retainMax, sliceSort, totalCount);
+    if (tail) return tail;
+    const tailRetry = await fetchGiteaRecentCreatedTailSlice(ctx, retainMax, sliceSort, totalCount);
+    if (tailRetry) return tailRetry;
+    const tailPage = giteaRecentCreatedTailPage(totalCount, GITEA_PAGE_SIZE);
+    return paginateGiteaOpenPullList(ctx, opts, sliceSort, {
+      trustedTotalCount: totalCount,
+      startPage: tailPage,
+      maxPages: tailPage,
+      suppressFinalPageProbe: true,
+    });
+  }
+
+  if (
+    isRecentCreatedFastPathEligible(totalCount, retainMax, sliceSort, 'gitea-api') &&
+    isNumberSortFastPathEligible(totalCount, retainMax, sliceSort) &&
+    validateFastPathPageLength(totalCount, requestLimit, body.length)
+  ) {
+    return buildGiteaOpenPullMetaFromPage(body, retainMax, sliceSort, totalCount, false);
+  }
+
+  const numberSortFullCollect = isNumberSortFullCollectRequired(totalCount, retainMax, sliceSort);
+  return paginateGiteaOpenPullList(
+    ctx,
+    opts,
+    sliceSort,
+    giteaProbePaginationOpts(probe, { numberSortFullCollect }),
+  );
 }
 
 export async function listOpenPulls(ctx, opts = {}) {
@@ -370,13 +666,7 @@ export function summarizeChecks(statuses) {
 export async function mergePlan(ctx, opts) {
   const view = await prView(ctx, opts);
   const checks = await prChecks(ctx, { number: view.pr_number });
-  const blockers = mergeBlockersFromFacts(view, checks);
-  return {
-    pr_number: view.pr_number,
-    mergeability: view.mergeability,
-    checks_conclusion: checks.check_conclusion,
-    blockers,
-  };
+  return buildMergePlanBodyFromFacts(ctx, view, checks, opts);
 }
 
 export async function syncPlan(ctx, remoteName = 'origin') {
@@ -418,4 +708,5 @@ export const provider = {
   prChecks,
   mergePlan,
   syncPlan,
+  crOpen,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remogram/provider-gitea-api",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.4",
   "description": "Gitea REST API forge provider for remogram",
   "type": "module",
   "license": "MIT",
@@ -22,6 +22,6 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@remogram/core": "0.1.0-beta.3"
+    "@remogram/core": "0.1.0-beta.4"
   }
 }