Extend CLI with argument to configure linking behaviour (local IDE vs CVS)

[BioPhoton]

Precondition:

• Issues sections should link to local file in your IDE at given commit with highlighted line(s) #745
• Issues sections should link to Git URL of file at given commit with highlighted line(s) #722

User story

As a user of the CLI I want to have click through experience for all actionable feedback a get from the audit issues.

At the moment no linking is present. What I need is a way to generate links depending on the current usecase.

• A) The report is located in your local file system
• B) The report is generate in the CI and added to a PR comment
• C) The report is checked in and lives in the repository

CLI argument Example:

• npx @code-pushup collect - links in IDE
• npx @code-pushup collect --git.host=https://my-github.com/repo-name --git.provider=github - links to git

Acceptance criteria

• The models package
• The CLI accepts the new git options
• By default the report links to the local filesystem. If the link is clicked you the fie is opened in the local IDE
• Over a configuration setting or terminal argument we can tell the CLI to generate links targeting another environment.
  • If the configuration targets a local setup the first criteria applies
  • If the the configuration targets a git-version e.g. GitLab, GitHub the URLs should get auto discovered
    • If the server and git-version cant get autodetected we don't apply a link

Implementation details

PersistConfig Example:

type GitConfig = {
  // skipped means local, otherwise remote
  git?: {
    provider: 'GitHub' | 'GitLab';
    host?: string; // for self-hosted only, defaults to https://github.com or https://gitlab.com
  }
}

const GitConfigSchema = z.object({
  git: z
    .object({
      provider: z.enum(['GitHub', 'GitLab']),
      host: z.string().url().optional(), // Optional host field with URL validation
    })
    .optional(), // git itself is optional
});

type ReportOptions = { 
  sourceLinkFormatter: (source?: SourceFileLocation) => string
}

const sourceLinkFormatter = coreConfig.git ? ideLinkFn : cvsLinkFn;

const mdReport = generateMdReport(report: Report, options: ReportOptions) {
   // 
}

Related Issues:

#149

[matejchalk]

I'd change the naming, no idea what cv or CVS is - I guess you mean VCS (Version Control System)? I'm not sure how many people are familiar with that term, so I'd go with "git" or "repo" instead (it's not like we support Mercurial 😁).

Also, we only need the extra information when it's remote, for local we don't need anything. So how about this?

type PersistConfig = {
  // skipped means local, otherwise remote
  git?: {
    provider: 'GitHub' | 'GitLab';
    host?: string; // for self-hosted only, defaults to https://github.com or https://gitlab.com
  }
}

[BioPhoton]

Thx for the suggestion! Was not done with fully documenting the solution but I like it!!! Will update the issue! 🙏

Wouldn't it be possible to detect the provider?
provider: 'GitHub' | 'GitLab'; => provider?: 'GitHub' | 'GitLab';

[matejchalk]

Wouldn't it be possible to detect the provider?
provider: 'GitHub' | 'GitLab'; => provider?: 'GitHub' | 'GitLab';

I suppose. But in that case, we'd need another way to differentiate local from remote. My thinking was that local would be the implicit default, but for remote you'd have to fill in something, so there needs to be a required prop - "if you want remote links, tell us who/where your remote is" seemed reasonable 😁

Having an explicit prop for remote or local as you suggested would also work, but then I would adjust the types since the provider and host are useless if local:

type PersistConfig = {
  //... 
  git?: GitConfig
} 

type GitConfig = {
  links: 'local'
} | {
  links: 'remote', 
  provider?: 'GitHub' | 'GitLab', 
  host?: string
} 

[BioPhoton]

"if you want remote links, tell us who/where your remote is" seemed reasonable 😁

As my plan is to prepare those issues for newcomer i'll go with the static version as less code.

[hanna-skryl]

After implementing the features outlined in the preconditions for this issue, it is now considered resolved and, therefore, irrelevant. Reports are now enriched with links based on the available environment variables. Specifically:

• CI-generated reports include links to GitHub/GitLab.
• Locally generated reports link to the local filesystem.