|
1 | 1 | # Dependency Submission Toolkit
|
2 | 2 |
|
3 |
| -`@github/dependency-submission-toolkit` is a TypeScript library for |
4 |
| -creating dependency snapshots and submitting them to the dependency |
5 |
| -submission API. Snapshots are a set of dependencies grouped by manifest with |
6 |
| -some related metadata. A manifest can be a physical file or a more abstract |
7 |
| -representation of a dependency grouping (such the processing of program |
8 |
| -outputs). After submission to the API, the included dependencies appear in the |
9 |
| -repository's [dependency |
10 |
| -graph](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph). |
| 3 | +`@github/dependency-submission-toolkit` is a TypeScript library for creating |
| 4 | +dependency snapshots and submitting them to the dependency submission API. |
| 5 | +Snapshots are a set of dependencies grouped by manifest with some related |
| 6 | +metadata. A manifest can be a physical file or a more abstract representation of |
| 7 | +a dependency grouping (such processing of program outputs). After submission to |
| 8 | +the API, the included dependencies appear in the repository's |
| 9 | +[dependency graph](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph). |
11 | 10 |
|
12 | 11 | ## Installation
|
13 | 12 |
|
14 | 13 | ```
|
15 | 14 | npm install @github/dependency-submission-toolkit
|
16 | 15 | ```
|
17 | 16 |
|
18 |
| -## Usage |
19 |
| - |
20 |
| -Some useful commands to navigate using the library: |
21 |
| - |
22 |
| -- `npm run build` to compile TypeScript source |
23 |
| -- `npm run test` to run the tests |
24 |
| - - `npm run test:watch` to run the tests in watch-mode (tests re-run |
25 |
| - when files change) |
26 |
| -- `npm run format` to format files using prettier |
27 |
| -- `npm run lint` to lint files using ESLint |
28 |
| -- `npm run package` to compile the code into a single file using `ncc` |
29 |
| -- `npm run all` will do the above and additional commands (e.g. lint the code, test) |
30 |
| - |
31 | 17 | ## Writing Your Own Dependency Submission Action
|
32 | 18 |
|
33 |
| -You may use classes from `@github/dependency-submission-toolkit` to help |
34 |
| -in building your own GitHub Action for submitting dependencies to the |
35 |
| -Dependency Submission API. At a high level, the steps to use the classes |
36 |
| -are: |
| 19 | +You may use classes from `@github/dependency-submission-toolkit` to help in |
| 20 | +building your own GitHub Action for submitting dependencies to the Dependency |
| 21 | +Submission API. At a high level, the steps to use the classes are: |
37 | 22 |
|
38 | 23 | 1. Create a `PackageCache` of all of the packages that could be included in your
|
39 | 24 | manifest, as well define as the relationships between them.
|
40 | 25 |
|
41 |
| -2. Using the packages defined in `PackageCache`, create a `Manifest` or |
42 |
| - a `BuildTarget`, which defines the dependencies of build environment or |
| 26 | +2. Using the packages defined in `PackageCache`, create a `Manifest` or a |
| 27 | + `BuildTarget`, which defines the dependencies of the build environment or |
43 | 28 | specific build artifact.
|
44 | 29 |
|
45 |
| -3. Create a `Snapshot` to include one or more `Manifests` or |
46 |
| - `BuildTargets`. The snapshot is the base container for submitting |
47 |
| - dependencies to the Dependency Submission API. |
48 |
| - |
49 |
| -4. Follow the instructions for [Creating a JavaScript Action](https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action). These include: |
50 |
| - |
51 |
| - - Defining an `action.yml` action metadata file |
52 |
| - - Compiling the JavaScript into a single script using `ncc` |
53 |
| - - Testing your action in a workflow |
54 |
| - |
55 |
| -A full example action using this library is included in th `example/` |
56 |
| -directory. This example uses the output from `npm list` to create an accurate |
57 |
| -and complete graph of the dependencies used in this library. This action is |
58 |
| -also included in a workflow in this repository and run for each commit to the |
59 |
| -`main` branch. |
| 30 | +3. Create a `Snapshot` to include one or more `Manifests` or `BuildTargets`. The |
| 31 | + snapshot is the base container for submitting dependencies to the Dependency |
| 32 | + Submission API. |
60 | 33 |
|
| 34 | +4. Follow the instructions for |
| 35 | + [Creating a JavaScript Action](https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action). |
| 36 | + These include: |
61 | 37 |
|
62 |
| -## Testing |
| 38 | + - Defining an `action.yml` action metadata file |
| 39 | + - Compiling the JavaScript into a single script using `ncc` |
| 40 | + - Testing your action in a workflow |
63 | 41 |
|
64 |
| -This library uses the `jest` testing framework with tests co-located with |
65 |
| -source files. To run the tests, you can use `npm test` to run tests. |
66 |
| -Otherwise you can use `jest` directly. |
| 42 | +A full example action using this library is included in the `example/` |
| 43 | +directory. This example uses the output from the `npm list` to create an |
| 44 | +accurate and complete graph of the dependencies used in this library. This |
| 45 | +action is also included in a workflow in this repository and runs for each |
| 46 | +commit to the `main` branch. |
0 commit comments