continuous-delivery-scripts 4.1.0__tar.gz → 4.2.0__tar.gz

{continuous_delivery_scripts-4.1.0/continuous_delivery_scripts.egg-info → continuous_delivery_scripts-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: continuous-delivery-scripts
-Version: 4.1.0
+Version: 4.2.0
 Summary: Git-based CI/CD tools for releases, changelogs, SPDX SBOMs and licence reporting
 Home-page: https://github.com/ARMmbed/continuous-delivery-scripts
 Author: Arm

{continuous_delivery_scripts-4.1.0 → continuous_delivery_scripts-4.2.0}/continuous_delivery_scripts/_version.py

@@ -11,8 +11,8 @@ References
 This file is autogenerated, do not modify by hand.
 """
 
-__version__ = "4.1.0"
-COMMIT = "298fb1cfdf2636976e5ea78d65207793279edcca"
+__version__ = "4.2.0"
+COMMIT = "757dd096956394de1185aa8f7bb169dc0d0fc982"
 MAJOR = 4
-MINOR = 1
+MINOR = 2
 PATCH = 0

{continuous_delivery_scripts-4.1.0 → continuous_delivery_scripts-4.2.0}/continuous_delivery_scripts/generate_docs.py

@@ -93,7 +93,7 @@ def _guide_settings() -> tuple[Path, Path, Path, str] | None:
 def _render_guide(source: Path, destination: Path, project_name: str, nav_prefix: str, has_api_index: bool) -> str:
     """Render one Markdown guide to an HTML page and return its title."""
     text = source.read_text(encoding="utf8")
-    title = text.splitlines()[0].removeprefix("# ").strip()
+    title = next((line[2:].strip() for line in text.splitlines() if line.startswith("# ")), source.stem)
     body: str = markdown.markdown(text, extensions=["fenced_code", "tables"])
     body = re.sub(r'href="([a-z0-9-]+)\.md(#[^"]*)?"', _html_guide_link, body)
     description = f"{title} — {project_name}."
@@ -124,10 +124,13 @@ def _write_guide_index(
 ) -> None:
     """Write the project-specific landing page for the published guides."""
     guide_prefix = guide_folder.as_posix()
+    licence = configuration.get_value_or_default(ConfigurationVariable.FILE_LICENCE_IDENTIFIER, None)
+    licence_details = f"<p>Project licence: {escape(str(licence))}</p>" if licence else ""
     overview = (
         f"<h1>{escape(project_name)}</h1>"
         f"<p>Task guides for {escape(project_name)}, with setup, examples and project workflows.</p>"
-        f'<p><a href="{escape(guide_prefix)}/index.html">All task guides</a>'
+        + licence_details
+        + f'<p><a href="{escape(guide_prefix)}/index.html">All task guides</a>'
         + (' · <a href="api.html">API reference</a>' if has_api_index else "")
         + "</p><ul>"
         + "".join(links)

continuous_delivery_scripts-4.2.0/continuous_delivery_scripts/plugins/GOLAND.MD

@@ -0,0 +1,52 @@
+# Golang plugin
+
+This plugin is used for golang projects when `PROGRAMMING_LANGUAGE` is set to `golang`.
+
+In order to work, `go > 1.18` is required.
+
+## Release
+The plugin leverages [goreleaser](https://goreleaser.com/) to package and release projects.
+Therefore, a `.goreleaser.yml` file must be present in the go source directory i.e. where the mod file lies.
+
+## Documentation
+The plugin uses [doc2go](https://abhinav.github.io/doc2go) to generate the code reference documentation.
+
+## SPDX and third-party IP reporting
+
+The Go plugin uses [go-licenses v2](https://github.com/google/go-licenses) to
+discover the licences of packages imported by Go modules. It checks for a
+usable `go-licenses` binary on `PATH` before installing
+`github.com/google/go-licenses/v2@latest` with `go install`. The Go toolchain
+must be available; an installed binary can also be located under `GOBIN` or
+the first `GOPATH` entry's `bin` directory.
+
+Set `PROGRAMMING_LANGUAGE = "golang"`, `PROJECT_NAME`, `PROJECT_ROOT` and
+`SOURCE_DIR` in `[ProjectConfig]`. Put a `go.mod` under the source or project
+root; `go.work` modules and nested Go modules are also considered. Supply
+`FILE_LICENCE_IDENTIFIER` for the project licence and set `PROJECT_UUID`
+and `[spdx]` namespace fields as explained in the
+[SPDX configuration guide](../../DEVELOPMENT.md#spdx-document-identity).
+
+With the project and its Go dependencies available, run:
+
+```bash
+mkdir -p licensing
+cd-generate-spdx --output-dir licensing
+```
+
+For each module, the plugin runs `go-licenses report ./...` with a template
+to collect dependency package names, versions, licence URLs and SPDX licence
+names. The [go-licenses custom-template documentation](https://github.com/google/go-licenses/blob/master/README.md#reports-with-custom-templates)
+defines the `Name`, `Version`, `LicenseURL` and `LicenseName` fields used by the
+plugin; the default CSV report has no `Version` field. The metadata then enters
+the **shared** SPDX writer, HTML/CSV/text/JSON
+third-party IP report and accepted-licence policy used by other plugins.
+To include the shared licence summary in release documentation, set
+`GENERATE_LICENSING_SUMMARY_ON_RELEASE = true` in `[ProjectConfig]` (the default
+is `false`).
+The Go tool's own `check` policy is not used; configure
+`ACCEPTED_THIRD_PARTY_LICENCES` and documented exceptions in
+`PACKAGES_WITH_CHECKED_LICENCE` in `pyproject.toml` instead. Unknown licences
+remain unknown so that the shared audit can flag them. The report reflects
+dependencies built for the current Go environment and excludes test-only
+imports unless the Go tool is invoked separately with `--include_tests`.

{continuous_delivery_scripts-4.1.0 → continuous_delivery_scripts-4.2.0}/continuous_delivery_scripts/plugins/golang.py

@@ -4,19 +4,23 @@
 #
 """Plugin for Golang projects."""
 
+import csv
+import io
 import json
 import logging
 import os
 import shutil
 from pathlib import Path
 from subprocess import check_call, check_output
-from typing import TYPE_CHECKING, Optional, List, Dict, MutableMapping
+from tempfile import TemporaryDirectory
+from typing import Optional, List, Dict, MutableMapping
 
+from continuous_delivery_scripts.spdx_report.spdx_project import SpdxProject
 from continuous_delivery_scripts.utils.configuration import (
     configuration,
     ConfigurationVariable,
 )
-from continuous_delivery_scripts.utils.definitions import CommitType
+from continuous_delivery_scripts.utils.definitions import CommitType, UNKNOWN
 from continuous_delivery_scripts.utils.git_helpers import (
     LocalProjectRepository,
     GitWrapper,
@@ -25,9 +29,12 @@ from continuous_delivery_scripts.utils.language_specifics_base import (
     BaseLanguage,
     get_language_from_file_name,
 )
-
-if TYPE_CHECKING:
-    from continuous_delivery_scripts.spdx_report.spdx_project import SpdxProject
+from continuous_delivery_scripts.utils.package_helpers import (
+    LicenceSource,
+    PackageMetadata,
+    ProjectMetadata,
+    ProjectMetadataFetcher,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -37,6 +44,9 @@ ENVVAR_GORELEASER_GIT_TOKEN = "GITHUB_TOKEN"
 ENVVAR_GORELEASER_CUSTOMISED_TAG = "GORELEASER_CURRENT_TAG"
 ENVVAR_GO_MOD = "GO111MODULE"
 GO_MOD_ON_VALUE = "on"
+# go-licenses report --template receives Name, Version, LicenseURL and LicenseName for each library.
+# https://github.com/google/go-licenses/blob/master/README.md#reports-with-custom-templates
+GO_LICENSES_TEMPLATE = "{{range .}}{{.Name}}\t{{.Version}}\t{{.LicenseURL}}\t{{.LicenseName}}\n{{end}}"
 
 
 def _generate_doc2go_command_list(output_directory: Path, module: str) -> List[str]:
@@ -81,24 +91,147 @@ def _install_goreleaser_command_list() -> List[str]:
     return ["go", "install", "github.com/goreleaser/goreleaser/v2@latest"]
 
 
+def _install_go_licenses_command_list() -> List[str]:
+    return ["go", "install", "github.com/google/go-licenses/v2@latest"]
+
+
+def _installed_go_tool_path(tool_name: str, env: MutableMapping[str, str]) -> str:
+    """Find a binary installed using go install, even when Go's bin directory is not on PATH."""
+    go_bin = check_output(["go", "env", "GOBIN"], env=env, encoding="utf8").strip()
+    if not go_bin:
+        go_path = check_output(["go", "env", "GOPATH"], env=env, encoding="utf8").strip()
+        go_bin = str(Path(go_path.split(os.pathsep)[0]) / "bin")
+    executable = Path(go_bin) / (f"{tool_name}.exe" if os.name == "nt" else tool_name)
+    if not executable.is_file():
+        raise FileNotFoundError(f"Could not find installed {tool_name} binary: {executable}")
+    return str(executable)
+
+
+def _candidate_go_module_directories(include_project_root: bool = False) -> List[Path]:
+    """Share module selection between release tags and licence reporting."""
+    candidates = [SRC_DIR]
+    if include_project_root:
+        candidates.append(ROOT_DIR)
+    workspace_modules = _determine_go_work_module_directories()
+    candidates.extend(workspace_modules if workspace_modules else _determine_go_subproject_directories())
+    return list(dict.fromkeys(candidates))
+
+
+def _go_licence_module_directories() -> List[Path]:
+    """Find actual Go modules for dependency reporting."""
+    modules = [
+        path for path in _candidate_go_module_directories(include_project_root=True) if (path / "go.mod").is_file()
+    ]
+    if not modules:
+        raise FileNotFoundError(f"No go.mod found in {SRC_DIR}, {ROOT_DIR} or their Go workspace modules.")
+    return modules
+
+
+def _go_module_name(module_dir: Path, env: MutableMapping[str, str]) -> str:
+    """Read the import path declared by a Go module."""
+    module = json.loads(check_output(["go", "list", "-m", "-json"], cwd=module_dir, env=env, encoding="utf8"))
+    return str(module["Path"])
+
+
+def _parse_go_licences(output: str) -> List[PackageMetadata]:
+    """Translate go-licenses template output into shared package metadata."""
+    packages = []
+    for row in csv.reader(io.StringIO(output), delimiter="\t"):
+        if len(row) != 4 or not row[0].strip():
+            raise ValueError(f"Unexpected go-licenses report row: {row}")
+        name, version, licence_url, licence = (item.strip() for item in row)
+        known_licence = bool(licence and licence.lower() != UNKNOWN)
+        evidence = [{"kind": "licence", "path": licence_url, "text": ""}] if licence_url.startswith("https://") else []
+        packages.append(
+            PackageMetadata.from_fields(
+                name=name,
+                version=version or UNKNOWN,
+                licence=licence if known_licence else UNKNOWN,
+                licence_source=LicenceSource.TOOL if known_licence else LicenceSource.UNKNOWN,
+                declared_licence=licence or UNKNOWN,
+                url=licence_url or UNKNOWN,
+                licence_evidence=evidence,
+            )
+        )
+    return packages
+
+
+class GoProjectMetadataFetcher(ProjectMetadataFetcher):
+    """Retrieve Go dependency licences for the shared SPDX and compliance report."""
+
+    def __init__(self) -> None:
+        """Initialise with the configured project name."""
+        super().__init__(str(configuration.get_value(ConfigurationVariable.PROJECT_NAME)))
+
+    def fetch_project_metadata(self) -> ProjectMetadata:
+        """Collect module dependencies using go-licenses without replacing shared policy checks."""
+        module_directories = _go_licence_module_directories()
+        env = os.environ.copy()
+        env[ENVVAR_GO_MOD] = GO_MOD_ON_VALUE
+        executable = _ensure_go_tool_installed(
+            tool_name="go-licenses",
+            version_command=["go-licenses", "report", "--help"],
+            install_command=_install_go_licenses_command_list(),
+            env=env,
+        )
+        project = ProjectMetadata(self._package_name)
+        project.project_metadata = PackageMetadata.from_fields(
+            name=self._package_name,
+            licence=str(configuration.get_value(ConfigurationVariable.FILE_LICENCE_IDENTIFIER)),
+            licence_source=LicenceSource.CONFIGURATION,
+        )
+        dependencies: Dict[str, PackageMetadata] = {}
+        modules = [(module_dir, _go_module_name(module_dir, env)) for module_dir in module_directories]
+        with TemporaryDirectory() as temporary_dir:
+            template_path = Path(temporary_dir) / "go-licenses.tpl"
+            template_path.write_text(GO_LICENSES_TEMPLATE, encoding="utf8")
+            for module_dir, _ in modules:
+                output = check_output(
+                    [executable, "report", "./...", "--template", str(template_path)],
+                    cwd=module_dir,
+                    env=env,
+                    encoding="utf8",
+                )
+                for package in _parse_go_licences(output):
+                    if any(package.name == name or package.name.startswith(f"{name}/") for _, name in modules):
+                        continue
+                    existing = dependencies.get(package.name)
+                    if existing and (existing.version, existing.licence) != (package.version, package.licence):
+                        candidates = existing.licence_candidates or [existing.licence]
+                        dependencies[package.name] = PackageMetadata.from_fields(
+                            name=package.name,
+                            version=UNKNOWN if existing.version != package.version else package.version,
+                            licence=UNKNOWN,
+                            licence_source=LicenceSource.UNKNOWN,
+                            licence_candidates=sorted(set(candidates + [package.licence])),
+                            licence_evidence=existing.licence_evidence + package.licence_evidence,
+                        )
+                    elif existing is None:
+                        dependencies[package.name] = package
+        for dependency in dependencies.values():
+            project.add_dependency_metadata(dependency)
+        return project
+
+
 def _ensure_go_tool_installed(
     tool_name: str,
     version_command: List[str],
     install_command: List[str],
     env: MutableMapping[str, str],
-) -> None:
-    """Ensure a Go-based tool is available on PATH before use."""
+) -> str:
+    """Return a usable Go tool on PATH or install it into the Go binary directory."""
     tool_path = shutil.which(tool_name)
     if tool_path:
         try:
             check_output(version_command, env=env)
             logger.info("Using %s from PATH: %s", tool_name, tool_path)
