agentic-mobile-kit 0.7.18 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/README.md +20 -5
  2. package/bin/cli.js +5 -3
  3. package/lib/doctor.js +31 -5
  4. package/lib/init.js +19 -24
  5. package/lib/menu.js +3 -3
  6. package/package.json +1 -1
  7. package/stacks/react-native/expo/.eas/workflows/pr-preview.yml +54 -0
  8. package/stacks/react-native/expo/.rulesync/permissions.jsonc +6 -0
  9. package/stacks/react-native/expo/AGENTS.md +33 -17
  10. package/stacks/react-native/expo/docs/amk/expo.md +22 -1
  11. package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +14 -12
  12. package/stacks/react-native/template/.agents/skills/m-change/SKILL.md +3 -2
  13. package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +6 -4
  14. package/stacks/react-native/template/.agents/skills/m-explore/SKILL.md +2 -2
  15. package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +34 -27
  16. package/stacks/react-native/template/.agents/skills/m-feature/build.md +35 -0
  17. package/stacks/react-native/template/.agents/skills/m-feature/plan.md +43 -0
  18. package/stacks/react-native/template/.agents/skills/m-learn/SKILL.md +3 -1
  19. package/stacks/react-native/template/.agents/skills/m-onboard/SKILL.md +10 -5
  20. package/stacks/react-native/template/.agents/skills/m-pause/SKILL.md +2 -0
  21. package/stacks/react-native/template/.agents/skills/m-prototype/SKILL.md +8 -9
  22. package/stacks/react-native/template/.agents/skills/m-release/SKILL.md +5 -4
  23. package/stacks/react-native/template/.agents/skills/m-report/SKILL.md +25 -0
  24. package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +8 -4
  25. package/stacks/react-native/template/.agents/skills/m-test/SKILL.md +24 -0
  26. package/stacks/react-native/template/.agents/skills/m-test/agents/openai.yaml +3 -0
  27. package/stacks/react-native/template/.githooks/pre-commit +12 -0
  28. package/stacks/react-native/template/.github/pull_request_template.md +7 -1
  29. package/stacks/react-native/template/.github/workflows/amk-ai-deps.yml +90 -0
  30. package/stacks/react-native/template/.github/workflows/amk-ai-review.yml +82 -0
  31. package/stacks/react-native/template/.github/workflows/amk-kit-update.yml +95 -0
  32. package/stacks/react-native/template/.github/workflows/amk-ready.yml +39 -0
  33. package/stacks/react-native/template/.github/workflows/ci.yml +79 -13
  34. package/stacks/react-native/template/.github/workflows/e2e.yml +10 -1
  35. package/stacks/react-native/template/.rulesync/hooks.jsonc +3 -1
  36. package/stacks/react-native/template/.rulesync/permissions.jsonc +6 -0
  37. package/stacks/react-native/template/.rulesync/subagents/m-design-reviewer.md +22 -0
  38. package/stacks/react-native/template/.rulesync/subagents/m-device-checker.md +2 -1
  39. package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +4 -2
  40. package/stacks/react-native/template/.rulesync/subagents/m-spec-writer.md +15 -0
  41. package/stacks/react-native/template/.rulesync/subagents/m-tester.md +23 -0
  42. package/stacks/react-native/template/AGENTS.md +26 -10
  43. package/stacks/react-native/template/codemagic.yaml +82 -1
  44. package/stacks/react-native/template/docs/amk/codemagic.md +8 -0
  45. package/stacks/react-native/template/docs/amk/design-system.md +15 -0
  46. package/stacks/react-native/template/docs/amk/glossary.md +12 -0
  47. package/stacks/react-native/template/docs/amk/react-native.md +22 -1
  48. package/stacks/react-native/template/docs/amk/team-process.md +33 -1
  49. package/stacks/react-native/template/rulesync.jsonc +1 -1
  50. package/stacks/react-native/template/scripts/amk/ai-job.js +106 -0
  51. package/stacks/react-native/template/scripts/amk/autopilot.js +837 -0
  52. package/stacks/react-native/template/scripts/amk/baseline.js +19 -7
  53. package/stacks/react-native/template/scripts/amk/ci-scope.js +59 -0
  54. package/stacks/react-native/template/scripts/amk/coverage.js +111 -0
  55. package/stacks/react-native/template/scripts/amk/guard.js +64 -1
  56. package/stacks/react-native/template/scripts/amk/handoff-check.js +87 -14
  57. package/stacks/react-native/template/scripts/amk/issue.js +31 -0
  58. package/stacks/react-native/template/scripts/amk/metrics.js +164 -0
  59. package/stacks/react-native/template/scripts/amk/pr.js +244 -0
  60. package/stacks/react-native/template/scripts/amk/redact.js +57 -0
  61. package/stacks/react-native/template/scripts/amk/release-build.sh +14 -0
  62. package/stacks/react-native/template/scripts/amk/report.js +48 -11
  63. package/stacks/react-native/template/scripts/amk/rn-check.js +204 -47
  64. package/stacks/react-native/template/scripts/amk/shots.js +131 -0
  65. package/stacks/react-native/template/scripts/amk/specs.js +717 -34
  66. package/stacks/react-native/template/scripts/amk/tool-configs.js +41 -0
  67. package/stacks/react-native/template/scripts/amk/verify.sh +127 -23
  68. package/stacks/react-native/template/specs/_templates/design.md +25 -3
  69. package/stacks/react-native/template/specs/_templates/flow.yaml +5 -1
  70. package/stacks/react-native/template/specs/_templates/plan.md +54 -0
  71. package/stacks/react-native/template/specs/_templates/progress.md +1 -1
  72. package/stacks/react-native/template/specs/_templates/questions.md +29 -0
  73. package/stacks/react-native/template/specs/_templates/requirements.md +40 -0
  74. package/stacks/react-native/template/specs/_templates/tasks.md +2 -2
  75. package/stacks/react-native/template/specs/_templates/test-report.md +25 -0
  76. package/stacks/react-native/template/.github/workflows/ios.yml +0 -41
