@promptbook/cli 0.112.0-38 → 0.112.0-39

package/esm/scripts/find-refactor-candidates/RefactorCandidateLevel.d.ts

@@ -1,7 +1,7 @@
 /**
  * Supported aggressiveness levels for refactor-candidate scanning.
  */
-export declare const REFACTOR_CANDIDATE_LEVEL_VALUES: readonly ["low", "medium", "high", "xhigh"];
+export declare const REFACTOR_CANDIDATE_LEVEL_VALUES: readonly ["xlow", "low", "medium", "high", "xhigh", "extreme"];
 /**
  * Supported aggressiveness levels for refactor-candidate scanning.
  */
@@ -39,3 +39,7 @@ export declare const DEFAULT_REFACTOR_CANDIDATE_LEVEL: RefactorCandidateLevel;
  * Resolves the thresholds for a selected refactor-candidate scanning level.
  */
 export declare function getRefactorCandidateLevelConfiguration(level?: RefactorCandidateLevel): RefactorCandidateLevelConfiguration;
+/**
+ * Resolves the user-facing description for a selected refactor-candidate scanning level.
+ */
+export declare function getRefactorCandidateLevelDescription(level: RefactorCandidateLevel): string;

package/esm/scripts/find-refactor-candidates/findRefactorCandidatesInProject.d.ts

@@ -1,5 +1,6 @@
 import type { RefactorCandidate } from './RefactorCandidate';
 import type { RefactorCandidateLevelConfiguration } from './RefactorCandidateLevel';
+import type { IsIgnoredRelativePath } from './resolveRefactorCandidateProject';
 /**
  * Input required to scan one project for refactor candidates.
  *
@@ -14,6 +15,10 @@ type FindRefactorCandidatesInProjectOptions = {
      * Thresholds used to score files.
      */
     readonly heuristics: RefactorCandidateLevelConfiguration;
