@bruc3van/dsh-doctor 0.5.5 → 0.5.7

package/skills/dsh-plugin-upgrade/references/verification.md

@@ -4,12 +4,16 @@
 
 Static analysis covers source/type imports, dependency ranges, client graph declarations, and generated artifacts. A pass means no known blocking finding; it does not execute project code.
 
+The current known static target is the catalog target declared in SKILL.md. When the actual target is later than that catalog ref on the same 0.1.2 release line, first inspect the additional interval, then use `--target-version <version>` at every phase. The report keeps `migration.to` as the catalog ref and records `migration.actualTarget` separately, so a successful dependency or runtime check cannot be mistaken for catalog coverage of the additional API delta.
+
 ## Build
 
 Build and runtime verification require `--yes --install`. The CLI selects the package manager from lockfiles, synchronizes dependencies with dependency lifecycle scripts disabled, records the lockfile hash before and after, and verifies installed DSH/Cordis versions against `dependencies`, `devDependencies`, `peerDependencies`, and `optionalDependencies`. Required peers must resolve and satisfy every declared range. Missing optional dependencies or peers are recorded as `optional-missing`; when installed, they must satisfy their ranges. It then runs declared scripts in this order: `typecheck`, `build`, `test`, `pack:check`, stopping at the first failure. Artifact verification requires a successful `build` or `pack:check`; `typecheck`/`test` alone do not pass this gate.
 
 If dependency installation or resolution verification fails, stop before running project scripts. Review and retain package manifest and lockfile changes with the source migration.
 
+If pnpm's `minimumReleaseAge` blocks a newly published target prerelease, do not disable or weaken the repository-wide supply-chain policy. Confirm the selected target and registry provenance, then add only the exact `package@version` rows required under `minimumReleaseAgeExclude`, including transitive DSH packages reported by pnpm. Review this workspace-policy change alongside the lockfile and report it explicitly.
+
 ## Runtime
 
 Runtime verification:
@@ -24,6 +28,8 @@ The gate also checks the DSH CLI's exact target version, the created profile man
 
 Use a built target Harness CLI through `--harness-root`, or pass `--dsh-command` explicitly. The temporary home is deleted only after a successful run unless `--keep-temp` is set.
 
+The runtime executable must report the exact actual target selected by `--target-version` (or the catalog target when the option is omitted). A later prerelease is not accepted implicitly because that would disconnect the runtime evidence from the reviewed dependency and source target.
+
 ## Behavior
 
 Choose focused checks from the plugin contract: render the real UI, invoke each command, exercise settings, verify service availability, repeat activation/deactivation, check listener cleanup, and cover failure recovery. Record exact commands, screenshots, logs, or tests. This gate is deliberately not inferred by dsh-doctor.

package/src/cli.mjs

@@ -43,7 +43,8 @@ Options:
   --fix, --repair        legacy confirmed repairs (never removes a plugin)
   --yes                  confirm an explicit write or command
   --from <ref>            source DSH ref (default: dsh-v0.1.1-rc.2)
-  --to <ref>              target DSH ref (default: dsh-v0.1.2-alpha.2)
+  --to <ref>              target DSH ref (default: dsh-v0.1.2-alpha.3)
+  --target-version <ver>  actual DSH 0.1.2 version for dependency/runtime checks
   --safe                  restrict migrate apply to catalog-confirmed exact rewrites
   --plan-file <path>      persist or consume the reviewed migrate apply plan
   --level <level>         static, build, or runtime verification
