tools-extension-conformance

Conformance checker for the workspace's browser extensions (sprint 4.45): the Gate 1.5.6 input guard, the parse-cleanliness probe, and `check` — loads docs/reference/extension-standard.tsv through closed enums, reads the manifest and extension.toml, and answers every applicable row; kinds without an evaluator answer unsupported, which fails the gate.

What it is for

Conformance checker for the workspace's browser extensions (sprint 4.45): the standard is a table, this reads it. Sprint doc: docs/userstories/sprint-4.45-the-extension-standard-is-a-table-and-the-checker-reads-it.md; seed: the sprint 4.44 audit (B-066..B-071). Dependencies: tree-sitter and tree-sitter-javascript (the syntax frontend, approved 2026-09-04), clap, serde, toml, tools-doc-truth (the cadence reader); clap's usage errors exit 2.

The two extensions under extensions/ are instances of the standard in docs/reference/extension-standard.tsv (two classes, site-bound and general-automation; each declares its class in extension.toml). Each row is a rule instance: a predicate kind with parameters, evaluated over the manifest, the descriptor, the README and the authored sources. A construct outside a kind's analysis subset is reported as unsupported, never passed, and unsupported fails the gate like failed (decision 2). This README is generated from this block; the per-kind readings, with what each passes unseen, are stated in the module headers named below.

# Commands

• parse-probe <dir> --json — admit a directory, parse every authored .js with

tree-sitter-javascript, report per-file ERROR/MISSING counts and the vendored and symlinked paths not read. Exit 0 clean · 1 any unclean file · 2 refused by the guard or no repository root · 3 a read or parse failed after admission.

• check <dir> --json --today YYYY-MM-DD — guard, read the manifest, the

descriptor and the README (the README under the descriptor cap, after admission), load the table, evaluate every row that applies to the class, print one line per rule (rule status location detail). Exit 0 when no row is failed or unsupported (warn, finding, exempt do not fail) · 1 otherwise · 2 refused · 3 read failed. --json emits schema extension-conformance.check/1, which operations-test-results-ingest from-conformance - records as one ledger run.

• check --staged --json --today … — the extensions the staged paths touch,

each evaluated whole against the index (decision 5; module staged): the snapshot being committed, not the working tree. --json emits extension-conformance.check-staged/1 with one check/1 report per evaluated extension; a selected directory with no file left under it in the index is listed under removed and evaluated by nothing. The pre-commit stage in .githooks/pre-commit runs it when a path under extensions/ is staged (AC 6). This is the crate's one subprocess: git by name with fixed argument vectors, output capped.

• template <site-bound|general-automation> <name> — scaffold extensions/<name>

from the class's embedded template (module template); an existing directory is refused. The committed extensions/TEMPLATE-* directories are this rendering, and a test holds them equal to the embedded sources (AC 7: a scaffold passes check with nothing failing or unsupported).

# The guard (Gate 1.5.6)

guard: fs::canonicalize + repo-root prefix check on the directory; per-file byte cap and running file count checked from metadata during the walk, refusing at the first offender; symlinks neither followed nor admitted, named in the report. Exactly one file is read before admission — the extension's extension.toml — after its own canonicalize + prefix check and a 64 KiB cap from metadata. No .js body is read by the guard; the tests make fixture files unreadable so a body read would surface as an Io error. probe and check read each admitted file under the same byte cap (a file that grew past it between guard and read is refused at read time). Hard links are not detected. No network, no database; no subprocess but git in --staged mode (above).

Vendored files — node_modules/, wasm/, *.min.js by default, plus vendored files = ... in extension.toml — are excluded from the walk and named as skipped. Entry grammar: name/ (one path component) matches a directory of that name at any depth; *.suffix matches files by name suffix at any depth; anything else is one file by exact relative path. Refused at load: a directory entry with more than one component, a wildcard anywhere but first, with nothing after it, or with a trailing /, a .. or . component, a repeated separator, an absolute path, an empty entry. layout development uses the same grammar.

# The rows and their readers

• rules — loads the table into Rule rows through closed enums for class,

