Enhancement: check --variants / variant-manifest — recognize intentional co-located variant sets (avoid false multiple_root_compositions)

[carlosmirandalevy]

Summary

npx hyperframes check assumes one root composition per project directory. Some production layouts intentionally co-locate a variant set — several complete root-composition files in one directory (e.g. index.html, index-en.html, index-fr.html, index-h.html — locale × orientation), each a standalone composition, built and rendered one explicit file per invocation (never dir-discovered).

Running check over such a directory reports multiple_root_compositions for every intro, even though each composition is correct and there is no duplicate-render / duplicate-audio risk (the build always targets an explicit file, not the directory).

This is an enhancement request for a first-class way to tell check that a directory holds an intentional variant set — distinct from the accidental "two compositions collided in one folder" case the current warning is designed for.

Impact today

• A clean, human-friendly layout (one directory per intro, its locale × orientation variants side by side) cannot pass a dir-level check at 0 findings, so "require 0 findings" can't be applied literally to it.
• The only alternative that satisfies the current discovery model is to explode an N-directory layout into N×M single-composition subdirectories, purely to appease dir-discovery — which trades a tidy structure for a mechanical one.

Current workaround

Gate per-file: run check against each composition file in isolation (a wrapper that presents one root at a time). It works and reports all real per-composition findings, but it's external tooling every consumer re-implements, and it gives up the convenience of a single dir-level check.

Requested enhancement

A first-class way to declare an intentional set of sibling root compositions in one directory — either of:

• check --variants — a flag that treats each root composition in the directory as an independent unit, checks each in isolation, and suppresses multiple_root_compositions while still surfacing every real per-composition finding.
• A variant manifest — e.g. a variants.json, or a data-variant-set marker on the roots, that enumerates the sibling compositions so check (and potentially render) understand the set explicitly.

Either would let a co-located variant layout pass a clean dir-level check without restructuring.

Concrete context

A real layout that hits this: a set of narrated intro compositions, each shipped as es/en/fr/pt × normal/vertical variants in one directory per intro. Every composition passes check individually (Runtime / Layout / Motion / Contrast all clean); the only dir-level finding is multiple_root_compositions, which is purely the deliberate co-location.

Related

• check (StaticGuard): false "uses data-end without data-duration" on <audio> that already has data-duration and no data-end #2662 — a separate StaticGuard false-positive (data-end on <audio> that has data-duration and no data-end). Independent of this request.

[jrusso1020]

Thanks for the detailed write-up + concrete context — variant sets in one directory is a legitimate authoring shape (locale × orientation matrices), and the current multiple_root_compositions rule is a false positive for it.

Confirmed the current behavior against packages/lint/src/project.ts:428: the rule counts every .html at the project root that contains data-composition-id, and errors if there's more than one. The rule was authored against the "two compositions accidentally collided in one folder" case; there's no signal today for the deliberate variant-set case.

I'd like to prioritize this with the team before shipping a fix — the API design has two reasonable shapes and either is small (~15-30 LoC + tests), so we should pick the one we want to live with:

Option A — hyperframes.json variant manifest (favored)

{
  "variants": ["index.html", "index-en.html", "index-fr.html", "index-h.html"]
}

Lint reads the field and treats listed files as an intentional set. check iterates each variant in isolation, aggregates findings, and suppresses multiple_root_compositions for the declared set. Non-listed root HTMLs still trip the rule. Render can later consume the same field to enable hyperframes render --variant en-h etc.

Option B — check --variants CLI flag
Simplest to ship (~10 LoC + a test); no config file change. Downside: variant identity is transient — CI must remember to pass the flag, and render gains no first-class awareness of the set.

Option C — per-file marker (e.g. data-variant-set="hero-intro" on the root)
Nice for self-describing files but adds a runtime-visible attribute for a build-time concern; probably worse than A/B.

My weak preference is A because it's declarative and unblocks future variant-aware commands. Happy to implement whichever the team picks — leaving this open for discussion rather than pushing a speculative PR.

@heygen-com/hyperframes-team — thoughts?

— Rames Jusso