@boyingliu01/xp-gate 0.31.3 → 0.32.0

package/adapters/java.sh

@@ -33,6 +33,15 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PLUGIN_DIR="$SCRIPT_DIR/plugins/p3c-java"
 WHALECLOUD_PLUGIN_DIR="$SCRIPT_DIR/plugins/whalecloud-java"
 
+# #640: smart test selection helpers (strategy truth table + path-convention
+# lookup). Sourced from lib/ so the logic stays unit-testable in isolation;
+# `|| true` keeps a stale install (adapter present, lib missing) from breaking
+# static analysis, which does not depend on it. run_coverage degrades to the
+# full suite when the functions are absent.
+_JAVA_SELECTION_LIB="$SCRIPT_DIR/../lib/java-test-selection.sh"
+# shellcheck source=/dev/null
+[ -f "$_JAVA_SELECTION_LIB" ] && . "$_JAVA_SELECTION_LIB"
+
 WC_JAVA_LINT_DEFAULT_TIMEOUT=180
 
 # ---------------------------------------------------------------------------
@@ -528,14 +537,257 @@ _detect_jacoco_configured() {
   return 1
 }
 
+# ── #640: Java smart test selection ─────────────────────────────────────────
+# The Java arm ran the FULL suite on every commit (measured: `mvn test
+# jacoco:report` = 77.8s for 1079 tests whether one file or a hundred changed).
+# TS (#286) and Python (#399) already had three-tier selection; Java did not,
+# and PARTIAL_TEST_RUN was therefore never set on this path — the downgrade
+# channel in Stage 2 was dead code for Java.
+#
+# This mirrors the Python selector exactly:
+#   1. changed-tests — only test files changed: run exactly those.
+#   2. related      — sources changed, no tests: run what the path convention maps.
+#   3. full         — >20 changed tests, a build manifest changed, or no related
+#                     tests found.
+# Tiers 1/2 set PARTIAL_TEST_RUN so Stage 2 WARNS about subset coverage instead
+# of blocking on it (subset coverage is meaningless as a global floor).
+#
+# Escape valve: XP_GATE_JAVA_TEST_SELECTION=off forces the full suite — for
+# anyone who would rather pay the time than risk a missed transitive impact.
+# Selection can only narrow the run, never widen it: every non-selected case
+# falls back to `full`.
+
+# Colon-separated list of changed paths, as handed in by pre-commit. Empty when
+# the caller does not provide one (older pre-commit, direct adapter use), in
+# which case we must NOT silently narrow the run — see _java_selection_enabled.
+_JAVA_CHANGED_FILES="${GATE_CHANGED_FILES:-}"
+
+# True when selection is usable: the escape valve is off AND the caller told us
+# what changed. Without changed files we cannot select, and guessing "nothing
+# changed" would run zero tests and report PASS — the exact failure mode the
+# fail-closed contract forbids.
+_java_selection_enabled() {
+  [ "${XP_GATE_JAVA_TEST_SELECTION:-on}" != "off" ] || return 1
+  [ -n "$_JAVA_CHANGED_FILES" ] || return 1
+  return 0
+}
+
+# Split the changed-file list into (test_count, src_count, deps_changed) and
+# echo the strategy. Pure delegation to the lib so the truth table lives in one
+# testable place.
+_java_select_strategy() {
+  local test_count=0 src_count=0 deps_changed=0 path
+  local _java_files
+  # Newline-delimited, either from a colon list or a pre-split newline list.
+  _java_files=$(printf '%s' "$_JAVA_CHANGED_FILES" | tr ':' '\n')
+
+  while IFS= read -r path; do
+    [ -n "$path" ] || continue
+    case "$path" in
+      *.java) ;;                # only Java sources influence the Java counts
+      *) continue ;;
+    esac
+    if java_is_test_file "$path"; then
+      test_count=$((test_count + 1))
+    else
+      src_count=$((src_count + 1))
+    fi
+  done <<EOF
+$_java_files
+EOF
+
+  # Build manifests are checked across ALL changed paths (a pom.xml change is
+  # not a .java file but invalidates every test).
+  # Build manifests are checked across ALL changed paths (a pom.xml change is
+  # not a .java file but invalidates every test). Newline-delimited and passed
+  # through a here-string rather than unquoted word splitting: a path with a
+  # space would otherwise arrive as two fragments, and on Windows a fragment
+  # containing a drive colon is indistinguishable from a separator.
+  while IFS= read -r path; do
+    [ -n "$path" ] || continue
+    if java_dependency_changed "$path"; then
+      deps_changed=1
+      break
+    fi
+  done <<EOF
+$(printf '%s' "$_JAVA_CHANGED_FILES" | tr ':' '\n')
+EOF
+
+  select_java_test_strategy "$test_count" "$src_count" "$deps_changed"
+}
+
+# Resolve the concrete test files to run for `related`, by mapping every changed
+# non-test Java source through the path convention. Echoes one path per line.
+#
+# Exit code distinguishes the two outcomes that both produce empty stdout:
+#   0 — lookup completed; no related test exists (caller escalates to full)
+#   1 — the lookup itself broke (helper function missing). The caller must ALSO
+#       escalate to full, but must not silently treat a broken lookup as
+#       "nothing related" — that is the difference between a slow commit and a
+#       commit that never ran the tests it should have.
+_java_related_test_files() {
+  command -v java_related_tests >/dev/null 2>&1 || return 1
+  local path seen="" rc=0
+  local _java_files
+  _java_files=$(printf '%s' "$_JAVA_CHANGED_FILES" | tr ':' '\n')
+  while IFS= read -r path; do
+    [ -n "$path" ] || continue
+    case "$path" in *.java) ;; *) continue ;; esac
+    java_is_test_file "$path" && continue
+    local related
+    while IFS= read -r related; do
+      [ -n "$related" ] || continue
+      case "$seen" in
+        *"|$related|"*) continue ;;
+      esac
+      seen="$seen|$related|"
+      printf '%s\n' "$related"
+    done <<EOF
+$(java_related_tests "$path")
+EOF
+  done <<EOF
+$_java_files
+EOF
+  return "$rc"
+}
+
+# Run the Maven suite. With a non-empty target list, runs only those classes;
+# otherwise runs everything.
+#
+#   $1 target list (comma-separated simple class names), may be empty
+#
+# Both fail-if-no-tests switches are required and they are NOT the same flag:
+#   -Dsurefire.failIfNoSpecifiedTests=false — a module with NO class matching
+#     -Dtest otherwise fails the build. In a multi-module repo the changed
+#     class lives in one module and every other module holds zero matches;
+#     without this the selective run is WORSE than the full one (measured:
+#     BUILD FAILURE on a 2-module project vs. a clean full-suite pass).
+#   -DfailIfNoTests=false — the older property some surefire versions read;
+#     kept for plugins predating the renamed key.
+_run_maven_tests() {
+  local targets="$1"
+  if [ -n "$targets" ]; then
+    echo "     ℹ️  Java selective run — $targets"
+    mvn test jacoco:report -q -Dtest="$targets" \
+      -Dsurefire.failIfNoSpecifiedTests=false \
+      -DfailIfNoTests=false 2>&1 | tail -10
+  else
+    mvn test jacoco:report -q 2>&1 | tail -10
+  fi
+  return "${PIPESTATUS[0]}"
+}
+
+# Run the Gradle suite, optionally filtered with repeated --tests flags.
+#
+#   $1..$N simple class names, may be empty
+_run_gradle_tests() {
+  if [ "$#" -gt 0 ] && [ -n "$1" ]; then
+    local filters=()
+    local name
+    for name in "$@"; do
+      [ -n "$name" ] || continue
+      filters+=("--tests" "$name")
+    done
+    echo "     ℹ️  Java selective run — ${*}"
+    gradle test jacocoTestReport --quiet "${filters[@]}" 2>&1 | tail -10
+  else
+    gradle test jacocoTestReport --quiet 2>&1 | tail -10
+  fi
+  return "${PIPESTATUS[0]}"
+}
+
 run_coverage() {
   local build_system
   build_system=$(_detect_java_build)
 
+  # Decide the selection once; every branch below honours it the same way.
+  local strategy="full" targets="" gradle_filters=()
+  if _java_selection_enabled; then
+    # lib/java-test-selection.sh is sourced by run_static_analysis's caller
+    # chain; guard so a direct invocation still works.
+    if command -v select_java_test_strategy >/dev/null 2>&1; then
+      strategy=$(_java_select_strategy)
+      case "$strategy" in
+        changed-tests)
+          # Feed ONLY actual test files to the selector. The strategy said
+          # "test files changed", but the raw list also carries every staged
+          # path; passing a production class here would have surefire report
+          # "No tests were executed" — and because of the failIfNoSpecifiedTests
+          # flag this run deliberately sets, that would exit 0 and count as a
+          # PASS while nothing ran. Filtering by java_is_test_file keeps the
+          # selector list and the strategy decision consistent.
+          local _ct_files=""
+          local _ct_path
+          while IFS= read -r _ct_path; do
+            [ -n "$_ct_path" ] || continue
+            case "$_ct_path" in *.java) ;; *) continue ;; esac
+            java_is_test_file "$_ct_path" || continue
+            _ct_files="$_ct_files$_ct_path"$'\n'
+          done <<EOF
+$(printf '%s' "$_JAVA_CHANGED_FILES" | tr ':' '\n')
+EOF
+          # shellcheck disable=SC2046
+          targets=$(java_maven_test_selector $(printf '%s' "$_ct_files"))
+          # shellcheck disable=SC2046,SC2207
+          gradle_filters=($(java_gradle_test_filters $(printf '%s' "$_ct_files")))
+          if [ -z "$targets" ] && [ "${#gradle_filters[@]}" -eq 0 ]; then
+            # Strategy said test files changed but none survived classification.
+            # Never run an empty inline list: widen to full rather than pass on
+            # a command that executes nothing.
+            strategy="full"
+          fi
+          ;;
+        related)
+          local related_files
+          related_files=$(_java_related_test_files)
+          local _rel_rc=$?
+          if [ "$_rel_rc" -ne 0 ]; then
+            # The lookup itself failed (helper missing). Escalate instead of
+            # pretending "nothing related" — an empty answer from a broken
+            # lookup and an empty answer from a real miss are different things.
+            strategy="full"
+          elif [ -n "$related_files" ]; then
+            # Word splitting IS the intent on both lines: $related_files is a
+            # space-separated path list and both helpers take it as $@.
+            # shellcheck disable=SC2046,SC2086
+            targets=$(java_maven_test_selector $related_files)
+            # shellcheck disable=SC2207,SC2086
+            gradle_filters=($(java_gradle_test_filters $related_files))
+          fi
+          if [ -z "$targets" ] && [ "${#gradle_filters[@]}" -eq 0 ]; then
+            # No related tests found -> tier 3, never "run nothing".
+            strategy="full"
+          fi
+          ;;
+      esac
+    fi
+  fi
+
+  case "$strategy" in
+    changed-tests|related)
+      # Subset run: the global coverage floor cannot be verified from it, so
+      # mark the run partial and let Stage 2 WARN (same contract as #399/#556).
+      #
+      # A plain `PARTIAL_TEST_RUN=true` does NOT work here: pre-commit calls
+      # `run_coverage` inside `$(...)`, so this function runs in a subshell and
+      # the assignment dies with it. Python's selective path gets away with the
+      # bare assignment only because it sets the flag at the call site, in the
+      # caller's own shell. Publish the decision through the file the caller
+      # named instead; the caller turns it into the flag.
+      if [ -n "${XP_GATE_PARTIAL_RUN_FILE:-}" ]; then
+        printf '%s\n' "$strategy" > "$XP_GATE_PARTIAL_RUN_FILE" 2>/dev/null || true
+      fi
+      echo "     ℹ️  Java: selective run ($strategy)"
+      ;;
+    *)
+      echo "     ℹ️  Java: full suite"
+      ;;
+  esac
+
   if [ "$build_system" = "maven" ]; then
     if _detect_jacoco_configured "$build_system"; then
