spviz-dsl-modeling

Files (1)

• SKILL.md

SKILL.md (first lines)

# Design SPViz DSL models
Use this skill for both the architecture metamodel (A2M) in `.spvizmodel` and the
view context metamodel (VC2M) in `.spviz`. Keep architecture facts separate from view
choices:

- The A2M states which artifact types, containments, and connections exist.
- The VC2M states which filtered graph views expose those facts.

Do not implement the source extractor or downstream styling in this skill.
Hand extractor work to `spviz-model-generator` and styling work to `spviz-style-customization` if prompted.

## Required intake
If the model scope or desired collaboration style has not been explicitly stated by the user, ask them:

> Do you want to tell me about the architecture and relationships in prose, or should I inspect a repository to make suggestions? Furthermore, should I work iteratively with you to refine the model, or should I generate a complete model?

Do not repeat this question when the user has already provided the necessary scope and collaboration preferences.
Suggest sensible candidates after inspecting the available evidence, but do not decide the scope silently.
Good candidates include:
- project, product, feature, module, package, or component containment
- module or package dependencies
- public API or import/export relationships
- service, dependency-injection, provider, and consumer relationships
- build-system projects and their resolved dependencies
- source-module or function-call relationships
- explicit layers, ownership groups, teams, or deployment categories
- runtime or trace relations only when the repository or another tool supplies runtime data

Suggest candidates that are relevant to the user's stated goals and explain what including each candidate would require from the model extractor and underlying source code.

Recommend a small set of focused views, for example a containment overview, a dependency view, a service/DI view, and one categorized view.
Explain why each suggested view helps with comprehension, onboarding, impact analysis, or documentation.
Discourage requests to show everything; treat them as a prompt to discuss filtering and hierarchy first.
Favour focused views over a messy all-at-once diagram.

Ask separately for or infer from the previous discussion:

- the repository path or the written architecture description
- the desired stable package identifier root (for example `com.example.projectviz`) and model/visualization names
- whether an existing A2M or VC2M should be extended

If the user provides prose and source is available, verify the proposed architecture against the source.
If the user gives a repository, inspect its build files, manifests, source layout, generated metadata, and existing documentation before proposing names.

## Architecture DSL rules
To design or modify architecture metamodels, read the Xtext grammar inside this skill at `SPVizModel.xtext` first.

Follow these rules:
- Keep names stable because project model instances and stored view contexts refer to them.
- A connection may target the same type or a different type.

- Model only relationships that the extractor or source description can establish.
Do not encode a relationship merely because it would look useful in a diagram.
If a category such as layer or ownership is needed but is absent from the source,
ask whether it should be added as maintained metadata or omitted.

- For an existing architecture, preserve its identifiers and add only the new artifact or connection needed by the requested view.
- For a written target architecture, record which elements are intended design decisions and which will later need extraction.
- For every modification to an existing architecture, check that the modification is compatible with the targeted repository
and think about and record the changes needed in the extractor or source description to support the new model.

## View context DSL rules
To design or modify view context metamodels, read the Xtext grammar inside this skill at `SPViz.xtext` first.

Follow these rules:
- Put directly related artifacts and connections in the same focused view.
- Use artifact views to show a filtered inner view inside a containing artifact.
- The last artifact in an artifact-source chain must be the artifact type shown by the inner view.
Longer containment chains are valid when the source data has that hierarchy, but note that they are not supported yet in the visualization tools generated by SPViz as of version 0.6.0 and therefore do not help the user yet.
- Use a category connection when a parent category should expose a connection that exists between artifacts in its nested artifact views:
```
Layers {
    show Example.Layer
    connect Example.Module.DependsOn via Example.Layer in Dependencies
}
```
The category must have a matching artifact view, and `in` must name the nested view that renders the connection.
Verify this against the grammar and generated model; do not use category connections when the containment context is not present.
- Do not invent an indirect-connection syntax.
The current grammar supports direct shown connections, category connections, and artifact-source chains.
More advanced indirect-connection shortcuts are not yet part of the tool.

## Practical design patterns
For module-oriented projects, start with:
```
Modules {
    show Example.Module
    connect Example.Module.Dependency
}
```

For service or dependency injection data, show both endpoints and both meaningful directions if the A2M defines them:
```
Services {
    show Example.ServiceInterface
    show Example.ServiceComponent
    connect Example.ServiceInterface.ProvidedBy
    connect Example.ServiceComponent.Required
}
```

For a hierarchy, define an overview of the parent and an artifact view containing the child-focused view.
For large projects, add a category view and a category connection instead of adding every cross-category edge to the main view.
The examples in the public `https://github.com/kieler/SoftwareProjectViz-examples` repository illustrate these patterns.
Use them as patterns, not as evidence that another project has the same file structure.

## Validate before handing off
1. Check that the `.spviz` import points to the intended `.spvizmodel` file and that the
   file is available relative to the model location.
2. Check every `show` and `connect` reference against the A2M.
3. Check every artifact-source chain against actual containment declarations.
4. Check that category connections have the required nested views and category data.
5. Use `spviz-cli-tools` to obtain and verify the bundled SPViz CLI:
   `java -jar <spviz-cli.jar> architecture.spvizmodel visualization.spviz --validate`
6. Only after the DSL parses should `spviz-build` be used.

Treat the CLI log as authoritative for generation failures, inspect it instead of relying on the process exit code alone.
Hand over to `spviz-troubleshooting` if the CLI fails to parse the DSLs.

From kieler/SoftwareProjectViz, EPL-2.0.

More from kieler/SoftwareProjectViz