pi-usereq 0.48.0 → 0.50.0

package/tests/helpers.ts

@@ -1,236 +0,0 @@
-import assert from "node:assert/strict";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { createRequire } from "node:module";
-import {
-  DEFAULT_DOCS_DIR,
-  getDefaultConfig,
-  getGlobalConfigPath,
-  getProjectConfigPath,
-  saveConfig,
-  saveGlobalConfig,
-  type StaticCheckLanguageConfig,
-  type UseReqConfig,
-} from "../src/core/config.js";
-import { normalizeEnabledPiUsereqTools } from "../src/core/pi-usereq-tools.js";
-
-const require = createRequire(import.meta.url);
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const TSX_ROOT = fs.existsSync(path.join(ROOT, "node_modules"))
-  ? ROOT
-  : path.join(ROOT, "..", "PI-useReq");
-const TSX_LOADER = require.resolve("tsx", { paths: [TSX_ROOT] });
-const ORACLE_VENV_PYTHON = path.join(ROOT, ".venv-oracle", "bin", "python");
-const PYTHON = fs.existsSync(ORACLE_VENV_PYTHON) ? ORACLE_VENV_PYTHON : "python3";
-const ORACLE_PYTHONPATH_ROOT = fs.existsSync(path.join(ROOT, "temp", "usereq"))
-  ? path.join(ROOT, "temp")
-  : path.join(ROOT, "..", "PI-useReq", "temp");
-const ORACLE_NODE_ROOT = fs.existsSync(path.join(ROOT, "node_modules"))
-  ? ROOT
-  : path.join(ROOT, "..", "PI-useReq");
-const ORACLE_STUBS_ROOT = path.join(ROOT, "tests", "python_oracle_stubs");
-const FIXTURES_DIR = path.join(ROOT, "tests", "fixtures");
-const TEST_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "pi-usereq-home-"));
-process.env.HOME = TEST_HOME;
-process.env.USERPROFILE = TEST_HOME;
-process.env.XDG_CONFIG_HOME = path.join(TEST_HOME, ".config");
-
-export function getFixtureFiles(): string[] {
-  return fs
-    .readdirSync(FIXTURES_DIR)
-    .filter((entry) => entry.startsWith("fixture_"))
-    .map((entry) => path.join(FIXTURES_DIR, entry))
-    .sort();
-}
-
-/**
- * @brief Executes the TypeScript CLI in a subprocess.
- * @details Invokes `node --import tsx src/cli.ts` with the supplied arguments, cwd, and environment overrides while preserving the oracle Python interpreter binding. Runtime is dominated by child-process execution. Side effects are limited to subprocess creation.
- * @param[in] args {string[]} CLI arguments forwarded to `src/cli.ts`.
- * @param[in] cwd {string} Working directory for the child process.
- * @param[in] envOverrides {NodeJS.ProcessEnv | undefined} Optional environment additions or overrides.
- * @return {import("node:child_process").SpawnSyncReturns<string>} Captured process result.
- */
-export function runNodeCli(args: string[], cwd = ROOT, envOverrides?: NodeJS.ProcessEnv) {
-  return spawnSync("node", ["--import", TSX_LOADER, path.join(ROOT, "src", "cli.ts"), ...args], {
-    cwd,
-    encoding: "utf8",
-    env: {
-      ...process.env,
-      PI_USEREQ_PYTHON: PYTHON,
-      ...envOverrides,
-    },
-  });
-}
-
-/**
- * @brief Executes the Python oracle CLI in a subprocess.
- * @details Invokes `python -m usereq.cli` with the supplied arguments, cwd, and environment overrides while preserving the oracle `PYTHONPATH`. Runtime is dominated by child-process execution. Side effects are limited to subprocess creation.
- * @param[in] args {string[]} CLI arguments forwarded to the oracle module.
- * @param[in] cwd {string} Working directory for the child process.
- * @param[in] envOverrides {NodeJS.ProcessEnv | undefined} Optional environment additions or overrides.
- * @return {import("node:child_process").SpawnSyncReturns<string>} Captured process result.
- */
-export function runPythonCli(args: string[], cwd = ROOT, envOverrides?: NodeJS.ProcessEnv) {
-  assert.ok(fs.existsSync(path.join(ORACLE_PYTHONPATH_ROOT, "usereq")), `Python oracle source not found at ${ORACLE_PYTHONPATH_ROOT}`);
-  return spawnSync(PYTHON, ["-m", "usereq.cli", ...args], {
-    cwd,
-    encoding: "utf8",
-    env: {
-      ...process.env,
-      PYTHONPATH: [ORACLE_STUBS_ROOT, ORACLE_PYTHONPATH_ROOT].join(path.delimiter),
-      PI_USEREQ_NODE_ROOT: ORACLE_NODE_ROOT,
-      ...envOverrides,
-    },
-  });
-}
-
-/**
- * @brief Executes inline Python code with the oracle module search path.
- * @details Invokes the oracle interpreter with `-c`, preserves `PYTHONPATH` for `usereq` imports, and returns the captured subprocess result. Runtime is dominated by child-process execution. Side effects are limited to subprocess creation.
- * @param[in] code {string} Inline Python program.
- * @param[in] cwd {string} Working directory for the child process.
- * @param[in] envOverrides {NodeJS.ProcessEnv | undefined} Optional environment additions or overrides.
- * @return {import("node:child_process").SpawnSyncReturns<string>} Captured process result.
- */
-export function runPythonInline(code: string, cwd = ROOT, envOverrides?: NodeJS.ProcessEnv) {
-  assert.ok(fs.existsSync(path.join(ORACLE_PYTHONPATH_ROOT, "usereq")), `Python oracle source not found at ${ORACLE_PYTHONPATH_ROOT}`);
-  return spawnSync(PYTHON, ["-c", code], {
-    cwd,
-    encoding: "utf8",
-    env: {
-      ...process.env,
-      PYTHONPATH: [ORACLE_STUBS_ROOT, ORACLE_PYTHONPATH_ROOT].join(path.delimiter),
-      PI_USEREQ_NODE_ROOT: ORACLE_NODE_ROOT,
-      ...envOverrides,
-    },
-  });
-}
-
-/**
- * @brief Creates one temporary working directory and resets the isolated test global config.
- * @details Allocates a unique directory under the system temp root, rewrites the process-scoped test global config file to documented defaults derived from the new project base, and returns the directory path. Runtime is O(n) in serialized config size. Side effects include directory creation and global-config file overwrite under the isolated test home.
- * @param[in] prefix {string} Prefix forwarded to `fs.mkdtempSync(...)`.
- * @return {string} Absolute temporary directory path.
- */
-export function createTempDir(prefix: string): string {
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
-  saveGlobalConfig(getDefaultConfig(tempDir));
-  return tempDir;
-}
-
-/**
- * @brief Persists the Python oracle configuration mirror for one fixture project.
- * @details Writes `.req/config.json` with the supplied config plus the oracle-specific `guidelines-dir` field so Node and Python parity tests observe the same project metadata. Runtime is O(n) in serialized config size. Side effects include directory creation and file overwrite.
- * @param[in] projectBase {string} Fixture project root.
- * @param[in] config {UseReqConfig} Effective project configuration to mirror.
- * @return {void} No return value.
- */
-function writeOracleReqConfig(projectBase: string, config: UseReqConfig): void {
-  const reqDir = path.join(projectBase, ".req");
-  fs.mkdirSync(reqDir, { recursive: true });
-  const payload = {
-    "guidelines-dir": "guidelines",
-    ...config,
-  };
-  fs.writeFileSync(path.join(reqDir, "config.json"), `${JSON.stringify(payload, null, 2)}\n`, "utf8");
-}
-
-/**
- * @brief Persists Node local/global configs plus the Python-oracle mirror for parity tests.
- * @details Writes split `.pi-usereq.json` and `~/.config/pi-usereq/config.json` files for the TypeScript runtime, then writes `.req/config.json` for the Python oracle using the same effective payload. Runtime is O(n) in serialized config size. Side effects include directory creation and file overwrite.
- * @param[in] projectBase {string} Fixture project root.
- * @param[in] config {UseReqConfig} Effective project configuration to persist.
- * @return {void} No return value.
- */
-export function saveFixtureConfigs(projectBase: string, config: UseReqConfig): void {
-  saveConfig(projectBase, config);
-  writeOracleReqConfig(projectBase, config);
-}
-
-/**
- * @brief Reads the raw persisted TypeScript local project config JSON.
- * @details Loads `.pi-usereq.json` without normalization so tests can inspect local-scope merge order and unknown metadata preservation exactly as written. Runtime is O(n) in file size. Side effects are limited to filesystem reads.
- * @param[in] projectBase {string} Fixture project root.
- * @return {Record<string, unknown>} Parsed raw local configuration object.
- */
-export function readProjectConfigJson(projectBase: string): Record<string, unknown> {
-  return JSON.parse(fs.readFileSync(getProjectConfigPath(projectBase), "utf8")) as Record<string, unknown>;
-}
-
-/**
- * @brief Reads the raw persisted TypeScript global config JSON.
- * @details Loads `~/.config/pi-usereq/config.json` without normalization so tests can inspect global-scope merge order and unknown metadata preservation exactly as written. Runtime is O(n) in file size. Side effects are limited to filesystem reads.
- * @return {Record<string, unknown>} Parsed raw global configuration object.
- */
-export function readGlobalConfigJson(): Record<string, unknown> {
-  return JSON.parse(fs.readFileSync(getGlobalConfigPath(), "utf8")) as Record<string, unknown>;
-}
-
-/**
- * @brief Writes one executable shell script for integration tests.
- * @details Creates the parent directory when required, writes UTF-8 content, and marks the file owner-executable. Runtime is O(n) in script size. Side effects include directory creation, file overwrite, and permission changes.
- * @param[in] filePath {string} Absolute destination path for the script.
- * @param[in] content {string} Full script body.
- * @return {string} Absolute script path.
- */
-export function writeExecutableScript(filePath: string, content: string): string {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, content, "utf8");
-  fs.chmodSync(filePath, 0o755);
-  return filePath;
-}
-
-export function initFixtureRepo(options: {
-  fixtures?: string[];
-  docs?: Record<string, string>;
-  staticCheck?: Record<string, StaticCheckLanguageConfig>;
-} = {}): { projectBase: string; config: UseReqConfig } {
-  const projectBase = createTempDir("pi-usereq-repo-");
-  fs.mkdirSync(path.join(projectBase, "src"), { recursive: true });
-  fs.mkdirSync(path.join(projectBase, "tests"), { recursive: true });
-  fs.mkdirSync(path.join(projectBase, "guidelines"), { recursive: true });
-  fs.mkdirSync(path.join(projectBase, ...DEFAULT_DOCS_DIR.split("/")), { recursive: true });
-
-  for (const fixture of options.fixtures ?? getFixtureFiles()) {
-    const destination = path.join(projectBase, "src", path.basename(fixture));
-    fs.copyFileSync(fixture, destination);
-  }
-
-  const docs = options.docs ?? {
-    "REQUIREMENTS.md": "# Requirements\n",
-    "WORKFLOW.md": "# Workflow\n",
-    "REFERENCES.md": "# References\n",
-  };
-  for (const [name, content] of Object.entries(docs)) {
-    fs.writeFileSync(path.join(projectBase, ...DEFAULT_DOCS_DIR.split("/"), name), content, "utf8");
-  }
-
-  const gitInit = spawnSync("git", ["init"], { cwd: projectBase, encoding: "utf8" });
-  assert.equal(gitInit.status, 0, gitInit.stderr);
-  spawnSync("git", ["config", "user.name", "pi-usereq"], { cwd: projectBase, encoding: "utf8" });
-  spawnSync("git", ["config", "user.email", "pi-usereq@example.com"], { cwd: projectBase, encoding: "utf8" });
-  const config: UseReqConfig = {
-    ...getDefaultConfig(projectBase),
-    "docs-dir": DEFAULT_DOCS_DIR,
-    "tests-dir": "tests",
-    "src-dir": ["src"],
-    "static-check": options.staticCheck ?? {},
-    "enabled-tools": normalizeEnabledPiUsereqTools(undefined),
-  };
-  saveFixtureConfigs(projectBase, config);
-  spawnSync("git", ["add", "."], { cwd: projectBase, encoding: "utf8" });
-  const commit = spawnSync("git", ["commit", "-m", "init"], { cwd: projectBase, encoding: "utf8" });
-  assert.equal(commit.status, 0, commit.stderr);
-
-  const localVenv = path.join(projectBase, ".venv");
-  const oracleVenvRoot = path.dirname(path.dirname(ORACLE_VENV_PYTHON));
-  if (!fs.existsSync(localVenv) && fs.existsSync(oracleVenvRoot)) {
-    fs.symlinkSync(oracleVenvRoot, localVenv, "dir");
-  }
-
-  return { projectBase, config };
-}

