pi-usereq 0.4.0

package/src/core/config.ts

@@ -0,0 +1,272 @@
+/**
+ * @file
+ * @brief Loads, normalizes, and persists pi-usereq project configuration.
+ * @details Defines the configuration schema, default directory conventions, JSON serialization helpers, and prompt placeholder expansion paths. Runtime is dominated by filesystem reads and writes plus linear normalization over configured entries. Side effects include config-file persistence under `.pi-usereq`.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { ReqError } from "./errors.js";
+import {
+  buildRuntimePathContext,
+  buildRuntimePathFacts,
+  formatRuntimePathForDisplay,
+  getConfigPath,
+} from "./path-context.js";
+import {
+  DEFAULT_PI_NOTIFY_SOUND_HIGH_CMD,
+  DEFAULT_PI_NOTIFY_SOUND_LOW_CMD,
+  DEFAULT_PI_NOTIFY_SOUND_MID_CMD,
+  DEFAULT_PI_NOTIFY_SOUND_TOGGLE_SHORTCUT,
+  normalizePiNotifyCommand,
+  normalizePiNotifyShortcut,
+  normalizePiNotifySoundLevel,
+} from "./pi-notify.js";
+import { normalizeEnabledPiUsereqTools } from "./pi-usereq-tools.js";
+import { makeRelativeIfContainsProject } from "./utils.js";
+
+/**
+ * @brief Describes one static-check module configuration entry.
+ * @details Each record identifies the checker module and optional command or parameter list used during per-language static analysis dispatch. The interface is type-only and has no runtime cost.
+ */
+export interface StaticCheckEntry {
+  module: string;
+  cmd?: string;
+  params?: string[];
+}
+
+/**
+ * @brief Defines the persisted pi-usereq project configuration schema.
+ * @details Captures documentation paths, source/test directory selection, static-check configuration, enabled startup tools, and notification settings while excluding runtime-derived path metadata. The interface is compile-time only and introduces no runtime side effects.
+ */
+export interface UseReqConfig {
+  "docs-dir": string;
+  "tests-dir": string;
+  "src-dir": string[];
+  "static-check": Record<string, StaticCheckEntry[]>;
+  "enabled-tools": string[];
+  "notify-beep-on-end": boolean;
+  "notify-beep-on-esc": boolean;
+  "notify-beep-on-error": boolean;
+  "notify-sound": "none" | "low" | "mid" | "high";
+  "notify-sound-toggle-shortcut": string;
+  PI_NOTIFY_SOUND_LOW_CMD: string;
+  PI_NOTIFY_SOUND_MID_CMD: string;
+  PI_NOTIFY_SOUND_HIGH_CMD: string;
+}
+
+/**
+ * @brief Defines the default documentation directory relative to the project root.
+ * @details Used when no persisted `docs-dir` value exists or normalization yields an empty string. Lookup complexity is O(1).
+ * @satisfies CTN-001
+ */
+export const DEFAULT_DOCS_DIR = "pi-usereq/docs";
+/**
+ * @brief Defines the default tests directory relative to the project root.
+ * @details Used when no persisted `tests-dir` value exists or normalization yields an empty string. Lookup complexity is O(1).
+ */
+export const DEFAULT_TESTS_DIR = "tests";
+/**
+ * @brief Defines the default set of source directories relative to the project root.
+ * @details The array seeds newly created configs and repairs invalid persisted source selections. Access complexity is O(1).
+ */
+export const DEFAULT_SRC_DIRS = ["src"];
+/**
+ * @brief Computes the per-project config file path.
+ * @details Joins the project base with `.pi-usereq/config.json`, producing the canonical persistence location used by CLI and extension code. Time complexity is O(1). No I/O side effects occur.
+ * @param[in] projectBase {string} Absolute project root path.
+ * @return {string} Absolute config file path.
+ */
+export function getProjectConfigPath(projectBase: string): string {
+  return getConfigPath(projectBase);
+}
+
+/**
+ * @brief Builds the default project configuration.
+ * @details Populates canonical docs/test/source directories, the default startup tool set, and default pi-notify fields while excluding runtime-derived path metadata. Time complexity is O(n) in default tool count. No filesystem side effects occur.
+ * @param[in] projectBase {string} Absolute project root path.
+ * @return {UseReqConfig} Fresh default configuration object.
+ * @satisfies CTN-001, CTN-012, REQ-066, REQ-146
+ */
+export function getDefaultConfig(_projectBase: string): UseReqConfig {
+  return {
+    "docs-dir": DEFAULT_DOCS_DIR,
+    "tests-dir": DEFAULT_TESTS_DIR,
+    "src-dir": [...DEFAULT_SRC_DIRS],
+    "static-check": {},
+    "enabled-tools": normalizeEnabledPiUsereqTools(undefined),
+    "notify-beep-on-end": false,
+    "notify-beep-on-esc": false,
+    "notify-beep-on-error": false,
+    "notify-sound": "none",
+    "notify-sound-toggle-shortcut": DEFAULT_PI_NOTIFY_SOUND_TOGGLE_SHORTCUT,
+    PI_NOTIFY_SOUND_LOW_CMD: DEFAULT_PI_NOTIFY_SOUND_LOW_CMD,
+    PI_NOTIFY_SOUND_MID_CMD: DEFAULT_PI_NOTIFY_SOUND_MID_CMD,
+    PI_NOTIFY_SOUND_HIGH_CMD: DEFAULT_PI_NOTIFY_SOUND_HIGH_CMD,
+  };
+}
+
+/**
+ * @brief Loads and sanitizes the persisted project configuration.
+ * @details Returns defaults when the config file does not exist. Otherwise parses JSON, validates directory and static-check field shapes, normalizes enabled tool names and pi-notify fields, and ignores removed or runtime-derived path metadata. Runtime is O(n) in config size. Side effects are limited to filesystem reads.
+ * @param[in] projectBase {string} Absolute project root path.
+ * @return {UseReqConfig} Sanitized effective configuration.
+ * @throws {ReqError} Throws with exit code `11` when the config file contains invalid JSON or a non-object payload.
+ * @satisfies CTN-012, REQ-066, REQ-146
+ */
+export function loadConfig(projectBase: string): UseReqConfig {
+  const configPath = getProjectConfigPath(projectBase);
+  if (!fs.existsSync(configPath)) {
+    return getDefaultConfig(projectBase);
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch (error) {
+    throw new ReqError(`Error: invalid ${configPath}`, 11);
+  }
+
+  if (!payload || typeof payload !== "object") {
+    throw new ReqError(`Error: invalid ${configPath}`, 11);
+  }
+  const data = payload as Record<string, unknown>;
+  const docsDir = typeof data["docs-dir"] === "string" && data["docs-dir"].trim() ? data["docs-dir"] : DEFAULT_DOCS_DIR;
+  const testsDir = typeof data["tests-dir"] === "string" && data["tests-dir"].trim() ? data["tests-dir"] : DEFAULT_TESTS_DIR;
+  const srcDir = Array.isArray(data["src-dir"]) && data["src-dir"].every((item) => typeof item === "string" && item.trim())
+    ? (data["src-dir"] as string[])
+    : [...DEFAULT_SRC_DIRS];
+  const staticCheck = typeof data["static-check"] === "object" && data["static-check"] !== null
+    ? (data["static-check"] as Record<string, StaticCheckEntry[]>)
+    : {};
+  const enabledTools = normalizeEnabledPiUsereqTools(data["enabled-tools"]);
+  const notifyBeepOnEnd = data["notify-beep-on-end"] === true;
+  const notifyBeepOnEsc = data["notify-beep-on-esc"] === true;
+  const notifyBeepOnError = data["notify-beep-on-error"] === true;
+  const notifySound = normalizePiNotifySoundLevel(data["notify-sound"]);
+  const notifySoundToggleShortcut = normalizePiNotifyShortcut(data["notify-sound-toggle-shortcut"]);
+  const lowSoundCommand = normalizePiNotifyCommand(data.PI_NOTIFY_SOUND_LOW_CMD, DEFAULT_PI_NOTIFY_SOUND_LOW_CMD);
+  const midSoundCommand = normalizePiNotifyCommand(data.PI_NOTIFY_SOUND_MID_CMD, DEFAULT_PI_NOTIFY_SOUND_MID_CMD);
+  const highSoundCommand = normalizePiNotifyCommand(data.PI_NOTIFY_SOUND_HIGH_CMD, DEFAULT_PI_NOTIFY_SOUND_HIGH_CMD);
+
+  return {
+    "docs-dir": docsDir,
+    "tests-dir": testsDir,
+    "src-dir": srcDir,
+    "static-check": staticCheck,
+    "enabled-tools": enabledTools,
+    "notify-beep-on-end": notifyBeepOnEnd,
+    "notify-beep-on-esc": notifyBeepOnEsc,
+    "notify-beep-on-error": notifyBeepOnError,
+    "notify-sound": notifySound,
+    "notify-sound-toggle-shortcut": notifySoundToggleShortcut,
+    PI_NOTIFY_SOUND_LOW_CMD: lowSoundCommand,
+    PI_NOTIFY_SOUND_MID_CMD: midSoundCommand,
+    PI_NOTIFY_SOUND_HIGH_CMD: highSoundCommand,
+  };
+}
+
+/**
+ * @brief Builds the persisted configuration payload that excludes runtime-derived fields.
+ * @details Copies only the canonical persisted configuration keys into a fresh object so runtime-derived metadata such as `base-path` and `git-path` can never be written to disk. Runtime is O(n) in config size. No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective configuration object.
+ * @return {UseReqConfig} Persistable configuration payload.
+ * @satisfies CTN-012, REQ-146
+ */
+function buildPersistedConfig(config: UseReqConfig): UseReqConfig {
+  return {
+    "docs-dir": config["docs-dir"],
+    "tests-dir": config["tests-dir"],
+    "src-dir": [...config["src-dir"]],
+    "static-check": Object.fromEntries(
+      Object.entries(config["static-check"]).map(([language, entries]) => [
+        language,
+        entries.map((entry) => ({
+          module: entry.module,
+          ...(entry.cmd ? { cmd: entry.cmd } : {}),
+          ...(entry.params ? { params: [...entry.params] } : {}),
+        })),
+      ]),
+    ),
+    "enabled-tools": [...config["enabled-tools"]],
+    "notify-beep-on-end": config["notify-beep-on-end"],
+    "notify-beep-on-esc": config["notify-beep-on-esc"],
+    "notify-beep-on-error": config["notify-beep-on-error"],
+    "notify-sound": config["notify-sound"],
+    "notify-sound-toggle-shortcut": config["notify-sound-toggle-shortcut"],
+    PI_NOTIFY_SOUND_LOW_CMD: config.PI_NOTIFY_SOUND_LOW_CMD,
+    PI_NOTIFY_SOUND_MID_CMD: config.PI_NOTIFY_SOUND_MID_CMD,
+    PI_NOTIFY_SOUND_HIGH_CMD: config.PI_NOTIFY_SOUND_HIGH_CMD,
+  };
+}
+
+/**
+ * @brief Persists the project configuration to disk.
+ * @details Creates the parent `.pi-usereq` directory when necessary, strips runtime-derived fields from the serialized payload, and writes formatted JSON terminated by a newline. Runtime is O(n) in serialized config size. Side effects include directory creation and file overwrite.
+ * @param[in] projectBase {string} Absolute project root path.
+ * @param[in] config {UseReqConfig} Configuration object to persist.
+ * @return {void} No return value.
+ * @satisfies CTN-012, REQ-146
+ */
+export function saveConfig(projectBase: string, config: UseReqConfig): void {
+  const configPath = getProjectConfigPath(projectBase);
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify(buildPersistedConfig(config), null, 2)}\n`, "utf8");
+}
+
+/**
+ * @brief Normalizes persisted directory fields to project-relative forms.
+ * @details Rewrites docs, tests, and source directories using project containment heuristics, strips trailing separators, and restores defaults for empty results. Runtime is O(n) in configured path count plus path-length processing. No filesystem writes occur.
+ * @param[in] projectBase {string} Absolute project root path.
+ * @param[in] config {UseReqConfig} Configuration object to normalize.
+ * @return {UseReqConfig} Normalized configuration copy.
+ */
+export function normalizeConfigPaths(projectBase: string, config: UseReqConfig): UseReqConfig {
+  const docsDir = makeRelativeIfContainsProject(config["docs-dir"], projectBase).replace(/[/\\]+$/, "") || DEFAULT_DOCS_DIR;
+  const testsDir = makeRelativeIfContainsProject(config["tests-dir"], projectBase).replace(/[/\\]+$/, "") || DEFAULT_TESTS_DIR;
+  const srcDirs = config["src-dir"].map((value) => makeRelativeIfContainsProject(value, projectBase).replace(/[/\\]+$/, "")).filter(Boolean);
+  return {
+    ...config,
+    "docs-dir": docsDir,
+    "tests-dir": testsDir,
+    "src-dir": srcDirs.length > 0 ? srcDirs : [...DEFAULT_SRC_DIRS],
+  };
+}
+
+/**
+ * @brief Builds placeholder replacements for bundled prompt rendering.
+ * @details Computes runtime path context from the execution path, derives installation-owned template and guideline paths, enumerates visible guideline files from the installed resource tree, and returns the token map consumed by prompt templates. Runtime is O(g log g + s) where g is guideline count and s is source-directory count. Side effects are limited to filesystem reads.
+ * @param[in] projectBase {string} Absolute project root path.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @return {Record<string, string>} Placeholder-to-string replacement map including runtime path tokens.
+ * @satisfies REQ-002, REQ-103, REQ-106, REQ-107, CTN-011
+ */
+export function buildPromptReplacementPaths(projectBase: string, config: UseReqConfig): Record<string, string> {
+  const runtimePathContext = buildRuntimePathContext(projectBase, config);
+  const runtimePathFacts = buildRuntimePathFacts(runtimePathContext);
+  const guidelineEntries = fs.existsSync(runtimePathContext.guidelinesPath)
+    ? fs.readdirSync(runtimePathContext.guidelinesPath)
+        .filter((entry) => !entry.startsWith("."))
+        .map((entry) => formatRuntimePathForDisplay(path.join(runtimePathContext.guidelinesPath, entry)))
+        .sort((left, right) => left.localeCompare(right))
+    : [];
+
+  const srcValue = config["src-dir"].map((value) => `\`${value.replace(/[/\\]+$/, "")}/\``).join(", ");
+  const testValue = `\`${config["tests-dir"].replace(/[/\\]+$/, "")}/\``;
+  const guidelinesValue = guidelineEntries.length > 0
+    ? guidelineEntries.map((entry) => `\`${entry}\``).join(", ")
+    : `\`${runtimePathFacts.guidelines_path}/\``;
+
+  return {
+    "%%DOC_PATH%%": config["docs-dir"].replace(/[/\\]+$/, ""),
+    "%%GUIDELINES_FILES%%": guidelinesValue,
+    "%%GUIDELINES_PATH%%": runtimePathFacts.guidelines_path,
+    "%%TEMPLATE_PATH%%": runtimePathFacts.templates_path,
+    "%%SRC_PATHS%%": srcValue,
+    "%%TEST_PATH%%": testValue,
+    "%%PROJECT_BASE%%": runtimePathFacts.base_path,
+    "%%EXECUTION_PATH%%": runtimePathFacts.execution_path,
+    "%%INSTALLATION_PATH%%": runtimePathFacts.installation_path,
+    "%%CONFIG_PATH%%": runtimePathFacts.config_path,
+  };
+}