predicate kind, decidable and severity; a row outside any enum, a missing column, a duplicate id or an empty table is a load error. A table defect at evaluation (a query that does not compile, an unknown scope token, a missing parameter) is failed at the table path with severity and exemptions not applied.

• descriptor — extension.toml: extension class (required, closed), `adr

host_permissions (four digits; E2 matches <id>-*.md under docs/architecture/adr), layout development (E8 excludes the files it names, a directory entry at any depth), [exempt] rows (rule, non-empty reason, ISO since`; anything else refuses the descriptor; an exemption naming a rule that produced no verdict is a failed verdict).

• manifest — MV3 only: permissions, host permissions, content scripts, web

accessible resources, the extension-pages CSP, the background service worker; page_loadable (a resource a page can fetch, or a "world": "MAIN" script) and MatchPattern with Chrome's grammar (ws compares as http, wss as https).

• evaluate — manifest_subset (E1, E11: every string literal spelling an

http(s)/ws(s) URL falls inside a host permission; a template URL with a substitution is unsupported; a URL built by concatenation is not visible), manifest_key (E2, E12), owner (J2), single_file_query (E9: the table's tree-sitter query, compiled once, scoped by manifest section, a hit when the named capture mentions a top-level declaration), cross_file_producer (E4, reader in messages), call_site_guard (E5, reader in guards), dominance_gate (E3, E7, E8, E10, readers in dominance, selected by site=), doc_code_agreement (E6: the README's cadence claims against the background worker, decided by tools_doc_truth::cadence, registered there as D15), pair_emission (J1: the flows of every file, reader in flows, paired by side-effect class and cut into tools_packet_compile::flow_pair::FlowPairShard packets carried on the verdict — digests, enums and counts, validated before they are carried; the commit they pin is read from .git by head_commit, no subprocess). Every kind has an evaluator. A failed verdict's detail also lists the rule's sites outside the reading.

• query — a table-held tree-sitter query over one file; top_level_names,

top_level_unread.

# Where it sits

Tier tools. Invoked by the operator (cargo run -q -p tools-extension-conformance -- check extensions/<x>) and, at pre-commit, by the stage in .githooks/pre-commit for staged extensions/ paths. The tree-sitter loading is marked as a candidate for a foundation- crate the day a second consumer wants it.

Capabilities

crate root

Conformance checker for the workspace's browser extensions (sprint 4.45): the

Admitted

Conformance checker for the workspace's browser extensions (sprint 4.45): the

GuardError

Conformance checker for the workspace's browser extensions (sprint 4.45): the

Limits

Conformance checker for the workspace's browser extensions (sprint 4.45): the

ParseReport

Conformance checker for the workspace's browser extensions (sprint 4.45): the

Vendored

Conformance checker for the workspace's browser extensions (sprint 4.45): the

descriptor (other)

extension.toml — the descriptor beside manifest.json.

Descriptor

extension.toml — the descriptor beside manifest.json.

DescriptorError

extension.toml — the descriptor beside manifest.json.

Exempt

extension.toml — the descriptor beside manifest.json.

Against

Sites and the gates that dominate them, as the dominance_gate kind reads them

Compared

Sites and the gates that dominate them, as the dominance_gate kind reads them

EffectGate

Sites and the gates that dominate them, as the dominance_gate kind reads them

Gate

Sites and the gates that dominate them, as the dominance_gate kind reads them

GateSource

Sites and the gates that dominate them, as the dominance_gate kind reads them

GatedSite

Sites and the gates that dominate them, as the dominance_gate kind reads them

GatedSites

Sites and the gates that dominate them, as the dominance_gate kind reads them

ListenerFacts

Sites and the gates that dominate them, as the dominance_gate kind reads them

ListenerSite

Sites and the gates that dominate them, as the dominance_gate kind reads them

Operand

Sites and the gates that dominate them, as the dominance_gate kind reads them

SideEffect

Sites and the gates that dominate them, as the dominance_gate kind reads them

SinkSite

Sites and the gates that dominate them, as the dominance_gate kind reads them

Sinks

Sites and the gates that dominate them, as the dominance_gate kind reads them

evaluate (other)

Evaluate the rule table against one admitted extension.

Context

Evaluate the rule table against one admitted extension.

