[ANE-1250] Adds fossa init command (#1323)

.github/pull_request_template.md

@@ -44,5 +44,5 @@ _Example:_
 - [ ] I added tests for this PR's change (or explained in the PR description why tests don't make sense).
 - [ ] If this PR introduced a user-visible change, I added documentation into `docs/`.
 - [ ] If this change is externally visible, I updated `Changelog.md`. If this PR did not mark a release, I added my changes into an `# Unreleased` section at the top.
-- [ ] If I made changes to `.fossa.yml` or `fossa-deps.{json.yml}`, I updated `docs/references/files/*.schema.json`. You may also need to update these if you have added/removed new dependency type (e.g. `pip`) or analysis target type (e.g. `poetry`).
+- [ ] If I made changes to `.fossa.yml` or `fossa-deps.{json.yml}`, I updated `docs/references/files/*.schema.json` AND I have updated example files used by `fossa init` command. You may also need to update these if you have added/removed new dependency type (e.g. `pip`) or analysis target type (e.g. `poetry`).
 - [ ] If I made changes to a subcommand's options, I updated `docs/references/subcommands/<subcommand>.md`.

Changelog.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 - Maven: add support for maven scope filtering ([#1331](https://github.com/fossas/fossa-cli/pull/1331))
+- `fossa init`: adds new `fossa init` command which creates `.fossa.yml.example`, and `fossa-deps.yml.example` file. ([#1323](https://github.com/fossas/fossa-cli/pull/1323))
 
 ## v3.8.24
 

docs/README.md

@@ -57,6 +57,7 @@ Feature guides explain how to use specific features. These are most useful if th
 Reference guides provide an exhaustive listing of all CLI functionality. If you can't find documentation on how something works elsewhere, it should be here.
 
 - CLI commands
+  - [`fossa init`](./references/subcommands/init.md)
   - [`fossa analyze`](./references/subcommands/analyze.md)
   - [`fossa test`](./references/subcommands/test.md)
   - [`fossa report`](./references/subcommands/report.md)

docs/references/subcommands/init.md

@@ -0,0 +1,9 @@
+## `fossa init`
+
+The `fossa init` command creates _examples_ of the following files if they do not exist in the current working directory:
+
+- [.fossa.yml](./../files/fossa-yml.md): `fossa-cli` Configuration file
+- [fossa-deps.yml](./../files/fossa-deps.md): File for stubbing and manually providing dependencies
+
+Note that both the `.fossa.yml` and `fossa-deps.yml` files are optional.
+They allow for more specificity on how fossa-cli performs dependency analysis, but they are not required for `fossa-cli` usage.

spectrometer.cabal

@@ -199,6 +199,7 @@ library
     App.Fossa.DumpBinaries
     App.Fossa.EmbeddedBinary
     App.Fossa.FirstPartyScan
+    App.Fossa.Init
     App.Fossa.Lernie.Analyze
     App.Fossa.Lernie.Types
     App.Fossa.LicenseScan
@@ -516,6 +517,7 @@ test-suite unit-tests
     App.Fossa.Container.AnalyzeNativeSpec
     App.Fossa.Container.AnalyzeNativeUploadSpec
     App.Fossa.FirstPartyScanSpec
+    App.Fossa.InitSpec
     App.Fossa.LernieSpec
     App.Fossa.LicenseScannerSpec
     App.Fossa.ManualDepsSpec

src/App/Docs.hs

@@ -1,6 +1,7 @@
 module App.Docs (
   userGuideUrl,
   newIssueUrl,
+  fossaDepsDocUrl,
   fossaYmlDocUrl,
   strategyLangDocUrl,
   platformDocUrl,
@@ -24,6 +25,9 @@ userGuideUrl = guidePathOf versionOrBranch "/docs/README.md"
 fossaYmlDocUrl :: Text
 fossaYmlDocUrl = guidePathOf versionOrBranch "/docs/references/files/fossa-yml.md"
 
+fossaDepsDocUrl :: Text
+fossaDepsDocUrl = guidePathOf versionOrBranch "/docs/references/files/fossa-deps.md"
+
 newIssueUrl :: Text
 newIssueUrl = sourceCodeUrl <> "/issues/new"
 

src/App/Fossa/Init.hs

@@ -0,0 +1,71 @@
+{-# LANGUAGE TemplateHaskell #-}
+
+module App.Fossa.Init (
+  initCommand,
+
+  -- * testing only
+  mkFossaYml,
+  mkFossaDeps,
+  exampleFossaYml,
+  exampleFossaDeps,
+) where
+
+import Control.Algebra (Has)
+import Control.Carrier.Diagnostics (Diagnostics, logWithExit_)
+import Control.Carrier.Lift (sendIO)
+import Control.Carrier.Stack (runStack)
+import Control.Carrier.Telemetry (withTelemetry)
+import Control.Effect.Lift (Lift)
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.FileEmbed.Extra (embedFileIfExists)
+import Effect.Logger (Logger, Severity (SevInfo), logInfo, pretty, withDefaultLogger)
+import Effect.ReadFS (ReadFS, getCurrentDir, runReadFSIO)
+import Options.Applicative (CommandFields, Mod, Parser, info, progDesc)
+import Options.Applicative.Builder (command)
+import Path (
+  Abs,
+  Dir,
+  File,
+  Path,
+  Rel,
+  mkRelFile,
+  toFilePath,
+  (</>),
+ )
+
+initCommand :: Mod CommandFields (IO ())
+initCommand = command "init" (info run $ progDesc "Creates .fossa.yml.example and fossa-deps.yml.example file")
+  where
+    run :: Parser (IO ())
+    run = pure $ withTelemetry . runStack . withDefaultLogger SevInfo . logWithExit_ . runReadFSIO $ runInit
+
+runInit :: (Has Diagnostics sig m, Has (Lift IO) sig m, Has ReadFS sig m, Has Logger sig m) => m ()
+runInit = do
+  dir <- getCurrentDir
+  mkFossaYml dir
+  mkFossaDeps dir
+
+mkFossaYml :: (Has Diagnostics sig m, Has (Lift IO) sig m, Has Logger sig m) => Path Abs Dir -> m ()
+mkFossaYml baseDir = do
+  let fossaYmlExample = baseDir </> fossaYmlFile
+  sendIO $ BS.writeFile (toFilePath fossaYmlExample) exampleFossaYml
+  logInfo . pretty $ "Wrote example configuration File: " <> (toFilePath fossaYmlExample)
+
+mkFossaDeps :: (Has Diagnostics sig m, Has (Lift IO) sig m, Has Logger sig m) => Path Abs Dir -> m ()
+mkFossaDeps baseDir = do
+  let fossaDepsYml = baseDir </> fossaDepsYmlFile
+  sendIO $ BS.writeFile (toFilePath fossaDepsYml) exampleFossaDeps
+  logInfo . pretty $ "Wrote example fossa-deps File: " <> (toFilePath fossaDepsYml)
+
+exampleFossaYml :: ByteString
+exampleFossaYml = $(embedFileIfExists "src/App/Fossa/Init/.fossa.yml")
+
+exampleFossaDeps :: ByteString
+exampleFossaDeps = $(embedFileIfExists "src/App/Fossa/Init/fossa-deps.yml")
+
+fossaYmlFile :: Path Rel File
+fossaYmlFile = $(mkRelFile ".fossa.yml.example")
+
+fossaDepsYmlFile :: Path Rel File
+fossaDepsYmlFile = $(mkRelFile "fossa-deps.yml.example")

src/App/Fossa/Init/.fossa.yml

@@ -0,0 +1,197 @@
+# # fossa-cli configuration file.
+# #
+# # All fields are optional except 'version' field.
+# #
+# #  To learn more:
+# #   - https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-yml.md
+# #
+# #  If you need assistance, or would like to file a defect, contact support at:
+# #   - https://support.fossa.com/
+# #
+# # -----
+
+version: 3
+
+# # Sets the endpoint that the CLI will send requests to.
+# # Modify only if your FOSSA account lives on a different server than app.fossa.com.
+# # Default: https://app.fossa.com
+# server: https://app.fossa.com
+#
+#
+# # Sets the FOSSA API key required for accessing the FOSSA API and uploading/retrieving project data.
+# # FOSSA strongly recommends setting the API key with the $FOSSA_API_KEY environment variable for security.
+# # See documentation for details: https://docs.fossa.com/docs/api-reference
+# apiKey: a1b2c3
+#
+#
+# # Configures settings for the project you are interacting with through the FOSSA API.
+# project:
+#   # Defines a unique ID that the FOSSA API will use to reference this project.
+#   # Default:
+#   #   - Git: From .git/config file or project's remote "origin" URL.
+#   #   - SVN: From "Repository Root" obtained using 'svn info'.
+#   #   - No VCS: Name of the project's directory.
+#   # 
+#   # NOTE:
+#   #   A project's ID cannot be modified after a project is created. If you change the ID, 
+#   #   you will be interacting with a different project. If the new ID does not exist, 
+#   #   a new project will be created for it.
+#   id: github.com/fossas/fossa-cli
+#
+#   # Project Name Configuration
+#   # Sets the project's visible name in the FOSSA dashboard.
+#   # Default: Project's ID
+#   #
+#   # NOTE:
+#   #   Can only be set when creating a project (running fossa analyze for the first time),
+#   #   Otherwise, they will be silently ignored.
+#   name: fossa-cli
+#
+#   # Name of the team in your FOSSA organization to associate with this project.
+#   # NOTE:
+#   #   Can only be set when creating a project (running fossa analyze for the first time),
+#   #   Otherwise, they will be silently ignored.
+#   team: cli-team
+#
+#   # Name of the policy in your FOSSA organization to associate with this project.
+#   # NOTE:
+#   #   Can only be set when creating a project (running fossa analyze for the first time),
+#   #   Otherwise, they will be silently ignored.
+#   policy: custom-cli-policy
+#
+#   # An external link that will appear in the FOSSA UI for this specific project.
+#   # NOTE:
+#   #   Can only be set when creating a project (running fossa analyze for the first time),
+#   #   Otherwise, they will be silently ignored.
+#   link: fossa.com
+#
+#   # The URL of your project that will appear in FOSSA.
+#   # Intended to be the URL to the repository of this project.
+#   url: github.com/fossas/fossa-cli
+#
+#   # Jira Project Key to associate with your project for improved issue triage.
+#   # See documentation for details: https://docs.fossa.com/docs/atlassian-jira
+#   #
+#   # NOTE:
+#   #   Can only be set when creating a project (running fossa analyze for the first time),
+#   #   Otherwise, they will be silently ignored.
+#   jiraProjectKey: jira-key
+#
+#   # The 'name' and 'release' of the release group's release to add your project to in the FOSSA dashboard.
+#   # See documentation for details: https://docs.fossa.com/docs/release-groups
+#   #
+#   # NOTE:
+#   #   If you choose to associate a project with a release group, you must supply both name and release.
+#   releaseGroup:
+#     name: release-group-name
+#     release: 123-release-candidate
+#
+#   # Allows you to add labels to projects for classification in the FOSSA UI.
+#   # See documentation for details: https://docs.fossa.com/docs/projects-ui-whats-new#labels
+#   labels:
+#     - project-label-1
+#     - test-project
+#
+#
+# # Revision associated with project scan.
+# revision:
+#   # Used to identify a specific scan for a project.
+#   # Default:
+#   #   - Git: Commit hash of the HEAD branch (inferred from current HEAD state in the .git directory)
+#   #   - SVN: "Revision" obtained using 'svn info' command.
+#   #   - No VCS: Unix timestamp.
+#   commit: "12345"
+#
+#   # Optional setting used for organizing project revisions in the FOSSA UI.
+#   # Default:
+#   #   - Git: Current branch from .git/config file.
+#   #   - SVN: "URL" or "Repository Root" fields using `svn info` command.
+#   #   - No VCS: Empty.
+#   branch: master
+#
+#
+# # Vendored Dependencies Configuration
+# # See documentation for details: https://github.com/fossas/fossa-cli/blob/master/docs/features/vendored-dependencies.md
+# vendoredDependencies:
+#   # If true, forces a re-scan of all vendored dependencies on every run. Default: false
+#   forceRescans: false
+# 
+#   # Determines whether vendored dependencies are scanned using "Archive Upload" or "CLI License Scan" method.
+#   # Possible values: ArchiveUpload, CLILicenseScan.
+#   # The default is usually "CLILicenseScan", but your organization may have opted to default to "ArchiveUpload".
+#   scanMethod: CLILicenseScan
+# 
+#   # License Scan Path Filters Configuration
+#   # Path filtering to omit some files or directories from license scanning.
+#   # See documentation for details: https://github.com/fossas/fossa-cli/blob/master/docs/features/vendored-dependencies.md#path-filtering
+#   licenseScanPathFilters:
+#     only:
+#       - "**/*.rb"
+#     exclude:
+#       - ".git/**"
+#       - "test/**/*.rb"
+#
+#
+# # Targets Configuration
+# # Filtering section to specify exact targets to be scanned.
+# # See documentation for details: https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-yml.md#analysis-target-configuration
+# # See walkthough for example usage: https://github.com/fossas/fossa-cli/blob/master/docs/walkthroughs/analysis-target-configuration.md
+# targets:
+#   # The list of only targets that should be scanned. When used alongside paths.only, 
+#   # the intersection of the two lists is taken to find targets for scanning.
+#   only:
+#     - type: maven
+#       path: foo/bar
+#
+#   # The list of exclude targets which should be excluded from scanning. 
+#   # The targets listed in the exclude section will override the targets listed in the only 
+#   # sections. This feature is used most effectively to remove specific targets from a directory. 
+#   exclude:
+#     - type: bundler
+#       path: prod/docker
+#
+#
+# # Paths Configuration
+# # Filtering section to specify which paths should be scanned or excluded.
+# # See documentation for details: https://github.com/fossas/fossa-cli/blob/master/docs/references/files/fossa-yml.md#paths
+# # See walkthough for example usage: https://github.com/fossas/fossa-cli/blob/master/docs/walkthroughs/analysis-target-configuration.md
+# paths:
+#   # The list of paths to only allow scanning within.
+#   # This section is most commonly used when you would like to restrict scanning 
+#   # to a certain list of directories from the root of your project.
+#   only:
+#     - ./production
+#
+#   # The list of paths to exclude from scanning in your directory.
+#   # This section is intended to be used as the inverse to paths.only. 
+#   # If you have a certain directory such as development you wish to exclude, 
+#   # paths.exclude enables you to do this.
+#   exclude:
+#     - ./vendor/django/test
+#
+#
+# # Telemetry Configuration
+# # Sets the telemetry configurations.
+# telemetry:
+#   # 'full' emits telemetry data to the server, 'off' does not. Default: 'full'.
+#   scope: full
+#
+#
+# # FOSSA offers the ability to search your codebase using regular expressions 
+# # and to report matches. 'customLicenseSearch' can be used to search codebase
+# # with regular expression to mark custom licenses, with project.
+# # See documentation for details: https://github.com/fossas/fossa-cli/blob/master/docs/features/custom-license-and-keyword-searches.md#custom-license-and-keyword-searches
+# customLicenseSearch:
+#     # matchCriteria is a regular expression used to find the thing you are searching for
+#     # https://github.com/fossas/fossa-cli/blob/master/docs/features/custom-license-and-keyword-searches.md#regular-expression-format
+#   - matchCriteria: "[Pp]roprietary [Ll]icense"
+#
+#     # name is a description of what you are searching for
+#     name: "Proprietary License"
+#
+#
+# # Defines experimental keyword search criteria.
+# # See documentation for details: https://github.com/fossas/fossa-cli/blob/master/docs/features/custom-license-and-keyword-searches.md#keyword-searches
+# experimentalKeywordSearch:
+#  - matchCriteria: abc123
+#    name: Password