@@ -2,16 +2,22 @@
2
2
  // Checks the lines this branch adds or changes for React Native mistakes that the app's rules (docs/amk/react-native.md
3
3
  // or expo.md) list, and its Maestro flows (.maestro/): Maestro's own syntax check, files they run that aren't there,
4
4
  // taps by text, and each scenario of a spec the branch touched with its steps, an assertion and a screenshot.
5
- // Problems (✗) fail it, and so verify.sh quick; warnings (!) don't. Only changed lines: code already
5
+ // Problems (✗) fail it, and so verify.sh quick; warnings (!) don't. An API a React Native version removed is a problem
6
+ // from that version on, and a warning in an app still below it, where it works. Only changed lines: code already
6
7
  // on the base branch is never reported. A line that's right as it is carries `// amk-ok <date>: <reason>`, on it or on
7
8
  // the line above, with the user's reason and the day they gave it; it's listed as kept, for review. When a branch changes
8
9
  // a file again, a kept line in it that's over two weeks old is reported again, for the user to decide again (the date
9
10
  // from git when the comment has none).
10
- // The base is the one baseline.js uses (AMK_BASE sets it). Usage: node scripts/amk/rn-check.js
11
+ // It warns too about a source file over a size limit that's new or grows, and a function over a complexity limit (as
12
+ // ESLint's complexity rule counts it, through the app's ESLint) that's new or got more complex. .amk-size-caps, which
13
+ // the project owns, holds the limits and a cap for each file already over the limit: `--write-caps` writes it from the
14
+ // code as it is, and later lowers caps as files shrink (never raises one).
15
+ // The base is the one baseline.js uses (AMK_BASE sets it). Usage: node scripts/amk/rn-check.js [--write-caps]
11
16
  'use strict';
12
17
  const fs = require('fs');
13
18
  const path = require('path');
14
19
  const { execFileSync, spawnSync } = require('child_process');
20
+ const { stripYamlComments, scenarios, flowBlocks, blockFor, allFlows, flowsOf } = require('./specs.js');
15
21
 
16
22
  const root = process.cwd();
