mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-10-18 21:16:47 +00:00
jubnl
54b0e4eed4
* fix(sdk): grade docs/screenshot.png exactly, like the registry gate * docs(wiki): document plugin MCP tools and the exact screenshot gate * test(sdk): cover the preflight screenshot probe
93 lines
3.8 KiB
TypeScript
93 lines
3.8 KiB
TypeScript
/**
|
|
* The README quality gate, as pure functions of the markdown.
|
|
*
|
|
* These are a LINE-FOR-LINE port of TREK-Plugins' scripts/check-readme.mjs. They live apart
|
|
* from the checks that call them because the same gate runs twice, against two different
|
|
* READMEs, and both must agree with CI:
|
|
*
|
|
* - offline, against README.md in the WORKING TREE (`status` / `validate`)
|
|
* - over the network, against README.md at the PINNED COMMIT (`preflight`)
|
|
*
|
|
* The two differ more often than you would think — an author fills the README in and forgets
|
|
* to commit it, and the tree is green while the tag CI grades is not. Keeping one implementation
|
|
* means the offline pass can never be more lenient than the network one; only more current.
|
|
*
|
|
* If you change a rule here, change scripts/check-readme.mjs to match, or you have built a
|
|
* false green. test/checks-parity.test.ts asserts the two agree.
|
|
*/
|
|
|
|
/** Every section CI demands, matched case-insensitively as a substring of a heading. */
|
|
export const REQUIRED_SECTIONS = ['What it does', 'Screenshots', 'Permissions', 'Setup'];
|
|
|
|
/** Template prose that means the author never edited the scaffold. */
|
|
export const PLACEHOLDER_PATTERNS = [
|
|
/\{\{[^}]*\}\}/,
|
|
/\bREPLACE_ME\b/i,
|
|
/\bDescribe (what|the)\b/i,
|
|
/\byour-name\/trek-plugin/i,
|
|
];
|
|
|
|
export const MIN_PROSE_CHARS = 400;
|
|
|
|
/**
|
|
* The heading body, with the trailing HTML comment authors use to hide anchors cut off.
|
|
*
|
|
* Cut with indexOf rather than a regex on purpose. The obvious spellings — the
|
|
* `(.+?)\s*(?:<!--.*)?$` this used to be, or a `replace(/\s*<!--.*$/, '')` in front of it —
|
|
* put two quantifiers on the same run of spaces, and both then backtrack quadratically:
|
|
* a heading line padded with 80k spaces takes ~12s, 200k takes ~30s. This gate runs over
|
|
* READMEs anyone can submit to the registry, so that is a stall someone can post. Same
|
|
* failure the wiki sidebar parser was rewritten for (server/src/nest/help/wiki.ts).
|
|
*/
|
|
function headingBody(line: string): string {
|
|
const comment = line.indexOf('<!--');
|
|
return comment < 0 ? line : line.slice(0, comment);
|
|
}
|
|
|
|
/** Which of REQUIRED_SECTIONS have no matching heading. */
|
|
export function missingSections(md: string): string[] {
|
|
const headings = md
|
|
.split('\n')
|
|
// `\S.*\S|\S` instead of a lazy body: the edges are pinned to non-space, so nothing
|
|
// competes with the trailing `\s*`.
|
|
.map((line) => /^#{1,6}\s+(\S.*\S|\S)\s*$/.exec(headingBody(line))?.[1].toLowerCase())
|
|
.filter((h): h is string => h !== undefined);
|
|
return REQUIRED_SECTIONS.filter((want) => !headings.some((got) => got.includes(want.toLowerCase())));
|
|
}
|
|
|
|
/** The literal placeholder strings still present, e.g. ['Describe what']. */
|
|
export function placeholders(md: string): string[] {
|
|
const hits: string[] = [];
|
|
for (const re of PLACEHOLDER_PATTERNS) {
|
|
const hit = md.match(re);
|
|
if (hit) hits.push(hit[0]);
|
|
}
|
|
return hits;
|
|
}
|
|
|
|
/**
|
|
* The length of the author's actual WRITING, with everything that isn't prose stripped:
|
|
* comments, code fences, images, links, headings, table rows, then markdown punctuation.
|
|
*
|
|
* This is why a scaffold can't game the 400-char floor with a big permissions table — the
|
|
* table is stripped. It has to be sentences.
|
|
*/
|
|
export function proseLength(md: string): number {
|
|
return md
|
|
.replace(/<!--[\s\S]*?-->/g, '')
|
|
.replace(/```[\s\S]*?```/g, '')
|
|
.replace(/!\[[^\]]*\]\([^)]*\)/g, '')
|
|
.replace(/\[[^\]]*\]\([^)]*\)/g, '')
|
|
.replace(/^#{1,6}\s+.*$/gm, '')
|
|
.replace(/^\s*\|.*$/gm, '')
|
|
.replace(/[#>*_`|-]/g, '')
|
|
.replace(/\s+/g, ' ')
|
|
.trim().length;
|
|
}
|
|
|
|
/** Manifest permissions that are never named anywhere in the README. CI rejects these. */
|
|
export function undocumentedPermissions(md: string, permissions: string[]): string[] {
|
|
const lower = md.toLowerCase();
|
|
return permissions.filter((p) => !lower.includes(p.toLowerCase()));
|
|
}
|