package/tests/oracle-project.test.ts

@@ -1,67 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import fs from "node:fs";
-import path from "node:path";
-import { createStaticCheckLanguageConfig } from "../src/core/config.js";
-import { LANGUAGE_TAGS } from "../src/core/find-constructs.js";
-import { getFixtureFiles, initFixtureRepo, runNodeCli, runPythonCli } from "./helpers.js";
-
-const TAB_SENSITIVE_FIXTURE_NAME = "fixture_go.go";
-
-/**
- * @brief Compares one project-scoped Node CLI execution against the Python oracle.
- * @details Executes the same repository command through both implementations and asserts exact equality for exit status, stdout, and stderr. Runtime is dominated by subprocess execution. Side effects are limited to child processes.
- * @param[in] args {string[]} CLI argument vector forwarded to both implementations.
- * @param[in] cwd {string} Project root used as the working directory.
- * @return {void} No return value.
- */
-function compareCli(args: string[], cwd: string): void {
-  const python = runPythonCli(args, cwd);
-  const node = runNodeCli(args, cwd);
-  assert.equal(node.status, python.status, `exit code mismatch for ${args.join(" ")}`);
-  assert.equal(node.stdout, python.stdout, `stdout mismatch for ${args.join(" ")}`);
-  assert.equal(node.stderr, python.stderr, `stderr mismatch for ${args.join(" ")}`);
-}
-
-test("project-scan commands match the Python oracle on a git-backed repository without preserved leading tabs", async (t) => {
-  const fixtures = getFixtureFiles().filter((fixture) => path.basename(fixture) !== TAB_SENSITIVE_FIXTURE_NAME);
-  const { projectBase } = initFixtureRepo({
-    fixtures,
-    staticCheck: {
-      Python: createStaticCheckLanguageConfig([{ module: "Command", cmd: "false" }], "enable"),
-    },
-  });
-  t.after(() => {
-    fs.rmSync(projectBase, { recursive: true, force: true });
-  });
-
-  await t.test("summarize", () => compareCli(["--summarize"], projectBase));
-  await t.test("compress", () => compareCli(["--compress"], projectBase));
-  await t.test("compress with line numbers", () => compareCli(["--compress", "--enable-line-numbers"], projectBase));
-  await t.test("find", () => {
-    const tagFilter = [...LANGUAGE_TAGS.python].sort().join("|");
-    compareCli(["--find", tagFilter, ".*"], projectBase);
-  });
-  await t.test("tokens", () => compareCli(["--tokens"], projectBase));
-});
-
-test("project-scan source extraction preserves leading tabs for Go sources", (t) => {
-  const goFixture = getFixtureFiles().find((fixture) => path.basename(fixture) === TAB_SENSITIVE_FIXTURE_NAME);
-  assert.ok(goFixture, `missing ${TAB_SENSITIVE_FIXTURE_NAME}`);
-  const { projectBase } = initFixtureRepo({ fixtures: [goFixture] });
-  t.after(() => {
-    fs.rmSync(projectBase, { recursive: true, force: true });
-  });
-
-  const summarize = runNodeCli(["--summarize"], projectBase);
-  assert.equal(summarize.status, 0, summarize.stderr);
-  assert.match(summarize.stdout, /\tvar wg sync\.WaitGroup/);
-
-  const compress = runNodeCli(["--compress", "--enable-line-numbers"], projectBase);
-  assert.equal(compress.status, 0, compress.stderr);
-  assert.match(compress.stdout, /\d+: \t"context"/);
-
-  const find = runNodeCli(["--find", "METHOD|FUNCTION", "^Start$", "--enable-line-numbers"], projectBase);
-  assert.equal(find.status, 0, find.stderr);
-  assert.match(find.stdout, /\d+: \ts\.Lock\(\)/);
-});

