universal-dev-standards 6.14.1 → 6.15.0-beta.2

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 (65) hide show
  1. package/bin/uds.js +2 -2
  2. package/bundled/ai/standards/developer-memory.ai.yaml +2 -2
  3. package/bundled/ai/standards/full-coverage-testing.ai.yaml +6 -4
  4. package/bundled/ai/standards/project-context-memory.ai.yaml +2 -2
  5. package/bundled/core/developer-memory.md +1 -1
  6. package/bundled/core/full-coverage-testing.md +4 -2
  7. package/bundled/core/open-work-tracking.md +13 -0
  8. package/bundled/core/project-context-memory.md +1 -1
  9. package/bundled/locales/COVERAGE.md +5 -4
  10. package/bundled/locales/zh-CN/CHANGELOG.md +57 -4
  11. package/bundled/locales/zh-CN/README.md +2 -2
  12. package/bundled/locales/zh-CN/SECURITY.md +1 -0
  13. package/bundled/locales/zh-CN/core/full-coverage-testing.md +5 -3
  14. package/bundled/locales/zh-CN/docs/AVAILABLE-STANDARDS.md +4 -4
  15. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +1 -0
  16. package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +8 -3
  17. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +5 -4
  18. package/bundled/locales/zh-CN/skills/README.md +2 -1
  19. package/bundled/locales/zh-CN/skills/commands/sdd-retro.md +1 -1
  20. package/bundled/locales/zh-CN/skills/dev-workflow-guide/SKILL.md +7 -7
  21. package/bundled/locales/zh-CN/skills/open-work-assistant/SKILL.md +133 -0
  22. package/bundled/locales/zh-TW/CHANGELOG.md +57 -4
  23. package/bundled/locales/zh-TW/README.md +2 -2
  24. package/bundled/locales/zh-TW/SECURITY.md +1 -0
  25. package/bundled/locales/zh-TW/core/developer-memory.md +3 -3
  26. package/bundled/locales/zh-TW/core/full-coverage-testing.md +5 -3
  27. package/bundled/locales/zh-TW/core/open-work-tracking.md +13 -2
  28. package/bundled/locales/zh-TW/core/project-context-memory.md +3 -3
  29. package/bundled/locales/zh-TW/docs/AVAILABLE-STANDARDS.md +4 -4
  30. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +1 -0
  31. package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +8 -3
  32. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +5 -4
  33. package/bundled/locales/zh-TW/skills/README.md +2 -1
  34. package/bundled/locales/zh-TW/skills/dev-workflow-guide/SKILL.md +7 -7
  35. package/bundled/locales/zh-TW/skills/open-work-assistant/SKILL.md +133 -0
  36. package/bundled/skills/README.md +2 -1
  37. package/bundled/skills/dev-workflow-guide/SKILL.md +4 -4
  38. package/bundled/skills/open-work-assistant/SKILL.md +127 -0
  39. package/bundled/templates/gates/check-anti-fake-tests.mjs +183 -23
  40. package/bundled/templates/gates/check-stubs.mjs +85 -16
  41. package/package.json +2 -2
  42. package/src/commands/audit.js +4 -1
  43. package/src/commands/check.js +55 -6
  44. package/src/commands/config.js +2 -3
  45. package/src/commands/init.js +10 -3
  46. package/src/commands/update.js +239 -43
  47. package/src/i18n/messages.js +87 -0
  48. package/src/installers/hooks-installer.js +32 -5
  49. package/src/installers/skills-installer.js +45 -0
  50. package/src/reconciler/actual-state-scanner.js +7 -1
  51. package/src/reconciler/backup-locations.js +3 -2
  52. package/src/reconciler/backup-manager.js +14 -11
  53. package/src/reconciler/diff-engine.js +19 -1
  54. package/src/reconciler/plan-executor.js +51 -7
  55. package/src/utils/copier.js +13 -8
  56. package/src/utils/flush-and-exit.js +37 -0
  57. package/src/utils/group-errors.js +65 -0
  58. package/src/utils/integration-generator.js +14 -5
  59. package/src/utils/marker-locator.js +48 -4
  60. package/src/utils/skill-hash-ownership.js +33 -0
  61. package/src/utils/skill-link-rewriter.js +184 -0
  62. package/src/utils/skills-installer.js +115 -11
  63. package/src/utils/transient-fs.js +168 -14
  64. package/standards-registry.json +10 -19
  65. package/bundled/ai/standards/open-work-tracking.ai.yaml +0 -466
@@ -23,10 +23,19 @@
23
23
  // node scripts/check-anti-fake-tests.mjs scan every test file under the project
24
24
  // node scripts/check-anti-fake-tests.mjs --staged scan only the test files staged for commit
25
25
  // node scripts/check-anti-fake-tests.mjs --json machine-readable result
26
+ // node scripts/check-anti-fake-tests.mjs --max-files N stop the walk after N files (default 200000) — and say so
26
27
  //
27
28
  // Exit codes: 0 nothing found | 1 findings (run on its own, this is a hard failure —
28
29
  // wire it into CI to enforce) | 2 could not judge (the scanner's own self-test failed,
29
- // or git was unreadable in --staged mode). 2 is never a pass.
30
+ // git was unreadable in --staged mode, or the search was INCOMPLETE — the walk hit its file
31
+ // limit, a directory could not be opened, or a test file could not be read — and it found
32
+ // nothing in the part it did see). 2 is never a pass.
33
+ //
34
+ // Exempting ONE test: put a comment `ANTI_FAKE_EXEMPT: <why this test needs no assertion>` on its
35
+ // own line, or in the comment lines directly above it. The reason must be at least 8 letters, digits
36
+ // or Chinese characters and not a placeholder such as TODO, or the marker does nothing. It reaches
37
+ // only the one test it is attached to. Exempted tests are listed in every run (and in --json as
38
+ // `exempted`), never hidden.
30
39
  //