+    /**
+     * Matcher for project-relative paths that should be skipped because they are matched by `.gitignore`.
+     */
+    readonly isIgnoredRelativePath?: IsIgnoredRelativePath;
 };
 /**
  * Scans the repository and returns all files that qualify as refactor candidates.

package/esm/scripts/find-refactor-candidates/resolveRefactorCandidateProject.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Project-relative path matcher used to skip paths matched by `.gitignore`.
+ */
+export type IsIgnoredRelativePath = (relativePath: string) => boolean;
+/**
+ * Project metadata resolved before scanning for refactor candidates.
+ */
+export type ResolvedRefactorCandidateProject = {
+    /**
+     * Absolute directory used as the scan root.
+     */
+    readonly rootDir: string;
+    /**
+     * Matcher used to skip project-relative paths covered by `.gitignore`.
+     */
+    readonly isIgnoredRelativePath: IsIgnoredRelativePath;
+};
+/**
+ * Resolves the project root and `.gitignore` matcher for refactor-candidate scanning.
+ *
+ * @private function of findRefactorCandidates
+ */
+export declare function resolveRefactorCandidateProject(startDir: string): Promise<ResolvedRefactorCandidateProject>;

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.112.0-37`).
+ * It follows semantic versioning (e.g., `0.112.0-38`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.112.0-38",
+    "version": "0.112.0-39",
     "description": "Promptbook: Turn your company's scattered knowledge into AI ready books",
     "private": false,
     "sideEffects": false,
@@ -111,6 +111,7 @@
         "express": "4.21.2",
         "express-openapi-validator": "5.4.9",
         "glob-promise": "6.0.7",
+        "ignore": "^5.3.2",
         "jsdom": "25.0.1",
         "jszip": "3.10.1",
         "markitdown-ts": "0.0.10",

package/umd/index.umd.js

@@ -1,8 +1,8 @@
 (function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('colors'), require('commander'), require('spacetrim'), require('fs'), require('path'), require('fs/promises'), require('waitasecond'), require('prompts'), require('dotenv'), require('crypto-js/enc-hex'), require('crypto-js/sha256'), require('socket.io-client'), require('crypto-js'), require('jszip'), require('crypto'), require('@mozilla/readability'), require('jsdom'), require('showdown'), require('glob-promise'), require('moment'), require('express'), require('express-openapi-validator'), require('http'), require('socket.io'), require('swagger-ui-express'), require('react'), require('react-dom/server'), require('@anthropic-ai/sdk'), require('bottleneck'), require('@azure/openai'), require('typescript'), require('readline'), require('child_process'), require('pg'), require('@supabase/supabase-js'), require('path/posix'), require('rxjs'), require('mime-types'), require('papaparse'), require('@openai/agents'), require('openai')) :
-    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'commander', 'spacetrim', 'fs', 'path', 'fs/promises', 'waitasecond', 'prompts', 'dotenv', 'crypto-js/enc-hex', 'crypto-js/sha256', 'socket.io-client', 'crypto-js', 'jszip', 'crypto', '@mozilla/readability', 'jsdom', 'showdown', 'glob-promise', 'moment', 'express', 'express-openapi-validator', 'http', 'socket.io', 'swagger-ui-express', 'react', 'react-dom/server', '@anthropic-ai/sdk', 'bottleneck', '@azure/openai', 'typescript', 'readline', 'child_process', 'pg', '@supabase/supabase-js', 'path/posix', 'rxjs', 'mime-types', 'papaparse', '@openai/agents', 'openai'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-cli"] = {}, global.colors, global.commander, global._spaceTrim, global.fs, global.path, global.promises, global.waitasecond, global.prompts, global.dotenv, global.hexEncoder, global.sha256, global.socket_ioClient, global.cryptoJs, global.JSZip, global.crypto, global.readability, global.jsdom, global.showdown, global.glob, global.moment, global.express, global.OpenApiValidator, global.http, global.socket_io, global.swaggerUi, global.react, global.server, global.Anthropic, global.Bottleneck, global.openai, global.ts, global.readline, global.child_process, global.pg, null, global.posix, global.rxjs, global.mimeTypes, global.papaparse, global.agents, global.OpenAI));
-})(this, (function (exports, colors, commander, _spaceTrim, fs, path, promises, waitasecond, prompts, dotenv, hexEncoder, sha256, socket_ioClient, cryptoJs, JSZip, crypto, readability, jsdom, showdown, glob, moment, express, OpenApiValidator, http, socket_io, swaggerUi, react, server, Anthropic, Bottleneck, openai, ts, readline, child_process, pg, supabaseJs, posix, rxjs, mimeTypes, papaparse, agents, OpenAI) { 'use strict';
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('colors'), require('commander'), require('spacetrim'), require('fs'), require('path'), require('fs/promises'), require('waitasecond'), require('prompts'), require('dotenv'), require('crypto-js/enc-hex'), require('crypto-js/sha256'), require('socket.io-client'), require('crypto-js'), require('jszip'), require('crypto'), require('@mozilla/readability'), require('jsdom'), require('showdown'), require('glob-promise'), require('moment'), require('express'), require('express-openapi-validator'), require('http'), require('socket.io'), require('swagger-ui-express'), require('react'), require('react-dom/server'), require('@anthropic-ai/sdk'), require('bottleneck'), require('@azure/openai'), require('typescript'), require('ignore'), require('readline'), require('child_process'), require('pg'), require('@supabase/supabase-js'), require('path/posix'), require('rxjs'), require('mime-types'), require('papaparse'), require('@openai/agents'), require('openai')) :
+    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'commander', 'spacetrim', 'fs', 'path', 'fs/promises', 'waitasecond', 'prompts', 'dotenv', 'crypto-js/enc-hex', 'crypto-js/sha256', 'socket.io-client', 'crypto-js', 'jszip', 'crypto', '@mozilla/readability', 'jsdom', 'showdown', 'glob-promise', 'moment', 'express', 'express-openapi-validator', 'http', 'socket.io', 'swagger-ui-express', 'react', 'react-dom/server', '@anthropic-ai/sdk', 'bottleneck', '@azure/openai', 'typescript', 'ignore', 'readline', 'child_process', 'pg', '@supabase/supabase-js', 'path/posix', 'rxjs', 'mime-types', 'papaparse', '@openai/agents', 'openai'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-cli"] = {}, global.colors, global.commander, global._spaceTrim, global.fs, global.path, global.promises, global.waitasecond, global.prompts, global.dotenv, global.hexEncoder, global.sha256, global.socket_ioClient, global.cryptoJs, global.JSZip, global.crypto, global.readability, global.jsdom, global.showdown, global.glob, global.moment, global.express, global.OpenApiValidator, global.http, global.socket_io, global.swaggerUi, global.react, global.server, global.Anthropic, global.Bottleneck, global.openai, global.ts, global.ignore, global.readline, global.child_process, global.pg, null, global.posix, global.rxjs, global.mimeTypes, global.papaparse, global.agents, global.OpenAI));
+})(this, (function (exports, colors, commander, _spaceTrim, fs, path, promises, waitasecond, prompts, dotenv, hexEncoder, sha256, socket_ioClient, cryptoJs, JSZip, crypto, readability, jsdom, showdown, glob, moment, express, OpenApiValidator, http, socket_io, swaggerUi, react, server, Anthropic, Bottleneck, openai, ts, ignore, readline, child_process, pg, supabaseJs, posix, rxjs, mimeTypes, papaparse, agents, OpenAI) { 'use strict';
 
     function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -43,6 +43,7 @@
     var Anthropic__default = /*#__PURE__*/_interopDefaultLegacy(Anthropic);
     var Bottleneck__default = /*#__PURE__*/_interopDefaultLegacy(Bottleneck);
     var ts__namespace = /*#__PURE__*/_interopNamespace(ts);
+    var ignore__default = /*#__PURE__*/_interopDefaultLegacy(ignore);
     var readline__namespace = /*#__PURE__*/_interopNamespace(readline);
     var OpenAI__default = /*#__PURE__*/_interopDefaultLegacy(OpenAI);
 
@@ -60,7 +61,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-38';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-39';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1735,7 +1736,7 @@
     /**
      * 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.
      */
@@ -1743,37 +1744,76 @@
     /**
      * Threshold table for each supported refactor-candidate scanning level.
      */
-    const REFACTOR_CANDIDATE_LEVEL_CONFIGURATION_BY_LEVEL = {
-        low: createRefactorCandidateLevelConfiguration({
+    const REFACTOR_CANDIDATE_LEVEL_DETAILS_BY_LEVEL = {
+        xlow: createRefactorCandidateLevelDetails({
+            description: 'Very benevolent scan that only flags the most obvious refactor targets.',
+            maxLineCount: 4200,
+            maxEntityCountPerFile: 36,
+            maxFunctionCountPerFile: 24,
+            maxFunctionComplexity: 24,
+        }),
+        low: createRefactorCandidateLevelDetails({
+            description: 'Conservative scan for only the most obvious refactor targets.',
             maxLineCount: 2800,
             maxEntityCountPerFile: 28,
             maxFunctionCountPerFile: 18,
             maxFunctionComplexity: 20,
         }),
-        medium: createRefactorCandidateLevelConfiguration({
+        medium: createRefactorCandidateLevelDetails({
+            description: 'Default scan using the current standard thresholds.',
             maxLineCount: 2000,
             maxEntityCountPerFile: 20,
             maxFunctionCountPerFile: 14,
             maxFunctionComplexity: 16,
         }),
-        high: createRefactorCandidateLevelConfiguration({
-            maxLineCount: 1500,
-            maxEntityCountPerFile: 16,
+        high: createRefactorCandidateLevelDetails({
+            description: 'Strict scan that finds more crowded or complex files.',
+            maxLineCount: 1400,
+            maxEntityCountPerFile: 15,
             maxFunctionCountPerFile: 10,
             maxFunctionComplexity: 12,
         }),
-        xhigh: createRefactorCandidateLevelConfiguration({
-            maxLineCount: 1000,
-            maxEntityCountPerFile: 12,
-            maxFunctionCountPerFile: 8,
+        xhigh: createRefactorCandidateLevelDetails({
+            description: 'Very strict scan for denser and more complex candidates.',
+            maxLineCount: 900,
+            maxEntityCountPerFile: 10,
+            maxFunctionCountPerFile: 7,
             maxFunctionComplexity: 8,
         }),
+        extreme: createRefactorCandidateLevelDetails({
+            description: 'Most aggressive scan that also surfaces weaker refactor opportunities.',
+            maxLineCount: 600,
+            maxEntityCountPerFile: 6,
+            maxFunctionCountPerFile: 4,
+            maxFunctionComplexity: 6,
+        }),
     };
     /**
      * 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.
@@ -1809,17 +1849,14 @@
      */
     function $initializeCoderFindRefactorCandidatesCommand(program) {
         const command = program.command('find-refactor-candidates');
-        command.description(_spaceTrim.spaceTrim(`
-            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 commander.Option('--level <level>', `Set scan aggressiveness (${REFACTOR_CANDIDATE_LEVEL_VALUES.join(', ')})`)
             .choices([...REFACTOR_CANDIDATE_LEVEL_VALUES])
             .default(DEFAULT_REFACTOR_CANDIDATE_LEVEL));
