@thomasminh1995/depverdict 0.6.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (252) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +518 -0
  3. package/bin/depverdict.js +7 -0
  4. package/bin/upgradelens.js +7 -0
  5. package/docs/GR-01-Semantic-Grounding-Failure-Analysis.md +309 -0
  6. package/docs/GR-02-Versioned-Action-Evaluation-Criteria.md +187 -0
  7. package/docs/GR-03-Extractive-Contract-Safety-Experiment.md +242 -0
  8. package/docs/GR-04-Versioned-Production-Extractive-Contract.md +154 -0
  9. package/docs/IA-01-Repository-Usage-Discovery.md +122 -0
  10. package/docs/IA-02-Repository-Impact-Analysis.md +118 -0
  11. package/docs/IA-03-Repository-Impact-Evidence.md +160 -0
  12. package/docs/IA-04-CLI-Orchestration.md +235 -0
  13. package/docs/IA-05-Real-Provider-Validation.md +235 -0
  14. package/docs/IA-05-VinGrade-Validation.md +339 -0
  15. package/docs/MVP-01.md +48 -0
  16. package/docs/MVP-02-Architecture.md +536 -0
  17. package/docs/MVP-02-CLI-HTTP-Runtime.md +50 -0
  18. package/docs/MVP-02-HTTP-Lifecycle.md +37 -0
  19. package/docs/MVP-02-Knowledge-Manifest-Generation.md +75 -0
  20. package/docs/MVP-02-Knowledge-Manifest.md +279 -0
  21. package/docs/MVP-02-Knowledge-Research-Orchestration.md +62 -0
  22. package/docs/MVP-02-Knowledge-Store.md +87 -0
  23. package/docs/MVP-02-PyPI-Registry-Adapter.md +97 -0
  24. package/docs/MVP-02-Research-Planning.md +196 -0
  25. package/docs/MVP-02-Source-Provenance.md +81 -0
  26. package/docs/MVP-02-npm-Registry-Adapter.md +99 -0
  27. package/docs/RR-01-End-to-End-and-Real-Provider-Validation.md +393 -0
  28. package/docs/RR-01-RERUN-Extractive-Contract-Validation.md +566 -0
  29. package/docs/RR-02-Full-Product-Workflow-and-Developer-CLI-UX-Review.md +35 -0
  30. package/docs/RR02-FIX-01-Persistent-Qualification-Resolution.md +32 -0
  31. package/docs/RR02-FIX-02-Stage-aware-CLI-Progress-and-Heartbeat.md +28 -0
  32. package/docs/RR02-FIX-03-npm-Capture-Evidence-Exclusion.md +33 -0
  33. package/docs/RR02-FIX-03A-Complete-Package-Exclusion-and-Evidence-Commit.md +223 -0
  34. package/docs/RR02-FIX-04-Event-loop-safe-Heartbeat.md +393 -0
  35. package/docs/RR02-FIX-05-Materialize-Persisted-Qualification.md +207 -0
  36. package/docs/RR02-RERUN-CLI-Qualification-Progress-UX-and-Package-Validation.md +342 -0
  37. package/docs/VinGrade-MVP-02-Validation.md +480 -0
  38. package/docs/VinGrade-RC02-Live-Validation.md +273 -0
  39. package/docs/ai-capability-discovery.md +573 -0
  40. package/docs/ai-engineering-production-readiness.md +390 -0
  41. package/docs/ai-engineering-review.md +251 -0
  42. package/docs/ai-runtime-governance-discovery.md +754 -0
  43. package/docs/architecture-overview.md +78 -0
  44. package/docs/cli-progress.md +111 -0
  45. package/docs/decisions/diff-01-brand-distribution-identity.md +450 -0
  46. package/docs/decisions/diff-02-identity-compatibility-contract.md +274 -0
  47. package/docs/decisions/diff-03-repository-docs-community-migration.md +165 -0
  48. package/docs/decisions/diff-04-release-evidence-gap-acceptance.md +110 -0
  49. package/docs/discovery/mvp-05-ai-migration-planning-discovery.md +350 -0
  50. package/docs/gateway-runtime-discovery.md +614 -0
  51. package/docs/live-ai-validation.md +299 -0
  52. package/docs/migration-planning-qualification-resolution.md +99 -0
  53. package/docs/migrations/upgradelens-to-depverdict.md +97 -0
  54. package/docs/mp-r03-deterministic-upgrade-decision-architecture.md +135 -0
  55. package/docs/mp-r04-evidence-bounded-migration-handoff-architecture.md +116 -0
  56. package/docs/mp-r05-product-completion-and-decision-first-cli-architecture.md +162 -0
  57. package/docs/mvp-05-deterministic-context-runtime.md +127 -0
  58. package/docs/mvp-05-migration-checklist-contract.md +166 -0
  59. package/docs/mvp-05-migration-checklist-orchestration.md +105 -0
  60. package/docs/mvp-05-migration-evaluation-and-qualification.md +135 -0
  61. package/docs/mvp-05-provider-neutral-generator.md +79 -0
  62. package/docs/ollama-local-smoke-validation.md +156 -0
  63. package/docs/openai-compatible-runtime-discovery.md +789 -0
  64. package/docs/openrouter-one-dependency-validation.md +205 -0
  65. package/docs/oss-02-package-guard-hardening-architecture.md +131 -0
  66. package/docs/oss-04-public-ci-package-metadata-architecture.md +142 -0
  67. package/docs/package-content-policy.md +98 -0
  68. package/docs/releases/v0.5.0-technical-preview.md +114 -0
  69. package/docs/releases/v0.6.0-alpha.1-depverdict-preview.md +101 -0
  70. package/docs/reviews/diff-02-identity-contract-compatibility.md +413 -0
  71. package/docs/reviews/diff-03-repository-docs-community-migration.md +364 -0
  72. package/docs/reviews/diff-04-depverdict-distribution-identity-readiness-rereview.md +453 -0
  73. package/docs/reviews/diff-04-fix-post-rename-identity-release-remediation.md +310 -0
  74. package/docs/reviews/diff-05-final-preview-distribution-qualification.md +561 -0
  75. package/docs/reviews/mvp-05-final-product-value-workflow-rereview.md +471 -0
  76. package/docs/reviews/mvp-05-product-workflow-review.md +605 -0
  77. package/docs/reviews/oss-01-duplicate-artifact-investigation-cleanup.md +411 -0
  78. package/docs/reviews/oss-02-package-guard-hardening.md +303 -0
  79. package/docs/reviews/oss-03-community-scaffolding.md +378 -0
  80. package/docs/reviews/oss-04-public-ci-package-metadata.md +439 -0
  81. package/docs/reviews/oss-05-technical-preview-qualification.md +482 -0
  82. package/docs/reviews/upgradelens-vs-upgradedepdetective-source-comparison.md +355 -0
  83. package/docs/reviews/v0.5.0-pre-release-smoke.md +263 -0
  84. package/docs/reviews/v0.5.0-version-bump-release-verification.md +306 -0
  85. package/docs/runtime-contract-discovery.md +521 -0
  86. package/docs/structured-output-compatibility-report.md +100 -0
  87. package/docs/ts-fix-01-exact-duplicate-occurrence-target-selection-architecture.md +111 -0
  88. package/docs/version-analysis-architecture.md +827 -0
  89. package/eval/README.md +86 -0
  90. package/eval/datasets/generic/declared-constraint.json +59 -0
  91. package/eval/datasets/generic/evidence-conflict.json +73 -0
  92. package/eval/datasets/generic/major-breaking-release.json +66 -0
  93. package/eval/datasets/generic/missing-evidence.json +46 -0
  94. package/eval/datasets/generic/patch-release-low.json +59 -0
  95. package/eval/datasets/node/axios-patch-low.json +59 -0
  96. package/eval/datasets/node/react-major-breaking.json +66 -0
  97. package/eval/datasets/node/react-minor-compatibility.json +66 -0
  98. package/eval/datasets/python/fastapi-deprecation.json +66 -0
  99. package/eval/datasets/python/pydantic-major-breaking.json +66 -0
  100. package/eval/migration-planning/golden-dataset-v2.json +306 -0
  101. package/eval/migration-planning/golden-dataset.json +214 -0
  102. package/eval/schemas/expected-result.schema.json +88 -0
  103. package/eval/schemas/golden-case.schema.json +181 -0
  104. package/package.json +57 -0
  105. package/schemas/ai-scorecard.schema.json +132 -0
  106. package/schemas/benchmark-report.schema.json +189 -0
  107. package/schemas/benchmark.schema.json +55 -0
  108. package/schemas/capability-profile.schema.json +44 -0
  109. package/schemas/conformance-report.schema.json +150 -0
  110. package/schemas/deployment-profile.schema.json +64 -0
  111. package/schemas/evaluation-report.schema.json +158 -0
  112. package/schemas/knowledge-evidence-bundle.schema.json +150 -0
  113. package/schemas/knowledge-manifest.schema.json +548 -0
  114. package/schemas/metrics.schema.json +178 -0
  115. package/schemas/migration-checklist-extractive-candidate.schema.json +42 -0
  116. package/schemas/migration-checklist.schema.json +706 -0
  117. package/schemas/migration-evaluation-dataset-v2.schema.json +208 -0
  118. package/schemas/migration-evaluation-dataset.schema.json +204 -0
  119. package/schemas/migration-planning-qualification-record.schema.json +234 -0
  120. package/schemas/project-manifest.schema.json +308 -0
  121. package/schemas/qualification-record.schema.json +56 -0
  122. package/schemas/repository-impact-evidence.schema.json +232 -0
  123. package/schemas/repository-impact.schema.json +202 -0
  124. package/schemas/upgrade-decision.schema.json +273 -0
  125. package/schemas/usage-index.schema.json +179 -0
  126. package/schemas/version-analysis.schema.json +449 -0
  127. package/src/ai-runtime-debug.js +325 -0
  128. package/src/ai-runtime-error.js +42 -0
  129. package/src/ai-runtime.js +174 -0
  130. package/src/ai-scorecard.js +204 -0
  131. package/src/ai-version-analysis.js +484 -0
  132. package/src/artifact-root-compatibility.js +91 -0
  133. package/src/benchmark-report.js +111 -0
  134. package/src/benchmark-runner.js +191 -0
  135. package/src/canonical-json.js +69 -0
  136. package/src/cli.js +1299 -0
  137. package/src/conformance-report.js +158 -0
  138. package/src/conformance-runner.js +253 -0
  139. package/src/constants.js +73 -0
  140. package/src/cooperative-scheduler.js +79 -0
  141. package/src/dependencies.js +44 -0
  142. package/src/dependency-ai-context.js +625 -0
  143. package/src/detectors.js +253 -0
  144. package/src/discovery.js +234 -0
  145. package/src/ecosystem-version-adapter.js +294 -0
  146. package/src/environment-compatibility.js +77 -0
  147. package/src/evaluation-comparator.js +158 -0
  148. package/src/evaluation-report.js +76 -0
  149. package/src/evaluation-runner.js +248 -0
  150. package/src/evidence-source-adapter.js +472 -0
  151. package/src/files.js +89 -0
  152. package/src/governance-diagnostics.js +64 -0
  153. package/src/governance-loader.js +63 -0
  154. package/src/governance-metadata.js +346 -0
  155. package/src/governance-validator.js +360 -0
  156. package/src/http/bounded-fetch.js +278 -0
  157. package/src/http/cli-http-runtime.js +44 -0
  158. package/src/impact/input-loader.js +157 -0
  159. package/src/impact/matcher.js +40 -0
  160. package/src/impact/repository-impact.js +199 -0
  161. package/src/impact/runtime.js +24 -0
  162. package/src/impact/status.js +62 -0
  163. package/src/impact/writer.js +30 -0
  164. package/src/impact-evidence/input-loader.js +202 -0
  165. package/src/impact-evidence/repository-impact-evidence.js +234 -0
  166. package/src/impact-evidence/runtime.js +16 -0
  167. package/src/impact-evidence/writer.js +30 -0
  168. package/src/index.js +563 -0
  169. package/src/installed-version-baseline.js +196 -0
  170. package/src/knowledge-cache.js +324 -0
  171. package/src/knowledge-evidence-bundle.js +101 -0
  172. package/src/knowledge-evidence-producer.js +233 -0
  173. package/src/knowledge-manifest-builder.js +188 -0
  174. package/src/knowledge-manifest-writer.js +32 -0
  175. package/src/knowledge-manifest.js +255 -0
  176. package/src/knowledge-research.js +615 -0
  177. package/src/metrics-engine.js +205 -0
  178. package/src/migration-checklist/ai-candidate.js +320 -0
  179. package/src/migration-checklist/assembler.js +37 -0
  180. package/src/migration-checklist/context-runtime.js +828 -0
  181. package/src/migration-checklist/evaluation/action-criteria.js +244 -0
  182. package/src/migration-checklist/evaluation/comparator-v2.js +332 -0
  183. package/src/migration-checklist/evaluation/comparator.js +279 -0
  184. package/src/migration-checklist/evaluation/dataset-v2.js +227 -0
  185. package/src/migration-checklist/evaluation/dataset.js +336 -0
  186. package/src/migration-checklist/evaluation/extractive-fixtures-v2.js +148 -0
  187. package/src/migration-checklist/evaluation/metrics-v2.js +226 -0
  188. package/src/migration-checklist/evaluation/metrics.js +158 -0
  189. package/src/migration-checklist/evaluation/qualification-v2.js +321 -0
  190. package/src/migration-checklist/evaluation/qualification.js +239 -0
  191. package/src/migration-checklist/evaluation/runner-v2.js +294 -0
  192. package/src/migration-checklist/evaluation/runner.js +194 -0
  193. package/src/migration-checklist/evaluation/scorecard-v2.js +106 -0
  194. package/src/migration-checklist/evaluation/scorecard.js +86 -0
  195. package/src/migration-checklist/extractive-candidate.js +166 -0
  196. package/src/migration-checklist/extractive-prompt.js +62 -0
  197. package/src/migration-checklist/generator.js +702 -0
  198. package/src/migration-checklist/grounding-policy.js +117 -0
  199. package/src/migration-checklist/input-loader.js +613 -0
  200. package/src/migration-checklist/migration-checklist.js +635 -0
  201. package/src/migration-checklist/presentation.js +292 -0
  202. package/src/migration-checklist/progress.js +96 -0
  203. package/src/migration-checklist/prompt.js +83 -0
  204. package/src/migration-checklist/qualification-guard.js +462 -0
  205. package/src/migration-checklist/qualification-resolution.js +122 -0
  206. package/src/migration-checklist/qualification-store.js +225 -0
  207. package/src/migration-checklist/runtime.js +205 -0
  208. package/src/migration-checklist/verification.js +134 -0
  209. package/src/migration-checklist/writer.js +35 -0
  210. package/src/openai-compatible-provider.js +451 -0
  211. package/src/orchestration/failure-log.js +32 -0
  212. package/src/orchestration/pipeline.js +200 -0
  213. package/src/orchestration/progress-events.js +337 -0
  214. package/src/orchestration/progress-reporter.js +131 -0
  215. package/src/orchestration/text-writer.js +22 -0
  216. package/src/portable.js +13 -0
  217. package/src/product-completion.js +249 -0
  218. package/src/project-manifest-input.js +90 -0
  219. package/src/project-manifest.js +141 -0
  220. package/src/python-requirements.js +137 -0
  221. package/src/registry/npm-packument.js +256 -0
  222. package/src/registry/npm-registry-adapter.js +262 -0
  223. package/src/registry/pypi-project.js +300 -0
  224. package/src/registry/pypi-registry-adapter.js +235 -0
  225. package/src/registry/sanitize-registry-body.js +51 -0
  226. package/src/renderers/console.js +160 -0
  227. package/src/renderers/impact-presentation.js +278 -0
  228. package/src/renderers/markdown.js +172 -0
  229. package/src/research-plan.js +455 -0
  230. package/src/runtime-conformance.js +275 -0
  231. package/src/source-provenance.js +393 -0
  232. package/src/source-url.js +62 -0
  233. package/src/structured-output-schema.js +66 -0
  234. package/src/target-selector.js +306 -0
  235. package/src/upgrade-decision/input-loader.js +107 -0
  236. package/src/upgrade-decision/presentation.js +43 -0
  237. package/src/upgrade-decision/runtime.js +21 -0
  238. package/src/upgrade-decision/upgrade-decision.js +626 -0
  239. package/src/upgrade-decision/writer.js +30 -0
  240. package/src/usage/analyzer-registry.js +63 -0
  241. package/src/usage/coverage.js +116 -0
  242. package/src/usage/input-loader.js +139 -0
  243. package/src/usage/js/analyzer.js +240 -0
  244. package/src/usage/js/parser.js +21 -0
  245. package/src/usage/runtime.js +187 -0
  246. package/src/usage/scope.js +44 -0
  247. package/src/usage/source-files.js +50 -0
  248. package/src/usage/usage-index.js +217 -0
  249. package/src/usage/writer.js +31 -0
  250. package/src/version-analysis-loader.js +203 -0
  251. package/src/version-analysis-manifest.js +314 -0
  252. package/src/version-analysis-writer.js +30 -0
