pi-usereq 0.5.0 → 0.7.0

package/src/core/reference-payload.ts

@@ -182,10 +182,9 @@ export interface ReferenceToolRepositorySection {
 
 /**
  * @brief Describes the full agent-oriented references payload.
- * @details Orders the top-level sections as request, summary, repository, and files for deterministic downstream traversal. The interface is compile-time only and introduces no runtime cost.
+ * @details Exposes only aggregate analysis totals, repository structure, and per-file reference records, omitting request echoes that are already known to the caller or encoded in the tool registration. The interface is compile-time only and introduces no runtime cost.
  */
 export interface ReferenceToolPayload {
-  request: ReferenceToolRequestSection;
   summary: ReferenceToolSummarySection;
   repository: ReferenceToolRepositorySection;
   files: ReferenceToolFileEntry[];
@@ -663,9 +662,9 @@ function analyzeReferenceFile(
 
 /**
  * @brief Builds the full agent-oriented references payload.
- * @details Validates requested paths against the filesystem, analyzes processable files in caller order, preserves skipped and failed inputs in structured file entries, computes aggregate numeric totals, and emits a structured repository tree. Runtime is O(F log F + S). Side effects are limited to filesystem reads and optional stderr logging.
+ * @details Validates requested paths against the filesystem, analyzes processable files in caller order, preserves skipped and failed inputs in structured file entries, computes aggregate numeric totals, and emits structured repository data without echoing request metadata already known to the caller. Runtime is O(F log F + S). Side effects are limited to filesystem reads and optional stderr logging.
  * @param[in] options {BuildReferenceToolPayloadOptions} Payload-construction options.
- * @return {ReferenceToolPayload} Structured references payload ordered as request, summary, repository, and files.
+ * @return {ReferenceToolPayload} Structured references payload ordered as summary, repository, and files.
  * @satisfies REQ-011, REQ-014, REQ-076, REQ-077, REQ-078, REQ-079
  */
 export function buildReferenceToolPayload(options: BuildReferenceToolPayloadOptions): ReferenceToolPayload {
@@ -761,17 +760,10 @@ export function buildReferenceToolPayload(options: BuildReferenceToolPayloadOpti
   const repositoryFileCanonicalPaths = [...new Set(analyzedFiles.map((file) => file.canonical_path))]
     .sort((left, right) => left.localeCompare(right));
 
+  void toolName;
+  void scope;
+  void canonicalRequestedPaths;
   return {
-    request: {
-      tool_name: toolName,
-      scope,
-      base_dir_path: absoluteBaseDir,
-      source_directory_count: sourceDirectoryPaths.length,
-      source_directory_paths: sourceDirectoryPaths.map((sourceDirectoryPath) => canonicalizeReferencePath(sourceDirectoryPath, absoluteBaseDir)),
-      requested_file_count: requestedPaths.length,
-      requested_input_paths: [...requestedPaths],
-      requested_canonical_paths: canonicalRequestedPaths,
-    },
     summary: {
       processable_file_count: processableFiles.length,
       analyzed_file_count: analyzedFiles.length,

package/src/core/settings-menu.ts

@@ -26,10 +26,21 @@ export interface PiUsereqSettingsMenuChoice {
 export interface PiUsereqSettingsMenuBridge {
   title: string;
   choices: PiUsereqSettingsMenuChoice[];
+  selectedChoiceId?: string;
   selectByLabel: (label: string) => boolean;
   cancel: () => void;
 }
 
+/**
+ * @brief Describes optional behavior overrides for one settings-menu render.
+ * @details Carries the caller-selected initial focus row so menu re-renders can
+ * preserve selection after an in-place toggle or value edit. The interface is
+ * compile-time only and introduces no runtime cost.
+ */
+export interface PiUsereqSettingsMenuOptions {
+  initialSelectedId?: string;
+}
+
 /**
  * @brief Represents a custom menu component augmented with the offline bridge.
  * @details Extends the generic TUI `Component` contract with one optional bridge field consumed only by deterministic test and debug harness adapters. The interface is compile-time only and introduces no runtime cost.
@@ -177,13 +188,15 @@ function buildSettingItems(
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in] title {string} Menu title displayed in the heading and offline bridge.
  * @param[in] choices {PiUsereqSettingsMenuChoice[]} Ordered menu-choice vector.
+ * @param[in] options {PiUsereqSettingsMenuOptions | undefined} Optional initial-focus override.
  * @return {Promise<string | undefined>} Selected choice identifier or `undefined` when cancelled.
- * @satisfies REQ-151, REQ-152, REQ-153, REQ-154, REQ-156
+ * @satisfies REQ-151, REQ-152, REQ-153, REQ-154, REQ-156, REQ-192
  */
 export async function showPiUsereqSettingsMenu(
   ctx: ExtensionCommandContext,
   title: string,
   choices: PiUsereqSettingsMenuChoice[],
+  options: PiUsereqSettingsMenuOptions = {},
 ): Promise<string | undefined> {
   return ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => {
     const container = new Container();
@@ -199,6 +212,12 @@ export async function showPiUsereqSettingsMenu(
       () => undefined,
       () => done(undefined),
     );
+    const initialSelectedIndex = options.initialSelectedId === undefined
+      ? 0
+      : choices.findIndex((choice) => choice.id === options.initialSelectedId);
+    if (initialSelectedIndex >= 0) {
+      (settingsList as SettingsList & { selectedIndex: number }).selectedIndex = initialSelectedIndex;
+    }
     container.addChild(titleText);
     container.addChild(new Text("", 0, 0));
     container.addChild(settingsList);
@@ -218,6 +237,7 @@ export async function showPiUsereqSettingsMenu(
       __piUsereqSettingsMenu: {
         title,
         choices,
+        selectedChoiceId: initialSelectedIndex >= 0 ? choices[initialSelectedIndex]?.id : undefined,
         selectByLabel(label: string): boolean {
           const choice = choices.find(
             (candidate) => candidate.label === label || candidate.id === label,

package/src/core/token-counter.ts

@@ -6,9 +6,10 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { getEncoding } from "js-tiktoken";
+import { createRequire } from "node:module";
 import { detectLanguage as detectSourceLanguage } from "./compress.js";
 import { parseDoxygenComment, type DoxygenFieldMap } from "./doxygen-parser.js";
+import { ReqError } from "./errors.js";
 
 /**
  * @brief Declares the tokenizer encoding used by token-count workflows.
@@ -175,13 +176,11 @@ export interface TokenToolGuidanceSection {
 
 /**
  * @brief Describes the full agent-oriented token payload.
- * @details Orders the top-level sections as request, summary, files, and guidance for deterministic downstream traversal. The interface is compile-time only and introduces no runtime cost.
+ * @details Exposes only aggregate numeric totals plus per-file metrics, omitting request echoes and derived guidance that can be inferred from tool registration or recomputed by the caller. The interface is compile-time only and introduces no runtime cost.
  */
 export interface TokenToolPayload {
-  request: TokenToolRequestSection;
   summary: TokenToolSummarySection;
   files: TokenToolFileEntry[];
-  guidance: TokenToolGuidanceSection;
 }
 
 /**
@@ -198,6 +197,57 @@ export interface BuildTokenToolPayloadOptions {
   encodingName?: string;
 }
 
+type TokenCounterEncoding = {
+  encode(content: string): ArrayLike<number>;
+};
+
+type JsTiktokenModule = {
+  getEncoding(encodingName: string): TokenCounterEncoding;
+};
+
+const require = createRequire(import.meta.url);
+
+function defaultJsTiktokenModuleLoader(): JsTiktokenModule {
+  return require("js-tiktoken") as JsTiktokenModule;
+}
+
+let jsTiktokenModuleLoader: () => JsTiktokenModule = defaultJsTiktokenModuleLoader;
+
+/**
+ * @brief Overrides the `js-tiktoken` loader for tests.
+ * @details Enables deterministic dependency-failure tests without mutating repository dependencies on disk. Runtime is O(1). Side effects are limited to module-local test state.
+ * @param[in] loader {(() => JsTiktokenModule) | undefined} Replacement loader, or `undefined` to restore the default loader.
+ * @return {void} No return value.
+ */
+export function setJsTiktokenModuleLoaderForTests(loader?: () => JsTiktokenModule): void {
+  jsTiktokenModuleLoader = loader ?? defaultJsTiktokenModuleLoader;
+}
+
+/**
+ * @brief Loads the `js-tiktoken` module on demand.
+ * @details Defers dependency resolution until token counting is requested so extension registration can succeed even when the optional runtime dependency has not yet been installed. Runtime is O(1) plus module resolution cost. Side effects are limited to Node module loading.
+ * @return {JsTiktokenModule} Loaded tokenizer module.
+ * @throws {ReqError} Throws when `js-tiktoken` is unavailable.
+ */
+function loadJsTiktokenModule(): JsTiktokenModule {
+  try {
+    const module = jsTiktokenModuleLoader();
+    if (!module || typeof module.getEncoding !== "function") {
+      throw new ReqError("Error: token-count dependency 'js-tiktoken' is unavailable. Run `npm ci` in the PI-useReq repository.", 1);
+    }
+    return module;
+  } catch (error) {
+    if (error instanceof ReqError) {
+      throw error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (/Cannot find (module|package) 'js-tiktoken'|ERR_MODULE_NOT_FOUND/.test(message)) {
+      throw new ReqError("Error: token-count dependency 'js-tiktoken' is not installed. Run `npm ci` in the PI-useReq repository.", 1);
+    }
+    throw error;
+  }
+}
+
 /**
  * @brief Encapsulates one tokenizer instance for repeated token counting.
  * @details Caches a `js-tiktoken` encoding object so multiple documents can be counted without repeated encoding lookup. Counting cost is O(n) in content length. The class mutates only instance state during construction.
@@ -207,7 +257,7 @@ export class TokenCounter {
    * @brief Stores the tokenizer implementation used for subsequent counts.
    * @details The field holds the encoder returned by `getEncoding`. Access complexity is O(1). The value is initialized once per instance.
    */
-  private encoding;
+  private encoding: TokenCounterEncoding;
 
   /**
    * @brief Initializes a token counter for one encoding family.
@@ -216,7 +266,7 @@ export class TokenCounter {
    * @return {TokenCounter} New token counter instance.
    */
   constructor(encodingName = TOKEN_COUNTER_ENCODING) {
-    this.encoding = getEncoding(encodingName);
+    this.encoding = loadJsTiktokenModule().getEncoding(encodingName);
   }
 
   /**
@@ -359,41 +409,6 @@ function roundRatio(numerator: number, denominator: number): number {
   return Number((numerator / denominator).toFixed(6));
 }
 
-/**
- * @brief Orders canonical file paths by one numeric metric while removing duplicates.
- * @details Filters to counted file entries, sorts by the supplied metric direction, breaks ties by canonical path, and preserves only the first occurrence of each path. Runtime is O(n log n). No external state is mutated.
- * @param[in] files {TokenToolFileEntry[]} Token payload file entries.
- * @param[in] metric {(entry: TokenToolFileEntry) => number} Numeric metric selector.
- * @param[in] direction {"asc" | "desc"} Sort direction.
- * @return {string[]} Unique canonical paths ordered by the requested metric.
- */
-function orderPathsByMetric(
-  files: TokenToolFileEntry[],
-  metric: (entry: TokenToolFileEntry) => number,
-  direction: "asc" | "desc",
-): string[] {
-  const sorted = files
-    .filter((entry) => entry.status === "counted")
-    .sort((left, right) => {
-      const leftMetric = metric(left);
-      const rightMetric = metric(right);
-      if (leftMetric === rightMetric) {
-        return left.canonical_path.localeCompare(right.canonical_path);
-      }
-      return direction === "desc" ? rightMetric - leftMetric : leftMetric - rightMetric;
-    });
-  const seen = new Set<string>();
-  const orderedPaths: string[] = [];
-  for (const entry of sorted) {
-    if (seen.has(entry.canonical_path)) {
-      continue;
-    }
-    seen.add(entry.canonical_path);
-    orderedPaths.push(entry.canonical_path);
-  }
-  return orderedPaths;
-}
-
 /**
  * @brief Probes one requested path before token counting.
  * @details Resolves whether the target exists and is a regular file while capturing a stable skip reason for missing or non-file inputs. Runtime is dominated by one filesystem stat. Side effects are limited to filesystem reads.
@@ -496,9 +511,9 @@ export function countFilesMetrics(filePaths: string[], encodingName = TOKEN_COUN
 
 /**
  * @brief Builds the agent-oriented JSON payload for token-centric tools.
- * @details Validates requested paths against the filesystem, counts token metrics for processable files, preserves caller order in the file table, separates raw observations from derived guidance, and emits direct-access file facts such as line ranges, sizes, headings, and optional Doxygen file fields. Runtime is O(F log F + S). Side effects are limited to filesystem reads.
+ * @details Validates requested paths against the filesystem, counts token metrics for processable files, preserves caller order in the file table, and emits direct-access file facts such as sizes, headings, and optional Doxygen file fields while omitting request echoes and derived guidance. Runtime is O(F + S). Side effects are limited to filesystem reads.
  * @param[in] options {BuildTokenToolPayloadOptions} Payload-construction options.
- * @return {TokenToolPayload} Structured token payload ordered as request, summary, files, guidance.
+ * @return {TokenToolPayload} Structured token payload ordered as summary then files.
  * @satisfies REQ-010, REQ-017, REQ-069, REQ-070, REQ-071, REQ-073, REQ-074, REQ-075
  */
 export function buildTokenToolPayload(options: BuildTokenToolPayloadOptions): TokenToolPayload {
@@ -596,71 +611,7 @@ export function buildTokenToolPayload(options: BuildTokenToolPayloadOptions): To
   const countedFileCount = filesWithShares.filter((entry) => entry.status === "counted").length;
   const errorFileCount = filesWithShares.filter((entry) => entry.status === "error").length;
   const skippedFileCount = filesWithShares.filter((entry) => entry.status === "skipped").length;
-  const countedPathsByTokenCountDesc = orderPathsByMetric(filesWithShares, (entry) => entry.token_count, "desc");
-  const countedPathsByTokenCountAsc = orderPathsByMetric(filesWithShares, (entry) => entry.token_count, "asc");
-  const countedPathsByLineCountDesc = orderPathsByMetric(filesWithShares, (entry) => entry.line_count, "desc");
-  const dominantTokenFileEntry = filesWithShares
-    .filter((entry) => entry.status === "counted")
-    .sort((left, right) => {
-      if (left.token_count === right.token_count) {
-        return left.canonical_path.localeCompare(right.canonical_path);
-      }
-      return right.token_count - left.token_count;
-    })[0];
-  const skippedInputs = filesWithShares
-    .filter((entry) => entry.status === "skipped" && entry.error_message)
-    .map((entry) => ({
-      input_path: entry.input_path,
-      canonical_path: entry.canonical_path,
-      reason: entry.error_message!,
-    }));
-  const errorInputs = filesWithShares
-    .filter((entry) => entry.status === "error" && entry.error_message)
-    .map((entry) => ({
-      input_path: entry.input_path,
-      canonical_path: entry.canonical_path,
-      reason: entry.error_message!,
-    }));
-  const derivedRecommendations: TokenToolRecommendation[] = countedPathsByTokenCountDesc.length > 0
-    ? [
-      {
-        kind: "prioritize_high_token_paths",
-        basis_metric_name: "token_count",
-        ordered_paths: countedPathsByTokenCountDesc,
-      },
-      {
-        kind: "defer_low_token_paths",
-        basis_metric_name: "token_count",
-        ordered_paths: countedPathsByTokenCountAsc,
-      },
-    ]
-    : [];
-  const actionableNextSteps: TokenToolNextStepHint[] = countedPathsByTokenCountDesc.length > 0
-    ? [
-      {
-        kind: "read_top_token_paths_first",
-        ordered_paths: countedPathsByTokenCountDesc.slice(0, 3),
-        goal: "minimize context-truncation risk during initial review",
-      },
-      {
-        kind: "reserve_low_token_paths_for_follow_up",
-        ordered_paths: countedPathsByTokenCountAsc.slice(0, 3),
-        goal: "defer lower-cost files until high-cost files have been reviewed",
-      },
-    ]
-    : [];
   return {
-    request: {
-      tool_name: options.toolName,
-      scope: options.scope,
-      encoding_name: encodingName,
-      base_dir_path: baseDir.split(path.sep).join("/"),
-      requested_file_count: options.requestedPaths.length,
-      requested_input_paths: options.requestedPaths,
-      requested_canonical_paths: requestedEntries.map((entry) => entry.canonicalPath),
-      docs_dir_path: options.docsDir,
-      canonical_doc_names: options.canonicalDocNames,
-    },
     summary: {
       processable_file_count: countedFileCount + errorFileCount,
       counted_file_count: countedFileCount,
@@ -676,23 +627,6 @@ export function buildTokenToolPayload(options: BuildTokenToolPayloadOptions): To
       average_line_count_per_counted_file: countedFileCount === 0 ? 0 : Number((totalLineCount / countedFileCount).toFixed(6)),
     },
     files: filesWithShares,
-    guidance: {
-      source_observations: {
-        counted_paths_by_token_count_desc: countedPathsByTokenCountDesc,
-        counted_paths_by_line_count_desc: countedPathsByLineCountDesc,
-        skipped_inputs: skippedInputs,
-        error_inputs: errorInputs,
-        dominant_token_file: dominantTokenFileEntry
-          ? {
-            canonical_path: dominantTokenFileEntry.canonical_path,
-            token_count: dominantTokenFileEntry.token_count,
-            token_share: dominantTokenFileEntry.token_share,
-          }
-          : undefined,
-      },
-      derived_recommendations: derivedRecommendations,
-      actionable_next_steps: actionableNextSteps,
-    },
   };
 }