dsh-plugin-toolkit 0.20.38 → 0.20.40

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,53 @@
1
+ ## 0.20.40
2
+
3
+ - **`doctor`'s subdirectory ignore matcher understands npm extglob patterns.**
4
+ A `lib/.npmignore` of `@(client|other).js` makes `npm pack` drop
5
+ `lib/client.js`, but the files-list check escaped the parentheses and read
6
+ the line as one literal filename, so it called the package clean. The glob
7
+ compiler now expands npm's extglob operators (`@()`, `+()`, `?()`, `*()` and
8
+ `!()`), including alternatives with their own wildcards, so the ignore rule
9
+ removes the same paths the packer does. `test/doctor-files-npmignore.test.mjs`
10
+ runs the extglob fixture and a literal `client.js` control against
11
+ `npm pack --dry-run --json` and three consecutive `doctor` runs.
12
+
13
+ ## 0.20.39
14
+
15
+ - **`doctor`'s files-list check honors a `.npmignore` in a subdirectory.** npm
16
+ disables the root `.npmignore` when `files` exists, but a `lib/.npmignore`
17
+ (or the `lib/.gitignore` fallback) still removes files from the tarball. A
18
+ package whose `files: ["lib"]` shipped the folder while `lib/.npmignore`
19
+ dropped the `lib/client.js` named by `exports["./client"]` used to pass
20
+ `doctor` and fail after install. The check walks each declared path through
21
+ the subdirectory ignore files and keeps npm's two exceptions: an explicit
22
+ file entry in `files` re-includes that file, and a later `!` rule in the
23
+ subdirectory ignore file puts it back. `test/doctor-files-npmignore.test.mjs`
24
+ pins the reported case, the `.gitignore` fallback, a nested
25
+ `lib/nested/.npmignore`, and the unrelated-file and negation controls against
26
+ `npm pack --dry-run --json`.
27
+
28
+ - **`release --dry-run` no longer plans a tag git will reject when the version
29
+ is valid.** A pre-release or build identifier ending in `.lock`
30
+ (`1.2.3-rc.lock`) is legal SemVer and packs with npm, but
31
+ `git tag plugin-v1.2.3-rc.lock` fails; an invalid `--tag-prefix` (a space or
32
+ `..`) had the same effect. `plan()` and the real release now apply git's
33
+ ref-name rules before printing or creating the tag, and report a `tag`
34
+ failure instead. `test/release.test.mjs` covers the valid controls, the
35
+ `.lock` version, an invalid prefix, and that the real release makes no git
36
+ calls for a name it refuses.
37
+
38
+ - **`doctor` validates `version` with the same strict SemVer parser the rest of
39
+ the toolkit uses, and `release --dry-run` no longer prints a tag for a version
40
+ the preflight rejects.** The package version check had its own regex while
41
+ the compatibility code had another parser, so the two could disagree about
42
+ forms such as `01.2.3`, `1.2.3-01` and `1.2.3-..`. The shared parser now also
43
+ rejects malformed build identifiers (`1.2.3+build..1`), which the older
44
+ compatibility parser let through. `plan()` refuses to build a `plugin-v...`
45
+ tag when the version is invalid, and the CLI reports the version failure
46
+ instead of printing a command the real release would never run.
47
+ `test/doctor-version-semver.test.mjs` checks the parser agreement, the
48
+ accepted `1.2.3` / `1.2.3-rc.1` controls, and that the invalid forms exit `1`
49
+ without a tag in the dry-run plan.
50
+
1
51
  ## 0.20.38
2
52
 
3
53
  - **`doctor` accepts SemVer 2.0 build metadata in `version`, and rejects
package/README.md CHANGED
@@ -746,7 +746,7 @@ the diff in the terminal.
746
746
  | `dsh field` | `dsh.bundle.patch` must exist for the host to load the plugin |
747
747
  | `patch file` | The path declared above must be a real file |
748
748
  | `client entry` | If `dsh.client` is declared, the bundle has to be there |