@@ -85,7 +86,8 @@ const HELP_ZH = `用法：
   --fix, --repair        旧式确认修复（绝不移除插件）
   --yes                  确认一个明确的写入或命令动作
   --from <ref>           源 DSH ref（默认：dsh-v0.1.1-rc.2）
-  --to <ref>             目标 DSH ref（默认：dsh-v0.1.2-alpha.2）
+  --to <ref>             目标 DSH ref（默认：dsh-v0.1.2-alpha.3）
+  --target-version <版本> 依赖与 runtime 验证使用的实际 DSH 0.1.2 版本
   --safe                 migrate apply 仅执行 catalog 确认的精确改写
   --plan-file <路径>     保存或读取已审阅的 migrate apply 计划
   --level <级别>        static、build 或 runtime
@@ -146,6 +148,8 @@ function parse(args) {
     else if (arg.startsWith('--from=')) options.from = optionValue(arg, '--from')
     else if (arg === '--to') options.to = valueAfter(args, index++, arg)
     else if (arg.startsWith('--to=')) options.to = optionValue(arg, '--to')
+    else if (arg === '--target-version') options.targetVersion = valueAfter(args, index++, arg)
+    else if (arg.startsWith('--target-version=')) options.targetVersion = optionValue(arg, '--target-version')
     else if (arg === '--safe') options.safe = true
     else if (arg === '--plan-file') options.planFile = valueAfter(args, index++, arg)
     else if (arg.startsWith('--plan-file=')) options.planFile = optionValue(arg, '--plan-file')
@@ -300,7 +304,7 @@ async function main() {
     if (!['analyze', 'apply', 'verify'].includes(options.migrateAction)) throw new Error('migrate needs analyze, apply, or verify')
     if (options.migrateAction === 'apply' && options.safe !== true) throw new Error('migrate apply requires --safe')
     if (options.migrateAction === 'apply' && options.pluginRoot === undefined) throw new Error('migrate apply requires an explicit plugin root')
-    const migrationOptions = { from: options.from, to: options.to, harnessRoot: options.harnessRoot, dshCommand: options.dshCommand, level: options.level, yes: options.yes, safe: options.safe, keepTemp: options.keepTemp, planFile: options.planFile, install: options.install }
+    const migrationOptions = { from: options.from, to: options.to, targetVersion: options.targetVersion, harnessRoot: options.harnessRoot, dshCommand: options.dshCommand, level: options.level, yes: options.yes, safe: options.safe, keepTemp: options.keepTemp, planFile: options.planFile, install: options.install }
     if (options.migrateAction === 'verify') {
       const { formatVerification, verifyMigration } = await import('./migrate-verify.mjs')
       const result = verifyMigration(options.pluginRoot, migrationOptions)

package/src/migrate-verify.mjs

@@ -214,7 +214,8 @@ export function verifyMigration(pluginRoot = process.cwd(), options = {}) {
   const [versionCommand, versionArgs] = dshInvocation(dsh, ['--version'])
   const versionRun = commandResult(versionCommand, versionArgs, { cwd: root, env })
   const actualDshVersion = versionRun.stdout.trim()
-  const versionPassed = versionRun.passed && actualDshVersion === analysis.migration.to.version
+  const expectedDshVersion = analysis.migration.actualTarget.version
+  const versionPassed = versionRun.passed && actualDshVersion === expectedDshVersion
   const pack = commandResult(manager.command, manager.pack(packDir), { cwd: root })
   const tarball = tarballFromPack(pack, packDir)
   const runtimeCommands = []
@@ -236,7 +237,7 @@ export function verifyMigration(pluginRoot = process.cwd(), options = {}) {
   result.stages.push({
     name: 'runtime',
     passed: runtimePassed,
-    dshVersion: { expected: analysis.migration.to.version, actual: actualDshVersion, passed: versionPassed, command: commandEvidence(versionRun) },
+    dshVersion: { expected: expectedDshVersion, catalog: analysis.migration.to.version, actual: actualDshVersion, passed: versionPassed, command: commandEvidence(versionRun) },
     pack: commandEvidence(pack),
     tarball,
     commands: runtimeCommands.map(commandEvidence),

package/src/migrate.mjs

@@ -80,12 +80,17 @@ function moduleLiteral(node) {
 
 function namedImports(node) {
   const bindings = node.importClause?.namedBindings
-  if (!bindings || !ts.isNamedImports(bindings)) return []
-  return bindings.elements.map(item => ({
+  if (bindings && ts.isNamedImports(bindings)) return bindings.elements.map(item => ({
     imported: item.propertyName?.text ?? item.name.text,
     local: item.name.text,
     typeOnly: node.importClause.isTypeOnly || item.isTypeOnly,
   }))
+  if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) return node.exportClause.elements.map(item => ({
+    imported: item.propertyName?.text ?? item.name.text,
+    local: item.name.text,
+    typeOnly: node.isTypeOnly || item.isTypeOnly,
+  }))
+  return []
 }
 
 function quoteModule(text) {
@@ -117,10 +122,11 @@ function analyzeFile(file, pluginRoot, catalog, origin) {
       handledLiterals.add(literal)
       const moduleName = literal.text
       const rootName = packageRoot(moduleName)
-      if (removed.has(rootName)) {
+      const moduleRemoved = removed.has(rootName)
+      const symbolRules = catalog.symbols.modules[moduleName]
+      if (moduleRemoved || symbolRules !== undefined) {
         const where = location(source, literal, pluginRoot)
-        const symbolRules = catalog.symbols.modules[moduleName]
-        const specs = ts.isImportDeclaration(node) ? namedImports(node) : []
+        const specs = namedImports(node)
         const exact = []
         const remaining = []
         for (const spec of specs) {
@@ -128,7 +134,7 @@ function analyzeFile(file, pluginRoot, catalog, origin) {
           if (rule?.confidence === 'exact') {
             exact.push({ ...spec, imported: rule.toSymbol, toModule: rule.toModule, fromSymbol: spec.imported, reason: rule.reason })
             findings.push({ code: 'MIG_MOVED_SYMBOL', severity: 'error', message: `${spec.imported} moved to ${rule.toModule}`, location: where, evidence: { module: moduleName, symbol: spec.imported, targetModule: rule.toModule, replacement: rule.toSymbol }, autoFix: 'safe' })
-          } else {
+          } else if (rule?.confidence === 'semantic' || moduleRemoved) {
             remaining.push(spec)
             const semantic = rule?.confidence === 'semantic'
             findings.push({ code: semantic ? 'MIG_SEMANTIC_API_CHANGE' : 'MIG_REMOVED_PACKAGE_REFERENCE', severity: 'error', message: semantic ? `${spec.imported} requires a semantic migration: ${rule.reason}` : `${moduleName} was removed without a safe automatic replacement`, location: where, evidence: { module: moduleName, ...(spec.imported ? { symbol: spec.imported } : {}) }, autoFix: 'none' })
@@ -140,7 +146,7 @@ function analyzeFile(file, pluginRoot, catalog, origin) {
               ...(rule?.toSymbol ? { targetSymbol: rule.toSymbol } : {}),
               reason: rule?.reason ?? 'No exact replacement is known.',
             })
-          }
+          } else remaining.push(spec)
         }
         const declarationText = ts.isImportDeclaration(node) ? text.slice(node.getStart(source), node.getEnd()) : ''
         const simpleNamedImport = exact.length > 0 && ts.isImportDeclaration(node) && node.importClause?.namedBindings && ts.isNamedImports(node.importClause.namedBindings) && node.importClause.name === undefined && node.attributes === undefined && node.assertClause === undefined && !/\/(?:\/|\*)/.test(declarationText)
@@ -160,7 +166,7 @@ function analyzeFile(file, pluginRoot, catalog, origin) {
           const generated = [...groups].map(([target, items]) => importText(target, items, node.importClause.isTypeOnly))
           if (remaining.length > 0) generated.unshift(importText(moduleName, remaining, node.importClause.isTypeOnly))
           replacements.push({ start: node.getStart(source), end: node.getEnd(), next: generated.join('\n'), exact })
-        } else if (specs.length === 0 || exact.length > 0) {
+        } else if (moduleRemoved && (specs.length === 0 || exact.length > 0)) {
           for (const finding of findings) if (finding.code === 'MIG_MOVED_SYMBOL' && finding.location.line === where.line && exact.some(item => item.fromSymbol === finding.evidence.symbol)) finding.autoFix = 'none'
           findings.push({ code: 'MIG_REMOVED_PACKAGE_REFERENCE', severity: 'error', message: `${moduleName} was removed and this reference cannot be rewritten safely`, location: where, evidence: { module: moduleName, kind: ts.SyntaxKind[node.kind] }, autoFix: 'none' })
           unresolved.push({ file: where.file, package: rootName, module: moduleName, reason: 'Default, namespace, side-effect, export, require, dynamic import, or module augmentation reference.' })
@@ -189,12 +195,28 @@ function readManifest(pluginRoot) {
   return { file, value, text }
 }
 
-function targetVersion(name, catalog) {
+function actualTargetVersion(catalog, requested) {
+  if (requested === undefined) return catalog.manifest.to.version
+  const version = semver.valid(requested)
+  if (version === null) throw new Error(`--target-version must be an exact semantic version, received ${requested}`)
+  const catalogVersion = semver.parse(catalog.manifest.to.version)
+  const target = semver.parse(version)
+  if (catalogVersion === null || target === null || target.major !== catalogVersion.major || target.minor !== catalogVersion.minor || target.patch !== catalogVersion.patch) {
+    throw new Error(`--target-version ${requested} is outside the catalog's ${catalogVersion?.major}.${catalogVersion?.minor}.${catalogVersion?.patch} release line`)
+  }
+  if (semver.lt(target, catalogVersion)) {
+    throw new Error(`--target-version ${requested} predates the catalog target ${catalog.manifest.to.version}`)
+  }
+  return version
+}
+
+function targetVersion(name, catalog, actualTarget) {
+  if (name.startsWith('@deepseek-ai/dsh-')) return actualTarget
   if (catalog.packages.targetVersions?.[name] !== undefined) return catalog.packages.targetVersions[name]
-  return name.startsWith('@deepseek-ai/dsh-') ? catalog.manifest.to.version : undefined
+  return undefined
 }
 
