octocode-cli 1.3.0 → 1.5.0

package/skills/octocode-engineer/src/pipeline/main.ts

@@ -16,7 +16,7 @@ import {
 } from './cache.js';
 import { parseArgs } from './cli.js';
 import { loadConfigFile, mergeConfigIntoDefaults } from './config-loader.js';
-import { createOptions, OptionsError } from './create-options.js';
+import { createOptions } from './create-options.js';
 import { attachConsoleFeedback, bus } from './progress.js';
 import { resolveAffectedFiles } from './affected.js';
 import { saveBaseline, filterKnownFindings } from './baseline.js';
@@ -46,7 +46,6 @@ import {
   analyzeSourceFile,
   buildDependencyCriticality,
 } from '../ast/ts-analyzer.js';
-import { isDirectRun } from '../common/is-direct-run.js';
 import { canonicalScriptKind, increment } from '../common/utils.js';
 import { computeHotFiles } from '../detectors/index.js';
 import { runSemanticDetectors } from '../detectors/semantic.js';
@@ -1249,18 +1248,3 @@ function buildFindingStats(
   return { overall, pillars };
 }
 
-if (isDirectRun(import.meta.url)) {
-  main()
-    .then(code => {
-      process.exitCode = code;
-    })
-    .catch((error: unknown) => {
-      if (error instanceof OptionsError) {
-        console.error(error.message);
-        process.exitCode = EXIT_ERROR;
-      } else {
-        console.error(error);
-        process.exitCode = EXIT_ERROR;
-      }
-    });
-}

package/skills/octocode-engineer/src/pipeline/progress.ts