-            return
+            return tool_path
         except Exception as exception:
             logger.warning("Could not use %s from PATH: %s", tool_name, exception)
 
     logger.info("Installing %s with go install.", tool_name)
     check_call(install_command, env=env)
+    return _installed_go_tool_path(tool_name, env)
 
 
 def _call_doc2go(output_directory: Path, module: str) -> None:
@@ -212,15 +345,9 @@ def _determine_go_module_tag(version: str) -> List[str]:
     https://go.dev/ref/mod#workspaces, and
     https://github.com/golang/go/wiki/Modules/a549b3e4b7ad6be6e7d11c37ef247bb2279c8146#faqs--multi-module-repositories.
     """
-    module_directories = [SRC_DIR]
-    go_work_module_directories = _determine_go_work_module_directories()
-    if go_work_module_directories:
-        module_directories.extend(go_work_module_directories)
-    else:
-        module_directories.extend(_determine_go_subproject_directories())
-
     tags = [
-        _determine_go_module_tag_for_directory(module_directory, version) for module_directory in module_directories
+        _determine_go_module_tag_for_directory(module_directory, version)
+        for module_directory in _candidate_go_module_directories()
     ]
     return list(dict.fromkeys([tag for tag in tags if tag]))
 
@@ -263,7 +390,7 @@ class Go(BaseLanguage):
 
     def can_get_project_metadata(self) -> bool:
         """States whether project metadata can be retrieved."""
-        return False
+        return True
 
     def get_secret_registry_exclude_files(self) -> List[str]:
         """Gets additional detect-secrets exclude patterns for Go projects."""
@@ -274,10 +401,9 @@ class Go(BaseLanguage):
             (r"^\.github[\\/]workflows[\\/].*"),
         ]
 
-    def get_current_spdx_project(self) -> Optional["SpdxProject"]:
+    def get_current_spdx_project(self) -> Optional[SpdxProject]:
         """Gets current SPDX description."""
-        # TODO
-        return None
+        return SpdxProject(GoProjectMetadataFetcher())
 
     def should_clean_before_packaging(self) -> bool:
         """States whether the repository must be cleaned before packaging happens."""

{continuous_delivery_scripts-4.1.0 → continuous_delivery_scripts-4.2.0}/continuous_delivery_scripts/spdx_report/spdx_document.py

@@ -23,7 +23,7 @@ from continuous_delivery_scripts.utils.configuration import (
     ConfigurationVariable,
 )
 from continuous_delivery_scripts.utils.hash_helpers import generate_uuid_based_on_str
-from continuous_delivery_scripts.utils.python.package_helpers import PackageMetadata
+from continuous_delivery_scripts.utils.package_helpers import PackageMetadata
 
 if TYPE_CHECKING:
     from spdx.document import Document
@@ -240,7 +240,7 @@ class SpdxDocument:
         doc.namespace = determine_spdx_value(self.document_namespace)
         doc.spdx_id = "SPDXRef-DOCUMENT"
         doc.comment = determine_spdx_value(
-            "This document was created automatically using available information from python packages."
+            "This document was created automatically using available project and dependency information."
         )
         doc.data_license = License.from_identifier("CC0-1.0")
         doc.creation_info.add_creator(Person(self.author, self.author_email))

{continuous_delivery_scripts-4.1.0 → continuous_delivery_scripts-4.2.0}/continuous_delivery_scripts/spdx_report/spdx_helpers.py

@@ -67,7 +67,7 @@ COPYRIGHT_PATTERN = r"Copyright.*$"
 COPYRIGHT_REGEX_PATTERN = re.compile(COPYRIGHT_PATTERN, flags=re.MULTILINE | re.IGNORECASE)
 # Specification of the identifier based on https://spdx.org/spdx-specification-21-web-version#h.twlc0ztnng3b
 # and https://spdx.org/ids-how
-SPDX_LICENCE_IDENTIFIER_PATTERN = r"SPDX-License-Identifier: ([\.\w+\-\(\)\s]+)[\*]?$"
+SPDX_LICENCE_IDENTIFIER_PATTERN = r"SPDX-License-Identifier: ([\.\w+\-\(\)\t ]+)[\*]?$"
 SPDX_IDENTIFIER_REGEX_PATTERN = re.compile(SPDX_LICENCE_IDENTIFIER_PATTERN, re.MULTILINE)
 THIRD_PARTY_CONFIG_NAMESPACE = "spdx"
 PATHS_TO_EXCLUDE = [
@@ -77,6 +77,7 @@ PATHS_TO_EXCLUDE = [
     "*.rdf",
     "*.pyc",
     "*.bin",
+    "*.exe",
     "*.tar",
     "*.zip",
     "**/__pycache__/**",

{continuous_delivery_scripts-4.1.0 → continuous_delivery_scripts-4.2.0}/continuous_delivery_scripts/spdx_report/spdx_package.py

@@ -6,17 +6,19 @@
 
 from dataclasses import dataclass
 from pathlib import Path
+import re
 from typing import TYPE_CHECKING, List, Optional
 
 from license_expression import ExpressionError
 
 from continuous_delivery_scripts.spdx_report.spdx_file import SpdxFile
+from continuous_delivery_scripts.utils.hash_helpers import generate_uuid_based_on_str
 from continuous_delivery_scripts.spdx_report.spdx_helpers import (
     determine_spdx_value,
     list_project_files_for_licensing,
 )
 from continuous_delivery_scripts.utils.definitions import UNKNOWN
-from continuous_delivery_scripts.utils.python.package_helpers import PackageMetadata
+from continuous_delivery_scripts.utils.package_helpers import PackageMetadata
 from continuous_delivery_scripts.utils.third_party_licences import (
     UNKNOWN_LICENCE,
     cleanse_licence_expression,
@@ -30,7 +32,7 @@ if TYPE_CHECKING:
 
 @dataclass(frozen=True, order=True)
 class PackageInfo:
-    """Definition of a Python package.
+    """Definition of a project or dependency package.
 
     Attributes:
         metadata: metadata about an installed package.
@@ -90,7 +92,9 @@ class SpdxPackage:
         Returns:
             An ID
         """
