Skip to content

Update documentation for 2025 model updates. #637

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Jun 6, 2025
Merged

Update documentation for 2025 model updates. #637

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
00204cf
Remove custom_components option from documentation as it is obsolete.
Mar 19, 2025
c6bd2a4
Update JSOn fields.
Mar 31, 2025
c0e8a72
Merge branch 'main' into aq-model-2025
dennis-sig Jun 2, 2025
61b7476
Merge branch 'main' into aq-model-2025
dennis-sig Jun 2, 2025
42795e4
Merge branch 'main' into aq-model-2025
dennis-sig Jun 4, 2025
637dd60
Remove alerts section.
Jun 4, 2025
dbec7c6
Fixed test.
Jun 4, 2025
5b1a8d5
Better error message.
Jun 4, 2025
5bb9722
Simplify checkmarx schema.
Jun 4, 2025
788405f
Merge branch 'main' into aq-model-2025
dennis-sig Jun 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 11 additions & 23 deletions docs/reference/analysis-scope-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -273,31 +273,19 @@ Architecture Quality is available by default. However, you can still use the var

The `architecture` section of the scope file supports the following options:

| Option | Required | Description |
|----------------------------|----------|------------------------------------------------------------------------------------------|
| `model` | No | SIG Architecture Quality Model that should be used for the analysis, defaults to latest. |
| `exclude` | No | See [Excluding files and directories for Architecture Quality](#excluding-files-and-directories-for-architecture-quality). |
| `custom_components` | No | See [Components in Maintainability versus components in Architecture Quality](#components-in-maintainability-versus-components-in-architecture-quality). |
| `add_dependencies` | No | See [Manually specifying architecture dependencies](#manually-specifying-architecture-dependencies). |
| `remove_dependencies` | No | See [Manually specifying architecture dependencies](#manually-removing-architecture-dependencies). |
| `undesirable_dependencies` | No | See [Highlighting undesirable dependencies](#highlighting-undesirable-dependencies). |
| `add_system_elements` | No | See [Manually specifying architecture elements](#manually-specifying-architecture-elements). |
| Option | Required | Description |
|----------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------|
| `model` | No | SIG Architecture Quality Model that should be used for the analysis, defaults to latest. |
| `exclude` | No | See [Excluding files and directories for Architecture Quality](#excluding-files-and-directories-for-architecture-quality). |
| `add_dependencies` | No | See [Manually specifying architecture dependencies](#manually-specifying-architecture-dependencies). |
| `remove_dependencies` | No | See [Manually specifying architecture dependencies](#manually-removing-architecture-dependencies). |
| `undesirable_dependencies` | No | See [Highlighting undesirable dependencies](#highlighting-undesirable-dependencies). |
| `add_system_elements` | No | See [Manually specifying architecture elements](#manually-specifying-architecture-elements). |
| `grouping` | No | See [Grouping and annotating components in Architecture Quality](#grouping-and-annotating-components-in-architecture-quality). |
| `history_period_months` | No | See [Analyzing your repository history](#analyzing-your-repository-history). |
| `history_start` | No | See [Analyzing your repository history](#analyzing-your-repository-history). |
| `history_end` | No | See [Analyzing your repository history](#analyzing-your-repository-history). |
| `history_period_months` | No | See [Analyzing your repository history](#analyzing-your-repository-history). |
| `history_start` | No | See [Analyzing your repository history](#analyzing-your-repository-history). |
| `history_end` | No | See [Analyzing your repository history](#analyzing-your-repository-history). |

### Components in Maintainability versus components in Architecture Quality

By default, Sigrid will automatically detect your system's component structure. This applies to all Sigrid capabilities, so the automatically detected component structure will also be used for Architecture Quality.

However, it is possible to [manually override the component structure](#defining-components). If you do this, the manually defined components *only* apply to the Maintainability capability, and are not automatically picked up by the Architecture Quality capability. If you *also* want to override the component structure for Architecture Quality, you will need to explicitly add the following option:

architecture:
custom_components: true

As explained in the section on [defining components](#defining-components), we recommend you use the automatic component detection.

### Analyzing your repository history

Architecture Quality analyzes both your source code and the repository history. See the [frequently asked questions for architecture quality](../capabilities/faq-architecture.md) for more information on how the repository history is analyzed.
Expand Down
1 change: 1 addition & 0 deletions docs/reference/aq-json-export-format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,7 @@ picture in the previous section.
| systemElement.observationType | See the list of [architecture observations](#architecture-observations) below. Optional field. [1] |
| systemElement.technology | Indicates this is a technology-specific system element. Optional field. [2] |
| systemElement.annotation | Text description that provides information for system elements. Optional field, defined in configuration. [3] |
| dependency.id | ID based on the dependency's fingerprint. Dependencies will retain the same ID across subsequent scans. |
| dependency.sourceElementId | Refers to one of the entries in `systemElements`. |
| dependency.targetElementId | Refers to one of the entries in `systemElements`. |
| dependency.type | See the [list of dependency types](#dependency-types) below. |
Expand Down
56 changes: 14 additions & 42 deletions resources/sigrid-scope-file.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -226,26 +226,14 @@
"properties": {
"description": {
"type": "string"
},
"action": {
"type": "string"
},
"technologies": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
}
},
"required": ["description", "action", "technologies"],
"required": ["description"],
"additionalProperties": true
},
"dependency_checker_source": {
"type": "string",
"enum": ["all", "sbom"]
}
},

Expand Down Expand Up @@ -283,25 +271,6 @@
"description": "SIG Maintainability Model that should be used for the analysis, defaults to latest."
},

"alerts": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "When true, will send alert email notifications when noteworthy events happen."
},
"recipients": {
"type": "array",
"items": {
"type": "string",
"format": "email"
},
"description": "List of email addresses that should receive alerts."
}
},
"additionalProperties": false
},

"dependencychecker": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -395,6 +364,9 @@
"type": "string"
},
"description": "List of technologies for which the analysis should be disabled."
},
"source": {
"$ref": "#/definitions/dependency_checker_source"
}
},
"additionalProperties": false,
Expand All @@ -418,7 +390,7 @@
},
"custom_components": {
"type": "boolean",
"description": "Overrides automatic component detection with components defined manually in scope file."
"description": "Deprecated. This option is obsolete."
},
"file_annotation_components": {
"type": "boolean",
Expand Down Expand Up @@ -465,7 +437,7 @@
},
"history_enabled": {
"type": "boolean",
"description": "Deprecated, this is now detected automatically."
"description": "Deprecated. This option is obsolete."
},
"history": {
"anyOf": [
Expand All @@ -476,7 +448,7 @@
"type": "string"
}
],
"description": "Deprecated, this is now detected automatically."
"description": "Deprecated. This option is obsolete."
},
"history_period_months": {
"type": "integer",
Expand All @@ -500,7 +472,7 @@
},
"branch": {
"$ref": "#/definitions/branches",
"description": "Repository branch to use, comma-separated for multiple branches. Defaults to current branch."
"description": "Deprecated. This option is obsolete."
},
"duplication": {
"type": "boolean",
Expand Down Expand Up @@ -566,10 +538,10 @@
},
"additionalProperties": false,
"required": []
}
},
"checkmarx": false
},
"required": ["languages"],
"not": {"required": ["checkmarx"]},
"title": "Sigrid scope configuration file",
"type": "object"
}
33 changes: 27 additions & 6 deletions test/test_scope_file_schema.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
# See the License for the specific language governing permissions and
# limitations under the License.

import inspect
import json
import jsonschema
import yaml
Expand All @@ -34,12 +35,11 @@ def testSchemaIsValidJson(self):
"description",
"properties",
"required",
"not",
"title",
"title",
"type"
]

self.assertEqual(list(self.schema.keys()), fields)
self.assertEqual(sorted(self.schema.keys()), fields)

def testValidScopeFileAgainstSchema(self):
scope = """
Expand Down Expand Up @@ -71,14 +71,15 @@ def testDisallowedSection(self):
languages:
- Java
checkmarx:
enabled: true
aap: true
"""

try:
parsedScope = yaml.load(scope, Loader=yaml.FullLoader)
jsonschema.validate(instance=parsedScope, schema=self.schema)
self.assertTrue(False, "ValidationError should have been raised")
except jsonschema.ValidationError as e:
self.assertTrue(e.message.endswith("should not be valid under {'required': ['checkmarx']}"))
self.assertTrue("schema does not allow {'aap': True}" in e.message)

def testDependencyCheckerExcludeOptions(self):
scope = """
Expand Down Expand Up @@ -111,4 +112,24 @@ def testRejectUnknownDependencyCheckerExcludeOptions(self):
self.assertTrue(False, "ValidationError should have been raised")
except jsonschema.ValidationError as e:
self.assertTrue("{'something': 'noot'} is not valid under any of the given schemas" in e.message)


def testDependencyCheckerSourceOption(self):
base = inspect.cleandoc("""
languages:
- Python
dependencychecker:
blocklist: ["NONE"]
""")

scope = yaml.load(f"{base}\n source: all", Loader=yaml.FullLoader)
jsonschema.validate(instance=scope, schema=self.schema)

scope = yaml.load(f"{base}\n source: sbom", Loader=yaml.FullLoader)
jsonschema.validate(instance=scope, schema=self.schema)

try:
scope = yaml.load(f"{base}\n source: aap", Loader=yaml.FullLoader)
jsonschema.validate(instance=scope, schema=self.schema)
self.assertTrue(False, "ValidationError should have been raised")
except jsonschema.ValidationError as e:
self.assertTrue("'aap' is not one of ['all', 'sbom']" in e.message)