trunative 1.0.0

package/dist/compile.js

@@ -0,0 +1,235 @@
+import { tokenize, values } from './mdx.js';
+/** Agent values a block may carry. Zed and anything else reads the "other" build. */
+export const AGENTS = ['claude', 'codex', 'antigravity', 'opencode', 'other'];
+/** Stack values a block may carry, in the order STACK.md may record them. */
+export const STACKS = ['flutter', 'expo', 'react-native', 'swiftui', 'compose', 'web'];
+/** Expo runs React Native, so it follows that branch when it has none of its own. */
+const INHERITS = { expo: 'react-native' };
+const STACK_LABELS = {
+    flutter: 'Flutter',
+    expo: 'Expo',
+    'react-native': 'React Native',
+    swiftui: 'SwiftUI',
+    compose: 'Jetpack Compose',
+    web: 'Mobile web',
+    other: 'Any other stack',
+};
+/**
+ * How a question reaches the user, per harness. The compiler writes one of
+ * these in front of the question, so no flow file carries the mechanism.
+ */
+const ASK = {
+    claude: (header) => `Ask this with the AskUserQuestion tool: \`header\` is "${header}", the options below are the options in that order, and the recommended one carries "(recommended)" at the end of its label. Wait for the answer before writing anything.`,
+    codex: (header) => `Ask this with the harness's question tool when the session exposes one, labelled "${header}", the options below in that order with the recommended one first and named as the recommendation. When it does not, ask in plain text ending in a question mark. Wait for the answer before writing anything.`,
+    antigravity: (header) => `Ask this with the harness's question tool when the session exposes one, labelled "${header}", the options below in that order with the recommended one first and named as the recommendation. When it does not, ask in plain text ending in a question mark. Wait for the answer before writing anything.`,
+    opencode: (header) => `Ask this in plain text, ending in a question mark, under the label "${header}", with the options below listed in that order and the recommended one named as the recommendation. Wait for the answer before writing anything.`,
+    other: (header) => `Ask this in plain text, ending in a question mark, under the label "${header}", with the options below listed in that order and the recommended one named as the recommendation. Wait for the answer before writing anything.`,
+};
+function matches(tag, target) {
+    const agent = values(tag.attributes['agent']);
+    if (agent.length > 0) {
+        return agent.includes(target.agent);
+    }
+    const stack = values(tag.attributes['stack']);
+    if (stack.includes('undecided')) {
+        return !target.stack;
+    }
+    if (!target.stack) {
+        return 'label';
+    }
+    if (stack.includes(target.stack)) {
+        return true;
+    }
+    const inherited = INHERITS[target.stack];
+    return inherited ? stack.includes(inherited) : false;
+}
+/**
+ * Sibling blocks, meaning a run of <If> blocks with nothing but blank lines
+ * between them. An "other" branch answers for its own run, not for the file.
+ */
+function groupsOf(tokens) {
+    const groups = new Map();
+    let group = [];
+    let depth = 0;
+    const flush = () => {
+        for (const tag of group) {
+            groups.set(tag, group);
+        }
+        group = [];
+    };
+    for (const token of tokens) {
+        if (token.type === 'tag') {
+            if (token.tag.name !== 'If') {
+                continue;
+            }
+            if (token.tag.kind === 'open') {
+                if (depth === 0) {
+                    group.push(token.tag);
+                }
+                depth += 1;
+            }
+            else if (token.tag.kind === 'close') {
+                depth = Math.max(0, depth - 1);
+            }
+            continue;
+        }
+        if (depth === 0 && token.text.trim() !== '' && group.length > 0) {
+            flush();
+        }
+    }
+    flush();
+    return groups;
+}
+/** True when nothing else in the run matched, so the "other" branch answers. */
+function otherWins(group, tag, target) {
+    return !(group ?? [tag]).some((sibling) => sibling !== tag && matches(sibling, target) === true);
+}
+function label(kind, tag) {
+    const list = values(tag.attributes[kind]);
+    return list.map((value) => STACK_LABELS[value] ?? value).join(' and ');
+}
+function collapse(lines) {
+    const out = [];
+    let fence = false;
+    for (const line of lines) {
+        if (/^\s*(```|~~~)/.test(line)) {
+            fence = !fence;
+        }
+        if (!fence && line.trim() === '' && out.length > 0 && out[out.length - 1].trim() === '') {
+            continue;
+        }
+        out.push(line);
+    }
+    while (out.length > 0 && out[out.length - 1].trim() === '') {
+        out.pop();
+    }
+    return out;
+}
+/** One rule heading, as the shipped file spells it. */
+function heading(tag) {
+    const id = tag.attributes['id'] ?? '';
+    const description = tag.attributes['description'] ?? '';
+    return `${tag.prefix}\`${id}\` ${description}`.trimEnd();
+}
+/**
+ * Turns one source file into the text a given agent reads. Every tag is either
+ * resolved or rendered as prose: nothing tagged survives into the output.
+ */
+export function compile(source, target) {
+    const tokens = tokenize(source);
+    const groups = groupsOf(tokens);
+    const out = [];
+    let skipDepth = 0;
+    let ask = null;
+    for (const token of tokens) {
+        if (token.type === 'text') {
+            if (skipDepth > 0) {
+                continue;
+            }
+            if (ask) {
+                if (ask.current) {
+                    ask.current.push(token.text);
+                }
+                else {
+                    ask.question.push(token.text);
+                }
+                continue;
+            }
+            out.push(token.text);
+            continue;
+        }
+        const tag = token.tag;
+        if (tag.name === 'If') {
+            if (tag.kind === 'close') {
+                if (skipDepth > 0) {
+                    skipDepth -= 1;
+                }
+                continue;
+            }
+            if (skipDepth > 0) {
+                skipDepth += 1;
+                continue;
+            }
+            const verdict = matches(tag, target);
+            if (verdict === 'label') {
+                out.push(`**${label('stack', tag)}**`, '');
+                continue;
+            }
+            const isOther = values(tag.attributes['agent']).includes('other') ||
+                values(tag.attributes['stack']).includes('other');
+            if (verdict === true || (isOther && otherWins(groups.get(tag), tag, target))) {
+                continue;
+            }
+            skipDepth = 1;
+            continue;
+        }
+        if (skipDepth > 0) {
+            continue;
+        }
+        if (tag.name === 'Rule') {
+            out.push(heading(tag));
+            continue;
+        }
+        if (tag.name === 'Index') {
+            continue;
+        }
+        if (tag.name === 'Check') {
+            if (tag.kind === 'open') {
+                const against = tag.attributes['against'] ?? 'line';
+                out.push('## Check', '', `Review answers each of these against the code, pointing at the ${against}:`, '');
+            }
+            continue;
+        }
+        if (tag.name === 'Verify') {
+            out.push(`- ${tag.content} \`${tag.attributes['rule'] ?? ''}\``);
+            continue;
+        }
+        if (tag.name === 'Device') {
+            out.push('', tag.content);
+            continue;
+        }
+        if (tag.name === 'Ask') {
+            if (tag.kind === 'open') {
+                ask = {
+                    header: tag.attributes['header'] ?? '',
+                    question: [],
+                    options: [],
+                    current: null,
+                    recommended: false,
+                };
+                continue;
+            }
+            if (ask) {
+                const lead = (ASK[target.agent] ?? ASK['other'])(ask.header);
+                out.push(...collapse(ask.question), '', lead, '', ...ask.options);
+                ask = null;
+            }
+            continue;
+        }
+        if (tag.name === 'Option' && ask) {
+            if (tag.kind === 'open') {
+                ask.current = [];
+                ask.recommended = tag.flags.includes('recommended');
+                continue;
+            }
+            const text = collapse(ask.current ?? [])
+                .map((line) => line.trim())
+                .filter(Boolean)
+                .join(' ');
+            ask.options.push(`- ${text}${ask.recommended ? ' (recommended)' : ''}`);
+            ask.current = null;
+            ask.recommended = false;
+            continue;
+        }
+    }
+    return `${collapse(out).join('\n')}\n`;
+}
+/**
+ * A rule heading is the one tag that carries content rather than a decision, so
+ * a file with nothing but headings still differs between variants only through
+ * the blocks around it. Every stack gets a copy regardless: the entry file names
+ * the stack it was resolved for, and an undecided block is dropped from it.
+ */
+export function variantStacks() {
+    return [...STACKS];
+}

package/dist/detect/rules.js

@@ -0,0 +1,208 @@
+import { finding, lines, occurrences } from './types.js';
+const DART = ['.dart'];
+const XML = ['.xml'];
+const BOTH = [...DART, ...XML];
+/** Anything in the file that makes a widget pressable. */
+const PRESSABLE = /GestureDetector|InkWell|IconButton|TextButton|ElevatedButton|OutlinedButton|FilledButton|onTap:|onPressed:/;
+const SCREEN = /Scaffold|CupertinoPageScaffold/;
+/** A literal size in a Flutter text style, which the type scale should own. */
+const detectTypeScale = {
+    rule: 'type-scale',
+    extensions: BOTH,
+    run(file, source) {
+        const found = [];
+        for (const { line, text } of lines(source)) {
+            if (file.endsWith('.dart') && /\bfontSize:\s*\d/.test(text)) {
+                found.push(finding('type-scale', file, line, text, 'a literal font size, where a text style should carry it'));
+            }
+            const android = /android:textSize="(\d+(?:\.\d+)?)(dp|px|sp)"/.exec(text);
+            if (android && android[2] !== 'sp') {
+                found.push(finding('type-scale', file, line, text, `text sized in ${android[2]}, which does not follow the user's setting`));
+            }
+        }
+        return found;
+    },
+};
+/** A pressable drawn smaller than the platform floor. */
+const detectTouchFloor = {
+    rule: 'touch-floor',
+    extensions: BOTH,
+    run(file, source) {
+        const found = [];
+        const pressable = PRESSABLE.test(source);
+        for (const { line, text } of lines(source)) {
+            if (file.endsWith('.dart') && pressable) {
+                for (const match of text.matchAll(/\b(width|height|size|minWidth|minHeight):\s*(\d+(?:\.\d+)?)/g)) {
+                    const value = Number(match[2]);
+                    if (value > 0 && value < 48) {
+                        found.push(finding('touch-floor', file, line, text, `${match[1]} of ${value} on a file that draws a pressable, under the 48dp floor`));
+                    }
+                }
+            }
+            const android = /android:(minWidth|minHeight|layout_width|layout_height)="(\d+(?:\.\d+)?)dp"/.exec(text);
+            if (android && Number(android[2]) > 0 && Number(android[2]) < 48 && /clickable="true"|Button/.test(source)) {
+                found.push(finding('touch-floor', file, line, text, `${android[1]} of ${android[2]}dp on a clickable view, under the 48dp floor`));
+            }
+        }
+        return found;
+    },
+};
+/** A screen that never reads an inset. */
+const detectLayoutInsets = {
+    rule: 'layout-insets',
+    extensions: DART,
+    run(file, source) {
+        if (!SCREEN.test(source)) {
+            return [];
+        }
+        if (/SafeArea|viewPadding|viewInsets|MediaQuery\.(of\(context\)\.)?padding|padding\.of\(context\)/.test(source)) {
+            return [];
+        }
+        const at = lines(source).find(({ text }) => SCREEN.test(text));
+        return [
+            finding('layout-insets', file, at?.line ?? 0, at?.text ?? '', 'a screen with no inset read anywhere in the file'),
+        ];
+    },
+};
+/** An icon-only control with nothing to announce. */
+const detectA11yName = {
+    rule: 'a11y-name',
+    extensions: BOTH,
+    run(file, source) {
+        const found = [];
+        if (file.endsWith('.dart')) {
+            for (const { line, text, window } of occurrences(source, /IconButton\(/)) {
+                if (!/tooltip:/.test(window) && !/Semantics\(|semanticsLabel|semanticLabel/.test(window)) {
+                    found.push(finding('a11y-name', file, line, text, 'an IconButton with neither a tooltip nor a Semantics label'));
+                }
+            }
+        }
+        for (const { line, text, window } of occurrences(source, /<ImageButton|<ImageView/, 400)) {
+            if (file.endsWith('.xml') && !/android:contentDescription/.test(window)) {
+                found.push(finding('a11y-name', file, line, text, 'an image control with no contentDescription on it'));
+            }
+        }
+        return found;
+    },
+};
+/** A field that arrives with the wrong keyboard and no autofill. */
+const detectFormInput = {
+    rule: 'form-input',
+    extensions: BOTH,
+    run(file, source) {
+        const found = [];
+        if (file.endsWith('.dart')) {
+            for (const { line, text, window } of occurrences(source, /\bTextF(?:ield|ormField)\(/)) {
+                if (!/keyboardType:/.test(window)) {
+                    found.push(finding('form-input', file, line, text, 'a text field with no keyboardType, so every field opens the same keyboard'));
+                }
+            }
+        }
+        for (const { line, text, window } of occurrences(source, /<EditText/, 400)) {
+            if (file.endsWith('.xml') && !/android:inputType/.test(window)) {
+                found.push(finding('form-input', file, line, text, 'an EditText with no inputType'));
+            }
+        }
+        return found;
+    },
+};
+/** A field that the platform cannot fill. */
+const detectFormAutofill = {
+    rule: 'form-autofill',
+    extensions: DART,
+    run(file, source) {
+        const found = [];
+        for (const { line, text, window } of occurrences(source, /\bTextF(?:ield|ormField)\(/)) {
+            if (!/autofillHints:/.test(window)) {
+                found.push(finding('form-autofill', file, line, text, 'a text field with no autofillHints, which the platform cannot fill'));
+            }
+        }
+        return found;
+    },
+};
+/** A client built without a deadline. */
+const detectNetTimeout = {
+    rule: 'net-timeout',
+    extensions: DART,
+    run(file, source) {
+        const found = [];
+        const configured = /connectTimeout|receiveTimeout|sendTimeout|\.timeout\(/.test(source);
+        for (const { line, text } of lines(source)) {
+            if (/\b(http\.Client\(\)|Dio\(|IOClient\()/.test(text) && !configured) {
+                found.push(finding('net-timeout', file, line, text, 'an HTTP client with no timeout anywhere in the file'));
+            }
+            if (/\bawait\s+http\.(get|post|put|delete|patch)\(/.test(text) && !/\.timeout\(/.test(text) && !configured) {
+                found.push(finding('net-timeout', file, line, text, 'a request with no deadline on it'));
+            }
+        }
+        return found;
+    },
+};
+/** Text the catalogue never saw. */
+const detectL10nStrings = {
+    rule: 'l10n-strings',
+    extensions: DART,
+    run(file, source) {
+        const found = [];
+        for (const { line, text } of lines(source)) {
+            const match = /\b(Text|SelectableText)\(\s*(['"])([^'"]{4,})\2/.exec(text);
+            if (!match) {
+                continue;
+            }
+            const literal = match[3];
+            if (!/[a-zA-Z]{3}/.test(literal) || /^\$/.test(literal)) {
+                continue;
+            }
+            found.push(finding('l10n-strings', file, line, text, `"${literal.slice(0, 40)}" is user-facing text written in code`));
+        }
+        return found;
+    },
+};
+/** Motion that never reads the system setting. */
+const detectMotionReduced = {
+    rule: 'motion-reduced',
+    extensions: DART,
+    run(file, source) {
+        if (!/AnimationController|AnimatedContainer|TweenAnimationBuilder|\.animate\(/.test(source)) {
+            return [];
+        }
+        if (/disableAnimations|reduceMotion|accessibleNavigation/.test(source)) {
+            return [];
+        }
+        const at = lines(source).find(({ text }) => /AnimationController|AnimatedContainer|TweenAnimationBuilder|\.animate\(/.test(text));
+        return [
+            finding('motion-reduced', file, at?.line ?? 0, at?.text ?? '', 'animation with no read of the reduced-motion setting in the file'),
+        ];
+    },
+};
+/** A list built without recycling. */
+const detectListVirtualise = {
+    rule: 'list-virtualise',
+    extensions: DART,
+    run(file, source) {
+        const found = [];
+        for (const { line, text, window } of occurrences(source, /\b(?:Column|ListBody)\(/)) {
+            if (/\.\.\.\w+\.map\(|\.\.\.\w+\.entries|for \(final/.test(window)) {
+                found.push(finding('list-virtualise', file, line, text, 'rows expanded into a Column, which builds every one of them'));
+            }
+        }
+        for (const { line, text, window } of occurrences(source, /\bListView\(/, 120)) {
+            if (/children:/.test(window)) {
+                found.push(finding('list-virtualise', file, line, text, 'a ListView with a children list rather than a builder'));
+            }
+        }
+        return found;
+    },
+};
+export const DETECTORS = [
+    detectTypeScale,
+    detectTouchFloor,
+    detectLayoutInsets,
+    detectA11yName,
+    detectFormInput,
+    detectFormAutofill,
+    detectNetTimeout,
+    detectL10nStrings,
+    detectMotionReduced,
+    detectListVirtualise,
+];

package/dist/detect/types.js

@@ -0,0 +1,36 @@
+/** Lines with their 1-based numbers, with block comments already dropped. */
+export function lines(source) {
+    return source
+        .replace(/\/\*[\s\S]*?\*\//g, (match) => match.replace(/[^\n]/g, ' '))
+        .split(/\r?\n/)
+        .map((text, index) => ({ line: index + 1, text }))
+        .filter(({ text }) => !/^\s*(\/\/|#|<!--)/.test(text));
+}
+/**
+ * Every match of a pattern, with the line it sits on and the text that follows
+ * it. Widgets span lines, so a per-line test calls a labelled control unlabelled
+ * whenever the label is on the next line.
+ */
+export function occurrences(source, pattern, span = 600) {
+    const clean = source.replace(/\/\*[\s\S]*?\*\//g, (match) => match.replace(/[^\n]/g, ' '));
+    const found = [];
+    const global = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`);
+    for (const match of clean.matchAll(global)) {
+        const index = match.index ?? 0;
+        const before = clean.slice(0, index);
+        const start = before.lastIndexOf('\n') + 1;
+        const text = clean.slice(start, clean.indexOf('\n', index) === -1 ? undefined : clean.indexOf('\n', index));
+        if (/^\s*(\/\/|#|<!--)/.test(text)) {
+            continue;
+        }
+        found.push({
+            line: before.split('\n').length,
+            text,
+            window: clean.slice(index, index + span),
+        });
+    }
+    return found;
+}
+export function finding(rule, file, line, text, message) {
+    return { rule, file, line, snippet: text.trim().slice(0, 160), message };
+}

package/dist/emit.js

@@ -0,0 +1,77 @@
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { compile } from './compile.js';
+import { packagedSkillDir, variantName } from './paths.js';
+import { isSkillFile } from './skill.js';
+const STACK_LABELS = {
+    flutter: 'Flutter',
+    expo: 'Expo',
+    'react-native': 'React Native',
+    swiftui: 'SwiftUI',
+    compose: 'Jetpack Compose',
+    web: 'mobile web',
+};
+/** Every file of the source skill, project-relative, in a stable order. */
+export async function listSkillFiles(root = packagedSkillDir) {
+    const found = [];
+    async function walk(dir) {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            if (!isSkillFile(entry.name)) {
+                continue;
+            }
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile()) {
+                found.push(relative(root, full).split(sep).join('/'));
+            }
+        }
+    }
+    await walk(root);
+    return found.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/** The written skill, read once and reused for every variant. */
+export async function readSources(root = packagedSkillDir) {
+    const sources = new Map();
+    for (const file of await listSkillFiles(root)) {
+        sources.set(file, await readFile(join(root, file)));
+    }
+    return sources;
+}
+/**
+ * The entry file names the skill, and a stack variant is a different skill with
+ * a different name, or an agent would see several skills claiming one id.
+ */
+function retitle(source, stack) {
+    if (!stack) {
+        return source;
+    }
+    const label = STACK_LABELS[stack] ?? stack;
+    return source
+        .replace(/^name:\s*(.+)$/m, (_, name) => `name: ${variantName(name.trim(), stack)}`)
+        .replace(/^description:\s*(.+)$/m, (_, text) => `description: ${text.trim().replace(/for any stack \([^)]*\)/, `in ${label}`)} Install this copy only in a ${label} project.`);
+}
+/** One variant, resolved in memory. Markdown is compiled, anything else copied. */
+export function resolve(sources, target) {
+    const out = new Map();
+    for (const [file, content] of sources) {
+        if (!file.endsWith('.md')) {
+            out.set(file, content);
+            continue;
+        }
+        const compiled = compile(content.toString('utf8'), target);
+        out.set(file, Buffer.from(file === 'SKILL.md' ? retitle(compiled, target.stack) : compiled, 'utf8'));
+    }
+    return out;
+}
+/** Writes a resolved variant to disk, replacing whatever was there. */
+export async function write(files, destination) {
+    await rm(destination, { recursive: true, force: true });
+    for (const [file, content] of files) {
+        const path = join(destination, ...file.split('/'));
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, content);
+    }
+    return files.size;
+}