@promptbook/cli 0.112.0-38 → 0.112.0-40

package/README.md

@@ -602,7 +602,7 @@ npx ptbk coder verify
 | `ptbk coder init` | Creates `prompts/`, `prompts/done/`, the project-generic template files materialized in `prompts/templates/` (currently `common.md`), and a starter `AGENTS.md`; ensures `.env` contains `CODING_AGENT_GIT_NAME`, `CODING_AGENT_GIT_EMAIL`, and `CODING_AGENT_GIT_SIGNING_KEY`; adds helper coder scripts to `package.json`; ensures `.gitignore` contains `/.tmp`; and configures `.vscode/settings.json` to save pasted prompt images into `prompts/screenshots/`. |
 | `ptbk coder generate-boilerplates` | Creates new prompt markdown files with fresh emoji tags so you can quickly fill in coding tasks; `--template` accepts either a built-in alias or a markdown file path relative to the project root. |
 | `ptbk coder run` | Picks the next ready prompt, appends optional context, runs it through the selected coding agent, marks success or failure, then commits and pushes the result. |
-| `ptbk coder find-refactor-candidates` | Scans the repository for oversized or overpacked files and writes prompt files for likely refactors; `--level <low|medium|high|xhigh>` makes the scan more or less aggressive. |
+| `ptbk coder find-refactor-candidates` | Scans the repository for oversized or overpacked files and writes prompt files for likely refactors; `--level <xlow|low|medium|high|xhigh|extreme>` ranges from a very benevolent scan to a very aggressive sweep. |
 | `ptbk coder verify` | Walks through completed prompts, archives truly finished work, and adds follow-up repair prompts for unfinished results. |
 
 #### Most useful `ptbk coder run` flags

package/esm/index.es.js

@@ -31,6 +31,7 @@ import Anthropic from '@anthropic-ai/sdk';
 import Bottleneck from 'bottleneck';
 import { OpenAIClient, AzureKeyCredential } from '@azure/openai';
 import * as ts from 'typescript';
+import ignore from 'ignore';
 import * as readline from 'readline';
 import { cursorTo, clearLine, createInterface } from 'readline';
 import { spawn } from 'child_process';
@@ -57,7 +58,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-38';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-40';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1732,7 +1733,7 @@ const PROMPT_SLUG_MAX_LENGTH = 80;
 /**
  * Supported aggressiveness levels for refactor-candidate scanning.
  */
-const REFACTOR_CANDIDATE_LEVEL_VALUES = ['low', 'medium', 'high', 'xhigh'];
+const REFACTOR_CANDIDATE_LEVEL_VALUES = ['xlow', 'low', 'medium', 'high', 'xhigh', 'extreme'];
 /**
  * Default aggressiveness level for refactor-candidate scanning.
  */
@@ -1740,37 +1741,76 @@ const DEFAULT_REFACTOR_CANDIDATE_LEVEL = 'medium';
 /**
  * Threshold table for each supported refactor-candidate scanning level.
  */