-function manifestFindings(manifest, catalog) {
+function manifestFindings(manifest, catalog, actualTarget) {
   const findings = []
   for (const field of DEPENDENCY_FIELDS) {
     const dependencyMap = manifest.value[field]
@@ -207,7 +229,7 @@ function manifestFindings(manifest, catalog) {
         findings.push({ code: 'MIG_REMOVED_PACKAGE_REFERENCE', severity: 'error', message: `${field}.${name} targets a removed package`, location: { file: 'package.json' }, evidence: { field, package: name, range }, autoFix: 'conditional' })
         continue
       }
-      const target = targetVersion(name, catalog)
+      const target = targetVersion(name, catalog, actualTarget)
       if (target === undefined) continue
       const validRange = typeof range === 'string' ? semver.validRange(range) : null
       if (validRange === null) findings.push({ code: 'MIG_INVALID_DEPENDENCY_RANGE', severity: 'error', message: `${field}.${name} has a non-registry range that cannot prove target compatibility`, location: { file: 'package.json' }, evidence: { field, package: name, range, target }, autoFix: field === 'devDependencies' ? 'safe' : 'none' })
@@ -307,7 +329,7 @@ function patchTargetFindings(pluginRoot, manifest, harness) {
   return findings
 }
 
-function planManifest(manifest, sourceResults, artifactResults, opaqueReferences, catalog) {
+function planManifest(manifest, sourceResults, artifactResults, opaqueReferences, catalog, actualTarget) {
   const next = structuredClone(manifest.value)
   const exactTargets = sourceResults.flatMap(result => result.exactTargets)
   const sourceReferences = new Set(sourceResults.flatMap(result => result.remainingPackages))
@@ -323,14 +345,14 @@ function planManifest(manifest, sourceResults, artifactResults, opaqueReferences
     }
     if (field === 'devDependencies') {
       for (const [name, range] of Object.entries(deps)) {
-        const target = targetVersion(name, catalog)
+        const target = targetVersion(name, catalog, actualTarget)
         if (target !== undefined && !catalog.packages.removed.includes(name) && (semver.validRange(range) === null || !semver.satisfies(target, range))) deps[name] = target
       }
     }
   }
   for (const move of new Map(exactTargets.map(item => [`${item.relationship}\0${item.toPackage}`, item])).values()) {
     const fields = catalog.packages.dependencyPolicies?.[move.toPackage]?.[move.relationship]
-    const version = targetVersion(move.toPackage, catalog)
+    const version = targetVersion(move.toPackage, catalog, actualTarget)
     if (!Array.isArray(fields) || version === undefined) continue
     for (const field of fields) {
       if (!DEPENDENCY_FIELDS.includes(field)) throw new Error(`migration catalog has an invalid dependency field ${field}`)
@@ -369,7 +391,8 @@ function analysisInputs(root) {
 export function analyzeMigration(pluginRoot = process.cwd(), options = {}) {
   const root = resolve(pluginRoot)
   if (!statSync(root).isDirectory()) throw new Error(`plugin root is not a directory: ${root}`)
-  const catalog = loadMigration(options.from ?? 'dsh-v0.1.1-rc.2', options.to ?? 'dsh-v0.1.2-alpha.2')
+  const catalog = loadMigration(options.from ?? 'dsh-v0.1.1-rc.2', options.to ?? 'dsh-v0.1.2-alpha.3')
+  const actualTarget = actualTargetVersion(catalog, options.targetVersion)
   const harness = verifyHarnessCheckout(catalog, options.harnessRoot)
   const manifest = readManifest(root)
   const sourceFiles = walk(root, SOURCE_DIRS_TO_SKIP).filter(file => !isTopLevelArtifact(root, file))
@@ -378,10 +401,10 @@ export function analyzeMigration(pluginRoot = process.cwd(), options = {}) {
   const opaqueReferences = opaqueReferenceFindings(root, sourceFiles, manifest, catalog)
   const sourceRemoved = sources.some(item => item.findings.some(finding => ['MIG_REMOVED_PACKAGE_REFERENCE', 'MIG_SEMANTIC_API_CHANGE', 'MIG_MOVED_SYMBOL'].includes(finding.code)))
   const artifactRemoved = artifacts.some(item => item.findings.some(finding => ['MIG_REMOVED_PACKAGE_REFERENCE', 'MIG_SEMANTIC_API_CHANGE', 'MIG_MOVED_SYMBOL'].includes(finding.code)))
-  const findings = [...manifestFindings(manifest, catalog), ...patchTargetFindings(root, manifest, harness), ...sources.flatMap(item => item.findings), ...opaqueReferences.findings, ...artifacts.flatMap(item => item.findings)]
+  const findings = [...manifestFindings(manifest, catalog, actualTarget), ...patchTargetFindings(root, manifest, harness), ...sources.flatMap(item => item.findings), ...opaqueReferences.findings, ...artifacts.flatMap(item => item.findings)]
   if (!sourceRemoved && artifactRemoved) findings.push({ code: 'MIG_SOURCE_ARTIFACT_DRIFT', severity: 'error', message: 'built artifacts still reference removed APIs although source files do not', location: { file: '.' }, evidence: { artifactDirectories: ARTIFACT_DIRS }, autoFix: 'none' })
   findings.push({ code: 'MIG_RUNTIME_VERIFICATION_REQUIRED', severity: 'info', message: 'static analysis cannot prove activation and lifecycle behavior; run migrate verify --level runtime', location: { file: '.' }, evidence: {}, autoFix: 'none' })
-  const manifestPlan = planManifest(manifest, sources, artifacts, opaqueReferences.packages, catalog)
+  const manifestPlan = planManifest(manifest, sources, artifacts, opaqueReferences.packages, catalog, actualTarget)
   const changed = [...sources.filter(item => item.changed), ...(manifestPlan.changed ? [manifestPlan] : [])]
   const safeEdits = changed.map(item => ({
     file: relativePath(root, item.file),
@@ -393,14 +416,21 @@ export function analyzeMigration(pluginRoot = process.cwd(), options = {}) {
   return {
     schemaVersion: 1,
     command: 'migrate analyze',
-    migration: { id: catalog.manifest.id, from: catalog.manifest.from, to: catalog.manifest.to, references: catalog.manifest.references ?? {}, harness },
+    migration: {
+      id: catalog.manifest.id,
+      from: catalog.manifest.from,
+      to: catalog.manifest.to,
+      actualTarget: { version: actualTarget, catalogVersion: catalog.manifest.to.version, catalogExact: actualTarget === catalog.manifest.to.version },
+      references: catalog.manifest.references ?? {},
+      harness,
+    },
     plugin: { root, name: manifest.value.name ?? basename(root), version: manifest.value.version ?? 'unknown', manifestFile: manifest.file, packageManager: existsSync(join(root, 'pnpm-lock.yaml')) ? 'pnpm' : existsSync(join(root, 'yarn.lock')) ? 'yarn' : 'npm' },
     summary: summarize(findings, safeEdits, unresolved),
     findings,
     safeEdits,
     semanticTasks: unresolved,
     sourceInvestigation: {
-      required: harness.exact !== true || unresolved.length > 0,
+      required: harness.exact !== true || unresolved.length > 0 || actualTarget !== catalog.manifest.to.version,
       targetRef: catalog.manifest.to.ref,
       catalogReferences: catalog.manifest.references ?? {},
       semanticTargets: [...new Set(unresolved.map(item => item.targetModule).filter(Boolean))],
@@ -429,6 +459,7 @@ export function createMigrationPlan(report) {
       id: report.migration.id,
       from: report.migration.from.ref,
       to: report.migration.to.ref,
+      targetVersion: report.migration.actualTarget.version,
       harness: {
         status: report.migration.harness.status,
         fromCommit: report.migration.harness.fromCommit,
@@ -453,7 +484,7 @@ function readMigrationPlan(file) {
 function assertMigrationPlan(report, plan) {
   const current = createMigrationPlan(report)
   if (plan.plugin.root !== current.plugin.root || plan.plugin.manifestFile !== current.plugin.manifestFile) throw new Error('migration plan targets a different plugin')
-  if (plan.migration.id !== current.migration.id || plan.migration.from !== current.migration.from || plan.migration.to !== current.migration.to) throw new Error('migration plan targets a different catalog')
+  if (plan.migration.id !== current.migration.id || plan.migration.from !== current.migration.from || plan.migration.to !== current.migration.to || plan.migration.targetVersion !== current.migration.targetVersion) throw new Error('migration plan targets a different catalog or actual target version')
   if (plan.reportHash !== current.reportHash || JSON.stringify(plan.inputs) !== JSON.stringify(current.inputs) || JSON.stringify(plan.edits) !== JSON.stringify(current.edits)) throw new Error('plugin analysis changed after the preview; create and review a new migration plan')
   return current
 }
@@ -478,7 +509,7 @@ export function applyMigration(report, options = {}) {
     if (currentExists !== item.snapshot.exists || sha256(current) !== item.snapshot.hash) throw new Error(`${item.snapshot.file} changed after the preview; diagnose again before applying`)
   }
   const writes = report._plan.map(item => ({ ...atomicWrite(item.snapshot, item.nextText), beforeHash: item.snapshot.hash, afterHash: sha256(item.nextText) }))
-  const verification = analyzeMigration(report.plugin.root, { from: report.migration.from.ref, to: report.migration.to.ref, harnessRoot: report.migration.harness.root })
+  const verification = analyzeMigration(report.plugin.root, { from: report.migration.from.ref, to: report.migration.to.ref, targetVersion: report.migration.actualTarget.version, harnessRoot: report.migration.harness.root })
   return { mode: 'applied', plan: { file: planFile, id: verifiedPlan.planId }, writes, report: publicMigrationReport(verification) }
 }