package/src/core/doxygen-parser.ts

@@ -0,0 +1,318 @@
+/**
+ * @file
+ * @brief Parses repository-approved Doxygen tags and renders them as markdown bullets.
+ * @details Implements a constrained Doxygen grammar used by the source analyzer and construct finder. Parsing cost is linear in comment length. The module is pure and performs no I/O.
+ */
+
+/**
+ * @brief Defines the ordered repository Doxygen tag taxonomy.
+ * @details The array is reused for validation, parsing precedence, and markdown serialization order. Lookup by index is O(1); scans are O(n) in tag count. The list is immutable after module load.
+ */
+export const DOXYGEN_TAGS = [
+  "brief",
+  "details",
+  "param",
+  "param[in]",
+  "param[out]",
+  "param[in,out]",
+  "return",
+  "retval",
+  "exception",
+  "throws",
+  "warning",
+  "deprecated",
+  "note",
+  "see",
+  "sa",
+  "satisfies",
+  "pre",
+  "post",
+] as const;
+
+/**
+ * @brief Lists supported tags that are not parameter variants.
+ * @details Derived once from `DOXYGEN_TAGS` to simplify regex construction for parsers that need to discriminate `@param` forms from all other tags. Construction complexity is O(n).
+ */
+const NON_PARAM_TAGS = DOXYGEN_TAGS.filter(
+  (tag) => !["param", "param[in]", "param[in,out]", "param[out]"].includes(tag),
+);
+
+/**
+ * @brief Builds the escaped alternation fragment for non-parameter tags.
+ * @details Sorts longer tags first to preserve greedy matching semantics in the main parser regex. Construction complexity is O(n log n) due to sorting. The resulting string is immutable.
+ */
+const NON_PARAM_TAG_ALTERNATION = [...NON_PARAM_TAGS]
+  .sort((a, b) => b.length - a.length)
+  .map((tag) => tag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+  .join("|");
+
+/**
+ * @brief Matches repository-supported Doxygen tags inside comment text.
+ * @details Captures `@param` plus optional direction modifiers separately from all other approved tags so downstream parsing can normalize them into deterministic keys. Regex evaluation is linear in comment size under expected inputs.
+ */
+const DOXYGEN_TAG_PATTERN = new RegExp(
+  String.raw`[@\\](?:(param)(\[[^\]]+\])?|(${NON_PARAM_TAG_ALTERNATION}))`,
+  "g",
+);
+
+/**
+ * @brief Represents parsed Doxygen fields grouped by normalized tag name.
+ * @details Each key maps to one or more textual payloads because the same tag may appear multiple times in a single comment. The alias is compile-time only and adds no runtime cost.
+ */
+export type DoxygenFieldMap = Record<string, string[]>;
+
+/**
+ * @brief Enumerates supported structured parameter directions.
+ * @details Normalizes `@param` direction modifiers into one small closed set so agents can branch on parameter flow without reparsing raw tag names. The alias is compile-time only and introduces no runtime cost.
+ */
+export type StructuredDoxygenParamDirection = "in" | "out" | "in,out" | "unspecified";
+
+/**
+ * @brief Describes one structured Doxygen parameter field.
+ * @details Separates parameter direction, optional parameter name, optional declared type, and residual text so agents can access argument contracts without reparsing monolithic tag strings. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface StructuredDoxygenParameterEntry {
+  direction: StructuredDoxygenParamDirection;
+  parameter_name?: string;
+  value_type?: string;
+  description?: string;
+  text?: string;
+}
+
+/**
+ * @brief Describes the structured Doxygen field contract used by LLM-oriented JSON payloads.
+ * @details Converts repeated raw tag strings into tag-specific arrays and specialized parameter records while keeping unsplittable residual text local to the affected field. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface StructuredDoxygenFields {
+  brief?: string[];
+  details?: string[];
+  params?: StructuredDoxygenParameterEntry[];
+  returns?: string[];
+  retvals?: string[];
+  exceptions?: string[];
+  throws?: string[];
+  warnings?: string[];
+  deprecated?: string[];
+  notes?: string[];
+  see_also?: string[];
+  satisfies_requirement_ids?: string[];
+  preconditions?: string[];
+  postconditions?: string[];
+}
+
+/**
+ * @brief Parses repository-approved Doxygen fields from one comment block.
+ * @details Normalizes line endings, strips comment delimiters, locates supported tags, and accumulates tag payloads in declaration order. Unsupported content is ignored. Runtime is O(n) in comment length. No side effects occur.
+ * @param[in] commentText {string} Raw comment text including delimiters.
+ * @return {DoxygenFieldMap} Parsed tag payloads keyed by normalized tag name.
+ */
+export function parseDoxygenComment(commentText: string): DoxygenFieldMap {
+  if (!commentText?.trim()) {
+    return {};
+  }
+
+  const result: DoxygenFieldMap = {};
+  const text = stripCommentDelimiters(commentText.replace(/\r\n/g, "\n").replace(/\r/g, "\n"));
+  const matches = [...text.matchAll(DOXYGEN_TAG_PATTERN)];
+  if (matches.length === 0) {
+    return {};
+  }
+
+  matches.forEach((match, index) => {
+    const paramTag = match[1];
+    const direction = match[2] ?? "";
+    const nonParamTag = match[3];
+    const normalizedTag = paramTag ? `param${direction}` : nonParamTag;
+    if (!normalizedTag) {
+      return;
+    }
+
+    const startPos = match.index! + match[0].length;
+    const endPos = index + 1 < matches.length ? matches[index + 1]!.index! : text.length;
+    const content = normalizeWhitespace(text.slice(startPos, endPos).trim());
+    if (!content) {
+      return;
+    }
+
+    result[normalizedTag] ??= [];
+    result[normalizedTag].push(content);
+  });
+
+  return result;
+}
+
+/**
+ * @brief Removes language comment delimiters from raw comment text.
+ * @details Drops standalone opening and closing markers, strips leading comment prefixes on each line, and preserves semantic payload lines only. Runtime is O(n) in line count. No external state is mutated.
+ * @param[in] text {string} Raw comment text.
+ * @return {string} Cleaned multi-line payload without delimiter syntax.
+ */
+export function stripCommentDelimiters(text: string): string {
+  const cleanedLines: string[] = [];
+  for (const line of text.split("\n")) {
+    let stripped = line.trim();
+    if (["/**", "/*", "*/", '"""', "'''", "/*!", "///", "//!"].includes(stripped)) {
+      continue;
+    }
+    stripped = stripped.replace(/^[/*#]+\s*/, "");
+    stripped = stripped.replace(/^\*\s*/, "");
+    stripped = stripped.replace(/^\/\/\/?!?\s*/, "");
+    stripped = stripped.replace(/^#+\s*/, "");
+    if (stripped) {
+      cleanedLines.push(stripped);
+    }
+  }
+  return cleanedLines.join("\n");
+}
+
+/**
+ * @brief Collapses redundant whitespace while preserving paragraph boundaries.
+ * @details Converts repeated spaces to single spaces, trims each line, and reduces multiple blank lines to one blank separator. Runtime is O(n) in text length. No side effects occur.
+ * @param[in] text {string} Input text to normalize.
+ * @return {string} Canonically spaced text.
+ */
+export function normalizeWhitespace(text: string): string {
+  const lines = text.replace(/ +/g, " ").split("\n").map((line) => line.trim());
+  const normalized: string[] = [];
+  let prevBlank = false;
+  for (const line of lines) {
+    if (!line) {
+      if (!prevBlank) {
+        normalized.push(line);
+      }
+      prevBlank = true;
+    } else {
+      normalized.push(line);
+      prevBlank = false;
+    }
+  }
+  return normalized.join("\n").trim();
+}
+
+/**
+ * @brief Serializes parsed Doxygen fields into markdown bullet lines.
+ * @details Iterates over `DOXYGEN_TAGS` in canonical order and emits one `- @tag value` line for every stored payload. Runtime is O(t + v) where t is tag count and v is total values. No side effects occur.
+ * @param[in] doxygenFields {DoxygenFieldMap} Parsed Doxygen field map.
+ * @return {string[]} Ordered markdown bullet lines.
+ */
+export function formatDoxygenFieldsAsMarkdown(doxygenFields: DoxygenFieldMap): string[] {
+  const lines: string[] = [];
+  for (const tag of DOXYGEN_TAGS) {
+    const values = doxygenFields[tag] ?? [];
+    for (const value of values) {
+      lines.push(`- @${tag} ${value}`);
+    }
+  }
+  return lines;
+}
+
+/**
+ * @brief Counts the total number of parsed Doxygen field values.
+ * @details Sums the value-array lengths across all tags so payload builders can expose aggregate Doxygen density as a numeric fact. Runtime is O(t) in tag count. No side effects occur.
+ * @param[in] doxygenFields {DoxygenFieldMap} Parsed Doxygen fields.
+ * @return {number} Total stored Doxygen value count.
+ */
+export function countDoxygenFieldValues(doxygenFields: DoxygenFieldMap): number {
+  return Object.values(doxygenFields).reduce((sum, values) => sum + values.length, 0);
+}
+
+/**
+ * @brief Parses one raw Doxygen parameter value into structured fields.
+ * @details Supports the repository-preferred `name {type} description` form, the alternate `{type} name description` form, and a residual-text fallback when no safe split is possible. Runtime is O(n) in value length. No side effects occur.
+ * @param[in] value {string} Raw Doxygen parameter value.
+ * @param[in] direction {StructuredDoxygenParamDirection} Normalized parameter direction.
+ * @return {StructuredDoxygenParameterEntry} Structured parameter record.
+ */
+function structureDoxygenParameterValue(value: string, direction: StructuredDoxygenParamDirection): StructuredDoxygenParameterEntry {
+  const trimmed = value.trim();
+  const preferredMatch = trimmed.match(/^([^\s{}]+)(?:\s+\{([^}]+)\})?(?:\s+(.+))?$/);
+  if (preferredMatch) {
+    const [, parameterName, valueType, description] = preferredMatch;
+    if (parameterName) {
+      return {
+        direction,
+        parameter_name: parameterName,
+        value_type: valueType,
+        description: description?.trim() || undefined,
+      };
+    }
+  }
+
+  const alternateMatch = trimmed.match(/^\{([^}]+)\}\s+([^\s{}]+)(?:\s+(.+))?$/);
+  if (alternateMatch) {
+    const [, valueType, parameterName, description] = alternateMatch;
+    return {
+      direction,
+      parameter_name: parameterName,
+      value_type: valueType,
+      description: description?.trim() || undefined,
+    };
+  }
+
+  return {
+    direction,
+    text: trimmed,
+  };
+}
+
+/**
+ * @brief Splits comma-delimited Doxygen value strings into normalized items.
+ * @details Trims surrounding whitespace, drops empty segments, and preserves original declaration order. Runtime is O(n) in aggregate text length. No side effects occur.
+ * @param[in] values {string[] | undefined} Raw Doxygen value strings.
+ * @return {string[]} Normalized item list.
+ */
+function splitCommaSeparatedDoxygenValues(values: string[] | undefined): string[] {
+  return (values ?? [])
+    .flatMap((value) => value.split(","))
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+/**
+ * @brief Extracts normalized requirement IDs from raw `@satisfies` values.
+ * @details Matches repository requirement ID prefixes directly from the raw value text so agents receive requirement links as a dedicated string array. Runtime is O(n) in aggregate text length. No side effects occur.
+ * @param[in] values {string[] | undefined} Raw `@satisfies` values.
+ * @return {string[]} Normalized requirement IDs in declaration order.
+ */
+function extractSatisfiedRequirementIds(values: string[] | undefined): string[] {
+  const matches = (values ?? []).flatMap((value) => value.match(/\b(?:PRJ|CTN|DES|REQ|TST)-\d+\b/g) ?? []);
+  return [...new Set(matches)];
+}
+
+/**
+ * @brief Converts raw parsed Doxygen fields into the structured JSON contract.
+ * @details Reorders raw tags into tag-specific arrays, structures parameter fields, normalizes `@see` aliases, and extracts requirement IDs from `@satisfies`. Runtime is O(t + v) where t is tag count and v is total value count. No side effects occur.
+ * @param[in] doxygenFields {DoxygenFieldMap} Raw parsed Doxygen field map.
+ * @return {StructuredDoxygenFields} Structured Doxygen fields.
+ * @satisfies REQ-078
+ */
+export function structureDoxygenFields(doxygenFields: DoxygenFieldMap): StructuredDoxygenFields {
+  const params = [
+    ...(doxygenFields["param"] ?? []).map((value) => structureDoxygenParameterValue(value, "unspecified")),
+    ...(doxygenFields["param[in]"] ?? []).map((value) => structureDoxygenParameterValue(value, "in")),
+    ...(doxygenFields["param[out]"] ?? []).map((value) => structureDoxygenParameterValue(value, "out")),
+    ...(doxygenFields["param[in,out]"] ?? []).map((value) => structureDoxygenParameterValue(value, "in,out")),
+  ];
+  const seeAlso = [
+    ...splitCommaSeparatedDoxygenValues(doxygenFields["see"]),
+    ...splitCommaSeparatedDoxygenValues(doxygenFields["sa"]),
+  ];
+  const satisfiesRequirementIds = extractSatisfiedRequirementIds(doxygenFields["satisfies"]);
+  const structured: StructuredDoxygenFields = {};
+
+  if (doxygenFields["brief"]?.length) structured.brief = [...doxygenFields["brief"]];
+  if (doxygenFields["details"]?.length) structured.details = [...doxygenFields["details"]];
+  if (params.length) structured.params = params;
+  if (doxygenFields["return"]?.length) structured.returns = [...doxygenFields["return"]];
+  if (doxygenFields["retval"]?.length) structured.retvals = [...doxygenFields["retval"]];
+  if (doxygenFields["exception"]?.length) structured.exceptions = [...doxygenFields["exception"]];
+  if (doxygenFields["throws"]?.length) structured.throws = [...doxygenFields["throws"]];
+  if (doxygenFields["warning"]?.length) structured.warnings = [...doxygenFields["warning"]];
+  if (doxygenFields["deprecated"]?.length) structured.deprecated = [...doxygenFields["deprecated"]];
+  if (doxygenFields["note"]?.length) structured.notes = [...doxygenFields["note"]];
+  if (seeAlso.length) structured.see_also = seeAlso;
+  if (satisfiesRequirementIds.length) structured.satisfies_requirement_ids = satisfiesRequirementIds;
+  if (doxygenFields["pre"]?.length) structured.preconditions = [...doxygenFields["pre"]];
+  if (doxygenFields["post"]?.length) structured.postconditions = [...doxygenFields["post"]];
+  return structured;
+}

package/src/core/errors.ts

@@ -0,0 +1,31 @@
+/**
+ * @file
+ * @brief Defines the repository-specific error class used by CLI and extension workflows.
+ * @details Centralizes deterministic failure signaling by pairing an error message with a numeric exit code. The module is pure and performs no I/O. Access complexity is O(1).
+ */
+
+/**
+ * @brief Represents a useReq failure with a stable numeric exit code.
+ * @details Extends `Error` so callers can propagate human-readable diagnostics together with process-style status codes. Construction and property access are O(1). State mutation is limited to the created instance.
+ */
+export class ReqError extends Error {
+  /**
+   * @brief Stores the process-style exit code associated with the failure.
+   * @details Downstream CLI and extension handlers read this field to decide the final command status. Access complexity is O(1). The field is assigned during construction.
+   */
+  code: number;
+
+  /**
+   * @brief Initializes a ReqError instance.
+   * @details Assigns the inherited error message, normalizes the runtime name to `ReqError`, and stores the provided numeric exit code. Time complexity is O(1). Side effects are limited to instance field mutation.
+   * @param[in] message {string} Human-readable failure description.
+   * @param[in] code {number} Process exit code associated with the failure. Defaults to `1`.
+   * @post `this.name === "ReqError"`.
+   * @post `this.code === code`.
+   */
+  constructor(message: string, code = 1) {
+    super(message);
+    this.name = "ReqError";
+    this.code = code;
+  }
+}