-        return self.name if self._is_dependency else self._package_info.uuid
+        if not self._is_dependency:
+            return self._package_info.uuid
+        return self.name if re.fullmatch(r"[A-Za-z0-9.-]+", self.name) else str(generate_uuid_based_on_str(self.name))
 
     @property
     def is_dependency(self) -> bool:

{continuous_delivery_scripts-4.1.0 → continuous_delivery_scripts-4.2.0}/continuous_delivery_scripts/spdx_report/spdx_project.py

@@ -2,10 +2,11 @@
 # Copyright (C) 2020-2026 Arm Limited or its affiliates and Contributors. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 #
-"""Definition of an SPDX report for a Python project."""
+"""Definition of an SPDX report for a project."""
 
 from pathlib import Path
 import os
+import re
 from typing import Optional, List, cast, Tuple, Dict
 
 from continuous_delivery_scripts.spdx_report.spdx_dependency import (
@@ -13,15 +14,14 @@ from continuous_delivery_scripts.spdx_report.spdx_dependency import (
 )
 from continuous_delivery_scripts.spdx_report.spdx_document import SpdxDocument
 from continuous_delivery_scripts.utils.hash_helpers import determine_sha1_hash_of_file
-from continuous_delivery_scripts.utils.python.package_helpers import (
-    ProjectMetadataFetcher,
-)
+from continuous_delivery_scripts.utils.package_helpers import ProjectMetadataFetcher
 from continuous_delivery_scripts.spdx_report.spdx_helpers import (
     is_package_licence_manually_checked,
     get_package_manual_check,
 )
 from continuous_delivery_scripts.spdx_report.spdx_summary import SummaryGenerator
 from continuous_delivery_scripts.utils.configuration import configuration, ConfigurationVariable
+from continuous_delivery_scripts.utils.hash_helpers import generate_uuid_based_on_str
 from continuous_delivery_scripts.utils.third_party_licences import UNKNOWN_LICENCE
 
 
@@ -98,6 +98,16 @@ class SpdxProject:
             self._parser.project_metadata.missing_dependencies,
         ).generate_summary(dir)
 
