diff options
Diffstat (limited to 'scripts')
| -rwxr-xr-x | scripts/lv2_build_index.py | 207 | ||||
| -rwxr-xr-x | scripts/lv2_check_specification.py | 248 | ||||
| -rwxr-xr-x | scripts/lv2_check_syntax.py | 85 | ||||
| -rw-r--r-- | scripts/meson.build | 8 |
4 files changed, 548 insertions, 0 deletions
diff --git a/scripts/lv2_build_index.py b/scripts/lv2_build_index.py new file mode 100755 index 0000000..6e4ebea --- /dev/null +++ b/scripts/lv2_build_index.py @@ -0,0 +1,207 @@ +#!/usr/bin/env python3 + +# Copyright 2022 David Robillard <d@drobilla.net> +# SPDX-License-Identifier: ISC + +""" +Write an HTML index for a set of LV2 specifications. +""" + +import json +import os +import sys +import argparse +import subprocess + +import rdflib + + +doap = rdflib.Namespace("http://usefulinc.com/ns/doap#") +lv2 = rdflib.Namespace("http://lv2plug.in/ns/lv2core#") +owl = rdflib.Namespace("http://www.w3.org/2002/07/owl#") +rdf = rdflib.Namespace("http://www.w3.org/1999/02/22-rdf-syntax-ns#") + + +def _subst_file(template_path, output_file, substitutions): + "Replace keys with values in a template file and write the result." + + with open(template_path, "r", encoding="utf-8") as template: + for line in template: + for key, value in substitutions.items(): + line = line.replace(key, value) + + output_file.write(line) + + +def _load_ttl(data_paths, exclude=None): + "Load an RDF model from a Turtle file." + + model = rdflib.ConjunctiveGraph() + for path in data_paths: + if exclude is None or path not in exclude: + try: + model.parse(path, format="n3") + except SyntaxError as error: + sys.stderr.write(f"error: Failed to parse {path}\n") + raise error + + return model + + +def _warn(message): + "Load a warning message." + + assert not message.startswith("warning: ") + assert not message.endswith("\n") + sys.stderr.write(message) + sys.stderr.write("\n") + + +def _spec_target(spec, root, online=False): + "Return the relative link target for a specification." + + target = spec.replace(root, "") if spec.startswith(root) else spec + + return target if online else target + ".html" + + +def _spec_link_columns(spec, root, name, online): + "Return the first two link columns in a spec row as an HTML string." + + # Find relative link target and stem + target = _spec_target(spec, root, online) + stem = os.path.splitext(os.path.basename(target))[0] + + # Prefix with a comment to act as a sort key for the row + col = f"<!-- {stem} -->" + + # Specification + col += f'<td><a rel="rdfs:seeAlso" href="{target}">{name}</a></td>' + + # API + col += '<td><a rel="rdfs:seeAlso"' + col += f' href="../c/html/group__{stem}.html">{name}' + col += "</a></td>" + + return col + + +def _spec_description_column(model, spec): + "Return the description column in a spec row as an HTML string." + + shortdesc = model.value(spec, doap.shortdesc, None, any=False) + + return "<td>" + str(shortdesc) + "</td>" if shortdesc else "<td></td>" + + +def index_row(model, spec, root_uri, online): + "Return the row for a spec as an HTML string." + + # Get version + minor = 0 + micro = 0 + try: + minor = int(model.value(spec, lv2.minorVersion, None, any=False)) + micro = int(model.value(spec, lv2.microVersion, None, any=False)) + except rdflib.exceptions.UniquenessError: + _warn(f"{spec} has no unique valid version") + return "" + + row = "<tr>" + + # Specification and API + row += _spec_link_columns( + spec, + root_uri, + model.value(spec, doap.name, None).replace("LV2 ", ""), + online, + ) + + # Description + row += _spec_description_column(model, spec) + + # Version + row += f"<td>{minor}.{micro}</td>" + + # Status + deprecated = model.value(spec, owl.deprecated, None) + deprecated = deprecated and str(deprecated) not in ["0", "false"] + if minor == 0: + row += '<td><span class="error">Experimental</span></td>' + elif deprecated: + row += '<td><span class="warning">Deprecated</span></td>' + elif micro % 2 == 0: + row += '<td><span class="success">Stable</span></td>' + else: + row += '<td><span class="warning">Development</span></td>' + + row += "</tr>" + + return row + + +def build_index( + lv2_source_root, + lv2_version, + input_paths, + root_uri, + online, +): + "Build the LV2 specification index and write it to stdout." + + model = _load_ttl(input_paths) + + rows = [] + for spec in model.triples([None, rdf.type, lv2.Specification]): + rows += [index_row(model, spec[0], root_uri, online)] + + _subst_file( + os.path.join(lv2_source_root, "doc", "index.html.in"), + sys.stdout, + { + "@ROWS@": "\n".join(sorted(rows)), + "@LV2_VERSION@": lv2_version, + }, + ) + + +if __name__ == "__main__": + ap = argparse.ArgumentParser( + usage="%(prog)s [OPTION]... INPUT_PATH...", + description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + + ap.add_argument("--lv2-version", help="LV2 release version") + ap.add_argument("--lv2-source-root", help="path to LV2 source root") + ap.add_argument( + "--root-uri", + default="http://lv2plug.in/ns/", + help="root URI for specifications", + ) + ap.add_argument( + "--online", + action="store_true", + default=False, + help="build online documentation", + ) + ap.add_argument("input_paths", nargs="+", help="path to Turtle input file") + + args = ap.parse_args(sys.argv[1:]) + + if args.lv2_version is None or args.lv2_source_root is None: + introspect_command = ["meson", "introspect", "-a"] + project_info = json.loads( + subprocess.check_output(introspect_command).decode("utf-8") + ) + + if args.lv2_version is None: + args.lv2_version = project_info["projectinfo"]["version"] + + if args.lv2_source_root is None: + meson_build_path = project_info["buildsystem_files"][0] + args.lv2_source_root = os.path.relpath( + os.path.dirname(meson_build_path) + ) + + build_index(**vars(args)) diff --git a/scripts/lv2_check_specification.py b/scripts/lv2_check_specification.py new file mode 100755 index 0000000..41611ef --- /dev/null +++ b/scripts/lv2_check_specification.py @@ -0,0 +1,248 @@ +#!/usr/bin/env python3 + +# Copyright 2020-2022 David Robillard <d@drobilla.net> +# SPDX-License-Identifier: ISC + +""" +Check an LV2 specification for issues. +""" + +import argparse +import os +import sys + +import rdflib + +foaf = rdflib.Namespace("http://xmlns.com/foaf/0.1/") +lv2 = rdflib.Namespace("http://lv2plug.in/ns/lv2core#") +owl = rdflib.Namespace("http://www.w3.org/2002/07/owl#") +rdf = rdflib.Namespace("http://www.w3.org/1999/02/22-rdf-syntax-ns#") +rdfs = rdflib.Namespace("http://www.w3.org/2000/01/rdf-schema#") + + +class Checker: + "A callable that checks conditions and records pass/fail counts." + + def __init__(self, verbose=False): + self.num_checks = 0 + self.num_errors = 0 + self.verbose = verbose + + def __call__(self, condition, name): + if not condition: + sys.stderr.write(f"error: Unmet condition: {name}\n") + self.num_errors += 1 + elif self.verbose: + sys.stderr.write(f"note: {name}\n") + + self.num_checks += 1 + return condition + + def print_summary(self): + "Print a summary (if verbose) when all checks are finished." + + if self.verbose: + if self.num_errors: + sys.stderr.write(f"note: Failed {self.num_errors}/") + else: + sys.stderr.write("note: Passed all ") + + sys.stderr.write(f"{self.num_checks} checks\n") + + +def _check(condition, name): + "Check that condition is true, returning 1 on failure." + + if not condition: + sys.stderr.write(f"error: Unmet condition: {name}\n") + return 1 + + return 0 + + +def _has_statement(model, pattern): + "Return true if model contains a triple matching pattern." + + for _ in model.triples(pattern): + return True + + return False + + +def _has_property(model, subject, predicate): + "Return true if subject has any value for predicate in model." + + return model.value(subject, predicate, None) is not None + + +def _check_version(checker, model, spec, is_stable): + "Check that the version of a specification is present and valid." + + minor = model.value(spec, lv2.minorVersion, None, any=False) + checker(minor is not None, f"{spec} has a lv2:minorVersion") + + micro = model.value(spec, lv2.microVersion, None, any=False) + checker(micro is not None, f"{spec} has a lv2:microVersion") + + if is_stable: + checker(int(minor) > 0, f"{spec} has a non-zero minor version") + checker(int(micro) % 2 == 0, f"{spec} has an even micro version") + + +def _check_specification(checker, spec_dir, is_stable=False): + "Check all specification data for errors and omissions." + + # Load manifest + manifest_path = os.path.join(spec_dir, "manifest.ttl") + model = rdflib.Graph() + model.parse(manifest_path, format="n3") + + # Get the specification URI from the manifest + spec_uri = model.value(None, rdf.type, lv2.Specification, any=False) + if not checker( + spec_uri is not None, + manifest_path + " declares an lv2:Specification", + ): + return 1 + + # Check that the manifest declares a valid version + _check_version(checker, model, spec_uri, is_stable) + + # Get the link to the main document from the manifest + document = model.value(spec_uri, rdfs.seeAlso, None, any=False) + if not checker( + document is not None, + manifest_path + " has one rdfs:seeAlso link to the definition", + ): + return 1 + + # Load main document into the model + model.parse(document, format="n3") + + # Check that the main data files aren't bloated with extended documentation + checker( + not _has_statement(model, [None, lv2.documentation, None]), + f"{document} has no lv2:documentation", + ) + + # Load all other directly linked data files (for any other subjects) + for link in sorted(model.triples([None, rdfs.seeAlso, None])): + if link[2] != document and link[2].endswith(".ttl"): + model.parse(link[2], format="n3") + + # Check that all properties have a more specific type + for typing in sorted(model.triples([None, rdf.type, rdf.Property])): + subject = typing[0] + + checker(isinstance(subject, rdflib.term.URIRef), f"{subject} is a URI") + + if str(subject) == "http://lv2plug.in/ns/ext/patch#value": + continue # patch:value is just a "promiscuous" rdf:Property + + types = list(model.objects(subject, rdf.type)) + + checker( + (owl.DatatypeProperty in types) + or (owl.ObjectProperty in types) + or (owl.AnnotationProperty in types), + f"{subject} is a Datatype, Object, or Annotation property", + ) + + # Get all subjects that have an explicit rdf:type + typed_subjects = set() + for subject in model.subjects(rdf.type, None): + typed_subjects.add(subject) + + # Check that all named and typed resources have labels and comments + for subject in typed_subjects: + if isinstance( + subject, rdflib.term.BNode + ) or foaf.Person in model.objects(subject, rdf.type): + continue + + if checker( + _has_property(model, subject, rdfs.label), + f"{subject} has a rdfs:label", + ): + label = str(model.value(subject, rdfs.label, None)) + + checker( + not label.endswith("."), + f"{subject} label has no trailing '.'", + ) + checker( + label.find("\n") == -1, + f"{subject} label is a single line", + ) + checker( + label == label.strip(), + f"{subject} label has stripped whitespace", + ) + + if checker( + _has_property(model, subject, rdfs.comment), + f"{subject} has a rdfs:comment", + ): + comment = str(model.value(subject, rdfs.comment, None)) + + checker( + comment.endswith("."), + f"{subject} comment has a trailing '.'", + ) + checker( + comment.find("\n") == -1 and comment.find("\r"), + f"{subject} comment is a single line", + ) + checker( + comment == comment.strip(), + f"{subject} comment has stripped whitespace", + ) + + # Check that lv2:documentation, if present, is proper Markdown + documentation = model.value(subject, lv2.documentation, None) + if documentation is not None: + checker( + documentation.datatype == lv2.Markdown, + f"{subject} documentation is explicitly Markdown", + ) + checker( + str(documentation).startswith("\n\n"), + f"{subject} documentation starts with blank line", + ) + checker( + str(documentation).endswith("\n\n"), + f"{subject} documentation ends with blank line", + ) + + return checker.num_errors + + +if __name__ == "__main__": + ap = argparse.ArgumentParser( + usage="%(prog)s [OPTION]... BUNDLE", + description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + + ap.add_argument( + "--stable", + action="store_true", + help="enable checks for stable release versions", + ) + + ap.add_argument( + "-v", "--verbose", action="store_true", help="print successful checks" + ) + + ap.add_argument( + "BUNDLE", help="path to specification bundle or manifest.ttl" + ) + + args = ap.parse_args(sys.argv[1:]) + + if os.path.basename(args.BUNDLE): + args.BUNDLE = os.path.dirname(args.BUNDLE) + + sys.exit( + _check_specification(Checker(args.verbose), args.BUNDLE, args.stable) + ) diff --git a/scripts/lv2_check_syntax.py b/scripts/lv2_check_syntax.py new file mode 100755 index 0000000..391e4e1 --- /dev/null +++ b/scripts/lv2_check_syntax.py @@ -0,0 +1,85 @@ +#!/usr/bin/env python3 + +# Copyright 2022 David Robillard <d@drobilla.net> +# SPDX-License-Identifier: ISC + +""" +Check that a Turtle file has valid syntax and strict formatting. + +This is a strict tool that enforces machine formatting with serdi. +""" + +import argparse +import difflib +import filecmp +import sys +import tempfile +import os +import subprocess + + +def _show_diff(from_lines, to_lines, from_path, to_path): + "Show a diff between two files, returning non-zero if they differ." + + differences = False + for line in difflib.unified_diff( + from_lines, + to_lines, + fromfile=from_path, + tofile=to_path, + ): + sys.stderr.write(line) + differences = True + + return int(differences) + + +def _check_file_equals(patha, pathb): + "Check that two files are equal, returning non-zero if they differ." + + for path in (patha, pathb): + if not os.access(path, os.F_OK): + sys.stderr.write(f"error: missing file {path}") + return 1 + + if filecmp.cmp(patha, pathb, shallow=False): + return 0 + + with open(patha, "r", encoding="utf-8") as in_a: + with open(pathb, "r", encoding="utf-8") as in_b: + return _show_diff(in_a.readlines(), in_b.readlines(), patha, pathb) + + +def run(serdi, filenames): + "Check that every file in filenames has valid formatted syntax." + + status = 0 + + for filename in filenames: + rel_path = os.path.relpath(filename) + with tempfile.NamedTemporaryFile(mode="w", delete=False) as out: + out_name = out.name + command = [serdi, "-o", "turtle", rel_path] + subprocess.check_call(command, stdout=out) + + if _check_file_equals(rel_path, out_name): + status = 1 + + os.remove(out_name) + + return status + + +if __name__ == "__main__": + ap = argparse.ArgumentParser( + usage="%(prog)s [OPTION]... TURTLE_FILE...", + description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + + ap.add_argument("--serdi", default="serdi", help="path to serdi") + ap.add_argument("TURTLE_FILE", nargs="+", help="input file to check") + + args = ap.parse_args(sys.argv[1:]) + + sys.exit(run(args.serdi, args.TURTLE_FILE)) diff --git a/scripts/meson.build b/scripts/meson.build new file mode 100644 index 0000000..1a77ab7 --- /dev/null +++ b/scripts/meson.build @@ -0,0 +1,8 @@ +# Copyright 2021-2022 David Robillard <d@drobilla.net> +# SPDX-License-Identifier: 0BSD OR ISC + +lv2_scripts = files( + 'lv2_build_index.py', + 'lv2_check_specification.py', + 'lv2_check_syntax.py', +) |