listendev / lstn

A CLI tool to analyze the behavior of your dependencies using listen.dev

lstn

lstn is the listen.dev command line. It lets you analyze the behavior of your dependencies.

Documentation

To install lstn in your environment, refer to the installation section below. For usage instructions, see:

• the usage manual
• the guide about the ~/.lstn.yaml config file
• the guide about the LSTN_* environment variables
• the reporters reference

Installation

CI

GitHub Actions

We recommend using the GitHub Action for running lstn in CI for GitHub projects. For integration instructions see this guide.

Other CI

It's highly recommended to install a specific version of lstn available on the releases page. Here are a few ways to install it:

# The binary will be /usr/local/bin/lstn
curl -sSfL https://lstn.dev/get | sh -s -- -b /usr/local/bin

# Or install it into $PWD/bin/
curl -sSfL https://lstn.dev/get | sh -s

# In Alpine Linux (as it does not come with curl by default)
wget -O- -nv https://lstn.dev/get | sh -s

You can test the installation by running:

lstn version

Locally

To install lstn locally, see the options below:

Binaries

curl -sSfL https://lstn.dev/get | sh -s -- -b /usr/local/bin
lstn version

macOS

lstn is available via TODO: Homebrew, ..., and as a downloadable binary from our releases page.

Linux & BSD

lstn is available via:

• TODO: our Debian and RPM repositories
• OS-agnostic package managers such as TODO: Homebrew, ...
• our releases pages as precompiled binaries.

From source

We recommend using binary installation. Using go install or go get might work but those aren't guaranteed to.

Why?

1. Some users use the -u flag for go get which upgrades our dependencies: we can not guarantee they work!
2. The go.mod replacement directive doesn't apply.
3. The lstn stability may depend on a user's Go version.
4. It allows installation from the main branch which can't be considered stable.
5. It is way slower than binary installation.

Contributing

If anything feels off, or if you feel that some functionality is missing, please check out the contributing page.

There you will find instructions for sharing your feedback, building the tool locally, and submitting pull requests to the project.

lstn's Issues

Fix the changelog URL returned by the lstn version command

Describe the bug

The generated GitHub release URL is wrong. It contains also version metadata but it MUST not.

Steps to reproduce the behavior

Run lstn version on a release tag and notice that the changelog URL points to a wrong GitHub release URL.

Expected vs actual behavior

I'd expect the generated GitHub release URL to not contain the metadata part (after the"+" sign) of the version.

Logs

NONE

Create the --jq flag

Describe the feature or problem you’d like to solve

Currently, it is possible (and it comes in very handy) to pipe the lstn JSON output to JQ.

Example:

export LSTN_ENDPOINT=https://smtg.listen.dev/
./lstn to postcss-clean --json | jq -c '.[] | select(.verdicts[].severity == "critical") | halt_error(1)'

Problem is that this requires the JQ tool to be installed on the system.

Proposed solution

We should embed a Go implementation of the JQ engine and tie it to a --jq (shorthand -q) flag so that lstn users can filter the (JSON) output directly from our CLI.

When done, I expect this to work:

export LSTN_ENDPOINT=https://smtg.listen.dev/
./lstn to postcss-clean --json -q ".[] | select(.verdicts != [])"

Additional context

Since JQ queries can rewrite the resulting structure we can use this mechanism only with JSON output, not with struct-based output.

Add a version command

Describe the feature or problem you’d like to solve

Provide users info on the version of the CLI

Proposed solution

Display the current version of the CLI using lstn --version or lstn -v

Linked with goreleaser

Send the lstn version with the user agent

Describe the feature or problem you’d like to solve

Not a big deal but it would be nice to augment the user agent with the current lstn version.

Proposed solution

The proposed solution will implement a lightweight telemetry mechanism so that we'll know which lstn version our users are currently using the most.

Additional context

Send the short and long lstn versions.

Detect the caller function and set it into the user agent header

Describe the feature or problem you’d like to solve

We may automatically grab the function executing the HTTP request for the same reasons outlined in #27 and #39.

Having the caller function will give us more granularity in understanding *what the user was using the lstn CLI for.

Proposed solution

