diff --git a/packages/core/src/compiler/htmlBundler.test.ts b/packages/core/src/compiler/htmlBundler.test.ts index e6ede4da0..b820d536f 100644 --- a/packages/core/src/compiler/htmlBundler.test.ts +++ b/packages/core/src/compiler/htmlBundler.test.ts @@ -1345,4 +1345,46 @@ describe("bundleToSingleHtml", () => { ); expect(styleEls[0]?.parentElement?.tagName.toLowerCase()).toBe("head"); }); + + // Regression: cli-feedback field cluster (crons 61-68, n=25+, cross-OS, + // versions 0.7.56-0.7.64). Reporter L3 cite (ts=1784519869): + // "bundleToSingleHtml compiles data-duration into data-end, then validates + // the compiled HTML and reports its own generated data-end as deprecated. + // Raw-source lint passes with 0 errors and 0 warnings." The end-to-end + // guarantee: source authored with only data-duration must round-trip through + // bundle + StaticGuard without producing a StaticGuard warning on the + // compiler's own consistent data-end. Facet-(a)/(e) fix. + it("does not emit a StaticGuard warning for source-authored data-duration on media", async () => { + const dir = makeTempProject({ + "index.html": ` + +t + +
+ + +
+ +`, + "bgm.mp3": "", + "narr.mp3": "", + }); + + const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); + try { + const bundled = await bundleToSingleHtml(dir); + // Sanity: the compiler MUST have emitted data-end for both audio elements, + // so the linter is actually seeing the compiled shape (not the raw source). + expect(bundled).toContain('id="bgm"'); + expect(bundled).toMatch(/id="bgm"[^>]*data-end="18"|data-end="18"[^>]*id="bgm"/); + expect(bundled).toMatch(/id="narration"[^>]*data-end="15"|data-end="15"[^>]*id="narration"/); + + const staticGuardWarnings = warnSpy.mock.calls + .map((call) => String(call[0] ?? "")) + .filter((line) => line.includes("[StaticGuard]")); + expect(staticGuardWarnings).toEqual([]); + } finally { + warnSpy.mockRestore(); + } + }); }); diff --git a/packages/lint/src/rules/composition.test.ts b/packages/lint/src/rules/composition.test.ts index eaaf7fdd7..6b70817dc 100644 --- a/packages/lint/src/rules/composition.test.ts +++ b/packages/lint/src/rules/composition.test.ts @@ -28,6 +28,42 @@ describe("composition rules", () => { result.findings.find(({ code }) => code === "overlapping_clips_same_track"), ).toBeUndefined(); }); + + // Regression: cli-feedback field cluster (crons 61-68, n=25+ across + // darwin/linux/win32 and versions 0.7.56-0.7.64). `bundleToSingleHtml` + // compiles `data-duration` into `data-end`, then re-validates the compiled + // HTML. Before this fix the linter fired `deprecated_data_end` on the + // compiler's own consistent output — a false-positive that reporters + // routed as "check --strict passes but StaticGuard still logs + // deprecated-attribute noise" (ts=1784548892, ts=1784541122). + it("does not flag deprecated_data_end when compiled data-end matches data-duration", async () => { + const result = await lintHyperframeHtml(` +
+ + +
+ + `); + + const deprecatedEnd = result.findings.filter(({ code }) => code === "deprecated_data_end"); + expect(deprecatedEnd).toEqual([]); + }); + + // Companion regression: a manually authored stale `data-end` still fires + // `deprecated_data_end`, with a message that names the disagreement so + // the author can spot the drift rather than reading the legacy phrasing. + it("still flags deprecated_data_end when data-end disagrees with data-duration", async () => { + const result = await lintHyperframeHtml(` +
+ +
+ + `); + + const deprecatedEnd = result.findings.find(({ code }) => code === "deprecated_data_end"); + expect(deprecatedEnd).toBeDefined(); + expect(deprecatedEnd?.message).toMatch(/disagrees with data-duration/); + }); }); describe("subcomposition guidance", () => { diff --git a/packages/lint/src/rules/composition.ts b/packages/lint/src/rules/composition.ts index 025e1551d..cbc8799aa 100644 --- a/packages/lint/src/rules/composition.ts +++ b/packages/lint/src/rules/composition.ts @@ -465,10 +465,20 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding } if (timing.diagnostics.some(({ code }) => code === "deprecated-end")) { const elementId = readAttr(tag.raw, "id") || undefined; + const conflicting = timing.diagnostics.some(({ code }) => code === "conflicting-end"); + // Two shapes reach here after the false-positive fix (see + // compositionContract.ts `diagnoseDerivedEnd`): the truly-legacy shape + // (no data-duration, data-end alone) and the stale-companion shape + // (data-duration present but paired with a data-end that disagrees). + // A consistent data-duration + data-end pair — the shape the compiler + // emits — is silent and never reaches this branch. + const message = conflicting + ? `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has data-end that disagrees with data-duration. Remove the stale data-end; the compiler regenerates it from data-duration.` + : `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses data-end without data-duration. Use data-duration in source HTML.`; findings.push({ code: "deprecated_data_end", severity: "error", - message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses data-end without data-duration. Use data-duration in source HTML.`, + message, elementId, fixHint: "Replace data-end with data-duration. The compiler generates data-end from data-duration automatically.", diff --git a/packages/parsers/src/compositionContract.test.ts b/packages/parsers/src/compositionContract.test.ts index 526b8fe4f..3842301ff 100644 --- a/packages/parsers/src/compositionContract.test.ts +++ b/packages/parsers/src/compositionContract.test.ts @@ -88,6 +88,39 @@ describe("composition timing contract", () => { expected: { start: 1, duration: 2, end: 3, trackIndex: 1 }, codes: ["deprecated-end", "conflicting-end", "deprecated-layer", "conflicting-layer"], }, + { + // Regression: compiler-derived `data-end` matching `data-duration` used + // to fire `deprecated-end`, which surfaced as a false-positive + // `deprecated_data_end` from StaticGuard whenever bundler output was + // re-validated. Field cluster: cli-feedback crons 61-68, n=25+ across + // darwin/linux/win32 and versions 0.7.56-0.7.64. Reporter L3 cite + // (ts=1784519869): "bundleToSingleHtml compiles data-duration into + // data-end, then validates the compiled HTML and reports its own + // generated data-end as deprecated." Consistent pairs are silent. + name: "compiler-derived end consistent with canonical duration is silent", + attrs: { + "data-start": "0", + "data-duration": "18", + "data-end": "18", + }, + expected: { start: 0, duration: 18, end: 18, trackIndex: 0 }, + codes: [], + }, + { + name: "compiler-derived end within float epsilon of canonical duration is silent", + // data-start="0.1" + data-duration="0.2" evaluates to 0.30000000000000004 + // under IEEE-754. The compiler serializes that residual verbatim, so the + // parsed derived-end and the reader-computed canonical end differ by ~2 ulps. + // A byte-exact comparison would refire the false positive; the epsilon + // gate keeps it silent. + attrs: { + "data-start": "0.1", + "data-duration": "0.2", + "data-end": "0.30000000000000004", + }, + expected: { start: 0.1, duration: 0.2 }, + codes: [], + }, { name: "invalid values are diagnosed rather than coerced", attrs: { "data-start": "wat +", "data-duration": "-1", "data-track-index": "1.5" }, diff --git a/packages/parsers/src/compositionContract.ts b/packages/parsers/src/compositionContract.ts index 56d901e60..1c25c58c6 100644 --- a/packages/parsers/src/compositionContract.ts +++ b/packages/parsers/src/compositionContract.ts @@ -206,18 +206,57 @@ function resolveStart( type DurationRead = Pick; type TrackRead = Pick; +// Float pairs like `data-start="0.1" + data-duration="0.2"` add to +// `0.30000000000000004`, so the compiler-emitted `data-end` string can be a few +// ulps off the sum a reader computes from the canonical inputs. Any drift below +// this ceiling is treated as equal for the derived-end reconciliation check — +// well below one 60fps frame (~16.67 ms) and orders of magnitude above the +// worst realistic IEEE-754 residual (~2e-16 s). +const DERIVED_END_EQUALITY_EPSILON_SECONDS = 1e-9; + +function derivedEndsAreConsistent(parsedEnd: number, canonicalEnd: number): boolean { + return Math.abs(parsedEnd - canonicalEnd) <= DERIVED_END_EQUALITY_EPSILON_SECONDS; +} + +// Reconcile a `data-end` attribute paired with canonical `data-duration`. +// +// The compiler (`compileTimingAttrs` in @hyperframes/core) writes +// `data-end = data-start + data-duration` into the bundled HTML so the runtime +// can key off a single attribute. That derived attribute is legitimate — it is +// not a legacy authoring shape. Treating it as `deprecated-end` here made the +// linter fire `deprecated_data_end` on the compiler's own output whenever +// StaticGuard re-validated a bundled composition, producing a false-positive +// cluster reported in the field (n=25+ across cli-feedback crons 61-68). +// +// We keep `deprecated-end` for the truly legacy shape (see `readLegacyEnd` — +// `data-end` present without `data-duration`) and for the *conflicting* case +// where an author left a stale `data-end` behind a canonical duration edit; a +// stale end must not be silently overridden without a diagnostic. function diagnoseDerivedEnd( rawEnd: string, canonicalEnd: number | null, diagnostics: ClipTimingDiagnostic[], ): void { - pushDiagnostic(diagnostics, "deprecated-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd); const parsedEnd = parseNumeric(rawEnd); if (parsedEnd == null) { + pushDiagnostic(diagnostics, "deprecated-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd); pushDiagnostic(diagnostics, "invalid-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd); - } else if (canonicalEnd != null && parsedEnd !== canonicalEnd) { - pushDiagnostic(diagnostics, "conflicting-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd); + return; } + if (canonicalEnd == null) { + // Canonical duration exists but resolved end is unknown (e.g. unresolved + // reference start). Preserve prior behavior — flag as deprecated so authors + // remove the stale companion attribute. + pushDiagnostic(diagnostics, "deprecated-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd); + return; + } + if (derivedEndsAreConsistent(parsedEnd, canonicalEnd)) { + // Compiler-derived (or manually consistent) `data-end` alongside + // `data-duration` — silent. No diagnostic. + return; + } + pushDiagnostic(diagnostics, "deprecated-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd); + pushDiagnostic(diagnostics, "conflicting-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd); } function readCanonicalDuration(