+    @staticmethod
+    def _spdx_filename(name: str) -> str:
+        """Use a stable, filesystem-safe SPDX filename for any package name."""
+        safe_name = (
+            name
+            if re.fullmatch(r"[A-Za-z0-9_.-]+", name) and name not in (".", "..")
+            else str(generate_uuid_based_on_str(name))
+        )
+        return f"{safe_name}.spdx"
+
     def generate_tag_value_files(self, dir: Path) -> None:
         """Generates SPDX tag-value files into the specified directory.
 
@@ -115,7 +125,7 @@ class SpdxProject:
 
         externalRefs = list()
         for spdx_dependency in self.dependency_documents:
-            file_name = f"{spdx_dependency.name}.spdx"
+            file_name = self._spdx_filename(spdx_dependency.name)
             checksum = SpdxProject.generate_tag_value_file(dir, spdx_dependency, file_name)
             externalRefs.append(
                 DependencySpdxDocumentRef(
@@ -125,7 +135,7 @@ class SpdxProject:
                 )
             )
         self.main_document.external_refs = externalRefs
-        SpdxProject.generate_tag_value_file(dir, self.main_document, f"{self.main_document.name}.spdx")
+        SpdxProject.generate_tag_value_file(dir, self.main_document, self._spdx_filename(self.main_document.name))
 
     def _report_issues(self, issues: Dict[str, str]) -> None:
         if issues:
@@ -164,7 +174,7 @@ class SpdxProject:
                 package.name
                 for package in [self.main_document, *self.dependency_documents]
                 if (
-                    package.generate_spdx_package().metadata.licence_source == "unknown"
+                    package.generate_spdx_package().metadata.has_unknown_licence
                     or package.generate_spdx_package().main_licence == UNKNOWN_LICENCE.identifier
                 )
                 and not is_package_licence_manually_checked(package.name)

{continuous_delivery_scripts-4.1.0 → continuous_delivery_scripts-4.2.0}/continuous_delivery_scripts/spdx_report/spdx_summary.py

@@ -15,6 +15,8 @@ from continuous_delivery_scripts.spdx_report.spdx_helpers import (
     get_package_manual_check,
 )
 from continuous_delivery_scripts.spdx_report.spdx_package import SpdxPackage
+from continuous_delivery_scripts.utils.configuration import configuration, ConfigurationVariable
+from continuous_delivery_scripts.utils.hash_helpers import generate_uuid_based_on_str
 from continuous_delivery_scripts.utils.third_party_licences import UNKNOWN_LICENCE
 
 JINJA_TEMPLATE_SUMMARY_HTML = "third_party_IP_report.html.jinja2"
@@ -28,6 +30,40 @@ JINJA_TEMPLATES = [
 logger = logging.getLogger(__name__)
 
 
+def _configured_licence_policy() -> List[str]:
+    """List the accepted licence entries as configured, retaining wildcard patterns."""
+    accepted = configuration.get_value(ConfigurationVariable.ACCEPTED_THIRD_PARTY_LICENCES)
+    if isinstance(accepted, str):
+        entries = accepted.split(",")
+    elif isinstance(accepted, (list, tuple, dict)):
+        entries = [str(entry) for entry in accepted]
+    elif isinstance(accepted, set):
+        entries = sorted(str(entry) for entry in accepted)
+    else:
+        entries = []
+    return [entry.strip() for entry in entries if entry.strip()]
+
+
+def _link_report_from_index(output_dir: Path) -> None:
+    """Link the completed TPIP report from a generated documentation index, when present."""
+    index = output_dir / "index.html"
+    report = output_dir / JINJA_TEMPLATE_SUMMARY_HTML.removesuffix(".jinja2")
+    if not index.is_file() or not report.is_file():
+        return
+    contents = index.read_text(encoding="utf8")
+    report_href = f'href="{report.name}"'
+    if report_href in contents:
+        return
+    link = (
+        '<section id="third-party-ip-report"><h2>Third-party IP and licence report</h2>'
+        f"<p><a {report_href}>View the report</a></p></section>"
+    )
+    for closing_tag in ("</main>", "</body>"):
+        if closing_tag in contents:
+            index.write_text(contents.replace(closing_tag, f"{link}{closing_tag}", 1), encoding="utf8")
+            return
+
+
 def _get_jinja2_env() -> jinja2.Environment:
     return jinja2.Environment(
         loader=jinja2.FileSystemLoader(str(Path(__file__).resolve().parent.joinpath("templates"))),
@@ -81,16 +117,25 @@ class SummaryGenerator:
         arguments: Dict[str, Any] = dict()
 
         global_compliance, description_list = self._generate_packages_description()
+        compliance_points = (
+            [
+                "The project and all assessed dependencies meet the configured licence policy, "
+                "including any documented manual reviews.",
+            ]
+            if global_compliance
+            else [
+                "The project or one or more dependencies do not meet the configured licence policy.",
+                "Review the package results below for details.",
+            ]
+        )
         arguments["project"] = {
             "name": self.project.name,
+            "licence": self.project.main_licence,
+            "accepted_licences": _configured_licence_policy(),
             "compliance": global_compliance,
-            "compliance_details": (
-                (
-                    f"Project [{self.project.name}]'s licence is compliant: {self.project.licence}."
-                    "All its dependencies are also compliant licence-wise."
-                )
-                if global_compliance
-                else f"Project [{self.project.name}] or one, at least, of its dependencies has a non compliant licence"
+            "compliance_points": compliance_points,
+            "compliance_details": " ".join(
+                [f"The project is licensed under the {self.project.main_licence} licence.", *compliance_points]
             ),
         }
         arguments["packages"] = description_list
@@ -98,7 +143,7 @@ class SummaryGenerator:
         arguments["unknown_licences"] = sorted(
             p.name
             for p in self.all_packages
-            if p.metadata.licence_source == "unknown" or p.main_licence == UNKNOWN_LICENCE.identifier
+            if p.metadata.has_unknown_licence or p.main_licence == UNKNOWN_LICENCE.identifier
         )
         arguments["unreviewed_licences"] = [
             name for name in arguments["unknown_licences"] if not get_package_manual_check(name)[1]
@@ -112,8 +157,14 @@ class SummaryGenerator:
             self.missing_dependencies or arguments["unreviewed_licences"] or arguments["undocumented_exemptions"]
         )
         if not arguments["project"]["complete"]:
-            details = "Incomplete audit: review missing dependencies, unknown licences and undocumented exemptions."
-            arguments["project"]["compliance_details"] = details
+            compliance_points = [
+                "The licence audit is incomplete.",
+                "Review missing dependencies, unknown licences and undocumented exemptions before using this report.",
+            ]
+            arguments["project"]["compliance_points"] = compliance_points
+            arguments["project"]["compliance_details"] = " ".join(
+                [f"The project is licensed under the {self.project.main_licence} licence.", *compliance_points]
+            )
         arguments["render_time"] = datetime.datetime.now()
         return arguments
 
@@ -148,6 +199,7 @@ class SummaryGenerator:
     ) -> dict:
         return {
             "name": p.name,
+            "anchor": f"package-{generate_uuid_based_on_str(p.name)}",
             "is_dependency": p.is_dependency,
             "url": p.url,
             "licence": p.licence,
@@ -161,12 +213,13 @@ class SummaryGenerator:
             "is_compliant": is_compliant,
             "mark_as_problematic": not is_licence_compliant,
             "licence_compliance_details": (
-                "Licence is compliant."
+                "Automatic licence assessment meets the configured policy."
                 if is_licence_compliant
                 else (
-                    f"Package's licence manually checked: {manual_check_details}"
+                    "Automatic licence assessment does not meet the configured policy; "
+                    f"accepted after manual review: {manual_check_details or 'no reason recorded'}."
                     if package_manually_checked
-                    else "Licence is not compliant according to project's configuration."
+                    else "Automatic licence assessment does not meet the configured policy."
                 )
             ),
         }
@@ -191,3 +244,4 @@ class SummaryGenerator:
         dir.joinpath("third_party_IP_report.json").write_text(
             json.dumps(arguments, indent=2, sort_keys=True) + "\n", encoding="utf8"
         )
+        _link_report_from_index(dir)