Result Structure: ResolverResult and AggregatedResult

Every resolved source produces a typed output object that captures both what was found and how confident GitResolve is about the result. When you call scrapePortfolio or parseResume directly, you receive a ResolverResult for that single source. When you run the CLI in batch mode across multiple inputs for the same candidate, each candidate’s sources are merged into an AggregatedResult. Understanding the shape of these objects — including what goes into warnings, when error appears, and how ownedRepos differs from externalRepos — lets you build reliable downstream logic on top of GitResolve’s output.

TypeScript import

import type {
  ResolverResult,
  ExtractedGitLink,
  InputType,
  GitProvider,
  GitLinkType,
} from "@clyrisai/gitresolve";

AggregatedResult is defined in the source type system but is not exported from the package index. It is used internally by the CLI when merging multiple sources for a single candidate. You cannot import it directly from @clyrisai/gitresolve in your own code.

ResolverResult

ResolverResult is the return type of both scrapePortfolio and parseResume. It contains everything GitResolve found about one source input.

source

string

required

The original input string — the URL that was scraped, or the file path that was parsed. Preserved exactly as passed in.

sourceType

InputType

required

The InputType for this source. One of 'repo_url', 'git_profile', 'portfolio', 'resume_file', 'resume_url', 'linkedin', or 'unknown'. For most sources this is the value returned by classifyInput; the CLI sets 'resume_url' when it downloads a remote PDF before parsing. See Input Classification for the full decision logic.

ownerProfile

ExtractedGitLink | null

required

The resolved git profile for the candidate, or null if no owner could be determined. When confidence is 'none', this field is always null. See ExtractedGitLink below for the shape of this object.

confidence

'high' | 'medium' | 'low' | 'none'

required

How certain GitResolve is about the ownerProfile attribution. See the confidence levels table for the full meaning of each level.

ownedRepos

ExtractedGitLink[]

required

Repository links where link.username matches the resolved owner (case-insensitive). These are repos the candidate owns. Deduplicated by URL.

contributions

ExtractedGitLink[]

required

Links with type === 'pull_request' or type === 'issue'. These represent explicit contribution activity found in the source. Deduplicated by URL.

externalRepos

ExtractedGitLink[]

required

Repository links owned by someone other than the resolved owner. These may be libraries depended on, employer repositories, or open-source projects the candidate referenced without owning. Deduplicated by URL.

allLinks

ExtractedGitLink[]

required

The complete, unfiltered set of every parsed git link found in the source — profiles, repos, gists, PRs, issues, and other link types combined. Use this for custom filtering or auditing the raw extraction output.

warnings

string[]

required

Non-fatal diagnostic messages logged during processing. This includes the browser provider used, disambiguation decisions and rationale, and edge-case flags. See The warnings array for a full description.

error

string

Present only when a fatal error occurred during processing — for example, a network failure fetching the portfolio URL, or a file read error on a resume path. When error is set, the other fields (ownedRepos, allLinks, etc.) will be empty arrays and confidence will be 'none'. See The error field for details.

ExtractedGitLink

ExtractedGitLink is the atomic unit of every link GitResolve extracts. It appears in ownerProfile, ownedRepos, contributions, externalRepos, and allLinks.

url

string

required

The canonical URL for this link. For repos, this is the normalized form https://{host}/{owner}/{repo}. For PRs and issues, the raw URL (including the PR/issue number path) is preserved. For synthetic profile links (created in Case 3 of disambiguation), this is https://{host}/{username}.

provider

GitProvider

required

The git hosting platform. One of 'github', 'gitlab', or 'bitbucket'.

type

GitLinkType

required

The kind of resource this link points to. See the GitLinkType values table below.

username

string

required

The username or organization name extracted from the URL path. Used for all ownership matching. Matching is always performed case-insensitively.

repo

string

The repository name. Present when type is 'repo', 'pull_request', or 'issue'. Absent for 'profile' and 'gist' links.

number

string

The PR or issue number as a string. Present only when type is 'pull_request' or 'issue'.

GitLinkType values

Value	Description
`profile`	A user or organization profile page (e.g. `github.com/janedoe`)
`repo`	A repository root (e.g. `github.com/janedoe/my-project`)
`gist`	A GitHub Gist (e.g. `gist.github.com/janedoe/abc123`)
`pull_request`	A pull request or merge request URL including a numeric ID
`issue`	An issue URL including a numeric ID
`other`	A valid git host URL that did not match any of the above patterns

AggregatedResult

AggregatedResult is not exported from the @clyrisai/gitresolve package index and cannot be imported directly. It is an internal type used by the CLI. The field reference below documents its shape for CLI output consumers and contributors only.

AggregatedResult is the output type for CLI batch runs where multiple source inputs (a portfolio URL, a resume PDF, a repo URL) are resolved together for a single candidate. GitResolve merges the individual ResolverResult objects, deduplicates links across sources, and picks the highest-confidence owner profile. Note that unlike ResolverResult, AggregatedResult has no error field — errors are captured on individual ResolverResult objects before aggregation.

candidateUsername

string | null

required

