Files
gstack/lib/design-lint/report.ts
T
Garry Tanandcapy-ai[bot] 5f9b7ef209 Let the design lint check one section of a running app for crowded rows, cramped help text, loud notes and small tap targets (#4138)
* feat(design-lint): --scope app measures one app section for row spacing, flush help copy, loud notes and small targets (GST-1741 PR 1)

Adds an opt-in, render-only app profile to gstack-design-lint: its own
scheduler (lib/design-lint/render-app.ts) and probes
(lib/design-lint/render-probe-app.ts on window.__gstackLintApp), five
app-only rules at ask (row-crowding, copy-flush-under-list,
note-in-row-weight, small-hit-area, section-overflow), --within matched
through open shadow roots, readiness and state assertions, a LINT_APP
verdict with exit 0 clean / 1 open / 4 incomplete / 3 usage, --waivers,
URL redaction everywhere and private trace files for probe errors.

Behavior change: --url with no browser now exits 4 with
RENDER_UNAVAILABLE under every scope. Page and component output is
otherwise byte-identical to e58be61 (test/design-lint-scope-guard.test.ts).

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* test(design-lint): app profile scope, label-target and select-in-row cases (GST-1741 PR 1)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(design-lint): app rows read laid-out unboxed lists, and subpixel noise never fires a threshold (GST-1741 PR 1)

Measured against six real qm builds from the probe: the shipped access list
(flex rows, no border) slipped past row-crowding, and 8px padding read as 7.99px
and fired. Rows that set an avatar, text and control side by side now count as
a list of rows; thresholds ignore the last 0.05px.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: pre-landing review fixes (GST-1741 PR 1)

Redact secret-looking #fragment parameters like query ones; keep two --url states whose redacted names match as two states (name~2) and refuse only the same URL twice; a trace that cannot be written keeps the state PROBE_ERROR instead of crashing to exit 1; a section selector the browser refuses no longer holds the soft readiness wait, and a NOT_READY without --wait-for names the section.

Review-Finding: p1/specialist-batched#1 reader=security
Review-Finding: p1/specialist-batched#2 reader=testing
Review-Finding: p1/red-team#1 reader=red-team
Review-Finding: p1/red-team#2 reader=red-team
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: a generated state name never collides with a literal one (GST-1741 PR 1)

Names for --url states are given out from the set of names already used, so /p, /p#x and /p~2 measure as three states. Review-loop exception a-7c954c6c661f.

Review-Finding: p2/outside-voice#1 reader=outside-voice
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs: design-lint usage and project map name --scope app (GST-1741 PR 1)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Describe the app section check in everyday words in the changelog

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-11-07 19:56:12 +00:00

133 lines
5.1 KiB
TypeScript

/**
* Findings and the output contract of the design lint.
*
* LINT: <blocks|ask|polish|waived> <rule-id> <file>:<line> <evidence> | fix: <fix>
* LINT_SUMMARY: blocks=N ask=N waived=N polish=N render=<ran|skipped: reason>
*
* Blocking and waived are never summed: a waived finding leaves the ask count
* and lands in waived, so blocks=0 is always a true sentence about the Floor.
* Exit 2 when anything blocks, 1 when an ask is unanswered, 0 otherwise.
*/
import * as path from 'node:path';
import { RULES, ruleMeta, type Tier } from './rules/ids';
export type Grade = Tier | 'waived';
export type Source = 'static' | 'render' | 'copy';
export interface Finding {
rule: string;
tier: Tier;
grade: Grade;
file: string;
line: number;
evidence: string;
fix: string;
source: Source;
/** Set when a waiver answered the finding: the reason it recorded. */
waiver?: string;
/** An app-profile finding's measurement (--scope app): kept whole, never truncated. */
app?: AppMeasure;
}
export interface AppMeasure {
state: string;
viewport: string;
locator: string;
measured: number;
threshold: number;
}
export interface ReportOptions {
fix?: string;
/** A tell the rule can only suspect: a blocking rule reports at ask so a person confirms it. */
suspected?: boolean;
source?: Source;
}
export const trunc = (s: string, n = 120): string => (s.length > n ? s.slice(0, n - 1) + '…' : s);
/** One printable line: control characters, line separators and runs of whitespace become one space, so no value a page controls can forge a LINT line or drive the terminal. */
export const oneLine = (s: string): string => s.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029\s]+/g, ' ').trim();
export const relPath = (file: string, cwd = process.cwd()): string =>
/^https?:\/\//.test(file) ? file : path.isAbsolute(file) && file.startsWith(cwd + path.sep) ? file.slice(cwd.length + 1) : file;
/** Collects findings for one context (a page and its stylesheets, or a directory of components). */
export class Reporter {
readonly findings: Finding[] = [];
constructor(readonly scope: 'page' | 'component' | 'app' = 'page', readonly cwd = process.cwd()) {}
/** Records one finding and returns it; null when the rule is page-only and the scope is component. */
report(rule: string, file: string, line: number | null | undefined, evidence: string, opts: ReportOptions = {}): Finding | null {
const meta = ruleMeta(rule);
if (!meta) throw new Error(`design-lint: unknown rule id ${rule}`);
if (this.scope === 'component' && meta.pageOnly) return null;
if (meta.app && this.scope !== 'app') return null;
const tier: Tier = opts.suspected && meta.tier === 'blocks' ? 'ask' : meta.tier;
const finding: Finding = {
rule, tier, grade: tier,
file: oneLine(relPath(file, this.cwd)), line: line || 1,
evidence: trunc(field(evidence)),
fix: trunc(field(opts.fix ?? meta.fix), 240),
source: opts.source ?? (meta.render ? 'render' : 'static'),
};
this.findings.push(finding);
return finding;
}
}
/** One line, with the LINT line's own separator kept out of page-supplied text, so a parser splitting on the first ` | fix: ` reads the fix. */
const field = (s: unknown): string => oneLine(String(s)).replace(/ \| fix: /g, ' / fix: ');
const GRADE_RANK: Record<Grade, number> = { blocks: 0, ask: 1, waived: 2, polish: 3 };
/** Drop exact duplicates and order findings: blocks, ask, waived, polish; then rule, file, line. */
export function finalize(findings: Finding[]): Finding[] {
const seen = new Set<string>();
const unique = findings.filter((f) => {
const k = `${f.rule}|${f.grade}|${f.file}|${f.line}|${f.evidence}` + (f.app ? `|${f.app.state}|${f.app.viewport}|${f.app.locator}` : '');
if (seen.has(k)) return false;
seen.add(k);
return true;
});
return unique.sort((a, b) =>
GRADE_RANK[a.grade] - GRADE_RANK[b.grade]
|| (a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0)
|| (a.file < b.file ? -1 : a.file > b.file ? 1 : 0)
|| a.line - b.line);
}
export interface Summary {
blocks: number;
ask: number;
waived: number;
polish: number;
render: string;
}
export function summarize(findings: Finding[], render: string): Summary {
const count = (g: Grade) => findings.filter((f) => f.grade === g).length;
return { blocks: count('blocks'), ask: count('ask'), waived: count('waived'), polish: count('polish'), render };
}
export function formatFinding(f: Finding): string {
const fix = f.grade === 'waived' ? `waived (${f.waiver ?? 'on the record'})` : f.fix;
return oneLine(`LINT: ${f.grade} ${f.rule} ${f.file}:${f.line} ${f.evidence} | fix: ${fix}`);
}
export function formatSummary(s: Summary): string {
return `LINT_SUMMARY: blocks=${s.blocks} ask=${s.ask} waived=${s.waived} polish=${s.polish} render=${s.render}`;
}
export function exitCodeOf(s: Summary): 0 | 1 | 2 {
if (s.blocks > 0) return 2;
if (s.ask > 0) return 1;
return 0;
}
/** Every rule id, so a caller can list the contract. */
export const ruleTable = (): Array<{ id: string; tier: Tier; gate: string; title: string }> =>
Object.entries(RULES).map(([id, m]) => ({ id, tier: m.tier, gate: m.gate, title: m.title }));