<!-- SPDX-License-Identifier: Apache-2.0
     https://www.apache.org/licenses/LICENSE-2.0 -->

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [generate-cve-json](#generate-cve-json)
  - [Run](#run)
  - [Test](#test)
  - [Lint / type-check](#lint--type-check)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

<!-- Licensed to the Apache Software Foundation (ASF) under one
     or more contributor license agreements.  See the NOTICE file
     distributed with this work for additional information
     regarding copyright ownership.  The ASF licenses this file
     to you under the Apache License, Version 2.0 (the
     "License"); you may not use this file except in compliance
     with the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing,
     software distributed under the License is distributed on an
     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     KIND, either express or implied.  See the License for the
     specific language governing permissions and limitations
     under the License. -->

# generate-cve-json

Small Python project that generates a CVE 5.x JSON record from an
`<tracker>` tracking issue, ready to paste into the Vulnogram
`#source` tab of the [ASF CVE tool](https://cveprocess.apache.org/).

The behavioural contract and the security-process context live in
[`SKILL.md`](SKILL.md). This README covers the local-setup and test
workflow for the project itself.

## Run

From the framework's root (this repository when running standalone;
the `.apache-magpie/` snapshot path inside an adopting tracker repo):

```bash
uv run --project tools/cve-tool-vulnogram/generate-cve-json generate-cve-json <ISSUE-NUMBER> [options]
```

Skill files reference the same invocation via the `<framework>`
placeholder so the path resolves in either context:

```bash
uv run --project <framework>/tools/cve-tool-vulnogram/generate-cve-json generate-cve-json <ISSUE-NUMBER>
```

`<framework>` substitutes to `.apache-magpie/apache-magpie` in
adopting projects and to `.` (the repository root) in framework
standalone — see the placeholder convention in
[`AGENTS.md`](../../../AGENTS.md#placeholder-convention-used-in-skill-files).

Equivalent forms:

```bash
# as a module
uv run --project <framework>/tools/cve-tool-vulnogram/generate-cve-json python -m generate_cve_json <ISSUE-NUMBER>

# from inside the project dir
cd <framework>/tools/cve-tool-vulnogram/generate-cve-json
uv run generate-cve-json <ISSUE-NUMBER>
```

Flags are documented in `generate-cve-json --help` and in [`SKILL.md`](SKILL.md).

## Test

```bash
cd tools/cve-tool-vulnogram/generate-cve-json
uv run --group dev pytest
```

## Lint / type-check

```bash
cd tools/cve-tool-vulnogram/generate-cve-json
uv run --group dev ruff check src tests
uv run --group dev ruff format --check src tests
uv run --group dev mypy
```

The `prek` hooks configured in `.pre-commit-config.yaml` at the
repository root run `ruff check`, `ruff format --check`, and `mypy`
on the project files automatically on every commit that touches them.
