ConvertTo‑ShpAnnotation

SYNOPSIS

Converts a structured finding into a CI annotation command.

SYNTAX

ConvertTo-ShpAnnotation [-InputObject] <Object> [[-PropertyMap] <Hashtable>] [[-Format] <String>] [-Emit]
 [-Summary] [<CommonParameters>]

DESCRIPTION

Accepts a ShellPilot result or a plain finding object from the pipeline and returns a GitHub Actions, Azure DevOps, or readable text annotation. A ShellPilot result is unwrapped through its ContentObject member. If ContentObject is an array, one annotation is produced per finding.

Finding properties are read case-insensitively. By default the cmdlet reads Level, Path, Line, Column, Title, and Message. PropertyMap changes the source property for any of those canonical names, for example @{ Level = 'severity'; Message = 'detail' }.

Error, Warning, and Notice are recognized without regard to case. GitHub Actions supports all three. Azure DevOps accepts only error and warning, so Notice becomes warning there. Every missing or unknown level also becomes warning; malformed model output must not create an error annotation by accident.

Without Format, GITHUB_ACTIONS is checked first, then TF_BUILD. If neither variable is set, Text is used. Strings are returned by default. Emit writes each annotation to the host stream instead.

EXAMPLES

EXAMPLE 1

$schema = @{
    type = 'object'
    required = @('Level', 'Message')
    properties = @{
        Level = @{ type = 'string' }
        Path = @{ type = 'string' }
        Line = @{ type = 'integer' }
        Column = @{ type = 'integer' }
        Title = @{ type = 'string' }
        Message = @{ type = 'string' }
    }
} | ConvertTo-Json -Depth 5 -Compress

Invoke-Shp -Prompt 'Review the staged changes.' -JsonSchema $schema | ConvertTo-ShpAnnotation -Emit

Requests one structured finding, unwraps ContentObject from the ShellPilot result, auto-detects the CI vendor, and emits the annotation.

EXAMPLE 2

$map = @{ Level = 'severity'; Path = 'file'; Message = 'detail' }
$findings | ConvertTo-ShpAnnotation -PropertyMap $map -Format Text

Formats objects from a caller-specific schema as readable text.

PARAMETERS

-Emit

Writes each formatted annotation to the host stream instead of returning it to the success stream.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Format

GitHubActions, AzureDevOps, or Text. When omitted, a non-empty GITHUB_ACTIONS variable selects GitHubActions; otherwise a non-empty TF_BUILD variable selects AzureDevOps; otherwise Text is used.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-InputObject

A ShellPilot.Result or a plain object containing one finding. Accepts pipeline input. A ShellPilot result's ContentObject may contain one finding or an array of findings.

Type: Object
Parameter Sets: (All)
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-PropertyMap

Maps canonical finding names to property names in the input schema. Unspecified entries retain their defaults. For example, @{ Level = 'severity'; Path = 'file'; Message = 'detail' }.

Type: Hashtable
Parameter Sets: (All)
Aliases:

Required: False
Position: 2
Default value: @{}
Accept pipeline input: False
Accept wildcard characters: False

-Summary

Appends the findings as a Markdown table to the file named by GITHUB_STEP_SUMMARY when that environment variable is set.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

System.String

One annotation per finding. Emit writes to the host stream instead.

NOTES

RELATED LINKS

Invoke-Shp

https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands

https://learn.microsoft.com/azure/devops/pipelines/scripts/logging-commands