Skip to content

Commit

Permalink
keep an up-to-date documentation and avoid outdated copies of sarif a…
Browse files Browse the repository at this point in the history 
…nd php scripts
  • Loading branch information
@llaville
llaville committed Dec 4, 2024
1 parent b861c91 commit 7f33c70
Show file tree
Hide file tree
Showing 52 changed files with 1,050 additions and 4,121 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
######################################

docs/assets/images/
docs/assets/sarif/
site/

###### Composer dependencies ######
Expand Down
Empty file added docs/assets/sarif/.gitkeep
View file
Empty file.
Empty file added docs/assets/sarif/message/.gitkeep
View file
Empty file.
98 changes: 19 additions & 79 deletions docs/reference/address.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,91 +4,31 @@
An `address` object describes a physical or virtual address,
or a range of addresses, in an “addressable region” (memory or a binary file).

![address object](../assets/images/reference-address.graphviz.svg)
=== ":simple-uml: Graph"

## Example
![address object](../assets/images/reference-address.graphviz.svg)

```json
{
"$schema": "https://json.schemastore.org/sarif-2.1.0.json",
"version": "2.1.0",
"runs": [
{
"tool": {
"driver": {
"name": "CodeScanner",
"semanticVersion": "1.1.2-beta.12",
"informationUri": "https://codeScanner.dev"
}
},
"addresses": [
{
"absoluteAddress": 1024,
"kind": "module",
"name": "Multitool.exe"
},
{
"absoluteAddress": 1400,
"relativeAddress": 376,
"kind": "header",
"name": "Sections",
"offsetFromParent": 376,
"parentIndex": 0
},
{
"absoluteAddress": 1536,
"relativeAddress": 512,
"kind": "section",
"name": ".text",
"offsetFromParent": 136,
"parentIndex": 1
}
],
"results": []
}
]
}
```
=== ":octicons-file-code-16: sarif.json"

## How to generate
> [!TIP]
>
> Generated with following command : `php ./resources/serialize.php address docs/assets/sarif 192`

See full [`examples/address.php`][example-script] script into repository.
```json title="docs/assets/sarif/address.json"
--8<-- "docs/assets/sarif/address.json"
```

> [!NOTE]
> Since release 1.5.0, you may use fluent builders API as alternative.
> See full [`examples/builder/address.php`][example-builder] script into repository.
=== ":simple-php: Simple API"

