URL Parsing and Creation

/**
 * Parse a git URL and return a GitHost instance
 * @param {string} giturl - Git URL to parse
 * @param {object} [opts] - Options object
 * @param {boolean} [opts.noCommittish] - Exclude committish from generated URLs
 * @param {boolean} [opts.noGitPlus] - Exclude 'git+' prefix from URLs
 * @returns {GitHost|undefined} GitHost instance or undefined if URL cannot be parsed
 */
static fromUrl(giturl, opts);

const hostedGitInfo = require("hosted-git-info");

// GitHub HTTPS URL
const info1 = hostedGitInfo.fromUrl("https://github.com/npm/hosted-git-info.git");
// Result: GitHost { type: 'github', user: 'npm', project: 'hosted-git-info' }

// GitHub SSH URL
const info2 = hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git");
// Result: same as above

// GitHub shortcut
const info3 = hostedGitInfo.fromUrl("github:npm/hosted-git-info");
// Result: same as above

// GitHub extreme shorthand (npm packages only)
const info4 = hostedGitInfo.fromUrl("npm/hosted-git-info");
// Result: same as above

// With committish (branch/tag/commit)
const info5 = hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git#v1.0.0");
// Result: GitHost with committish: 'v1.0.0'

// With options
const info6 = hostedGitInfo.fromUrl("git@github.com:npm/hosted-git-info.git", {
  noCommittish: true,
  noGitPlus: true
});

// Invalid/unrecognized URLs return undefined
const info7 = hostedGitInfo.fromUrl("not-a-git-url");
// Result: undefined

/**
 * Parse repository URL from package manifest
 * @param {object} manifest - Package manifest object
 * @param {object} [opts] - Options object
 * @returns {GitHost|string|null} GitHost instance, URL string, or null
 */
static fromManifest(manifest, opts);

const hostedGitInfo = require("hosted-git-info");

// Manifest with repository string
const manifest1 = {
  repository: "git+https://github.com/npm/hosted-git-info.git"
};
const info1 = hostedGitInfo.fromManifest(manifest1);
// Result: GitHost instance

// Manifest with repository object
const manifest2 = {
  repository: {
    type: "git",
    url: "https://github.com/npm/hosted-git-info.git"
  }
};
const info2 = hostedGitInfo.fromManifest(manifest2);
// Result: GitHost instance

// Manifest with no repository field
const manifest3 = {};
try {
  const info3 = hostedGitInfo.fromManifest(manifest3);
} catch (error) {
  console.log(error.message); // "no repository"
}

// Manifest with unrecognized repository URL
const manifest4 = {
  repository: "https://example.com/some-repo.git"
};
const info4 = hostedGitInfo.fromManifest(manifest4);
// Result: URL string if it can be normalized, or null

/**
 * Parse URL into components
 * @param {string} url - URL to parse
 * @returns {object|undefined} Parsed URL object or undefined if invalid
 */
static parseUrl(url);

const hostedGitInfo = require("hosted-git-info");

// Parse a git URL
const parsed = hostedGitInfo.parseUrl("git@github.com:npm/hosted-git-info.git#v1.0.0");
// Result: URL-like object with protocol, hostname, pathname, hash, etc.

// Parse HTTPS URL
const parsed2 = hostedGitInfo.parseUrl("https://github.com/npm/hosted-git-info/tree/main");
// Result: URL object with parsed components

// Invalid URLs return undefined
const parsed3 = hostedGitInfo.parseUrl("not-a-url");
// Result: undefined

// HTTPS with auth
const info1 = hostedGitInfo.fromUrl("https://user:token@github.com/user/repo.git");
// Result: GitHost with auth: 'user:token'

// SSH with auth (ignored for shortcuts)
const info2 = hostedGitInfo.fromUrl("github:user:password@user/repo");
// Result: GitHost with auth: null (auth ignored in shortcuts)

/**
 * Add a custom host configuration
 * @param {string} name - Host name identifier
 * @param {object} host - Host configuration object
 */
static addHost(name, host);

const hostedGitInfo = require("hosted-git-info");

// Define a custom host configuration
const customHost = {
  protocols: ['git+ssh:', 'git+https:', 'ssh:', 'https:'],
  domain: 'git.example.com',
  treepath: 'tree',
  blobpath: 'blob',
  editpath: 'edit',
  // Template functions for URL generation
  httpstemplate: ({ domain, user, project, committish }) =>
    `git+https://${domain}/${user}/${project}.git${committish ? '#' + committish : ''}`,
  sshtemplate: ({ domain, user, project, committish }) =>
    `git@${domain}:${user}/${project}.git${committish ? '#' + committish : ''}`,
  browsetemplate: ({ domain, user, project, committish }) =>
    `https://${domain}/${user}/${project}${committish ? '/tree/' + committish : ''}`,
  bugstemplate: ({ domain, user, project }) =>
    `https://${domain}/${user}/${project}/issues`,
  // Extraction function for parsing URLs
  extract: (url) => {
    const [, user, project] = url.pathname.split('/', 3);
    if (!user || !project) return null;
    return {
      user,
      project: project.replace(/\.git$/, ''),
      committish: url.hash.slice(1) || null
    };
  }
};

// Add the custom host
hostedGitInfo.addHost('example', customHost);

// Now URLs from the custom host can be parsed
const info = hostedGitInfo.fromUrl('https://git.example.com/user/repo.git#main');
console.log(info.type);     // "example"
console.log(info.domain);   // "git.example.com"
console.log(info.browse()); // "https://git.example.com/user/repo/tree/main"

// Shortcut support is automatically added
const info2 = hostedGitInfo.fromUrl('example:user/repo');
console.log(info2.type);    // "example"