Strudy

Strudy is an analysis tool for Web spec crawl reports created by Reffy that detects potential spec content anomalies such as missing references or invalid constructs.

Potential anomalies that Strudy may report on are:

specs that do not seem to reference any other spec normatively;
specs that define Web IDL terms but do not normatively reference the Web IDL spec;
specs that contain invalid Web IDL terms definitions;
specs that use obsolete Web IDL constructs (e.g. [] instead of FrozenArray);
specs that define Web IDL terms that are also defined in another spec;
specs that use Web IDL terms defined in another spec without referencing that spec normatively;
specs that use Web IDL terms for which the crawler could not find any definition in any of the specs it studied;
specs that link to another spec but do not include a reference to that other spec;
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.

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 18 or greater.

You will also need to install Pandoc if you want to generate HTML reports.

Installation

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

npm install -g strudy

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

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

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. 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 and Dominique Hazaël-Massieux.

Additional ideas, bugs and/or code contributions are most welcome. Create issues on GitHub as needed!

Licensing

The code is available under an MIT license.