pm-ops 2026.10.27 → 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 +45 -25
- package/README.md +86 -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,15 @@
|
|
|
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
|
+
|
|
3
13
|
## 2026.10.27 - 2026-10-27
|
|
4
14
|
|
|
5
15
|
### Other
|
|
@@ -44,12 +54,9 @@ No tracked changes.
|
|
|
44
54
|
### Fixed
|
|
45
55
|
|
|
46
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))
|
|
47
|
-
- Fix release publish-before-protected-main-push ordering ([ops-gitr](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-gitr.toon))
|
|
48
|
-
- 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))
|
|
49
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))
|
|
50
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))
|
|
51
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))
|
|
52
|
-
- 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))
|
|
53
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))
|
|
54
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))
|
|
55
62
|
- Duplication gate scans generated PM extension copies ([ops-to4t](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-to4t.toon))
|
|
@@ -63,6 +70,12 @@ No tracked changes.
|
|
|
63
70
|
- Enable GitHub CodeQL code scanning ([ops-jasw](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-jasw.toon))
|
|
64
71
|
- Characterize pre-existing fleet workflow scanner refusals ([ops-0u7l](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/tasks/ops-0u7l.toon))
|
|
65
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
|
+
|
|
66
79
|
## 2026.10.21 - 2026-10-21
|
|
67
80
|
|
|
68
81
|
No tracked changes.
|
|
@@ -214,9 +227,9 @@ No tracked changes.
|
|
|
214
227
|
|
|
215
228
|
## 2026.9.8 - 2026-09-08
|
|
216
229
|
|
|
217
|
-
###
|
|
230
|
+
### Closed
|
|
218
231
|
|
|
219
|
-
- 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))
|
|
220
233
|
|
|
221
234
|
## 2026.9.7 - 2026-09-07
|
|
222
235
|
|
|
@@ -243,9 +256,9 @@ No tracked changes.
|
|
|
243
256
|
|
|
244
257
|
## 2026.9.5 - 2026-09-05
|
|
245
258
|
|
|
246
|
-
###
|
|
259
|
+
### Closed
|
|
247
260
|
|
|
248
|
-
- 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))
|
|
249
262
|
|
|
250
263
|
## 2026.9.2 - 2026-09-02
|
|
251
264
|
|
|
@@ -258,7 +271,6 @@ No tracked changes.
|
|
|
258
271
|
|
|
259
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))
|
|
260
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))
|
|
261
|
-
- 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))
|
|
262
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))
|
|
263
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))
|
|
264
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))
|
|
@@ -271,10 +283,7 @@ No tracked changes.
|
|
|
271
283
|
### Security
|
|
272
284
|
|
|
273
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))
|
|
274
|
-
- 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))
|
|
275
|
-
- 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))
|
|
276
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))
|
|
277
|
-
- 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))
|
|
278
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))
|
|
279
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))
|
|
280
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))
|
|
@@ -284,22 +293,32 @@ No tracked changes.
|
|
|
284
293
|
|
|
285
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))
|
|
286
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
|
+
|
|
287
303
|
## 2026.8.31 - 2026-08-31
|
|
288
304
|
|
|
289
|
-
###
|
|
305
|
+
### Closed
|
|
290
306
|
|
|
291
|
-
- 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))
|
|
292
308
|
|
|
293
309
|
## 2026.8.29 - 2026-08-29
|
|
294
310
|
|
|
295
311
|
### Fixed
|
|
296
312
|
|
|
297
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))
|
|
298
|
-
- Harden literal scalar assignment parsing ([ops-mjnd](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-mjnd.toon))
|
|
299
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))
|
|
300
|
-
- 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))
|
|
301
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))
|
|
302
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
|
+
|
|
303
322
|
## 2026.8.28 - 2026-08-28
|
|
304
323
|
|
|
305
324
|
### Fixed
|
|
@@ -309,18 +328,21 @@ No tracked changes.
|
|
|
309
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))
|
|
310
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))
|
|
311
330
|
|
|
312
|
-
###
|
|
331
|
+
### Closed
|
|
313
332
|
|
|
314
|
-
- 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))
|
|
315
334
|
|
|
316
335
|
## 2026.8.17 - 2026-08-17
|
|
317
336
|
|
|
318
337
|
### Fixed
|
|
319
338
|
|
|
320
|
-
- 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))
|
|
321
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))
|
|
322
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))
|
|
323
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
|
+
|
|
324
346
|
## 2026.8.16 - 2026-08-16
|
|
325
347
|
|
|
326
348
|
### Added
|
|
@@ -436,14 +458,14 @@ No tracked changes.
|
|
|
436
458
|
|
|
437
459
|
## 2026.7.23 - 2026-07-23
|
|
438
460
|
|
|
439
|
-
### Fixed
|
|
440
|
-
|
|
441
|
-
- 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))
|
|
442
|
-
|
|
443
461
|
### Other
|
|
444
462
|
|
|
445
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))
|
|
446
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
|
+
|
|
447
469
|
## 2026.7.22 - 2026-07-22
|
|
448
470
|
|
|
449
471
|
No tracked changes.
|
|
@@ -489,9 +511,7 @@ No tracked changes.
|
|
|
489
511
|
|
|
490
512
|
## 2026.7.10 - 2026-07-10
|
|
491
513
|
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
- 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.
|
|
495
515
|
|
|
496
516
|
## 2026.7.7 - 2026-07-07
|
|
497
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
|
|
@@ -831,3 +831,86 @@ See the [SDK contract and example](docs/diagnostic-witnesses.md) and the
|
|
|
831
831
|
|
|
832
832
|
Witness reduction works without Git, including when Git is absent from PATH.
|
|
833
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"}
|