feat: add inheritance view to ssp-generate and ssp-assemble

.gitignore

@@ -49,3 +49,5 @@ site
 tmp_bin_test
 .mypy_cache
 
+/venv.trestle/
+

docs/api_reference/trestle.core.crm.bycomp_interface.md

@@ -0,0 +1,2 @@
+::: trestle.core.crm.bycomp_interface
+handler: python

docs/api_reference/trestle.core.crm.export_reader.md

@@ -0,0 +1,2 @@
+::: trestle.core.crm.export_reader
+handler: python

docs/api_reference/trestle.core.crm.export_writer.md

@@ -0,0 +1,2 @@
+::: trestle.core.crm.export_writer
+handler: python

docs/api_reference/trestle.core.crm.leveraged_statements.md

@@ -0,0 +1,2 @@
+::: trestle.core.crm.leveraged_statements
+handler: python

docs/api_reference/trestle.core.crm.ssp_inheritance_api.md

@@ -0,0 +1,2 @@
+::: trestle.core.crm.ssp_inheritance_api
+handler: python

docs/tutorials/ssp_profile_catalog_authoring/ssp_profile_catalog_authoring.md

@@ -1050,6 +1050,131 @@ As with all the `assemble` tools, you may optionally specify a `--name` for a co
 
 If you do not specify component-defintions during assembly, the markdown should not refer to any components other than `This System`.  Thus you may first generate markdown with `ssp-generate` and no component-definitions specified - and then you may assemble that ssp with `ssp-assemble` and no component-definitions specified - but only if there are no components other than `This System` referenced in the markdown.  You may add new component implementation details to the markdown later, but any new components must be defined in a component-defintion file, and that file must be specified when `ssp-assemble` is run.
 