Status

Evaluate the rule table against one admitted extension.

UrlLiterals

Evaluate the rule table against one admitted extension.

Verdict

Evaluate the rule table against one admitted extension.

Flow

Flows that end in a real-world action, as the pair_emission kind reads them (J1).

CallSite

In-flight guards around a call, as the call_site_guard kind reads them (E5).

GuardFacts

In-flight guards around a call, as the call_site_guard kind reads them (E5).

manifest (other)

manifest.json as the checker reads it, and Chrome match patterns.

Background

manifest.json as the checker reads it, and Chrome match patterns.

ContentScript

manifest.json as the checker reads it, and Chrome match patterns.

ContentSecurityPolicy

manifest.json as the checker reads it, and Chrome match patterns.

Host

manifest.json as the checker reads it, and Chrome match patterns.

Manifest

manifest.json as the checker reads it, and Chrome match patterns.

ManifestError

manifest.json as the checker reads it, and Chrome match patterns.

MatchPattern

manifest.json as the checker reads it, and Chrome match patterns.

PageLoadable

manifest.json as the checker reads it, and Chrome match patterns.

PatternError

manifest.json as the checker reads it, and Chrome match patterns.

Port

manifest.json as the checker reads it, and Chrome match patterns.

Scheme

manifest.json as the checker reads it, and Chrome match patterns.

WebAccessible

manifest.json as the checker reads it, and Chrome match patterns.

World

manifest.json as the checker reads it, and Chrome match patterns.

Listener

window.postMessage producers and message listeners, as the cross-file rule reads

ListenerConstant

window.postMessage producers and message listeners, as the cross-file rule reads

MessageFacts

window.postMessage producers and message listeners, as the cross-file rule reads

Producer

window.postMessage producers and message listeners, as the cross-file rule reads

query (other)

Tree-sitter queries held in the table, run over one file.

Capture

Tree-sitter queries held in the table, run over one file.

Match

Tree-sitter queries held in the table, run over one file.

QueryError

Tree-sitter queries held in the table, run over one file.

rules (other)

The rule table, loaded from docs/reference/extension-standard.tsv.

Applies

The rule table, loaded from docs/reference/extension-standard.tsv.

Class

The rule table, loaded from docs/reference/extension-standard.tsv.

Decidable

The rule table, loaded from docs/reference/extension-standard.tsv.

PredicateKind

The rule table, loaded from docs/reference/extension-standard.tsv.

Rule

The rule table, loaded from docs/reference/extension-standard.tsv.

Severity

The rule table, loaded from docs/reference/extension-standard.tsv.

TableError

The rule table, loaded from docs/reference/extension-standard.tsv.

staged (other)

check --staged — the extensions a commit touches, evaluated whole against the

template (other)

template <class> <name> — the standard's executable form (sprint 4.45 task 7).

TemplateError

template <class> <name> — the standard's executable form (sprint 4.45 task 7).

How to use it

No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.

Module structure

tools_extension_conformance

• descriptor
• dominance
• evaluate
• flows
• guards
• manifest
• messages
• query
• rules
• staged
• template

flowchart TD
  n_tools_extension_conformance["tools_extension_conformance"]
  n_tools_extension_conformance --> n_descriptor["descriptor"]
  n_tools_extension_conformance --> n_dominance["dominance"]
  n_tools_extension_conformance --> n_evaluate["evaluate"]
  n_tools_extension_conformance --> n_flows["flows"]
  n_tools_extension_conformance --> n_guards["guards"]
  n_tools_extension_conformance --> n_manifest["manifest"]
  n_tools_extension_conformance --> n_messages["messages"]
  n_tools_extension_conformance --> n_query["query"]
  n_tools_extension_conformance --> n_rules["rules"]
  n_tools_extension_conformance --> n_staged["staged"]
  n_tools_extension_conformance --> n_template["template"]

Public surface

`crate root`

`descriptor`

`dominance`

`evaluate`

`flows`

`guards`

`manifest`

`messages`

`query`

`rules`

`staged`

`template`

No pub use re-exports: every item above is declared in this crate.

Boundary

Depends on no other workspace tier.

