dsh-plugin-toolkit 0.20.13 → 0.20.15

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/CHANGELOG.md CHANGED
@@ -1,3 +1,50 @@
1
+ ## 0.20.15
2
+
3
+ - **A strict comparison against a wildcard major matches nothing.** `audit
4
+ --remote <owner/repo> --host <version>` treated `>*`, `>x`, `<*` and `<x` as
5
+ "any version" and called every host compatible, while npm reads them as an
6
+ empty set that no release satisfies. The host-range parser now reports
7
+ `incompatible` for those spellings; the inclusive `>=*` and `<=*` forms still
8
+ span every stable host. Regression tests pin the parser, the printed CLI
9
+ verdict and the `--json` row, including the major-only `>1`/`<=1` boundary:
10
+ `>1` rejects 1.2.3 and `<=1` accepts it, in both the text line and
11
+ `compatibility`.
12
+
13
+ ## 0.20.14
14
+
15
+ - **The `--jobs` benchmark asserts work, not wall-clock speed.** The throughput
16
+ test used to fail whenever the batched run was not at least 25% faster, which
17
+ is noise when the whole measurement is tens of milliseconds on a loaded
18
+ runner. It now checks what batching actually guarantees: the same named
19
+ results and the same number of API requests at `--jobs 1` and the default
20
+ width, no overlap at `--jobs 1`, and real overlap (never above the requested
21
+ width) after batching. The benchmark still prints before/after wall clock and
22
+ the speedup as context, but no assertion depends on them, so a slow machine
23
+ can no longer block the publish gate.
24
+ - **`npm run benchmark -- --latency` reaches the measured run.** The script
25
+ parsed the flag into `latency` while `runBenchmark` reads `latencyMs`, so the
26
+ option was accepted and ignored and every run used the default 500 ms. Both
27
+ names now agree, and a regression test runs the shipped script with
28
+ `--limit 1 --latency 1` and checks the printed delay.
29
+ - **`doctor` reads the root export from code, not from prose.** A root module
30
+ whose only `apply` was inside a comment, string, template or regex literal
31
+ used to pass the `root export` check, while `verify --no-mount` rejected the
32
+ installed package. The check now removes those non-code spans, without
33
+ importing or running the plugin, and accepts only a real exported `apply`:
34
+ `export function apply`, `export const apply = ...`, `export { apply }` and
35
+ the CommonJS `module.exports` forms still pass, while
36
+ `// TODO: export function apply() {}` is a failure. The same helper backs
37
+ `doctor --remote`, so the checkout and the published repository agree.
38
+ - **`doctor` and `verify --no-mount` are pinned to one root-export verdict at
39
+ the process boundary.** A regression test spawns the shipped CLI on the
40
+ comment-only fixture and requires both commands to exit `1`, so the source
41
+ parser and the installed import cannot disagree again. The README and
42
+ `docs/repair.md` now state the exact rule: the resolved root is read as
43
+ source, comments and string/template/regex contents are removed, and only a
44
+ real `export function apply`, `export const apply = ...` (also `let` and
45
+ `var`), `export { apply }` (including aliases), `exports.apply = ...` or
46
+ `module.exports = { apply }` passes.
47
+
1
48
  ## 0.20.13
2
49
 
3
50
  - **The compatibility sample says which snapshot it answers for.** The README
package/README.md CHANGED
@@ -685,6 +685,8 @@ the diff in the terminal.
685
685
  | `files list` | Every path `package.json` points at (`exports`, patch, client) must be covered by `files` |
686
686
  | `root export` | The loader imports the bare package name; if that module is the CLI (or exports no `apply`), the row mounts nothing while the install reports success |
687
687
 
688
+ The `root export` check is a source check, not an install. `doctor` resolves the module the loader imports — `exports["."]` when it is a string or a conditions object (`default`, `import`, `require`, `node`, `module-sync`), otherwise `main` — then removes comments and the contents of string, template and regex literals before looking for a real export. It accepts `export function apply`, `export async function apply`, `export const apply = ...` (also `let` and `var`), `export { apply }` (including `export { helper as apply }`), `exports.apply = ...`, and an `apply` property in `module.exports = { ... }`. A comment such as `// TODO: export function apply() {}` is not an export, and `doctor` never imports or runs the plugin to decide. `verify --no-mount` installs the tarball and imports that same module, so it reaches the same verdict; `npm test` spawns the shipped CLI on the comment-only fixture and requires both commands to exit `1`.
689
+
688
690
  Exit code is `0` when the plugin can be installed and `1` when it cannot, so it drops into CI unchanged. `doctor --remote` and `audit --remote` run the same manifest and README checks (`name`, `version`, `engines.dsh`, `dsh field`, `files list`, `readme`) against the `package.json` and README GitHub serves, then check the files the manifest points at, so a bad package name or a README with no Requirements heading is reported before a clone or install. The `name` check is pinned at the process boundary: `npm test` expects the shipped CLI to reject a missing, empty and malformed name (`accepted=0/3`) and to accept a valid plain or scoped control.
