universal-dev-standards 6.14.1-beta.2 → 6.15.0-beta.1
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.
- package/bin/uds.js +2 -2
- package/bundled/ai/standards/developer-memory.ai.yaml +2 -2
- package/bundled/ai/standards/full-coverage-testing.ai.yaml +6 -4
- package/bundled/ai/standards/project-context-memory.ai.yaml +2 -2
- package/bundled/core/developer-memory.md +1 -1
- package/bundled/core/full-coverage-testing.md +4 -2
- package/bundled/core/open-work-tracking.md +13 -0
- package/bundled/core/project-context-memory.md +1 -1
- package/bundled/locales/COVERAGE.md +5 -4
- package/bundled/locales/zh-CN/CHANGELOG.md +53 -4
- package/bundled/locales/zh-CN/README.md +2 -2
- package/bundled/locales/zh-CN/SECURITY.md +3 -3
- package/bundled/locales/zh-CN/core/full-coverage-testing.md +5 -3
- package/bundled/locales/zh-CN/docs/AVAILABLE-STANDARDS.md +4 -4
- package/bundled/locales/zh-CN/docs/CHEATSHEET.md +1 -0
- package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +8 -3
- package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +5 -4
- package/bundled/locales/zh-CN/skills/README.md +2 -1
- package/bundled/locales/zh-CN/skills/commands/sdd-retro.md +1 -1
- package/bundled/locales/zh-CN/skills/dev-workflow-guide/SKILL.md +7 -7
- package/bundled/locales/zh-CN/skills/open-work-assistant/SKILL.md +133 -0
- package/bundled/locales/zh-TW/CHANGELOG.md +53 -4
- package/bundled/locales/zh-TW/README.md +2 -2
- package/bundled/locales/zh-TW/SECURITY.md +3 -3
- package/bundled/locales/zh-TW/core/developer-memory.md +3 -3
- package/bundled/locales/zh-TW/core/full-coverage-testing.md +5 -3
- package/bundled/locales/zh-TW/core/open-work-tracking.md +13 -2
- package/bundled/locales/zh-TW/core/project-context-memory.md +3 -3
- package/bundled/locales/zh-TW/docs/AVAILABLE-STANDARDS.md +4 -4
- package/bundled/locales/zh-TW/docs/CHEATSHEET.md +1 -0
- package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +8 -3
- package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +5 -4
- package/bundled/locales/zh-TW/skills/README.md +2 -1
- package/bundled/locales/zh-TW/skills/dev-workflow-guide/SKILL.md +7 -7
- package/bundled/locales/zh-TW/skills/open-work-assistant/SKILL.md +133 -0
- package/bundled/skills/.claude-plugin/plugin.json +1 -1
- package/bundled/skills/README.md +2 -1
- package/bundled/skills/dev-workflow-guide/SKILL.md +4 -4
- package/bundled/skills/open-work-assistant/SKILL.md +127 -0
- package/bundled/templates/gates/check-anti-fake-tests.mjs +183 -23
- package/bundled/templates/gates/check-stubs.mjs +85 -16
- package/package.json +2 -2
- package/src/commands/audit.js +4 -1
- package/src/commands/check.js +55 -6
- package/src/commands/config.js +2 -3
- package/src/commands/init.js +10 -3
- package/src/commands/update.js +239 -43
- package/src/i18n/messages.js +87 -0
- package/src/installers/hooks-installer.js +32 -5
- package/src/installers/skills-installer.js +45 -0
- package/src/reconciler/backup-locations.js +3 -2
- package/src/reconciler/backup-manager.js +14 -11
- package/src/reconciler/plan-executor.js +51 -7
- package/src/utils/copier.js +13 -8
- package/src/utils/flush-and-exit.js +37 -0
- package/src/utils/group-errors.js +65 -0
- package/src/utils/integration-generator.js +14 -5
- package/src/utils/skill-hash-ownership.js +33 -0
- package/src/utils/skill-link-rewriter.js +184 -0
- package/src/utils/skills-installer.js +115 -11
- package/src/utils/transient-fs.js +168 -14
- package/standards-registry.json +10 -19
- 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
|
-
//
|
|
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
|
-
/**
|
|
371
|
-
export
|
|
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
|
-
|
|
396
|
+
let truncated = false;
|
|
397
|
+
while (stack.length > 0 && !truncated) {
|
|
376
398
|
const rel = stack.pop();
|
|
377
399
|
let entries;
|
|
378
|
-
try {
|
|
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())
|
|
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:
|
|
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:
|
|
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
|
-
|
|
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,
|
|
1231
|
-
|
|
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) {
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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,
|
|
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
|
-
/**
|
|
373
|
-
export
|
|
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
|
-
|
|
391
|
+
let truncated = false;
|
|
392
|
+
while (stack.length > 0 && !truncated) {
|
|
378
393
|
const rel = stack.pop();
|
|
379
394
|
let entries;
|
|
380
|
-
try {
|
|
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())
|
|
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
|
-
|
|
626
|
+
const w = walkFilesChecked(root, policy, maxFiles);
|
|
627
|
+
files = w.files;
|
|
628
|
+
truncated = w.truncated;
|
|
629
|
+
unreadableDirs = w.unreadable;
|
|
597
630
|
}
|
|
598
|
-
const result = {
|
|
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) {
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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.
|
|
3
|
+
"version": "6.15.0-beta.1",
|
|
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.
|
|
78
|
+
"eslint": "10.13.0",
|
|
79
79
|
"globals": "17.13.0",
|
|
80
80
|
"husky": "^9.1.7",
|
|
81
81
|
"lint-staged": "^17.0.3",
|
package/src/commands/audit.js
CHANGED
|
@@ -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(
|
|
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
|
/**
|