Tools#

Release:

6.1.1

Date:

Oct 15, 2026

MANDATORY_README_SECTIONS

Built-in immutable sequence.

QUERY_CLASSES

parse_readme_sections(text)

Parse the ## <name> sections of a queries README into an ordered mapping section name -> body lines.

stored_reverse_forward(stem, stems)

Return the forward label of a stored reversed matrix stem, if any.

unpack_single_dir(path, dest)

Unpack path (a .tar.gz) into dest and return its single top-level directory.

validate_archive(path, *[, partial])

Validate one graph archive (a .tar.gz or an unpacked directory).

Archive structure checker#

flpq-check-archive (installed with the package) validates that a graph archive has the fixed self-contained structure documented in File structure:

flpq-check-archive ARCHIVE.tar.gz
flpq-check-archive UNPACKED_DIR
flpq-check-archive PARTIAL.tar.gz --partial
flpq-check-archive --audit --prefix 6.0.0/graph/ \
    --access-key-id KEY_ID --secret-access-key SECRET

A partial archive provides new queries for an existing graph: it contains only queries/ — the new query directories plus a README.md fragment with their sections. With --partial the tool checks that skeleton, that every representation file parses (the label and dimension checks are skipped — there is no graph to check against), and that the fragment describes exactly the query directories it contains.

The checks:

  • Skeleton. A single top-level directory named after the archive, containing exactly README.md, graph/ (non-empty, only .mtx files), and queries/ with its README.md and the three class directories. Each class directory holds query directories only (flat query files are rejected); each query directory contains at least one representation file with a class extension (.cnf/.rsm for CFPQ, .re/.rsm for RPQ, .mcfg for MCFPQ) and exactly one results.mtx.

  • Graph. Every MTX file parses as a Boolean pattern matrix, every edge endpoint fits the declared dimensions, and all label matrices declare the same dimensions.

  • Labels. No forbidden label components (bar, rev); and reversed edges are not stored — neither <label>_r.mtx nor <base>_r_<n>.mtx may exist when the forward matrix is present (they are auto-generated by add_reverse_edges).

  • Results. Every results.mtx parses as a Boolean pattern matrix with the graph’s dimensions and in-range entries.

  • Queries. Every representation file parses with its class reader (an .rsm via rsa_from_text), uses at least one terminal, and uses only labels of its own graph (stored or reversed). An .rsm in rpq/ must be regular — no box transition labelled by a nonterminal.

  • Description. README.md answers all mandatory questions of the contribution templates; queries/README.md describes exactly the query directories that exist, each with a non-empty section.

The tool collects every violation and exits non-zero if any is found, so it can gate a commit. With --audit it downloads and validates every .tar.gz object under the bucket prefix (credentials from the command line, like Upload to Yandex S3; boto3 must be installed — it is a development dependency of the repo, not of the package). Upload to Yandex S3 runs the same check before uploading any .tar.gz and refuses an invalid archive.