Shares tier tools with 84 other crates: tools-advisory-reach, tools-archive-guard, tools-artifact-scaffold, tools-ask-ai-core, tools-ask-ais, tools-ask-gemini, tools-book, tools-book-report, … (84 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Dependencies

Runtime, in this workspace.

Runtime, from outside the workspace.

Development, in this workspace.

Development, from outside the workspace.

Build. None.

Depended on by. Nothing in this workspace.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  SELF["tools-extension-conformance"]
  SELF -->|development| n_tools_cli_conformance["tools-cli-conformance"]
  SELF -->|runtime| n_tools_doc_truth["tools-doc-truth"]
  SELF -->|runtime| n_tools_packet_compile["tools-packet-compile"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Error model

Operational characteristics

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

Related capabilities

No workspace crate depends on this one.

Verification

Evidence by module. How often each public module is named by something executable.

What the tests establish, by name:

• a_directory_outside_the_repository_is_refused_with_exit_two_and_unread — tests/cli_test.rs
• a_read_failure_after_admission_exits_three_not_two — tests/cli_test.rs
• an_unclean_file_exits_one_and_is_named — tests/cli_test.rs
• bare_invocation_prints_usage_not_a_bare_error — tests/cli_test.rs
• check_exits_zero_when_every_unbuilt_row_is_exempt_and_the_built_rows_pass — tests/cli_test.rs
• check_fails_e1_and_e11_and_names_the_permission_and_the_url — tests/cli_test.rs
• check_reads_the_admitted_directory_whatever_the_shell_cwd_is — tests/cli_test.rs
• check_reads_the_readme_for_e6_and_refuses_a_symlinked_one_unread — tests/cli_test.rs
• check_refuses_a_malformed_today_and_reports_development_layout — tests/cli_test.rs
• check_reports_every_applicable_rule_and_exits_one_while_any_row_is_unsupported — tests/cli_test.rs
• check_staged_evaluates_the_index_snapshot_not_the_working_tree — tests/cli_test.rs
• check_staged_reports_a_whole_extension_removal_and_evaluates_nothing — tests/cli_test.rs
• check_without_a_descriptor_exits_three_with_the_file_named — tests/cli_test.rs
• clean_extension_exits_zero_and_lists_each_file — tests/cli_test.rs
• template_scaffolds_an_extension_that_passes_check_with_nothing_failing — tests/cli_test.rs
• vendored_files_are_named_as_skipped_not_parsed — tests/cli_test.rs
• a_descriptor_over_the_cap_is_refused_at_read — src/descriptor.rs
• a_layout_entry_in_an_unimplemented_form_is_refused — src/descriptor.rs
• an_adr_citation_is_four_digits_or_refused — src/descriptor.rs
• an_exemption_is_typed_a_rule_id_a_reason_and_a_date — src/descriptor.rs
• class_is_required_and_closed — src/descriptor.rs
• the_two_committed_descriptors_parse — src/descriptor.rs
• a_filter_urls_array_with_a_non_literal_element_is_unread — src/dominance.rs
• a_gate_is_read_with_the_truth_value_the_effect_requires — src/dominance.rs
• a_listener_that_writes_outer_state_after_a_literal_comparison_is_a_site — src/dominance.rs
• a_listener_with_no_side_effect_has_none_and_an_unread_handler_says_so — src/dominance.rs
• a_literal_composed_operand_is_not_a_site_and_anything_else_is_untracked — src/dominance.rs
• a_registration_at_module_level_in_a_bare_try_has_no_gate — src/dominance.rs
• a_remove_or_has_listener_reference_is_not_unread — src/dominance.rs
• a_storage_callback_parameter_and_a_name_assigned_inside_it_are_storage_reads — src/dominance.rs
• _… 139 more_

Documentation coverage

pie showData
    title Public items with rustdoc
    "Documented" : 92
    "No rustdoc detected" : 26

Metrics

pie showData
    title Public API by kind
    "constant" : 9
    "enum" : 21
    "function" : 38
    "method" : 15
    "struct" : 34
    "type alias" : 1

pie showData
    title Rust source composition
    "Code" : 8814
    "Blank or comment" : 1825

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.