package/tests/oracle-standalone.test.ts

@@ -1,68 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import path from "node:path";
-import { LANGUAGE_TAGS } from "../src/core/find-constructs.js";
-import { detectLanguage } from "../src/core/generate-markdown.js";
-import { getFixtureFiles, runNodeCli, runPythonCli } from "./helpers.js";
-
-const TAB_SENSITIVE_FIXTURE_NAME = "fixture_go.go";
-
-/**
- * @brief Compares one standalone Node CLI execution against the Python oracle.
- * @details Executes the same explicit-file command through both implementations and asserts exact equality for exit status, stdout, and stderr. Runtime is dominated by subprocess execution. Side effects are limited to child processes.
- * @param[in] args {string[]} CLI argument vector forwarded to both implementations.
- * @return {void} No return value.
- */
-function compareCli(args: string[]): void {
-  const python = runPythonCli(args);
-  const node = runNodeCli(args);
-  assert.equal(node.status, python.status, `exit code mismatch for ${args.join(" ")}`);
-  assert.equal(node.stdout, python.stdout, `stdout mismatch for ${args.join(" ")}`);
-  assert.equal(node.stderr, python.stderr, `stderr mismatch for ${args.join(" ")}`);
-}
-
-test("standalone command outputs match the Python oracle for fixtures without preserved leading tabs", async (t) => {
-  const fixtures = getFixtureFiles();
-  for (const fixture of fixtures) {
-    const fileName = path.basename(fixture);
-    await t.test(`files-tokens ${fileName}`, () => {
-      compareCli(["--files-tokens", fixture]);
-    });
-    if (fileName === TAB_SENSITIVE_FIXTURE_NAME) {
-      continue;
-    }
-    await t.test(`files-summarize ${fileName}`, () => {
-      compareCli(["--files-summarize", fixture]);
-    });
-    await t.test(`files-compress ${fileName}`, () => {
-      compareCli(["--files-compress", fixture]);
-    });
-    await t.test(`files-compress --enable-line-numbers ${fileName}`, () => {
-      compareCli(["--files-compress", fixture, "--enable-line-numbers"]);
-    });
-    await t.test(`files-find ${fileName}`, () => {
-      const language = detectLanguage(fixture);
-      assert.ok(language);
-      const tagFilter = [...LANGUAGE_TAGS[language!]!].sort().join("|");
-      compareCli(["--files-find", tagFilter, ".*", fixture]);
-    });
-  }
-});
-
-test("standalone source extraction preserves leading tabs for the Go fixture", () => {
-  const fixture = getFixtureFiles().find((candidate) => path.basename(candidate) === TAB_SENSITIVE_FIXTURE_NAME);
-  assert.ok(fixture, `missing ${TAB_SENSITIVE_FIXTURE_NAME}`);
-  const cwd = path.dirname(fixture);
-
-  const summarize = runNodeCli(["--files-summarize", fixture], cwd);
-  assert.equal(summarize.status, 0, summarize.stderr);
-  assert.match(summarize.stdout, /\tvar wg sync\.WaitGroup/);
-
-  const compress = runNodeCli(["--files-compress", fixture, "--enable-line-numbers"], cwd);
-  assert.equal(compress.status, 0, compress.stderr);
-  assert.match(compress.stdout, /\d+: \t"context"/);
-
-  const search = runNodeCli(["--files-find", "METHOD|FUNCTION", "^Start$", fixture, "--enable-line-numbers"], cwd);
-  assert.equal(search.status, 0, search.stderr);
-  assert.match(search.stdout, /\d+: \ts\.Lock\(\)/);
-});