17
23
  const git = (...args) => {
@@ -37,15 +43,56 @@ const source = f => /\.(js|jsx|ts|tsx|mjs|cjs)$/.test(f) && !f.endsWith('.d.ts')
37
43
  // Maestro flows: the ones verify.sh runs (.maestro/*.yaml) and the subflows they run (in folders below)
38
44
  // (not the copies with view-tree steps verify.sh runs for a moment on Android: .amk-<screen>-<flow>.yaml)
39
45
  const flowFile = f => /^\.maestro\/.+\.ya?ml$/.test(f) && !/(^|\/)\.amk-/.test(f);
46
+
47
+ // ---------- the size limits: .amk-size-caps ----------
48
+ const CAPS = '.amk-size-caps';
49
+ let capsText = null;
50
+ try { capsText = fs.readFileSync(path.join(root, CAPS), 'utf8').replace(/\r\n/g, '\n'); } catch {}
51
+ const limits = { limit: 400, complexity: 20 };
52
+ const caps = new Map(); // file -> the most lines it may have
53
+ for (const l of (capsText || '').split('\n')) {
54
+ const m = /^\s*([^#\s]\S*)\s+(\d+)\s*$/.exec(l);
55
+ if (m && m[1] in limits) limits[m[1]] = Number(m[2]); else if (m) caps.set(m[1], Number(m[2]));
56
+ }
57
+ const lineCount = text => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
58
+ // what the limits count: source files, not generated ones
59
+ const sized = (f, text) => source(f) && !/(^|\/)(__generated__|generated)\/|\.generated\.\w+$/.test(f) && !/@generated\b/.test(text.slice(0, 1000));
60
+ if (process.argv.includes('--write-caps')) {
61
+ const now = new Map();
62
+ for (const f of (git('ls-files') || '').split('\n')) {
63
+ let text;
64
+ try { text = fs.readFileSync(path.join(root, f), 'utf8'); } catch { continue; }
65
+ if (f && sized(f, text)) now.set(f, lineCount(text));
66
+ }
67
+ // the first time, every file over the limit at its size; later, caps only come down: to a file's size when it
68
+ // shrank, and away when it's gone or under the limit
69
+ const entries = capsText === null ? [...now].filter(([, n]) => n > limits.limit)
70
+ : [...caps].filter(([f]) => (now.get(f) || 0) > limits.limit).map(([f, cap]) => [f, Math.min(cap, now.get(f))]);
71
+ const head = capsText === null ? [
72
+ '# rn-check (in verify.sh quick) warns about a source file over the limit, in lines, that\'s new or grows. These files were',
73
+ '# over it already: each warns when it grows past its cap here. Caps only come down: `node scripts/amk/rn-check.js',
74
+ '# --write-caps` lowers them as the files shrink. complexity: the most a new function may have (ESLint\'s complexity rule).',
75
+ `limit ${limits.limit}`, `complexity ${limits.complexity}`,
76
+ ] : capsText.split('\n').filter(l => { const m = /^\s*([^#\s]\S*)\s+\d+\s*$/.exec(l); return !m || m[1] in limits; });
77
+ while (head.length && !head[head.length - 1].trim()) head.pop();
78
+ fs.writeFileSync(path.join(root, CAPS), `${[...head, ...entries.sort().map(([f, n]) => `${f} ${n}`)].join('\n')}\n`);
79
+ const lowered = capsText === null ? 0 : entries.filter(([f, n]) => n < caps.get(f)).length;
80
+ console.log(capsText === null ? `${CAPS}: ${entries.length} file(s) over ${limits.limit} lines, each capped at its size now. Commit it.`
81
+ : `${CAPS}: ${lowered} cap(s) lowered, ${caps.size - entries.length} removed (the file is gone or under the limit)`);
82
+ process.exit(0);
83
+ }
84
+
40
85
  const changed = new Map(); // file -> Set of line numbers, or 'all'
86
+ const hunks = new Map(); // file -> the diff's [base start, base lines, start, lines], to find a line's place in the base
41
87
  if (sha) {
42
88
  let file = null;
43
89
  for (const line of (git('diff', '-U0', '--no-color', '--no-ext-diff', '--relative', '-M', '--diff-filter=ACMR', sha) || '').split('\n')) {
44
90
  if (line.startsWith('+++ ')) { file = line === '+++ /dev/null' ? null : line.slice(6); continue; }
45
- const h = /^@@ -\S+ \+(\d+)(?:,(\d+))? @@/.exec(line);
91
+ const h = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
46
92
  if (!h || !file || !(source(file) || flowFile(file))) continue;
47
- if (!changed.has(file)) changed.set(file, new Set());
48
- for (let n = Number(h[1]), end = n + Number(h[2] ?? 1); n < end; n++) changed.get(file).add(n);
93
+ if (!changed.has(file)) { changed.set(file, new Set()); hunks.set(file, []); }
94
+ hunks.get(file).push([Number(h[1]), Number(h[2] ?? 1), Number(h[3]), Number(h[4] ?? 1)]);
95
+ for (let n = Number(h[3]), end = n + Number(h[4] ?? 1); n < end; n++) changed.get(file).add(n);
49
96
  }
50
97
  }
51
98
  for (const f of (git('ls-files', '--others', '--exclude-standard') || '').split('\n')) if (f && (source(f) || flowFile(f))) changed.set(f, 'all');
@@ -56,6 +103,11 @@ try { pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))
56
103
  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
57
104
  const major = name => Number((/\d+/.exec(deps[name] || '') || [0])[0]);
58
105
  const expoSdk = deps.expo ? major('expo') : 0;
106
+ // React Native's minor version (0.84.1 is 84; a 1.x is past every 0.x). An API a version removed is a problem from that
107
+ // version on; in an app still below it, it works, so it's a warning to change it before upgrading. Unknown: a problem
108
+ const rnMinor = (m => (!m ? null : Number(m[1]) > 0 ? Infinity : Number(m[2])))(/(\d+)\.(\d+)/.exec(deps['react-native'] || ''));
109
+ const removedIn = minor => (rnMinor !== null && rnMinor < minor ? '!' : '✗');
110
+ const beforeUpgrade = minor => (rnMinor !== null && rnMinor < minor ? ` (this app is on 0.${rnMinor}: change it before upgrading)` : '');
59
111
 
60
112
  // the code without its comments (each comment character a space, so positions and lines stay). A quote opened in
61
113
  // JSX text (Don't) ends with its line, so it can't hide the rest of the file; a template string can span lines
@@ -135,9 +187,9 @@ function check(file, text) {
135
187
  const each = (re, fn, src = code) => { for (const m of src.matchAll(re)) fn(m); };
136
188
 
137
189
  // problems: removed or private APIs, secrets and tokens in the open, images in code
138
- each(/\bInteractionManager\b/g, m => add('✗', m.index, null, 'InteractionManager was removed in React Native 0.87: use requestIdleCallback'));
139
- each(/\babsoluteFillObject\b/g, m => add('✗', m.index, null, 'StyleSheet.absoluteFillObject was removed in React Native 0.85: use StyleSheet.absoluteFill'));
140
- each(/\bStatusBar\s*\.\s*set(BackgroundColor|Translucent)\s*\(/g, m => add('✗', m.index, null, `StatusBar.set${m[1]} was removed in React Native 0.87 (edge to edge, it did nothing)`));
190
+ each(/\bInteractionManager\b/g, m => add(removedIn(87), m.index, null, `InteractionManager was removed in React Native 0.87: use requestIdleCallback${beforeUpgrade(87)}`));
191
+ each(/\babsoluteFillObject\b/g, m => add(removedIn(85), m.index, null, `StyleSheet.absoluteFillObject was removed in React Native 0.85: use StyleSheet.absoluteFill${beforeUpgrade(85)}`));
192
+ each(/\bStatusBar\s*\.\s*set(BackgroundColor|Translucent)\s*\(/g, m => add(removedIn(87), m.index, null, `StatusBar.set${m[1]} was removed in React Native 0.87 (edge to edge, it did nothing)${beforeUpgrade(87)}`));
141
193
  each(/<\s*(StatusBar|Modal|ScrollView|FlatList|SectionList|KeyboardAwareScrollView)\b/g, m => {
142
194
  const end = endOf(code, m.index);
143
195
  const tag = code.slice(m.index, end + 1);
@@ -146,9 +198,9 @@ function check(file, text) {
146
198
  : /\s(keyboardShouldPersistTaps)(\s*=\s*\{\s*(true|false)\s*\}|(?=[\s/>]))/.exec(tag);
147
199
  if (!prop) return;
148
200
  const instead = { backgroundColor: 'edge to edge, it did nothing', translucent: 'edge to edge, it did nothing', animated: 'use animationType', keyboardShouldPersistTaps: 'use "handled"' }[prop[1]];
149
- add('✗', m.index + prop.index + 1, null, `${m[1]}'s ${prop[1] === 'keyboardShouldPersistTaps' ? 'boolean keyboardShouldPersistTaps' : prop[1]} was removed in React Native 0.87: ${instead}`);
201
+ add(removedIn(87), m.index + prop.index + 1, null, `${m[1]}'s ${prop[1] === 'keyboardShouldPersistTaps' ? 'boolean keyboardShouldPersistTaps' : prop[1]} was removed in React Native 0.87: ${instead}${beforeUpgrade(87)}`);
150
202
  });
151
- each(/(['"])react-native\/Libraries\/[^'"\n]*\1/g, m => add('✗', m.index, null, `${m[0]} is React Native's private code (a type error from 0.87): import from 'react-native'`));
203
+ each(/(['"])react-native\/Libraries\/[^'"\n]*\1/g, m => add(removedIn(87), m.index, null, `${m[0]} is React Native's private code (a type error from 0.87): import from 'react-native'${beforeUpgrade(87)}`));
152
204
  // at the name itself: a branch that adds another name to an old import statement didn't add this one
153
205
  for (const m of importsFrom(code, 'react-native')) {
154
206
  const name = n => { const i = m[0].search(new RegExp(`\\b${n}\\b`)); return i < 0 ? null : m.index + i; };
@@ -211,6 +263,15 @@ function check(file, text) {
211
263
  if (l && !/\breturn\b/.test(body)) add('!', m.index, close, `${l[1]} in an effect that returns no cleanup: return a function that removes it`, lineAt(code, open + l.index));
212
264
  });
213
265
  each(/\bconsole\s*\.\s*log\s*\(/g, m => add('!', m.index, null, 'console.log left in: remove it, or use the app\'s logger'));
266
+ // the generated look: marketing filler for copy, placeholder text and names, emoji in place of the app's icons
267
+ each(/\b(seamless(?:ly)?|effortless(?:ly)?|supercharge[ds]?|revolutioni[sz](?:e|es|ed|ing)|revolutionary|cutting-edge|next-level|game-?chang(?:er|ing)|unleash(?:es|ed)?|elevate your|empower your|unlock your (?:full )?potential)\b/gi,
268
+ m => add('!', m.index, null, `"${m[0]}" reads as generated copy: say what it does, in the app's words (docs/amk/glossary.md)`));
269
+ each(/\b(lorem ipsum|(?:john|jane) doe|acme)\b/gi, m => add('!', m.index, null, `"${m[0]}" is filler: the real text, or a placeholder the PR lists`));
270
+ // not in translation files: an emoji there is part of a message ("Welcome 👋"), not an icon
271
+ if (!/(^|\/)(i18n?|locales?|translations?|lang)\//i.test(file)) {
272
+ each(/\p{Emoji_Presentation}|\p{Extended_Pictographic}\uFE0F/gu,
273
+ m => add('!', m.index, null, 'an emoji in the app: an icon from its icon set (docs/amk/design-system.md), unless it\'s content'));
274
+ }
214
275
  each(/\bmask(AllTextInputs|AllText|AllInputs|TextInputs)\s*:\s*false\b/g, m => add('!', m.index, null, 'session replay that records what users type: mask text inputs'));
215
276
  each(/\bAccessibilityInfo\s*\.\s*setAccessibilityFocus\s*\(/g, m => add('!', m.index, null, 'AccessibilityInfo.setAccessibilityFocus is deprecated: use sendAccessibilityEvent'));
216
277
  // platform guidelines: text, back, screen readers, tap areas, permissions, motion
@@ -261,18 +322,6 @@ function lineAt(code, i) {
261
322
  }
262
323
 
263
324
  // ---------- Maestro flows ----------
264
- // a flow without its comments (each comment character a space, so positions stay): # outside quotes starts one
265
- function stripYamlComments(text) {
266
- return text.split('\n').map(l => {
267
- let quote = null;
268
- for (let i = 0; i < l.length; i++) {
269
- const c = l[i];
270
- if (quote) { if (c === quote) quote = null; } else if (c === '"' || c === "'") quote = c;
271
- else if (c === '#' && (i === 0 || /\s/.test(l[i - 1]))) return l.slice(0, i) + ' '.repeat(l.length - i);
272
- }
273
- return l;
274
- }).join('\n');
275
- }
276
325
  const TAPS = /^(tapOn|doubleTapOn|longPressOn)$/;
277
326
  const SELECTS = /^(tapOn|doubleTapOn|longPressOn|assertVisible|assertNotVisible|scrollUntilVisible|extendedWaitUntil|copyTextFrom)$/;
278
327
  const ASSERTS = /^(assertVisible|assertNotVisible|assertTrue|assertWithAI|assertNoDefectsWithAI)$/;
@@ -280,6 +329,8 @@ const ASSERTS = /^(assertVisible|assertNotVisible|assertTrue|assertWithAI|assert
280
329
  const SYSTEM_BUTTON = /^(allow|allow while using (the )?app|allow once|only this time|while using the app|ok|cancel|continue|don.t allow|not now|deny|close)$/i;
281
330
  const unquote = v => { v = v.trim(); return /^'.*'$/.test(v) ? v.slice(1, -1).replace(/''/g, "'") : /^".*"$/.test(v) ? v.slice(1, -1) : v; };
282
331
  let noMaestro = false;
332
+ // Maestro there but unable to start (a sandbox that keeps it out of ~/.maestro, a broken Java): its first line
333
+ let maestroFailed = '';
283
334
  function checkFlow(file, text) {
284
335
  const out = [];
285
336
  const add = (level, at, message, always) => out.push({ level, at, end: at, message, always });
@@ -325,9 +376,11 @@ function checkFlow(file, text) {
325
376
  // a flow verify.sh runs (not a subflow) that never checks anything passes whatever the app shows
326
377
  if (/^\.maestro\/[^/]+$/.test(file) && !asserts) add('!', 0, 'this flow checks nothing: add an assertVisible for what each scenario\'s THEN expects', true);
327
378
  // Maestro's own syntax check (seconds, no device): AMK_MAESTRO names another maestro
328
- const r = noMaestro ? null : spawnSync(process.env.AMK_MAESTRO || 'maestro', ['check-syntax', file], { cwd: root, encoding: 'utf8' });
379
+ const r = noMaestro || maestroFailed ? null : spawnSync(process.env.AMK_MAESTRO || 'maestro', ['check-syntax', file], { cwd: root, encoding: 'utf8' });
329
380
  if (r && r.error) noMaestro = true;
330
- else if (r && r.status !== 0) {
381
+ else if (r && r.status !== 0 && /Exception in thread|java\.lang\.\w+(?:Error|Exception)|Error occurred during initialization of VM|Could not find or load main class|Operation not permitted/.test(`${r.stdout}${r.stderr}`)) {
382
+ maestroFailed = `${r.stdout || ''}\n${r.stderr || ''}`.split('\n').map(x => x.trim()).find(Boolean);
383
+ } else if (r && r.status !== 0) {
331
384
  const said = `${r.stdout || ''}\n${r.stderr || ''}`.split('\n').map(s => s.trim()).find(s => s && s !== 'OK') || 'invalid flow';
332
385
  const n = Number((/:(\d+):\d+/.exec(said) || [])[1]) || 1;
333
386
  add('✗', text.split('\n').slice(0, n - 1).reduce((a, s) => a + s.length + 1, 0), `maestro check-syntax: ${said.replace(/\s+at \/syntax-checker:\d+:\d+/, '')}`, true);
@@ -362,6 +415,93 @@ for (const [file, lines] of changed) {
362
415
  }
363
416
  }
364
417
 
418
+ // ---------- file size and complexity, in the files this branch changed ----------
419
+ // ESLint's complexity rule, run on its own through the app's ESLint, reporting every function (no other rule runs);
420
+ // beside it a rule that reports each function's whole range, to know which function each count is about. TypeScript
421
+ // files need the app's @typescript-eslint/parser. null without ESLint
422
+ const complexity = (() => {
423
+ const req = name => { try { return require(require.resolve(name, { paths: [root] })); } catch { return null; } };
424
+ const { Linter } = req('eslint') || {};
425
+ if (!Linter) return null;
426
+ const ts = req('@typescript-eslint/parser');
427
+ const fns = { create: context => { const report = node => context.report({ node, message: 'function' }); return { FunctionDeclaration: report, FunctionExpression: report, ArrowFunctionExpression: report }; } };
428
+ const parserOptions = { ecmaVersion: 'latest', sourceType: 'module', ecmaFeatures: { jsx: true } };
429
+ let verify;
430
+ try {
431
+ if (Number(String(Linter.version).split('.')[0]) >= 9) {
432
+ const linter = new Linter({ configType: 'flat' });
433
+ verify = (text, file, parser) => linter.verify(text, [{ files: ['**/*.{js,jsx,ts,tsx,mjs,cjs}'], plugins: { amk: { rules: { fns } } },
434
+ languageOptions: { ecmaVersion: 'latest', sourceType: 'module', parserOptions: { ecmaFeatures: { jsx: true } }, ...(parser && { parser }) },
435
+ rules: { complexity: ['warn', 0], 'amk/fns': 'warn' } }], file);
436
+ } else {
437
+ const linter = new Linter();
438
+ linter.defineRule('amk-fns', fns);
439
+ if (ts) linter.defineParser('amk-ts', ts);
440
+ verify = (text, file, parser) => linter.verify(text, { ...(parser && { parser: 'amk-ts' }), parserOptions, rules: { complexity: ['warn', 0], 'amk-fns': 'warn' } }, { filename: file });
441
+ }
442
+ } catch { return null; }
443
+ // the functions of a file: label ("Function 'save'"), complexity and first line; null when it can't be read
444
+ return Object.assign((file, text) => {
445
+ const parser = /\.tsx?$/.test(file) ? ts : null;
446
+ if (/\.tsx?$/.test(file) && !ts) return null;
447
+ let messages;
448
+ try { messages = verify(text, file, parser); } catch { return null; }
449
+ // a message from no rule: the file didn't parse, or the setup didn't take
450
+ if (messages.some(m => !m.ruleId)) return null;
451
+ const ranges = messages.filter(m => /^amk[-/]fns$/.test(m.ruleId));
452
+ const holds = (r, m) => (r.line < m.line || (r.line === m.line && r.column <= m.column)) && (r.endLine > m.line || (r.endLine === m.line && r.endColumn >= m.column));
453
+ return messages.filter(m => m.ruleId === 'complexity').map(m => {
454
+ const [, label, n] = /^(.*?) has a complexity of (\d+)/.exec(m.message) || [];
455
+ const fn = ranges.filter(r => holds(r, m)).sort((a, b) => b.line - a.line || b.column - a.column)[0];
456
+ return { label, n: Number(n), start: fn ? fn.line : m.line };
457
+ }).filter(f => f.label);
458
+ }, { ts: Boolean(ts) });
459
+ })();
460
+ // line n of a file now, in its version on the base: through the diff's hunks (null for a line the branch added)
461
+ function baseLine(hs, n) {
462
+ let shift = 0;
463
+ for (const [a, b, c, d] of hs) {
464
+ if (d && n >= c && n < c + d) return b ? a + Math.min(n - c, b - 1) : null;
465
+ if (n < (d ? c : c + 1)) break;
466
+ shift = (b ? a + b - 1 : a) - (d ? c + d - 1 : c);
467
+ }
468
+ return n + shift;
469
+ }
470
+ for (const [file, lines] of changed) {
471
+ if (!source(file)) continue;
472
+ let text;
473
+ try { text = fs.readFileSync(path.join(root, file), 'utf8'); } catch { continue; }
474
+ if (!sized(file, text)) continue;
475
+ const say = (at, message) => findings.push({ level: '!', message, where: `${file}:${at}` });
476
+ const before = lines === 'all' || !sha ? null : git('show', `${sha}:${file}`);
477
+ const n = lineCount(text);
478
+ if (caps.has(file)) {
479
+ if (n > caps.get(file)) say(1, `${n} lines, past its cap of ${caps.get(file)} in ${CAPS}: move a part out (a component, a hook, a helper) rather than raise the cap`);
480
+ } else if (n > limits.limit && before === null) {
481
+ say(1, `a new file of ${n} lines, over the ${limits.limit}-line limit: split it (components, hooks, helpers in files of their own)`);
482
+ } else if (n > limits.limit && n > lineCount(before)) {
483
+ say(1, `${n} lines, over the ${limits.limit}-line limit, and this branch made it longer (it had ${lineCount(before)}): move a part out rather than add to it`);
484
+ }
485
+ if (!complexity) continue;
486
+ const now = complexity(file, text);
487
+ if (!now) continue;
488
+ const old = before ? complexity(file, before) : null;
489
+ for (const f of now.filter(x => x.n > limits.complexity)) {
490
+ const at = old && baseLine(hunks.get(file) || [], f.start);
491
+ const was = at && old.find(o => o.start === at && o.label === f.label);
492
+ if (was && was.n >= f.n) continue;
493
+ say(f.start, was ? `${f.label} went from a complexity of ${was.n} to ${f.n}, over ${limits.complexity}: move a branch out into a function of its own`
494
+ : `${f.label} has a complexity of ${f.n}, over ${limits.complexity}: split it into smaller functions`);
495
+ }
496
+ }
497
+ // caps that can come down: their file shrank, is under the limit, or is gone
498
+ const lower = [...caps].flatMap(([f, cap]) => {
499
+ let text;
500
+ try { text = fs.readFileSync(path.join(root, f), 'utf8'); } catch { return [`${f} (gone)`]; }
501
+ const n = lineCount(text);
502
+ return n <= limits.limit ? [`${f} (now ${n} lines)`] : n < cap ? [`${f} (${cap} → ${n})`] : [];
503
+ });
504
+
365
505
  // ---------- once for the app: an error boundary somewhere ----------
366
506
  let boundary = true;
367
507
  if ([...changed.keys()].some(source)) {
@@ -379,38 +519,50 @@ if ([...changed.keys()].some(source)) {
379
519
  // "# Scenario <n>: <name>" comment above each one's steps, as specs/_templates/flow.yaml shows
380
520
  const touchedPaths = [...(sha ? (git('diff', '--name-only', '--relative', sha) || '').split('\n') : []),
381
521
  ...(git('ls-files', '--others', '--exclude-standard') || '').split('\n')].filter(Boolean);
382
- const norm = s => s.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
383
522
  const specIds = fs.existsSync(path.join(root, 'specs')) ? fs.readdirSync(path.join(root, 'specs'), { withFileTypes: true })
384
523
  .filter(e => e.isDirectory() && !/^(_|current$)/.test(e.name)).map(e => e.name) : [];
385
- const flowsDir = fs.existsSync(path.join(root, '.maestro')) ? fs.readdirSync(path.join(root, '.maestro')).filter(f => /\.ya?ml$/.test(f)) : [];
524
+ const flowsDir = allFlows(path.join(root, '.maestro'));
386
525
  for (const id of specIds) {
387
526
  const req = `specs/${id}/requirements.md`;
388
527
  let reqText;
389
528
  try { reqText = fs.readFileSync(path.join(root, req), 'utf8'); } catch { continue; }
390
- const flows = flowsDir.filter(f => f.toLowerCase().startsWith(id.toLowerCase())).map(f => `.maestro/${f}`);
529
+ const flows = flowsOf(id, flowsDir).map(f => `.maestro/${f}`);
391
530
  if (!flows.length || !touchedPaths.some(p => p.startsWith(`specs/${id}/`) || flows.includes(p))) continue;
392
- const blocks = flows.flatMap(f => {
393
- const text = fs.readFileSync(path.join(root, f), 'utf8');
394
- const code = stripYamlComments(text).split('\n');
395
- const out = [];
396
- text.split('\n').forEach((l, i) => {
397
- const m = /^\s*#\s*Scenario\b\s*(\d+)?\s*[:.)-]?\s*(.*)$/i.exec(l);
398
- if (m) out.push({ n: Number(m[1]) || 0, name: norm(m[2]), at: i });
399
- else if (out.length) out[out.length - 1].code = `${out[out.length - 1].code || ''}${code[i]}\n`;
400
- });
401
- return out.map(b => ({ ...b, flow: f }));
402
- });
403
- [...reqText.matchAll(/^#### Scenario:\s*(.*)$/gm)].forEach((m, i) => {
404
- const name = norm(m[1]);
405
- const where = `${req}:${reqText.slice(0, m.index).split('\n').length}`;
406
- const b = blocks.find(x => x.n === i + 1) || blocks.find(x => name && x.name && (x.name.includes(name) || name.includes(x.name)));
407
- const say = message => findings.push({ level: '!', message, where });
408
- if (!b) say(`scenario ${i + 1} "${m[1].trim()}" has no block in ${flows.join(', ')}: add "# Scenario ${i + 1}: ${m[1].trim()}" above its steps, with an assertion for its THEN and a screenshot`);
531
+ const blocks = flows.flatMap(f => flowBlocks(fs.readFileSync(path.join(root, f), 'utf8')).map(b => ({ ...b, flow: f })));
532
+ for (const s of scenarios(reqText)) {
533
+ const b = blockFor(blocks, s.n, s.name);
534
+ const say = message => findings.push({ level: '!', message, where: `${req}:${s.line}` });
535
+ if (!b) say(`scenario ${s.n} "${s.name}" has no block in ${flows.join(', ')}: add "# Scenario ${s.n}: ${s.name}" above its steps, with an assertion for its THEN and a screenshot`);
409
536
  else {
410
- if (!/-\s*(assertVisible|assertNotVisible|assertTrue|assertWithAI|extendedWaitUntil)\b/.test(b.code || '')) say(`scenario ${i + 1} "${m[1].trim()}" has no assertion in ${b.flow}: check what its THEN expects`);
411
- if (!/-\s*takeScreenshot\b/.test(b.code || '')) say(`scenario ${i + 1} "${m[1].trim()}" has no screenshot in ${b.flow}, so it has no evidence`);
537
+ if (!/-\s*(assertVisible|assertNotVisible|assertTrue|assertWithAI|extendedWaitUntil)\b/.test(b.code)) say(`scenario ${s.n} "${s.name}" has no assertion in ${b.flow}: check what its THEN expects`);
538
+ if (!/-\s*takeScreenshot\b/.test(b.code)) say(`scenario ${s.n} "${s.name}" has no screenshot in ${b.flow}, so it has no evidence`);
412
539
  }
413
- });
540
+ }
541
+ }
542
+
543
+ // ---------- a text in every language: the language files a branch touched lack no key a sibling has ----------
544
+ // JSON in a folder named i18n, locales, translations or lang: en.json beside de.json, or en/common.json beside
545
+ // de/common.json. Only gaps the branch made: a key missing on the base branch already isn't reported
546
+ const LANG = /(^|\/)(i18n?|locales?|translations?|lang)\//i;
547
+ const flatKeys = text => { const flat = (o, p) => Object.entries(o || {}).flatMap(([k, v]) => (v && typeof v === 'object' && !Array.isArray(v) ? flat(v, `${p}${k}.`) : [`${p}${k}`]));
548
+ try { return new Set(flat(JSON.parse(text), '')); } catch { return null; } };
549
+ const langGroups = new Map();
550
+ for (const f of new Set([...(git('ls-files') || '').split('\n'), ...touchedPaths])) {
551
+ if (!f || !f.endsWith('.json') || !LANG.test(f) || !fs.existsSync(path.join(root, f))) continue;
552
+ const dir = path.posix.dirname(f);
553
+ const key = /^[a-z]{2,3}([-_][A-Za-z]{2,4})?$/.test(path.posix.basename(dir)) ? `${path.posix.dirname(dir)}/*/${path.posix.basename(f)}` : `${dir}/*.json`;
554
+ langGroups.set(key, [...(langGroups.get(key) || []), f]);
555
+ }
556
+ for (const files of langGroups.values()) {
557
+ if (files.length < 2 || !files.some(f => touchedPaths.includes(f))) continue;
558
+ const gaps = read => { const sets = files.map(f => [f, flatKeys(read(f) || '{}')]).filter(([, k]) => k);
559
+ const all = new Set(sets.flatMap(([, k]) => [...k])); return new Map(sets.map(([f, k]) => [f, [...all].filter(x => !k.has(x))])); };
560
+ const now = gaps(f => fs.readFileSync(path.join(root, f), 'utf8'));
561
+ const before = sha ? gaps(f => git('show', `${sha}:${f}`)) : new Map();
562
+ for (const [f, missing] of now) {
563
+ const fresh = missing.filter(k => !(before.get(f) || []).includes(k));
564
+ if (fresh.length) findings.push({ level: '!', where: `${f}:1`, message: `no text for ${fresh.length === 1 ? 'a key' : `${fresh.length} keys`} its other languages have: ${fresh.slice(0, 5).join(', ')}${fresh.length > 5 ? ', …' : ''}. Add each, as react-native.md says (Texts in several languages)` });
565
+ }
414
566
  }
415
567
 
416
568
  // ---------- report ----------
@@ -425,6 +577,11 @@ else if (!findings.length) console.log(`rn-check: nothing to report in the lines
425
577
  else console.log(`rn-check: ${plural(problems.length, 'problem')}, ${plural(warnings.length, 'warning')} in the lines changed since ${since}`);
426
578
  for (const f of [...problems, ...warnings]) console.log(` ${f.level} ${f.where} ${f.message}`);
427
579
  if (noMaestro && [...changed.keys()].some(flowFile)) console.log(' flows not syntax-checked: Maestro isn\'t installed here');
580
+ if (maestroFailed && [...changed.keys()].some(flowFile)) console.log(` flows not syntax-checked: Maestro couldn't start here (${maestroFailed.slice(0, 120)})`);
581
+ const sources = [...changed.keys()].filter(source);
582
+ if (sources.length && !complexity) console.log(' complexity not counted: ESLint isn\'t installed here');
583
+ else if (sources.some(f => /\.tsx?$/.test(f)) && complexity && !complexity.ts) console.log(' complexity not counted in TypeScript files: rn-check can\'t find the app\'s @typescript-eslint/parser');
584
+ if (lower.length) console.log(` size caps that can come down: ${lower.slice(0, 5).join(', ')}${lower.length > 5 ? ` and ${lower.length - 5} more` : ''}. node scripts/amk/rn-check.js --write-caps lowers them`);
428
585
  if (!boundary) console.log(` ! the app has no error boundary: a render error shows a blank screen or closes the app. Wrap the app in one`);
429
586
  if (kept.length) console.log(` kept with amk-ok: ${[...new Set(kept)].join('; ')}`);
430
587
  if (problems.length) {
@@ -0,0 +1,131 @@
1
+ #!/usr/bin/env node
2
+ // Compares a device check's screenshots with the approved ones, so only the screens that changed need a look, and makes
3
+ // new ones the approved ones. Approved screenshots stay on this machine, in .amk/approved/<screen>/<name>.png (.amk/ is
4
+ // out of git), by screen (ios, android-landscape, …) and screenshot name, which is unique in an app (<id>-<n>-<name>).
5
+ // The status bar (the top 6% of a screenshot, with its clock) isn't compared; a screenshot changed when over 1% of the
6
+ // rest differs. verify.sh runs `compare` after each device check, and `approve` for `verify.sh approve`.
7
+ // node scripts/amk/shots.js compare <evidence folder> writes <evidence folder>/.shots and says what changed
8
+ // node scripts/amk/shots.js approve <evidence folder> copies its screenshots into .amk/approved/
9
+ 'use strict';
10
+ const fs = require('fs');
11
+ const path = require('path');
12
+ const zlib = require('zlib');
13
+ // required, not the global: an app's lint may check these scripts with React Native's globals, which leave Buffer out
14
+ const { Buffer } = require('buffer');
15
+
16
+ const APPROVED = '.amk/approved';
17
+ const [cmd, dir] = process.argv.slice(2);
18
+
19
+ // the screenshots of an evidence folder, [screen, name, path]: each screen's folder, its parts', not Maestro's own logs
20
+ function shots(evidence) {
21
+ const out = [];
22
+ const walk = (screen, d) => {
23
+ for (const e of fs.readdirSync(d, { withFileTypes: true })) {
24
+ if (e.isDirectory()) walk(screen, path.join(d, e.name));
25
+ else if (e.name.endsWith('.png')) out.push([screen, e.name, path.join(d, e.name)]);
26
+ }
27
+ };
28
+ for (const e of fs.readdirSync(evidence, { withFileTypes: true })) if (e.isDirectory() && e.name !== 'maestro-logs') walk(e.name, path.join(evidence, e.name));
29
+ return out.sort((a, b) => a[2].localeCompare(b[2]));
30
+ }
31
+
32
+ // a PNG's pixels: 8-bit RGB or RGBA, not interlaced, as simulators, emulators and Maestro save them; null for any other
33
+ function decode(buf) {
34
+ if (buf.length < 8 || buf.readUInt32BE(0) !== 0x89504e47) return null;
35
+ let w = 0, h = 0, depth = 0, type = 0, interlace = 0;
36
+ const data = [];
37
+ for (let i = 8; i + 8 <= buf.length;) {
38
+ const len = buf.readUInt32BE(i);
39
+ const kind = buf.toString('ascii', i + 4, i + 8);
40
+ const body = buf.subarray(i + 8, i + 8 + len);
41
+ if (kind === 'IHDR') [w, h, depth, type, interlace] = [body.readUInt32BE(0), body.readUInt32BE(4), body[8], body[9], body[12]];
42
+ else if (kind === 'IDAT') data.push(body);
43
+ else if (kind === 'IEND') break;
44
+ i += 12 + len;
45
+ }
46
+ const bpp = { 2: 3, 6: 4 }[type];
47
+ if (depth !== 8 || !bpp || interlace) return null;
48
+ let raw;
49
+ try { raw = zlib.inflateSync(Buffer.concat(data)); } catch { return null; }
50
+ const stride = w * bpp;
51
+ if (raw.length < h * (stride + 1)) return null;
52
+ const px = Buffer.alloc(h * stride);
53
+ // each row's filter (none, sub, up, average, Paeth) undone against the row before
54
+ for (let y = 0; y < h; y++) {
55
+ const f = raw[y * (stride + 1)];
56
+ const row = y * (stride + 1) + 1;
57
+ for (let x = 0; x < stride; x++) {
58
+ const a = x >= bpp ? px[y * stride + x - bpp] : 0;
59
+ const b = y ? px[(y - 1) * stride + x] : 0;
60
+ const c = x >= bpp && y ? px[(y - 1) * stride + x - bpp] : 0;
61
+ let v = raw[row + x];
62
+ if (f === 1) v += a;
63
+ else if (f === 2) v += b;
64
+ else if (f === 3) v += (a + b) >> 1;
65
+ else if (f === 4) { const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c); v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c; }
66
+ px[y * stride + x] = v & 255;
67
+ }
68
+ }
69
+ return { w, h, bpp, px };
70
+ }
71
+
72
+ // the share of two screenshots' pixels that differ, in percent, below the status bar; -1 when their sizes differ
73
+ function differs(a, b) {
74
+ if (a.w !== b.w || a.h !== b.h) return -1;
75
+ const top = Math.round(a.h * 0.06);
76
+ let changed = 0;
77
+ for (let y = top; y < a.h; y++) {
78
+ for (let x = 0; x < a.w; x++) {
79
+ const i = (y * a.w + x) * a.bpp;
80
+ const j = (y * b.w + x) * b.bpp;
81
+ if (Math.abs(a.px[i] - b.px[j]) > 24 || Math.abs(a.px[i + 1] - b.px[j + 1]) > 24 || Math.abs(a.px[i + 2] - b.px[j + 2]) > 24) changed++;
82
+ }
83
+ }
84
+ return Math.round((10000 * changed) / ((a.h - top) * a.w)) / 100;
85
+ }
86
+
87
+ function compare(evidence) {
88
+ const label = path.basename(path.resolve(evidence));
89
+ const all = shots(evidence);
90
+ if (!all.length) return 0;
91
+ if (!fs.existsSync(APPROVED)) {
92
+ console.log(`screenshots: none approved yet. Once these look right: sh scripts/amk/verify.sh approve --label ${label}`);
93
+ return 0;
94
+ }
95
+ const rows = all.map(([screen, name, file]) => {
96
+ const was = path.join(APPROVED, screen, name);
97
+ if (!fs.existsSync(was)) return [screen, name, 'new', '', file];
98
+ const [now, then] = [decode(fs.readFileSync(file)), decode(fs.readFileSync(was))];
99
+ if (!now || !then) return [screen, name, 'changed', 'not compared', file]; // a kind of PNG this can't read: look at it
100
+ const pct = differs(now, then);
101
+ return [screen, name, pct > 1 || pct < 0 ? 'changed' : 'same', pct < 0 ? 'another size' : `${pct}% differs`, file];
102
+ });
103
+ fs.writeFileSync(path.join(evidence, '.shots'), rows.map(r => [...r.slice(0, 4), path.relative(evidence, r[4]).split(path.sep).join('/')].join('\t')).join('\n') + '\n');
104
+ const of = s => rows.filter(r => r[2] === s);
105
+ console.log(`screenshots: ${of('changed').length} changed since the approved ones, ${of('new').length} new, ${of('same').length} the same`);
106
+ for (const r of [...of('changed'), ...of('new')].slice(0, 12)) console.log(` ${r[2]}: ${path.relative(process.cwd(), r[4]).split(path.sep).join('/')}${r[3] ? ` (${r[3]})` : ''}`);
107
+ if (of('changed').length + of('new').length > 12) console.log(` … all of them in ${path.join(evidence, '.shots')}`);
108
+ if (of('changed').length || of('new').length) console.log(` Once these look right: sh scripts/amk/verify.sh approve --label ${label}`);
109
+ return 0;
110
+ }
111
+
112
+ function approve(evidence) {
113
+ const all = shots(evidence);
114
+ if (!all.length) { console.log(`verify: no screenshots in ${path.relative(process.cwd(), evidence) || evidence} to approve: run a device check first`); return 1; }
115
+ for (const [screen, name, file] of all) {
116
+ fs.mkdirSync(path.join(APPROVED, screen), { recursive: true });
117
+ fs.copyFileSync(file, path.join(APPROVED, screen, name));
118
+ }
119
+ fs.rmSync(path.join(evidence, '.shots'), { force: true });
120
+ console.log(`approved: ${all.length} screenshots of ${path.basename(path.resolve(evidence))} are the approved ones now (${APPROVED}/)`);
121
+ return 0;
122
+ }
123
+
124
+ module.exports = { decode, differs };
125
+
126
+ if (require.main === module) {
127
+ if (!['compare', 'approve'].includes(cmd) || !dir || !fs.existsSync(dir)) {
128
+ console.error('usage: node scripts/amk/shots.js compare|approve <evidence folder>');
129
+ process.exitCode = 2;
130
+ } else process.exitCode = cmd === 'compare' ? compare(dir) : approve(dir);
131
+ }