The final resolved username for this candidate, or null if no owner could be determined across any source. Derived from ownerProfile.username.

sources

string[]

required

All input strings that were resolved and merged into this aggregate. For example ["https://janedoe.dev", "./resumes/janedoe.pdf"].

sourceTypes

InputType[]

required

The InputType value for each entry in sources, in the same order.

ownerProfile

ExtractedGitLink | null

required

The best owner profile resolved across all sources. When one source yields confidence: 'high', that profile wins. When all sources are lower confidence, the first resolved profile is used.

confidence

'high' | 'medium' | 'low' | 'none'

required

The highest confidence level achieved across all merged sources.

ownedRepos

ExtractedGitLink[]

required

Deduplicated union of ownedRepos from all sources, filtered to the resolved owner.

contributions

ExtractedGitLink[]

required

Deduplicated union of contributions from all sources.

externalRepos

ExtractedGitLink[]

required

Deduplicated union of externalRepos from all sources.

allLinks

ExtractedGitLink[]

required

Deduplicated union of allLinks from all sources.

warnings

string[]

required

Combined warnings from all merged ResolverResult objects.

Confidence levels

Level	Meaning
`high`	The owner was determined with certainty — either from a direct `git_profile`/`repo_url` input, a single unambiguous profile link, or a clear repo-count majority when multiple profiles were present.
`medium`	The owner was inferred rather than directly identified. In Case 2 (multiple profiles), this means two profiles tied for the highest repo count. In Case 3 (no profiles), this means the owner was inferred from repo-username frequency — either all repos share one username, or one username clearly dominates.
`low`	The owner is a best guess — profiles or repos were found but evidence was tied or contradictory. The first candidate was picked, but downstream code should treat this result with caution.
`none`	No git links were found at all, or the source was a type that cannot be resolved (e.g. `linkedin`). `ownerProfile` is `null`.

The warnings array

The warnings array is always present (never undefined) and collects non-fatal diagnostic messages logged throughout processing. These messages are useful for debugging scraper output and understanding disambiguation decisions. Common warnings you will encounter:

Warning message pattern	When it appears
`Used fetch provider (SPA rendering layer …)`	Portfolio was fetched with the fallback `fetch` provider; a headless browser was not available
`Used {name} provider for page content`	Portfolio was fetched with a named browser provider (e.g. Puppeteer, Browserless)
`Found {n} git URL(s) in text content`	Resume text extraction found git URLs
`Text extraction failed: {message}`	The `unpdf` text pass failed; annotation extraction may still succeed
`Annotation extraction failed: {message}`	The `unpdf` annotation pass failed
`Owner strictly determined by profile URL input: {username}`	`knownOwnerProfile` was provided; algorithm was bypassed
`Multiple profile links found: {usernames}`	Case 2 disambiguation was triggered
`Owner determined by repo cross-reference: {scores}`	Case 2 resolved to `high` confidence via repo count comparison
`⚠ Tied repo ownership between profiles: {scores}. Picked {username}.`	Case 2 ended in a tie; `medium` confidence
`None of the profile links match any repo owner — picking first profile`	Case 2 found profiles but zero matching repos; `low` confidence
`Multiple profiles found but no repos to cross-reference — picking first`	Case 2 with no repos at all; `low` confidence
`No profile link found — all repos belong to same user, inferred as owner`	Case 3 single username; `medium` confidence
`No profile link found — inferred from repo majority: {counts}`	Case 3 dominant username; `medium` confidence
`No profile link found — tied repo ownership: {counts}. Picked {username}.`	Case 3 tie; `low` confidence
`No git links found`	Case 4; `confidence: 'none'`

The error field

The error field on ResolverResult is only present when a fatal, unrecoverable exception occurred. It is absent (undefined) on successful runs — even runs that produced zero links. Conditions that set error:

Network failure — the portfolio URL timed out or returned a non-recoverable HTTP error
File system error — the resume file path does not exist or cannot be read
Unexpected exception — any other unhandled error thrown inside the scraper or parser

When error is set, ownerProfile is null, confidence is 'none', and all link arrays (ownedRepos, allLinks, etc.) are empty. The warnings array may still contain partial diagnostic output from before the error occurred.

Partial extraction failures — such as one PDF parsing pass failing while the other succeeds — are reported in warnings, not error. An error value means the entire source could not be processed.

JSON examples

ResolverResult example

Show Full ResolverResult JSON