749
- | `files list` | Every path `package.json` points at (`exports`, patch, client) must be covered by `files`; a leading `!` excludes what the positive entries would ship |
749
+ | `files list` | Every path `package.json` points at (`exports`, patch, client) must be covered by `files` and not removed by a `.npmignore`/`.gitignore` in a subdirectory it passes through; a leading `!` excludes what the positive entries would ship |
750
750
  | `root export` | The loader imports the bare package name; if that module is missing, is a directory, is the CLI, exports no `apply`, or the `exports` map has no `.` entry, the row mounts nothing while the install reports success |
751
751
 
752
752
  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 checks that the path is a readable regular file, removes comments and the contents of string, template and regex literals, and looks for a real export. A missing file, a directory and an unreadable file are reported as `root export` failures naming the target instead of being skipped or raising a raw `EISDIR`; on a directory the install would have failed at import too. 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.
package/lib/cli.mjs CHANGED
@@ -863,6 +863,11 @@ export async function run(argv, io = console, deps = {}) {
863
863
  tagPrefix: options.tagPrefix,
864
864
  indexFile: options.index === undefined ? undefined : expandHome(options.index),
865
865
  });
866
+ if (planned.tag === null) {
867
+ io.error(' cannot plan a release tag:');
868
+ printFailures(planned.failures, io);
869
+ return 1;
870
+ }
866
871
  for (const step of planned.steps) {
867
872
  io.log(` ${step.runs === false ? '·' : '→'} ${step.title}`);
868
873
  io.log(` ${step.command}`);
package/lib/compat.mjs CHANGED
@@ -13,9 +13,22 @@
13
13
  */
14
14
 
15
15
  const CORE = '(0|[1-9]\\d*)';
16
- const PRERELEASE = '(?:-([0-9A-Za-z.-]+))?';
17
- const BUILD = '(?:\\+[0-9A-Za-z.-]+)?';
18
- const FULL_VERSION = new RegExp(`^[v=]?${CORE}\\.${CORE}\\.${CORE}${PRERELEASE}${BUILD}$`, 'u');
16
+ // One grammar for every version this module accepts. Numeric identifiers may
17
+ // not carry leading zeros, while non-numeric ones may; prerelease and build
18
+ // identifiers are never empty and never joined by a bare dot. The same rule is
19
+ // used for the package `version` a release tags and for the host version a
20
+ // range is compared against, so the two probes cannot drift apart.
21
+ const NUMERIC_ID = '0|[1-9]\\d*';
22
+ const PRERELEASE_ID = `(?:${NUMERIC_ID}|\\d*[A-Za-z-][0-9A-Za-z-]*)`;
23
+ const BUILD_ID = '[0-9A-Za-z-]+';
24
+ const PRERELEASE = `(?:-(${PRERELEASE_ID}(?:\\.${PRERELEASE_ID})*))?`;
25
+ const BUILD = `(?:\\+(${BUILD_ID}(?:\\.${BUILD_ID})*))?`;
26
+ const VERSION_BODY = `${CORE}\\.${CORE}\\.${CORE}${PRERELEASE}${BUILD}`;
27
+ const FULL_VERSION = new RegExp(`^[v=]?${VERSION_BODY}$`, 'u');
28
+ // A package `version` is written by the author, not typed at a CLI: npm does
29
+ // not normalise a leading `v`/`=` or surrounding whitespace in the manifest
30
+ // field, and a release must not tag a version npm will rewrite.
31
+ const STRICT_VERSION = new RegExp(`^${VERSION_BODY}$`, 'u');
19
32
  const PARTIAL_VERSION = new RegExp(
20
33
  `^[v=]?(0|[1-9]\\d*|[xX*])(?:\\.(0|[1-9]\\d*|[xX*]))?(?:\\.(0|[1-9]\\d*|[xX*]))?${PRERELEASE}${BUILD}$`,
21
34
  'u',
@@ -31,11 +44,7 @@ function prereleaseOf(text) {
31
44
  return identifiers;
32
45
  }
33
46
 
34
- /** A complete `major.minor.patch[-prerelease]` version, or null when malformed. */
35
- export function parseVersion(value) {
36
- if (typeof value !== 'string') return null;
37
- const match = FULL_VERSION.exec(value.trim());
38
- if (match === null) return null;
47
+ function versionFromMatch(match) {
39
48
  const prerelease = prereleaseOf(match[4]);
40
49
  if (prerelease === null) return null;
41
50
  return {
@@ -46,6 +55,32 @@ export function parseVersion(value) {
46
55
  };
47
56
  }
48
57
 
58
+ /**
59
+ * A complete `major.minor.patch[-prerelease][+build]` version, or null when
60
+ * malformed. This is the strict form a `package.json` `version` must have: no
61
+ * `v`/`=` prefix, no surrounding whitespace, and valid prerelease and build
62
+ * identifiers. Build metadata is accepted and does not affect precedence.
63
+ */
64
+ export function parseStrictVersion(value) {
65
+ if (typeof value !== 'string') return null;
66
+ const match = STRICT_VERSION.exec(value);
67
+ if (match === null) return null;
68
+ return versionFromMatch(match);
69
+ }
70
+
71
+ /**
72
+ * A complete version for a host or range comparison, or null when malformed.
73
+ * npm's parser tolerates the leading `v`/`=` and surrounding whitespace users
74
+ * type on a command line, so the host form keeps that tolerance; the package
75
+ * `version` check uses `parseStrictVersion` instead.
76
+ */
77
+ export function parseVersion(value) {
78
+ if (typeof value !== 'string') return null;
79
+ const match = FULL_VERSION.exec(value.trim());
80
+ if (match === null) return null;
81
+ return versionFromMatch(match);
82
+ }
83
+
49
84
  /**
50
85
  * The audit's `--host` contract, in one place: a complete version to compare
51
86
  * against, never a range, a partial version or a label. Returns null when the
package/lib/doctor.mjs CHANGED
@@ -9,25 +9,11 @@
9
9
  import fs from 'node:fs';
10
10
  import path from 'node:path';
11
11
 
12
- import { hostCompatibility, parsePartialVersion, parseRange } from './compat.mjs';
12
+ import { hostCompatibility, parsePartialVersion, parseRange, parseStrictVersion } from './compat.mjs';
13
13
  import { resolvePath } from './paths.mjs';
14
14
 
15
15
  export { hostCompatibility } from './compat.mjs';
16
16
 
17
- // SemVer 2.0's whole grammar, not just a prefix test. `npm pack` and `npm
18
- // publish` accept build metadata (`1.0.0+build.5`), and a pre-release or build
19
- // identifier cannot be empty or split by a bare dot (`1.0.0-..`). Numeric
20
- // identifiers also cannot carry leading zeros, while build identifiers may.
21
- const SEMVER_NUMBER = '0|[1-9]\\d*';
22
- const SEMVER_PRERELEASE_ID = `(?:${SEMVER_NUMBER}|\\d*[A-Za-z-][0-9A-Za-z-]*)`;
23
- const SEMVER_BUILD_ID = '[0-9A-Za-z-]+';
24
- const SEMVER = new RegExp(
25
- `^(?:${SEMVER_NUMBER})\\.(?:${SEMVER_NUMBER})\\.(?:${SEMVER_NUMBER})` +
26
- `(?:-(?:${SEMVER_PRERELEASE_ID})(?:\\.(?:${SEMVER_PRERELEASE_ID}))*)?` +
27
- `(?:\\+(?:${SEMVER_BUILD_ID})(?:\\.(?:${SEMVER_BUILD_ID}))*)?$`,
28
- 'u',
29
- );
30
-
31
17
  /**
32
18
  * npm publishes and installs by `name`; a missing, empty or malformed one fails
33
19
  * at the publish/pack boundary, after every other check has already passed.
@@ -159,7 +145,9 @@ export function checkName(manifest) {
159
145
  export function checkVersion(manifest) {
160
146
  const value = version(manifest);
161
147
  if (value === null) return 'package.json has no version';
162
- if (SEMVER.test(value) === false) return `version "${value}" is not semver`;
148
+ // The same strict parser the compatibility code uses for a package version,
149
+ // so `doctor` and `release --dry-run` cannot accept different forms.
150
+ if (parseStrictVersion(value) === null) return `version "${value}" is not semver`;
163
151
  return null;
164
152
  }
165
153
 
@@ -334,7 +322,7 @@ export function declaredPaths(manifest) {
334
322
  return [...paths];
335
323
  }
336
324
 
337
- const GLOB_MAGIC = /[*?{}[\]]/u;
325
+ const GLOB_MAGIC = /[*?{}[\]]|[!+@]\(/u;
338
326
 
339
327
  /** npm compares tarball paths with forward slashes and no leading `./` or `/`. */
340
328
  function packagePath(value) {
@@ -386,11 +374,101 @@ function expandBraces(pattern) {
386
374
  return parts.flatMap((part) => expandBraces(`${prefix}${part}${suffix}`));
387
375
  }
388
376
 
377
+ /**
378
+ * Index of the `)` that closes the extglob opened at `open`, or -1 when the
379
+ * pattern has no closing paren. Parentheses inside a bracket class, a nested
380
+ * extglob or an escape do not count.
381
+ */
382
+ function extglobEnd(pattern, open) {
383
+ let depth = 0;
384
+ let inClass = false;
385
+ for (let index = open; index < pattern.length; index += 1) {
386
+ const char = pattern[index];
387
+ if (char === '\\') {
388
+ index += 1;
389
+ } else if (inClass === true) {
390
+ if (char === ']') inClass = false;
391
+ } else if (char === '[') {
392
+ inClass = true;
393
+ } else if (char === '(') {
394
+ depth += 1;
395
+ } else if (char === ')') {
396
+ depth -= 1;
397
+ if (depth === 0) return index;
398
+ }
399
+ }
400
+ return -1;
401
+ }
402
+
403
+ /** Split an extglob body on `|`, ignoring separators inside a nested group or class. */
404
+ function splitExtglobAlternatives(body) {
405
+ const parts = [];
406
+ let current = '';
407
+ let depth = 0;
408
+ let inClass = false;
409
+ for (let index = 0; index < body.length; index += 1) {
410
+ const char = body[index];
411
+ if (char === '\\') {
412
+ current += char;
413
+ if (index + 1 < body.length) current += body[(index += 1)];
414
+ } else if (inClass === true) {
415
+ current += char;
416
+ if (char === ']') inClass = false;
417
+ } else if (char === '[') {
418
+ inClass = true;
419
+ current += char;
420
+ } else if (char === '(') {
421
+ depth += 1;
422
+ current += char;
423
+ } else if (char === ')') {
424
+ depth -= 1;
425
+ current += char;
426
+ } else if (char === '|' && depth === 0) {
427
+ parts.push(current);
428
+ current = '';
429
+ } else {
430
+ current += char;
431
+ }
432
+ }
433
+ parts.push(current);
434
+ return parts;
435
+ }
436
+
437
+ /** The regex source for one extglob operator and its `|`-separated body. */
438
+ function extglobSource(operator, body) {
439
+ const alternatives = splitExtglobAlternatives(body).map(globSource);
440
+ const inner = alternatives.length === 1 ? alternatives[0] : `(?:${alternatives.join('|')})`;
441
+ switch (operator) {
442
+ case '@':
443
+ return `(?:${inner})`;
444
+ case '+':
445
+ return `(?:${inner})+`;
446
+ case '?':
447
+ return `(?:${inner})?`;
448
+ case '*':
449
+ return `(?:${inner})*`;
450
+ default:
451
+ // `!(...)` is minimatch's negative extglob: at this position no
452
+ // alternative may match, and the lazy segment lets the rest of the
453
+ // pattern decide where the group ends (`!(foo).js` still matches
454
+ // `bar.js`, not `foo.js`).
455
+ return `(?:(?!(?:${inner}))[^/]*?)`;
456
+ }
457
+ }
458
+
389
459
  /** One glob alternative, with `*` kept inside a path segment and `**` crossing them. */
390
460
  function globSource(pattern) {
391
461
  let source = '';
392
462
  for (let index = 0; index < pattern.length; index += 1) {
393
463
  const char = pattern[index];
464
+ if ('@+?!*'.includes(char) === true && pattern[index + 1] === '(') {
465
+ const close = extglobEnd(pattern, index + 1);
466
+ if (close !== -1) {
467
+ source += extglobSource(char, pattern.slice(index + 2, close));
468
+ index = close;
469
+ continue;
470
+ }
471
+ }
394
472
  if (char === '*') {
395
473
  if (pattern[index + 1] === '*') {
396
474
  while (pattern[index + 1] === '*') index += 1;
@@ -508,10 +586,137 @@ export function isShipped(target, files) {
508
586
  return shipped;
509
587
  }
510
588
 
589
+ /**
590
+ * Read the ignore file npm would use for a subdirectory. A `.npmignore` file
591
+ * wins over `.gitignore` in the same directory, and a missing one falls through
592
+ * to the next candidate. The root `.npmignore` is not consulted here: when a
593
+ * `files` list exists npm disables the root ignore files, but a subdirectory
594
+ * `.npmignore` (or the `.gitignore` fallback) still subtracts from it.
595
+ */
596
+ function subdirectoryIgnoreFile(directory) {
597
+ for (const name of ['.npmignore', '.gitignore']) {
598
+ let text;
599
+ try {
600
+ text = fs.readFileSync(path.join(directory, name), 'utf8');
601
+ } catch (error) {
602
+ if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') continue;
603
+ // npm would stop packing on an unreadable ignore file. The files-list
604
+ // check has no way to report that, so it keeps looking rather than
605
+ // calling the package clean because of a filesystem error.
606
+ return null;
607
+ }
608
+ return {
609
+ file: path.join(directory, name),
610
+ rules: text
611
+ .split(/\r?\n/u)
612
+ .map((line) => line.trim())
613
+ .filter((line) => line !== '' && line.startsWith('#') === false)
614
+ .map((line) => {
615
+ const negate = line.startsWith('!');
616
+ return { negate, pattern: negate ? line.slice(1) : line };
617
+ })
618
+ .filter((rule) => rule.pattern !== ''),
619
+ };
620
+ }
621
+ return null;
622
+ }
623
+
624
+ /**
625
+ * Whether one ignore-file rule names `relative`, a path below the directory
626
+ * that owns the ignore file. A rule also removes a file when it names one of
627
+ * its parent directories, which is how `nested/` drops `nested/client.js`.
628
+ */
629
+ function ignoreRuleMatches(relative, pattern) {
630
+ // Anchoring is decided before `packagePath` strips the leading slash that
631
+ // spells it; `/client.js` names a direct child of the ignore file's folder,
632
+ // not a basename at any depth.
633
+ const anchored = String(pattern).startsWith('/');
634
+ let clean = packagePath(pattern);
635
+ const directoryOnly = clean.endsWith('/');
636
+ if (directoryOnly === true) clean = clean.replace(/\/+$/u, '');
637
+ if (clean === '' || clean === '.') return false;
638
+
639
+ const segments = relative.split('/');
640
+ for (let depth = 1; depth <= segments.length; depth += 1) {
641
+ // A trailing slash names a directory. It removes the files below that
642
+ // directory, not a file that happens to have the directory's name.
643
+ if (directoryOnly === true && depth === segments.length) continue;
644
+ const candidate = segments.slice(0, depth).join('/');
645
+ if (anchored === true || clean.includes('/') === true) {
646
+ if (globMatches(candidate, clean) === true) return true;
647
+ } else {
648
+ // npm compiles ignore rules with minimatch's matchBase: a pattern with
649
+ // no slash matches a basename at any depth (`*.test.js`).
650
+ const basename = candidate.slice(candidate.lastIndexOf('/') + 1);
651
+ if (globMatches(basename, clean) === true) return true;
652
+ }
653
+ }
654
+ return false;
655
+ }
656
+
657
+ /** Whether the last matching rule in one ignore file excludes `relative`. */
658
+ function ignoredByRules(relative, rules) {
659
+ let ignored = false;
660
+ for (const rule of rules) {
661
+ if (ignoreRuleMatches(relative, rule.pattern) === true) ignored = rule.negate === false;
662
+ }
663
+ return ignored;
664
+ }
665
+
666
+ /**
667
+ * The subdirectory ignore file that makes `npm pack` drop `target`, or null.
668
+ *
669
+ * npm walks the tree and applies each directory's own ignore file to the paths
670
+ * below it. The shallowest directory that excludes the path stops the walk, so
671
+ * a deeper ignore file cannot re-include what a parent removed. An explicit
672
+ * file entry in `files` is the one exception: npm marks it as required and
673
+ * packs it even when a subdirectory `.npmignore` names it.
674
+ */
675
+ function subdirectoryIgnoreFor(dir, target) {
676
+ const root = path.resolve(dir);
677
+ const wanted = packagePath(target);
678
+ // A wildcard export names a set of files, not one path. npm decides that set
679
+ // while packing, so a single ignore rule cannot say the whole export is gone.
680
+ if (GLOB_MAGIC.test(wanted) === true) return null;
681
+ const segments = wanted.split('/').filter((segment) => segment !== '' && segment !== '.');
682
+ if (segments.length < 2 || segments.includes('..') === true) return null;
683
+
684
+ for (let depth = 1; depth < segments.length; depth += 1) {
685
+ const directory = path.join(root, ...segments.slice(0, depth));
686
+ if (directory.startsWith(`${root}${path.sep}`) === false) return null;
687
+ const ignore = subdirectoryIgnoreFile(directory);
688
+ if (ignore === null) continue;
689
+ const relative = segments.slice(depth).join('/');
690
+ if (ignoredByRules(relative, ignore.rules) === true) return ignore.file;
691
+ }
692
+ return null;
693
+ }
694
+
695
+ /** True when `files` names `target` as a file, which npm marks as required. */
696
+ function explicitlyListedFile(dir, target, files) {
697
+ const wanted = packagePath(target);
698
+ for (const entry of files) {
699
+ if (typeof entry !== 'string' || entry.startsWith('!')) continue;
700
+ const clean = packagePath(entry).replace(/\/+$/u, '');
701
+ if (clean !== wanted || clean === '') continue;
702
+ try {
703
+ if (fs.statSync(path.join(dir, clean)).isFile() === true) return true;
704
+ } catch {
705
+ // npm treats a path that is not there as a pattern, so nothing is
706
+ // required and a subdirectory ignore file still applies.
707
+ }
708
+ }
709
+ return false;
710
+ }
711
+
511
712
  /**
512
713
  * npm always puts these in the tarball whatever `files` says, so a `files` list
513
714
  * that omits them is not a packaging bug. `main` is on the same list: npm adds
514
715
  * the file the `main` field names even when `files` does not mention it.
716
+ *
717
+ * A subdirectory `.npmignore` can still drop these files, so the caller has to
718
+ * ask the ignore question separately; this predicate only covers the `files`
719
+ * list part of npm's rules.
515
720
  */
516
721
  const ALWAYS_SHIPPED = (entry, manifest) => {
517
722
  if (entry === 'package.json') return true;
@@ -522,19 +727,35 @@ const ALWAYS_SHIPPED = (entry, manifest) => {
522
727
  return main !== null && entry === main;
523
728
  };
524
729
 
525
- /** The paths `package.json` points at that its own `files` list would omit. */
526
- export function missingDeclaredPaths(manifest) {
730
+ /**
731
+ * The paths `package.json` points at that its own `files` list (or the
732
+ * subdirectory ignore files npm applies on top of it) would omit.
733
+ *
734
+ * `dir` is optional because `doctor --remote` and `audit --remote` only have
735
+ * the manifest GitHub serves. Without a tree there is nothing to read, so the
736
+ * remote check keeps its manifest-only answer instead of guessing.
737
+ */
738
+ export function missingDeclaredPaths(manifest, dir = undefined) {
527
739
  const files = manifest.files;
528
740
  if (Array.isArray(files) === false) return [];
529
- const declared = declaredPaths(manifest).filter((entry) => ALWAYS_SHIPPED(entry, manifest) === false);
530
- return declared.filter((entry) => isShipped(entry, files) === false);
531
- }
532
-
533
- export function checkFilesList(manifest) {
741
+ const declared = declaredPaths(manifest);
742
+ const root = dir === undefined ? null : path.resolve(dir);
743
+ return declared.filter((entry) => {
744
+ const alwaysShipped = ALWAYS_SHIPPED(entry, manifest);
745
+ if (alwaysShipped === false && isShipped(entry, files) === false) return true;
746
+ if (root === null) return false;
747
+ // npm's synthetic rule for an explicit file in `files` re-includes that
748
+ // file, so a subdirectory `.npmignore` cannot drop it.
749
+ if (explicitlyListedFile(root, entry, files) === true) return false;
750
+ return subdirectoryIgnoreFor(root, entry) !== null;
751
+ });
752
+ }
753
+
754
+ export function checkFilesList(manifest, dir = undefined) {
534
755
  if (Array.isArray(manifest.files) === false) {
535
756
  return 'package.json has no "files" list, so the tarball ships whatever happens to be in the folder';
536
757
  }
537
- const missing = missingDeclaredPaths(manifest);
758
+ const missing = missingDeclaredPaths(manifest, dir);
538
759
  if (missing.length > 0) {
539
760
  return `files does not ship ${missing.join(', ')}, which package.json points at, so the installed plugin would be missing its own code`;
540
761
  }
@@ -768,7 +989,7 @@ export function doctor(dir, { installed = false } = {}) {
768
989
  ['client declaration', checkClientDeclaration(target, manifest)],
769
990
  // After install the tarball is already unpacked, so `files` cannot be used to
770
991
  // decide what shipped: npm always ships package.json and the README.
771
- ['files list', installed === true ? null : checkFilesList(manifest)],
992
+ ['files list', installed === true ? null : checkFilesList(manifest, target)],
772
993
  ['root export', checkRootExport(target, manifest)],
773
994
  ];
774
995
  const failures = checks.filter(([, result]) => result !== null && typeof result === 'string');
package/lib/release.mjs CHANGED
@@ -9,7 +9,7 @@ import { commandFailureDetail, run as runCommand } from './exec.mjs';
9
9
  import fs from 'node:fs';
10
10
  import path from 'node:path';
11
11
 
12
- import { doctor } from './doctor.mjs';
12
+ import { checkVersion, doctor } from './doctor.mjs';
13
13
  import { expandHome, resolvePath } from './paths.mjs';
14
14
  import { addVersion, buildEntry, readIndex, writeIndex } from './index-file.mjs';
15
15
  import { publishedAt, waitForVersion } from './registry.mjs';
@@ -59,6 +59,43 @@ export function tagName(version, prefix = 'plugin-v') {
59
59
  return `${prefix}${version}`;
60
60
  }
61
61
 
62
+ /**
63
+ * True when `git tag` would accept this name; `refs/tags/` is implicit.
64
+ *
65
+ * The version check alone is not enough: a valid SemVer pre-release or build
66
+ * identifier can end in `.lock` (`1.2.3-rc.lock`), and `--tag-prefix` can carry
67
+ * a space or `..`. A dry run that printed one of those tags would tell the
68
+ * author to run a `git tag` command that fails. These are the
69
+ * `git check-ref-format` rules a derived name can violate, without asking a git
70
+ * binary during a read-only plan.
71
+ */
72
+ export function isValidTagName(tag) {
73
+ if (typeof tag !== 'string' || tag.length === 0) return false;
74
+ if (/[\u0000-\u0020\u007f~^:?*\[\\]/u.test(tag)) return false;
75
+ if (
76
+ tag.includes('..') ||
77
+ tag.includes('@{') ||
78
+ tag.startsWith('/') ||
79
+ tag.endsWith('/') ||
80
+ tag.endsWith('.')
81
+ ) {
82
+ return false;
83
+ }
84
+ return tag.split('/').every((component) => {
85
+ return (
86
+ component !== '' &&
87
+ component.startsWith('.') === false &&
88
+ component.endsWith('.lock') === false
89
+ );
90
+ });
91
+ }
92
+
93
+ /** The sentence both the plan and the real release report for an unusable tag. */
94
+ function tagNameIssue(tag) {
95
+ if (isValidTagName(tag) === true) return null;
96
+ return `tag ${JSON.stringify(tag)} is not a valid git tag name; use a version and --tag-prefix without spaces, "..", a leading dot or a ".lock" component`;
97
+ }
98
+
62
99
  export function tagExists(dir, tag, run) {
63
100
  try {
64
101
  (run ?? ((args) => git(dir, args)))(['rev-parse', `refs/tags/${tag}`]);
@@ -155,8 +192,33 @@ export function dirtyPaths(dir, limit = 3, run) {
155
192
  export function plan({ dir = process.cwd(), version, name, tagPrefix = 'plugin-v', indexFile = 'market/index.json', marketDir }) {
156
193
  const report = doctor(resolvePath(dir));
157
194
  const resolvedName = name ?? report.manifest.name ?? 'this-plugin';
158
- const resolvedVersion = version ?? report.manifest.version ?? '0.0.0';
195
+ const resolvedVersion = version ?? report.manifest.version;
196
+ // Do not build a tag for a version the preflight rejects. A dry run that
197
+ // printed `plugin-v01.2.3` was telling the author to run a command that npm
198
+ // would normalise away once the real release began.
199
+ const versionFailure = checkVersion({ version: resolvedVersion });
200
+ if (versionFailure !== null) {
201
+ return {
202
+ tag: null,
203
+ name: resolvedName,
204
+ version: resolvedVersion ?? '(no version)',
205
+ indexFile,
206
+ steps: [],
207
+ failures: [{ check: 'version', message: versionFailure }],
208
+ };
209
+ }
159
210
  const tag = tagName(resolvedVersion, tagPrefix);
211
+ const tagFailure = tagNameIssue(tag);
212
+ if (tagFailure !== null) {
213
+ return {
214
+ tag: null,
215
+ name: resolvedName,
216
+ version: resolvedVersion,
217
+ indexFile,
218
+ steps: [],
219
+ failures: [{ check: 'tag', message: tagFailure }],
220
+ };
221
+ }
160
222
  const steps = [
161
223
  { title: 'Read the manifest and check it can be loaded', command: 'dsh-plugin doctor', runs: true },
162
224
  { title: `Create the tag ${tag}`, command: `git tag ${tag}`, runs: true },
@@ -208,6 +270,10 @@ export async function release(options) {
208
270
  const name = report.manifest.name;
209
271
  const version = report.manifest.version;
210
272
  const tag = tagName(version, tagPrefix);
273
+ const tagFailure = tagNameIssue(tag);
274
+ if (tagFailure !== null) {
275
+ return { ok: false, stage: 'tag', failures: [{ check: 'tag', message: tagFailure }] };
276
+ }
211
277
 
212
278
  const resuming = tagExists(root, tag, gitRun) === true;
213
279
  if (resuming === true && tagPointsAtHead(root, tag, gitRun) === false) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-toolkit",
3
- "version": "0.20.38",
3
+ "version": "0.20.40",
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": {