pm-ops 2026.10.26 → 2026.10.28
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 +51 -25
- package/README.md +89 -3
- package/dist/compatibility-reasons.d.ts +124 -0
- package/dist/compatibility-reasons.d.ts.map +1 -0
- package/dist/compatibility-reasons.js +350 -0
- package/dist/compatibility-reasons.js.map +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +16 -1
- package/dist/index.js.map +1 -1
- package/manifest.json +1 -1
- package/package.json +10 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,21 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 2026.10.28 - 2026-10-28
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
|
|
7
|
+
- Keep release changelog bytes stable when the pending version becomes a tag ([ops-release-changelog-stability](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-release-changelog-stability.toon))
|
|
8
|
+
|
|
9
|
+
### Other
|
|
10
|
+
|
|
11
|
+
- Stop Hound from linting generated dist/ output ([ops-hound-generated-dist](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-hound-generated-dist.toon))
|
|
12
|
+
|
|
13
|
+
## 2026.10.27 - 2026-10-27
|
|
14
|
+
|
|
15
|
+
### Other
|
|
16
|
+
|
|
17
|
+
- Use SDK corpus reads for backend assurance and diagnostics ([ops-sdk-adoption-1025](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/tasks/ops-sdk-adoption-1025.toon))
|
|
18
|
+
|
|
3
19
|
## 2026.10.26 - 2026-10-26
|
|
4
20
|
|
|
5
21
|
### Fixed
|
|
@@ -38,12 +54,9 @@ No tracked changes.
|
|
|
38
54
|
### Fixed
|
|
39
55
|
|
|
40
56
|
- A release run bumped and committed a new version every night while publishing was impossible, because the only externally-failable step runs last ([ops-e9g6](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-e9g6.toon))
|
|
41
|
-
- Fix release publish-before-protected-main-push ordering ([ops-gitr](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-gitr.toon))
|
|
42
|
-
- A parenthesised command inside a case arm is read as an arm label, refusing a publish the shell attests ([ops-vkvy](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-vkvy.toon))
|
|
43
57
|
- Self-hosted pm-changelog is reported not ready because it does not depend on itself ([ops-pksh](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-pksh.toon))
|
|
44
58
|
- Adding a source file breaks the coverage gate in three places, and none of them says so ([ops-cl0o](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-cl0o.toon))
|
|
45
59
|
- Recognize third-party publish wrappers (semantic-release, np, release-it, lerna publish, changeset publish) in the canonical attestation auditor ([ops-third-party-publish-wrappers](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-third-party-publish-wrappers.toon))
|
|
46
|
-
- A hardcoded fixture date aged out of the seven day window and broke the daily release ([ops-i2iz](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-i2iz.toon))
|
|
47
60
|
- The release completeness audit reported a published version and its GitHub Release as missing, turning a successful release into a failed one ([ops-fcow](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-fcow.toon))
|
|
48
61
|
- Guarded merge-driver launcher: omit-dev clone installs complete instead of failing on the devDependency import ([ops-mqdi](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-mqdi.toon))
|
|
49
62
|
- Duplication gate scans generated PM extension copies ([ops-to4t](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-to4t.toon))
|
|
@@ -57,6 +70,12 @@ No tracked changes.
|
|
|
57
70
|
- Enable GitHub CodeQL code scanning ([ops-jasw](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-jasw.toon))
|
|
58
71
|
- Characterize pre-existing fleet workflow scanner refusals ([ops-0u7l](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/tasks/ops-0u7l.toon))
|
|
59
72
|
|
|
73
|
+
### Closed
|
|
74
|
+
|
|
75
|
+
- Closed: Fix release publish-before-protected-main-push ordering ([ops-gitr](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-gitr.toon))
|
|
76
|
+
- Closed: A parenthesised command inside a case arm is read as an arm label, refusing a publish the shell attests ([ops-vkvy](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-vkvy.toon))
|
|
77
|
+
- Closed: A hardcoded fixture date aged out of the seven day window and broke the daily release ([ops-i2iz](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-i2iz.toon))
|
|
78
|
+
|
|
60
79
|
## 2026.10.21 - 2026-10-21
|
|
61
80
|
|
|
62
81
|
No tracked changes.
|
|
@@ -208,9 +227,9 @@ No tracked changes.
|
|
|
208
227
|
|
|
209
228
|
## 2026.9.8 - 2026-09-08
|
|
210
229
|
|
|
211
|
-
###
|
|
230
|
+
### Closed
|
|
212
231
|
|
|
213
|
-
- An assignment the scanner cannot read leaves the previous binding standing, so a replaced provenance flag still attests the publish ([ops-3wbz](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-3wbz.toon))
|
|
232
|
+
- Closed: An assignment the scanner cannot read leaves the previous binding standing, so a replaced provenance flag still attests the publish ([ops-3wbz](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-3wbz.toon))
|
|
214
233
|
|
|
215
234
|
## 2026.9.7 - 2026-09-07
|
|
216
235
|
|
|
@@ -237,9 +256,9 @@ No tracked changes.
|
|
|
237
256
|
|
|
238
257
|
## 2026.9.5 - 2026-09-05
|
|
239
258
|
|
|
240
|
-
###
|
|
259
|
+
### Closed
|
|
241
260
|
|
|
242
|
-
- The merge-driver test builds a shell command from an environment-controlled path, which is the pattern this repository asks every other one to stop using ([ops-6no1](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-6no1.toon))
|
|
261
|
+
- Closed: The merge-driver test builds a shell command from an environment-controlled path, which is the pattern this repository asks every other one to stop using ([ops-6no1](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-6no1.toon))
|
|
243
262
|
|
|
244
263
|
## 2026.9.2 - 2026-09-02
|
|
245
264
|
|
|
@@ -252,7 +271,6 @@ No tracked changes.
|
|
|
252
271
|
|
|
253
272
|
- Finish shell-accurate heredoc and unset handling in publish attestation ([ops-62d1](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-62d1.toon))
|
|
254
273
|
- Repaired the ops-5jp6 history drift that had blocked two stacked release pull requests ([ops-yxej](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-yxej.toon))
|
|
255
|
-
- A case opener sharing its first arm cleared the outer scope and refused a genuinely attested publish ([ops-cout](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-cout.toon))
|
|
256
274
|
- Three shell-scope and quoting fail-opens attest unproven npm publishes ([ops-p9lb](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-p9lb.toon))
|
|
257
275
|
- A malformed npm reply crashed the release audit, and the docstring already promised it would not ([ops-f5m7](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-f5m7.toon))
|
|
258
276
|
- The revert-proof test read its vulnerable fixture from origin/main, so merging it would have turned it red ([ops-9ktn](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-9ktn.toon))
|
|
@@ -265,10 +283,7 @@ No tracked changes.
|
|
|
265
283
|
### Security
|
|
266
284
|
|
|
267
285
|
- A heredoc body and a discarded binding both let an unattested publish pass the attestation gate ([ops-5jp6](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-5jp6.toon))
|
|
268
|
-
- Four more fail modes in the canonical gate: an arm pattern read as an opener, an escaped run key read as data, a sequence marker missing from the indent, and composite actions unscanned ([ops-cxrx](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-cxrx.toon))
|
|
269
|
-
- Attributing a case arm label by presence rather than position refused an attested publish, and a quoted key hid a phantom one ([ops-setc](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-setc.toon))
|
|
270
286
|
- An arm that opens a nested case skipped the sibling reset, so a publish could borrow a flag from a mutually exclusive arm ([ops-rsbn](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-rsbn.toon))
|
|
271
|
-
- Skipping the sibling-arm reset for any depth-increasing segment let a later arm borrow the previous arm's binding ([ops-narm](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-narm.toon))
|
|
272
287
|
- A tracked executable whose name merely ends in package.json has its publish hidden from the audit ([ops-fnbd](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-fnbd.toon))
|
|
273
288
|
- A case opener sharing a segment with its first arm leaks that arm's binding past esac ([ops-csop](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-csop.toon))
|
|
274
289
|
- Branch-local and compound-line publish bindings let an unattested npm publish pass the attestation gate ([ops-brsc](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-brsc.toon))
|
|
@@ -278,22 +293,32 @@ No tracked changes.
|
|
|
278
293
|
|
|
279
294
|
- Converge the pinned pm-cli on 2026.8.31 and repair history hashes ([ops-uulf](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-uulf.toon))
|
|
280
295
|
|
|
296
|
+
### Closed
|
|
297
|
+
|
|
298
|
+
- Closed: Four more fail modes in the canonical gate: an arm pattern read as an opener, an escaped run key read as data, a sequence marker missing from the indent, and composite actions unscanned ([ops-cxrx](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-cxrx.toon))
|
|
299
|
+
- Closed: Attributing a case arm label by presence rather than position refused an attested publish, and a quoted key hid a phantom one ([ops-setc](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-setc.toon))
|
|
300
|
+
- Closed: Skipping the sibling-arm reset for any depth-increasing segment let a later arm borrow the previous arm's binding ([ops-narm](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-narm.toon))
|
|
301
|
+
- Closed: A case opener sharing its first arm cleared the outer scope and refused a genuinely attested publish ([ops-cout](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-cout.toon))
|
|
302
|
+
|
|
281
303
|
## 2026.8.31 - 2026-08-31
|
|
282
304
|
|
|
283
|
-
###
|
|
305
|
+
### Closed
|
|
284
306
|
|
|
285
|
-
- The release changelog remained Unreleased after the release tag was created ([ops-3ete](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-3ete.toon))
|
|
307
|
+
- Closed: The release changelog remained Unreleased after the release tag was created ([ops-3ete](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-3ete.toon))
|
|
286
308
|
|
|
287
309
|
## 2026.8.29 - 2026-08-29
|
|
288
310
|
|
|
289
311
|
### Fixed
|
|
290
312
|
|
|
291
313
|
- Prevent a failed provenance publish from silently falling back to an unattested publish ([ops-w3ke](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-w3ke.toon))
|
|
292
|
-
- Harden literal scalar assignment parsing ([ops-mjnd](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-mjnd.toon))
|
|
293
314
|
- Escaped shell metacharacter in scalar value bypasses the attestation gate ([ops-5mv7](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-5mv7.toon))
|
|
294
|
-
- Shell scalar assignments were read from raw text, so a comment could make an unattested publish pass the attestation gate ([ops-q6wi](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-q6wi.toon))
|
|
295
315
|
- A multi-line fixture joined with a literal backslash-n made the array-flag case pass without exercising it ([ops-xmb6](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-xmb6.toon))
|
|
296
316
|
|
|
317
|
+
### Closed
|
|
318
|
+
|
|
319
|
+
- Closed: Harden literal scalar assignment parsing ([ops-mjnd](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-mjnd.toon))
|
|
320
|
+
- Closed: Shell scalar assignments were read from raw text, so a comment could make an unattested publish pass the attestation gate ([ops-q6wi](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-q6wi.toon))
|
|
321
|
+
|
|
297
322
|
## 2026.8.28 - 2026-08-28
|
|
298
323
|
|
|
299
324
|
### Fixed
|
|
@@ -303,18 +328,21 @@ No tracked changes.
|
|
|
303
328
|
- The changelog gate stamps an untagged version with the current date, so its verdict flips every midnight with no commit ([ops-vll0](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-vll0.toon))
|
|
304
329
|
- Canonicalize fleet metric reads and enforce the pm 2026.8.20 host contract ([ops-3w9m](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-3w9m.toon))
|
|
305
330
|
|
|
306
|
-
###
|
|
331
|
+
### Closed
|
|
307
332
|
|
|
308
|
-
- The identity gate deadlocks the one remediation its own failure message prescribes ([ops-wsi9](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-wsi9.toon))
|
|
333
|
+
- Closed: The identity gate deadlocks the one remediation its own failure message prescribes ([ops-wsi9](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-wsi9.toon))
|
|
309
334
|
|
|
310
335
|
## 2026.8.17 - 2026-08-17
|
|
311
336
|
|
|
312
337
|
### Fixed
|
|
313
338
|
|
|
314
|
-
- merge-receipts labels two canonical fence patterns as stale, inviting someone to delete extension merge protection ([ops-github-db3225403a4b-44](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-github-db3225403a4b-44.toon))
|
|
315
339
|
- The pm CLI compatibility floor was declared only in peerDependencies, which only npm enforces, and not in manifest.json pm_min_version, which is the field the CLI enforces ([ops-zl7a](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-zl7a.toon))
|
|
316
340
|
- A truncated list-all answer corrupts fleet throughput and cycle-time metrics ([ops-x3wc](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-x3wc.toon))
|
|
317
341
|
|
|
342
|
+
### Closed
|
|
343
|
+
|
|
344
|
+
- Closed: merge-receipts labels two canonical fence patterns as stale, inviting someone to delete extension merge protection ([ops-github-db3225403a4b-44](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-github-db3225403a4b-44.toon))
|
|
345
|
+
|
|
318
346
|
## 2026.8.16 - 2026-08-16
|
|
319
347
|
|
|
320
348
|
### Added
|
|
@@ -430,14 +458,14 @@ No tracked changes.
|
|
|
430
458
|
|
|
431
459
|
## 2026.7.23 - 2026-07-23
|
|
432
460
|
|
|
433
|
-
### Fixed
|
|
434
|
-
|
|
435
|
-
- Recommend pm merge reconcile (2026.7.22) over raw history-repair in Multi-agent merge safety docs ([ops-owhy](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-owhy.toon))
|
|
436
|
-
|
|
437
461
|
### Other
|
|
438
462
|
|
|
439
463
|
- Adopt pm field-aware merge driver for multi-agent branch-merge safety ([ops-3ype](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-3ype.toon))
|
|
440
464
|
|
|
465
|
+
### Closed
|
|
466
|
+
|
|
467
|
+
- Closed: Recommend pm merge reconcile (2026.7.22) over raw history-repair in Multi-agent merge safety docs ([ops-owhy](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-owhy.toon))
|
|
468
|
+
|
|
441
469
|
## 2026.7.22 - 2026-07-22
|
|
442
470
|
|
|
443
471
|
No tracked changes.
|
|
@@ -483,9 +511,7 @@ No tracked changes.
|
|
|
483
511
|
|
|
484
512
|
## 2026.7.10 - 2026-07-10
|
|
485
513
|
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
- Fix manifest: add schema capability so registerCommand flags load (extension failed to activate) ([ops-tg86](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/tasks/ops-tg86.toon))
|
|
514
|
+
No tracked changes.
|
|
489
515
|
|
|
490
516
|
## 2026.7.7 - 2026-07-07
|
|
491
517
|
|
package/README.md
CHANGED
|
@@ -33,7 +33,7 @@ activation.
|
|
|
33
33
|
|
|
34
34
|
### Without git
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
Compatibility explanations, tracker metrics, policy checks and file-based reports work in plain directories.
|
|
37
37
|
GitHub probes, release inventory/repair and changelog generation from tags need a
|
|
38
38
|
git repository and their provider tools. Git-only checks do not certify a plain
|
|
39
39
|
tracker as a release checkout.
|
|
@@ -648,8 +648,8 @@ The repository changelog scripts require Git for release-tag windows and refuse
|
|
|
648
648
|
plain-directory trackers with an explicit diagnostic. The changelog adapter can
|
|
649
649
|
still generate directly from tracker items when invoked without tag flags.
|
|
650
650
|
|
|
651
|
-
|
|
652
|
-
reports and docstring analysis work in plain directories. The witness, capability and
|
|
651
|
+
Compatibility explanations, diagnostic witnesses, evidence expiry, backend capability diagnostics, scan, policy, status, outdated, audit, metrics,
|
|
652
|
+
reports and docstring analysis work in plain directories. The compatibility, witness, capability and
|
|
653
653
|
evidence expiry paths never invoke Git. Release verification runs package-defined
|
|
654
654
|
scripts, which may
|
|
655
655
|
need Git; GitHub queries need their own credentials and network access. Configure
|
|
@@ -662,6 +662,9 @@ membership to the pinned generator, then renders empty sections as
|
|
|
662
662
|
generator currently hardcodes `No changes.` and has no empty-message option.
|
|
663
663
|
Every tag gets one section, including consecutive empty releases and same-day
|
|
664
664
|
suffixes; a pending release also gets its section before its tag exists.
|
|
665
|
+
The adapter omits an empty `Unreleased` window above release history, so creating
|
|
666
|
+
the release tag does not change the committed changelog. Nonempty unreleased
|
|
667
|
+
work stays visible, and empty version sections retain their notes.
|
|
665
668
|
Regenerating main cannot change changelogs inside historical release commits.
|
|
666
669
|
|
|
667
670
|
## Operational evidence expiry
|
|
@@ -828,3 +831,86 @@ See the [SDK contract and example](docs/diagnostic-witnesses.md) and the
|
|
|
828
831
|
|
|
829
832
|
Witness reduction works without Git, including when Git is absent from PATH.
|
|
830
833
|
It reads only the selected input file and never reads or changes tracker state.
|
|
834
|
+
|
|
835
|
+
## Compatibility reason chains
|
|
836
|
+
|
|
837
|
+
`pm ops compatibility --input docs/examples/compatibility.json --json` explains
|
|
838
|
+
joint package, host and extension requirements. TOON is the default; both formats
|
|
839
|
+
preserve nested arrays and nulls. The example's three pins are pairwise compatible
|
|
840
|
+
but jointly contradictory. The report names exactly `pin-a`, `pin-b`, `pin-c` as
|
|
841
|
+
the minimum conflict, with `compatible_ranges: []`. Removing any one leaves a
|
|
842
|
+
compatible version. It also reports observed pin failures and missing capabilities,
|
|
843
|
+
with directed upstream declaration chains for each reason.
|
|
844
|
+
|
|
845
|
+
This is a read-only metadata preview. `commands` contains literal argv previews
|
|
846
|
+
for version and extension discovery; the package never executes them, resolves
|
|
847
|
+
packages, installs dependencies or changes configuration. Core remains authoritative
|
|
848
|
+
for extension admission. This command works without Git and never opens a tracker.
|
|
849
|
+
|
|
850
|
+
```ts
|
|
851
|
+
import { explainCompatibility, type CompatibilityInput } from "pm-ops/compatibility-reasons";
|
|
852
|
+
|
|
853
|
+
const metadata: CompatibilityInput = {
|
|
854
|
+
version: 1,
|
|
855
|
+
components: [
|
|
856
|
+
{ id: "package", version: "1.0.0", capabilities: [] },
|
|
857
|
+
{ id: "host", version: "2026.10.20", capabilities: ["commands"] },
|
|
858
|
+
],
|
|
859
|
+
requirements: [{ id: "host-peer", from: "package", to: "host",
|
|
860
|
+
range: ">=2026.10.20", capabilities: ["commands"],
|
|
861
|
+
manifest: { pm_min_version: "2026.10.20" } }],
|
|
862
|
+
};
|
|
863
|
+
const report = explainCompatibility(metadata);
|
|
864
|
+
```
|
|
865
|
+
|
|
866
|
+
Every `range` uses npm semver semantics, including prerelease admission.
|
|
867
|
+
`compatible_ranges` is an OR of inner arrays; **every** range in an inner array
|
|
868
|
+
must hold. Keeping conjunctions separate preserves each declaration's prerelease
|
|
869
|
+
rules. A range can itself contain `||`; when expansion exceeds 16 alternatives,
|
|
870
|
+
one conjunction retains the original ranges exactly to keep output compact.
|
|
871
|
+
Joint version contradictions use exact minimum-cardinality subsets;
|
|
872
|
+
observed pin/support conflicts additionally rely on the target metadata shown in
|
|
873
|
+
the row. The report retains one minimum witness for a pin failure and all missing
|
|
874
|
+
capabilities. Optional native `manifest` bounds are independently evaluated through
|
|
875
|
+
`checkExtensionManifestCompatibility`, the SDK helper shared with core. They are
|
|
876
|
+
reported separately from the joint npm range intersection; include the declared
|
|
877
|
+
supported npm range explicitly in `range`.
|
|
878
|
+
|
|
879
|
+
Joint decisions use semver's `Range`, `intersects`, `minVersion`, `inc` and
|
|
880
|
+
validated observations/declarations. The solver never constructs numeric or
|
|
881
|
+
prerelease successor strings. Every derived library value is parsed again before
|
|
882
|
+
it can support a decision. A rejected value produces a typed
|
|
883
|
+
`UnrepresentableRangeReason` with `code: "unrepresentable_range"`, the rejected
|
|
884
|
+
range/conjunction and a remedy; it never proves a joint conflict. A valid observed
|
|
885
|
+
witness can establish a conjunction without deriving a successor, including
|
|
886
|
+
maximum-length prereleases. An independently verified installed-pin, capability
|
|
887
|
+
or native-bound conflict still remains visible alongside incomplete evidence.
|
|
888
|
+
|
|
889
|
+
A proven empty intersection survives failures while reducing its witness. The
|
|
890
|
+
search records each rejected subset and continues through the other candidates.
|
|
891
|
+
The minimum concerns parsed npm-range declarations; missing or unsupported range
|
|
892
|
+
declarations remain separately listed as unknown.
|
|
893
|
+
If smaller subsets remain undecided, `minimum_unproven: true` marks the retained
|
|
894
|
+
conflict: the contradiction is proven, while global minimum cardinality is not.
|
|
895
|
+
An undecided full set still searches for a provably conflicting subset. Within
|
|
896
|
+
an OR expression, an independently proven nonempty branch remains available even
|
|
897
|
+
when another branch cannot be represented; an unknown branch never proves emptiness.
|
|
898
|
+
|
|
899
|
+
`null` means unknown metadata; `[]` means a known empty capability declaration,
|
|
900
|
+
and `*` means a declared unrestricted range. Tags, workspace/file protocols,
|
|
901
|
+
unparseable versions and missing metadata produce `unknown`, never a fabricated
|
|
902
|
+
incompatibility. Known conflicts take precedence while unknown reasons stay visible.
|
|
903
|
+
Each target is evaluated independently. A package's arbitrary capability labels
|
|
904
|
+
are declared metadata, independent of backend probes or core's admission policy.
|
|
905
|
+
|
|
906
|
+
The strict version 1 schema accepts 1–16 unique components and 1–12 unique directed
|
|
907
|
+
requirements, 1–96 character public ids, strings of at most 256 characters, and at
|
|
908
|
+
most 16 unique capabilities per declaration. Input arrays must be dense, unknown
|
|
909
|
+
keys are refused, and files must be regular JSON no larger than 64 KiB. Up to 256
|
|
910
|
+
expanded alternatives per target bound the exact search. Cycles terminate; a
|
|
911
|
+
rootless cycle retains the local declaration. Typed `CompatibilityRefusal` errors
|
|
912
|
+
carry `code`, `remedy` and usage exit code 2. `ok` is false for unknown or
|
|
913
|
+
incompatible rows; a completed explanation still exits successfully so agents
|
|
914
|
+
should inspect `ok` and row status. Counts are checked for finite integer bounds.
|
|
915
|
+
|
|
916
|
+
See the [public tracker and packed validation](docs/compatibility-validation.md).
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import type { ExtensionManifestCompatibilityCode } from "@unbrained/pm-cli/sdk/authoring";
|
|
2
|
+
/** Explicit metadata; null means unknown, while an empty capability list means known empty. */
|
|
3
|
+
export interface CompatibilityComponent {
|
|
4
|
+
/** Public metadata identity, independent of package resolution or paths. */
|
|
5
|
+
id: string;
|
|
6
|
+
/** Observed exact semantic version, or null when unavailable. */
|
|
7
|
+
version: string | null;
|
|
8
|
+
/** Exhaustive declared support, or null when unavailable. */
|
|
9
|
+
capabilities: string[] | null;
|
|
10
|
+
}
|
|
11
|
+
/** One directed declaration from a package or extension to its dependency or host. */
|
|
12
|
+
export interface CompatibilityRequirement {
|
|
13
|
+
/** Unique declaration identity. */
|
|
14
|
+
id: string;
|
|
15
|
+
/** Declaring component. */
|
|
16
|
+
from: string;
|
|
17
|
+
/** Required component. */
|
|
18
|
+
to: string;
|
|
19
|
+
/** npm semantic version range; null is unknown, * is explicitly unrestricted. */
|
|
20
|
+
range: string | null;
|
|
21
|
+
/** Required capabilities; null is unknown, [] explicitly requires none. */
|
|
22
|
+
capabilities: string[] | null;
|
|
23
|
+
/** Optional native extension bounds, evaluated by the public SDK against the target. */
|
|
24
|
+
manifest?: {
|
|
25
|
+
pm_min_version?: string;
|
|
26
|
+
pm_max_version?: string;
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
/** Versioned strict input; at most 16 components and 12 requirements. */
|
|
30
|
+
export interface CompatibilityInput {
|
|
31
|
+
/** Input contract version. */
|
|
32
|
+
version: 1;
|
|
33
|
+
/** Unique observed components. */
|
|
34
|
+
components: CompatibilityComponent[];
|
|
35
|
+
/** Unique directed declarations; cycles are permitted. */
|
|
36
|
+
requirements: CompatibilityRequirement[];
|
|
37
|
+
}
|
|
38
|
+
/** Actionable refusal that never includes supplied paths or raw parser errors. */
|
|
39
|
+
export declare class CompatibilityRefusal extends Error {
|
|
40
|
+
/** Stable machine-readable classification. */
|
|
41
|
+
readonly code: "invalid_compatibility_input" | "compatibility_input_unreadable" | "invalid_compatibility_output" | "compatibility_sdk_unavailable";
|
|
42
|
+
/** Safe recovery guidance. */
|
|
43
|
+
readonly remedy: string;
|
|
44
|
+
/** Invalid input is a usage error. */
|
|
45
|
+
readonly exitCode = 2;
|
|
46
|
+
/** Construct a sanitized refusal. */
|
|
47
|
+
constructor(code: CompatibilityRefusal["code"], remedy: string);
|
|
48
|
+
}
|
|
49
|
+
/** One established conflict; minimum cardinality is certified unless explicitly unproven. */
|
|
50
|
+
export interface CompatibilityConflict {
|
|
51
|
+
/** Joint declarations, observed pin, capability declaration, or native admission finding. */
|
|
52
|
+
code: "joint_range_conflict" | "installed_pin_conflict" | "capability_conflict" | "extension_bound_conflict";
|
|
53
|
+
/** Exact declaration ids; installed pin/support is explicit in the row's component. */
|
|
54
|
+
requirements: string[];
|
|
55
|
+
/** Conflicting capability or native SDK code, if relevant. */
|
|
56
|
+
detail: string;
|
|
57
|
+
/** A smaller candidate was unrepresentable; the retained contradiction is still proven. */
|
|
58
|
+
minimum_unproven?: true;
|
|
59
|
+
}
|
|
60
|
+
/** A rejected library value is incomplete evidence, never proof of an empty version domain. */
|
|
61
|
+
export interface UnrepresentableRangeReason {
|
|
62
|
+
/** Declaration that could not be evaluated. */
|
|
63
|
+
requirement: string;
|
|
64
|
+
/** Stable discriminant for conservative domain refusals. */
|
|
65
|
+
code: "unrepresentable_range";
|
|
66
|
+
/** Exact range or conjunction the library could not represent. */
|
|
67
|
+
range: string;
|
|
68
|
+
/** Safe action without installs or configuration edits. */
|
|
69
|
+
remedy: string;
|
|
70
|
+
}
|
|
71
|
+
/** Metadata gaps and native SDK advisories remain distinct from range representation failures. */
|
|
72
|
+
export type CompatibilityUnknownReason = UnrepresentableRangeReason | {
|
|
73
|
+
/** Declaration owning the incomplete evidence. */
|
|
74
|
+
requirement: string;
|
|
75
|
+
/** Missing metadata or the native SDK's own diagnostic. */
|
|
76
|
+
code: "range_unknown" | "version_unknown" | "capabilities_unknown" | ExtensionManifestCompatibilityCode;
|
|
77
|
+
};
|
|
78
|
+
/** Compact explanation for a component with incoming constraints. */
|
|
79
|
+
export interface CompatibilityRow {
|
|
80
|
+
/** Observed target metadata, including unknowns. */
|
|
81
|
+
component: CompatibilityComponent;
|
|
82
|
+
/** Incompatibility takes precedence; unknowns remain visible independently. */
|
|
83
|
+
status: "compatible" | "incompatible" | "unknown";
|
|
84
|
+
/** OR of conjunctions (all ranges in each inner array must hold). Preserves npm prerelease rules. */
|
|
85
|
+
compatible_ranges: string[][] | null;
|
|
86
|
+
/** Proven witnesses per conflict dimension; uncertain global minima are explicitly marked. */
|
|
87
|
+
conflicts: CompatibilityConflict[];
|
|
88
|
+
/** Declaration ids with incomplete metadata and a reason code. */
|
|
89
|
+
unknown: CompatibilityUnknownReason[];
|
|
90
|
+
/** Deterministic shortest upstream paths ending at relevant declarations; ids refer to declarations. */
|
|
91
|
+
chains: string[][];
|
|
92
|
+
/** Next safe step; never an authorization or automatic change. */
|
|
93
|
+
remedy: string;
|
|
94
|
+
}
|
|
95
|
+
/** Bounded report; ok means every declared check is compatible, never admission authorization. */
|
|
96
|
+
export interface CompatibilityReport {
|
|
97
|
+
/** Report contract version. */
|
|
98
|
+
version: 1;
|
|
99
|
+
/** True only with no conflicts or unknowns. */
|
|
100
|
+
ok: boolean;
|
|
101
|
+
/** Evaluation is observational. */
|
|
102
|
+
preview: true;
|
|
103
|
+
/** Complete declarations so every reason chain is self-contained. */
|
|
104
|
+
requirements: CompatibilityRequirement[];
|
|
105
|
+
/** One row per referenced target, sorted by id. */
|
|
106
|
+
rows: CompatibilityRow[];
|
|
107
|
+
/** Finite bounded outcome counts. */
|
|
108
|
+
counts: {
|
|
109
|
+
compatible: number;
|
|
110
|
+
incompatible: number;
|
|
111
|
+
unknown: number;
|
|
112
|
+
};
|
|
113
|
+
/** Literal argv previews, never executed. */
|
|
114
|
+
commands: string[][];
|
|
115
|
+
}
|
|
116
|
+
/** One strict structural schema shared by SDK and file producers; metadata text stays verbatim. */
|
|
117
|
+
export declare function parseCompatibilityInput(value: unknown): CompatibilityInput;
|
|
118
|
+
/** Check every emitted numeric field before returning a successful report. */
|
|
119
|
+
export declare function validateCompatibilityCounts(counts: CompatibilityReport["counts"], rowCount: number): void;
|
|
120
|
+
/** Explain joint declarations without loading extensions, invoking commands or touching tracker state. */
|
|
121
|
+
export declare function explainCompatibility(value: unknown): CompatibilityReport;
|
|
122
|
+
/** Read at most 64 KiB of regular JSON; no shell, Git, installs or configuration edits. */
|
|
123
|
+
export declare function readCompatibilityReasons(path: string): CompatibilityReport;
|
|
124
|
+
//# sourceMappingURL=compatibility-reasons.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"compatibility-reasons.d.ts","sourceRoot":"","sources":["../compatibility-reasons.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAsH,kCAAkC,EAAE,MAAM,iCAAiC,CAAC;AAqB9M,+FAA+F;AAC/F,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,iEAAiE;IACjE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAC/B;AAED,sFAAsF;AACtF,MAAM,WAAW,wBAAwB;IACvC,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,iFAAiF;IACjF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC9B,wFAAwF;IACxF,QAAQ,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED,yEAAyE;AACzE,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,kCAAkC;IAClC,UAAU,EAAE,sBAAsB,EAAE,CAAC;IACrC,0DAA0D;IAC1D,YAAY,EAAE,wBAAwB,EAAE,CAAC;CAC1C;AAED,kFAAkF;AAClF,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,6BAA6B,GAAG,gCAAgC,GAAG,8BAA8B,GAAG,+BAA+B,CAAC;IACnJ,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,KAAK;IACtB,qCAAqC;IACrC,YAAY,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAE7D;CACF;AAED,6FAA6F;AAC7F,MAAM,WAAW,qBAAqB;IACpC,6FAA6F;IAC7F,IAAI,EAAE,sBAAsB,GAAG,wBAAwB,GAAG,qBAAqB,GAAG,0BAA0B,CAAC;IAC7G,uFAAuF;IACvF,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,gBAAgB,CAAC,EAAE,IAAI,CAAC;CACzB;AAED,+FAA+F;AAC/F,MAAM,WAAW,0BAA0B;IACzC,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,IAAI,EAAE,uBAAuB,CAAC;IAC9B,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kGAAkG;AAClG,MAAM,MAAM,0BAA0B,GAAG,0BAA0B,GAAG;IACpE,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,sBAAsB,GAAG,kCAAkC,CAAC;CACzG,CAAC;AAEF,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,SAAS,EAAE,sBAAsB,CAAC;IAClC,+EAA+E;IAC/E,MAAM,EAAE,YAAY,GAAG,cAAc,GAAG,SAAS,CAAC;IAClD,qGAAqG;IACrG,iBAAiB,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC;IACrC,8FAA8F;IAC9F,SAAS,EAAE,qBAAqB,EAAE,CAAC;IACnC,kEAAkE;IAClE,OAAO,EAAE,0BAA0B,EAAE,CAAC;IACtC,wGAAwG;IACxG,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;IACnB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kGAAkG;AAClG,MAAM,WAAW,mBAAmB;IAClC,+BAA+B;IAC/B,OAAO,EAAE,CAAC,CAAC;IACX,+CAA+C;IAC/C,EAAE,EAAE,OAAO,CAAC;IACZ,mCAAmC;IACnC,OAAO,EAAE,IAAI,CAAC;IACd,qEAAqE;IACrE,YAAY,EAAE,wBAAwB,EAAE,CAAC;IACzC,mDAAmD;IACnD,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,qCAAqC;IACrC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC;CACtB;AA6BD,mGAAmG;AACnG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CA+B1E;AAwJD,8EAA8E;AAC9E,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQzG;AAED,0GAA0G;AAC1G,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CA+DxE;AAED,2FAA2F;AAC3F,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAM1E"}
|