-const REFACTOR_CANDIDATE_LEVEL_CONFIGURATION_BY_LEVEL = {
-    low: createRefactorCandidateLevelConfiguration({
-        maxLineCount: 2800,
-        maxEntityCountPerFile: 28,
-        maxFunctionCountPerFile: 18,
-        maxFunctionComplexity: 20,
+const REFACTOR_CANDIDATE_LEVEL_DETAILS_BY_LEVEL = {
+    xlow: createRefactorCandidateLevelDetails({
+        description: 'Extremely benevolent scan that flags only very obvious refactor targets.',
+        maxLineCount: 9600,
+        maxEntityCountPerFile: 72,
+        maxFunctionCountPerFile: 48,
+        maxFunctionComplexity: 40,
     }),
-    medium: createRefactorCandidateLevelConfiguration({
-        maxLineCount: 2000,
-        maxEntityCountPerFile: 20,
-        maxFunctionCountPerFile: 14,
-        maxFunctionComplexity: 16,
+    low: createRefactorCandidateLevelDetails({
+        description: 'Conservative scan for only the most obvious refactor targets.',
+        maxLineCount: 3600,
+        maxEntityCountPerFile: 30,
+        maxFunctionCountPerFile: 20,
+        maxFunctionComplexity: 24,
     }),
-    high: createRefactorCandidateLevelConfiguration({
-        maxLineCount: 1500,
+    medium: createRefactorCandidateLevelDetails({
+        description: 'Default scan using the current standard thresholds.',
+        maxLineCount: 1800,
         maxEntityCountPerFile: 16,
-        maxFunctionCountPerFile: 10,
-        maxFunctionComplexity: 12,
+        maxFunctionCountPerFile: 12,
+        maxFunctionComplexity: 16,
     }),
-    xhigh: createRefactorCandidateLevelConfiguration({
-        maxLineCount: 1000,
-        maxEntityCountPerFile: 12,
+    high: createRefactorCandidateLevelDetails({
+        description: 'Strict scan that finds more crowded or complex files.',
+        maxLineCount: 900,
+        maxEntityCountPerFile: 9,
         maxFunctionCountPerFile: 8,
-        maxFunctionComplexity: 8,
+        maxFunctionComplexity: 11,
+    }),
+    xhigh: createRefactorCandidateLevelDetails({
+        description: 'Very strict scan for denser and more complex candidates.',
+        maxLineCount: 450,
+        maxEntityCountPerFile: 5,
+        maxFunctionCountPerFile: 5,
+        maxFunctionComplexity: 7,
+    }),
+    extreme: createRefactorCandidateLevelDetails({
+        description: 'Most aggressive scan that surfaces even weak refactor opportunities.',
+        maxLineCount: 180,
+        maxEntityCountPerFile: 2,
+        maxFunctionCountPerFile: 2,
+        maxFunctionComplexity: 4,
     }),
 };
 /**
  * Resolves the thresholds for a selected refactor-candidate scanning level.
  */
 function getRefactorCandidateLevelConfiguration(level = DEFAULT_REFACTOR_CANDIDATE_LEVEL) {
-    return REFACTOR_CANDIDATE_LEVEL_CONFIGURATION_BY_LEVEL[level];
+    return REFACTOR_CANDIDATE_LEVEL_DETAILS_BY_LEVEL[level].configuration;
+}
+/**
+ * Resolves the user-facing description for a selected refactor-candidate scanning level.
+ */
+function getRefactorCandidateLevelDescription(level) {
+    return REFACTOR_CANDIDATE_LEVEL_DETAILS_BY_LEVEL[level].description;
+}
+/**
+ * Builds one normalized refactor-candidate level entry.
+ */
+function createRefactorCandidateLevelDetails(options) {
+    const { description, maxLineCount, maxEntityCountPerFile, maxFunctionCountPerFile, maxFunctionComplexity } = options;
+    return {
+        description,
+        configuration: createRefactorCandidateLevelConfiguration({
+            maxLineCount,
+            maxEntityCountPerFile,
+            maxFunctionCountPerFile,
+            maxFunctionComplexity,
+        }),
+    };
 }
 /**
  * Builds one normalized refactor-candidate level configuration entry.
@@ -1806,17 +1846,14 @@ function createLineCountLimits(maxLineCount) {
  */
 function $initializeCoderFindRefactorCandidatesCommand(program) {
     const command = program.command('find-refactor-candidates');
-    command.description(spaceTrim$1(`
-            Scan source files to identify refactoring candidates
-
-            Levels:
-            - low: Conservative scan for only the most obvious refactor targets
-            - medium: Default scan using the current standard thresholds
-            - high: Stricter scan that finds more crowded or complex files
-            - xhigh: Most aggressive scan for denser and more complex candidates
-
-            Generates refactor prompts with guidance for identified candidates.
-        `));
+    command.description([
+        'Scan source files to identify refactoring candidates',
+        '',
+        'Levels:',
+        ...REFACTOR_CANDIDATE_LEVEL_VALUES.map((level) => `- ${level}: ${getRefactorCandidateLevelDescription(level)}`),
+        '',
+        'Generates refactor prompts with guidance for identified candidates.',
+    ].join('\n'));
     command.addOption(new Option('--level <level>', `Set scan aggressiveness (${REFACTOR_CANDIDATE_LEVEL_VALUES.join(', ')})`)
         .choices([...REFACTOR_CANDIDATE_LEVEL_VALUES])
         .default(DEFAULT_REFACTOR_CANDIDATE_LEVEL));
@@ -1944,7 +1981,7 @@ async function ensureDefaultCoderPromptTemplateFiles(projectPath) {
     const ensuredTemplateFiles = [];
     for (const definition of DEFAULT_CODER_PROJECT_PROMPT_TEMPLATE_DEFINITIONS) {
         const absoluteTemplatePath = join(projectPath, definition.relativeFilePath);
-        if (await isExistingFile$1(absoluteTemplatePath)) {
+        if (await isExistingFile$2(absoluteTemplatePath)) {
             ensuredTemplateFiles.push({
                 id: definition.id,
                 relativeFilePath: definition.relativeFilePath,
@@ -2058,7 +2095,7 @@ function isNodeJsErrorWithCode(error, code) {
 /**
  * Checks whether a path exists and is a file.
  */
-async function isExistingFile$1(path) {
+async function isExistingFile$2(path) {
     try {
         return (await stat(path)).isFile();
     }
@@ -2492,7 +2529,7 @@ function hasTmpGitignoreRule(gitignoreContent) {
  */
 async function ensureCoderMarkdownFile(projectPath, relativeFilePath, fileContent) {
     const absoluteFilePath = join(projectPath, relativeFilePath);
-    if (await isExistingFile(absoluteFilePath)) {
+    if (await isExistingFile$1(absoluteFilePath)) {
         return 'unchanged';
     }
     await writeFile(absoluteFilePath, `${fileContent}\n`, 'utf-8');
@@ -2501,7 +2538,7 @@ async function ensureCoderMarkdownFile(projectPath, relativeFilePath, fileConten
 /**
  * Checks whether a path exists and is a file.
  */
-async function isExistingFile(path) {
+async function isExistingFile$1(path) {
     try {
         return (await stat(path)).isFile();
     }
@@ -41457,9 +41494,9 @@ function normalizeAbsolutePath$1(pathValue) {
  * @private function of findRefactorCandidates
  */
 async function findRefactorCandidatesInProject(options) {
-    const { heuristics, rootDir } = options;
-    const lineCountExemptPaths = await buildExemptPathSet(rootDir, LINE_COUNT_EXEMPT_GLOBS);
-    const sourceFiles = await listSourceFiles(rootDir);
+    const { heuristics, isIgnoredRelativePath = () => false, rootDir } = options;
+    const lineCountExemptPaths = await buildExemptPathSet(rootDir, LINE_COUNT_EXEMPT_GLOBS, isIgnoredRelativePath);
+    const sourceFiles = await listSourceFiles(rootDir, isIgnoredRelativePath);
     const candidates = [];
     for (const filePath of sourceFiles) {
         const candidate = await analyzeSourceFileForRefactorCandidate({
@@ -41479,7 +41516,7 @@ async function findRefactorCandidatesInProject(options) {
  *
  * @private function of findRefactorCandidatesInProject
  */
-async function listSourceFiles(rootDir) {
+async function listSourceFiles(rootDir, isIgnoredRelativePath) {
     const extensions = SOURCE_FILE_EXTENSIONS.map((extension) => extension.replace(/^\./, '')).join(',');
     const extensionGlob = `{${extensions}}`;
     const patterns = [...SOURCE_ROOTS.map((root) => `${root}/**/*.${extensionGlob}`), `*.${extensionGlob}`];
@@ -41492,6 +41529,9 @@ async function listSourceFiles(rootDir) {
             absolute: true,
         });
         for (const match of matches) {
+            if (shouldIgnoreAbsolutePath(rootDir, match, isIgnoredRelativePath)) {
+                continue;
+            }
             files.add(match);
         }
     }
@@ -41502,7 +41542,7 @@ async function listSourceFiles(rootDir) {
  *
  * @private function of findRefactorCandidatesInProject
  */
-async function buildExemptPathSet(rootDir, patterns) {
+async function buildExemptPathSet(rootDir, patterns, isIgnoredRelativePath) {
     const exemptPaths = new Set();
     for (const pattern of patterns) {
         const matches = await glob(pattern, {
@@ -41512,11 +41552,23 @@ async function buildExemptPathSet(rootDir, patterns) {
             absolute: true,
         });
         for (const match of matches) {
+            if (shouldIgnoreAbsolutePath(rootDir, match, isIgnoredRelativePath)) {
+                continue;
+            }
             exemptPaths.add(normalizeAbsolutePath(match));
         }
     }
     return exemptPaths;
 }
+/**
+ * Resolves whether an absolute path falls under the project `.gitignore` rules.
+ *
+ * @private function of findRefactorCandidatesInProject
+ */
+function shouldIgnoreAbsolutePath(rootDir, absolutePath, isIgnoredRelativePath) {
+    const relativePath = normalizeRefactorCandidatePath(relative(rootDir, absolutePath));
+    return isIgnoredRelativePath(relativePath);
+}
 /**
  * Normalizes an absolute path for consistent comparisons.
  *
@@ -41565,6 +41617,69 @@ function escapeRegExp(value) {
 }
 // Note: [🟡] Code for repository script [loadExistingPromptTargets](scripts/find-refactor-candidates/loadExistingPromptTargets.ts) should never be published outside of `@promptbook/cli`
 
+/**
+ * Filename used to discover the project root for refactor-candidate scanning.
+ */
+const GITIGNORE_FILE_NAME = '.gitignore';
+/**
+ * Resolves the project root and `.gitignore` matcher for refactor-candidate scanning.
+ *
+ * @private function of findRefactorCandidates
+ */
+async function resolveRefactorCandidateProject(startDir) {
+    const absoluteStartDir = resolve(startDir);
+    const gitignorePath = await findNearestGitignorePath(absoluteStartDir);
+    if (!gitignorePath) {
+        return {
+            rootDir: absoluteStartDir,
+            isIgnoredRelativePath: () => false,
+        };
+    }
+    const rootDir = dirname(gitignorePath);
+    const gitignoreMatcher = ignore().add(await readFile(gitignorePath, 'utf-8'));
+    return {
+        rootDir,
+        isIgnoredRelativePath(relativePath) {
+            return gitignoreMatcher.ignores(normalizeRefactorCandidatePath(relativePath));
+        },
+    };
+}
+/**
+ * Finds the nearest ancestor `.gitignore` so scans work from any project subdirectory.
+ *
+ * @private function of resolveRefactorCandidateProject
+ */
+async function findNearestGitignorePath(startDir) {
+    let currentDir = resolve(startDir);
+    while (true) {
+        const gitignorePath = join(currentDir, GITIGNORE_FILE_NAME);
+        if (await isExistingFile(gitignorePath)) {
+            return gitignorePath;
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
+/**
+ * Detects whether a file exists without swallowing unexpected filesystem failures.
+ *
+ * @private function of resolveRefactorCandidateProject
+ */
+async function isExistingFile(filePath) {
+    var _a;
+    const fileStats = await stat(filePath).catch((error) => {
+        if (error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    });
+    return (_a = fileStats === null || fileStats === void 0 ? void 0 : fileStats.isFile()) !== null && _a !== void 0 ? _a : false;
+}
+// Note: [🟡] Code for repository script [resolveRefactorCandidateProject](scripts/find-refactor-candidates/resolveRefactorCandidateProject.ts) should never be published outside of `@promptbook/cli`
+
 /**
  * Calculates the next available prompt numbering sequence for a month.
  */
@@ -41922,11 +42037,12 @@ async function findRefactorCandidates(options = {}) {
     initializeFindRefactorCandidatesRun();
     console.info(colors.cyan('⚡🏭 Find refactor candidates'));
     console.info(colors.gray(`Using \`${level}\` scan level.`));
-    const rootDir = process.cwd();
+    const { isIgnoredRelativePath, rootDir } = await resolveRefactorCandidateProject(process.cwd());
     const promptsDir = join(rootDir, PROMPTS_DIR_NAME);
     const existingTargets = await loadExistingPromptTargets(promptsDir);
     const candidates = await findRefactorCandidatesInProject({
         heuristics,
+        isIgnoredRelativePath,
         rootDir,
     });
     if (candidates.length === 0) {