@amrishkhan05/frankly 0.1.0

package/src/project/detector.ts

@@ -0,0 +1,242 @@
+/**
+ * Project detection and analysis
+ * Identifies TypeScript/JavaScript projects, workspaces, and configuration
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { ProjectError } from "../core/errors.js";
+
+export type PackageManager = "npm" | "pnpm" | "yarn";
+
+export interface Project {
+    root: string;
+    type: "typescript" | "javascript";
+    packageManager: PackageManager;
+    isWorkspace: boolean;
+    workspaceRoot?: string;
+    packages?: string[];
+    hasTsConfig: boolean;
+    testRunner?: "jest" | "vitest" | "nx";
+}
+
+export class ProjectDetector {
+    private rootPath: string;
+    private cache: Map<string, unknown> = new Map();
+
+    constructor(rootPath: string) {
+        this.rootPath = rootPath;
+    }
+
+    /**
+     * Detect project configuration
+     */
+    async detectProject(): Promise<Project> {
+        const cacheKey = "project";
+        if (this.cache.has(cacheKey)) {
+            return this.cache.get(cacheKey) as Project;
+        }
+
+        const packageJson = this.readPackageJson(this.rootPath);
+        if (!packageJson) {
+            throw new ProjectError("No package.json found", { path: this.rootPath });
+        }
+
+        const project: Project = {
+            root: this.rootPath,
+            type: this.detectLanguageType(),
+            packageManager: this.detectPackageManager(),
+            isWorkspace: this.isWorkspace(packageJson),
+            hasTsConfig: this.hasTsConfig(this.rootPath),
+            testRunner: this.detectTestRunner(packageJson),
+        };
+
+        if (project.isWorkspace) {
+            project.workspaceRoot = this.rootPath;
+            project.packages = this.detectWorkspacePackages(packageJson);
+        }
+
+        this.cache.set(cacheKey, project);
+        return project;
+    }
+
+    /**
+     * Detect language type from tsconfig or file extensions
+     */
+    private detectLanguageType(): "typescript" | "javascript" {
+        if (this.hasTsConfig(this.rootPath)) {
+            return "typescript";
+        }
+        // Check for .ts files
+        return this.hasTypeScriptFiles(this.rootPath) ? "typescript" : "javascript";
+    }
+
+    /**
+     * Check if tsconfig.json exists
+     */
+    private hasTsConfig(dir: string): boolean {
+        return fs.existsSync(path.join(dir, "tsconfig.json"));
+    }
+
+    /**
+     * Check for TypeScript files
+     */
+    private hasTypeScriptFiles(dir: string, depth = 2): boolean {
+        if (depth <= 0) return false;
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+                if (entry.isFile() && entry.name.endsWith(".ts")) return true;
+                if (entry.isDirectory() && this.hasTypeScriptFiles(path.join(dir, entry.name), depth - 1)) {
+                    return true;
+                }
+            }
+        } catch {
+            // Ignore errors
+        }
+        return false;
+    }
+
+    /**
+     * Detect package manager from lock files
+     */
+    private detectPackageManager(): PackageManager {
+        if (fs.existsSync(path.join(this.rootPath, "pnpm-lock.yaml"))) return "pnpm";
+        if (fs.existsSync(path.join(this.rootPath, "yarn.lock"))) return "yarn";
+        return "npm";
+    }
+
+    /**
+     * Check if project is a workspace
+     */
+    private isWorkspace(packageJson: Record<string, unknown>): boolean {
+        return (
+            Array.isArray(packageJson.workspaces) || typeof packageJson.workspaces === "object"
+        );
+    }
+
+    /**
+     * Detect workspace packages
+     */
+    private detectWorkspacePackages(packageJson: Record<string, unknown>): string[] {
+        const workspaces = packageJson.workspaces;
+        if (!workspaces) return [];
+
+        let patterns: string[] = [];
+        if (Array.isArray(workspaces)) {
+            patterns = workspaces as string[];
+        } else if (typeof workspaces === "object" && workspaces !== null) {
+            const w = workspaces as Record<string, unknown>;
+            if (Array.isArray(w.packages)) {
+                patterns = w.packages as string[];
+            }
+        }
+
+        // Resolve glob patterns to actual packages
+        const packages: string[] = [];
+        for (const pattern of patterns) {
+            const resolved = this.resolveGlobPattern(pattern);
+            packages.push(...resolved);
+        }
+
+        return packages;
+    }
+
+    /**
+     * Resolve glob pattern to actual directories
+     */
+    private resolveGlobPattern(pattern: string): string[] {
+        const result: string[] = [];
+        if (!pattern.includes("*")) {
+            const fullPath = path.join(this.rootPath, pattern);
+            if (fs.existsSync(fullPath)) {
+                result.push(pattern);
+            }
+            return result;
+        }
+
+        // Simple glob resolution
+        const parts = pattern.split("/");
+        const basePart = parts[0];
+
+        if (basePart.includes("*")) {
+            const basePattern = basePart.replace("*", "");
+            try {
+                const entries = fs.readdirSync(this.rootPath);
+                for (const entry of entries) {
+                    if (entry.startsWith(basePattern)) {
+                        const fullPath = path.join(this.rootPath, entry);
+                        if (fs.statSync(fullPath).isDirectory()) {
+                            result.push(entry);
+                        }
+                    }
+                }
+            } catch {
+                // Ignore errors
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Detect test runner from package.json
+     */
+    private detectTestRunner(packageJson: Record<string, unknown>): "jest" | "vitest" | "nx" | undefined {
+        const deps = {
+            ...((packageJson.dependencies as Record<string, unknown>) || {}),
+            ...((packageJson.devDependencies as Record<string, unknown>) || {}),
+        };
+
+        if ("nx" in deps) return "nx";
+        if ("vitest" in deps) return "vitest";
+        if ("jest" in deps) return "jest";
+        return undefined;
+    }
+
+    /**
+     * Read package.json from directory
+     */
+    private readPackageJson(dir: string): Record<string, unknown> | null {
+        const packageJsonPath = path.join(dir, "package.json");
+        try {
+            const content = fs.readFileSync(packageJsonPath, "utf-8");
+            return JSON.parse(content) as Record<string, unknown>;
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * Find package.json for a given file path
+     */
+    findPackageJsonForFile(filePath: string): string | null {
+        let dir = path.dirname(filePath);
+        while (dir !== path.dirname(dir)) {
+            const packageJsonPath = path.join(dir, "package.json");
+            if (fs.existsSync(packageJsonPath)) {
+                return packageJsonPath;
+            }
+            dir = path.dirname(dir);
+        }
+        return null;
+    }
+
+    /**
+     * Read tsconfig.json
+     */
+    readTsConfig(dir: string = this.rootPath): Record<string, unknown> | null {
+        const tsConfigPath = path.join(dir, "tsconfig.json");
+        try {
+            const content = fs.readFileSync(tsConfigPath, "utf-8");
+            return JSON.parse(content) as Record<string, unknown>;
+        } catch {
+            return null;
+        }
+    }
+}
+
+export async function createProjectDetector(rootPath: string): Promise<ProjectDetector> {
+    return new ProjectDetector(rootPath);
+}

package/src/report/json.ts

@@ -0,0 +1,175 @@
+/**
+ * Report formatting
+ * Outputs analysis results in various formats
+ */
+
+import type { AnalysisResult, RedInkReview, Finding } from "../core/models.js";
+
+export class ReportFormatter {
+    /**
+     * Format as JSON
+     */
+    formatAsJson(result: AnalysisResult): string {
+        return JSON.stringify(result, null, 2);
+    }
+
+    /**
+     * Format as compact terminal output
+     */
+    formatAsTerminal(result: AnalysisResult): string {
+        const lines: string[] = [];
+
+        lines.push("FRANKLY · RED INK REVIEW\n");
+
+        // Task
+        lines.push(`Task\n${result.task}\n`);
+
+        // Verdict
+        const review = result.review;
+        lines.push(`CHANGE VERDICT\n${review.verdict}\n`);
+
+        // Metrics
+        lines.push(`TASK ALIGNMENT\n${review.taskAlignment}\n`);
+        lines.push(`CHANGE NECESSITY\n${review.changeNecessity}/100\n`);
+        lines.push(`CHANGE SURFACE\n${review.changeSurface}\n`);
+    lines.push(`SCOPE DRIFT\n${Math.round(review.scopeDrift * 100)}%\n`);
+    lines.push(`MINIMUM PATCH\n${result.files.length} file(s), ${result.symbols.length} changed symbol(s)\n`);
+
+        // Red marks
+        if (review.findings.length > 0) {
+            lines.push("RED MARKS\n");
+            for (const finding of review.findings) {
+                const icon = finding.severity === "error" ? "✗" : "⚠";
+                lines.push(`${icon} ${finding.title}`);
+            }
+            lines.push("");
+        }
+
+        // Blast radius
+        lines.push("BLAST RADIUS\n");
+        lines.push(`Direct callers       ${review.blastRadius.directCallers}`);
+        lines.push(`Transitive callers   ${review.blastRadius.transitiveCallers}`);
+        lines.push(`Packages             ${review.blastRadius.affectedPackages}\n`);
+
+        // Test impact
+        lines.push("TEST IMPACT\n");
+        lines.push(`Likely affected      ${review.testImpact.likelyAffected}`);
+        lines.push(`Possibly affected    ${review.testImpact.possiblyAffected}`);
+        lines.push(`Executed             ${review.testImpact.executed}`);
+    lines.push(`Passed               ${review.testImpact.passed}\n`);
+    for (const test of review.testImpact.predicted.slice(0, 10)) {
+      lines.push(`  ${test.status.padEnd(19)} ${test.path}`);
+    }
+    if (review.testImpact.predicted.length) lines.push("");
+
+    if (review.contractChanges.length) {
+      lines.push("CONTRACT CHANGES\n");
+      for (const contract of review.contractChanges.slice(0, 10)) lines.push(`⚠ ${contract.type} ${contract.location}`);
+      lines.push("");
+    }
+
+        // Recommendation
+        lines.push("RECOMMENDATION\n");
+    lines.push(review.recommendation);
+
+    if (review.correction) lines.push(`\nCORRECTION PASS (1/1)\n${review.correction.instruction}`);
+
+        if (review.personality) {
+            lines.push(`\nFrank: "${review.personality}"`);
+        }
+
+        return lines.join("\n");
+    }
+
+    /**
+     * Format as markdown
+     */
+    formatAsMarkdown(result: AnalysisResult): string {
+        const lines: string[] = [];
+
+        lines.push("# Frankly · Red Ink Review\n");
+
+        // Task
+        lines.push(`## Task\n${result.task}\n`);
+
+        // Verdict
+        const review = result.review;
+        lines.push(`## Change Verdict\n**${review.verdict}**\n`);
+
+        // Metrics
+        lines.push("## Analysis\n");
+        lines.push(`- **Task Alignment**: ${review.taskAlignment}`);
+        lines.push(`- **Change Necessity**: ${review.changeNecessity}/100`);
+        lines.push(`- **Change Surface**: ${review.changeSurface}`);
+    lines.push(`- **Scope Drift**: ${Math.round(review.scopeDrift * 100)}%\n`);
+    lines.push(`- **Behavioral Changes**: ${review.behavioralChanges.join(", ") || "none detected"}`);
+
+        // Findings
+        if (review.findings.length > 0) {
+            lines.push("## Findings\n");
+            for (const finding of review.findings) {
+                lines.push(
+                    `- **${finding.title}** (${finding.severity})\n  ${finding.description}`,
+                );
+            }
+            lines.push("");
+        }
+
+        // Impact
+        lines.push("## Impact\n");
+        lines.push("### Blast Radius");
+        lines.push(`- Direct callers: ${review.blastRadius.directCallers}`);
+        lines.push(`- Transitive callers: ${review.blastRadius.transitiveCallers}`);
+        lines.push(`- Affected packages: ${review.blastRadius.affectedPackages}\n`);
+
+        lines.push("### Test Impact");
+        lines.push(`- Likely affected: ${review.testImpact.likelyAffected}`);
+        lines.push(`- Possibly affected: ${review.testImpact.possiblyAffected}`);
+        lines.push(`- Executed: ${review.testImpact.executed}`);
+        lines.push(`- Passed: ${review.testImpact.passed}\n`);
+
+        // Recommendation
+        lines.push("## Recommendation\n");
+    lines.push(review.recommendation);
+
+    if (review.correction) lines.push(`\n## Correction Pass\n\n${review.correction.instruction}`);
+
+        return lines.join("\n");
+    }
+
+    /**
+     * Format as summary
+     */
+  formatAsSummary(result: AnalysisResult): string {
+        const review = result.review;
+        return `
+FRANKLY ANALYSIS
+
+Verdict: ${review.verdict}
+Files changed: ${result.files.length}
+Symbols changed: ${result.symbols.length}
+Findings: ${review.findings.length}
+Task alignment: ${review.taskAlignment}
+Change necessity: ${review.changeNecessity}/100
+
+${review.recommendation}
+    `.trim();
+  }
+
+  formatAsCi(result: AnalysisResult): string {
+    return JSON.stringify({
+      schemaVersion: result.schemaVersion,
+      verdict: result.review.verdict,
+      necessityScore: result.review.changeNecessity,
+      scopeDrift: result.review.scopeDrift,
+      findings: result.review.findings.map(({ id, severity, confidence, title, affectedSymbols }) => ({ id, severity, confidence, title, affectedSymbols })),
+      predictedTests: result.review.testImpact.predicted,
+      executedTests: result.review.testImpact.executedResults,
+      contracts: result.review.contractChanges,
+    });
+  }
+}
+
+export function createReportFormatter(): ReportFormatter {
+    return new ReportFormatter();
+}

package/src/review/red-ink-review.ts

@@ -0,0 +1,125 @@
+import type {
+  ChangedFile,
+  ExecutedTest,
+  Finding,
+  RedInkReview,
+  Verdict,
+} from "../core/models.js";
+import type { ClassifiedChange } from "../analysis/change-classifier.js";
+import type { RepositoryIntelligence } from "../analysis/repository-intelligence.js";
+import type { FranklyAction, FranklyIntensity, FranklyPersonality } from "../core/config.js";
+
+export interface ReviewInput {
+  task: string;
+  files: ChangedFile[];
+  classifications: ClassifiedChange[];
+  scopeDrift: number;
+  fileCount: number;
+  symbolCount: number;
+  intelligence: RepositoryIntelligence;
+  executedTests: ExecutedTest[];
+  personality: FranklyPersonality;
+  action: FranklyAction;
+  intensity: FranklyIntensity;
+  disabled: boolean;
+  maxCorrectionPasses: number;
+}
+
+export class RedInkReviewBuilder {
+  build(input: ReviewInput): RedInkReview {
+    const confidence = input.intensity === "lite" ? ["high"] : input.intensity === "ultra" ? ["high", "medium", "low"] : ["high", "medium"];
+    const findings = input.disabled ? [] : [...this.classificationFindings(input.classifications), ...input.intelligence.findings].filter((item) => confidence.includes(item.confidence));
+    const hasUntestedImpact = !input.disabled && input.intelligence.predictedTests.length > 0 && input.executedTests.length === 0;
+    const baseVerdict = this.verdict(findings, input.disabled ? 0 : input.scopeDrift, hasUntestedImpact);
+    const verdict = input.action === "enforce" && baseVerdict !== "CLEAN" ? "BLOCK" : baseVerdict;
+    const justified = input.classifications.filter((item) => ["REQUIRED", "SUPPORTING", "TEST", "GENERATED"].includes(item.classification)).length;
+    const necessity = input.disabled ? 100 : input.classifications.length
+      ? Math.max(0, Math.round((justified / input.classifications.length) * 100 - findings.filter((item) => item.confidence !== "low").length * 5))
+      : 100;
+    const passed = input.executedTests.filter((test) => test.status === "PASSED").length;
+    const correction = input.action === "correct" && input.maxCorrectionPasses > 0 && verdict !== "CLEAN" ? input.intelligence.correction : undefined;
+
+    return {
+      task: input.task,
+      verdict,
+      taskAlignment: necessity >= 80 ? "high" : necessity >= 50 ? "medium" : "low",
+      changeNecessity: necessity,
+      changeSurface: surface(input.files, input.symbolCount, input.intelligence),
+      scopeDrift: input.disabled ? 0 : input.scopeDrift,
+      findings,
+      blastRadius: {
+        directCallers: input.intelligence.directCallers.length,
+        transitiveCallers: input.intelligence.transitiveCallers.length,
+        affectedPackages: input.intelligence.packages.length,
+        callers: [...input.intelligence.directCallers, ...input.intelligence.transitiveCallers],
+        packages: input.intelligence.packages,
+      },
+      testImpact: {
+        likelyAffected: input.intelligence.predictedTests.filter((test) => test.status === "LIKELY_AFFECTED").length,
+        possiblyAffected: input.intelligence.predictedTests.filter((test) => test.status === "POSSIBLY_AFFECTED").length,
+        executed: input.executedTests.length,
+        passed,
+        predicted: input.intelligence.predictedTests,
+        executedResults: input.executedTests,
+      },
+      contractChanges: input.intelligence.contracts,
+      behavioralChanges: input.intelligence.behavioralChanges,
+      reuseCandidates: input.intelligence.reuseCandidates,
+      correction,
+      recommendation: recommendation(verdict, findings, Boolean(correction)),
+      personality: personalityLine(input.personality, verdict),
+    };
+  }
+
+  private classificationFindings(classifications: ClassifiedChange[]): Finding[] {
+    return classifications.flatMap((item, index): Finding[] => {
+      if (!["SUSPICIOUS", "UNEXPLAINED", "REFACTOR", "INCIDENTAL"].includes(item.classification)) return [];
+      const target = "path" in item.symbol ? item.symbol.path : item.symbol.id;
+      return [{
+        id: `classification-${index + 1}`,
+        severity: item.classification === "UNEXPLAINED" ? "error" : "warning",
+        confidence: item.confidence,
+        title: item.classification === "REFACTOR" ? "Refactor contamination" : `${item.classification[0]}${item.classification.slice(1).toLowerCase()} change`,
+        description: item.justification,
+        affectedSymbols: [target],
+        evidence: item.evidence,
+        recommendation: "Remove the change or provide repository evidence that the task requires it.",
+        autoCorrectible: true,
+      }];
+    });
+  }
+
+  private verdict(findings: Finding[], drift: number, untested: boolean): Verdict {
+    if (findings.some((item) => item.title === "Refactor contamination")) return "SPLIT";
+    if (findings.some((item) => item.severity === "error") || drift > 0.3 || findings.length > 3) return "SIMPLIFY";
+    if (untested || findings.some((item) => item.title === "Missing regression coverage")) return "VERIFY";
+    if (findings.length) return "REVIEW";
+    return "CLEAN";
+  }
+}
+
+function surface(files: ChangedFile[], symbols: number, intelligence: RepositoryIntelligence): "LOW" | "MEDIUM" | "HIGH" {
+  const score = files.filter((file) => !/(?:-lock\.json|pnpm-lock\.yaml|yarn\.lock)$/.test(file.path)).length
+    + Math.ceil(symbols / 3)
+    + intelligence.contracts.length * 2
+    + Math.max(0, intelligence.packages.length - 1) * 3;
+  return score <= 4 ? "LOW" : score <= 12 ? "MEDIUM" : "HIGH";
+}
+
+function recommendation(verdict: Verdict, findings: Finding[], correction: boolean): string {
+  if (verdict === "CLEAN") return "Patch appears appropriately scoped; no red marks found.";
+  if (correction) return "Give the coding agent the single correction pass below, then run verify_change.";
+  if (verdict === "VERIFY") return "Run the predicted related tests and record their actual results.";
+  if (verdict === "SPLIT") return "Move unrelated refactoring into a separate patch.";
+  return `Review ${findings.length} evidence-backed finding(s) before approval.`;
+}
+
+function personalityLine(personality: FranklyPersonality, verdict: Verdict): string {
+  if (personality === "conservative") return verdict === "CLEAN" ? "The patch appears proportionate." : "These changes may be broader than required.";
+  if (personality === "witty") return verdict === "CLEAN" ? "Nothing to circle in red." : "The diff brought guests the task did not invite.";
+  return verdict === "CLEAN" ? "Every changed line has a plausible reason." : "This task does not yet justify this patch.";
+}
+
+export function createRedInkReviewBuilder(): RedInkReviewBuilder {
+  return new RedInkReviewBuilder();
+}

package/src/tests/phase1.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Basic fixture for testing
+ * Simple TypeScript project
+ */
+
+import { describe, it, expect } from "vitest";
+import { FranklyAnalysisEngine, createAnalysisEngine } from "../core/engine.js";
+import { Repository } from "../git/repository.js";
+import { ProjectDetector } from "../project/detector.js";
+import { SymbolExtractor } from "../graph/symbols.js";
+
+describe("Frankly Phase 1 Foundation", () => {
+    it("should detect a TypeScript project", async () => {
+        const detector = new ProjectDetector(process.cwd());
+        const project = await detector.detectProject();
+
+        expect(project).toBeDefined();
+        expect(project.type).toBe("typescript");
+        expect(project.hasTsConfig).toBe(true);
+    });
+
+    it("should extract symbols from TypeScript files", () => {
+        const extractor = new SymbolExtractor(process.cwd());
+        const symbols = extractor.extractSymbols("./src/core/models.ts");
+
+        expect(symbols).toBeDefined();
+        expect(symbols.length).toBeGreaterThan(0);
+    });
+
+    it("should classify changes", async () => {
+        const repository = new Repository(process.cwd());
+        const status = repository.getStatus();
+
+        // Should return status without errors
+        expect(status).toBeDefined();
+        expect(Array.isArray(status.modified)).toBe(true);
+    });
+
+    it("should plan a task using normalized intent and scope estimation", async () => {
+        const engine = await createAnalysisEngine(process.cwd());
+        const plan = await engine.plan("Please fix retry logic in the API client and add tests");
+
+        expect(plan).toBeDefined();
+        expect(plan.normalizedIntent).toContain("retry");
+        expect(plan.keywords.length).toBeGreaterThan(0);
+        expect(plan.estimatedFiles).toBeGreaterThan(0);
+        expect(plan.estimatedFiles).toBeLessThanOrEqual(12);
+    });
+
+    it("should surface existing repo matches as reuse candidates", async () => {
+        const engine = await createAnalysisEngine(process.cwd());
+        const plan = await engine.plan("review the red ink logic and findings");
+
+        expect(plan.reuseCandidates.length).toBeGreaterThan(0);
+        expect(plan.reuseCandidates.some((candidate) => candidate.toLowerCase().includes("review") || candidate.toLowerCase().includes("analysis"))).toBe(true);
+    });
+});