mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-19 22:54:36 +01:00
* 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>
133 lines
5.1 KiB
TypeScript
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 }));
|