[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/address.php
[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/address.php
```php title="examples/address.php"
--8<-- "examples/address.php"
```

```php
<?php declare(strict_types=1);
=== ":simple-php: Fluent Builder API"

use Bartlett\Sarif\Definition\Address;
use Bartlett\Sarif\Definition\Run;
> [!NOTE]
> This alternative API is available since release 1.5.0

$address1 = new Address();
$address1->setName('Multitool.exe');
$address1->setKind('module');
$address1->setAbsoluteAddress(1024);

$address2 = new Address();
$address2->setName('Sections');
$address2->setKind('header');
$address2->setParentIndex(0);
$address2->setOffsetFromParent(376);
$address2->setAbsoluteAddress(1400);
$address2->setRelativeAddress(376);

$address3 = new Address();
$address3->setName('.text');
$address3->setKind('section');
$address3->setParentIndex(1);
$address3->setOffsetFromParent(136);
$address3->setAbsoluteAddress(1536);
$address3->setRelativeAddress(512);

$run = new Run($tool);
$run->addAddresses([$address1, $address2, $address3]);

```
```php title="examples/builder/address.php"
--8<-- "examples/builder/address.php"
```
94 changes: 19 additions & 75 deletions docs/reference/artifact.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,87 +3,31 @@

An `artifact` object represents a single artifact.

![artifact object](../assets/images/reference-artifact.graphviz.svg)
=== ":simple-uml: Graph"

## Example
![artifact object](../assets/images/reference-artifact.graphviz.svg)

```json
{
"$schema": "https://json.schemastore.org/sarif-2.1.0.json",
"version": "2.1.0",
"runs": [
{
"tool": {
"driver": {
"name": "CodeScanner",
"semanticVersion": "1.1.2-beta.12",
"informationUri": "https://codeScanner.dev"
}
},
"artifacts": [
{
"location": {
"uri": "file:///C:/Code/app.zip"
},
"mimeType": "application/zip"
},
{
"location": {
"uri": "docs/intro.docx"
},
"mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
},
{
"parentIndex": 1,
"offset": 17522,
"length": 4050,
"mimeType": "application/x-contoso-animation"
}
],
"results": []
}
]
}
```
=== ":octicons-file-code-16: sarif.json"

## How to generate
> [!TIP]
>
> Generated with following command : `php ./resources/serialize.php artifact docs/assets/sarif 192`

See full [`examples/artifact.php`][example-script] script into repository.
```json title="docs/assets/sarif/artifact.json"
--8<-- "docs/assets/sarif/artifact.json"
```

> [!NOTE]
> Since release 1.5.0, you may use fluent builders API as alternative.
> See full [`examples/builder/artifact.php`][example-builder] script into repository.
=== ":simple-php: Simple API"

[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/artifact.php
[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/artifact.php
```php title="examples/artifact.php"
--8<-- "examples/artifact.php"
```

```php
<?php declare(strict_types=1);
=== ":simple-php: Fluent Builder API"

use Bartlett\Sarif\Definition\Artifact;
use Bartlett\Sarif\Definition\ArtifactLocation;
use Bartlett\Sarif\Definition\Run;
> [!NOTE]
> This alternative API is available since release 1.5.0

$artifact1 = new Artifact();
$artifactLocation1 = new ArtifactLocation();
$artifactLocation1->setUri('file:///C:/Code/app.zip');
$artifact1->setLocation($artifactLocation1);
$artifact1->setMimeType('application/zip');

$artifact2 = new Artifact();
$artifactLocation2 = new ArtifactLocation();
$artifactLocation2->setUri('docs/intro.docx');
$artifact2->setLocation($artifactLocation2);
$artifact2->setMimeType('application/vnd.openxmlformats-officedocument.wordprocessingml.document');
$artifact2->setParentIndex(0);

$artifact3 = new Artifact();
$artifact3->setOffset(17522);
$artifact3->setLength(4050);
$artifact3->setMimeType('application/x-contoso-animation');
$artifact3->setParentIndex(1);

$run = new Run($tool);
$run->addArtifacts([$artifact1, $artifact2, $artifact3]);

```
```php title="examples/builder/artifact.php"
--8<-- "examples/builder/artifact.php"
```
92 changes: 19 additions & 73 deletions docs/reference/artifactChange.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,85 +3,31 @@

An `artifactChange` object represents a change to a single artifact.

![artifactChange object](../assets/images/reference-artifact-change.graphviz.svg)
=== ":simple-uml: Graph"

## Example
![artifactChange object](../assets/images/reference-artifact-change.graphviz.svg)

```json
{
"$schema": "https://json.schemastore.org/sarif-2.1.0.json",
"version": "2.1.0",
"runs": [
{
"tool": {
"driver": {
"name": "CodeScanner",
"semanticVersion": "1.1.2-beta.12",
"informationUri": "https://codeScanner.dev"
}
},
"results": [
{
"message": {
"text": "..."
},
"ruleId": "CA1001",
"fixes": [
{
"artifactChanges": [
{
"artifactLocation": {
"uri": "src/a.c"
},
"replacements": [
{
"deletedRegion": {
"startLine": 1,
"startColumn": 1,
"endLine": 1
},
"insertedContent": {
"text": "// "
}
}
]
}
]
}
]
}
]
}
]
}
```
=== ":octicons-file-code-16: sarif.json"

## How to generate
> [!TIP]
>
> Generated with following command : `php ./resources/serialize.php fix docs/assets/sarif 192`

See full [`examples/fix.php`][example-script] script into repository.
```json title="docs/assets/sarif/fix.json"
--8<-- "docs/assets/sarif/fix.json"
```

> [!NOTE]
> Since release 1.5.0, you may use fluent builders API as alternative.
> See full [`examples/builder/fix.php`][example-builder] script into repository.
=== ":simple-php: Simple API"

[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/fix.php
[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/fix.php
```php title="examples/fix.php"
--8<-- "examples/fix.php"
```

```php
<?php declare(strict_types=1);
=== ":simple-php: Fluent Builder API"

use Bartlett\Sarif\Definition\ArtifactChange;
use Bartlett\Sarif\Definition\ArtifactContent;
use Bartlett\Sarif\Definition\ArtifactLocation;
use Bartlett\Sarif\Definition\Region;
use Bartlett\Sarif\Definition\Replacement;
> [!NOTE]
> This alternative API is available since release 1.5.0

$artifactLocation = new ArtifactLocation();
$artifactLocation->setUri('src/a.c');
$replacement = new Replacement(new Region(1, 1, 1));
$insertedContent = new ArtifactContent();
$insertedContent->setText('// ');
$replacement->setInsertedContent($insertedContent);
$artifactChange = new ArtifactChange($artifactLocation, [$replacement]);

```
```php title="examples/builder/fix.php"
--8<-- "examples/builder/fix.php"
```
Loading

0 comments on commit 7f33c70

Please sign in to comment.