31
40
  // Which files are tests, and which extensions are code, comes from `.standards/test-policy.json`
32
41
  // (optional; see the UDS docs). Test files in a language this script has no rule for are
@@ -367,22 +376,48 @@ export function lineIndex(text) {
367
376
  };
368
377
  }
369
378
 
370
- /** Every project-relative file under `root`, skipping the policy's ignored directories and symlinks. */
371
- export function walkFiles(root, policy) {
379
+ /** The most files one walk will list; the next file after that makes the walk "truncated". */
380
+ export const WALK_LIMIT = 200000;
381
+
382
+ /**
383
+ * Every project-relative file under `root`, skipping the policy's ignored directories and symlinks.
384
+ * At most `limit` files are listed (a hard limit, not a hint). The list is NOT the whole project when
385
+ * - `truncated` is true: there was at least one more file after the `limit`th, or
386
+ * - `unreadable` is not empty: a directory could not be opened, so what is in it is unknown.
387
+ * A caller must say so (XSPEC-518 R2): a short list is not a clean project. Directories are read in
388
+ * name order, so which part is left unread does not depend on the file system.
389
+ * @returns {{ files: string[], truncated: boolean, unreadable: string[] }}
390
+ */
391
+ export function walkFilesChecked(root, policy, limit = WALK_LIMIT) {
372
392
  const skip = new Set(policy.ignoreDirs);
373
393
  const out = [];
394
+ const unreadable = [];
374
395
  const stack = [''];
375
- while (stack.length > 0 && out.length < 200000) {
396
+ let truncated = false;
397
+ while (stack.length > 0 && !truncated) {
376
398
  const rel = stack.pop();
377
399
  let entries;
378
- try { entries = readdirSync(join(root, rel), { withFileTypes: true }); } catch { continue; }
400
+ try {
401
+ entries = readdirSync(join(root, rel), { withFileTypes: true }).sort((x, y) => (x.name < y.name ? -1 : x.name > y.name ? 1 : 0));
402
+ } catch (e) {
403
+ unreadable.push(`${rel || '.'} (${e.code || e.message})`);
404
+ continue;
405
+ }
379
406
  for (const e of entries) {
380
407
  const r = rel ? `${rel}/${e.name}` : e.name;
381
408
  if (e.isSymbolicLink()) continue;
382
- if (e.isDirectory()) { if (!skip.has(e.name)) stack.push(r); } else if (e.isFile()) out.push(r);
409
+ if (e.isDirectory()) { if (!skip.has(e.name)) stack.push(r); } else if (e.isFile()) {
410
+ if (out.length >= limit) { truncated = true; break; }
411
+ out.push(r);
412
+ }
383
413
  }
384
414
  }
385
- return out.sort();
415
+ return { files: out.sort(), truncated, unreadable };
416
+ }
417
+
418
+ /** The file list alone (see walkFilesChecked for whether it is the whole project). */
419
+ export function walkFiles(root, policy, limit = WALK_LIMIT) {
420
+ return walkFilesChecked(root, policy, limit).files;
386
421
  }
387
422
 
388
423
  /** Files staged for the next commit (added, copied, modified, renamed), or `{ error }`. */
@@ -397,7 +432,7 @@ export function stagedFiles(root) {
397
432
  }
398
433
  }
399
434
 
400
- /** File text, or `{ skipped }` when it is binary or larger than 2 MB (said, never silently dropped). */
435
+ /** File text, or `{ skipped }` when it is binary or larger than 2 MB (said, never silently dropped); `failed: true` when the read itself failed. */
401
436
  export function readText(abs) {
402
437
  try {
403
438
  if (lstatSync(abs).size > 2 * 1024 * 1024) return { skipped: 'larger than 2 MB' };
@@ -405,7 +440,7 @@ export function readText(abs) {
405
440
  if (buf.subarray(0, 8000).includes(0)) return { skipped: 'binary', quiet: true };
406
441
  return { text: buf.toString('utf8').replace(/^\uFEFF/, '') };
407
442
  } catch (e) {
408
- return { skipped: `unreadable (${e.code || e.message})` };
443
+ return { skipped: `unreadable (${e.code || e.message})`, failed: true };
409
444
  }
410
445
  }
411
446
 
@@ -1055,6 +1090,65 @@ export const INDEPENDENCE_DETECTORS = Object.freeze({
1055
1090
  find: (family, ncBody, nsBody, testName) => (family === 'js' ? findNonIndependentExpectations(ncBody, nsBody, testName) : [])
1056
1091
  });
1057
1092
 
1093
+ // ═══════════════════════════════════════════════════════════════════════════
1094
+ // One test, exempted with a reason (XSPEC-518 R3)
1095
+ //
1096
+ // A comment `ANTI_FAKE_EXEMPT: <reason>` exempts the ONE test it is attached to from no-assertion /
1097
+ // tautology. "Attached" means: the comment is on the test's own line, or it is in the block of
1098
+ // comment lines (annotation / decorator lines may sit between) that ends on the line right above the
1099
+ // test. A blank line or any code between the comment and the test breaks the attachment, so a marker
1100
+ // inside the previous test, or one test further up, reaches nothing. If two tests start on one line the
1101
+ // marker is ambiguous and exempts neither.
1102
+ //
1103
+ // The reason is the point. It is the text after the colon, on the marker's own line, and it must be
1104
+ // usable: at least MIN_REASON_CHARS letters, digits or Chinese characters once placeholder words
1105
+ // (TODO, TBD, FIXME, XXX, WIP, N/A, 待補 ...) are taken out. A marker whose reason is empty, a
1106
+ // placeholder or too short does nothing, and the finding says so. An exempted test is still LISTED
1107
+ // (`exempted` in --json, a line in the report) so an exemption is never invisible. The marker is only
1108
+ // honored inside a comment — the same words in a string are text, not a decision.
1109
+ // ═══════════════════════════════════════════════════════════════════════════
1110
+
1111
+ const EXEMPT_MARKER = /ANTI_FAKE_EXEMPT\b[ \t]*:?[ \t]*([^\n]*)/g;
1112
+ export const MIN_REASON_CHARS = 8;
1113
+ const PLACEHOLDER_REASON = /\b(?:todo|tbd|fixme|xxx|wip|n\/a|na)\b|待補|待辦|待定|暫時|以後再說/giu;
1114
+ const NO_USABLE_REASON = `an ANTI_FAKE_EXEMPT comment is there but gives no usable reason (at least ${MIN_REASON_CHARS} letters, digits or Chinese characters that are not a placeholder such as TODO), so it is not honored`;
1115
+
1116
+ /** Is this text a reason? */
1117
+ export function isUsableReason(reason) {
1118
+ const kept = String(reason).replace(PLACEHOLDER_REASON, ' ').match(/[\p{L}\p{N}]/gu) || [];
1119
+ return kept.length >= MIN_REASON_CHARS;
1120
+ }
1121
+
1122
+ /**
1123
+ * The exemption attached to the test that starts on line `caseLine` (1-based), or null.
1124
+ * @returns {{ reason: string }|{ reason: null }|null} `reason: null` = a marker is attached but its reason is not usable
1125
+ */
1126
+ function exemptionFor(textLines, ncLines, caseLine, casesOnLine) {
1127
+ if (casesOnLine.get(caseLine) !== 1) return null;
1128
+ const commentLines = [caseLine]; // the own line is searched for a trailing comment
1129
+ for (let n = caseLine - 1; n >= 1; n--) {
1130
+ const t = textLines[n - 1].trim();
1131
+ const code = ncLines[n - 1].trim();
1132
+ if (t !== '' && code === '') { commentLines.push(n); continue; } // a comment-only line
1133
+ if (/^(?:@|#\[|\[)/.test(code)) continue; // an annotation / decorator between the comment and the test
1134
+ break; // blank, or code: the block above ends here
1135
+ }
1136
+ let found = null;
1137
+ for (const n of commentLines) {
1138
+ const line = textLines[n - 1];
1139
+ const nc = ncLines[n - 1];
1140
+ EXEMPT_MARKER.lastIndex = 0;
1141
+ let m;
1142
+ while ((m = EXEMPT_MARKER.exec(line)) !== null) {
1143
+ if (nc[m.index] !== ' ' || line[m.index] === ' ') continue; // not inside a comment
1144
+ const reason = m[1].replace(/\*\/\s*$/, '').trim();
1145
+ if (isUsableReason(reason)) return { reason };
1146
+ found = { reason: null };
1147
+ }
1148
+ }
1149
+ return found;
1150
+ }
1151
+
1058
1152
  const FORM_DETAIL = {
1059
1153
  'same-call': 'the expected value is the same call as the code under test (same function, same arguments)',
1060
1154
  recomputed: 'the expected value is recomputed from the same input as the code under test (reduce/map/filter with a callback that uses only its own parameters), so it is not an independent oracle'
@@ -1063,16 +1157,22 @@ const FORM_DETAIL = {
1063
1157
  /**
1064
1158
  * Analyze one test file's text.
1065
1159
  * @returns {{ family: string|null, cases: number, skipped: number, unparsed: number,
1066
- * findings: { rule: string, line: number|null, name: string, detail: string }[] }}
1160
+ * findings: { rule: string, line: number|null, name: string, detail: string }[],
1161
+ * exempted: { rule: string, line: number, name: string, reason: string }[] }}
1067
1162
  */
1068
1163
  export function analyzeTestText(text, ext, extraAssertion = [], detectors = INDEPENDENCE_DETECTORS) {
1069
1164
  const family = FAMILY_BY_EXT[ext] || null;
1070
1165
  const rules = family && FAMILY_RULES[family];
1071
- if (!rules) return { family: null, cases: 0, skipped: 0, unparsed: 0, findings: [] };
1166
+ if (!rules) return { family: null, cases: 0, skipped: 0, unparsed: 0, findings: [], exempted: [] };
1072
1167
  const { noComments, noStrings } = maskSource(text, family);
1073
1168
  const { cases, unparsed } = rules.find(text, noStrings, noComments, ext);
1074
1169
  const lineOf = lineIndex(text);
1075
1170
  const findings = [];
1171
+ const exempted = [];
1172
+ const textLines = text.split('\n');
1173
+ const ncLines = noComments.split('\n');
1174
+ const casesOnLine = new Map();
1175
+ for (const c of cases) casesOnLine.set(lineOf(c.idx), (casesOnLine.get(lineOf(c.idx)) || 0) + 1);
1076
1176
  let skipped = 0;
1077
1177
  for (const c of cases) {
1078
1178
  if (c.skipped) { skipped++; continue; }
@@ -1086,17 +1186,23 @@ export function analyzeTestText(text, ext, extraAssertion = [], detectors = INDE
1086
1186
  taut += detectors.count(family, ncBody, nsBody, c.name);
1087
1187
  const real = Math.max(0, tokens - taut) + c.credit;
1088
1188
  if (real > 0) continue;
1189
+ const exemption = exemptionFor(textLines, ncLines, lineOf(c.idx), casesOnLine);
1190
+ if (exemption && exemption.reason) {
1191
+ exempted.push({ rule: taut === 0 ? 'no-assertion' : 'tautology', line: lineOf(c.idx), name: c.name, reason: exemption.reason });
1192
+ continue;
1193
+ }
1194
+ const noReason = exemption ? ` (${NO_USABLE_REASON})` : '';
1089
1195
  if (taut === 0) {
1090
- findings.push({ rule: 'no-assertion', line: lineOf(c.idx), name: c.name, detail: 'the body contains nothing that can fail an assertion' });
1196
+ findings.push({ rule: 'no-assertion', line: lineOf(c.idx), name: c.name, detail: `the body contains nothing that can fail an assertion${noReason}` });
1091
1197
  continue;
1092
1198
  }
1093
1199
  const hits = detectors.find(family, ncBody, nsBody, c.name);
1094
1200
  const forms = [...new Set(hits.map((h) => h.form))];
1095
- const finding = { rule: 'tautology', line: lineOf(c.idx), name: c.name, detail: 'its only assertion(s) can never fail' };
1201
+ const finding = { rule: 'tautology', line: lineOf(c.idx), name: c.name, detail: `its only assertion(s) can never fail${noReason}` };
1096
1202
  if (forms.length > 0) {
1097
1203
  const parts = forms.map((f) => FORM_DETAIL[f]);
1098
1204
  if (regexTaut > 0) parts.unshift('an assertion that can never fail');
1099
- finding.detail = `its only assertion(s) are not independent of the code under test: ${parts.join('; ')} (see verification-oracle)`;
1205
+ finding.detail = `its only assertion(s) are not independent of the code under test: ${parts.join('; ')} (see verification-oracle)${noReason}`;
1100
1206
  finding.forms = forms;
1101
1207
  finding.assertions = hits.map((h) => ({ line: lineOf(c.bodyStart + h.offset), form: h.form }));
1102
1208
  }
@@ -1105,7 +1211,7 @@ export function analyzeTestText(text, ext, extraAssertion = [], detectors = INDE
1105
1211
  if (cases.length > 0 && skipped === cases.length) {
1106
1212
  findings.push({ rule: 'all-skipped', line: null, name: '(file)', detail: `every test in this file is skipped or todo (${skipped})` });
1107
1213
  }
1108
- return { family, cases: cases.length, skipped, unparsed, findings };
1214
+ return { family, cases: cases.length, skipped, unparsed, findings, exempted };
1109
1215
  }
1110
1216
 
1111
1217
  // ═══════════════════════════════════════════════════════════════════════════
@@ -1160,6 +1266,15 @@ const SELF_TEST = [
1160
1266
  { ext: 'js', rules: ['tautology'], text: "it('destructured reduce', () => { expect(calculateTotal(items)).toBe(items.reduce((s, { price }) => s + price, 0)); });\n" },
1161
1267
  { ext: 'js', rules: ['tautology'], text: "it('function expression', () => { expect(calculateTotal(items)).toBe(items.reduce(function (s, i) { return s + i.price; }, 0)); });\n" },
1162
1268
  { ext: 'js', rules: ['tautology'], text: "it('block arrow', () => { expect(calculateTotal(items)).toBe(items.reduce((s, i) => { return s + i.qty * i.price; }, 0)); });\n" },
1269
+ // XSPEC-518 R3: one test exempted with a reason; the same marker without a reason, or inside a string, exempts nothing.
1270
+ { ext: 'js', rules: [], text: "// ANTI_FAKE_EXEMPT: the hook only has to not throw on this platform\nit('hook runs', () => { runHook(); });\n" },
1271
+ { ext: 'js', rules: ['no-assertion'], text: "// ANTI_FAKE_EXEMPT:\nit('hook runs', () => { runHook(); });\n" },
1272
+ { ext: 'js', rules: ['no-assertion'], text: "const note = 'ANTI_FAKE_EXEMPT: not a comment';\nit('hook runs', () => { runHook(); });\n" },
1273
+ { ext: 'js', rules: ['no-assertion'], text: "// ANTI_FAKE_EXEMPT: covers only the next test\nit('a', () => { runHook(); });\nit('b', () => { runHook(); });\n" },
1274
+ { ext: 'js', rules: ['no-assertion'], text: "// ANTI_FAKE_EXEMPT: x\nit('hook runs', () => { runHook(); });\n" },
1275
+ { ext: 'js', rules: ['no-assertion'], text: "// ANTI_FAKE_EXEMPT: TODO\nit('hook runs', () => { runHook(); });\n" },
1276
+ { ext: 'js', rules: ['no-assertion', 'no-assertion'], text: "it('a', () => {\n runHook(); // ANTI_FAKE_EXEMPT: smoke test of the first hook\n});\nit('b', () => { runHook(); });\n" },
1277
+ { ext: 'js', rules: ['no-assertion', 'no-assertion'], text: "it('a', () => { runHook(); }); it('b', () => { runHook(); }); // ANTI_FAKE_EXEMPT: smoke tests of the hook\n" },
1163
1278
  { ext: 'py', rules: ['no-assertion'], text: "def test_nothing():\n x = 1\n pass\n" },
1164
1279
  { ext: 'py', rules: ['tautology'], text: "def test_true():\n assert True\n" },
1165
1280
  { ext: 'py', rules: [], text: "def test_ok():\n assert add(1, 2) == 3\n\n\ndef test_raises():\n with pytest.raises(ValueError):\n f()\n" },
@@ -1214,21 +1329,27 @@ function readAssertionPatterns(root) {
1214
1329
  // Directories under a test tree that hold data, not tests.
1215
1330
  const FIXTURE_DIRS = new Set(['fixtures', 'fixture', '__fixtures__', '__snapshots__', 'snapshots', 'testdata', '__mocks__']);
1216
1331
 
1217
- export function scan(root, { staged = false } = {}) {
1332
+ export function scan(root, { staged = false, maxFiles = WALK_LIMIT } = {}) {
1218
1333
  const { policy, problems } = loadPolicy(root);
1219
1334
  const extra = readAssertionPatterns(root);
1220
1335
  problems.push(...extra.problems);
1221
1336
  let files;
1337
+ let truncated = false;
1338
+ let unreadableDirs = [];
1222
1339
  if (staged) {
1223
1340
  const s = stagedFiles(root);
1224
1341
  if (s.error) return { error: `cannot read the staged files: ${s.error}`, problems };
1225
1342
  files = s.files;
1226
1343
  } else {
1227
- files = walkFiles(root, policy);
1344
+ const w = walkFilesChecked(root, policy, maxFiles);
1345
+ files = w.files;
1346
+ truncated = w.truncated;
1347
+ unreadableDirs = w.unreadable;
1228
1348
  }
1229
1349
  const result = {
1230
- mode: staged ? 'staged' : 'all', problems, testFiles: 0, cases: 0, skippedCases: 0, unparsed: 0,
1231
- findings: [], unsupported: [], unreadable: []
1350
+ mode: staged ? 'staged' : 'all', problems, incomplete: false, truncated, walkLimit: staged ? null : maxFiles, unreadableDirs,
1351
+ testFiles: 0, cases: 0, skippedCases: 0, unparsed: 0,
1352
+ findings: [], exempted: [], unsupported: [], unreadable: [], readFailures: 0
1232
1353
  };
1233
1354
  for (const rel of files) {
1234
1355
  if (classifyPath(rel, policy).kind !== 'test') continue;
@@ -1242,14 +1363,22 @@ export function scan(root, { staged = false } = {}) {
1242
1363
  continue;
1243
1364
  }
1244
1365
  const r = readText(join(root, rel));
1245
- if (r.skipped) { if (!r.quiet) result.unreadable.push(`${rel} (${r.skipped})`); continue; }
1366
+ if (r.skipped) {
1367
+ if (!r.quiet) result.unreadable.push(`${rel} (${r.skipped})`);
1368
+ if (r.failed) result.readFailures++;
1369
+ continue;
1370
+ }
1246
1371
  const a = analyzeTestText(r.text, ext, extra.patterns);
1247
1372
  result.testFiles++;
1248
1373
  result.cases += a.cases;
1249
1374
  result.skippedCases += a.skipped;
1250
1375
  result.unparsed += a.unparsed;
1251
1376
  for (const f of a.findings) result.findings.push({ file: rel, ...f });
1377
+ for (const x of a.exempted) result.exempted.push({ file: rel, ...x });
1252
1378
  }
1379
+ // Not the whole project, or a file that could not be read: what was not seen is not clean (a test file
1380
+ // skipped for being over 2 MB is listed under "NOT scanned", like an unsupported language, and is not counted here).
1381
+ result.incomplete = result.truncated || result.unreadableDirs.length > 0 || result.readFailures > 0;
1253
1382
  return result;
1254
1383
  }
1255
1384
 
@@ -1260,6 +1389,10 @@ function report(r) {
1260
1389
  for (const f of r.findings) {
1261
1390
  out.push(` ✗ ${f.file}${f.line ? `:${f.line}` : ''} ${f.rule} "${f.name}" — ${f.detail}`);
1262
1391
  }
1392
+ if (r.exempted.length > 0) {
1393
+ out.push(` · ${r.exempted.length} test(s) exempted by an ANTI_FAKE_EXEMPT comment with a reason (not judged):`);
1394
+ for (const x of r.exempted) out.push(` ${x.file}:${x.line} "${x.name}" — ${x.reason}`);
1395
+ }
1263
1396
  if (r.unsupported.length > 0) {
1264
1397
  const exts = [...new Set(r.unsupported.map((p) => `.${extOfPath(p) || '(none)'}`))].join(', ');
1265
1398
  out.push(` · NOT scanned — no rule for this language (${exts}): ${r.unsupported.slice(0, 5).join(', ')}${r.unsupported.length > 5 ? `, +${r.unsupported.length - 5} more` : ''}`);
@@ -1268,10 +1401,30 @@ function report(r) {
1268
1401
  for (const u of r.unreadable) out.push(` · NOT scanned — ${u}`);
1269
1402
  if (r.unparsed > 0) out.push(` · ${r.unparsed} test call(s) could not be parsed (unbalanced brackets) and were not judged`);
1270
1403
  if (r.testFiles === 0 && r.unsupported.length === 0 && r.mode === 'all') out.push(' · no test files found — nothing was measured');
1271
- out.push(r.findings.length > 0 ? `RESULT: ${r.findings.length} finding(s)` : 'RESULT: no fake tests found among the files scanned');
1404
+ if (r.truncated) {
1405
+ out.push(` ! INCOMPLETE — the walk stopped after ${r.walkLimit} files and more were left unread. The files above are NOT the whole project; fake tests in the unread part would not be found.`);
1406
+ }
1407
+ if (r.unreadableDirs.length > 0) {
1408
+ out.push(` ! INCOMPLETE — ${r.unreadableDirs.length} director${r.unreadableDirs.length === 1 ? 'y' : 'ies'} could not be opened, so what is inside was not scanned: ${r.unreadableDirs.slice(0, 5).join(', ')}${r.unreadableDirs.length > 5 ? `, +${r.unreadableDirs.length - 5} more` : ''}`);
1409
+ }
1410
+ if (r.readFailures > 0) {
1411
+ out.push(` ! INCOMPLETE — ${r.readFailures} test file(s) could not be read (listed above under "NOT scanned"); fake tests in them would not be found.`);
1412
+ }
1413
+ if (r.findings.length > 0) out.push(`RESULT: ${r.findings.length} finding(s)${r.incomplete ? ' — and the search was INCOMPLETE' : ''}`);
1414
+ else if (r.incomplete) out.push('RESULT: INCOMPLETE — the search did not cover everything it should have, so this is NOT a pass');
1415
+ else out.push('RESULT: no fake tests found among the files scanned');
1272
1416
  return out.join('\n');
1273
1417
  }
1274
1418
 
1419
+ /** `--max-files N` lowers the walk limit (to try the incomplete-search path, or to cap a huge tree). */
1420
+ function maxFilesFrom(argv) {
1421
+ const i = argv.findIndex((a) => a === '--max-files' || a.startsWith('--max-files='));
1422
+ if (i === -1) return {};
1423
+ const raw = argv[i].includes('=') ? argv[i].split('=')[1] : argv[i + 1];
1424
+ if (!/^[1-9]\d*$/.test(String(raw))) return { error: `--max-files needs a positive whole number, got ${JSON.stringify(raw)}` };
1425
+ return { value: Number(raw) };
1426
+ }
1427
+
1275
1428
  export function main(argv, root = process.cwd()) {
1276
1429
  const bad = selfTest();
1277
1430
  if (bad.length > 0) {
@@ -1279,13 +1432,20 @@ export function main(argv, root = process.cwd()) {
1279
1432
  for (const b of bad) console.error(` ${b}`);
1280
1433
  return 2;
1281
1434
  }
1282
- const r = scan(root, { staged: argv.includes('--staged') });
1435
+ const limit = maxFilesFrom(argv);
1436
+ if (limit.error) {
1437
+ console.error(`check-anti-fake-tests: ${limit.error}`);
1438
+ return 2;
1439
+ }
1440
+ const r = scan(root, { staged: argv.includes('--staged'), ...(limit.value === undefined ? {} : { maxFiles: limit.value }) });
1283
1441
  if (r.error) {
1284
1442
  console.error(`check-anti-fake-tests: ${r.error}`);
1285
1443
  return 2;
1286
1444
  }
1287
1445
  console.log(argv.includes('--json') ? JSON.stringify(r, null, 2) : report(r));
1288
- return r.findings.length > 0 ? 1 : 0;
1446
+ // A search that did not cover the project is "could not judge" (2), never a pass; findings still win (1).
1447
+ if (r.findings.length > 0) return 1;
1448
+ return r.incomplete ? 2 : 0;
1289
1449
  }
1290
1450
 
1291
1451
  if (isMain(import.meta.url)) process.exitCode = main(process.argv.slice(2));
@@ -27,7 +27,9 @@
27
27
  // node scripts/check-stubs.mjs --json machine-readable result
28
28
  //
29
29
  // Exit codes: 0 nothing found | 1 findings | 2 could not judge (the scanner's own
30
- // self-test failed, or git was unreadable in --staged mode). 2 is never a pass.
30
+ // self-test failed, git was unreadable in --staged mode, or the search was INCOMPLETE — the
31
+ // walk hit its file limit (`--max-files N`, default 200000), a directory could not be opened,
32
+ // or a file could not be read — and it found nothing in the part it did see). 2 is never a pass.
31
33
  //
32
34
  // Marker rule: a placeholder is DECLARED when the text `STUB` or `COVERAGE_EXEMPT` is on
33
35
  // the same line or in the three lines above it. A declared placeholder is reported once, as
@@ -369,22 +371,48 @@ export function lineIndex(text) {
369
371
  };
370
372
  }
371
373
 
372
- /** Every project-relative file under `root`, skipping the policy's ignored directories and symlinks. */
373
- export function walkFiles(root, policy) {
374
+ /** The most files one walk will list; the next file after that makes the walk "truncated". */
375
+ export const WALK_LIMIT = 200000;
376
+
377
+ /**
378
+ * Every project-relative file under `root`, skipping the policy's ignored directories and symlinks.
379
+ * At most `limit` files are listed (a hard limit, not a hint). The list is NOT the whole project when
380
+ * - `truncated` is true: there was at least one more file after the `limit`th, or
381
+ * - `unreadable` is not empty: a directory could not be opened, so what is in it is unknown.
382
+ * A caller must say so (XSPEC-518 R2): a short list is not a clean project. Directories are read in
383
+ * name order, so which part is left unread does not depend on the file system.
384
+ * @returns {{ files: string[], truncated: boolean, unreadable: string[] }}
385
+ */
386
+ export function walkFilesChecked(root, policy, limit = WALK_LIMIT) {
374
387
  const skip = new Set(policy.ignoreDirs);
375
388
  const out = [];
389
+ const unreadable = [];
376
390
  const stack = [''];
377
- while (stack.length > 0 && out.length < 200000) {
391
+ let truncated = false;
392
+ while (stack.length > 0 && !truncated) {
378
393
  const rel = stack.pop();
379
394
  let entries;
380
- try { entries = readdirSync(join(root, rel), { withFileTypes: true }); } catch { continue; }
395
+ try {
396
+ entries = readdirSync(join(root, rel), { withFileTypes: true }).sort((x, y) => (x.name < y.name ? -1 : x.name > y.name ? 1 : 0));
397
+ } catch (e) {
398
+ unreadable.push(`${rel || '.'} (${e.code || e.message})`);
399
+ continue;
400
+ }
381
401
  for (const e of entries) {
382
402
  const r = rel ? `${rel}/${e.name}` : e.name;
383
403
  if (e.isSymbolicLink()) continue;
384
- if (e.isDirectory()) { if (!skip.has(e.name)) stack.push(r); } else if (e.isFile()) out.push(r);
404
+ if (e.isDirectory()) { if (!skip.has(e.name)) stack.push(r); } else if (e.isFile()) {
405
+ if (out.length >= limit) { truncated = true; break; }
406
+ out.push(r);
407
+ }
385
408
  }
386
409
  }
387
- return out.sort();
410
+ return { files: out.sort(), truncated, unreadable };
411
+ }
412
+
413
+ /** The file list alone (see walkFilesChecked for whether it is the whole project). */
414
+ export function walkFiles(root, policy, limit = WALK_LIMIT) {
415
+ return walkFilesChecked(root, policy, limit).files;
388
416
  }
389
417
 
390
418
  /** Files staged for the next commit (added, copied, modified, renamed), or `{ error }`. */
@@ -399,7 +427,7 @@ export function stagedFiles(root) {
399
427
  }
400
428
  }
401
429
 
402
- /** File text, or `{ skipped }` when it is binary or larger than 2 MB (said, never silently dropped). */
430
+ /** File text, or `{ skipped }` when it is binary or larger than 2 MB (said, never silently dropped); `failed: true` when the read itself failed. */
403
431
  export function readText(abs) {
404
432
  try {
405
433
  if (lstatSync(abs).size > 2 * 1024 * 1024) return { skipped: 'larger than 2 MB' };
@@ -407,7 +435,7 @@ export function readText(abs) {
407
435
  if (buf.subarray(0, 8000).includes(0)) return { skipped: 'binary', quiet: true };
408
436
  return { text: buf.toString('utf8').replace(/^\uFEFF/, '') };
409
437
  } catch (e) {
410
- return { skipped: `unreadable (${e.code || e.message})` };
438
+ return { skipped: `unreadable (${e.code || e.message})`, failed: true };
411
439
  }
412
440
  }
413
441
 
@@ -585,30 +613,44 @@ export function selfTest() {
585
613
  const SELF = (() => { try { return realpathSync(fileURLToPath(import.meta.url)); } catch { return null; } })();
586
614
  const isSelf = (abs) => { try { return SELF !== null && realpathSync(abs) === SELF; } catch { return false; } };
587
615
 
588
- export function scan(root, { staged = false } = {}) {
616
+ export function scan(root, { staged = false, maxFiles = WALK_LIMIT } = {}) {
589
617
  const { policy, problems } = loadPolicy(root);
590
618
  let files;
619
+ let truncated = false;
620
+ let unreadableDirs = [];
591
621
  if (staged) {
592
622
  const s = stagedFiles(root);
593
623
  if (s.error) return { error: `cannot read the staged files: ${s.error}`, problems };
594
624
  files = s.files;
595
625
  } else {
596
- files = walkFiles(root, policy);
626
+ const w = walkFilesChecked(root, policy, maxFiles);
627
+ files = w.files;
628
+ truncated = w.truncated;
629
+ unreadableDirs = w.unreadable;
597
630
  }
598
- const result = { mode: staged ? 'staged' : 'all', problems, files: 0, findings: [], noEmptyRule: new Set(), unreadable: [] };
631
+ const result = {
632
+ mode: staged ? 'staged' : 'all', problems, incomplete: false, truncated, walkLimit: staged ? null : maxFiles, unreadableDirs,
633
+ files: 0, findings: [], noEmptyRule: new Set(), unreadable: [], readFailures: 0
634
+ };
599
635
  for (const rel of files) {
600
636
  const kind = classifyPath(rel, policy).kind;
601
637
  if (kind !== 'source' && kind !== 'unclassified') continue;
602
638
  if (isSelf(join(root, rel))) continue;
603
639
  const ext = extOfPath(rel);
604
640
  const r = readText(join(root, rel));
605
- if (r.skipped) { if (!r.quiet) result.unreadable.push(`${rel} (${r.skipped})`); continue; }
641
+ if (r.skipped) {
642
+ if (!r.quiet) result.unreadable.push(`${rel} (${r.skipped})`);
643
+ if (r.failed) result.readFailures++;
644
+ continue;
645
+ }
606
646
  const a = analyzeStubText(r.text, ext);
607
647
  result.files++;
608
648
  if (!a.emptyRule) result.noEmptyRule.add(ext ? `.${ext}` : '(no extension)');
609
649
  for (const f of a.findings) result.findings.push({ file: rel, ...f });
610
650
  }
611
651
  result.noEmptyRule = [...result.noEmptyRule].sort();
652
+ // Not the whole project, or a file that could not be read: what was not seen is not clean.
653
+ result.incomplete = result.truncated || result.unreadableDirs.length > 0 || result.readFailures > 0;
612
654
  return result;
613
655
  }
614
656
 
@@ -621,10 +663,30 @@ function report(r) {
621
663
  out.push(` · empty-function scan has no rule for: ${r.noEmptyRule.join(' ')} (markers and "not implemented" bodies were still searched)`);
622
664
  }
623
665
  for (const u of r.unreadable) out.push(` · NOT scanned — ${u}`);
624
- out.push(r.findings.length > 0 ? `RESULT: ${r.findings.length} finding(s)` : 'RESULT: no stubs found among the files scanned');
666
+ if (r.truncated) {
667
+ out.push(` ! INCOMPLETE — the walk stopped after ${r.walkLimit} files and more were left unread. The files above are NOT the whole project; stubs in the unread part would not be found.`);
668
+ }
669
+ if (r.unreadableDirs.length > 0) {
670
+ out.push(` ! INCOMPLETE — ${r.unreadableDirs.length} director${r.unreadableDirs.length === 1 ? 'y' : 'ies'} could not be opened, so what is inside was not scanned: ${r.unreadableDirs.slice(0, 5).join(', ')}${r.unreadableDirs.length > 5 ? `, +${r.unreadableDirs.length - 5} more` : ''}`);
671
+ }
672
+ if (r.readFailures > 0) {
673
+ out.push(` ! INCOMPLETE — ${r.readFailures} source file(s) could not be read (listed above under "NOT scanned"); stubs in them would not be found.`);
674
+ }
675
+ if (r.findings.length > 0) out.push(`RESULT: ${r.findings.length} finding(s)${r.incomplete ? ' — and the search was INCOMPLETE' : ''}`);
676
+ else if (r.incomplete) out.push('RESULT: INCOMPLETE — the search did not cover everything it should have, so this is NOT a pass');
677
+ else out.push('RESULT: no stubs found among the files scanned');
625
678
  return out.join('\n');
626
679
  }
627
680
 
681
+ /** `--max-files N` lowers the walk limit (to try the incomplete-search path, or to cap a huge tree). */
682
+ function maxFilesFrom(argv) {
683
+ const i = argv.findIndex((a) => a === '--max-files' || a.startsWith('--max-files='));
684
+ if (i === -1) return {};
685
+ const raw = argv[i].includes('=') ? argv[i].split('=')[1] : argv[i + 1];
686
+ if (!/^[1-9]\d*$/.test(String(raw))) return { error: `--max-files needs a positive whole number, got ${JSON.stringify(raw)}` };
687
+ return { value: Number(raw) };
688
+ }
689
+
628
690
  export function main(argv, root = process.cwd()) {
629
691
  const bad = selfTest();
630
692
  if (bad.length > 0) {
@@ -632,13 +694,20 @@ export function main(argv, root = process.cwd()) {
632
694
  for (const b of bad) console.error(` ${b}`);
633
695
  return 2;
634
696
  }
635
- const r = scan(root, { staged: argv.includes('--staged') });
697
+ const limit = maxFilesFrom(argv);
698
+ if (limit.error) {
699
+ console.error(`check-stubs: ${limit.error}`);
700
+ return 2;
701
+ }
702
+ const r = scan(root, { staged: argv.includes('--staged'), ...(limit.value === undefined ? {} : { maxFiles: limit.value }) });
636
703
  if (r.error) {
637
704
  console.error(`check-stubs: ${r.error}`);
638
705
  return 2;
639
706
  }
640
707
  console.log(argv.includes('--json') ? JSON.stringify(r, null, 2) : report(r));
641
- return r.findings.length > 0 ? 1 : 0;
708
+ // A search that did not cover the project is "could not judge" (2), never a pass; findings still win (1).
709
+ if (r.findings.length > 0) return 1;
710
+ return r.incomplete ? 2 : 0;
642
711
  }
643
712
 
644
713
  if (isMain(import.meta.url)) process.exitCode = main(process.argv.slice(2));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "universal-dev-standards",
3
- "version": "6.14.1",
3
+ "version": "6.15.0-beta.2",
4
4
  "description": "CLI tool for adopting Universal Development Standards",
5
5
  "keywords": [
6
6
  "documentation",
@@ -75,7 +75,7 @@
75
75
  "devDependencies": {
76
76
  "@eslint/js": "^10.0.1",
77
77
  "@vitest/coverage-v8": "^5.0.0",
78
- "eslint": "10.12.0",
78
+ "eslint": "10.13.0",
79
79
  "globals": "17.13.0",
80
80
  "husky": "^9.1.7",
81
81
  "lint-staged": "^17.0.3",
@@ -24,6 +24,7 @@ import {
24
24
  DEFAULT_BASELINE_PATH
25
25
  } from '../utils/effect-boundary.js';
26
26
  import { readManifest, isInitialized } from '../utils/copier.js';
27
+ import { flushAndExit } from '../utils/flush-and-exit.js';
27
28
  import { runHealthCheck } from '../utils/health-checker.js';
28
29
  import { runHealthScore, saveScoreSnapshot, loadTrend } from '../utils/health-scorer.js';
29
30
  import { analyzePatterns } from '../utils/pattern-analyzer.js';
@@ -219,7 +220,9 @@ function handleEffectsMode(projectPath, options) {
219
220
  } else {
220
221
  for (const line of lines) console.log(line);
221
222
  }
222
- process.exit(exitCode);
223
+ // Board #81: the report grows with the findings and the exit code is the gate's answer; process.exit() alone can cut
224
+ // the report (or a --format json document) at one pipe's worth of output on macOS. Wait for it to be taken first.
225
+ return flushAndExit(exitCode); // wire:audit-effects-flushes-before-exit
223
226
  }
224
227
 
225
228
  /**