From 2d5264d166a86dcf82207416bdb114d3aadbe629 Mon Sep 17 00:00:00 2001
From: Ben Kettle <ben@semgrep.com>
Date: Wed, 30 Oct 2024 13:29:05 -0700
Subject: [PATCH] chore(sca): add comments to manifest kinds (#305)

In order to consolidate the `manifest_kind` type in interfaces with
`Manifest_kind.ml`, this PR:
- transfers the comments from the ML file to interfaces
- adds `eq`, `show`, and `yojson` derivations to the ATD definition

- [x] I ran `make setup && make` to update the generated code after
editing a `.atd` file (TODO: have a CI check)
- [x] I made sure we're still backward compatible with old versions of
the CLI.
For example, the Semgrep backend need to still be able to *consume* data
generated
	  by Semgrep 1.17.0.
See
https://atd.readthedocs.io/en/latest/atdgen-tutorial.html#smooth-protocol-upgrades
---
 semgrep_output_v1.atd   | 25 ++++++++++++++++++-------
 semgrep_output_v1_j.ml  |  1 +
 semgrep_output_v1_j.mli |  1 +
 3 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/semgrep_output_v1.atd b/semgrep_output_v1.atd
index 20446d1..c4cf44d 100644
--- a/semgrep_output_v1.atd
+++ b/semgrep_output_v1.atd
@@ -1824,22 +1824,33 @@ type output_format = [
   | Emacs
 ]
 
-(* TODO: merge with Manifest_kind.ml *)
-type manifest_kind <python decorator="dataclass(frozen=True)"> = [
-  | RequirementsIn (* Manifest file for pip *)
+type manifest_kind 
+  <ocaml attr="deriving show, eq, yojson">
+  <python decorator="dataclass(frozen=True)">   = [
+  | RequirementsIn
+    (* A Pip Requirements.in in file, which follows the format of requirements.txt - https://pip.pypa.io/en/stable/reference/requirements-file-format/ *)
   | PackageJson
+    (* An NPM package.json manifest file - https://docs.npmjs.com/cli/v10/configuring-npm/package-json *)
   | Gemfile
-  | GoMod
+    (* A Ruby Gemfile manifest - https://bundler.io/v2.5/man/gemfile.5.html *)
+  | GoMod (* go.mod - https://go.dev/doc/modules/gomod-ref *)
   | CargoToml
+    (* cargo.toml - https://doc.rust-lang.org/cargo/reference/manifest.html *)
   | PomXml
+    (* A Maven pom.xml manifest file - https://maven.apache.org/guides/introduction/introduction-to-the-pom.html *)
   | BuildGradle
-  | ComposerJson
+    (* A Gradle build.gradle build file  - https://docs.gradle.org/current/userguide/build_file_basics.html *)
+  | ComposerJson (* composer.json - https://getcomposer.org/doc/04-schema.md *)
   | NugetManifestJson
-  | PubspecYaml
+    (* manifest for nuget - could not find a reference; this may not actually exist *)
+  | PubspecYaml (* pubspec.yaml - https://dart.dev/tools/pub/pubspec *)
   | PackageSwift
+    (* Package.swift - https://docs.swift.org/package-manager/PackageDescription/PackageDescription.html *)
   | MixExs
-  | Pipfile
+    (* mix.exs - https://hexdocs.pm/elixir/introduction-to-mix.html#project-compilation *)
+  | Pipfile (* Pipfile - https://pipenv.pypa.io/en/latest/pipfile.html *)
   | PyprojectToml
+    (* pyproject.toml - https://packaging.python.org/en/latest/guides/writing-pyproject-toml/ *)
 ]
 
 type manifest = {
diff --git a/semgrep_output_v1_j.ml b/semgrep_output_v1_j.ml
index 00497e4..47e7fb1 100644
--- a/semgrep_output_v1_j.ml
+++ b/semgrep_output_v1_j.ml
@@ -659,6 +659,7 @@ type partial_scan_result = Semgrep_output_v1_t.partial_scan_result
 type output_format = Semgrep_output_v1_t.output_format
 
 type manifest_kind = Semgrep_output_v1_t.manifest_kind
+  [@@deriving show, eq, yojson]
 
 type manifest = Semgrep_output_v1_t.manifest = {
   kind: manifest_kind;
diff --git a/semgrep_output_v1_j.mli b/semgrep_output_v1_j.mli
index 89cd809..e068f28 100644
--- a/semgrep_output_v1_j.mli
+++ b/semgrep_output_v1_j.mli
@@ -659,6 +659,7 @@ type partial_scan_result = Semgrep_output_v1_t.partial_scan_result
 type output_format = Semgrep_output_v1_t.output_format
 
 type manifest_kind = Semgrep_output_v1_t.manifest_kind
+  [@@deriving show, eq, yojson]
 
 type manifest = Semgrep_output_v1_t.manifest = {
   kind: manifest_kind;