+## Inheritance view
+
+The inheritance view is generated by setting the `--leveraged-ssp` flag with `trestle author ssp-generate`. It contains information relating to exported information such as inherited capabilities and customer responsibilities that can be used to populate the inheritance information in the assembled SSP. When used, a directory named "inheritance" is created within the markdown directory. This directory serves as a designated space for  mapping inherited capabilities and responsibilities onto components in the assemble SSP and authoring satisfied statements for responsibilities.
+
+Example usage for creation of the markdown:
+
+`trestle author ssp-generate --profile my_prof --compdefs "compdef_a,compdef_b" --yaml /my_yaml_dir/header.yaml --leveraged-ssp my_provider_ssp --output my_ssp`
+
+In this example the leveraged ssp has previously been imported into the trestle directory, but it can be fetched from remote location.
+
+The generated markdown output with the inheritance view will be placed in the trestle subdirectory `my_ssp/inheritance` with a subdirectory for each component in the leveraged ssp with directories separated by control and statement id below.
+
+An example of this directory structure is below.
+
+```text
+.
+├── Application
+│   ├── ac-1_stmt.a
+│   │   └── 11111111-0000-4000-9009-001001002006.md
+│   ├── ac-2.1
+│   │   └── 11111111-0000-4000-9009-001001002004.md
+│   └── ac-2_stmt.a
+│       └── 11111111-0000-4000-9009-002001002001_11111111-0000-4000-9009-002001002002.md
+└── This System
+    ├── ac-1_stmt.a
+    │   └── 11111111-0000-4000-9009-001002002001.md
+    ├── ac-2.1
+    │   └── 11111111-0000-4000-9009-001001002001.md
+    └── ac-2_stmt.a
+        └── 11111111-0000-4000-9009-002001001001.md
+```
+
+The leveraged components are used as the top level directory to allow any non-leveraged components to be easily skipped or removed. Each markdown file is named in accordance with the uuid of the exported statement to ensure statement description updates can be applied.
+
+There are three types of markdown files that can be generated from this process.
+
+The examples below demonstrate these types:
+
+<details markdown>
+
+<summary>Example of inheritance provided only markdown after ssp-generate</summary>
+
+```markdown
+---
+x-trestle-statement:
+  # Add or modify leveraged SSP Statements here.
+  provided-uuid: 11111111-0000-4000-9009-001002002001
+x-trestle-leveraging-comp:
+  # Leveraged statements can be optionally associated with components in this system.
+  # Associate leveraged statements to Components of this system here:
+  - name: REPLACE_ME
+---
+
+# Provided Statement Description
+
+Customer_appropriate description of what may be inherited.
+```
+
+</details>
+
+<details markdown>
+
+<summary>Example of inheritance customer responsibility only markdown after ssp-generate</summary>
+
+```markdown
+---
+x-trestle-statement:
+  # Add or modify leveraged SSP Statements here.
+  responsibility-uuid: 11111111-0000-4000-9009-002001001001
+x-trestle-leveraging-comp:
+  # Leveraged statements can be optionally associated with components in this system.
+  # Associate leveraged statements to Components of this system here:
+  - name: REPLACE_ME
+---
+
+# Responsibility Statement Description
+
+Leveraging system's responsibilities with respect to inheriting this capability.
+
+# Satisfied Statement Description
+
+<!-- Use this section to explain how the inherited responsibility is being satisfied. -->
+```
+
+</details>
+
+<details markdown>
+
+<summary>Example of inheritance shared responsibility markdown after ssp-generate</summary>
+
+```markdown
+---
+x-trestle-statement:
+  # Add or modify leveraged SSP Statements here.
+  provided-uuid: 11111111-0000-4000-9009-002001002001
+  responsibility-uuid: 11111111-0000-4000-9009-002001002002
+x-trestle-leveraging-comp:
+  # Leveraged statements can be optionally associated with components in this system.
+  # Associate leveraged statements to Components of this system here:
+  - name: REPLACE_ME
+---
+
+# Provided Statement Description
+
+Consumer-appropriate description of what may be inherited.
+
+# Responsibility Statement Description
+
+Leveraging system's responsibilities with respect to inheriting this capability.
+
+# Satisfied Statement Description
+
+<!-- Use this section to explain how the inherited responsibility is being satisfied. -->
+```
+
+</details>
+
+Some additional information and tips about this markdown are below:
+
+- Do not change the statement UUIDs in the YAML header. This is used in the assembled JSON to link the statements in the leveraged SSP to the components in the leveraging SSP.
+- When mapping components in the YAML header, use the component title. If you do not wish to map a component to a particular inherited capability or responsibility, just leave the file as is. Files without mapped components or that contain the default "REPLACE ME" entry will be skipped.
+- If the file exists, just the editable information will be preserved when regenerating existing inheritance view markdown. This includes the information under `Satisfied Statement Description` and the mapped components in the YAML header.
+
+After manually editing the inheritance view markdown, the `trestle author ssp-assemble` command can be run without modifications for the inheritance view use case. During assemble, the inheritance directory is detected and the information will be assembled into the SSP. The by-component assemblies will be updated or added under existing implemented requirement or statement sections with the information from the markdown.
+
 </details>
 
 <details markdown>

mkdocs.yml

@@ -113,6 +113,12 @@ nav:
       - control_interface: api_reference/trestle.core.control_interface.md
       - control_reader: api_reference/trestle.core.control_reader.md
       - control_writer: api_reference/trestle.core.control_writer.md
+      - crm:
+        - bycomp_interface: api_reference/trestle.core.crm.bycomp_interface.md
+        - export_reader: api_reference/trestle.core.crm.export_reader.md
+        - export_writer: api_reference/trestle.core.crm.export_writer.md
+        - leveraged_statements: api_reference/trestle.core.crm.leveraged_statements.md
+        - ssp_inheritance_api: api_reference/trestle.core.crm.ssp_inheritance_api.md
       - docs_control_writer: api_reference/trestle.core.docs_control_writer.md
       - draw_io: api_reference/trestle.core.draw_io.md
       - duplicates_validator: api_reference/trestle.core.duplicates_validator.md