package/tests/prompt-command-summary.test.ts

@@ -1,36 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import {
-  DEFAULT_STATIC_CHECK_LANGUAGES,
-  getDefaultConfig,
-} from "../src/core/config.js";
-import { renderPromptCommandSummary } from "../src/core/prompts.js";
-
-/**
- * @brief Builds a configuration with no enabled context files, no enabled static-check languages, and no enabled tools.
- * @details Clones the documented default configuration, disables every context-file flag, forces every canonical static-check language to `disable`, and empties the enabled-tool list so the command invocation summary is forced to render the `none` placeholder for all three empty-category fields. Runtime is O(l) in supported language count. No external state is mutated.
- * @param[in] projectBase {string} Absolute project root path used to seed the default configuration.
- * @return {ReturnType<typeof getDefaultConfig>} Configuration object with all three summary categories empty.
- */
-function buildEmptySummaryConfig(projectBase: string): ReturnType<typeof getDefaultConfig> {
-  const config = getDefaultConfig(projectBase);
-  config["context-files-requirements"] = false;
-  config["context-files-references"] = false;
-  config["context-files-workflow"] = false;
-  for (const language of DEFAULT_STATIC_CHECK_LANGUAGES) {
-    config["static-check"][language] = { ...config["static-check"][language], enabled: "disable" };
-  }
-  config["enabled-tools"] = [];
-  return config;
-}
-
-test("renderPromptCommandSummary renders none for empty context files, static code checks, and enabled tools", () => {
-  const projectBase = process.cwd();
-  const config = buildEmptySummaryConfig(projectBase);
-  const summary = renderPromptCommandSummary("analyze", "Inspect runtime behavior", config);
-  assert.match(summary, /Command: ANALYZE/);
-  assert.match(summary, /User's Request: Inspect runtime behavior/);
-  assert.match(summary, /- context files:       none/);
-  assert.match(summary, /- static code checks:  none/);
-  assert.match(summary, /- enabled tools:       none/);
-});

package/tests/prompt-rendering.test.ts

@@ -1,103 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { getDefaultConfig } from "../src/core/config.js";
-import { buildRuntimePathContext, buildRuntimePathFacts } from "../src/core/path-context.js";
-import { renderPrompt } from "../src/core/prompts.js";
-import { ensureBundledResourcesAccessible } from "../src/core/resources.js";
-
-/**
- * @brief Escapes regular-expression metacharacters for literal-path assertions.
- * @details Replaces every regex-significant character with an escaped fragment so tests can assert exact rendered path strings without interpreting path punctuation as pattern syntax. Runtime is O(n) in input length. No external state is mutated.
- * @param[in] value {string} Literal string to escape.
- * @return {string} Regex-safe literal fragment.
- */
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-test("installed bundled resources remain readable from the installation path", () => {
-  const resourceRoot = ensureBundledResourcesAccessible();
-  assert.ok(fs.existsSync(path.join(resourceRoot, "prompts", "analyze.md")));
-  assert.ok(fs.existsSync(path.join(resourceRoot, "instructions", "git_commit.md")));
-  assert.ok(fs.existsSync(path.join(resourceRoot, "instructions", "git_read-only.md")));
-  assert.ok(fs.existsSync(path.join(resourceRoot, "templates", "Requirements_Template.md")));
-  assert.ok(fs.existsSync(path.join(resourceRoot, "guidelines", "Google_Python_Style_Guide.md")));
-});
-
-test("prompt rendering replaces dynamic placeholders, expands commit instructions, and adapts req tool references", () => {
-  ensureBundledResourcesAccessible();
-  const projectBase = process.cwd();
-  const config = getDefaultConfig(projectBase);
-  config["src-dir"] = ["src", "scripts", ".github/workflows"];
-  config["tests-dir"] = "tests";
-  config["context-files-requirements"] = false;
-  config["context-files-references"] = false;
-  config["context-files-workflow"] = false;
-  const runtimePathFacts = buildRuntimePathFacts(
-    buildRuntimePathContext(projectBase, projectBase, config),
-  );
-  const rendered = renderPrompt("write", "Build a CLI parser", projectBase, config);
-  assert.match(rendered, /Build a CLI parser/);
-  assert.match(rendered, /req\/docs/);
-  assert.match(rendered, new RegExp(escapeRegExp(runtimePathFacts.template_path)));
-  assert.match(rendered, /`src\/`, `scripts\/`, `\.github\/workflows\/`/);
-  assert.match(rendered, /runtime-substituted token `write`/);
-  assert.doesNotMatch(rendered, /%%ARGS%%|%%DOC_PATH%%|%%GUIDELINES_FILES%%|%%TEMPLATE_PATH%%|%%SRC_PATHS%%|%%TEST_PATH%%|%%CONTEXT_PATH%%|%%INSTALLATION_PATH%%|%%CONFIG_PATH%%|%%PROMPT%%|%%COMMIT%%/);
-});
-
-test("prompt rendering injects the bundled read-only git instruction when auto git commit is disabled", () => {
-  ensureBundledResourcesAccessible();
-  const projectBase = process.cwd();
-  const config = getDefaultConfig(projectBase);
-  config.AUTO_GIT_COMMIT = "disable";
-  config["context-files-requirements"] = false;
-  config["context-files-references"] = false;
-  config["context-files-workflow"] = false;
-  const rendered = renderPrompt("write", "Build a CLI parser", projectBase, config);
-  assert.match(rendered, /Git Read-Only Restriction/);
-  assert.doesNotMatch(rendered, /git commit -m/);
-  assert.doesNotMatch(rendered, /%%COMMIT%%/);
-});
-
-test("pi.dev-aware prompts inject read-only governance and interface-contract mandates when the manifest exists", () => {
-  ensureBundledResourcesAccessible();
-  const projectBase = process.cwd();
-  const config = getDefaultConfig(projectBase);
-  const rendered = renderPrompt("new", "Add pi integration guidance", projectBase, config);
-  assert.match(rendered, /Treat every path under `docs\/` as read-only/);
-  assert.match(rendered, /do NOT modify `docs\/pi\.dev\/agent-document-manifest\.json` or any other documentation file\./);
-  assert.match(rendered, /Treat every path under `pi\.dev-src\/` as read-only/);
-  assert.match(rendered, /do NOT modify `pi\.dev-src\/pi-mono` or any other pi client source\./);
-  assert.match(rendered, /read `docs\/pi\.dev\/agent-document-manifest\.json` and every document path it references/);
-  assert.match(rendered, /`docs\/pi\.dev\/coding-agent-docs\/` and documents referenced by `docs\/pi\.dev\/agent-document-manifest\.json` as the authoritative read-only interface contract/);
-  assert.match(rendered, /new or modified pi\.dev CLI integrations MUST comply with the APIs they describe\./);
-  assert.match(rendered, /Treat manifest document paths as relative to `docs\/pi\.dev\/`/);
-});
-
-test("pi.dev-aware prompts require pi client source validation for ambiguous or bug-fix interface work", () => {
-  ensureBundledResourcesAccessible();
-  const projectBase = process.cwd();
-  const config = getDefaultConfig(projectBase);
-  const rendered = renderPrompt("new", "Add pi integration guidance", projectBase, config);
-  assert.match(rendered, /If manifest or `docs\/pi\.dev\/coding-agent-docs\/` guidance is ambiguous for extension-to-pi-client interface behavior, validate the produced source code by analyzing `pi\.dev-src\/pi-mono`\./);
-  assert.match(rendered, /For bug fixes or problem resolution influenced by extension-to-pi-client interface implementations, validate the produced source code by analyzing `pi\.dev-src\/pi-mono`\./);
-});
-
-test("pi.dev-aware prompts stay unchanged when the manifest is absent", () => {
-  ensureBundledResourcesAccessible();
-  const projectBase = fs.mkdtempSync(path.join(os.tmpdir(), "pi-usereq-prompts-"));
-  try {
-    const config = getDefaultConfig(projectBase);
-    const rendered = renderPrompt("new", "Add pi integration guidance", projectBase, config);
-    assert.doesNotMatch(rendered, /docs\/pi\.dev\/agent-document-manifest\.json/);
-    assert.doesNotMatch(rendered, /authoritative read-only interface contract/);
-    assert.doesNotMatch(rendered, /Treat every path under `docs\/` as read-only/);
-    assert.doesNotMatch(rendered, /pi\.dev-src\/pi-mono/);
-    assert.doesNotMatch(rendered, /Treat manifest document paths as relative to `docs\/pi\.dev\/`/);
-  } finally {
-    fs.rmSync(projectBase, { recursive: true, force: true });
-  }
-});

package/tests/python_oracle_stubs/tiktoken.py

@@ -1,76 +0,0 @@
-"""!
-@file tiktoken.py
-@brief Provides a minimal `tiktoken` compatibility shim for Python oracle tests.
-@details Delegates token counting to the repository's Node `js-tiktoken` dependency so Python oracle runs stay aligned with the TypeScript implementation without installing the real Python package. Runtime is dominated by short-lived Node subprocess execution. Side effects are limited to subprocess creation.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import subprocess
-from dataclasses import dataclass
-from typing import Sequence
-
-_NODE_SCRIPT = (
-    "import { getEncoding } from 'js-tiktoken';"
-    "const [, encodingName, textJson] = process.argv;"
-    "const encoding = getEncoding(encodingName);"
-    "const text = JSON.parse(textJson);"
-    "process.stdout.write(String(encoding.encode(text).length));"
-)
-"""! @brief Inline Node program used to proxy token counts through `js-tiktoken`."""
-
-
-@dataclass(frozen=True)
-class _EncodingProxy:
-    """!
-    @brief Proxies `encode(...)` calls to Node `js-tiktoken`.
-    @details Spawns `node --input-type=module -e <script>` for each encode request, reads the emitted integer token count, and returns a list of placeholder integers whose length matches the reported count. Runtime is dominated by subprocess execution. Side effects are limited to subprocess creation.
-    @param encoding_name {str} Canonical tokenizer encoding name.
-    @return {_EncodingProxy} Proxy instance bound to one encoding family.
-    """
-
-    encoding_name: str
-
-    def encode(self, content: str, disallowed_special: Sequence[str] = ()) -> list[int]:
-        """!
-        @brief Encode text and return a placeholder token sequence with the correct length.
-        @details Ignores `disallowed_special` because the Node proxy uses the repository's default `js-tiktoken` behavior, which matches the TypeScript implementation. Runtime is dominated by subprocess execution. Side effects are limited to subprocess creation.
-        @param content {str} Text to tokenize.
-        @param disallowed_special {Sequence[str]} Unused compatibility parameter accepted for API parity.
-        @return {list[int]} Placeholder token list whose length matches the delegated token count.
-        @throws {RuntimeError} Raised when the Node proxy cannot execute successfully.
-        """
-        del disallowed_special
-        node_root = os.environ.get("PI_USEREQ_NODE_ROOT")
-        if not node_root:
-            raise RuntimeError("PI_USEREQ_NODE_ROOT is required for the oracle tiktoken shim.")
-        result = subprocess.run(
-            [
-                "node",
-                "--input-type=module",
-                "-e",
-                _NODE_SCRIPT,
-                self.encoding_name,
-                json.dumps(content),
-            ],
-            cwd=node_root,
-            check=False,
-            capture_output=True,
-            text=True,
-        )
-        if result.returncode != 0:
-            raise RuntimeError(result.stderr.strip() or "Node token proxy failed.")
-        token_count = int(result.stdout.strip() or "0")
-        return [0] * token_count
-
-
-def get_encoding(encoding_name: str) -> _EncodingProxy:
-    """!
-    @brief Return the compatibility proxy for one encoding family.
-    @details Mirrors the real `tiktoken.get_encoding(...)` entry point used by the Python oracle and binds the requested encoding name to a proxy instance. Runtime is O(1). No external state is mutated.
-    @param encoding_name {str} Canonical tokenizer encoding name.
-    @return {_EncodingProxy} Encoding proxy instance.
-    """
-    return _EncodingProxy(encoding_name)