@ophan/core 0.0.1 → 0.0.3

package/README.md

@@ -1,107 +1,70 @@
 # @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
+The analysis engine behind [Ophan](https://ophan.dev) — AI-powered security analysis and documentation for codebases.
+
+This package provides the core analysis pipeline: source code parsing, function extraction, Claude-powered security analysis, and local SQLite storage. Used by [`@ophan/cli`](https://www.npmjs.com/package/@ophan/cli) and the [Ophan VS Code extension](https://marketplace.visualstudio.com/items?itemName=ophan.ophan).
+
+## What It Does
+
+- **Parses source code** using language-native ASTs (TypeScript compiler API, Python's `ast` module)
+- **Extracts functions** and computes SHA256 content hashes for change detection
+- **Analyzes with Claude** to detect security vulnerabilities and generate documentation
+- **Stores results** in a local SQLite database, keyed by content hash
 
 ### 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[];
-}
-```
+Identifies vulnerabilities including SQL injection, XSS, hardcoded secrets, path traversal, insecure deserialization, and unsanitized user input.
+
+### Data Flow Classification
+
+Tags functions by the data they handle: user input, PII, credentials, database operations, external APIs, file system access, and more.
+
+### Auto-Documentation
+
+Generates plain-English descriptions, parameter documentation, and return type documentation for every function.
 
-**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.
+## Supported Languages
 
-**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
+| Language | Parser | Extensions |
+|----------|--------|------------|
+| TypeScript | TypeScript compiler API | `.ts`, `.tsx` |
+| JavaScript | TypeScript compiler API | `.js`, `.jsx` |
+| Python | Python `ast` module | `.py` |
 
-**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.
+## Usage
 
-### Schema Fields
+Most users should use [`@ophan/cli`](https://www.npmjs.com/package/@ophan/cli) or the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ophan.ophan) instead of importing this package directly.
 
-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.
+`@ophan/core` is published for tools that need to build on the Ophan analysis pipeline programmatically.
+
+```typescript
+import { analyzeRepository, initDb } from '@ophan/core';
+
+const db = initDb('/path/to/repo');
+await analyzeRepository(db, '/path/to/repo', {
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+```
+
+### Schemas
+
+Zod schemas and TypeScript types for Ophan's analysis data are available as a lightweight subpath import — no native dependencies required:
+
+```typescript
+import {
+  ClaudeAnalysisResponse,
+  SECURITY_FLAG_LABELS,
+  DATA_TAG_LABELS,
+} from '@ophan/core/schemas';
+```
 
-### Migration Safety
+## Resources
 
-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.
+- [Documentation](https://docs.ophan.dev)
+- [CLI Package](https://www.npmjs.com/package/@ophan/cli)
+- [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=ophan.ophan)
+- [GitHub](https://github.com/nicholasgriffintn/ophan)
 
-## Extensibility
+## License
 
-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
+MIT

package/dist/community-detectors/index.d.ts

@@ -0,0 +1,20 @@
+export type { CommunityDetector, RawDetectionResult, DetectorOptions } from "./types";
+export { LouvainDetector } from "./louvain";
+export { LabelPropDetector } from "./label-prop";
+export { LeidenDetector } from "./leiden";
+import type { CommunityDetector } from "./types";
+/**
+ * Register a community detection algorithm.
+ * Call before detectCommunities() to make the algorithm available via GraphConfig.algorithm.
+ */
+export declare function registerDetector(detector: CommunityDetector): void;
+/**
+ * Get a registered detector by name.
+ * Throws if the algorithm is not registered.
+ */
+export declare function getDetector(name: string): CommunityDetector;
+/**
+ * List all registered detector names.
+ */
+export declare function listDetectors(): string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/community-detectors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/community-detectors/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAOjD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAElE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAO3D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAExC"}

package/dist/community-detectors/index.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LeidenDetector = exports.LabelPropDetector = exports.LouvainDetector = void 0;
+exports.registerDetector = registerDetector;
+exports.getDetector = getDetector;
+exports.listDetectors = listDetectors;
+var louvain_1 = require("./louvain");
+Object.defineProperty(exports, "LouvainDetector", { enumerable: true, get: function () { return louvain_1.LouvainDetector; } });
+var label_prop_1 = require("./label-prop");
+Object.defineProperty(exports, "LabelPropDetector", { enumerable: true, get: function () { return label_prop_1.LabelPropDetector; } });
+var leiden_1 = require("./leiden");
+Object.defineProperty(exports, "LeidenDetector", { enumerable: true, get: function () { return leiden_1.LeidenDetector; } });
+const louvain_2 = require("./louvain");
+const label_prop_2 = require("./label-prop");
+const leiden_2 = require("./leiden");
+const registry = new Map();
+/**
+ * Register a community detection algorithm.
+ * Call before detectCommunities() to make the algorithm available via GraphConfig.algorithm.
+ */
+function registerDetector(detector) {
+    registry.set(detector.name, detector);
+}
+/**
+ * Get a registered detector by name.
+ * Throws if the algorithm is not registered.
+ */
+function getDetector(name) {
+    const detector = registry.get(name);
+    if (!detector) {
+        const available = [...registry.keys()].join(", ");
+        throw new Error(`Unknown community detection algorithm: "${name}". Available: ${available}`);
+    }
+    return detector;
+}
+/**
+ * List all registered detector names.
+ */
+function listDetectors() {
+    return [...registry.keys()];
+}
+// Register built-in detectors
+registerDetector(new louvain_2.LouvainDetector());
+registerDetector(new label_prop_2.LabelPropDetector());
+registerDetector(new leiden_2.LeidenDetector());

package/dist/community-detectors/label-prop.d.ts

@@ -0,0 +1,20 @@
+import type Graph from "graphology";
+import type { CommunityDetector, DetectorOptions, RawDetectionResult } from "./types";
+/**
+ * Label Propagation Algorithm (LPA) for community detection.
+ *
+ * Each node starts with a unique label. On each iteration, every node adopts
+ * the label with the highest total edge weight among its neighbors. Ties are
+ * broken randomly. Converges when no node changes its label.
+ *
+ * Pros: fast, no resolution parameter needed, finds natural cluster boundaries
+ * Cons: non-deterministic, may produce different results on each run
+ */
+export declare class LabelPropDetector implements CommunityDetector {
+    readonly name = "label-propagation";
+    readonly supportsResolution = false;
+    private maxIterations;
+    constructor(maxIterations?: number);
+    detect(graph: Graph, options: DetectorOptions): RawDetectionResult;
+}
+//# sourceMappingURL=label-prop.d.ts.map

package/dist/community-detectors/label-prop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-prop.d.ts","sourceRoot":"","sources":["../../src/community-detectors/label-prop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAEtF;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,YAAW,iBAAiB;IACzD,QAAQ,CAAC,IAAI,uBAAuB;IACpC,QAAQ,CAAC,kBAAkB,SAAS;IAEpC,OAAO,CAAC,aAAa,CAAS;gBAElB,aAAa,SAAM;IAI/B,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,GAAG,kBAAkB;CA8DnE"}

package/dist/community-detectors/label-prop.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LabelPropDetector = void 0;
+/**
+ * Label Propagation Algorithm (LPA) for community detection.
+ *
+ * Each node starts with a unique label. On each iteration, every node adopts
+ * the label with the highest total edge weight among its neighbors. Ties are
+ * broken randomly. Converges when no node changes its label.
+ *
+ * Pros: fast, no resolution parameter needed, finds natural cluster boundaries
+ * Cons: non-deterministic, may produce different results on each run
+ */
+class LabelPropDetector {
+    constructor(maxIterations = 100) {
+        this.name = "label-propagation";
+        this.supportsResolution = false;
+        this.maxIterations = maxIterations;
+    }
+    detect(graph, options) {
+        // Initialize: each node gets a unique label
+        const labels = new Map();
+        let nextLabel = 0;
+        graph.forEachNode((node) => {
+            labels.set(node, nextLabel++);
+        });
+        const nodes = graph.nodes();
+        for (let iter = 0; iter < this.maxIterations; iter++) {
+            let changed = false;
+            // Shuffle nodes for random processing order (reduces bias)
+            for (let i = nodes.length - 1; i > 0; i--) {
+                const j = Math.floor(Math.random() * (i + 1));
+                [nodes[i], nodes[j]] = [nodes[j], nodes[i]];
+            }
+            for (const node of nodes) {
+                // Sum weights per neighboring label
+                const labelWeights = new Map();
+                graph.forEachEdge(node, (_edge, attrs, source, target) => {
+                    const neighbor = source === node ? target : source;
+                    const neighborLabel = labels.get(neighbor);
+                    const weight = attrs[options.weightAttribute] || 1.0;
+                    labelWeights.set(neighborLabel, (labelWeights.get(neighborLabel) || 0) + weight);
+                });
+                if (labelWeights.size === 0)
+                    continue;
+                // Find label(s) with maximum weight
+                let maxWeight = -Infinity;
+                const candidates = [];
+                for (const [label, weight] of labelWeights) {
+                    if (weight > maxWeight) {
+                        maxWeight = weight;
+                        candidates.length = 0;
+                        candidates.push(label);
+                    }
+                    else if (weight === maxWeight) {
+                        candidates.push(label);
+                    }
+                }
+                // Break ties randomly
+                const chosen = candidates[Math.floor(Math.random() * candidates.length)];
+                if (chosen !== labels.get(node)) {
+                    labels.set(node, chosen);
+                    changed = true;
+                }
+            }
+            if (!changed)
+                break;
+        }
+        // Convert to Record<string, number>
+        const communities = {};
+        for (const [node, label] of labels) {
+            communities[node] = label;
+        }
+        return { communities, modularity: null };
+    }
+}
+exports.LabelPropDetector = LabelPropDetector;

package/dist/community-detectors/leiden.d.ts

@@ -0,0 +1,22 @@
+import type Graph from "graphology";
+import type { CommunityDetector, DetectorOptions, RawDetectionResult } from "./types";
+/**
+ * Leiden community detection algorithm (Traag, van Eck & Waltman, 2019).
+ *
+ * Improvement over Louvain with three phases per iteration:
+ *   1. Local moving: nodes move to neighboring community maximizing modularity gain
+ *   2. Refinement: ensures each community is internally connected by re-examining
+ *      sub-structure within communities (the key Leiden innovation)
+ *   3. Aggregation: create super-graph where communities become nodes
+ *
+ * Guarantees communities are well-connected (no disconnected subgroups within a community).
+ * Uses modularity quality function: Q = Σ_c [e_c/m - γ(n_c/2m)²]
+ *
+ * Reference: https://arxiv.org/abs/1810.08473
+ */
+export declare class LeidenDetector implements CommunityDetector {
+    readonly name = "leiden";
+    readonly supportsResolution = true;
+    detect(graph: Graph, options: DetectorOptions): RawDetectionResult;
+}
+//# sourceMappingURL=leiden.d.ts.map

package/dist/community-detectors/leiden.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leiden.d.ts","sourceRoot":"","sources":["../../src/community-detectors/leiden.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,YAAW,iBAAiB;IACtD,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,kBAAkB,QAAQ;IAEnC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,GAAG,kBAAkB;CAqEnE"}