@@ -0,0 +1,114 @@
1
+ # UpgradeLens v0.5.0 — Public Technical Preview / Alpha
2
+
3
+ UpgradeLens v0.5.0 is a decision-first CLI for evidence-bounded dependency upgrade
4
+ analysis. This release is a Technical Preview: its contracts may change, support is
5
+ best effort, and every result requires developer judgment.
6
+
7
+ ## Preview installation
8
+
9
+ The recommended publication strategy is the npm `preview` dist-tag. After the
10
+ maintainer completes that separate release action, install without moving npm
11
+ `latest`:
12
+
13
+ ```sh
14
+ npm install -g upgradelens@preview
15
+ upgradelens --version
16
+ upgradelens --help
17
+ ```
18
+
19
+ Before publication, or when evaluating the exact repository source:
20
+
21
+ ```sh
22
+ git clone https://github.com/thomasMinh1995/UpgradeLens.git
23
+ cd UpgradeLens
24
+ npm install
25
+ node ./bin/upgradelens.js --version
26
+ ```
27
+
28
+ ## Try the zero-secret sample
29
+
30
+ The repository contains a public-safe Node sample with an exact declared dependency,
31
+ a lockfile-installed baseline, and real source usage:
32
+
33
+ ```sh
34
+ upgradelens discover examples/technical-preview-node --stdout
35
+ upgradelens analyze examples/technical-preview-node --offline --stdout
36
+ ```
37
+
38
+ No provider credential is needed. With no fresh local knowledge cache, the expected
39
+ offline completion is `INSUFFICIENT_DATA`: UpgradeLens retains the installed
40
+ baseline and refuses to invent a registry target or evidence. Read the
41
+ [sample guide](../../examples/technical-preview-node/README.md) before trying the
42
+ optional provider-configured workflow.
43
+
44
+ ## What v0.5.0 provides
45
+
46
+ - deterministic Node and Python project/dependency discovery;
47
+ - npm/PyPI research with bounded source provenance;
48
+ - installed npm baseline resolution from package-lock v2/v3 and limited v1 roots;
49
+ - AI-assisted, schema-validated Version Analysis behind a provider-neutral boundary;
50
+ - JavaScript/TypeScript source-usage and coverage-aware impact analysis;
51
+ - occurrence-scoped deterministic Upgrade Decisions;
52
+ - copy/paste-ready selectors for duplicate dependency occurrences;
53
+ - decision-first completion states and stable CLI exit semantics;
54
+ - an experimental, opt-in, qualification-bound, human-reviewed Migration
55
+ Checklist handoff.
56
+
57
+ A registry-latest version is candidate discovery, not a recommendation driver.
58
+ A caller can select an exact target and occurrence, but UpgradeLens still requires
59
+ sufficient evidence and review before producing an actionable handoff.
60
+
61
+ ## Supported scope and known limitations
62
+
63
+ The primary supported path is Node projects and workspaces using npm lockfiles.
64
+ Python requirements discovery, PyPI research, and bounded PEP 440 comparison are
65
+ available, but Python installed environments and source usage are not resolved.
66
+ pnpm and Yarn installed baselines are unsupported. JavaScript/TypeScript is the only
67
+ source-usage analyzer. Other detected ecosystems fail closed and should not be
68
+ interpreted as fully supported.
69
+
70
+ Offline mode uses only valid local, cached, and persisted facts. It may produce
71
+ `INSUFFICIENT_DATA` or a review-required result. Provider/model quality is not
72
+ identical across runtimes, and a Migration Checklist qualification applies only to
73
+ the exact machine-readable identity recorded.
74
+
75
+ UpgradeLens is not production-stable, a security scanner, a safety certification,
76
+ or an autonomous migration tool. It does not modify source, install dependency
77
+ upgrades, execute suggested verification commands, or synthesize recovery steps
78
+ without structured evidence.
79
+
80
+ ## Human-review boundary
81
+
82
+ Developers own target selection, approval, source changes, command execution,
83
+ verification, and recovery. Migration Checklist actions are evidence-bounded
84
+ proposals, are disabled by default, and always require human review. A generated
85
+ artifact is not permission to patch a repository or proof that migration succeeded.
86
+
87
+ ## Validation summary
88
+
89
+ The qualification snapshot passed hosted GitHub Actions on Node 20, 22, and 24,
90
+ including canonical tests, package guard, and Node 24 package smoke. An isolated
91
+ clean checkout passed 632 tests with one unchanged sandbox-loopback skip. Repeated
92
+ actual packs were byte-identical; clean tarball installation, CLI version/help, ESM
93
+ import, and 438 public exports passed. No provider secret or uploaded CI artifact
94
+ was used.
95
+
96
+ ## Tell us what works and what does not
97
+
98
+ Please evaluate:
99
+
100
+ 1. Are decisions understandable and actionable?
101
+ 2. Is `INVESTIGATE` too frequent or too rare?
102
+ 3. Are installed baselines correct in real npm workspaces and monorepos?
103
+ 4. Is duplicate-occurrence ambiguity and copy/paste selector UX usable?
104
+ 5. Are coverage limitations clear enough to prevent false confidence?
105
+ 6. Does the migration handoff reduce re-research for developers or Coding Agents?
106
+ 7. Are completion states and exit codes useful in CI?
107
+ 8. Which artifacts help code review and team planning?
108
+
109
+ Use the repository bug or feature forms described in
110
+ [Support](../../SUPPORT.md). Report vulnerabilities only through
111
+ [GitHub Private Vulnerability Reporting](../../SECURITY.md), and report sensitive
112
+ conduct concerns through the private contact in the
113
+ [Code of Conduct](../../CODE_OF_CONDUCT.md). Never post credentials, private source,
114
+ full private artifacts, or raw provider payloads.
@@ -0,0 +1,101 @@
1
+ # DepVerdict v0.6.0-alpha.1 — Technical Preview / Alpha
2
+
3
+ > Release draft — not yet published status is not asserted by this source.
4
+ > Verify live npm and GitHub Release availability independently.
5
+
6
+ DepVerdict is a decision-first CLI for evidence-bounded dependency upgrade
7
+ analysis. This preview adopts a clearer identity for a product that evaluates
8
+ whether and why an upgrade should proceed, instead of treating the existence of a
9
+ newer registry version as a recommendation.
10
+
11
+ ## Planned installation
12
+
13
+ When registry metadata confirms availability under the `preview` dist-tag,
14
+ install with:
15
+
16
+ ```sh
17
+ npm install -g @thomasminh1995/depverdict@preview
18
+ ```
19
+
20
+ This release note does not claim that the preview package is currently available
21
+ and does not use or promise the npm `latest` tag.
22
+
23
+ The canonical executable is:
24
+
25
+ ```sh
26
+ depverdict analyze .
27
+ ```
28
+
29
+ ## Identity transition
30
+
31
+ | Surface | Canonical | `0.6.x` preview compatibility |
32
+ | --- | --- | --- |
33
+ | npm package | `@thomasminh1995/depverdict` | The old npm package was never successfully published. |
34
+ | CLI | `depverdict` | `upgradelens` remains as a warning alias for one `0.6.x` preview window. |
35
+ | Artifact root | `.depverdict/` | `.upgradelens/` is a complete-chain read fallback; new writes use the canonical root. |
36
+ | Environment | `DEPVERDICT_*` | `UPGRADELENS_*` remains a warning fallback; canonical keys win. |
37
+
38
+ The GitHub repository rename is complete. Repository, issue, and private security
39
+ links use the canonical `thomasMinh1995/DepVerdict` repository directly.
40
+
41
+ ## Why the rebrand
42
+
43
+ The DepVerdict name emphasizes the product's actual boundary: it produces a
44
+ deterministic, inspectable decision and an optional evidence-bounded handoff. It is
45
+ not merely an available-update detector and does not claim autonomous migration.
46
+
47
+ ## Key capabilities
48
+
49
+ - declared, installed, and target versions remain separate facts;
50
+ - npm and PyPI target knowledge and evidence research;
51
+ - exact dependency-occurrence selection for ambiguous repositories;
52
+ - deterministic Upgrade Decision with structured reason codes;
53
+ - coverage-aware JavaScript/TypeScript usage and impact analysis;
54
+ - explicit completion states and CI exit behavior;
55
+ - offline research with honest missing-evidence limitations;
56
+ - experimental, opt-in Migration Checklist v2 for reviewed handoff to a developer
57
+ or Coding Agent.
58
+
59
+ Registry latest is target discovery, not a recommendation driver. Decisions fail
60
+ closed when target intent, installed baseline, evidence, version comparison, or
61
+ analyzer coverage is insufficient.
62
+
63
+ ## Supported scope
64
+
65
+ The preview supports Node `package.json` projects and workspaces, Python
66
+ `requirements.txt` discovery, npm and PyPI research, npm lockfile v2/v3 installed
67
+ baselines, a bounded Python version subset, and JavaScript/TypeScript source usage
68
+ analysis. Detector presence for another ecosystem does not imply end-to-end
69
+ support.
70
+
71
+ ## Human-review boundary
72
+
73
+ DepVerdict does not modify manifests, install dependencies, patch source, execute
74
+ suggested verification commands, approve a migration, or certify safety. Migration
75
+ Checklist remains experimental and opt-in. Every proposed action and target
76
+ requires authoritative human review, and a Coding Agent must reopen current source
77
+ before proposing changes.
78
+
79
+ ## Known limitations
80
+
81
+ - pnpm and Yarn installed-version baselines are not resolved;
82
+ - Python environment and lockfile installed versions are not resolved;
83
+ - source usage coverage is JavaScript/TypeScript-focused;
84
+ - partial or unavailable coverage cannot prove a dependency is unaffected;
85
+ - provider/model qualification is bound to exact runtime and evaluation identity;
86
+ - offline mode cannot invent a target, evidence, confidence, or recommendation;
87
+ - recovery and rollback plans are not synthesized;
88
+ - npm availability and dist-tag state must be verified from the registry.
89
+
90
+ ## Community and private reporting
91
+
92
+ - Security: use the verified GitHub Private Vulnerability Reporting route in
93
+ [SECURITY.md](../../SECURITY.md). It points directly to the canonical DepVerdict
94
+ repository.
95
+ - Conduct: use the verified private address in
96
+ [CODE_OF_CONDUCT.md](../../CODE_OF_CONDUCT.md). The legacy-named address remains
97
+ the active DepVerdict channel for this preview transition.
98
+ - Support: follow [SUPPORT.md](../../SUPPORT.md) for best-effort preview routing.
99
+
100
+ Do not post credentials, private source, complete private artifacts, provider
101
+ payloads, vulnerability details, or sensitive conduct reports publicly.
@@ -0,0 +1,413 @@
1
+ # DIFF-02 — Identity Contract and Compatibility Review
2
+
3
+ ## 1. Executive verdict
4
+
5
+ Verdict: `DEPVERDICT_IDENTITY_COMPATIBILITY_READY`
6
+
7
+ Gate: `PROCEED_TO_DIFF_03_REPOSITORY_DOCS_AND_COMMUNITY_MIGRATION`
8
+
9
+ DepVerdict is now the canonical runtime and package identity. The preview keeps
10
+ one bounded compatibility window for the `upgradelens` executable,
11
+ `UPGRADELENS_*` environment variables, and read-only `.upgradelens/` artifact
12
+ discovery. No schema, provider-qualification identity, historical tag, or
13
+ evidence protocol was generalized or rewritten.
14
+
15
+ ## 2. Brand availability preflight
16
+
17
+ The final read-only preflight ran at `2026-07-19T08:05:34Z`, before runtime
18
+ implementation.
19
+
20
+ - npm returned not-found for exact `depverdict` and
21
+ `@thomasminh1995/depverdict`.
22
+ - The exact future GitHub repository identity returned not-found, and GitHub
23
+ repository search returned zero exact repositories.
24
+ - PyPI and RubyGems returned not-found.
25
+ - No `depverdict` executable was found on the local command path.
26
+ - Exact general-web software, product, company, trademark-signal, and GitHub
27
+ queries returned no material collision.
28
+ - Crates.io returned access denied and unauthenticated GitHub code search
29
+ returned unauthorized, so those two checks are unverified.
30
+ - Domain RDAP not-found responses were treated only as weak signals.
31
+
32
+ Classification: `BRAND_PREFLIGHT_CLEAR_WITH_LOW_RISK`.
33
+
34
+ Availability is time-sensitive, does not reserve any identity, and is not legal
35
+ or trademark advice.
36
+
37
+ ## 3. Identity architecture decision
38
+
39
+ The pre-code decision is
40
+ `docs/decisions/diff-02-identity-compatibility-contract.md`.
41
+
42
+ It separates runtime identity from persisted protocol identity:
43
+
44
+ - runtime presentation: DepVerdict;
45
+ - package: `@thomasminh1995/depverdict`;
46
+ - canonical CLI: `depverdict`;
47
+ - persisted `generator.name`: historical protocol literal `"UpgradeLens"`;
48
+ - structured-output and Migration Planning task/schema identities: unchanged.
49
+
50
+ It also defines whole-chain artifact selection, environment precedence,
51
+ stderr-only diagnostics, explicit-path authority, qualification behavior, and
52
+ criteria for eventually removing compatibility.
53
+
54
+ ## 4. Package and version transition
55
+
56
+ Authoritative metadata now declares:
57
+
58
+ ```text
59
+ @thomasminh1995/depverdict@0.6.0-alpha.1
60
+ ```
61
+
62
+ The lockfile root name, version, and bin map were synchronized without
63
+ dependency, resolved URL, integrity, or transitive lock drift. Repository,
64
+ homepage, and issue URLs still point at the current UpgradeLens repository
65
+ because repository rename is outside DIFF-02.
66
+
67
+ The package remains public-capable and has no embedded publish credential,
68
+ publish hook, or `private` flag. No `publishConfig` was added: public access and
69
+ the non-default `preview` tag are kept as explicit future publish-command
70
+ controls instead of encoding a misleading substitute for dist-tag policy.
71
+
72
+ The description now exposes DepVerdict's decision-first positioning.
73
+
74
+ ## 5. Canonical and legacy CLI contract
75
+
76
+ The package has two executable entries sharing one dispatcher:
77
+
78
+ ```text
79
+ depverdict -> bin/depverdict.js
80
+ upgradelens -> bin/upgradelens.js
81
+ ```
82
+
83
+ Both files have a valid Node shebang and executable mode. The canonical wrapper
84
+ injects canonical invocation identity. The thin legacy wrapper injects only
85
+ legacy invocation identity and does not duplicate or recursively invoke command
86
+ logic.
87
+
88
+ The legacy command emits one warning per process state to stderr. It names both
89
+ commands and the `0.6.x` preview removal window. It does not change stdout or
90
+ exit status. Programmatic `runCli` use is canonical unless legacy invocation is
91
+ explicitly requested.
92
+
93
+ Help, progress heading, console outcome, new Markdown report title, failure
94
+ presentation, error guidance, and user agent now present DepVerdict. Historical
95
+ files and provider prompt/task identities were not rewritten.
96
+
97
+ ## 6. Artifact-root compatibility
98
+
99
+ Every implicit write now uses `.depverdict/`, including manifests, evidence,
100
+ analysis, usage, impact, decision, checklist, report, log, cache, governance,
101
+ conformance, and default qualification paths. Artifact filenames are unchanged.
102
+ Discovery ignores both generated roots.
103
+
104
+ The centralized read resolver implements:
105
+
106
+ 1. complete canonical chain wins;
107
+ 2. complete canonical plus any legacy data emits
108
+ `LEGACY_ARTIFACT_ROOT_IGNORED`;
109
+ 3. complete legacy with no canonical member emits
110
+ `LEGACY_ARTIFACT_ROOT_USED`;
111
+ 4. partial or split availability fails with `ARTIFACT_ROOT_CONFLICT`;
112
+ 5. no artifacts preserves the established canonical missing-input behavior.
113
+
114
+ The resolver never merges, copies, moves, deletes, or timestamp-selects
115
+ artifacts. Explicit CLI/API paths bypass automatic discovery and remain exact,
116
+ including an explicitly selected `.upgradelens/` output.
117
+
118
+ The bounded fallback is applied to Project Manifest research input, the
119
+ three-artifact Version Analysis input chain, the seven-artifact decision and
120
+ Migration Checklist chain, and default Migration Planning qualification.
121
+
122
+ ## 7. Environment compatibility and precedence
123
+
124
+ One resolver owns the complete discovered mapping:
125
+
126
+ | Canonical | Deprecated fallback | Secret-sensitive |
127
+ | --- | --- | --- |
128
+ | `DEPVERDICT_AI_PROVIDER` | `UPGRADELENS_AI_PROVIDER` | No |
129
+ | `DEPVERDICT_AI_ENDPOINT` | `UPGRADELENS_AI_ENDPOINT` | No |
130
+ | `DEPVERDICT_AI_MODEL` | `UPGRADELENS_AI_MODEL` | No |
131
+ | `DEPVERDICT_AI_AUTHORIZATION` | `UPGRADELENS_AI_AUTHORIZATION` | Yes |
132
+ | `DEPVERDICT_AI_TIMEOUT_MS` | `UPGRADELENS_AI_TIMEOUT_MS` | No |
133
+ | `DEPVERDICT_AI_TIMEOUT_SECONDS` | `UPGRADELENS_AI_TIMEOUT_SECONDS` | No |
134
+ | `DEPVERDICT_AI_MAX_RESPONSE_BYTES` | `UPGRADELENS_AI_MAX_RESPONSE_BYTES` | No |
135
+ | `DEPVERDICT_AI_DEBUG` | `UPGRADELENS_AI_DEBUG` | No |
136
+
137
+ Precedence is explicit override, canonical environment, legacy environment,
138
+ then established default. Canonical wins conflicts. Diagnostics name keys only,
139
+ are once-per-key bounded, and never contain values. Unknown identity-prefixed
140
+ variables are discarded. Passing an explicit empty environment remains isolated
141
+ from the host environment.
142
+
143
+ Provider request count, timeout parsing, runtime selection, and debug-output
144
+ contracts remain unchanged after resolution.
145
+
146
+ ## 8. Qualification compatibility
147
+
148
+ Package and product name do not participate in Migration Planning qualification
149
+ identity. Provider, endpoint/adapter, model, dataset, task, prompt, policy,
150
+ schema, and presentation identities remain authoritative and unchanged.
151
+
152
+ The default qualification path moved to `.depverdict/`. A valid legacy record is
153
+ selected intact only when canonical storage is absent. When both exist,
154
+ canonical is selected and legacy is visibly ignored. Explicit paths never fall
155
+ back. Corrupted, tampered, runtime-mismatched, fake-runtime, and matching
156
+ `NOT_QUALIFIED` records retain their fail-closed behavior.
157
+
158
+ No external provider requalification was required or performed.
159
+
160
+ ## 9. Schema and public API preservation
161
+
162
+ Schema versions, filenames, schema IDs, prompt versions, policy versions, task
163
+ IDs, status/reason codes, occurrence identities, evidence IDs, digests, and
164
+ lineage checks did not change.
165
+
166
+ New artifacts still write `generator.name: "UpgradeLens"` because current
167
+ schemas validate that literal. Generator version advances from package metadata
168
+ to `0.6.0-alpha.1`, as already permitted by the schemas. Old fixtures remain
169
+ schema-valid in the full suite.
170
+
171
+ The root ESM API remains 438 exports. No redundant identity helper was promoted
172
+ to the public surface.
173
+
174
+ ## 10. Package guard and CI updates
175
+
176
+ The package guard now requires:
177
+
178
+ - both executable files;
179
+ - both compatibility resolver modules;
180
+ - the DIFF-02 decision and this review;
181
+ - the established runtime, schemas, datasets, and user-facing assets.
182
+
183
+ An untracked protected implementation file is accepted only when it is on this
184
+ exact authoritative required list; other protected untracked files still fail.
185
+ Both `.depverdict/` and `.upgradelens/` runtime output trees are explicitly
186
+ forbidden from the package. Capture, duplicate/copy, credential, environment,
187
+ qualification-record, and local-artifact protections remain active.
188
+
189
+ CI remains read-only and fork-safe on Node 20, 22, and 24. It clears both complete
190
+ environment-prefix sets and runs install, tests, actual-tarball guard, and
191
+ clean-install package smoke. There is no publish, tag, release, writeback, or
192
+ provider-secret step.
193
+
194
+ Package smoke installs the scoped tarball into an isolated consumer, exercises
195
+ the npm-generated canonical and legacy command shims, checks canonical
196
+ help/version with clean stderr and legacy version with its warning, imports the
197
+ scoped ESM package, and verifies 438 exports.
198
+
199
+ ## 11. Focused and adversarial tests
200
+
201
+ Focused coverage proves:
202
+
203
+ - exact canonical name/version/help and clean canonical stderr;
204
+ - bounded legacy command warning, unchanged exit status, and JSON-only
205
+ `--stdout`;
206
+ - canonical/alias artifact equivalence after normalizing only generation time;
207
+ - explicit legacy output authority;
208
+ - canonical, legacy, conflict, and explicit environment precedence without
209
+ secret disclosure or host inheritance;
210
+ - complete canonical/legacy artifact selection and split-chain rejection;
211
+ - no fallback-side file rewrite;
212
+ - valid legacy qualification fallback and canonical qualification precedence;
213
+ - tamper and identity mismatch rejection;
214
+ - exact package metadata and dual-bin tarball/install behavior.
215
+
216
+ The full schema, lineage, tamper, deterministic replay, provider request
217
+ isolation, historical-fixture, and package-policy suites also passed.
218
+
219
+ ## 12. Canonical validation
220
+
221
+ Final source validation:
222
+
223
+ ```text
224
+ npm run check
225
+ tests: 640
226
+ passed: 639
227
+ failed: 0
228
+ skipped: 1
229
+ package guard: passed
230
+ ```
231
+
232
+ The single skip is the established sandbox limitation for a local loopback
233
+ keep-alive test. The related scoped HTTP lifecycle tests and real child-process
234
+ natural-exit test passed.
235
+
236
+ `git diff --check` passed. Lockfile review found only root identity/version and
237
+ the added canonical bin mapping. No dependency integrity changed.
238
+
239
+ ## 13. Actual tarball and clean-install results
240
+
241
+ The qualified filename is:
242
+
243
+ ```text
244
+ thomasminh1995-depverdict-0.6.0-alpha.1.tgz
245
+ ```
246
+
247
+ The final actual-tarball guard reports zero suspicious artifacts and all 25
248
+ required assets. Isolated clean install/extraction succeeds, both executable
249
+ files are mode `0755`, canonical help/version are clean, the alias warns on
250
+ stderr, and scoped import exposes 438 public exports.
251
+
252
+ Repeated `npm pack --dry-run --json --ignore-scripts` runs produce identical
253
+ metadata and integrity for the same source state. No tarball is retained in the
254
+ repository.
255
+
256
+ ## 14. npm publish dry-run and bin normalization
257
+
258
+ An initial npm 11.12.1 dry-run exposed publish normalization of `./bin/...`
259
+ values. This was treated as a real metadata defect, not ignored. The bin values
260
+ were changed to equivalent portable `bin/...` paths.
261
+
262
+ The final command:
263
+
264
+ ```text
265
+ npm publish --dry-run --access public --tag preview --json --ignore-scripts --offline
266
+ ```
267
+
268
+ completed with no auto-correction warning, kept both executable entries and
269
+ files, retained the exact scoped name/version, selected `preview` with public
270
+ access, and performed no registry mutation. No `npm pkg fix` was run.
271
+
272
+ ## 15. Provider-call count
273
+
274
+ External provider calls: `0`.
275
+
276
+ Tests used deterministic fake or local fixture runtimes only. npm registry access
277
+ during isolated consumer installation is package transport, not an AI provider
278
+ call.
279
+
280
+ ## 16. Blocked and skipped checks
281
+
282
+ - Crates.io exact-name availability: unverified because the service returned
283
+ access denied.
284
+ - Unauthenticated GitHub code search: unverified because the API returned
285
+ unauthorized.
286
+ - Hosted CI was not dispatched because DIFF-02 forbids commit and push. The
287
+ workflow contract and local CI-equivalent commands passed.
288
+ - Node 20/22/24 were not separately installed in the local environment; the
289
+ existing matrix remains configured. Validation ran on Node 26.0.0, which
290
+ satisfies the package's `>=20` engine contract.
291
+ - No repository rename, identity reservation, publish, tag, release, or external
292
+ provider qualification was attempted.
293
+
294
+ These are non-critical availability/platform follow-ups and do not undermine
295
+ the implemented compatibility invariants.
296
+
297
+ ## 17. Defects and remaining limitations
298
+
299
+ Resolved defect:
300
+
301
+ - npm publish normalization warned on `./bin/...` and would normalize those
302
+ paths. Using `bin/...` removes the warning and retains both bins.
303
+
304
+ Open Blocker defects: none.
305
+
306
+ Open High defects: none.
307
+
308
+ Remaining Medium limitations:
309
+
310
+ - broad repository, community, historical documentation, and release-text
311
+ migration remains intentionally deferred to DIFF-03;
312
+ - brand availability and legal-risk signals remain time-sensitive;
313
+ - automatic legacy compatibility is preview-bounded and must not be removed
314
+ without satisfying the decision's removal criteria;
315
+ - hosted Node-matrix execution awaits an authorized pushed change.
316
+
317
+ ## 18. Exact files changed or created
318
+
319
+ Package, CLI, CI, and current-use documentation:
320
+
321
+ ```text
322
+ .github/workflows/ci.yml
323
+ README.md
324
+ bin/depverdict.js
325
+ bin/upgradelens.js
326
+ package-lock.json
327
+ package.json
328
+ scripts/ci-package-smoke.mjs
329
+ scripts/package-content-guard.mjs
330
+ ```
331
+
332
+ Runtime:
333
+
334
+ ```text
335
+ src/ai-runtime-debug.js
336
+ src/ai-scorecard.js
337
+ src/artifact-root-compatibility.js
338
+ src/benchmark-report.js
339
+ src/cli.js
340
+ src/conformance-report.js
341
+ src/constants.js
342
+ src/discovery.js
343
+ src/environment-compatibility.js
344
+ src/evaluation-report.js
345
+ src/impact-evidence/repository-impact-evidence.js
346
+ src/impact/repository-impact.js
347
+ src/knowledge-cache.js
348
+ src/knowledge-evidence-producer.js
349
+ src/knowledge-manifest-builder.js
350
+ src/metrics-engine.js
351
+ src/migration-checklist/input-loader.js
352
+ src/migration-checklist/migration-checklist.js
353
+ src/migration-checklist/qualification-resolution.js
354
+ src/migration-checklist/runtime.js
355
+ src/orchestration/failure-log.js
356
+ src/orchestration/progress-reporter.js
357
+ src/renderers/console.js
358
+ src/renderers/markdown.js
359
+ src/upgrade-decision/runtime.js
360
+ src/upgrade-decision/upgrade-decision.js
361
+ src/usage/usage-index.js
362
+ src/version-analysis-loader.js
363
+ src/version-analysis-manifest.js
364
+ ```
365
+
366
+ Tests:
367
+
368
+ ```text
369
+ test/analysis-orchestration.test.js
370
+ test/ci-workflow-metadata.test.js
371
+ test/cli.test.js
372
+ test/discovery.test.js
373
+ test/governance-metadata.test.js
374
+ test/http-lifecycle-cli.test.js
375
+ test/identity-compatibility.test.js
376
+ test/knowledge-manifest-generation.test.js
377
+ test/migration-checklist-contract.test.js
378
+ test/migration-checklist-orchestration.test.js
379
+ test/migration-qualification-resolution.test.js
380
+ test/package-content-guard.test.js
381
+ test/product-completion-cli.test.js
382
+ test/research-plan.test.js
383
+ test/runtime-conformance.test.js
384
+ test/version-analysis-manifest.test.js
385
+ test/version-source.test.js
386
+ test-support/environment.mjs
387
+ ```
388
+
389
+ Decision and review:
390
+
391
+ ```text
392
+ docs/decisions/diff-02-identity-compatibility-contract.md
393
+ docs/reviews/diff-02-identity-contract-compatibility.md
394
+ ```
395
+
396
+ ## 19. Pre-existing changes preserved
397
+
398
+ The task began on `main` at
399
+ `c91fbb0032b0e2f6209cb4a14aeeb68d9cf0c28d`. The origin still points to the
400
+ UpgradeLens repository, and public tags through `v0.5.0` are unchanged.
401
+
402
+ Pre-existing untracked DIFF-01/source-comparison documents, RR02 capture trees,
403
+ and duplicate capture files were left intact. They were not cleaned, rewritten,
404
+ staged, or used as provider input.
405
+
406
+ No commit, merge, tag, push, repository rename, release, or publish was
407
+ performed.
408
+
409
+ ## 20. Final verdict and next gate
410
+
411
+ Verdict: `DEPVERDICT_IDENTITY_COMPATIBILITY_READY`
412
+
413
+ Gate: `PROCEED_TO_DIFF_03_REPOSITORY_DOCS_AND_COMMUNITY_MIGRATION`