In the comment part of the first part of the user-agent header we store the function performing the HTTP request (eg., github.com/listendev/lstn/pkg/npm.GetFromRegistry.

Additional context

NONE

Document the way we label the pull requests for changelog generation

Output ASCII tables

Describe the feature or problem you’d like to solve

Some commands dump the Go objects to the terminal (except when the --json flag gets used).

@fntlnz suggests letting these child commands (for example in and to) output ASCII tables to the terminal by default.

Proposed solution

Giving a nerdy (but not TUI) output is needed.

Additional context

NONE

Check if the Stderr buf can ever be full

• check if len(e.Stderr) > 0
• if so, append it to the error with string(e.Stderr)

Originally posted by @leodido in #68 (comment)

In that case, sync with @leodido on what to do.

Proxy npm logs

Describe the feature or problem you’d like to solve

Currently, when executing lstn in against an invalid package.json file (either because of syntax or semantic errors) it returns a generic error (see #62).

Proposed solution

We could proxy (some?) of the npm error logs to better explain to the user why lstn in couldn't work (I mean, even npm couldn't but...).

Additional context

NONE

Output in markdown

Describe the feature or problem you’d like to solve

I think that some commands (definitely the help topics) would benefit from rendering their output in markdown in the terminal.

Proposed solution

Out users will surely benefit from the improved legibility.

Additional context

Investigate charm.sh libraries.

Send the OS info via the User-Agent header

Describe the feature or problem you’d like to solve

We wanna know from which OS the lstn CLI was invoked.

Proposed solution

I propose to set the User-Agent header (like in #27) and store OS info (if available) like:

• os
• architecture
• kernel
• kernel version

Additional context

NONE

Point to different URL paths when backend is running locally

Describe the bug

The backend implementation sees the following distinctions in the URL path:

• /api/verdicts/ -> /api/npm/verdicts
• /api/analysis -> /api/npm/analysis

Please include:

• Version: lstn 9118714.20230208
• OS: Darwin

Steps to reproduce the behavior

1. Type lstn to <package-name> --endpoint=http://localhost:3000
2. An error is throw because the route is not found

Expected vs actual behavior

We want to automatically switch to the correct one, upon LSTN_ENDPOINT env var or --endpoint flag.

Logs

Running without a configuration file
Error: 

Generate manpages

Describe the feature or problem you’d like to solve

As with many other CLI tools out there, lstn should have its own man pages.

Proposed solution

Users will benefit from running man lstn and getting to read a manual about lstn.

Additional context

It should be possible to automatically generate them from Cobra commands.

Do not release against a shallow clone

Describe the bug

Some Goreleaser features (eg., the changelog generation with github provider) require git fetch depth to be 0.

See https://goreleaser.com/ci/actions/#fetch-depthness.

Steps to reproduce the behavior

Run a release.

Expected vs actual behavior

The changelog is to be generated properly.

Logs

NONE

Remove persistent flags on additional commands

Describe the feature or problem you’d like to solve

The lstn CLI comes with a set of persistent flags (eg., --endpoint, --timeout, etc.).

But it also comes with a few additional commands (eg., version, completion, etc.) that do not need or use them.

Proposed solution

Remove them from the additional commands.

Additional context

NONE

Automatically check every source file has a license header

Switch to GitHub native release notes

We wanna use the GitHub native release note generation mechanism.

It works on top of the pull request labels. See more at https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes.

Goreleaser supports it.

Store the git remote URL in the context

Describe the feature or problem you’d like to solve

When asking for an analysis of package.json, other than the package-lock.json and the list of the packages, the endpoint also accepts a context object.

This object is useful for attaching to the request a set of metadata for later processing.

This metadata should contain the git remote URL (if available).

Proposed solution

If lstn gets executed in a git repository we should fetch the git remote and set it into the context of the analysis requests.

Additional context

NONE

Setup CI to cross-build the CLI

Pull request automation

Describe the feature or problem you’d like to solve

We're about to release lstn in the open.

We need automation to encourage external contributions and also to ensure a good level of health and sanity of this repository.

Proposed solution

• #78
• Praise the contributors on pull requests
• Automatically label pulls depending on size
• Automatically label pulls depending on file changes
• Automatically bring attention up to pull requests waiting for reviews

Additional context

NONE

Support lockfileVersion 1

Describe the feature or problem you’d like to solve

When the npm version is 6.x it generates package-lock.json files with version 1.

We don't support those at the moment in the CLI, but we should because:

• we check for the npm version to be >= 6.x in the CLI
• listen.dev API supports them now

Proposed solution

Add support for lockfileVersion 1.

Additional context

NONE

Automatically add label "needs-triage" to new issues

Only for new issues incoming from OSS contributors not in the listendev organization.

Make the release process inject the version

Describe the bug

The current lstn version on release artifacts is wrong.

Steps to reproduce the behavior

If you download the current release (v0.0.1) and execute

lstn version

You will get 59dc0556.20230216 as version, which is wrong. Or at least, it is different from what you'd get if you build the git tag v0.0.1 on the main branch with make/make lstn.

In fact, in this case, you'll get version to be v0.0.1+59dc0556.20230216 (correct).

Expected vs actual behavior

Expect: <git_tag>+<commit_hash>.
Actual: <commit_hash>.

Logs

NONE.

Enforce pull request titles to follow Conventional Commits v1.0 spec

To implement #90 and avoiding having to manually label all the pull requests for changelog generation,
we want the pull requests title to follow the Conventional Commits v1.0 spec.

This way, we can write rules that, by looking at the pull request title, file changes, and even the branch name, automatically label the pull request.

Generate SBOMs

Describe the feature or problem you’d like to solve

A SBOM is a description of the components that make up a software artifact.

We should generate the Software Bill of Materials (SBOMs) while releasing, for all of the output artifacts.

Proposed solution

Goreleaser supports this. See docs.

Additional context

NONE.

Respect the git config semantics

Describe the feature or problem you’d like to solve

We collect git context information for telemetry reasons.

This info is grabbed from the Git config on the system executing lstn. To facilitate the task we are using as a dependency the go-git v5 Go module.

Its current implementation does not respect the Git config semantics, tho.

In particular, when reading the Git configuration of a repository (if found) it doesn't merge the local Git configuration with the global and the system Git configs (if present).

Furthermore, it also parses the Git configuration strictly exiting even if a section is wrong (while Git doesn't behave like that).

We need to collect the precise Git config of the user's repository because we send it as part of the POST HTTP requests for telemetry reasons.

Proposed solution

We'll be able to know who's using the CLI and spot bugs, give support faster and easily.

Additional context

See go-git/go-git#395

Create task to git tag ensuring a semantic version

Describe the feature or problem you’d like to solve

We are approaching the first release... 📦

We plan to release via GitHub releases by using git tags. At the same time, we wanna be sure that who's gonna release always uses a semantic version while git tagging the main branch.

Proposed solution

Create a task tag in the existing custom make/make tool.

It should get a string as an argument and check it's a valid SemVer tag.

Additional context

NONE

Add npm version to context

Describe the feature or problem you’d like to solve

In order to gather data for future analysis, we want to add the npm version to the context.

Proposed solution

Add it.

Additional context

None.

Remove the fetching of shasums from the npm registry

Describe the feature or problem you’d like to solve

At the moment, lstn fetches the shasum of every dependency in the generated package-lock.json file (there could be thousands!).

Why so? Because the previous version of our backend was trusting the input so it was not calling the registry.
Now it does call it.
Also, we wanted to offload as much as possible computation to the clients' machines. But since the scheduler now fetches such info, there is no need to duplicate it.

Proposed solution

Thus, it is now possible to remove the code that calls the registry and also make the CLI a lotta faster.

Additional context

Original idea by @fntlnz.

Validate the package name (`lstn to`)

Describe the feature or problem you’d like to solve

Currently, the lstn CLI does NOT validate the package name when invoking lstn to ....

Proposed solution

We should check that:

• the package name is an npm valid package name

We could also check that:

• the package actually exists on the npm registry before sending any query

I'm not sure we wanna do this (it would require an HTTP request) at the validation level, tho.
Maybe it would be better to do this after, crafting a client-side problem response.

Additional context

NONE

Switch the implementation of `lstn to` to POST HTTP call

Describe the feature or problem you’d like to solve

We wanna switch the lstn to implementation to using a POST HTTP call to our services.

This way, by also sending the context in the payload, we have telemetry also for the to child command invokations.

Proposed solution

Switch the HTTP method from GET to POST.

Additional context

NONE

Support Git URLs as argument

Describe the feature or problem you’d like to solve

Currently the lstn in command accepts package.json manifest files present in <path>, where <path> is a reference to a directory located on the local machine.

Proposed solution

It would be useful to support URLs for specifying the <path> to package.json, for example:

lstn in https://github.com/tierrun/node-sdk/blob/main/package.json

Additional context

Would be useful for scanning projects without having to clone the project locally, and could also result in a wider range of use cases and help with internal testing and data harvesting.

Annotate every command with their source file

Describe the feature or problem you’d like to solve

While building our internal tool for generating the manpages of lstn I've noticed that it would be very useful to populate the source part of the manpages headers.

Proposed solution

Annotate every command with a "source" key containing the path (or the URL, better IMO) of the current source file.

This way, the users would be able to jump directly into the source code while documenting themselves about any lstn command.

Additional context

NONE

Implement the releasing mechanism

Describe the feature or problem you’d like to solve

When do we release it? C'mon! 😄

To do so, we should have an automated release mechanism.

Proposed solution

Phase 1:

• MacOS artifacts
• Linux artifacts
• Archive the artifacts into the GitHub release
• #82
• #81
• #84

Phase 2:

• #83

Additional context

Double-check that the way that Goreleaser builds lstn is equal to the way we do it via the make/make script for local development.

Error: json: cannot unmarshal number into Go struct field

Describe the bug

When running lstn to <package> the following error is seen:
Error: json: cannot unmarshal number into Go struct field Verdict.verdicts.metadata of type string

Steps to reproduce the behavior

1. Run lstn to with the package name and no flags e.g. lstn to jq
2. View the output

Environment

lstn version: 807cfc9.20230209
go version: go1.19.4 darwin/arm64
macOS Monterey 12.0.1

Expected vs actual behavior

If you run lstn to <name> --json it works.
Ideally the default usage case (without --json flag) should work as described in the CLI description (e.g. lstn to chalk)

Logs

Error: json: cannot unmarshal number into Go struct field Verdict.verdicts.metadata of type string

Adjust Bug report template

Describe the bug

The command to retrieve the version is lstn version, and not lstn --version.

Steps to reproduce the behavior

1. Type lstn --version
2. View the error 'Error: unknown flag: --version'

Expected vs actual behavior

The template should advice the correct command.

Adopt a CLA

For external contributions from the community:

• Adopt a form of CLA
• Implement a GitHub action bot to automate its execution

Add unit tests

Create a devcontainer

Describe the feature or problem you’d like to solve

We should provide our OSS contributors with a .devcontainer/devcontainer.json.

Proposed solution

By providing a .devcontainer/devcontainer.json we will make the process of contributing to the lstn CLI even more straightforward, even from browsers.

Users will be able to spawn a suited GitHub codespace to contribute to it.

Additional context

NONE

Generate changelog automatically

Describe the feature or problem you’d like to solve

Since we are now enforcing the usage of Conventional Commits v1.0 spec (see #79),
we can now instruct Goreleaser to use the commit messages from the previous git tag to the current one to generate a changelog.

Proposed solution

Goreleaser has a mechanism to do it. See docs.

We must group commits by category, ie., breaking changes vs features vs bug fixes.

Also, we must ignore not significant commits.

Additional context

NONE

Generate Linux packages

Describe the feature or problem you’d like to solve

It would be cool to generate Linux packages at release time.

Proposed solution

Goreleaser supports nfpm.
We should integrate it letting it generate apk, deb, rpm, and archlinux Linux packages.

Additional context

An initial (but not completed) implementation is already in place but commented out.

Store the lstn version in the analysis context

Describe the feature or problem you’d like to solve

Similar reasoning of #50 and #22

Proposed solution

Append the lstn (short and long) versions in the analysis context.

Additional context

NONE

Setup issue templates

Create community-facing pages

Add the following pages to the repo:

• SECURITY.md
• CODE_OF_CONDUCT.md
• CHANGELOG.md

Check commits (from now on) follow Conventional Commits v1.0 spec

Describe the feature or problem you’d like to solve

We approach the first release of lstn.

We need an automated way to generate beautiful changelogs for future releases from commit messages.

To do so we need our commit messages to follow a convention.

In the past, I've written a blazingly fast and precise parser for Conventional Commits v1.0 specification.

I know that reviewpad uses it for providing commit linting on pull requests.

Proposed solution

Install and configure a reviewpad workflow that checks the commits are following the Conventional Commits v1.0 specification.

Additional context

• https://github.com/leodido/go-conventionalcommits
• https://docs.reviewpad.com/

Help topics

Describe the feature or problem you’d like to solve

I think we need to provide commands that don't actually run or execute anything.

Their scope would be to output some kind of documentation about the lstn CLI to its users.

Proposed solution

I propose to create the following "help topics":

• lstn help manual
• lstn help exit
• lstn help config
• lstn help environment

Additional context

NONE

Couldn't generate the package-lock.json file for certain projects

Describe the bug

Facing the below error when scanning certain project repos (e.g. tier and n8n)

Error: couldn't generate the package-lock.json file for certain projects

Steps to reproduce the behavior

1. Clone the project repo
2. Run lstn in inside the project root
3. View the output Error: couldn't generate the package-lock.json file

Environment

• lstn version: 807cfc9.20230209
• go version: go1.19.4 darwin/arm64
• macOS Monterey 12.0.1

Expected vs actual behavior

Currently, if you run lstn to tier --json it works.
Running lstn in for a project's package.json should return the same output as using lstn to <package>.

Store the OS info in the context

Describe the feature or problem you’d like to solve

For telemetry reasons it may be good to detect and store the OS the users are running on.

Proposed solution

We catch the OS the lstn CLI is run on.

Also the architecture, the kernel, and its version.

If possible.

Additional context

NONE

Detect if the npm install was already done

Describe the feature or problem you’d like to solve

This CLI is meant to be used before installing any dependency, theoretically.

So, we should detect if the users already run npm install and warn them accordingly.

Doing this will - hopefully - raise awareness about the packages getting installed.

Proposed solution

Checking whether the node_modules and/or the package-lock.json already exists in the target directory should suffice.

Additional context

NONE

Keyless sign release artifacts

Describe the feature or problem you’d like to solve

We wanna the release artifacts to be signed.

Proposed solution

Using cosign keyless signing.

Goreleaser should support it (see example).

Additional context

NONE