Add a source-backed element

Ownership and required inputs

The consumer owns the element type, group, ASIL, implementation class and namespace, native target, selected compilation units, topics, annotations, and the justification for each function transform. STIG owns the generators and pipeline.

With element.importEnabled = true, an explicitly invoked code import updates interface declarations in the ordinary Kotlin Context. Authored hierarchy and internal units remain in that same Context. With importEnabled = false, Context is maintained in Kotlin. This choice is independent of whether C++ analysis or a generated harness is enabled; compilation, checking and reporting never invoke model import.

Choose the production compilation units that implement the element being analyzed. An activity can call a separate domain component without including that component's implementation in softwareUnderAnalysis; its relevant effects then need appropriate transform models. Include domain sources when the selected implementation is split across directories or when the chosen analysis deliberately covers that component. Record the concrete selection and its rationale before deriving configuration.

Create and configure

1. Create the element, choosing Context ownership explicitly:

   ./gradlew stigInitElement \ --elementDir activities/example_activity \ --elementType ACTIVITY \ --asil B \ --group source_activities \ --importEnabled true

   Start a new Gradle invocation afterward so the new module is registered. The ordinary Kotlin scaffold can compile before an interface inventory is available. Enabling import does not run it.

2. Configure the existing element using its Gradle path:

   ./gradlew :activities:example_activity:stigConfigureAnalysis --preview ./gradlew :activities:example_activity:stigConfigureAnalysis

   Supply any missing native target, implementation, source selection, topics, annotations, and lifecycle options listed by help --task stigConfigureAnalysis. Omitted options reuse persisted inputs. The command obtains current native/LLVM evidence; it does not require a separate harness generation or copy command.

   Exact --analysisSource and tree --analysisSourceTree options combine into softwareUnderAnalysis. Tree selection uses the native target's production compilation commands and generated-source ownership; it does not select every C++ file on disk. Keep the resolved selection separate from the complete native dependency inventory, which also supplies original-code evidence for transforms.

   Interface extraction and harness generation use native filenames <implementationDir>/<moduleName>_activity.{h,cpp}, adding _activity only when it is absent from the module name. element.implementationDir defaults to the Gradle module path; set it when the upstream directory differs. The initializer's --implementationHeader supplies its validation input; it does not persist a separate header override for those later tasks.

   Review the candidate or edited element configuration, shared bitcodeTransformRegistry, and activities/example_activity/build/stig/stigConfigureAnalysis/source_code_analysis_configuration_result.json. The preview also retains candidate Gradle files and a temporary harness in that build directory.

3. If code owns the Context interfaces, select the module in the root build script:

   stigProject { model { imports { code { fromModules(":activities:example_activity") } } } }

   Extract the compiled interface inventory, import it explicitly, then check the resulting model. Run these as separate Gradle invocations:

   ./gradlew :activities:example_activity:stigExtractAnalysisInterfaceInventory ./gradlew :activities:example_activity:stigImportModel --from code ./gradlew :activities:example_activity:stigCheckModel

   Review the Kotlin source changes and the reported model findings. A fresh scaffold still needs authored descriptions, hierarchy and model ASIL values; successful initialization or compilation does not complete those specifications. See Model import and export.

4. Generate the report in a new invocation:

   ./gradlew stigGenerateHtml

   Compilation uses the current Kotlin sources. The generated harness feeds P5 directly. Valid output changes trigger regeneration; invalid inputs and failed analysis contracts remain errors.

Check and complete analysis

Use the single Check and align analysis evidence workflow with $stig:source-analysis. The --configuration-only mode of stigCheckAnalysis obtains P1–P5 evidence while configuration or reviews are unresolved. Investigate missing required P5 definitions as missing or incorrect configuration. The default mode includes the report chain; add --zip for portable review. Production sources and headers are not included, so review the original compiled LLVM and callers where they establish the necessary behavior.

An activity is complete only after missing registry definitions, missing required activity use(...) entries, and other incorrect configuration are resolved, each active activity transform rule has shared reviewStatus = CONFIRMED, every sink agrees across the compiled LLVM and downstream report stages, and observed flow gaps match the activity's accepted knownGaps. Inspect all active rules, not just proposed model edits or problematic sink rows. Each activity has its own review and completion state. The evidence guide defines the rerun boundaries and concrete engineering acceptance required at each stage.

For a focused final-module check, invoke stigCheckP5SymbolCompleteness. For native failures, invoke stigAnalysisP1BuildNativeTarget or stigAnalysisP1ExtractNativeCompileCommands on the affected element. These are supporting diagnostics, not additional mandatory setup steps or portable replay commands.

See Gradle task API, Bitcode rewrite modeling, and Analysis harness for details.