-      mvn test jacoco:report -q 2>&1 | tail -10
-      return "${PIPESTATUS[0]}"
+      _run_maven_tests "$targets"
+      return $?
     else
       echo "ℹ️  JaCoCo not configured in pom.xml — SKIP coverage check"
       echo "   To enable: add jacoco-maven-plugin to your pom.xml"
@@ -543,8 +795,8 @@ run_coverage() {
     fi
   elif [ "$build_system" = "gradle" ]; then
     if _detect_jacoco_configured "$build_system"; then
-      gradle jacocoTestReport --quiet 2>&1 | tail -10
-      return "${PIPESTATUS[0]}"
+      _run_gradle_tests "${gradle_filters[@]}"
+      return $?
     else
       echo "ℹ️  JaCoCo not configured in Gradle build — SKIP coverage check"
       echo "   To enable: add 'id \"jacoco\"' to your build.gradle plugins block"

package/adapters/powershell.sh

@@ -59,8 +59,36 @@ _detect_pwsh() {
   return 1
 }
 
+# List PowerShell SOURCE files under the current directory, without walking the
+# pruned artifact directories.
+#
+# #620: the caller used to pass '*.ps1', so a .psm1 module file was invisible --
+# a repo whose code lives in modules (the normal layout for anything that ships
+# one) got "no PowerShell files found outside the pruned directories" on every
+# commit, and the message blamed node_modules/dist instead of the glob. Our own
+# complexity path (gate-3.sh) already treated '.ps(m)?1$' as PowerShell, so the
+# two gates disagreed about what a PowerShell file is.
+#
+# The extension set is owned here rather than at each call site: one definition,
+# so Gate 1 and Gate 3 cannot drift apart again. Callers that want a narrower
+# population (e.g. only *.Tests.ps1) still pass an explicit pattern.
+_POWERSHELL_SOURCE_PATTERNS=('*.ps1' '*.psm1')
+
 _find_powershell_files() {
-  local name_pattern="$1"
+  local name_pattern="${1:-}"
+
+  # Default to every PowerShell source file. A bare name_pattern keeps the old
+  # single-extension behaviour for callers that pass one deliberately.
+  local -a name_test=()
+  if [ -z "$name_pattern" ]; then
+    local p
+    for p in "${_POWERSHELL_SOURCE_PATTERNS[@]}"; do
+      if [ "${#name_test[@]}" -gt 0 ]; then name_test+=('-o'); fi
+      name_test+=('-name' "$p")
+    done
+  else
+    name_test=('-name' "$name_pattern")
+  fi
 
   # #573: repo-local extra prune entries. The list below covers the artifact
   # directories xp-gate itself produces, but a consuming repo can have its own
@@ -149,7 +177,7 @@ _find_powershell_files() {
       -path './src/npm-package/plugins' \
       "${prune_args[@]+"${prune_args[@]}"}" \
     \) -prune \) -o \
-    \( -type f -name "$name_pattern" -print \) 2>/dev/null
+    \( -type f \( "${name_test[@]}" \) -print \) 2>/dev/null
 }
 
 _powershell_invocation() {
@@ -290,16 +318,27 @@ run_static_analysis() {
       # .git, node_modules, dist, coverage and the rest. The two paths disagreed
       # only because this one never called it. Now both use it, so "what this
       # adapter refuses to analyse" has one definition.
-      local legacy_files
-      legacy_files=$(_find_powershell_files '*.ps1')
-      if [ -z "$legacy_files" ]; then
+      # #620: no pattern means "every PowerShell source file", so .psm1 modules
+      # are analysed too. This used to pass '*.ps1', which made a module-only repo
+      # look empty and reported the emptiness as a pruning problem.
+      #
+      # Read into an ARRAY, one path per line. The previous shape captured the
+      # list into a string and let word splitting expand it again, which silently
+      # split any path containing a space. Reading line by line keeps the paths
+      # intact; `mapfile` would do the same but is not guaranteed by the bash
+      # versions this hook supports.
+      local -a legacy_files=()
+      while IFS= read -r _ps_file; do
+        [ -n "$_ps_file" ] && legacy_files+=("$_ps_file")
+      done < <(_find_powershell_files)
+      if [ "${#legacy_files[@]}" -eq 0 ]; then
         # Nothing to analyse is NOT a pass: say so via the reason protocol the
         # module-missing branch uses, so it stays visible in the gate output.
         echo "XP_G1_REASON: no PowerShell files found outside the pruned directories"
         return 3
       fi
       local legacy_array
-      legacy_array=$(_powershell_path_array $legacy_files)
+      legacy_array=$(_powershell_path_array "${legacy_files[@]}")
       PSSA_OUT=$("$PWSH" "${POWERSHELL_ARGS[@]}" "
         if (-not (Get-Module -ListAvailable -Name PSScriptAnalyzer)) {
           Write-Output 'PSSA_MODULE_MISSING'

package/bin/xp-gate.js

@@ -460,7 +460,11 @@ for (let i = 0; i <= 11; i++) {
   const gateInfo = gateRunner.GATE_REGISTRY[gateId];
   COMMANDS[`gate-${gateId}`] = {
     description: `Run Gate ${gateId}: ${gateInfo?.name || 'Unknown'}`,
-    run: subargs => gateRunner.runGate(gateId, subargs[0]).then(code => process.exit(code)),
+    // #618: a gate that ran nothing yields GATE_NOT_RUN. process.exit() would
+    // coerce that string to 0 (a pass), so map it to 2 -- "did not run" must not
+    // exit the same way as "ran clean".
+    run: subargs => gateRunner.runGate(gateId, subargs[0])
+      .then(code => process.exit(code === gateRunner.GATE_NOT_RUN ? 2 : code)),
     usage: `xp-gate gate-${gateId} [<path>]`
   };
 }
@@ -471,7 +475,9 @@ for (const gateId of ['python-health', 'test-layers', 'pbt']) {
   if (gateInfo) {
     COMMANDS[gateId] = {
       description: gateInfo.description,
-      run: subargs => gateRunner.runGate(gateId, subargs[0]).then(code => process.exit(code)),
+      // #618: same coercion guard as the numbered gates above.
+      run: subargs => gateRunner.runGate(gateId, subargs[0])
+        .then(code => process.exit(code === gateRunner.GATE_NOT_RUN ? 2 : code)),
       usage: `xp-gate ${gateId} [<path>]`
     };
   }

package/build-integrity/__tests__/gate-10.test.ts

@@ -1,12 +1,99 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import fs from 'fs/promises';
+import fss from 'node:fs';
 import path from 'path';
 import os from 'os';
-import { runTscCheck, runPackCheck } from '../gate-10';
+import { runTscCheck, runPackCheck, resolveImportPath } from '../gate-10';
 
 // Increase test timeout for subprocess calls (tsc, npm pack)
 vi.setConfig({ testTimeout: 30000 });
 
+/**
+ * @test REQ-627
+ * @intent `resolveImportPath` had ZERO direct tests before this file gained them.
+ *         It decides whether an import in changed code points at a real file, so
+ *         a silent regression here makes Gate 10 pass while imports are broken.
+ *         The `.js -> .ts` fallback is the subtle part: TypeScript's ESM output
+ *         rewrites `./x.ts` to `./x.js`, so a source tree has `x.js` specifiers
+ *         that must resolve to `x.ts`. Removing that arm left every existing test
+ *         green, which is exactly why these cases are needed.
+ * @covers AC-627-01, AC-627-02, AC-627-03
+ */
+
+describe('resolveImportPath (build-integrity)', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gate10-resolve-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  const from = (): string => path.join(dir, 'importer.ts');
+
+  /**
+   * Create a fixture file. The write is wrapped so a failure is reported with
+   * the file name instead of surfacing as a bare fs error somewhere later — a
+   * test whose fixture silently failed to materialise asserts nothing useful.
+   */
+  function writeSource(name: string, content: string): void {
+    try {
+      fss.writeFileSync(path.join(dir, name), content);
+    } catch (error) {
+      throw new Error(`could not create fixture ${name}: ${String(error)}`);
+    }
+  }
+
+  /** Create a fixture subdirectory, for the index-file fallback case. */
+  function makeDir(name: string): void {
+    try {
+      fss.mkdirSync(path.join(dir, name));
+    } catch (error) {
+      throw new Error(`could not create fixture dir ${name}: ${String(error)}`);
+    }
+  }
+
+  it('AC-627-01: resolves an explicit .js specifier to the sibling .ts source', async () => {
+    writeSource('target.ts', 'export const x = 1;\n');
+    // The specifier says .js; only target.ts exists. ESM output depends on this.
+    expect(resolveImportPath('./target.js', from())).toBe(path.join(dir, 'target.ts'));
+  });
+
+  it('AC-627-01: prefers an existing .js file over the .ts fallback', async () => {
+    writeSource('both.js', 'module.exports = {};\n');
+    writeSource('both.ts', 'export const x = 1;\n');
+    expect(resolveImportPath('./both.js', from())).toBe(path.join(dir, 'both.js'));
+  });
+
+  it('AC-627-02: an explicit non-.js extension must match exactly (no fallback)', async () => {
+    writeSource('mod.mjs', 'export {};\n');
+    // .mjs exists, resolves directly
+    expect(resolveImportPath('./mod.mjs', from())).toBe(path.join(dir, 'mod.mjs'));
+    // .cjs does NOT exist, and there is no .cjs -> .ts fallback
+    expect(resolveImportPath('./missing.cjs', from())).toBeNull();
+  });
+
+  it('AC-627-03: an extensionless import tries known extensions, then index files', async () => {
+    writeSource('plain.ts', 'export const y = 2;\n');
+    expect(resolveImportPath('./plain', from())).toBe(path.join(dir, 'plain.ts'));
+
+    makeDir('pkg');
+    writeSource('pkg/index.ts', 'export {};\n');
+    expect(resolveImportPath('./pkg', from())).toBe(path.join(dir, 'pkg', 'index.ts'));
+  });
+
+  it('AC-627-03: a non-relative specifier is not resolved at all', () => {
+    expect(resolveImportPath('lodash', from())).toBeNull();
+    expect(resolveImportPath('@scope/pkg', from())).toBeNull();
+  });
+
+  it('AC-627-03: a relative import to nothing returns null', async () => {
+    expect(resolveImportPath('./nope', from())).toBeNull();
+  });
+});
+
 /**
  * @test Gate 10 runTscCheck
  * @intent Verify tsc --noEmit check behavior for build integrity gate

package/build-integrity/gate-10.ts

@@ -281,34 +281,69 @@ function tryAccess(filePath: string): boolean {
   }
 }
 
-export function resolveImportPath(importPath: string, fromFile: string): string | null {
-  if (!isRelativeImport(importPath)) return null;
+/**
+ * Extensions tried when an import has none, in precedence order.
+ *
+ * `.js` first because a TS source that imports `./x` is compiled to `x.js`, so
+ * the emitted name is the most likely intent in a mixed tree.
+ */
+const IMPORT_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
 
-  const fromDir = path.dirname(fromFile);
-  const resolved = path.resolve(fromDir, importPath);
+/** Directory-index filenames tried last, when no sibling file matched. */
+const INDEX_FILES = ['index.ts', 'index.js'];
 
-  const ext = path.extname(importPath);
-  if (ext) {
-    if (tryAccess(resolved)) return resolved;
-    if (ext === '.js') {
-      if (tryAccess(resolved.slice(0, -3) + '.ts')) return resolved.slice(0, -3) + '.ts';
-      if (tryAccess(resolved.slice(0, -3) + '.tsx')) return resolved.slice(0, -3) + '.tsx';
-    }
-    return null;
+/**
+ * Source extensions an explicit `.js` import may actually refer to.
+ *
+ * TypeScript's ESM output rewrites `./x.ts` to `./x.js`, so an import that names
+ * a `.js` file legitimately resolves to the TypeScript source beside it. Checked
+ * in order, and only for `.js` -- an explicit `.ts` or `.mjs` must match exactly.
+ */
+const JS_TO_SOURCE_EXTENSIONS = ['.ts', '.tsx'];
+
+/**
+ * Resolve an import that already names an extension.
+ *
+ * A `.js` specifier may point at TypeScript source (ESM output rewrites `.ts` to
+ * `.js`), so it gets one extra look at the sibling source extensions. Every other
+ * extension must match the file on disk exactly.
+ */
+function resolveExplicitExtension(resolved: string, ext: string): string | null {
+  if (tryAccess(resolved)) return resolved;
+  if (ext !== '.js') return null;
+  const stem = resolved.slice(0, -'.js'.length);
+  for (const sourceExt of JS_TO_SOURCE_EXTENSIONS) {
+    if (tryAccess(stem + sourceExt)) return stem + sourceExt;
   }
+  return null;
+}
 
-  for (const tryExt of ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']) {
+/**
+ * Resolve an extensionless import: try the known extensions in order, then the
+ * directory-index names.
+ */
+function resolveBareImport(resolved: string): string | null {
+  for (const tryExt of IMPORT_EXTENSIONS) {
     if (tryAccess(resolved + tryExt)) return resolved + tryExt;
   }
-
-  for (const idxName of ['index.ts', 'index.js']) {
+  for (const idxName of INDEX_FILES) {
     const candidate = path.join(resolved, idxName);
     if (tryAccess(candidate)) return candidate;
   }
-
   return null;
 }
 
+export function resolveImportPath(importPath: string, fromFile: string): string | null {
+  if (!isRelativeImport(importPath)) return null;
+
+  const resolved = path.resolve(path.dirname(fromFile), importPath);
+  const ext = path.extname(importPath);
+
+  return ext
+    ? resolveExplicitExtension(resolved, ext)
+    : resolveBareImport(resolved);
+}
+
 /**
  * Runs the import check on a list of changed files.
  * Verifies that all relative imports in the changed files resolve to files

package/dsh.bundle.patch.yml

@@ -0,0 +1,15 @@
+# XP-Gate DSH bundle patch (npm main package).
+#
+# Mounts the xp-gate tool plugin so that
+#   dsh plugin add @boyingliu01/xp-gate
+# is sufficient on its own — no separate install of
+# @boyingliu01/dsh-plugin-xp-gate is required.
+#
+# The entry point is the package-internal subpath "./dsh", which resolves via
+# this package.json's `exports` map to plugins/dsh/lib/index.js (ESM). Shipping
+# the code inside the same tarball keeps `dependencies` empty, preserving the
+# zero-install distribution contract.
+
+- insert:
+    - id: tool-xp-gate
+      name: '@boyingliu01/xp-gate/dsh'