@@ -1947,7 +1984,7 @@
         const ensuredTemplateFiles = [];
         for (const definition of DEFAULT_CODER_PROJECT_PROMPT_TEMPLATE_DEFINITIONS) {
             const absoluteTemplatePath = path.join(projectPath, definition.relativeFilePath);
-            if (await isExistingFile$1(absoluteTemplatePath)) {
+            if (await isExistingFile$2(absoluteTemplatePath)) {
                 ensuredTemplateFiles.push({
                     id: definition.id,
                     relativeFilePath: definition.relativeFilePath,
@@ -2061,7 +2098,7 @@
     /**
      * Checks whether a path exists and is a file.
      */
-    async function isExistingFile$1(path) {
+    async function isExistingFile$2(path) {
         try {
             return (await promises.stat(path)).isFile();
         }
@@ -2495,7 +2532,7 @@
      */
     async function ensureCoderMarkdownFile(projectPath, relativeFilePath, fileContent) {
         const absoluteFilePath = path.join(projectPath, relativeFilePath);
-        if (await isExistingFile(absoluteFilePath)) {
+        if (await isExistingFile$1(absoluteFilePath)) {
             return 'unchanged';
         }
         await promises.writeFile(absoluteFilePath, `${fileContent}\n`, 'utf-8');
@@ -2504,7 +2541,7 @@
     /**
      * Checks whether a path exists and is a file.
      */
-    async function isExistingFile(path) {
+    async function isExistingFile$1(path) {
         try {
             return (await promises.stat(path)).isFile();
         }
@@ -41460,9 +41497,9 @@
      * @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({
@@ -41482,7 +41519,7 @@
      *
      * @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}`];
@@ -41495,6 +41532,9 @@
                 absolute: true,
             });
             for (const match of matches) {
+                if (shouldIgnoreAbsolutePath(rootDir, match, isIgnoredRelativePath)) {
+                    continue;
+                }
                 files.add(match);
             }
         }
@@ -41505,7 +41545,7 @@
      *
      * @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__default["default"](pattern, {
@@ -41515,11 +41555,23 @@
                 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(path.relative(rootDir, absolutePath));
+        return isIgnoredRelativePath(relativePath);
+    }
     /**
      * Normalizes an absolute path for consistent comparisons.
      *
@@ -41568,6 +41620,69 @@
     }
     // 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 = path.resolve(startDir);
+        const gitignorePath = await findNearestGitignorePath(absoluteStartDir);
+        if (!gitignorePath) {
+            return {
+                rootDir: absoluteStartDir,
+                isIgnoredRelativePath: () => false,
+            };
+        }
+        const rootDir = path.dirname(gitignorePath);
+        const gitignoreMatcher = ignore__default["default"]().add(await promises.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 = path.resolve(startDir);
+        while (true) {
+            const gitignorePath = path.join(currentDir, GITIGNORE_FILE_NAME);
+            if (await isExistingFile(gitignorePath)) {
+                return gitignorePath;
+            }
+            const parentDir = path.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 promises.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.
      */
@@ -41925,11 +42040,12 @@
         initializeFindRefactorCandidatesRun();
         console.info(colors__default["default"].cyan('⚡🏭 Find refactor candidates'));
         console.info(colors__default["default"].gray(`Using \`${level}\` scan level.`));
-        const rootDir = process.cwd();
+        const { isIgnoredRelativePath, rootDir } = await resolveRefactorCandidateProject(process.cwd());
         const promptsDir = path.join(rootDir, PROMPTS_DIR_NAME);
         const existingTargets = await loadExistingPromptTargets(promptsDir);
         const candidates = await findRefactorCandidatesInProject({
             heuristics,
+            isIgnoredRelativePath,
             rootDir,
         });
         if (candidates.length === 0) {