@ophan/core 0.0.1

package/README.md

@@ -0,0 +1,107 @@
+# @ophan/core
+
+Multi-language analysis engine combining language-native AST parsing with Claude-powered security analysis and documentation.
+
+## Capabilities
+
+### Static Analysis
+- Function extraction via pluggable language parsers (`src/parsers/`)
+- TypeScript/JavaScript: TypeScript compiler API
+- Python: Python's own `ast` module via subprocess (zero npm deps)
+- Content hashing (SHA256) for change detection and content-addressed storage
+- AST traversal for control flow understanding
+
+### Content-Addressed Storage
+Analysis is keyed by SHA256 of function source code:
+- Same function on any branch = same hash = same analysis entry
+- Skip analysis entirely when hash already exists in DB
+- Insert-only sync — no conflict resolution needed
+- Orphaned hashes accumulate harmlessly until manual `ophan gc` (30-day grace period, safe for branch switching)
+
+### Two-Table Schema
+- `function_analysis` — `content_hash → analysis JSON, model_version, created_at, language, entity_type` (synced to cloud)
+- `file_functions` — `file_path + function_name → content_hash, file_mtime, language, entity_type` (local only). No line numbers — resolved at runtime via LSP/parser.
+
+### Incremental Scanning
+1. Check `file_mtime` against stored value — skip unchanged files entirely (no parse)
+2. Re-parse changed files, extract functions, compute hashes
+3. Look up hash in `function_analysis` — skip if exists
+4. Only call Claude API for functions with new/unknown hashes
+5. Update `file_functions` with file path, function name, content_hash, mtime
+
+### AI Analysis
+Leverages Claude to provide:
+- Natural language function descriptions
+- Parameter and return type documentation
+- Security vulnerability identification
+- Data flow classification
+
+### Security Detection
+Identifies common vulnerabilities:
+- SQL injection risks
+- Cross-site scripting (XSS) potential
+- Hardcoded secrets and credentials
+- Unsanitized user input
+- Path traversal vulnerabilities
+
+### Data Flow Tagging
+Classifies functions by data they handle:
+- `user_input` — Processes user-provided data
+- `pii` — Handles personally identifiable information
+- `credentials` — Works with authentication data
+- `database` — Database read/write operations
+- `external_api` — Makes external HTTP requests
+- `file_system` — File I/O operations
+- `config` — Configuration management
+- `internal` — Internal system operations
+
+## Storage
+
+SQLite database at `.ophan/index.db` (gitignored, per-repo). Designed for:
+- Fast querying by content hash, file path, and line number
+- Incremental updates (only new hashes trigger analysis)
+- JSON storage for structured analysis results
+- Branch-agnostic analysis with branch-specific location mappings
+
+## Multi-Language Architecture
+
+### Parser Interface (`src/parsers/`)
+
+Function extraction is handled by pluggable, language-specific parsers. Each implements the `LanguageParser` interface:
+
+```typescript
+interface LanguageParser {
+  language: string;       // e.g. "typescript", "python"
+  extensions: string[];   // e.g. [".ts", ".tsx"]
+  extractFunctions(filePath: string): FunctionInfo[];
+}
+```
+
+**Current parsers:**
+- **TypeScript/JavaScript** (`parsers/typescript.ts`): Uses the TypeScript compiler API. Handles `.ts`, `.tsx`, `.js`, `.jsx`.
+- **Python** (`parsers/python.ts`): Shells out to `python3` with an inline `ast` module script. Handles `.py`. Gracefully skips if `python3` not installed.
+
+**To add a new language** (e.g. Go, Java):
+1. Create `parsers/go.ts` implementing `LanguageParser`
+2. Register it in `parsers/index.ts`
+3. That's it — the glob pattern, analysis pipeline, DB storage, and sync all pick it up automatically
+
+**Why no tree-sitter?** Each language uses its own native tooling (TS compiler, Python's ast, go/parser, etc.) rather than a universal parser framework. This avoids native C dependencies, grammar management, and adds zero npm packages per language.
+
+### Schema Fields
+
+Both tables carry `language` and `entity_type` fields set at parse time:
+- **`language`**: Derived from file extension (`.ts` → `"typescript"`, `.py` → `"python"`). Drives prompt template selection and language-specific security flags.
+- **`entity_type`**: Derived from AST node kind (`isMethodDeclaration` → `"method"`, `FunctionDef` inside `ClassDef` → `"method"`). Enables class-level vs function-level analysis.
+
+### Migration Safety
+
+Both tables use `DEFAULT 'typescript'` and `DEFAULT 'function'` for the new columns. Existing databases are migrated via `ALTER TABLE ADD COLUMN` on init — safe, no data loss.
+
+## Extensibility
+
+Designed to support:
+- Additional programming languages via parser interface (Go, Java, Rust planned)
+- Alternative AI models (Bedrock for enterprise)
+- Custom security rules
+- Supabase sync for cloud features

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+import Database from "better-sqlite3";
+export { FunctionInfo, computeHash } from "./shared";
+export { getSupportedExtensions } from "./parsers";
+export * from "./schemas";
+import type { FunctionInfo } from "./shared";
+/**
+ * Ensure .ophan/ is in .gitignore. Only acts in git repos.
+ * Creates .gitignore if the repo has .git/ but no .gitignore.
+ */
+export declare function ensureGitignore(rootPath: string): void;
+/**
+ * Discover source files using git (respects .gitignore) with glob fallback.
+ * Returns absolute paths filtered to supported extensions.
+ */
+export declare function discoverFiles(rootPath: string): Promise<string[]>;
+export interface AnalyzedFunction extends FunctionInfo {
+    description: string;
+    params: {
+        name: string;
+        type: string;
+        description: string;
+    }[];
+    returns: {
+        type: string;
+        description: string;
+    };
+    dataTags: string[];
+    securityFlags: string[];
+}
+export interface FunctionAnalysis {
+    description: string;
+    params: {
+        name: string;
+        type: string;
+        description: string;
+    }[];
+    returns: {
+        type: string;
+        description: string;
+    };
+    dataTags: string[];
+    securityFlags: string[];
+}
+export interface FileAnalysisEntry {
+    functionName: string;
+    contentHash: string;
+    analysis: FunctionAnalysis;
+    language: string;
+    entityType: string;
+}
+export declare function initDb(dbPath: string): Database.Database;
+/**
+ * Migrate from single-blob function_analysis to split analysis types.
+ * Creates v2 table, splits each existing row into 'documentation' + 'security' rows,
+ * drops old table, renames. Sets synced_at = NULL to force full re-sync.
+ */
+export declare function migrateToAnalysisTypes(db: Database.Database): void;
+export declare function analyzeFunctions(functions: FunctionInfo[]): Promise<AnalyzedFunction[]>;
+export interface AnalyzeFilesOptions {
+    pullFn?: (hashes: string[]) => Promise<void>;
+    onProgress?: (current: number, total: number, file: string) => void;
+}
+export interface AnalyzeFilesResult {
+    analyzed: number;
+    skipped: number;
+    pulled: number;
+    skippedSize: number;
+}
+/**
+ * Analyze a specific set of files: parse → hash → pull → Claude → store.
+ * Used by `analyzeRepository()` for full scans and `ophan watch` for incremental.
+ * The caller is responsible for DB lifecycle (open/close).
+ */
+export declare function analyzeFiles(db: Database.Database, rootPath: string, files: string[], options?: AnalyzeFilesOptions): Promise<AnalyzeFilesResult>;
+export declare function analyzeRepository(rootPath: string, onProgress?: (current: number, total: number, file: string) => void, pullFn?: (hashes: string[]) => Promise<void>): Promise<{
+    analyzed: number;
+    skipped: number;
+    pulled: number;
+    skippedSize: number;
+    files: number;
+}>;
+/**
+ * Merge documentation + security analysis rows for a content_hash into
+ * the unified FunctionAnalysis shape that consumers expect.
+ */
+export declare function mergeAnalysisRows(rows: {
+    analysis_type: string;
+    analysis: string;
+}[]): FunctionAnalysis;
+export declare function getAnalysisForFile(dbPath: string, filePath: string): FileAnalysisEntry[];
+export declare function getAnalysisByHash(dbPath: string, hash: string): FunctionAnalysis | null;
+export declare function gcAnalysis(dbPath: string, maxAgeDays?: number): {
+    deleted: number;
+};
+export declare function refreshFileIndex(rootPath: string, onProgress?: (current: number, total: number, file: string) => void): Promise<void>;
+/**
+ * Find content hashes that are referenced in file_functions but have no
+ * analysis in function_analysis. Used by CLI to know what to pull from Supabase
+ * before running expensive Claude analysis.
+ */
+export declare function findMissingHashes(dbPath: string): string[];
+/**
+ * Import analysis rows pulled from Supabase into the local SQLite database.
+ * Used by CLI pull sync to cache remote analysis locally.
+ */
+export declare function importAnalysis(dbPath: string, rows: {
+    content_hash: string;
+    analysis_type: string;
+    analysis: string;
+    model_version: string;
+    schema_version: number;
+    language: string;
+    entity_type: string;
+}[]): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}