# Strudy

<img align="right" width="256" height="256" src="images/strudy-512.png" alt="Strudy, represented as a detective dog carrying a magnifying glass, ready to look for potential spec defects in crawl reports">

Strudy is an **analysis tool for Web spec crawl reports** created by [Reffy](https://github.com/w3c/reffy) that detects potential spec content anomalies such as missing references or invalid constructs.

Potential anomalies that Strudy may report on are:

1. specs that do not seem to reference any other spec normatively;
2. specs that define Web IDL terms but do not normatively reference the Web IDL spec;
3. specs that contain invalid Web IDL terms definitions;
4. specs that use obsolete Web IDL constructs (e.g. `[]` instead of `FrozenArray`);
5. specs that define Web IDL terms that are *also* defined in another spec;
6. specs that use Web IDL terms defined in another spec without referencing that spec normatively;
7. specs that use Web IDL terms for which the crawler could not find any definition in any of the specs it studied;
8. specs that link to another spec but do not include a reference to that other spec;
9. specs that link to another spec inconsistently in the body of the document and in the list of references (e.g. because the body of the document references the Editor's draft while the reference is to the latest published version).

Strudy generates a JSON report by default but may also generate more human-friendly markdown and HTML reports.

The analysis code was initially part of [Reffy](https://github.com/w3c/reffy).

**Important:** This is work in progress. Tool and analysis reports should get substantially revamped in a not-too-distant future and breaking changes in the code ought to be expected.

> “For sturdy specs, we recommend Strudy!”
> — Dom & François

## How to use

### Pre-requisites

To install Strudy, you need [Node.js](https://nodejs.org/en/) 18 or greater.

You will also need to install [Pandoc](http://pandoc.org/) if you want to generate HTML reports.

### Installation

Strudy is available as an NPM package. To install the package globally, run:

```bash
npm install -g strudy
```

This will install Strudy as a command-line interface tool.

To make sure that you run the latest version, use:

```bash
npm update -g strudy
```

### Launch Strudy

Strudy takes a relative path to a crawl report folder or to a JSON file that contains a crawl report as parameter. The crawl report must have been generated by [Reffy](https://github.com/w3c/reffy). Strudy analyzes the crawl report to detect potential anomalies. It also reports on additional spec facts, for instance to list specs that normatively reference a given spec or term.

Run `strudy -h` for a complete list of options and usage details.


## Contributing

Authors so far are [François Daoust](https://github.com/tidoust/) and [Dominique Hazaël-Massieux](https://github.com/dontcallmedom/).

Additional ideas, bugs and/or code contributions are most welcome. Create [issues on GitHub](https://github.com/w3c/strudy/issues) as needed!


## Licensing

The code is available under an [MIT license](LICENSE).