Skip to content

Commit bd55dcc

Browse files
committed
chore(docs): add serena and conventions file
Signed-off-by: Ruben Romero Montes <rromerom@redhat.com>
1 parent d6cc464 commit bd55dcc

5 files changed

Lines changed: 190 additions & 5 deletions

File tree

.serena/.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/cache
2+
/project.local.yml
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# GoModulesProvider Architecture
2+
3+
## Dependency Resolution Flow
4+
1. `getDependenciesSbom(Path, boolean)` orchestrates: runs `go mod graph`, `go mod edit -json`, determines main module version
5+
2. `buildGoModulesDependencies(Path)` - runs `go mod graph` to get full dependency graph
6+
3. `getDirectDependencyPaths(Path)` - runs `go mod edit -json` to identify direct vs indirect deps
7+
4. For stack analysis: `buildSbomFromGraph` builds full dependency tree
8+
5. For component analysis: `buildSbomFromList` lists only direct dependencies
9+
10+
## Direct vs Indirect Filtering (TC-4300)
11+
- Since Go 1.17, `go mod tidy` adds all transitively-imported modules to go.mod with `// indirect` marker
12+
- `go mod graph` emits root-level edges for ALL modules in go.mod (both direct and indirect)
13+
- `go mod edit -json` returns structured JSON with `Require` array where each entry has optional `Indirect: true`
14+
- Both `buildSbomFromGraph` and `buildSbomFromList` filter root-level deps to only include direct ones
15+
16+
## Key Gotcha: MVS Version Suffix
17+
After MVS processing (`getFinalPackagesVersionsForModule`), the root key in the edges map changes from `module/path` to `module/path@v0.0.0`. The root comparison must use `getModulePath()` to strip the version suffix for both sides, otherwise the filtering silently does nothing when MVS is enabled.
18+
19+
## Helper Methods
20+
- `getModulePath(String)` - strips `@version` suffix from `go mod graph` entries (e.g., `github.com/foo/bar@v1.2.3` -> `github.com/foo/bar`)
21+
- `extractPackageName(String)` - strips `//` comment from go.mod require lines (different purpose, don't confuse)
22+
- `getParentVertex(String)` / `getChildVertex(String)` - split `go mod graph` edge lines on space
23+
- `isGoToolchainEntry(String)` - filters out `go@` and `toolchain@` entries
24+
25+
## Test Fixtures
26+
- `src/test/resources/tst_manifests/golang/` - main test fixtures with 6 test folders
27+
- `src/test/resources/msc/golang/mvs_logic/` - MVS-specific test fixtures
28+
- Tests use `dropIgnoredKeepFormat()` to strip timestamps and goarch/goos before comparison
29+
- Tests use `prettyJson()` (Jackson) to normalize JSON formatting
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# exhort-java-api Project Overview
2+
3+
## Purpose
4+
Java client library for the Dependency Analytics (DA) / Exhort vulnerability analysis backend. Generates SBOMs (CycloneDX JSON) from project manifests and submits them for analysis.
5+
6+
## Tech Stack
7+
- Java 17+, Maven build
8+
- Jackson for JSON, TOML parsing (com.moandjiezana.toml)
9+
- XMLStreamReader for POM parsing
10+
- CycloneDX SBOM model (custom `Sbom` class)
11+
12+
## Key Directories
13+
- `src/main/java/io/github/guacsec/trustifyda/providers/` - Provider implementations per ecosystem
14+
- `src/main/java/io/github/guacsec/trustifyda/tools/` - Utilities (Operations, Ecosystem, Environment)
15+
- `src/main/java/io/github/guacsec/trustifyda/utils/` - Shared utilities (IgnorePatternDetector, PythonControllerBase)
16+
- `src/test/resources/tst_manifests/` - Test fixtures per ecosystem
17+
18+
## Provider Pattern
19+
Each ecosystem has a Provider class extending `Provider` abstract class with methods:
20+
- `provideStack()` - Full dependency tree SBOM
21+
- `provideComponent()` - Direct dependencies only SBOM
22+
- `readLicenseFromManifest()` - License extraction
23+
- `validateLockFile(Path)` - Lock file validation
24+
25+
## Ignore Pattern Detection
26+
Centralized in `IgnorePatternDetector` with constants `IGNORE_PATTERN` ("trustify-da-ignore") and `LEGACY_IGNORE_PATTERN` ("exhortignore").
27+
28+
## Commands
29+
- Build: `mvn clean install`
30+
- Test: `mvn test`
31+
- Format: `mvn spotless:apply`

.serena/project.yml

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# the name by which the project can be referenced within Serena
2+
project_name: "trustify-da-java-client"
3+
4+
5+
# list of languages for which language servers are started; choose from:
6+
# al ansible bash clojure cpp
7+
# cpp_ccls crystal csharp csharp_omnisharp dart
8+
# elixir elm erlang fortran fsharp
9+
# go groovy haskell haxe hlsl
10+
# java json julia kotlin lean4
11+
# lua luau markdown matlab msl
12+
# nix ocaml pascal perl php
13+
# php_phpactor powershell python python_jedi python_ty
14+
# r rego ruby ruby_solargraph rust
15+
# scala solidity swift systemverilog terraform
16+
# toml typescript typescript_vts vue yaml
17+
# zig
18+
# (This list may be outdated. For the current list, see values of Language enum here:
19+
# https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
20+
# For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
21+
# Note:
22+
# - For C, use cpp
23+
# - For JavaScript, use typescript
24+
# - For Free Pascal/Lazarus, use pascal
25+
# Special requirements:
26+
# Some languages require additional setup/installations.
27+
# See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
28+
# When using multiple languages, the first language server that supports a given file will be used for that file.
29+
# The first language is the default language and the respective language server will be used as a fallback.
30+
# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
31+
languages:
32+
- java
33+
34+
# the encoding used by text files in the project
35+
# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
36+
encoding: "utf-8"
37+
38+
# line ending convention to use when writing source files.
39+
# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
40+
# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
41+
line_ending:
42+
43+
# The language backend to use for this project.
44+
# If not set, the global setting from serena_config.yml is used.
45+
# Valid values: LSP, JetBrains
46+
# Note: the backend is fixed at startup. If a project with a different backend
47+
# is activated post-init, an error will be returned.
48+
language_backend:
49+
50+
# whether to use project's .gitignore files to ignore files
51+
ignore_all_files_in_gitignore: true
52+
53+
# list of additional paths to ignore in this project.
54+
# Same syntax as gitignore, so you can use * and **.
55+
# Note: global ignored_paths from serena_config.yml are also applied additively.
56+
ignored_paths: []
57+
58+
# whether the project is in read-only mode
59+
# If set to true, all editing tools will be disabled and attempts to use them will result in an error
60+
# Added on 2025-04-18
61+
read_only: false
62+
63+
# list of tool names to exclude.
64+
# This extends the existing exclusions (e.g. from the global configuration)
65+
# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
66+
excluded_tools: []
67+
68+
# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
69+
# This extends the existing inclusions (e.g. from the global configuration).
70+
# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
71+
included_optional_tools: []
72+
73+
# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
74+
# This cannot be combined with non-empty excluded_tools or included_optional_tools.
75+
# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
76+
fixed_tools: []
77+
78+
# list of mode names to that are always to be included in the set of active modes
79+
# The full set of modes to be activated is base_modes + default_modes.
80+
# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply.
81+
# Otherwise, this setting overrides the global configuration.
82+
# Set this to [] to disable base modes for this project.
83+
# Set this to a list of mode names to always include the respective modes for this project.
84+
base_modes:
85+
86+
# list of mode names that are to be activated by default, overriding the setting in the global configuration.
87+
# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
88+
# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
89+
# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
90+
# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
91+
# for this project.
92+
# This setting can, in turn, be overridden by CLI parameters (--mode).
93+
# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
94+
default_modes:
95+
96+
# initial prompt for the project. It will always be given to the LLM upon activating the project
97+
# (contrary to the memories, which are loaded on demand).
98+
initial_prompt: ""
99+
100+
# time budget (seconds) per tool call for the retrieval of additional symbol information
101+
# such as docstrings or parameter information.
102+
# This overrides the corresponding setting in the global configuration; see the documentation there.
103+
# If null or missing, use the setting from the global configuration.
104+
symbol_info_budget:
105+
106+
# list of regex patterns which, when matched, mark a memory entry as read‑only.
107+
# Extends the list from the global configuration, merging the two lists.
108+
read_only_memory_patterns: []
109+
110+
# list of regex patterns for memories to completely ignore.
111+
# Matching memories will not appear in list_memories or activate_project output
112+
# and cannot be accessed via read_memory or write_memory.
113+
# To access ignored memory files, use the read_file tool on the raw file path.
114+
# Extends the list from the global configuration, merging the two lists.
115+
# Example: ["_archive/.*", "_episodes/.*"]
116+
ignored_memory_patterns: []
117+
118+
# advanced configuration option allowing to configure language server-specific options.
119+
# Maps the language key to the options.
120+
# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
121+
# No documentation on options means no options are available.
122+
ls_specific_settings: {}
123+
124+
# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
125+
# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
126+
# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
127+
added_modes:

CONVENTIONS.md

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Coding Conventions
22

3-
<!-- This file documents project-specific coding standards for exhort-java-api. -->
3+
<!-- This file documents project-specific coding standards for trustify-da-java-client. -->
44

55
## Language and Framework
66

@@ -85,10 +85,6 @@ src/main/java/io/github/guacsec/trustifyda/
8585

8686
- **Dependabot suppression**: Test fixture directories contain intentionally pinned (sometimes vulnerable) dependencies. When adding a new test fixture directory with a manifest file, review `.github/dependabot.yml` to ensure the new path is covered. Non-maven ecosystems are suppressed via root-level `ignore: [{dependency-name: "*"}]` entries. Maven fixtures use per-directory entries with `/**` globs since maven is the production ecosystem; add the parent directory if a new maven fixture tree is introduced.
8787

88-
## Test Fixtures
89-
90-
- **Dependabot suppression**: Test fixture directories contain intentionally pinned (sometimes vulnerable) dependencies. When adding a new test fixture directory with a manifest file, review `.github/dependabot.yml` to ensure the new path is covered. Non-maven ecosystems are suppressed via root-level `ignore: [{dependency-name: "*"}]` entries. Maven fixtures use explicit per-directory entries since maven is the production ecosystem; add the directory path if a new maven fixture is introduced.
91-
9288
## Dependencies
9389

9490
- All versions in `<properties>` section: `{artifact-name}.version` pattern

0 commit comments

Comments
 (0)