@amrishkhan05/frankly 0.1.0

package/src/git/repository.ts

@@ -0,0 +1,207 @@
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { GitError, RepositoryError } from "../core/errors.js";
+import type { ChangeType } from "../core/models.js";
+
+export interface DiffHunk {
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    content: string;
+}
+
+export interface FileDiff {
+    path: string;
+    status: ChangeType;
+    hunks: DiffHunk[];
+    oldPath?: string;
+}
+
+export class Repository {
+    constructor(private readonly rootPath: string) {
+        try {
+            this.git(["rev-parse", "--git-dir"]);
+        } catch {
+            throw new RepositoryError("Not a git repository", { path: rootPath });
+        }
+    }
+
+    private git(args: string[], allowFailure = false): string {
+        try {
+            return execFileSync("git", args, {
+                cwd: this.rootPath,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", allowFailure ? "ignore" : "pipe"],
+            }).trimEnd();
+        } catch (error) {
+            if (allowFailure) return "";
+            throw new GitError(`Git command failed: git ${args.join(" ")}`, { args, error: String(error) });
+        }
+    }
+
+    getRootPath(): string {
+        return this.rootPath;
+    }
+
+  async getWorkingTreeDiff(): Promise<FileDiff[]> {
+    if (!this.hasHead()) return this.getInitialTreeDiff();
+    const tracked = this.git(["diff", "HEAD", "--no-color", "--no-ext-diff", "--find-renames"]);
+        const files = this.parseDiff(tracked);
+        const known = new Set(files.map((file) => file.path));
+
+        for (const filePath of this.getStatus().untracked) {
+            if (known.has(filePath)) continue;
+            const fullPath = path.join(this.rootPath, filePath);
+            if (!fs.statSync(fullPath).isFile()) continue;
+      const content = fs.readFileSync(fullPath, "utf8");
+      const lines = lineCount(content);
+      files.push({
+        path: filePath,
+        status: "added",
+        hunks: [{ oldStart: 0, oldLines: 0, newStart: 1, newLines: lines, content: addedContent(content) }],
+            });
+        }
+
+        return files;
+    }
+
+    async getDiffBetween(base: string, head: string): Promise<FileDiff[]> {
+        return this.parseDiff(this.git(["diff", "--no-color", "--no-ext-diff", "--find-renames", base, head]));
+    }
+
+    async getStagedDiff(): Promise<FileDiff[]> {
+        return this.parseDiff(this.git(["diff", "--staged", "--no-color", "--no-ext-diff", "--find-renames"]));
+    }
+
+    fileExists(filePath: string): boolean {
+        return this.git(["ls-files", "--error-unmatch", "--", filePath], true) !== "";
+    }
+
+    async getFileContent(filePath: string, revision = "HEAD"): Promise<string> {
+        const value = this.git(["show", `${revision}:${filePath}`], true);
+        if (!value && !this.hasHead()) throw new GitError(`Revision ${revision} does not exist`);
+        return value;
+    }
+
+    getCurrentBranch(): string {
+        return this.git(["rev-parse", "--abbrev-ref", "HEAD"], true) || "HEAD";
+    }
+
+    getStatus(): { modified: string[]; staged: string[]; untracked: string[] } {
+        const modified: string[] = [];
+        const staged: string[] = [];
+        const untracked: string[] = [];
+        for (const line of this.git(["status", "--porcelain=v1", "-z"]).split("\0")) {
+            if (!line) continue;
+            const codes = line.slice(0, 2);
+            const filePath = line.slice(3);
+            if (codes === "??") untracked.push(filePath);
+            else {
+                if (codes[0] !== " ") staged.push(filePath);
+                if (codes[1] !== " ") modified.push(filePath);
+            }
+        }
+        return { modified, staged, untracked };
+    }
+
+    async getBlame(filePath: string, line: number): Promise<{ commit: string; author: string } | null> {
+        const value = this.git(["blame", "-L", `${line},${line}`, "--porcelain", "--", filePath], true);
+        if (!value) return null;
+        const rows = value.split("\n");
+        return {
+            commit: rows[0].split(" ")[0],
+            author: rows.find((row) => row.startsWith("author "))?.slice(7) || "unknown",
+        };
+    }
+
+  private hasHead(): boolean {
+        return this.git(["rev-parse", "--verify", "HEAD"], true) !== "";
+  }
+
+  private getInitialTreeDiff(): FileDiff[] {
+    return this.git(["ls-files", "--cached", "--others", "--exclude-standard", "-z"]).split("\0").flatMap((filePath): FileDiff[] => {
+      if (!filePath) return [];
+      const fullPath = path.join(this.rootPath, filePath);
+      if (!fs.existsSync(fullPath) || !fs.statSync(fullPath).isFile()) return [];
+      const content = fs.readFileSync(fullPath, "utf8");
+      return [{
+        path: filePath,
+        status: "added",
+        hunks: [{ oldStart: 0, oldLines: 0, newStart: 1, newLines: lineCount(content), content: addedContent(content) }],
+      }];
+    });
+  }
+
+    private parseDiff(diff: string): FileDiff[] {
+        const files: FileDiff[] = [];
+        let current: FileDiff | undefined;
+        let hunk: DiffHunk | undefined;
+
+        const flushHunk = () => {
+            if (current && hunk) current.hunks.push(hunk);
+            hunk = undefined;
+        };
+        const flushFile = () => {
+            flushHunk();
+            if (current) files.push(current);
+            current = undefined;
+        };
+
+        for (const line of diff.split("\n")) {
+            if (line.startsWith("diff --git ")) {
+                flushFile();
+                const match = line.match(/^diff --git a\/(.+) b\/(.+)$/);
+                current = { path: match?.[2] || "", oldPath: match?.[1], status: "modified", hunks: [] };
+            } else if (line.startsWith("new file mode")) {
+                if (current) current.status = "added";
+            } else if (line.startsWith("deleted file mode")) {
+                if (current) current.status = "deleted";
+            } else if (line.startsWith("rename from ")) {
+                if (current) {
+                    current.status = "renamed";
+                    current.oldPath = line.slice(12);
+                }
+            } else if (line.startsWith("rename to ")) {
+                if (current) current.path = line.slice(10);
+            } else if (line.startsWith("@@")) {
+                flushHunk();
+                const match = line.match(/@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
+                if (match) hunk = {
+                    oldStart: Number(match[1]),
+                    oldLines: Number(match[2] ?? 1),
+                    newStart: Number(match[3]),
+                    newLines: Number(match[4] ?? 1),
+                    content: "",
+                };
+            } else if (hunk && (/^[+\- ]/.test(line) || line.startsWith("\\ No newline"))) {
+                hunk.content += `${line}\n`;
+            }
+        }
+        flushFile();
+        return files;
+    }
+}
+
+export function countDiffLines(file: FileDiff): { additions: number; deletions: number } {
+  const lines = file.hunks.flatMap((hunk) => hunk.content.split("\n"));
+  return {
+    additions: lines.filter((line) => line.startsWith("+") && !line.startsWith("+++")).length,
+    deletions: lines.filter((line) => line.startsWith("-") && !line.startsWith("---")).length,
+  };
+}
+
+function lineCount(content: string): number {
+  return content === "" ? 0 : content.split("\n").length - (content.endsWith("\n") ? 1 : 0);
+}
+
+function addedContent(content: string): string {
+  if (!content) return "";
+  const body = content.endsWith("\n") ? content.slice(0, -1) : content;
+  return body.split("\n").map((line) => `+${line}`).join("\n");
+}
+
+export async function createRepository(rootPath: string): Promise<Repository> {
+    return new Repository(rootPath);
+}

package/src/graph/symbols.ts

@@ -0,0 +1,254 @@
+/**
+ * Symbol extraction from TypeScript/JavaScript code
+ * Uses TypeScript Compiler API for semantic analysis
+ */
+
+import * as ts from "typescript";
+import * as fs from "fs";
+import * as path from "path";
+import type { ChangedSymbol, SymbolType, Visibility } from "../core/models.js";
+import { SemanticError } from "../core/errors.js";
+
+export interface ExtractedSymbol {
+    name: string;
+    type: SymbolType;
+    visibility: Visibility;
+    isExported: boolean;
+    line: number;
+    column: number;
+    lineRange: [number, number];
+}
+
+export class SymbolExtractor {
+    private compilerOptions: ts.CompilerOptions;
+    private rootPath: string;
+
+    constructor(rootPath: string, tsConfigPath?: string) {
+        this.rootPath = rootPath;
+        this.compilerOptions = this.loadCompilerOptions(tsConfigPath);
+    }
+
+    /**
+     * Load TypeScript compiler options
+     */
+    private loadCompilerOptions(tsConfigPath?: string): ts.CompilerOptions {
+        let configPath = tsConfigPath || path.join(this.rootPath, "tsconfig.json");
+
+        if (!fs.existsSync(configPath)) {
+            // Use default options
+            return {
+                target: ts.ScriptTarget.ES2020,
+                module: ts.ModuleKind.ESNext,
+                lib: ["es2020"],
+                strict: true,
+                moduleResolution: ts.ModuleResolutionKind.Bundler,
+            };
+        }
+
+        try {
+            const configFile = ts.readConfigFile(configPath, (p) => fs.readFileSync(p, "utf-8"));
+            const config = ts.parseJsonConfigFileContent(
+                configFile.config,
+                ts.sys,
+                path.dirname(configPath),
+            );
+            return config.options;
+        } catch (error) {
+            throw new SemanticError("Failed to load TypeScript config", { error, path: configPath });
+        }
+    }
+
+    /**
+     * Extract symbols from a file
+     */
+    extractSymbols(filePath: string): ExtractedSymbol[] {
+        try {
+            const sourceText = fs.readFileSync(filePath, "utf-8");
+            const sourceFile = ts.createSourceFile(
+                filePath,
+                sourceText,
+                this.compilerOptions.target || ts.ScriptTarget.ES2020,
+                true,
+            );
+
+            const symbols: ExtractedSymbol[] = [];
+            this.visitNode(sourceFile, symbols, sourceText);
+            return symbols;
+        } catch (error) {
+            throw new SemanticError("Failed to extract symbols", { error, filePath });
+        }
+    }
+
+    /**
+     * Recursively visit AST nodes
+     */
+    private visitNode(node: ts.Node, symbols: ExtractedSymbol[], sourceText: string): void {
+        // Function declarations
+        if (ts.isFunctionDeclaration(node)) {
+            const name = node.name?.text || "anonymous";
+            const isExported = this.isExported(node);
+            const lineRange = this.getLineRange(node, sourceText);
+            const line = ts.getLineAndCharacterOfPosition(node.getSourceFile(), node.getStart()).line;
+
+            symbols.push({
+                name,
+                type: "function",
+                visibility: this.getVisibility(node),
+                isExported,
+                line,
+                column: ts.getLineAndCharacterOfPosition(node.getSourceFile(), node.getStart()).character,
+                lineRange,
+            });
+        }
+
+        // Class declarations
+        if (ts.isClassDeclaration(node)) {
+            const name = node.name?.text || "anonymous";
+            const isExported = this.isExported(node);
+            const lineRange = this.getLineRange(node, sourceText);
+            const line = ts.getLineAndCharacterOfPosition(node.getSourceFile(), node.getStart()).line;
+
+            symbols.push({
+                name,
+                type: "class",
+                visibility: this.getVisibility(node),
+                isExported,
+                line,
+                column: ts.getLineAndCharacterOfPosition(node.getSourceFile(), node.getStart()).character,
+                lineRange,
+            });
+
+            // Extract class methods
+            for (const member of node.members) {
+                if (ts.isMethodDeclaration(member)) {
+                    const methodName = member.name?.getText() || "anonymous";
+                    const memberLineRange = this.getLineRange(member, sourceText);
+                    const memberLine = ts.getLineAndCharacterOfPosition(
+                        node.getSourceFile(),
+                        member.getStart(),
+                    ).line;
+
+                    symbols.push({
+                        name: `${name}.${methodName}`,
+                        type: "method",
+                        visibility: this.getVisibility(member),
+                        isExported: false,
+                        line: memberLine,
+                        column: ts.getLineAndCharacterOfPosition(node.getSourceFile(), member.getStart())
+                            .character,
+                        lineRange: memberLineRange,
+                    });
+                }
+            }
+        }
+
+        // Interface declarations
+        if (ts.isInterfaceDeclaration(node)) {
+            const name = node.name?.text || "anonymous";
+            const isExported = this.isExported(node);
+            const lineRange = this.getLineRange(node, sourceText);
+            const line = ts.getLineAndCharacterOfPosition(node.getSourceFile(), node.getStart()).line;
+
+            symbols.push({
+                name,
+                type: "interface",
+                visibility: this.getVisibility(node),
+                isExported,
+                line,
+                column: ts.getLineAndCharacterOfPosition(node.getSourceFile(), node.getStart()).character,
+                lineRange,
+            });
+        }
+
+        // Type aliases
+        if (ts.isTypeAliasDeclaration(node)) {
+            const name = node.name?.text || "anonymous";
+            const isExported = this.isExported(node);
+            const lineRange = this.getLineRange(node, sourceText);
+            const line = ts.getLineAndCharacterOfPosition(node.getSourceFile(), node.getStart()).line;
+
+            symbols.push({
+                name,
+                type: "type",
+                visibility: this.getVisibility(node),
+                isExported,
+                line,
+                column: ts.getLineAndCharacterOfPosition(node.getSourceFile(), node.getStart()).character,
+                lineRange,
+            });
+        }
+
+        // Variable declarations
+        if (ts.isVariableStatement(node)) {
+            for (const decl of node.declarationList.declarations) {
+                const name = decl.name.getText();
+                const isExported = this.isExported(node);
+                const lineRange = this.getLineRange(decl, sourceText);
+                const line = ts.getLineAndCharacterOfPosition(node.getSourceFile(), decl.getStart()).line;
+
+                symbols.push({
+                    name,
+                    type: decl.initializer ? "variable" : "constant",
+                    visibility: this.getVisibility(node),
+                    isExported,
+                    line,
+                    column: ts.getLineAndCharacterOfPosition(node.getSourceFile(), decl.getStart()).character,
+                    lineRange,
+                });
+            }
+        }
+
+        // Export declarations
+        if (ts.isExportDeclaration(node)) {
+            symbols.push({
+                name: "export",
+                type: "export",
+                visibility: "public",
+                isExported: true,
+                line: ts.getLineAndCharacterOfPosition(node.getSourceFile(), node.getStart()).line,
+                column: ts.getLineAndCharacterOfPosition(node.getSourceFile(), node.getStart()).character,
+                lineRange: this.getLineRange(node, sourceText),
+            });
+        }
+
+        ts.forEachChild(node, (child) => this.visitNode(child, symbols, sourceText));
+    }
+
+    /**
+     * Check if node is exported
+     */
+    private isExported(node: ts.Node): boolean {
+        const flags = ts.getCombinedModifierFlags(node as ts.Declaration);
+        return (flags & ts.ModifierFlags.Export) !== 0;
+    }
+
+    /**
+     * Get visibility level
+     */
+    private getVisibility(node: ts.Node): Visibility {
+        const flags = ts.getCombinedModifierFlags(node as ts.Declaration);
+
+        if (flags & ts.ModifierFlags.Private) return "private";
+        if (flags & ts.ModifierFlags.Protected) return "protected";
+        if (flags & ts.ModifierFlags.Public) return "public";
+
+        return "internal";
+    }
+
+    /**
+     * Get line range of a node
+     */
+    private getLineRange(node: ts.Node, sourceText: string): [number, number] {
+        const sourceFile = node.getSourceFile();
+        const start = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line;
+        const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd()).line;
+        return [start + 1, end + 1]; // Convert to 1-based
+    }
+}
+
+export function createSymbolExtractor(
+    rootPath: string,
+    tsConfigPath?: string,
+): SymbolExtractor {
+    return new SymbolExtractor(rootPath, tsConfigPath);
+}

