octocode-cli 1.2.5 → 1.2.7

package/skills/octocode-code-engineer/eslint.config.mjs

@@ -0,0 +1,54 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import importPlugin from 'eslint-plugin-import';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['src/**/*.ts'],
+    plugins: {
+      import: importPlugin,
+    },
+    languageOptions: {
+      parserOptions: {
+        project: null,
+        tsconfigRootDir: __dirname,
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      '@typescript-eslint/no-explicit-any': 'error',
+      'import/first': 'error',
+      'import/newline-after-import': 'error',
+      'import/order': [
+        'error',
+        {
+          groups: ['builtin', 'external', 'internal', ['parent', 'sibling', 'index'], 'type'],
+          'newlines-between': 'always',
+          alphabetize: {
+            order: 'asc',
+            caseInsensitive: true,
+          },
+        },
+      ],
+      'sort-imports': ['error', { ignoreDeclarationSort: true }],
+      '@typescript-eslint/no-use-before-define': [
+        'error',
+        {
+          functions: false,
+          classes: true,
+          variables: true,
+        },
+      ],
+      'no-empty': 'error',
+    },
+  },
+  {
+    ignores: ['dist/**', 'node_modules/**', 'scripts/**'],
+  }
+);

package/skills/octocode-code-engineer/minify-scripts.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { minify } from 'terser';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const scriptsDir = path.join(__dirname, 'scripts');
+
+function collectJsFiles(dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectJsFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith('.js')) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+const files = collectJsFiles(scriptsDir);
+
+for (const filePath of files) {
+  let code = fs.readFileSync(filePath, 'utf8');
+  const shebang = code.startsWith('#!') ? code.slice(0, code.indexOf('\n') + 1) : '';
+  if (shebang) code = code.slice(shebang.length);
+  const result = await minify(code, { compress: true, mangle: true, format: { ecma: 2020 } });
+  if (result.error) throw result.error;
+  fs.writeFileSync(filePath, shebang + (result.code ?? ''), 'utf8');
+}