689
691
 
690
692
  ## Repair what `doctor` finds
package/lib/benchmark.mjs CHANGED
@@ -93,7 +93,36 @@ export function createLatencyFetch({
93
93
 
94
94
  const SILENT = { log() {}, error() {} };
95
95
 
96
- /** Time one audit of the whole list at a fixed width. */
96
+ /**
97
+ * Count the work an audit asks the fake GitHub to do. `active` is a request
98
+ * that has started and not answered; `maxInFlight` is the concurrency the
99
+ * audit actually reached, not the width it was given. Unlike wall clock, these
100
+ * counters do not change when the machine is slow or loaded.
101
+ */
102
+ function countRequests(fetchImpl) {
103
+ let active = 0;
104
+ let maxInFlight = 0;
105
+ let requests = 0;
106
+ return {
107
+ fetchImpl: async (url) => {
108
+ requests += 1;
109
+ active += 1;
110
+ maxInFlight = Math.max(maxInFlight, active);
111
+ try {
112
+ return await fetchImpl(url);
113
+ } finally {
114
+ active -= 1;
115
+ }
116
+ },
117
+ stats: () => ({ requests, maxInFlight }),
118
+ };
119
+ }
120
+
121
+ /**
122
+ * Time one audit of the whole list at a fixed width, and count the requests
123
+ * and the concurrency it actually used. The timing is context; the counters
124
+ * are the invariant a benchmark can assert on any machine.
125
+ */
97
126
  export async function measureAuditList({
98
127
  targets,
99
128
  jobs = DEFAULT_JOBS,
@@ -105,22 +134,28 @@ export async function measureAuditList({
105
134
  if (Array.isArray(targets) === false || targets.length === 0) {
106
135
  throw new Error('measureAuditList needs at least one target');
107
136
  }
137
+ const counted = countRequests(fetchImpl);
108
138
  const started = now();
109
- const result = await auditRemoteTargets(targets.join(','), { fetchImpl, jobs, io });
139
+ const result = await auditRemoteTargets(targets.join(','), { fetchImpl: counted.fetchImpl, jobs, io });
110
140
  const elapsedMs = now() - started;
141
+ const { requests, maxInFlight } = counted.stats();
111
142
  return {
112
143
  jobs,
113
144
  targets: targets.length,
114
145
  elapsedMs,
115
146
  secondsPerRepository: elapsedMs / 1000 / targets.length,
147
+ requests,
148
+ maxInFlight,
116
149
  result,
117
150
  };
118
151
  }
119
152
 
120
153
  /**
121
154
  * Run the same named list with one worker (the old loop) and with `jobs`
122
- * workers (the default). The ratio is wall clock, so it includes the cost of
123
- * filling the last partial wave instead of only dividing by the worker count.
155
+ * workers (the default). The reported speedup is wall clock, so it is context,
156
+ * not a guarantee: a loaded machine can make the wider run noisier. The
157
+ * measured work (`requests` and `maxInFlight`) is what batching does guarantee
158
+ * and what tests should assert.
124
159
  */
125
160
  export async function runBenchmark({
126
161
  list = BENCHMARK_LIST,
@@ -163,6 +198,7 @@ export function formatBenchmark(result, { root = ROOT } = {}) {
163
198
  `benchmark: ${result.targets.length} repositories from ${list}, ${result.latencyMs} ms per API request`,
164
199
  ` before --jobs 1 ${(result.before.elapsedMs / 1000).toFixed(2)} s wall ${seconds(result.before.secondsPerRepository)}/repository`,
165
200
  ` after --jobs ${String(result.after.jobs).padEnd(10)} ${(result.after.elapsedMs / 1000).toFixed(2)} s wall ${seconds(result.after.secondsPerRepository)}/repository (default)`,
166
- ` speedup ${result.speedup.toFixed(2)}x`,
201
+ ` requests ${result.before.requests} before, ${result.after.requests} after max in flight ${result.before.maxInFlight} before, ${result.after.maxInFlight} after`,
202
+ ` speedup ${result.speedup.toFixed(2)}x (wall clock, context only)`,
167
203
  ].join('\n');
168
204
  }
package/lib/compat.mjs CHANGED
@@ -120,6 +120,21 @@ function comparator(op, version) {
120
120
  return { op, version };
121
121
  }
122
122
 
123
+ /**
124
+ * A comparator set no version can satisfy. npm reads a strict comparison
125
+ * against a wildcard major (`>*`, `<*`, `>x`, `<x`) as `<0.0.0-0`: there is no
126
+ * boundary to start from, so the set is empty rather than unconstrained. An
127
+ * empty comparator array would mean "any version", which is the opposite
128
+ * answer and would call every host compatible.
129
+ *
130
+ * `<0.0.0` is enough to match nothing here: the parser only accepts versions at
131
+ * or above 0.0.0, and the pre-release rule already refuses to let a pre-release
132
+ * host satisfy a comparator that does not name a pre-release of its own tuple.
133
+ */
134
+ function noVersion() {
135
+ return [comparator('<', full(0, 0, 0))];
136
+ }
137
+
123
138
  function lowerBounds(partial, inclusive) {
124
139
  const version = filled(partial);
125
140
  if (inclusive === true) return [comparator('>=', version)];
@@ -199,9 +214,9 @@ function expandToken(token) {
199
214
  }
200
215
  if (operator === '=') return plainBounds(partial);
201
216
  if (operator === '>=') return partial.major === null ? [] : [comparator('>=', filled(partial))];
202
- if (operator === '>') return partial.major === null ? [] : lowerBounds(partial, false);
217
+ if (operator === '>') return partial.major === null ? noVersion() : lowerBounds(partial, false);
203
218
  if (operator === '<=') return partial.major === null ? [] : upperBounds(partial, true);
204
- if (operator === '<') return partial.major === null ? [] : upperBounds(partial, false);
219
+ if (operator === '<') return partial.major === null ? noVersion() : upperBounds(partial, false);
205
220
  return null;
206
221
  }
207
222
 
package/lib/doctor.mjs CHANGED
@@ -493,16 +493,149 @@ export function checkRootExport(dir, manifest) {
493
493
  return null;
494
494
  }
495
495
 
496
+ /**
497
+ * Replace comments and the contents of string, template and regex literals
498
+ * with spaces, keeping newlines. The export check is a source question, not an
499
+ * execution: `doctor` must never import the plugin it is checking, and an
500
+ * `apply` written in prose or a message is not an export. This is deliberately
501
+ * a small lexer rather than a module evaluator or a new dependency.
502
+ */
503
+ function codeOnly(source) {
504
+ let out = '';
505
+ let i = 0;
506
+ const n = source.length;
507
+ const blank = (text) => text.replace(/[^\r\n]/gu, ' ');
508
+
509
+ /** True when a `/` here starts a regex literal rather than a division. */
510
+ const regexMayStart = () => {
511
+ const trimmed = out.trimEnd();
512
+ if (trimmed === '') return true;
513
+ const last = trimmed.at(-1);
514
+ if ('([{,;:=!?&|+-*%^~<>'.includes(last)) return true;
515
+ const word = /([A-Za-z_$][\w$]*)$/u.exec(trimmed)?.[1];
516
+ return (
517
+ word !== undefined &&
518
+ ['return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void', 'yield', 'await', 'case', 'throw', 'else', 'do'].includes(word)
519
+ );
520
+ };
521
+
522
+ while (i < n) {
523
+ const ch = source[i];
524
+ const next = source[i + 1];
525
+
526
+ // A shebang is a comment line, even though it does not use `//`.
527
+ if (i === 0 && ch === '#' && next === '!') {
528
+ let end = source.indexOf('\n', i);
529
+ if (end === -1) end = n;
530
+ out += blank(source.slice(i, end));
531
+ i = end;
532
+ continue;
533
+ }
534
+
535
+ if (ch === '/' && next === '/') {
536
+ let end = i + 2;
537
+ while (end < n && source[end] !== '\n' && source[end] !== '\r') end++;
538
+ out += blank(source.slice(i, end));
539
+ i = end;
540
+ continue;
541
+ }
542
+
543
+ if (ch === '/' && next === '*') {
544
+ const close = source.indexOf('*/', i + 2);
545
+ const end = close === -1 ? n : close + 2;
546
+ out += blank(source.slice(i, end));
547
+ i = end;
548
+ continue;
549
+ }
550
+
551
+ if (ch === '"' || ch === "'" || ch === '`') {
552
+ const start = i;
553
+ i++;
554
+ while (i < n) {
555
+ if (source[i] === '\\') {
556
+ i += 2;
557
+ continue;
558
+ }
559
+ if (source[i] === ch) {
560
+ i++;
561
+ break;
562
+ }
563
+ i++;
564
+ }
565
+ // Keep the delimiters so adjacent code does not become one token; the
566
+ // literal's contents are not code and cannot export anything.
567
+ out += ch + blank(source.slice(start + 1, source[i - 1] === ch ? i - 1 : i)) + (source[i - 1] === ch ? ch : '');
568
+ continue;
569
+ }
570
+
571
+ if (ch === '/' && regexMayStart()) {
572
+ const start = i;
573
+ let inClass = false;
574
+ i++;
575
+ while (i < n) {
576
+ if (source[i] === '\\') {
577
+ i += 2;
578
+ continue;
579
+ }
580
+ if (source[i] === '\n' || source[i] === '\r') break;
581
+ if (source[i] === '[') inClass = true;
582
+ else if (source[i] === ']') inClass = false;
583
+ else if (source[i] === '/' && inClass === false) {
584
+ i++;
585
+ while (i < n && /[a-z]/iu.test(source[i])) i++;
586
+ break;
587
+ }
588
+ i++;
589
+ }
590
+ out += blank(source.slice(start, i));
591
+ continue;
592
+ }
593
+
594
+ out += ch;
595
+ i++;
596
+ }
597
+ return out;
598
+ }
599
+
600
+ /** The exported name of each specifier in `export { ... }`, comments removed. */
601
+ function exportedNames(code) {
602
+ const names = [];
603
+ for (const match of code.matchAll(/\bexport\s*\{([^}]*)\}/gu)) {
604
+ for (const part of match[1].split(',')) {
605
+ const specifier = /^\s*(?:([\w$]+)\s+as\s+)?([\w$]+)\s*$/u.exec(part);
606
+ if (specifier === null) continue;
607
+ // The second name is the exported one: `helper as apply` exports apply.
608
+ names.push(specifier[2]);
609
+ }
610
+ }
611
+ return names;
612
+ }
613
+
614
+ /** True when a CommonJS module assigns an `apply` function to its exports. */
615
+ function commonJsExportsApply(code) {
616
+ if (/\b(?:module\s*\.\s*)?exports\s*\.\s*apply\s*=/u.test(code)) return true;
617
+ for (const match of code.matchAll(/\bmodule\s*\.\s*exports\s*=\s*\{([^}]*)\}/gu)) {
618
+ if (/(?:^|,)\s*(?:async\s+)?apply\s*(?::|\(|,|$)/mu.test(match[1])) return true;
619
+ }
620
+ return false;
621
+ }
622
+
496
623
  /**
497
624
  * True when the module source exports `apply` in any of the forms a plugin
498
625
  * actually uses. Factored out because `doctor --remote` asks the same question
499
626
  * about a file it read over the API, and two copies would drift.
627
+ *
628
+ * Comments, strings and regex literals are removed first, so a comment saying
629
+ * "TODO: export function apply() {}" is not mistaken for the export it tells
630
+ * the author to write.
500
631
  */
501
632
  export function exportsApply(source) {
502
633
  if (typeof source !== 'string') return false;
503
- return /export\s+(?:async\s+)?function\s+apply\b|export\s+(?:const|let|var)\s+apply\b|export\s*\{[^}]*\bapply\b|\bapply\s*[:=]\s*(?:async\s*)?(?:function|\()/.test(
504
- source,
505
- );
634
+ const code = codeOnly(source);
635
+ if (/\bexport\s+(?:async\s+)?function\s*\*?\s*apply\b/u.test(code)) return true;
636
+ if (/\bexport\s+(?:const|let|var)\s+apply\b/u.test(code)) return true;
637
+ if (exportedNames(code).includes('apply')) return true;
638
+ return commonJsExportsApply(code);
506
639
  }
507
640
 
508
641
  /** Runs every check and returns `{ failures, notes }`. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.13",
3
+ "version": "0.20.15",
4
4
  "description": "Preflight, release and test DeepSeek Harness plugins: check a folder or any GitHub repository, wait for npm to actually serve the version, and keep the market index honest.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -29,7 +29,7 @@ function positive(name, value) {
29
29
  const options = {
30
30
  list: BENCHMARK_LIST,
31
31
  limit: BENCHMARK_LIMIT,
32
- latency: BENCHMARK_LATENCY_MS,
32
+ latencyMs: BENCHMARK_LATENCY_MS,
33
33
  jobs: DEFAULT_JOBS,
34
34
  };
35
35
 
@@ -50,7 +50,7 @@ for (let index = 0; index < argv.length; index += 1) {
50
50
  index += 1;
51
51
  if (flag === '--list') options.list = value;
52
52
  else if (flag === '--limit') options.limit = positive(flag, value);
53
- else if (flag === '--latency') options.latency = positive(flag, value);
53
+ else if (flag === '--latency') options.latencyMs = positive(flag, value);
54
54
  else if (flag === '--jobs') options.jobs = positive(flag, value);
55
55
  else throw new Error(`unknown flag ${flag}; run with --help`);
56
56
  }