scip-query 0.1.0

package/src/setup.ts

@@ -0,0 +1,202 @@
+import {
+  existsSync, mkdirSync, symlinkSync, readlinkSync,
+  unlinkSync, chmodSync, createWriteStream,
+} from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { homedir, platform, arch } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { get as httpsGet } from 'node:https';
+import { tryInstallScipCli } from './reindex/install.js';
+
+const IS_WINDOWS = platform() === 'win32';
+const SKILLS = ['concrete-plan', 'scip-explore', 'scip-debloat', 'scip-verify'];
+const SCIP_VERSION = 'v0.7.0';
+
+// ── Skills Installation ────────────────────────────────────
+
+export interface InstallSkillsResult {
+  installed: string[];
+  skipped: string[];
+  alreadyLinked: string[];
+}
+
+/**
+ * Install scip-query skills into both Claude Code (~/.claude/skills/)
+ * and Codex (~/.codex/skills/). Uses symlinks (junctions on Windows)
+ * so skills auto-update when the package updates.
+ */
+export function installSkills(
+  opts: { quiet?: boolean } = {},
+): InstallSkillsResult {
+  const log = opts.quiet ? () => {} : console.log;
+  const thisFile = fileURLToPath(import.meta.url);
+  const skillsSource = resolve(dirname(thisFile), '..', 'skills');
+
+  const targets = [
+    join(homedir(), '.claude', 'skills'),
+    join(homedir(), '.codex', 'skills'),
+  ];
+
+  const result: InstallSkillsResult = {
+    installed: [],
+    skipped: [],
+    alreadyLinked: [],
+  };
+
+  for (const targetDir of targets) {
+    // Only install if the parent directory exists (tool is installed)
+    const parentDir = dirname(targetDir);
+    if (!existsSync(parentDir)) {
+      continue;
+    }
+
+    mkdirSync(targetDir, { recursive: true });
+    const toolName = targetDir.includes('.codex') ? 'Codex' : 'Claude';
+
+    for (const skill of SKILLS) {
+      const source = join(skillsSource, skill);
+      const target = join(targetDir, skill);
+
+      if (!existsSync(source)) {
+        result.skipped.push(`${toolName}/${skill}`);
+        continue;
+      }
+
+      if (existsSync(target)) {
+        try {
+          const existing = readlinkSync(target);
+          if (resolve(existing) === resolve(source)) {
+            result.alreadyLinked.push(`${toolName}/${skill}`);
+            log(`  ok:   ${skill} → ${toolName} (already linked)`);
+            continue;
+          }
+        } catch {
+          // Not a symlink — don't overwrite user's custom skill
+          result.skipped.push(`${toolName}/${skill}`);
+          log(`  skip: ${skill} → ${toolName} (exists, not a symlink)`);
+          continue;
+        }
+        unlinkSync(target);
+      }
+
+      // Use 'junction' on Windows (doesn't need admin), 'dir' elsewhere
+      symlinkSync(source, target, IS_WINDOWS ? 'junction' : 'dir');
+      result.installed.push(`${toolName}/${skill}`);
+      log(`  done: ${skill} → ${toolName}`);
+    }
+  }
+
+  return result;
+}
+
+// ── SCIP CLI Binary Detection & Installation ───────────────
+
+/**
+ * Check if the `scip` CLI binary is available on PATH.
+ */
+export function isScipInstalled(): boolean {
+  try {
+    const cmd = IS_WINDOWS ? 'where' : 'which';
+    execFileSync(cmd, ['scip'], { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the scip CLI version if installed.
+ */
+export function getScipVersion(): string | null {
+  try {
+    const output = execFileSync('scip', ['--version'], { stdio: 'pipe' }).toString().trim();
+    return output;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the download URL for the scip CLI binary for this platform.
+ */
+function getScipDownloadUrl(): { url: string; filename: string } | null {
+  const os = platform();
+  const cpu = arch();
+
+  let osName: string;
+  let archName: string;
+  let ext: string;
+
+  switch (os) {
+    case 'darwin': osName = 'darwin'; ext = 'tar.gz'; break;
+    case 'linux': osName = 'linux'; ext = 'tar.gz'; break;
+    case 'win32': osName = 'windows'; ext = 'zip'; break;
+    default: return null;
+  }
+
+  switch (cpu) {
+    case 'arm64': archName = 'arm64'; break;
+    case 'x64': archName = 'amd64'; break;
+    default: return null;
+  }
+
+  const filename = `scip-${osName}-${archName}.${ext}`;
+  const url = `https://github.com/sourcegraph/scip/releases/download/${SCIP_VERSION}/${filename}`;
+  return { url, filename };
+}
+
+/**
+ * Print instructions for installing the scip CLI binary.
+ */
+export function printScipInstallInstructions(): void {
+  const download = getScipDownloadUrl();
+
+  console.log('\nThe `scip` CLI is required but not found on PATH.\n');
+
+  if (platform() === 'darwin') {
+    console.log('Install via Homebrew:');
+    console.log('  brew install sourcegraph/scip/scip\n');
+    console.log('Or download manually:');
+  } else {
+    console.log('Download from:');
+  }
+
+  if (download) {
+    console.log(`  ${download.url}\n`);
+  } else {
+    console.log(`  https://github.com/sourcegraph/scip/releases/tag/${SCIP_VERSION}\n`);
+  }
+
+  console.log('After installing, ensure `scip` is on your PATH and run `scip-query reindex`.');
+}
+
+// ── First-Run Setup ────────────────────────────────────────
+
+/**
+ * Run first-time setup: install skills and check for scip binary.
+ * Called from the postinstall script.
+ */
+export function postinstall(): void {
+  console.log('scip-query: installing skills...');
+  const result = installSkills({ quiet: false });
+
+  const total = result.installed.length + result.alreadyLinked.length;
+  if (total > 0) {
+    console.log(`\n${result.installed.length} skill(s) installed, ${result.alreadyLinked.length} already linked.`);
+  }
+
+  // Check for scip binary — auto-install if missing
+  if (!isScipInstalled()) {
+    console.log('\nscip CLI not found on PATH. Attempting auto-install...');
+    const installed = tryInstallScipCli(console.log);
+    if (!installed) {
+      printScipInstallInstructions();
+    }
+  } else {
+    const version = getScipVersion();
+    console.log(`\nscip CLI: ${version ?? 'installed'}`);
+  }
+
+  console.log('');
+}

package/src/symbol-parser.ts

@@ -0,0 +1,278 @@
+import type { ScipSymbol, ScipDescriptor, ScipLocalSymbol, DescriptorSuffix } from './types.js';
+
+/**
+ * SCIP Symbol Grammar (from the SCIP spec):
+ *
+ *   <symbol>     ::= <scheme> ' ' <package> ' ' <descriptor>+ | 'local ' <local-id>
+ *   <package>    ::= <manager> ' ' <package-name> ' ' <version> ' '
+ *   <descriptor> ::= <name> <suffix>
+ *
+ * Suffix characters:
+ *   /    namespace
+ *   #    type (class, interface, enum)
+ *   .    term (variable, field, property)
+ *   ().  method
+ *   [    type parameter
+ *   ()   parameter
+ *   :    meta
+ *   !    macro
+ *
+ * Names may be backtick-escaped: `some.weird/name`
+ */
+
+const SUFFIX_MAP: Record<string, DescriptorSuffix> = {
+  '/': 'namespace',
+  '#': 'type',
+  '.': 'term',
+  '[': 'type-param',
+  ':': 'meta',
+  '!': 'macro',
+};
+
+/**
+ * Parse a SCIP symbol string into its structured components.
+ * Works for any SCIP-indexed language (TypeScript, Java, Rust, Python, etc.)
+ */
+export function parseSymbol(raw: string): ScipSymbol | ScipLocalSymbol {
+  if (raw.startsWith('local ')) {
+    return { kind: 'local', id: raw.slice(6), raw };
+  }
+
+  // Split: <scheme> <manager> <package-name> <version> <descriptors...>
+  // The tricky part: package-name can contain spaces if backtick-escaped
+  const parts = raw.split(' ');
+  if (parts.length < 4) {
+    // Malformed — return a best-effort parse
+    return {
+      scheme: parts[0] ?? '',
+      manager: parts[1] ?? '',
+      packageName: parts[2] ?? '',
+      version: '',
+      descriptors: [],
+      raw,
+    };
+  }
+
+  const scheme = parts[0]!;
+  const manager = parts[1]!;
+
+  // Package name and version: package name might be backtick-escaped
+  // After scheme + manager, we need to find package + version + descriptor string
+  let restAfterManager = raw.slice(scheme.length + 1 + manager.length + 1);
+
+  // Parse package name (may be backtick-escaped)
+  let packageName: string;
+  if (restAfterManager.startsWith('`')) {
+    const closingTick = restAfterManager.indexOf('`', 1);
+    if (closingTick === -1) {
+      packageName = restAfterManager.slice(1);
+      restAfterManager = '';
+    } else {
+      packageName = restAfterManager.slice(1, closingTick);
+      restAfterManager = restAfterManager.slice(closingTick + 2); // skip ` and space
+    }
+  } else {
+    const spaceIdx = restAfterManager.indexOf(' ');
+    if (spaceIdx === -1) {
+      packageName = restAfterManager;
+      restAfterManager = '';
+    } else {
+      packageName = restAfterManager.slice(0, spaceIdx);
+      restAfterManager = restAfterManager.slice(spaceIdx + 1);
+    }
+  }
+
+  // Parse version
+  let version: string;
+  const versionSpaceIdx = restAfterManager.indexOf(' ');
+  if (versionSpaceIdx === -1) {
+    version = restAfterManager;
+    restAfterManager = '';
+  } else {
+    version = restAfterManager.slice(0, versionSpaceIdx);
+    restAfterManager = restAfterManager.slice(versionSpaceIdx + 1);
+  }
+
+  // Parse descriptors from the remaining string
+  const descriptors = parseDescriptors(restAfterManager);
+
+  return { scheme, manager, packageName, version, descriptors, raw };
+}
+
+/**
+ * Parse the descriptor chain from a SCIP symbol.
+ *
+ * SCIP descriptor grammar:
+ *   namespace:   name/
+ *   type:        name#
+ *   term:        name.
+ *   method:      name(disambiguator).
+ *   type-param:  [name]          (bracket-wrapped, prefix syntax)
+ *   parameter:   (name)          (paren-wrapped, prefix syntax)
+ *   meta:        name:
+ *   macro:       name!
+ *
+ * Names can be backtick-escaped: `some/name.with.dots`
+ */
+function parseDescriptors(input: string): ScipDescriptor[] {
+  const descriptors: ScipDescriptor[] = [];
+  let i = 0;
+
+  while (i < input.length) {
+    // Type parameter: [name]
+    if (input[i] === '[') {
+      const closeBracket = input.indexOf(']', i + 1);
+      if (closeBracket === -1) {
+        descriptors.push({ name: input.slice(i + 1), suffix: 'type-param' });
+        break;
+      }
+      descriptors.push({ name: input.slice(i + 1, closeBracket), suffix: 'type-param' });
+      i = closeBracket + 1;
+      continue;
+    }
+
+    // Parameter: (name) — only when ( appears at descriptor start with no preceding name
+    if (input[i] === '(' && (descriptors.length === 0 || i === 0 || isSuffixChar(input[i - 1]!))) {
+      const closeParen = input.indexOf(')', i + 1);
+      if (closeParen !== -1 && input[closeParen + 1] !== '.') {
+        // This is a parameter (name), not a method disambiguator
+        descriptors.push({ name: input.slice(i + 1, closeParen), suffix: 'parameter' });
+        i = closeParen + 1;
+        continue;
+      }
+    }
+
+    let name: string;
+
+    // Backtick-escaped name
+    if (input[i] === '`') {
+      const closingTick = input.indexOf('`', i + 1);
+      if (closingTick === -1) {
+        name = input.slice(i + 1);
+        i = input.length;
+        descriptors.push({ name, suffix: 'term' });
+        break;
+      }
+      name = input.slice(i + 1, closingTick);
+      i = closingTick + 1;
+    } else {
+      // Read name until we hit a suffix character
+      const start = i;
+      while (i < input.length && !isSuffixChar(input[i]!)) {
+        i++;
+      }
+      name = input.slice(start, i);
+    }
+
+    // Parse suffix after name
+    if (i >= input.length) {
+      if (name) descriptors.push({ name, suffix: 'term' });
+      break;
+    }
+
+    const char = input[i]!;
+
+    // Method: name(disambiguator).
+    if (char === '(') {
+      const closeParen = input.indexOf(')', i + 1);
+      if (closeParen !== -1 && input[closeParen + 1] === '.') {
+        descriptors.push({ name, suffix: 'method' });
+        i = closeParen + 2; // skip past ).
+      } else if (closeParen !== -1) {
+        // Bare (disambiguator) without . — treat as method anyway (common in practice)
+        descriptors.push({ name, suffix: 'method' });
+        i = closeParen + 1;
+      } else {
+        descriptors.push({ name, suffix: 'term' });
+        i++;
+      }
+    } else {
+      const suffix = SUFFIX_MAP[char];
+      if (suffix) {
+        descriptors.push({ name, suffix });
+        i += 1;
+      } else {
+        i += 1; // Unknown suffix — skip
+      }
+    }
+  }
+
+  return descriptors;
+}
+
+function isSuffixChar(c: string): boolean {
+  return c === '/' || c === '#' || c === '.' || c === '(' || c === '[' || c === ':' || c === '!';
+}
+
+/**
+ * Convert a parsed SCIP symbol to a short, human-readable name.
+ * Language-agnostic: works for any SCIP-indexed language.
+ *
+ * Examples:
+ *   "scip-typescript npm @vega/api 0.1.3 src/modules/auth/auth.service.ts/AuthService#login()."
+ *   → "auth.service:AuthService:login()"
+ *
+ *   "scip-java maven com.example/mylib 1.0.0 com/example/MyClass#doStuff()."
+ *   → "MyClass:doStuff()"
+ *
+ *   "rust-analyzer cargo my-crate 0.1.0 src/lib.rs/MyStruct#new()."
+ *   → "lib:MyStruct:new()"
+ */
+export function shortenSymbol(raw: string): string {
+  const parsed = parseSymbol(raw);
+  if ('kind' in parsed && parsed.kind === 'local') {
+    return `local:${parsed.id}`;
+  }
+
+  const sym = parsed as ScipSymbol;
+  if (sym.descriptors.length === 0) return sym.raw;
+
+  const parts: string[] = [];
+  for (const desc of sym.descriptors) {
+    // Strip file extensions from namespace descriptors (the file path parts)
+    let name = desc.name;
+    if (desc.suffix === 'namespace') {
+      // Remove common file extensions
+      name = name
+        .replace(/\.(ts|tsx|js|jsx|mjs|cjs)$/, '')
+        .replace(/\.(py|pyi)$/, '')
+        .replace(/\.(rs)$/, '')
+        .replace(/\.(java|scala|kt|kts)$/, '')
+        .replace(/\.(rb)$/, '')
+        .replace(/\.(go)$/, '')
+        .replace(/\.(cs|vb)$/, '')
+        .replace(/\.(dart)$/, '')
+        .replace(/\.(php)$/, '')
+        .replace(/\.(c|cc|cpp|cxx|h|hpp)$/, '');
+    }
+
+    // Skip empty names (can happen with trailing suffixes)
+    if (!name) continue;
+
+    // For methods, append () for clarity
+    if (desc.suffix === 'method') {
+      parts.push(`${name}()`);
+    } else {
+      parts.push(name);
+    }
+  }
+
+  return parts.join(':');
+}
+
+/**
+ * Extract just the leaf name from a SCIP symbol.
+ * Useful when you only need the function/class/variable name without path context.
+ */
+export function leafName(raw: string): string {
+  const parsed = parseSymbol(raw);
+  if ('kind' in parsed && parsed.kind === 'local') {
+    return parsed.id;
+  }
+
+  const sym = parsed as ScipSymbol;
+  if (sym.descriptors.length === 0) return '';
+
+  const last = sym.descriptors[sym.descriptors.length - 1]!;
+  return last.name;
+}