package/src/integrations/claude/checkpoint.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from "node:fs";
+import { loadRepositoryConfig } from "../../core/config.js";
+import { createAnalysisEngine } from "../../core/engine.js";
+
+interface StopHookInput {
+    cwd?: string;
+    last_assistant_message?: string;
+    stop_hook_active?: boolean;
+}
+
+async function main(): Promise<void> {
+    const input = JSON.parse(readFileSync(0, "utf8")) as StopHookInput;
+    if (input.stop_hook_active) return;
+
+    const root = input.cwd || process.cwd();
+    const config = loadRepositoryConfig(root);
+    if (config.trigger !== "checkpoint" || config.intensity === "off") return;
+
+    const task = input.last_assistant_message || "Review current changes";
+    const result = await (await createAnalysisEngine(root)).analyze(task);
+    if (result.review.verdict === "CLEAN") return;
+
+    const findings = result.review.findings
+        .slice(0, 5)
+        .map((finding) => `- ${finding.title}: ${finding.description}`)
+        .join("\n");
+    const message = `Frankly Red Ink Review\n${result.review.recommendation}\n${findings}`;
+    process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "Stop",
+            additionalContext: message,
+        },
+    }));
+}
+
+main().catch((error) => {
+    process.stdout.write(JSON.stringify({
+        systemMessage: `Frankly checkpoint skipped: ${error instanceof Error ? error.message : String(error)}`,
+    }));
+});

package/src/integrations/cli/demo.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createAnalysisEngine } from "../../core/engine.js";
+import { createReportFormatter } from "../../report/json.js";
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), "frankly-demo-"));
+const fixtureRoot = fileURLToPath(new URL("../../../fixtures/retry-429", import.meta.url));
+try {
+    copyFixture("baseline");
+    git(["init", "-q"]);
+    git(["config", "user.email", "demo@frankly.local"]);
+    git(["config", "user.name", "Frankly Demo"]);
+    git(["add", "."]);
+    git(["commit", "-qm", "baseline"]);
+
+    copyFixture("candidate");
+
+    const result = await (await createAnalysisEngine(root)).analyze("Retry HTTP 429 responses");
+    console.log(createReportFormatter().formatAsTerminal(result));
+} finally {
+    fs.rmSync(root, { recursive: true, force: true });
+}
+
+function copyFixture(name: "baseline" | "candidate"): void {
+    fs.cpSync(path.join(fixtureRoot, name), root, { recursive: true });
+}
+
+function git(args: string[]): void {
+    execFileSync("git", args, { cwd: root });
+}