{
  "source": "https://janedoe.dev",
  "sourceType": "portfolio",
  "ownerProfile": {
    "url": "https://github.com/janedoe",
    "provider": "github",
    "type": "profile",
    "username": "janedoe"
  },
  "confidence": "high",
  "ownedRepos": [
    {
      "url": "https://github.com/janedoe/api-server",
      "provider": "github",
      "type": "repo",
      "username": "janedoe",
      "repo": "api-server"
    },
    {
      "url": "https://github.com/janedoe/portfolio-site",
      "provider": "github",
      "type": "repo",
      "username": "janedoe",
      "repo": "portfolio-site"
    }
  ],
  "contributions": [
    {
      "url": "https://github.com/torvalds/linux/pull/99",
      "provider": "github",
      "type": "pull_request",
      "username": "torvalds",
      "repo": "linux",
      "number": "99"
    }
  ],
  "externalRepos": [
    {
      "url": "https://github.com/expressjs/express",
      "provider": "github",
      "type": "repo",
      "username": "expressjs",
      "repo": "express"
    }
  ],
  "allLinks": [
    {
      "url": "https://github.com/janedoe",
      "provider": "github",
      "type": "profile",
      "username": "janedoe"
    },
    {
      "url": "https://github.com/janedoe/api-server",
      "provider": "github",
      "type": "repo",
      "username": "janedoe",
      "repo": "api-server"
    },
    {
      "url": "https://github.com/janedoe/portfolio-site",
      "provider": "github",
      "type": "repo",
      "username": "janedoe",
      "repo": "portfolio-site"
    },
    {
      "url": "https://github.com/torvalds/linux/pull/99",
      "provider": "github",
      "type": "pull_request",
      "username": "torvalds",
      "repo": "linux",
      "number": "99"
    },
    {
      "url": "https://github.com/expressjs/express",
      "provider": "github",
      "type": "repo",
      "username": "expressjs",
      "repo": "express"
    }
  ],
  "warnings": [
    "Used puppeteer provider for page content",
    "Owner strictly determined by profile URL input: janedoe"
  ]
}

AggregatedResult example

Show Full AggregatedResult JSON

{
  "candidateUsername": "janedoe",
  "sources": [
    "https://janedoe.dev",
    "./resumes/jane_doe.pdf"
  ],
  "sourceTypes": [
    "portfolio",
    "resume_file"
  ],
  "ownerProfile": {
    "url": "https://github.com/janedoe",
    "provider": "github",
    "type": "profile",
    "username": "janedoe"
  },
  "confidence": "high",
  "ownedRepos": [
    {
      "url": "https://github.com/janedoe/api-server",
      "provider": "github",
      "type": "repo",
      "username": "janedoe",
      "repo": "api-server"
    },
    {
      "url": "https://github.com/janedoe/portfolio-site",
      "provider": "github",
      "type": "repo",
      "username": "janedoe",
      "repo": "portfolio-site"
    },
    {
      "url": "https://github.com/janedoe/data-pipeline",
      "provider": "github",
      "type": "repo",
      "username": "janedoe",
      "repo": "data-pipeline"
    }
  ],
  "contributions": [
    {
      "url": "https://github.com/torvalds/linux/pull/99",
      "provider": "github",
      "type": "pull_request",
      "username": "torvalds",
      "repo": "linux",
      "number": "99"
    }
  ],
  "externalRepos": [
    {
      "url": "https://github.com/expressjs/express",
      "provider": "github",
      "type": "repo",
      "username": "expressjs",
      "repo": "express"
    }
  ],
  "allLinks": [
    {
      "url": "https://github.com/janedoe",
      "provider": "github",
      "type": "profile",
      "username": "janedoe"
    },
    {
      "url": "https://github.com/janedoe/api-server",
      "provider": "github",
      "type": "repo",
      "username": "janedoe",
      "repo": "api-server"
    },
    {
      "url": "https://github.com/janedoe/portfolio-site",
      "provider": "github",
      "type": "repo",
      "username": "janedoe",
      "repo": "portfolio-site"
    },
    {
      "url": "https://github.com/janedoe/data-pipeline",
      "provider": "github",
      "type": "repo",
      "username": "janedoe",
      "repo": "data-pipeline"
    },
    {
      "url": "https://github.com/torvalds/linux/pull/99",
      "provider": "github",
      "type": "pull_request",
      "username": "torvalds",
      "repo": "linux",
      "number": "99"
    },
    {
      "url": "https://github.com/expressjs/express",
      "provider": "github",
      "type": "repo",
      "username": "expressjs",
      "repo": "express"
    }
  ],
  "warnings": [
    "Used puppeteer provider for page content",
    "Owner strictly determined by profile URL input: janedoe",
    "Found 2 git URL(s) in text content"
  ]
}

Input Classification

How every input is categorized before processing begins

Disambiguation

How GitResolve resolves ambiguous link sets to a single owner

Get Started

CLI Guide

Browser Providers

Concepts

Result Structure: ResolverResult and AggregatedResult

TypeScript import

ResolverResult

ExtractedGitLink

GitLinkType values

AggregatedResult

Confidence levels

The warnings array

The error field

JSON examples

ResolverResult example

AggregatedResult example

Input Classification

Disambiguation

Build docs developers (and LLMs) love

Get Started

CLI Guide

Browser Providers

Concepts

Documentation Index

​TypeScript import

​ResolverResult

​ExtractedGitLink

​GitLinkType values

​AggregatedResult

​Confidence levels

​The warnings array

​The error field

​JSON examples

​ResolverResult example

​AggregatedResult example

Input Classification

Disambiguation

Build docs developers (and LLMs) love

TypeScript import

ResolverResult

ExtractedGitLink

GitLinkType values

AggregatedResult

Confidence levels

The warnings array

The error field

JSON examples

ResolverResult example

AggregatedResult example