pi-usereq 0.44.0 → 0.46.0

package/scripts/install-static-checkers.ts

@@ -7,6 +7,7 @@
 
 import process from "node:process";
 import { spawnSync } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 import { resolveCheckerExecutable } from "../src/core/static-check.js";
 import { getInstallationPath } from "../src/core/path-context.js";
@@ -42,6 +43,196 @@ function bundledCheckerRange(pkg: string): string {
   }
 }
 
+/**
+ * @brief Describes one parsed package manifest entry used for install-script detection.
+ * @details Captures only the package `name` and lifecycle `scripts` map needed to decide whether a package contributes an install script. The interface is compile-time only and introduces no runtime side effects.
+ */
+export interface NodeModulesPackage {
+  name: string;
+  scripts: Record<string, string>;
+}
+
+/**
+ * @brief Lists the npm lifecycle script fields that trigger the allow-scripts warning for registry dependencies.
+ * @details Mirrors the npm lifecycle script names whose presence on a registry dependency causes `npm warn allow-scripts` when the package is not covered by the consumer-root `allowScripts` map. `prepare` is intentionally excluded because npm only runs `prepare` for non-registry (git/file) sources, so including it would over-approve ordinary registry dependencies that never trigger the warning. Access complexity is O(1).
+ */
+export const INSTALL_LIFECYCLE_SCRIPTS = ["preinstall", "install", "postinstall"] as const;
+
+/**
+ * @brief Describes the injectable filesystem operations consumed by the approval flow.
+ * @details Exposes the strict subset of `node:fs` synchronous operations needed to scan `node_modules` and update the consumer-root `package.json` so unit tests substitute an in-memory fake without touching the real filesystem. The interface is compile-time only and introduces no runtime side effects.
+ */
+export interface InstallScriptApprovalDeps {
+  existsSync(path: string): boolean;
+  readdirSync(path: string): string[];
+  readFileSync(path: string): string;
+  writeFileSync(path: string, data: string): void;
+}
+
+/**
+ * @brief Resolves the consumer install root that owns the active npm install transaction.
+ * @details During an npm lifecycle script npm sets `INIT_CWD` to the invocation directory and `npm_config_local_prefix` to the resolved project prefix; both point at the true consumer root instead of the installed package directory that is the postinstall `process.cwd()`. Returns the first available value so the approval flow writes the consumer-root `package.json` allowScripts map instead of the nested `node_modules/<pkg>` directory. Runtime is O(1). No external state is mutated.
+ * @param[in] env {NodeJS.ProcessEnv} Environment map read for npm lifecycle path variables.
+ * @return {string | undefined} Consumer install root, or `undefined` when not running inside an npm lifecycle.
+ */
+export function getConsumerInstallRoot(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  return env.INIT_CWD || env.npm_config_local_prefix || undefined;
+}
+
+/**
+ * @brief Selects package names that declare at least one npm install lifecycle script.
+ * @details Returns the `name` of every supplied package whose `scripts` map contains a non-empty `preinstall`, `install`, or `postinstall` entry, preserving input order. `prepare` is excluded because npm only runs it for non-registry sources. Pure derivation over supplied data with no filesystem access. Runtime is O(n * k) where n is the package count and k is the fixed lifecycle-field count. No external state is mutated.
+ * @param[in] packages {readonly NodeModulesPackage[]} Parsed package manifests scanned from `node_modules`.
+ * @return {string[]} Ordered list of package names declaring an install lifecycle script.
+ */
+export function selectInstallScriptPackageNames(packages: readonly NodeModulesPackage[]): string[] {
+  const names: string[] = [];
+  for (const pkg of packages) {
+    if (typeof pkg.name !== "string") {
+      continue;
+    }
+    const name = pkg.name.trim();
+    if (name === "") {
+      continue;
+    }
+    const hasLifecycleScript = INSTALL_LIFECYCLE_SCRIPTS.some(
+      (field) => typeof pkg.scripts[field] === "string" && pkg.scripts[field] !== "",
+    );
+    if (hasLifecycleScript) {
+      names.push(name);
+    }
+  }
+  return names;
+}
+
+/**
+ * @brief Merges name-only allowScripts approvals into an existing allowScripts map.
+ * @details Returns a new map that preserves every existing entry (including explicit `false` denials) and adds each missing package name keyed by name only (no version pin) so approvals survive dependency version changes and never re-trigger the warning on later updates. Runtime is O(n + e) where n is the supplied name count and e is the existing entry count. No external state is mutated.
+ * @param[in] existingAllowScripts {Record<string, boolean> | undefined} Current consumer-root allowScripts map, if any.
+ * @param[in] packageNames {readonly string[]} Package names to approve when absent.
+ * @return {Record<string, boolean>} Merged allowScripts map with name-only approvals added.
+ */
+export function mergeAllowScriptsEntries(
+  existingAllowScripts: Record<string, boolean> | undefined,
+  packageNames: readonly string[],
+): Record<string, boolean> {
+  const merged: Record<string, boolean> = { ...(existingAllowScripts ?? {}) };
+  for (const name of packageNames) {
+    const trimmedName = typeof name === "string" ? name.trim() : "";
+    if (trimmedName !== "" && !(trimmedName in merged)) {
+      merged[trimmedName] = true;
+    }
+  }
+  return merged;
+}
+
+/**
+ * @brief Provides the default real filesystem operations for the approval flow.
+ * @details Binds the synchronous `node:fs` operations used to scan `node_modules` and rewrite the consumer-root `package.json` in production. Runtime is dominated by filesystem I/O. Side effect: filesystem reads and an optional write.
+ */
+const realApprovalDeps: InstallScriptApprovalDeps = {
+  existsSync: (p) => fs.existsSync(p),
+  readdirSync: (p) => fs.readdirSync(p),
+  readFileSync: (p) => fs.readFileSync(p, "utf8"),
+  writeFileSync: (p, data) => fs.writeFileSync(p, data),
+};
+
+/**
+ * @brief Scans consumer-root `node_modules` and returns parsed package manifests.
+ * @details Iterates top-level `node_modules` entries, descends one level into `@scope` directories, skips dotfile entries and packages whose `package.json` is missing or unparseable, and returns the parsed `name` plus `scripts` map for every readable package. Runtime is O(m) where m is the top-level installed package count. No external state is mutated.
+ * @param[in] nodeModulesPath {string} Absolute consumer-root `node_modules` path.
+ * @param[in] deps {InstallScriptApprovalDeps} Injectable filesystem operations.
+ * @return {NodeModulesPackage[]} Parsed package manifests for every readable installed package.
+ */
+function collectNodeModulesPackages(
+  nodeModulesPath: string,
+  deps: InstallScriptApprovalDeps,
+): NodeModulesPackage[] {
+  const packages: NodeModulesPackage[] = [];
+  if (!deps.existsSync(nodeModulesPath)) {
+    return packages;
+  }
+  const readPackage = (entryRelativePath: string): void => {
+    const pkgPath = path.join(nodeModulesPath, entryRelativePath, "package.json");
+    if (!deps.existsSync(pkgPath)) {
+      return;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(deps.readFileSync(pkgPath));
+    } catch {
+      return;
+    }
+    const name = typeof (parsed as { name?: unknown })?.name === "string"
+      ? (parsed as { name: string }).name
+      : "";
+    const scripts = (parsed as { scripts?: unknown })?.scripts;
+    const scriptsMap = scripts && typeof scripts === "object"
+      ? (scripts as Record<string, string>)
+      : {};
+    packages.push({ name, scripts: scriptsMap });
+  };
+  for (const entry of deps.readdirSync(nodeModulesPath)) {
+    if (entry.startsWith(".")) {
+      continue;
+    }
+    if (entry.startsWith("@")) {
+      const scopePath = path.join(nodeModulesPath, entry);
+      for (const scopedEntry of deps.readdirSync(scopePath)) {
+        readPackage(path.join(entry, scopedEntry));
+      }
+    } else {
+      readPackage(entry);
+    }
+  }
+  return packages;
+}
+
+/**
+ * @brief Best-effort approves pending npm install scripts for the consumer install root.
+ * @details Resolves the consumer install root from the npm lifecycle environment, scans consumer-root `node_modules` for installed packages that declare an install lifecycle script, and writes name-only `allowScripts` approvals into the consumer-root `package.json` for every such package that is not already covered. Direct writes are required because `npm approve-scripts --all` refuses to approve packages mid-install with `no trusted identity for policy key`. Name-only entries (no version pin) are used so approvals survive dependency version changes and never re-trigger the warning on later updates. Existing entries (including explicit `false` denials) are always preserved. Accepts injectable filesystem operations so unit tests stay deterministic and isolated. Swallows all errors so the postinstall flow never fails. Runtime is dominated by filesystem I/O. Side effects include a consumer-root `package.json` read and an optional write.
+ * @param[in] deps {InstallScriptApprovalDeps} Injectable filesystem operations; defaults to the real `node:fs`-backed operations.
+ * @return {void} No return value.
+ * @satisfies DES-020, REQ-352
+ */
+export function approvePendingInstallScripts(deps: InstallScriptApprovalDeps = realApprovalDeps): void {
+  const root = getConsumerInstallRoot();
+  if (!root) {
+    return;
+  }
+  const nodeModulesPath = path.join(root, "node_modules");
+  const packages = collectNodeModulesPackages(nodeModulesPath, deps);
+  const packageNames = selectInstallScriptPackageNames(packages);
+  if (packageNames.length === 0) {
+    return;
+  }
+  const rootPackageJsonPath = path.join(root, "package.json");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(deps.readFileSync(rootPackageJsonPath));
+  } catch {
+    return;
+  }
+  if (!parsed || typeof parsed !== "object") {
+    return;
+  }
+  const pkgJson = parsed as Record<string, unknown>;
+  const existingAllowScripts = pkgJson.allowScripts;
+  const existingMap = existingAllowScripts && typeof existingAllowScripts === "object"
+    ? (existingAllowScripts as Record<string, boolean>)
+    : undefined;
+  const merged = mergeAllowScriptsEntries(existingMap, packageNames);
+  if (JSON.stringify(merged) === JSON.stringify(existingAllowScripts ?? {})) {
+    return;
+  }
+  pkgJson.allowScripts = merged;
+  try {
+    deps.writeFileSync(rootPackageJsonPath, `${JSON.stringify(pkgJson, null, 2)}\n`);
+  } catch (error) {
+    process.stderr.write(`Warning: failed to approve pending install scripts: ${error instanceof Error ? error.message : String(error)}\n`);
+  }
+}
+
 /**
  * @brief Prints platform-specific install guidance for native checkers.
  * @details Detects the current platform and emits one consolidated stderr line per native checker describing the recommended system package manager command. Runtime is O(1). Side effect: writes to stderr.
@@ -98,13 +289,16 @@ function attemptBundledInstall(pkg: string): void {
 
 /**
  * @brief Executes the postinstall static-checker installation flow.
- * @details Probes each bundled npm checker through `resolveCheckerExecutable`, attempts a best-effort install on miss, prints native-checker guidance for unresolvable native checkers, and always returns `0` so `npm install` never fails because of missing optional checkers. Runtime is dominated by PATH probing and optional npm execution. Side effects include stdout/stderr writes and best-effort `npm install` subprocess spawning. The script never modifies git-tracked files.
+ * @details When invoked as the npm `postinstall` lifecycle script, first best-effort approves pending consumer install scripts through `approvePendingInstallScripts`, then probes each bundled npm checker through `resolveCheckerExecutable`, attempts a best-effort install on miss, prints native-checker guidance for unresolvable native checkers, and always returns `0` so `npm install` never fails because of missing optional checkers. The lifecycle gate keeps the approval side effect bound to real installs so manual or test invocations never mutate an unrelated project root. Runtime is dominated by PATH probing and optional npm execution. Side effects include stdout/stderr writes and best-effort `npm install` subprocess spawning. The script never modifies git-tracked files.
  * @param[in] argv {string[]} Raw CLI arguments (unused, retained for CLI convention parity).
  * @return {number} Always returns `0`.
- * @satisfies REQ-339, DES-017
+ * @satisfies REQ-339, DES-017, DES-020, REQ-352
  */
 export function main(argv = process.argv.slice(2)): number {
   void argv;
+  if (process.env.npm_lifecycle_event === "postinstall") {
+    approvePendingInstallScripts();
+  }
   for (const checker of BUNDLED_NPM_CHECKERS) {
     if (resolveCheckerExecutable(checker)) {
       process.stdout.write(`Bundled static checker '${checker}' is available.\n`);

package/src/core/static-check.ts

@@ -399,11 +399,12 @@ export class StaticCheckCommand extends StaticCheckBase {
    * @throws {ReqError} Throws when the executable cannot be found on PATH.
    */
   constructor(cmd: string, inputs: string[], extraArgs?: string[], failOnly = false) {
-    if (!resolveCheckerExecutable(cmd)) {
+    const resolvedCmd = resolveCheckerExecutable(cmd);
+    if (!resolvedCmd) {
       throw new ReqError(`Error: external command '${cmd}' not found on PATH.`, 1);
     }
     super(inputs, extraArgs, failOnly);
-    this.cmd = cmd;
+    this.cmd = cmd.includes("%%INSTALLATION_PATH%%") ? resolvedCmd : cmd;
     this.label = `Command[${cmd}]`;
   }
 
@@ -475,20 +476,25 @@ export function findExecutable(cmd: string): string | undefined {
 }
 
 /**
- * @brief Resolves one checker executable across bundled `node_modules/.bin` locations and PATH.
- * @details Probes the installation-owned `node_modules/.bin` directory, the project-scope parent `node_modules/.bin` directory used by `--prefix` layouts, and finally the system PATH scan, returning the first executable match. Runtime is O(p) in PATH entry count plus bounded filesystem metadata checks. Side effects are limited to filesystem reads.
- * @param[in] cmd {string} Executable name or relative path to resolve.
+ * @brief Resolves one checker executable across installation-keyword, bundled `node_modules/.bin`, and PATH locations.
+ * @details Substitutes the `%%INSTALLATION_PATH%%` keyword with the runtime installation path and verifies the resulting explicit path when present, then probes the installation-owned `node_modules/.bin` directory, the project-scope parent `node_modules/.bin` directory used by `--prefix` layouts, and finally the system PATH scan, returning the first executable match so default configuration requires no target-project module installation. Runtime is O(p) in PATH entry count plus bounded filesystem metadata checks. Side effects are limited to filesystem reads.
+ * @param[in] cmd {string} Executable name, explicit path, or `%%INSTALLATION_PATH%%`-anchored path to resolve.
  * @return {string | undefined} Absolute executable path, or `undefined` when not found in any probed location.
- * @satisfies REQ-023, REQ-037, DES-018
+ * @satisfies REQ-023, REQ-037, DES-018, DES-019, REQ-350, REQ-351
  */
 export function resolveCheckerExecutable(cmd: string): string | undefined {
+  if (cmd.includes("%%INSTALLATION_PATH%%")) {
+    const installationPath = getInstallationPath();
+    const resolvedPath = cmd.split("%%INSTALLATION_PATH%%").join(installationPath);
+    return isExecutableFile(resolvedPath) ? path.resolve(resolvedPath) : undefined;
+  }
   if (cmd.includes(path.sep)) {
     return isExecutableFile(cmd) ? path.resolve(cmd) : undefined;
   }
   const installationPath = getInstallationPath();
   const bundledBinCandidates = [
     path.join(installationPath, "..", "node_modules", ".bin", cmd),
-    path.join(installationPath, "..", "..", "node_modules", ".bin", cmd),
+    path.join(installationPath, "..", "..", ".bin", cmd),
   ];
   for (const candidate of bundledBinCandidates) {
     if (isExecutableFile(candidate)) {

package/src/index.ts

@@ -3791,7 +3791,7 @@ function formatStaticCheckLanguagesSummary(config: UseReqConfig): string {
  * @details Serializes guided Command-oriented add and remove actions, renders one direct on/off toggle row for every supported language, and appends canonical terminal rows while omitting raw-spec and reference-only actions. Runtime is O(l). No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered static-check menu choices.
- * @satisfies REQ-008, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-160, REQ-161, REQ-193, REQ-248
+ * @satisfies REQ-008, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-160, REQ-161, REQ-193, REQ-248, REQ-345, REQ-347
  */
 function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   const supportedLanguages = getSupportedStaticCheckLanguageSupport();
@@ -3803,11 +3803,23 @@ function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenu
       value: `${supportedLanguages.length} languages`,
       description: "Select a supported language, then configure one Command static-check executable.",
     },
+    {
+      id: "view-static-check-entry",
+      label: "View static code checker",
+      value: configuredLanguageCount > 0 ? `${configuredLanguageCount} configured` : "(none)",
+      description: "Inspect the configured Command static-check entries for every language without mutating configuration.",
+    },
     {
       id: "remove-static-check-entry",
       label: "Remove static code checker",
       value: configuredLanguageCount > 0 ? `${configuredLanguageCount} configured` : "(none)",
-      description: "Remove every configured static-check entry for one language.",
+      description: "Preview and confirm removal of every configured static-check entry for one language.",
+    },
+    {
+      id: "reset-static-check-entry",
+      label: "Reset static code checker",
+      value: "embedded defaults",
+      description: "Restore the documented per-language static-check defaults after explicit confirmation.",
     },
     ...supportedLanguages.map(({ language, extensions }) => {
       const languageConfig = getStaticCheckLanguageConfigForMenu(config, language);
@@ -3877,13 +3889,164 @@ function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUser
   ];
 }
 
+/**
+ * @brief Formats one static-check checker entry as a compact command summary.
+ * @details Joins the module command plus its parameter list into a single shell-like token sequence so inspection and confirmation menus can render checker identity deterministically. Runtime is O(p) in parameter count. No external state is mutated.
+ * @param[in] entry {StaticCheckEntry} Static-check configuration entry.
+ * @return {string} Compact command summary string.
+ */
+function formatStaticCheckCheckerEntry(entry: StaticCheckEntry): string {
+  const cmd = typeof entry.cmd === "string" ? entry.cmd.trim() : "";
+  const params = Array.isArray(entry.params) ? entry.params.map(String) : [];
+  return [cmd, ...params].filter((value) => value !== "").join(" ");
+}
+
+/**
+ * @brief Summarizes every configured checker for one language as a delimited command list.
+ * @details Joins each checker entry summary with `; ` so the value column exposes the full language configuration in one row. Runtime is O(c * p). No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] language {string} Canonical language name.
+ * @return {string} Delimited checker summary string, or `(none)` when no checkers are configured.
+ */
+function formatStaticCheckLanguageCheckerSummary(config: UseReqConfig, language: string): string {
+  const checkers = getStaticCheckLanguageConfigForMenu(config, language).checkers;
+  if (checkers.length === 0) {
+    return "(none)";
+  }
+  return checkers.map(formatStaticCheckCheckerEntry).join("; ");
+}
+
+/**
+ * @brief Builds the shared settings-menu choices for the read-only static-check inspection submenu.
+ * @details Exposes only configured languages as disabled rows whose value column renders the full checker command list, appends one selectable `Close` row, and emits a disabled placeholder when no language is configured so the submenu never mutates configuration. Runtime is O(l * c * p). No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @return {PiUsereqSettingsMenuChoice[]} Ordered read-only inspection choices.
+ * @satisfies REQ-346
+ */
+function buildStaticCheckViewChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
+  const configured = getSupportedStaticCheckLanguageSupport()
+    .filter(({ language }) => getStaticCheckLanguageConfigForMenu(config, language).checkers.length > 0);
+  if (configured.length === 0) {
+    return [
+      {
+        id: "view-static-check-empty",
+        label: "No configured static checkers",
+        value: "(none)",
+        description: "Configure at least one Command static-check entry before inspecting configuration.",
+        disabled: true,
+        labelTone: "dim",
+        valueTone: "dim",
+      },
+      {
+        id: "view-static-check-close",
+        label: "Close",
+        value: "",
+        description: "Close the static-check inspection view and return to the previous menu.",
+      },
+    ];
+  }
+  return [
+    ...configured.map(({ language, extensions }) => {
+      const languageConfig = getStaticCheckLanguageConfigForMenu(config, language);
+      const summary = formatStaticCheckLanguageCheckerSummary(config, language);
+      const checkerCount = languageConfig.checkers.length;
+      const suffix = checkerCount === 1 ? "checker" : "checkers";
+      return {
+        id: `view-static-check-language:${language}`,
+        label: language,
+        value: summary,
+        description: `Read-only inspection of the configured Command static-check entries for ${language}. Supported extensions: ${extensions.join(", ")}. ${checkerCount} ${suffix}.`,
+        disabled: true,
+        labelTone: "dim" as const,
+        valueTone: "dim" as const,
+      };
+    }),
+    {
+      id: "view-static-check-close",
+      label: "Close",
+      value: "",
+      description: "Close the static-check inspection view and return to the previous menu.",
+    },
+  ];
+}
+
+/**
+ * @brief Builds the confirmation submenu choices for removing one configured static-check language.
+ * @details Renders each configured checker as a disabled preview row, appends explicit approve and abort actions, and falls back to one disabled no-op row when the language has no checkers. Runtime is O(c * p). No external state is mutated.
+ * @param[in] language {string} Canonical language name targeted for removal.
+ * @param[in] checkers {StaticCheckEntry[]} Configured checker entries that removal would clear.
+ * @return {PiUsereqSettingsMenuChoice[]} Ordered removal-confirmation choices.
+ * @satisfies REQ-349
+ */
+function buildStaticCheckRemovalConfirmationChoices(
+  language: string,
+  checkers: StaticCheckEntry[],
+): PiUsereqSettingsMenuChoice[] {
+  const previewRows = checkers.length > 0
+    ? checkers.map((entry, index) => ({
+      id: `removal-preview:${language}:${index}`,
+      label: formatStaticCheckCheckerEntry(entry),
+      value: `${language} checker`,
+      description: `Remove the configured Command static-check entry ${formatStaticCheckCheckerEntry(entry)} from ${language}.`,
+      disabled: true,
+      labelTone: "dim" as const,
+      valueTone: "dim" as const,
+    }))
+    : [{
+      id: `removal-preview:${language}:none`,
+      label: `No configured checkers for ${language}`,
+      value: "nothing to remove",
+      description: `No configured static-check entries exist for ${language}.`,
+      disabled: true,
+      labelTone: "dim" as const,
+      valueTone: "dim" as const,
+    }];
+  return [
+    ...previewRows,
+    {
+      id: "removal-approve",
+      label: "Approve removal",
+      value: `${checkers.length} ${checkers.length === 1 ? "checker" : "checkers"}`,
+      description: `Remove every configured static-check entry for ${language}.`,
+    },
+    {
+      id: "removal-abort",
+      label: "Abort removal",
+      value: "keep current",
+      description: `Keep the configured static-check entries for ${language}.`,
+    },
+  ];
+}
+
+/**
+ * @brief Opens one explicit removal-confirmation submenu for a configured static-check language.
+ * @details Renders the targeted checker entries before removal and returns `true` only when the user selects the explicit approval action. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
+ * @param[in] ctx {ExtensionCommandContext} Active command context.
+ * @param[in] language {string} Canonical language name targeted for removal.
+ * @param[in] checkers {StaticCheckEntry[]} Configured checker entries that removal would clear.
+ * @return {Promise<boolean>} `true` when the removal is explicitly approved.
+ * @satisfies REQ-349
+ */
+async function confirmStaticCheckRemoval(
+  ctx: ExtensionCommandContext,
+  language: string,
+  checkers: StaticCheckEntry[],
+): Promise<boolean> {
+  const choice = await showPiUsereqSettingsMenu(
+    ctx,
+    `Remove static code checker: ${language}`,
+    buildStaticCheckRemovalConfirmationChoices(language, checkers),
+  );
+  return choice === "removal-approve";
+}
+
 /**
  * @brief Runs the interactive static-check configuration menu.
- * @details Lets the user add and remove global Command entries, toggle direct local per-language enable flags, and reset the subtree to documented defaults through the shared settings-menu renderer until the user exits. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
+ * @details Lets the user add, inspect, confirm-before-remove, and reset global Command entries, toggle direct local per-language enable flags, and reset the subtree to documented defaults through the shared settings-menu renderer until the user exits. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<void>} Promise resolved when the menu closes.
- * @satisfies REQ-008, REQ-151, REQ-152, REQ-153, REQ-154, REQ-160, REQ-161, REQ-193, REQ-195, REQ-248, REQ-253
+ * @satisfies REQ-008, REQ-151, REQ-152, REQ-153, REQ-154, REQ-160, REQ-161, REQ-193, REQ-195, REQ-248, REQ-253, REQ-345, REQ-346, REQ-347, REQ-348, REQ-349
  */
 async function configureStaticCheckMenu(
   ctx: ExtensionCommandContext,
@@ -3978,6 +4141,11 @@ async function configureStaticCheckMenu(
       continue;
     }
 
+    if (staticChoice === "view-static-check-entry") {
+      await showPiUsereqSettingsMenu(ctx, "View static code checker", buildStaticCheckViewChoices(config));
+      continue;
+    }
+
     if (staticChoice === "remove-static-check-entry") {
       const configuredLanguage = await showPiUsereqSettingsMenu(ctx, "Remove static code checker", buildConfiguredStaticCheckLanguageChoices(config));
       if (!configuredLanguage) {
@@ -4004,12 +4172,40 @@ async function configureStaticCheckMenu(
         ctx.ui.notify("Restored default static code checker configuration", "info");
         continue;
       }
+      const targetedCheckers = getStaticCheckLanguageConfigForMenu(config, configuredLanguage).checkers;
+      const removalApproved = await confirmStaticCheckRemoval(ctx, configuredLanguage, targetedCheckers);
+      if (!removalApproved) {
+        ctx.ui.notify(`Aborted removal of static-check entries for ${configuredLanguage}`, "info");
+        continue;
+      }
       config["static-check"][configuredLanguage] = createStaticCheckLanguageConfig([]);
       onConfigChange();
       ctx.ui.notify(`Removed static-check entries for ${configuredLanguage}`, "info");
       continue;
     }
 
+    if (staticChoice === "reset-static-check-entry") {
+      const approved = await confirmResetChanges(
+        ctx,
+        "Confirm static-check reset",
+        [{
+          label: "Language static code checkers",
+          previousValue: formatStaticCheckLanguagesSummary(config),
+          nextValue: formatStaticCheckLanguagesSummary({ ...config, "static-check": getDefaultStaticCheckConfig() }),
+        }].filter((change) => change.previousValue !== change.nextValue),
+        "Approve restoring the documented per-language static-check defaults.",
+        "Abort the static-check reset and keep the current values.",
+      );
+      if (!approved) {
+        ctx.ui.notify("Aborted static-check reset", "info");
+        continue;
+      }
+      resetStaticCheckConfig(config);
+      onConfigChange();
+      ctx.ui.notify("Restored default static code checker configuration", "info");
+      continue;
+    }
+
     if (staticChoice === "reset-defaults") {
       const approved = await confirmResetChanges(
         ctx,

package/tests/extension-registration.test.ts

@@ -6692,10 +6692,17 @@ test("configuration menu omits removed static-check raw-spec and reference actio
   const renderedStaticCheckMenu = (ctx.__state.customRenderLines[1] ?? []).join("\n");
   const staticCheckItems = ctx.__state.selectCalls[1]?.items ?? [];
   assert.match(renderedStaticCheckMenu, /Add static code checker/);
+  assert.match(renderedStaticCheckMenu, /View static code checker/);
   assert.match(renderedStaticCheckMenu, /Remove static code checker/);
-  assert.deepEqual(staticCheckItems.slice(0, 2), ["Add static code checker", "Remove static code checker"]);
+  assert.match(renderedStaticCheckMenu, /Reset static code checker/);
+  assert.deepEqual(staticCheckItems.slice(0, 4), [
+    "Add static code checker",
+    "View static code checker",
+    "Remove static code checker",
+    "Reset static code checker",
+  ]);
   assert.deepEqual(
-    staticCheckItems.slice(2, 22),
+    staticCheckItems.slice(4, 24),
     getSupportedStaticCheckLanguageSupport().map((entry) => entry.language),
   );
   assert.deepEqual(staticCheckItems.slice(-1), ["Reset defaults"]);