feat: add structured error codes (PLB-XXXX) with documentation links

[stephrobert]

Summary

Add structured error codes (PLB-XXXX) to every issue detected by Plumber, with direct links to dedicated documentation pages.

Changes

New file

• control/codes.go — Central error code registry with 14 codes (PLB-0101 to PLB-0501), ErrorCode type, ErrorCodeInfo struct, and lookup/listing functions

Modified files

• control/types.go — Added Code ErrorCode and DocURL string fields to issue structs
• cmd/analyze.go — Display [PLB-XXXX] prefix on each issue line + ↳ docs: link + Codes column in summary table
• control/mrcomment.go — Include error codes and doc links in MR comments
• 10 control files — Assign error codes to all issue creation points

Error Codes

Code	Issue	Control
PLB-0101	Forbidden image tag	containerImageMustNotUseForbiddenTags
PLB-0102	Image not pinned by digest	containerImageMustNotUseForbiddenTags
PLB-0103	Unauthorized image source	containerImageMustComeFromAuthorizedSources
PLB-0201	Branch not protected	branchMustBeProtected
PLB-0202	Non-compliant branch protection	branchMustBeProtected
PLB-0301	Hardcoded job	pipelineMustNotIncludeHardcodedJobs
PLB-0302	Outdated include version	includesMustBeUpToDate
PLB-0303	Forbidden include version	includesMustNotUseForbiddenVersions
PLB-0401	Required component missing	pipelineMustIncludeComponent
PLB-0402	Required component overridden	pipelineMustIncludeComponent
PLB-0403	Required template missing	pipelineMustIncludeTemplate
PLB-0404	Required template overridden	pipelineMustIncludeTemplate
PLB-0501	Debug trace enabled	pipelineMustNotEnableDebugTrace

CLI Output Example

[PLB-0101] Job "build" uses image "node:latest" with forbidden tag "latest"
  ↳ docs: https://getplumber.io/e/PLB-0101

Summary table now includes a Codes column with links to documentation.

Documentation

Companion PR for doc pages: getplumber/getplumber.io#77

Closes #92

[Joseph94m]

Hello @stephrobert , thanks for the contribution.

• I did the tests and the review and it seems good
• I rebased on main which contains a new control and updated that new control to receive this branch's updates.
• If you want to perform any more operations on this branch, you have to pull --rebase

I have 1 question about the PR:

For example in the following configuration found in codes.go, we only ever use the Code and the DocURL in the codebase. Do you intended to use the other fields such as description and remediation?

	CodeDebugTraceEnabled: {
		Code:        CodeDebugTraceEnabled,
		Title:       "Debug trace enabled",
		Description: "The pipeline has CI_DEBUG_TRACE or CI_DEBUG_SERVICES enabled, which exposes all secret variables in the job log output. This is a critical security risk in production pipelines.",
		Remediation: "Remove or set CI_DEBUG_TRACE and CI_DEBUG_SERVICES to 'false' in your .gitlab-ci.yml variables section. These should only be used temporarily for debugging and never committed.",
		DocURL:      docsBaseURL + string(CodeDebugTraceEnabled),
		ControlName: "pipelineMustNotEnableDebugTrace",
	},

Also, for commits. use feat(scope): notation instead of feat: . In this case, the scope would have been analysis

[Joseph94m]

Activated branch protection and copilot should review

[Copilot]

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

[Joseph94m]

@copilot code review[agent] review please