Skip to content

Commit

Permalink
Merge pull request #67 from smorimoto/prepare-2.0.3
Browse files Browse the repository at this point in the history
Prepare 2.0.3
  • Loading branch information
febuiles committed Jan 22, 2024
2 parents ce17ae9 + cede478 commit bf1a8f9
Show file tree
Hide file tree
Showing 5 changed files with 98 additions and 121 deletions.
72 changes: 26 additions & 46 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,66 +1,46 @@
# Dependency Submission Toolkit

`@github/dependency-submission-toolkit` is a TypeScript library for
creating dependency snapshots and submitting them to the dependency
submission API. Snapshots are a set of dependencies grouped by manifest with
some related metadata. A manifest can be a physical file or a more abstract
representation of a dependency grouping (such the processing of program
outputs). After submission to the API, the included dependencies appear in the
repository's [dependency
graph](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph).
`@github/dependency-submission-toolkit` is a TypeScript library for creating
dependency snapshots and submitting them to the dependency submission API.
Snapshots are a set of dependencies grouped by manifest with some related
metadata. A manifest can be a physical file or a more abstract representation of
a dependency grouping (such processing of program outputs). After submission to
the API, the included dependencies appear in the repository's
[dependency graph](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph).

## Installation

```
npm install @github/dependency-submission-toolkit
```

## Usage

Some useful commands to navigate using the library:

- `npm run build` to compile TypeScript source
- `npm run test` to run the tests
- `npm run test:watch` to run the tests in watch-mode (tests re-run
when files change)
- `npm run format` to format files using prettier
- `npm run lint` to lint files using ESLint
- `npm run package` to compile the code into a single file using `ncc`
- `npm run all` will do the above and additional commands (e.g. lint the code, test)

## Writing Your Own Dependency Submission Action

You may use classes from `@github/dependency-submission-toolkit` to help
in building your own GitHub Action for submitting dependencies to the
Dependency Submission API. At a high level, the steps to use the classes
are:
You may use classes from `@github/dependency-submission-toolkit` to help in
building your own GitHub Action for submitting dependencies to the Dependency
Submission API. At a high level, the steps to use the classes are:

1. Create a `PackageCache` of all of the packages that could be included in your
manifest, as well define as the relationships between them.

2. Using the packages defined in `PackageCache`, create a `Manifest` or
a `BuildTarget`, which defines the dependencies of build environment or
2. Using the packages defined in `PackageCache`, create a `Manifest` or a
`BuildTarget`, which defines the dependencies of the build environment or
specific build artifact.

3. Create a `Snapshot` to include one or more `Manifests` or
`BuildTargets`. The snapshot is the base container for submitting
dependencies to the Dependency Submission API.

4. Follow the instructions for [Creating a JavaScript Action](https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action). These include:

- Defining an `action.yml` action metadata file
- Compiling the JavaScript into a single script using `ncc`
- Testing your action in a workflow

A full example action using this library is included in th `example/`
directory. This example uses the output from `npm list` to create an accurate
and complete graph of the dependencies used in this library. This action is
also included in a workflow in this repository and run for each commit to the
`main` branch.
3. Create a `Snapshot` to include one or more `Manifests` or `BuildTargets`. The
snapshot is the base container for submitting dependencies to the Dependency
Submission API.

4. Follow the instructions for
[Creating a JavaScript Action](https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action).
These include:

## Testing
- Defining an `action.yml` action metadata file
- Compiling the JavaScript into a single script using `ncc`
- Testing your action in a workflow

This library uses the `jest` testing framework with tests co-located with
source files. To run the tests, you can use `npm test` to run tests.
Otherwise you can use `jest` directly.
A full example action using this library is included in the `example/`
directory. This example uses the output from the `npm list` to create an
accurate and complete graph of the dependencies used in this library. This
action is also included in a workflow in this repository and runs for each
commit to the `main` branch.
3 changes: 0 additions & 3 deletions biome.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,5 @@
{
"$schema": "node_modules/@biomejs/biome/configuration_schema.json",
"files": {
"ignoreUnknown": true
},
"formatter": {
"enabled": true,
"indentStyle": "space"
Expand Down
2 changes: 1 addition & 1 deletion example/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,6 @@
"@tsconfig/strictest": "^2.0.2",
"@vercel/ncc": "^0.38.1",
"typescript": "^5.3.3",
"vitest": "^1.1.3"
"vitest": "^1.2.1"
}
}

0 comments on commit bf1a8f9

Please sign in to comment.