package/skills/octocode-code-engineer/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "octocode-local-code-quality",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "AST-based code quality analysis with duplicate detection, complexity metrics, and dependency graph intelligence",
+  "author": "Guy Bary <bgauryy@octocodeai.com>",
+  "homepage": "https://octocode.ai",
+  "repository": "bgauryy/octocode-mcp.git",
+  "license": "MIT",
+  "keywords": [
+    "agent-skill",
+    "ast-analysis",
+    "code-quality",
+    "tree-sitter",
+    "dependency-graph",
+    "octocode"
+  ],
+  "scripts": {
+    "build": "tsc && node minify-scripts.mjs",
+    "build:watch": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "analyze": "node scripts/index.js",
+    "analyze:json": "node scripts/index.js --json --out .octocode/scan/scan.json",
+    "analyze:full": "node scripts/index.js --include-tests --findings-limit 500 --deep-link-topn 30 --out .octocode/scan/scan.json",
+    "analyze:graph": "node scripts/index.js --graph --out .octocode/scan/scan.json",
+    "search": "node scripts/ast/search.js",
+    "search:json": "node scripts/ast/search.js --json",
+    "search:presets": "node scripts/ast/search.js --list-presets",
+    "search:trees": "node scripts/ast/tree-search.js",
+    "search:trees:json": "node scripts/ast/tree-search.js --json"
+  },
+  "dependencies": {
+    "@ast-grep/napi": "^0.42.0",
+    "tree-sitter": "^0.25.0",
+    "tree-sitter-typescript": "^0.23.2",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.27.0",
+    "@types/node": "^20.0.0",
+    "eslint": "^9.27.0",
+    "eslint-plugin-import": "^2.32.0",
+    "terser": "^5.46.1",
+    "typescript-eslint": "^8.32.0",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/skills/octocode-code-engineer/references/agent-ast-reading-rfc.md

@@ -0,0 +1,95 @@
+# RFC: Agent-Safe AST Artifact Reading
+
+> **Status: Implemented.** This RFC documents the design decisions behind `ast/tree-search.js`. For usage, see [ast-tree-search.md](./ast-tree-search.md). This file is architectural context only — not an actionable guide.
+
+## Summary
+
+This RFC standardizes how agents inspect generated AST artifacts in `octocode-local-code-quality`.
+
+The recommendation is to keep a dedicated `ast-tree-search` CLI for `ast-trees.txt`, make the TypeScript source authoritative, generate the runtime JS from that source, and have generated `summary.md` guidance point to the exact scan artifact being discussed.
+
+## Motivation
+
+The current AST artifact workflow had four failures:
+
+1. latest-scan ambiguity: commands that target `.octocode/scan` can silently read a different scan than the `summary.md` the agent is reviewing
+2. conflicting working-directory assumptions: some generated commands only work inside a scan directory while others assume repo-root or skill-root execution
+3. source/runtime drift: AST guidance and runtime behavior diverged because `scripts/` and `src/` were not acting like one source-of-truth pipeline
+4. agent-noisy output: artifact search could dump hundreds of hits with no built-in narrowing, which makes triage harder and increases false conclusions
+
+Agents need artifact inspection that is pinned, bounded, and clearly separate from source-level AST search.
+
+## Alternatives Considered
+
+### 1. Keep `grep` or `rg` only
+
+Pros:
+
+- zero new code
+- flexible for power users
+
+Cons:
+
+- easy to run against the wrong artifact
+- no default bounding or structured metadata
+- weak affordances for agents that need predictable output
+
+### 2. Teach `ast-search` to ingest generated output files
+
+Pros:
+
+- one CLI surface
+- reuses an existing command name
+
+Cons:
+
+- mixes two different problem spaces: generated artifact triage and source-level AST matching
+- increases confusion about what is being validated
+- encourages agents to treat artifact search as if it were source proof
+
+### 3. Keep a dedicated AST artifact CLI with TypeScript source-of-truth
+
+Pros:
+
+- clean separation between artifact navigation and source search
+- output can be optimized for agent triage
+- easy to pin generated guidance to the current scan
+
+Cons:
+
+- one additional CLI surface to document and test
+- more summary-generation logic
+- build sync must be maintained so `scripts/` does not drift from `src`
+
+## Recommendation
+
+Adopt alternative 3.
+
+- `ast-tree-search` remains a dedicated CLI for generated `ast-trees.txt`
+- `ast-search` remains the source-level structural search tool
+- the TypeScript source under `src/` becomes the implementation source of truth
+- generated `summary.md` points to the exact `ast-trees.txt` file for the current scan
+- artifact search output is bounded and filterable by default
+
+## Design Notes
+
+- default `--limit` is `50`; `0` means unlimited output
+- `--file` and `--section` support scan-specific narrowing
+- output always includes the selected `ast-trees.txt` file
+- JSON output includes parsed `file` metadata for each match
+- raw `rg` remains documented only as a fallback for indentation/text checks
+
+## Drawbacks
+
+- more implementation and testing surface
+- generated docs and runtime help must stay aligned
+- users now need to understand when to use artifact search versus source search
+
+## Implementation Plan
+
+1. Add `src/ast-tree-search.ts` and tests.
+2. Regenerate runtime `scripts/` from TypeScript source.
+3. Update `summary.md` generation to print pinned commands for the current scan.
+4. Add package aliases and reference docs for the new CLI.
+5. Update skill docs so the artifact-search flow is consistent everywhere.
+6. Validate with package tests and a real scoped scan.

package/skills/octocode-code-engineer/references/architecture-techniques.md

@@ -0,0 +1,121 @@
+# Architecture Techniques
+
+Use this reference when the scan output is directionally useful but not yet strong enough to justify a confident architecture claim.
+
+> For how to validate architecture findings with tools, see [validate & investigate](./validate-investigate.md) and the Architecture Playbooks in [playbooks.md](./playbooks.md). For metric definitions (instability, SDP, cyclomatic density), see [concepts.md](./concepts.md).
+
+---
+
+## Graph Techniques
+
+### SCC Condensation
+
+Collapse raw file cycles into strongly connected clusters before reasoning about architecture. This is better than treating every cycle edge as a separate problem.
+
+Use when:
+
+- many `dependency-cycle` findings point at overlapping files
+- the same hotspot appears in multiple cycle paths
+- the graph feels "sticky" but a single edge fix is unclear
+
+Interpretation:
+
+- a large SCC usually means a subsystem boundary is missing
+- hub files inside an SCC are better refactor starting points than random cycle members
+
+### Package / Folder Graph
+
+Aggregate file edges into package or folder edges to see subsystem behavior.
+
+Use when:
+
+- file-level cycles hide the real architectural issue
+- the repo has many cross-package imports
+- the user asks about bounded contexts or team ownership
+
+Interpretation:
+
+- high cross-package chatter means packages are acting like one subsystem
+- one package importing many internals of another usually means boundary erosion
+
+### Broker / Articulation Analysis
+
+Look for modules that many dependency paths flow through.
+
+Use when:
+
+- `hotFiles[]` is dominated by one or two files
+- changes in one file ripple unexpectedly broadly
+- the architecture feels centralized without an obvious god module
+
+Interpretation:
+
+- articulation points are brittle bridges between subsystems
+- high-scoring chokepoints are priority refactor targets even if they have few direct findings
+
+---
+
+## AST And Semantic Techniques
+
+### Relational AST Rules
+
+Use structure-aware rules instead of single-node patterns.
+
+Good targets:
+
+- boundary leaks
+- import-time orchestration
+- controller -> repository shortcuts
+- modules mixing transport, persistence, and domain logic
+
+Ask:
+
+- is the suspicious node `inside` the wrong context?
+- does the module `have` multiple unrelated responsibilities?
+- do bad patterns `follow` or `precede` each other in a repeated shape?
+
+### Symbol-Level Usage Graphs
+
+Reason below the file level by tracking which exports are consumed together.
+
+Use when:
+
+- `low-cohesion` is flagged
+- `feature-envy` looks real but the file is still widely used
+- a barrel or utility file may hide unrelated APIs
+
+Interpretation:
+
+- disjoint consumer groups usually mean the file exports multiple concepts
+- one symbol cluster dominating imports can mean the logic belongs closer to that target
+
+### CFG / Dataflow Checks
+
+Use lightweight flow reasoning to avoid flat heuristic claims.
+
+Best questions:
+
+- does validation dominate sink usage?
+- does cleanup happen on all exits?
+- is initialization happening only on some paths?
+- does import-time work trigger hidden side effects?
+
+Interpretation:
+
+- if the path is not explainable, lower confidence
+- if validation or cleanup is path-dependent, prefer a hybrid conclusion over a local one
+
+---
+
+## How To Decide
+
+- Use the **graph lens** first for cycles, chokepoints, package chatter, and startup risk.
+- Use the **AST lens** first for low cohesion, feature envy, repeated orchestration, and side effects.
+- Use the **hybrid lens** when graph and AST evidence point to the same file or boundary.
+- If graph and AST signals conflict, say so explicitly and validate before concluding.
+
+---
+
+## Validation
+
+These techniques are investigation tools, not proof. Validate statements about live code with Octocode local tools before presenting as fact. See the Principles section in [SKILL.md](../SKILL.md).

package/skills/octocode-code-engineer/references/ast-search.md

@@ -0,0 +1,210 @@
+# AST Search Reference
+
+Structural code search powered by [`@ast-grep/napi`](https://ast-grep.github.io/). Finds code by AST shape, not text — `console.log(x)` matches regardless of whitespace or formatting.
+
+```bash
+node <SKILL_DIR>/scripts/ast/search.js [options]
+```
+
+---
+
+## Search Modes
+
+Pick one per invocation.
+
+### Pattern (`-p`, `--pattern`)
+
+Write the code shape. Replace variable parts with `$X` (one node) or `$$$X` (zero or more).
+
+```bash
+-p 'console.log($$$ARGS)'                    # all console.log
+-p 'console.$METHOD($$$ARGS)'                # any console method
+-p 'if ($COND) { return $VAL }'              # early returns
+-p 'import { $$$NAMES } from $MOD'           # named imports (any module)
+-p 'export const $NAME = $VAL'               # exported constants
+-p 'process.env.$VAR'                        # env access
+-p 'throw new Error($$$MSG)'                 # error throws
+-p 'function $NAME($$$P) { $$$B }'           # function declarations
+-p 'const $NAME = ($$$P) => $BODY'           # arrow assignments
+```
+
+Meta-variables captured in JSON output under `metaVariables`:
+
+```json
+{ "$METHOD": "log", "$$$ARGS": "\"hello\", 42" }
+```
+
+> **Quote sensitivity**: `'fs'` won't match `"fs"`. Use `$MOD` wildcard to match any quote style.
+
+### Kind (`-k`, `--kind`)
+
+Match all nodes of an AST kind.
+
+```bash
+-k function_declaration    -k arrow_function         -k class_declaration
+-k interface_declaration   -k type_alias_declaration  -k import_statement
+-k try_statement           -k switch_statement        -k for_in_statement
+-k await_expression        -k template_string         -k object_pattern
+```
+
+> TS-only kinds (`predefined_type`, `interface_declaration`) are silently skipped on `.js` files.
+
+### Preset (`--preset`)
+
+16 built-in rules for common patterns. List with `--list-presets`.
+
+| Preset | Finds |
+|--------|-------|
+| `empty-catch` | `catch (e) {}` — silently swallowed errors |
+| `console-log` | `console.log(...)` left in production |
+| `console-any` | Any `console.*()` call |
+| `debugger` | `debugger;` statements |
+| `todo-fixme` | TODO/FIXME/HACK/XXX/BUG comments |
+| `any-type` | `: any` annotations (TS only) |
+| `type-assertion` | `x as Type` assertions |
+| `non-null-assertion` | `x!` non-null assertions |
+| `fat-arrow-body` | `() => { return x }` — could be expression |
+| `nested-ternary` | `a ? (b ? 1 : 2) : 3` |
+| `throw-string` | `throw "oops"` — should be Error |
+| `switch-no-default` | `switch` without `default` |
+| `class-declaration` | All class declarations |
+| `async-function` | `async function` declarations |
+| `export-default` | `export default` statements |
+| `import-star` | `import * as X` namespace imports |
+
+### Rule (`--rule`)
+
+Raw ast-grep rule JSON. Use for negation, regex, or nested structural queries.
+
+```bash
+# Negation: if without else
+--rule '{"rule":{"kind":"if_statement","not":{"has":{"kind":"else_clause"}}}}'
+
+# Regex on text: secrets in strings
+--rule '{"rule":{"kind":"string","regex":"password|secret|token|api.?key"}}'
+
+# Nested: try with finally
+--rule '{"rule":{"kind":"try_statement","has":{"kind":"finally_clause","stopBy":"end"}}}'
+
+# Long param lists
+--rule '{"rule":{"kind":"formal_parameters","regex":"(,.*){5,}"}}'
+```
+
+**Rule operators:**
+
+| Operator | Purpose | Example |
+|----------|---------|---------|
+| `kind` | Match node kind | `{"kind":"catch_clause"}` |
+| `pattern` | Match code shape | `{"pattern":"console.log($$$A)"}` |
+| `regex` | Match node text | `{"regex":"TODO\|FIXME"}` |
+| `has` | Child matches rule | `{"has":{"kind":"finally_clause"}}` |
+| `not` | Negate | `{"not":{"has":{"kind":"else_clause"}}}` |
+| `all` | AND | `{"all":[{"kind":"X"},{"regex":"Y"}]}` |
+| `any` | OR | `{"any":[{"kind":"X"},{"kind":"Y"}]}` |
+| `stopBy: "end"` | Search descendants (not just direct children) | `{"has":{"kind":"X","stopBy":"end"}}` |
+| `field` | Match by grammar field | `{"has":{"field":"default"}}` |
+
+---
+
+## CLI Reference
+
+```
+node scripts/ast/search.js [options]
+
+Search (pick one):
+  -p, --pattern <code>     Code shape with $X/$$$X wildcards
+  -k, --kind <name>        AST node kind
+  --preset <name>          Built-in rule (see --list-presets)
+  --rule <json>            Raw ast-grep rule JSON
+
+Options:
+  --root <path>            Search directory (default: cwd)
+  --json                   JSON output (use for programmatic consumption)
+  --limit N                Max matches (default: 500)
+  --include-tests          Include *.test.*, *.spec.*, __tests__/
+  -C, --context N          Context lines around matches (text mode only)
+  --list-presets           List presets and exit
+  -h, --help               Show help
+```
+
+| Flag | Default | Notes |
+|------|---------|-------|
+| `--root` | cwd | Relative or absolute |
+| `--json` | off | Outputs `AstSearchResult` — always use for agent consumption |
+| `--limit` | 500 | Global cap across all files |
+| `--include-tests` | off | Test files excluded by default |
+| `--context` | 0 | Shows source lines around matches with `>` marker |
+
+**Scanned**: `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs` (excludes `.d.ts`)
+
+**Skipped dirs**: `.git`, `.next`, `.yarn`, `.cache`, `.octocode`, `node_modules`, `dist`, `coverage`, `out`
+
+---
+
+## Output
+
+### Text (default)
+
+```
+🔍 preset:empty-catch — Empty catch blocks that silently swallow errors
+   3 matches across 2 files
+
+── packages/core/src/parser.ts ──
+  L42:4  [catch_clause]  catch (e) { }
+```
+
+### Text with `--context 2`
+
+```
+── src/index.ts ──
+     896 |   for (const [key, file] of Object.entries(outputFiles)) {
+     897 |     let size = '—';
+  >  898 |     try { size = formatFileSize(fs.statSync(path.join(dir, file)).size); } catch {}
+     899 |     lines.push(...);
+     900 |   }
+```
+
+### JSON (`--json`)
+
+```json
+{
+  "query": "preset:empty-catch — ...",
+  "queryType": "preset",
+  "totalMatches": 3,
+  "totalFiles": 2,
+  "matches": [{
+    "file": "packages/core/src/parser.ts",
+    "kind": "catch_clause",
+    "text": "catch (e) { }",
+    "lineStart": 42, "lineEnd": 42,
+    "columnStart": 4, "columnEnd": 18,
+    "metaVariables": {}
+  }]
+}
+```
+
+---
+
+## Agent Guide
+
+### Decision Tree
+
+```
+"Find all X() calls"        → -p 'X($$$ARGS)'
+"Find all X nodes"          → -k X_kind_name
+"Known code smell"          → --preset name
+"Negation / regex / nesting" → --rule '{...}'
+```
+
+### Rules for Agents
+
+1. **Always `--json`** for programmatic use. Parse `totalMatches`, iterate `matches[]`.
+2. **Start narrow**: `--limit 10 --root <specific-dir>` before broad search.
+3. **Chain with scan**: `index.js` flags `unsafe-any` → `--preset any-type --root <pkg>`.
+4. **Use `$MOD`** for imports — avoids quote mismatch.
+5. **`--rule` for negation** — patterns can't express "X without Y".
+6. **`stopBy: "end"`** required for recursive `has` (descendant search, not just children).
+7. **Grammar-safe**: TS-only kinds silently skipped on JS files.
+8. **`--include-tests`** for `describe`, `it`, `expect` patterns.
+9. **Meta-variables** appear in JSON — extract captured `$NAME`, `$MOD`, `$$$ARGS`.
+10. **`-C N`** for context — shows N lines before/after matches in text mode.