@@ -40,7 +40,11 @@ class ScanBus extends EventEmitter {
 
 export const bus = new ScanBus();
 
+let consoleFeedbackAttached = false;
+
 export function attachConsoleFeedback(): void {
+  if (consoleFeedbackAttached) return;
+  consoleFeedbackAttached = true;
   bus.on('progress', (event: ProgressEvent) => {
     if (event.detail) {
       process.stderr.write(`[${event.phase}] ${event.message}: ${event.detail}\n`);

package/skills/octocode-engineer/src/reporting/summary-md.test.ts

@@ -629,6 +629,54 @@ describe('computeQualityAspectRatings', () => {
     expect(folderAspect!.score).toBeGreaterThanOrEqual(85);
   });
 
+  it('penalizes leaf folders that accumulate too many files', () => {
+    const result = computeQualityAspectRatings([], {
+      fileInventory: [
+        ...Array.from({ length: 30 }, (_, index) =>
+          makeFileEntry({ file: `src/core/module-${index}.ts` })
+        ),
+        ...Array.from({ length: 5 }, (_, index) =>
+          makeFileEntry({ file: `src/api/route-${index}.ts` })
+        ),
+      ],
+    });
+
+    const folderAspect = result.aspects.find(
+      aspect => aspect.aspect === 'folder-topology'
+    );
+    expect(folderAspect).toBeDefined();
+    expect(folderAspect!.score).toBeLessThan(85);
+    expect(folderAspect!.signals).toContainEqual(
+      expect.objectContaining({
+        label: 'Bloated folders',
+        value: '1/2',
+        effect: 'negative',
+      })
+    );
+  });
+
+  it('includes folder naming consistency in codebase consistency', () => {
+    const result = computeQualityAspectRatings([], {
+      fileInventory: [
+        makeFileEntry({ file: 'src/user-profile/loadUser.ts' }),
+        makeFileEntry({ file: 'src/user_profile/saveUser.ts' }),
+        makeFileEntry({ file: 'src/UserProfile/listUser.ts' }),
+      ],
+    });
+
+    const consistencyAspect = result.aspects.find(
+      aspect => aspect.aspect === 'codebase-consistency'
+    );
+    expect(consistencyAspect).toBeDefined();
+    expect(consistencyAspect!.signals).toContainEqual(
+      expect.objectContaining({
+        label: 'Dominant folder naming style',
+        value: '33%',
+        effect: 'negative',
+      })
+    );
+  });
+
   it('ignores generated and minified paths in hybrid quality rating by default', () => {
     const result = computeQualityAspectRatings(
       [

package/skills/octocode-engineer/src/reporting/summary-md.ts

@@ -703,13 +703,16 @@ export function computeQualityAspectRatings(
   );
   const avgDepth = average(depthValues);
   const topLevelCounts = new Map<string, number>();
+  const folderCounts = new Map<string, number>();
   const dirSegments = new Set<string>();
   const vagueDirPattern = /^(util|utils|common|shared|misc|helper|helpers|tmp|temp)$/i;
   for (const file of topologyPaths) {
     const normalized = normalizeScanPath(file);
     const parts = normalized.split('/').filter(Boolean);
     const top = parts[0] || '.';
+    const folder = parts.length <= 1 ? '.' : parts.slice(0, -1).join('/');
     topLevelCounts.set(top, (topLevelCounts.get(top) || 0) + 1);
+    folderCounts.set(folder, (folderCounts.get(folder) || 0) + 1);
     for (const segment of parts.slice(0, -1)) dirSegments.add(segment);
   }
   const dominantRootRatio =
@@ -721,11 +724,23 @@ export function computeQualityAspectRatings(
       ? 0
       : [...dirSegments].filter(segment => vagueDirPattern.test(segment)).length
         / dirSegments.size;
+  const maxFolderFileCount =
+    folderCounts.size === 0 ? 0 : Math.max(...folderCounts.values());
+  const maxFolderShare = maxFolderFileCount / totalFiles;
+  const folderBloatPressure =
+    maxFolderFileCount < 12 ? 0 : Math.max(0, maxFolderShare - 0.35);
+  const bloatedFolderCount = [...folderCounts.values()].filter(
+    count => count >= 20 || (count >= 12 && count / totalFiles >= 0.35)
+  ).length;
+  const folderBucketCount = Math.max(1, folderCounts.size);
+  const bloatedFolderRatio = bloatedFolderCount / folderBucketCount;
   const folderScore = clampScore(
     100
     - softPenalty(Math.max(0, (avgDepth - 4) / 3), 20, 1.3)
     - softPenalty(Math.max(0, dominantRootRatio - 0.55), 18, 2.0)
     - softPenalty(vagueDirRatio, 24, 2.2)
+    - softPenalty(folderBloatPressure, 18, 2.0)
+    - softPenalty(bloatedFolderRatio, 14, 1.8)
   );
   aspects.push({
     aspect: 'folder-topology',
@@ -735,7 +750,7 @@ export function computeQualityAspectRatings(
     grade: gradeScore(folderScore),
     confidence: confidenceFromSample(filePaths.length),
     rationale:
-      'Rates how navigable the folder model is by blending depth balance, top-level concentration, and reliance on vague utility/common directories.',
+      'Rates how navigable the folder model is by blending depth balance, top-level concentration, leaf-folder bloat, and reliance on vague utility/common directories.',
     signals: [
       {
         label: 'Average path depth',
@@ -752,6 +767,16 @@ export function computeQualityAspectRatings(
         value: `${Math.round(vagueDirRatio * 100)}%`,
         effect: vagueDirRatio > 0.2 ? 'negative' : 'neutral',
       },
+      {
+        label: 'Largest folder file count',
+        value: String(maxFolderFileCount),
+        effect: maxFolderFileCount >= 20 ? 'negative' : 'neutral',
+      },
+      {
+        label: 'Bloated folders',
+        value: `${bloatedFolderCount}/${folderBucketCount}`,
+        effect: bloatedFolderCount > 0 ? 'negative' : 'neutral',
+      },
     ],
   });
 
@@ -940,14 +965,25 @@ export function computeQualityAspectRatings(
     const style = classifyFileNameStyle(baseName);
     styleCounts.set(style, (styleCounts.get(style) || 0) + 1);
   }
+  const folderStyleCounts = new Map<string, number>();
+  for (const segment of dirSegments) {
+    const style = classifyFileNameStyle(segment);
+    folderStyleCounts.set(style, (folderStyleCounts.get(style) || 0) + 1);
+  }
   const dominantStyleRatio =
     styleCounts.size === 0 ? 1 : Math.max(...styleCounts.values()) / totalFiles;
+  const folderSegmentCount = Math.max(1, dirSegments.size);
+  const dominantFolderStyleRatio =
+    folderStyleCounts.size === 0
+      ? 1
+      : Math.max(...folderStyleCounts.values()) / folderSegmentCount;
   const tsFileCount = filePaths.filter(file => /\.(ts|tsx)$/i.test(file)).length;
   const jsFileCount = filePaths.filter(file => /\.(js|jsx|mjs|cjs)$/i.test(file)).length;
   const mixedExtensionRatio = (Math.min(tsFileCount, jsFileCount) / totalFiles) * 2;
   const consistencyScore = clampScore(
     100
     - softPenalty(1 - dominantStyleRatio, 24, 2.0)
+    - softPenalty(1 - dominantFolderStyleRatio, 12, 1.8)
     - softPenalty(mixedExtensionRatio, 12, 1.6)
     - softPenalty(genericFileCount / totalFiles, 10, 1.6)
   );
@@ -959,13 +995,18 @@ export function computeQualityAspectRatings(
     grade: gradeScore(consistencyScore),
     confidence: confidenceFromSample(filePaths.length),
     rationale:
-      'Rates naming/structure consistency with soft penalties for mixed filename styles, mixed TS/JS surface area, and generic file naming concentration.',
+      'Rates naming/structure consistency with soft penalties for mixed file and folder naming styles, mixed TS/JS surface area, and generic file naming concentration.',
     signals: [
       {
         label: 'Dominant naming style',
         value: `${Math.round(dominantStyleRatio * 100)}%`,
         effect: dominantStyleRatio >= 0.7 ? 'positive' : 'negative',
       },
+      {
+        label: 'Dominant folder naming style',
+        value: `${Math.round(dominantFolderStyleRatio * 100)}%`,
+        effect: dominantFolderStyleRatio >= 0.7 ? 'positive' : 'negative',
+      },
       {
         label: 'TS/JS mix ratio',
         value: `${Math.round((Math.min(tsFileCount, jsFileCount) / totalFiles) * 100)}%`,

package/skills/octocode-install/SKILL.md

@@ -306,4 +306,4 @@ Tools responding = setup complete.
 | Skills not loading | Verify `~/<client>/skills/<skill>/SKILL.md` has `name` + `description` |
 | Already installed, want to update | Add `--force`: `npx octocode-cli install --ide cursor --force` |
 
-Docs: [Auth](https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-mcp/docs/AUTHENTICATION_SETUP.md) · [CLI Reference](https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-cli/docs/CLI_REFERENCE.md) · [Skills](https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-cli/docs/SKILLS_GUIDE.md)
+Docs: [Auth](https://github.com/bgauryy/octocode-mcp/blob/main/docs/configuration/providers/AUTHENTICATION_SETUP.md) · [CLI Reference](https://github.com/bgauryy/octocode-mcp/blob/main/docs/dev/reference/CLI_REFERENCE.md) · [Skills](https://github.com/bgauryy/octocode-mcp/blob/main/docs/dev/SKILLS_GUIDE.md)

package/skills/octocode-pull-request-reviewer/README.md

@@ -36,8 +36,8 @@ npx add-skill https://github.com/bgauryy/octocode-mcp/tree/main/skills/octocode-
 
 ### For PR Mode (Remote Pull Requests)
 
-- **Octocode MCP server** running with GitHub/GitLab authentication
-- See [Authentication Setup](https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-mcp/docs/AUTHENTICATION_SETUP.md)
+- **Octocode MCP server** running with GitHub authentication
+- See [Authentication Setup](https://github.com/bgauryy/octocode-mcp/blob/main/docs/configuration/providers/AUTHENTICATION_SETUP.md)
 
 ### For Local Mode (Local Changes) — `ENABLE_LOCAL=true`
 
@@ -64,7 +64,7 @@ export ENABLE_LOCAL=true
 | **Local Filesystem** | `localSearchCode`, `localViewStructure`, `localFindFiles`, `localGetFileContent` | Search, explore, and read code in your workspace |
 | **LSP Semantic** | `lspGotoDefinition`, `lspFindReferences`, `lspCallHierarchy` | Jump to definitions, find all usages, trace call chains |
 
-> **Full documentation:** [Local Tools Reference](https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-mcp/docs/LOCAL_TOOLS_REFERENCE.md) | [Configuration Reference](https://github.com/bgauryy/octocode-mcp/blob/main/docs/CONFIGURATION_REFERENCE.md)
+> **Full documentation:** [Local Tools Reference](https://github.com/bgauryy/octocode-mcp/blob/main/docs/dev/reference/LOCAL_TOOLS_REFERENCE.md) | [Configuration Reference](https://github.com/bgauryy/octocode-mcp/blob/main/docs/configuration/CONFIGURATION_REFERENCE.md)
 
 **Verify it's working:**
 
@@ -237,8 +237,8 @@ Optionally saved to:
 | [references/verification-checklist.md](./references/verification-checklist.md) | Full delivery checklist |
 | [references/parallel-agent-protocol.md](./references/parallel-agent-protocol.md) | Multi-agent swarm strategy |
 | [references/output-template.md](./references/output-template.md) | Report format template (PR + Local) |
-| [Local Tools Reference](https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-mcp/docs/LOCAL_TOOLS_REFERENCE.md) | Full local + LSP tool documentation |
-| [Configuration Reference](https://github.com/bgauryy/octocode-mcp/blob/main/docs/CONFIGURATION_REFERENCE.md) | `ENABLE_LOCAL` and other settings |
+| [Local Tools Reference](https://github.com/bgauryy/octocode-mcp/blob/main/docs/dev/reference/LOCAL_TOOLS_REFERENCE.md) | Full local + LSP tool documentation |
+| [Configuration Reference](https://github.com/bgauryy/octocode-mcp/blob/main/docs/configuration/CONFIGURATION_REFERENCE.md) | `ENABLE_LOCAL` and other settings |
 
 ---
 

package/skills/octocode-pull-request-reviewer/SKILL.md

@@ -104,7 +104,7 @@ Or in the Octocode config file (`local.enabled: true`).
   
   Set ENABLE_LOCAL=true in your Octocode MCP configuration.
   
-  See: https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-mcp/docs/LOCAL_TOOLS_REFERENCE.md
+  See: https://github.com/bgauryy/octocode-mcp/blob/main/docs/dev/reference/LOCAL_TOOLS_REFERENCE.md
   
   Alternatively, push your changes to a PR and I can review that instead.
   ```

package/skills/octocode-research/AGENTS.md

@@ -346,4 +346,4 @@ yarn install
 
 ---
 
-*This skill wraps `octocode-mcp` tools as HTTP endpoints. For tool-specific documentation, see the [octocode-mcp package](https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-mcp/AGENTS.md).*
+*This skill wraps `octocode-mcp` tools as HTTP endpoints. For tool-specific documentation, see the [octocode-mcp package](https://github.com/bgauryy/octocode-mcp/blob/main/AGENTS.md).*

package/skills/octocode-research/README.md

@@ -42,7 +42,7 @@ The server is not just a pass-through — it provides a persistent runtime layer
 npx add-skill https://github.com/bgauryy/octocode-mcp/tree/main/skills/octocode-research
 ```
 
-> Requires GitHub auth. See [Authentication Setup](https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-mcp/docs/AUTHENTICATION_SETUP.md).
+> Requires GitHub auth. See [Authentication Setup](https://github.com/bgauryy/octocode-mcp/blob/main/docs/configuration/providers/AUTHENTICATION_SETUP.md).
 
 Or manually:
 
@@ -201,7 +201,7 @@ Collects de-identified telemetry (usage counts, error rates). Never collects sou
 | [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Architecture |
 | [docs/API_REFERENCE.md](./docs/API_REFERENCE.md) | Full API reference |
 | [docs/FLOWS.md](./docs/FLOWS.md) | Request flow diagrams |
-| [Troubleshooting](https://github.com/bgauryy/octocode-mcp/blob/main/docs/TROUBLESHOOTING.md) | Common issues |
+| [Troubleshooting](https://github.com/bgauryy/octocode-mcp/blob/main/docs/configuration/TROUBLESHOOTING.md) | Common issues |
 
 ---
 

package/skills/octocode-research/docs/ARCHITECTURE.md

@@ -63,7 +63,7 @@ The `octocode-research` skill is an HTTP API server that provides code research
                                 ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │                    External Systems                              │
-│  • Local filesystem (ripgrep, grep, fs)                         │
+│  • Local filesystem (bundled ripgrep, fs)                       │
 │  • GitHub API (via Octokit)                                     │
 │  • NPM Registry API                                             │
 │  • PyPI API                                                     │