mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
Co-authored-by: GPT-5.6 Sol <noreply@openai.com> Co-authored-by: miguel.sierra <miguel.sierra@heygen.com> Co-authored-by: heygengenesis[bot] <262951085+heygengenesis[bot]@users.noreply.github.com>
163 lines
6.1 KiB
TypeScript
163 lines
6.1 KiB
TypeScript
import { FEEDBACK_RATING_SCALE } from "./feedbackRating.js";
|
|
|
|
/**
|
|
* Keywords that suggest the reporter is describing a visual defect (as opposed
|
|
* to a build failure, missing feature, or plain workflow friction). When these
|
|
* appear in a non-10 feedback comment, the reporter should include a
|
|
* `COMPOSITION_STRUCTURE:` block so maintainers can pattern-match against
|
|
* known bug families without receiving the composition ZIP. Matched
|
|
* case-insensitively, word-bounded against the raw comment (so "black" fires
|
|
* on "black frame" but not "blackboard" / "no black frame at all").
|
|
*
|
|
* `"render"` intentionally omitted: `hyperframes render` is the CLI's primary
|
|
* command, so build/perf/hang reports mention it constantly and would drown
|
|
* the structure warning in false positives. Rely on the more specific tokens
|
|
* ("black", "blank", "flicker", "corrupt", "wrong frame") to identify actual
|
|
* visual defects.
|
|
*/
|
|
export const VISUAL_DEFECT_KEYWORDS: readonly string[] = [
|
|
"black",
|
|
"flicker",
|
|
"corrupt",
|
|
"wrong frame",
|
|
"blank",
|
|
"visual",
|
|
] as const;
|
|
|
|
/**
|
|
* Ratings that should mandate `COMPOSITION_STRUCTURE:` when the comment
|
|
* contains a visual-defect keyword. 7 and below covers "clearly broken" —
|
|
* 8-9 are usually "worked, but noticed a nit" which doesn't need the full
|
|
* structural anatomy.
|
|
*/
|
|
export const COMPOSITION_STRUCTURE_RATING_CEILING = 7;
|
|
|
|
const REPRO_MARKER = "REPRO COMMAND:";
|
|
const STRUCTURE_MARKER = "COMPOSITION_STRUCTURE:";
|
|
const FEEDBACK_PACKET_MARKERS = [
|
|
REPRO_MARKER,
|
|
"EXPECTED / ACTUAL:",
|
|
"EXACT ERROR:",
|
|
"OUTCOME:",
|
|
"WORKAROUND:",
|
|
STRUCTURE_MARKER,
|
|
] as const;
|
|
|
|
export interface FeedbackLintInput {
|
|
rating: number;
|
|
comment: string | undefined;
|
|
}
|
|
|
|
export interface FeedbackLintWarning {
|
|
code: "missing-repro-command" | "missing-composition-structure";
|
|
message: string;
|
|
}
|
|
|
|
/**
|
|
* Soft-warn lint on the `hyperframes feedback` comment body. Never blocks
|
|
* submission — some legitimate reports (a one-line "cloudrun quota bumped
|
|
* yesterday, fine now") won't fit the mold. The warning is just a nudge and
|
|
* a pointer to the auto-census helper.
|
|
*
|
|
* Rules:
|
|
* 1. `rating === 10` — no check. A perfect run doesn't need a repro packet.
|
|
* 2. Comment missing / empty — no check. `feedback --rating 6` with no
|
|
* comment is a valid quick vote; the maintainer sees rating drift without
|
|
* the reporter having to synthesize a fake repro.
|
|
* 3. Comment present + rating < 10 + no non-empty `REPRO COMMAND:` body — warn.
|
|
* 4. Comment present + rating ≤ 7 + visual-defect keyword + no
|
|
* `COMPOSITION_STRUCTURE:` — warn (in addition to any #3 warning).
|
|
*/
|
|
export function lintFeedbackComment(input: FeedbackLintInput): FeedbackLintWarning[] {
|
|
const { rating, comment } = input;
|
|
if (rating === FEEDBACK_RATING_SCALE) return [];
|
|
const trimmed = comment?.trim();
|
|
if (!trimmed) return [];
|
|
|
|
// Marker checks are case-insensitive to match `mentionsVisualDefect`'s
|
|
// normalization. A reporter who writes `Repro command:` shouldn't get warned
|
|
// for compliance just because they lowercased the marker.
|
|
const upperTrimmed = trimmed.toUpperCase();
|
|
const warnings: FeedbackLintWarning[] = [];
|
|
|
|
if (!hasReproCommandBody(trimmed)) {
|
|
warnings.push({
|
|
code: "missing-repro-command",
|
|
message: [
|
|
`Comment on a ${rating}/${FEEDBACK_RATING_SCALE} report is missing a non-empty "${REPRO_MARKER}" block —`,
|
|
"maintainers can't rerun the failure from a symptom summary alone.",
|
|
"See `references/preview-render.md` → feedback for the required packet shape.",
|
|
].join(" "),
|
|
});
|
|
}
|
|
|
|
if (
|
|
rating <= COMPOSITION_STRUCTURE_RATING_CEILING &&
|
|
mentionsVisualDefect(trimmed) &&
|
|
!upperTrimmed.includes(STRUCTURE_MARKER)
|
|
) {
|
|
warnings.push({
|
|
code: "missing-composition-structure",
|
|
message: [
|
|
`Comment describes a visual defect at ${rating}/${FEEDBACK_RATING_SCALE} but omits a`,
|
|
`"${STRUCTURE_MARKER}" block. Agents can auto-fill this via the composition-census helper`,
|
|
"(`buildCompositionCensus`/`renderCompositionCensusBlock` in `packages/cli/src/utils/compositionCensus.ts`)",
|
|
"so maintainers can pattern-match against known bug families without the composition ZIP.",
|
|
].join(" "),
|
|
});
|
|
}
|
|
|
|
return warnings;
|
|
}
|
|
|
|
/**
|
|
* A marker is useful only when it carries a command. Accept the command on the
|
|
* marker line or on the next non-empty line, but do not let the next packet
|
|
* section masquerade as the command body.
|
|
*/
|
|
function hasReproCommandBody(comment: string): boolean {
|
|
const lines = comment.split(/\r?\n/);
|
|
|
|
return lines.some((line, index) => {
|
|
const markerIndex = line.toUpperCase().indexOf(REPRO_MARKER);
|
|
if (markerIndex === -1) return false;
|
|
|
|
const inlineBody = line.slice(markerIndex + REPRO_MARKER.length).trim();
|
|
if (inlineBody) return !startsWithFeedbackPacketMarker(inlineBody);
|
|
|
|
const nextContentLine = lines.slice(index + 1).find((candidate) => candidate.trim());
|
|
if (!nextContentLine) return false;
|
|
|
|
return !startsWithFeedbackPacketMarker(nextContentLine.trimStart());
|
|
});
|
|
}
|
|
|
|
function startsWithFeedbackPacketMarker(value: string): boolean {
|
|
const upperValue = value.toUpperCase();
|
|
return FEEDBACK_PACKET_MARKERS.some((marker) => upperValue.startsWith(marker));
|
|
}
|
|
|
|
// Compile once. Word-boundary at both sides prevents "black" matching
|
|
// "blackboard", "blank" matching "blanket", "visual" matching "visualize".
|
|
// Plural forms (e.g. "flickers") won't match — accepted tradeoff for a soft
|
|
// warn: false negatives skip the nudge, false positives waste the reporter's
|
|
// attention.
|
|
function escapeRegex(input: string): string {
|
|
return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
}
|
|
|
|
const VISUAL_DEFECT_REGEX = new RegExp(
|
|
`(^|[^A-Za-z0-9_])(?:${VISUAL_DEFECT_KEYWORDS.map(escapeRegex).join("|")})(?![A-Za-z0-9_])`,
|
|
"i",
|
|
);
|
|
|
|
/**
|
|
* Case-insensitive word-bounded probe against `VISUAL_DEFECT_KEYWORDS`.
|
|
* Exposed for tests and reuse. Word boundaries are enforced on both sides so
|
|
* partial-word false positives ("blackboard", "visualize", "corruptible")
|
|
* don't trigger the structure-block nudge.
|
|
*/
|
|
export function mentionsVisualDefect(comment: string): boolean {
|
|
return VISUAL_DEFECT_REGEX.test(comment);
|
|
}
|