@amrishkhan05/frankly 0.1.0

package/src/core/config.ts

@@ -0,0 +1,149 @@
+/**
+ * Configuration types and loader for Frankly
+ */
+
+import { z } from "zod";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export type FranklyTrigger = "manual" | "checkpoint" | "continuous" | "ci" | "off";
+export type FranklyAction = "observe" | "advise" | "correct" | "enforce";
+export type FranklyIntensity = "lite" | "full" | "ultra" | "off";
+export type FranklyPersonality = "conservative" | "senior" | "witty";
+
+const ConfigSchema = z.object({
+    trigger: z.enum(["manual", "checkpoint", "continuous", "ci", "off"]).default("checkpoint"),
+    action: z.enum(["observe", "advise", "correct", "enforce"]).default("correct"),
+    intensity: z.enum(["lite", "full", "ultra", "off"]).default("full"),
+    personality: z.enum(["conservative", "senior", "witty"]).default("senior"),
+    maxCorrectionPasses: z.number().int().min(0).max(5).default(1),
+
+    analysis: z
+        .object({
+            minimumSufficientChange: z.boolean().default(true),
+            taskAlignment: z.boolean().default(true),
+            reuseFirst: z.boolean().default(true),
+            scopeDrift: z.boolean().default(true),
+            refactorContamination: z.boolean().default(true),
+            unnecessaryAbstractions: z.boolean().default(true),
+            unnecessaryDependencies: z.boolean().default(true),
+            duplication: z.boolean().default(true),
+            blastRadius: z.boolean().default(true),
+            changeSurface: z.boolean().default(true),
+            changeNecessity: z.boolean().default(true),
+            reviewBurden: z.boolean().default(true),
+            contractChanges: z.boolean().default(true),
+            behavioralChanges: z.boolean().default(true),
+            testImpact: z.boolean().default(true),
+            missingRegressionTests: z.boolean().default(true),
+        })
+        .default({}),
+
+    restraint: z
+        .object({
+            enabled: z.boolean().default(true),
+            yagni: z.boolean().default(true),
+            reuseExistingCodeFirst: z.boolean().default(true),
+            stdlibFirst: z.boolean().default(true),
+            platformNativeFirst: z.boolean().default(true),
+            installedDependenciesFirst: z.boolean().default(true),
+            avoidNewDependencies: z.boolean().default(true),
+            avoidPrematureAbstraction: z.boolean().default(true),
+            avoidUnnecessaryGeneralization: z.boolean().default(true),
+            avoidUnrelatedRefactors: z.boolean().default(true),
+            preferLocalChange: z.boolean().default(true),
+            preferSmallestSafeDiff: z.boolean().default(true),
+            preserveSafetyGuardrails: z.boolean().default(true),
+        })
+        .default({}),
+
+    tests: z
+        .object({
+            predictAffected: z.boolean().default(true),
+            distinguishPredictedAndExecuted: z.boolean().default(true),
+            detectMissingRegressionCoverage: z.boolean().default(true),
+            riskBasedExecution: z.boolean().default(true),
+            adapters: z
+                .object({
+                    jest: z.boolean().default(true),
+                    vitest: z.boolean().default(true),
+                    nx: z.boolean().default(true),
+                })
+                .default({}),
+        })
+        .default({}),
+
+    correction: z
+        .object({
+            enabled: z.boolean().default(true),
+            preserveRequestedBehavior: z.boolean().default(true),
+            preserveSecurity: z.boolean().default(true),
+            preserveValidation: z.boolean().default(true),
+            preserveAccessibility: z.boolean().default(true),
+            preserveDataIntegrity: z.boolean().default(true),
+            preserveErrorHandling: z.boolean().default(true),
+            preserveRegressionCoverage: z.boolean().default(true),
+        })
+        .default({}),
+
+    report: z
+        .object({
+            redInkReview: z.boolean().default(true),
+            showEvidence: z.boolean().default(true),
+            showConfidence: z.boolean().default(true),
+            showLowConfidenceFindings: z.boolean().default(false),
+            showPersonalityLine: z.boolean().default(true),
+            progressiveDisclosure: z.boolean().default(true),
+        })
+        .default({}),
+
+    privacy: z
+        .object({
+            localOnly: z.boolean().default(true),
+            telemetry: z.boolean().default(false),
+            externalLLMCalls: z.boolean().default(false),
+            embeddings: z.boolean().default(false),
+            remoteCodeUpload: z.boolean().default(false),
+        })
+        .default({}),
+});
+
+export type FranklyConfig = z.infer<typeof ConfigSchema>;
+
+export function loadConfig(raw: unknown): FranklyConfig {
+    return ConfigSchema.parse(raw);
+}
+
+export function getDefaultConfig(): FranklyConfig {
+    return ConfigSchema.parse({});
+}
+
+export function loadRepositoryConfig(root: string): FranklyConfig {
+    const configPath = path.join(root, "frankly.config.json");
+    if (!fs.existsSync(configPath)) return getDefaultConfig();
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as Record<string, unknown>;
+    delete raw.$schema;
+    return loadConfig(raw);
+}
+
+export const INTENSITY_DESCRIPTIONS = {
+    lite: "Only obvious issues: unrelated changes, duplicate code, unnecessary dependency, obvious scope drift",
+    full: "Complete analysis: YAGNI, reuse, abstraction, scope, blast radius, tests, contracts, minimization",
+    ultra: "Aggressively challenge: premature generalization, new helpers, abstraction, unnecessary defensive complexity, dependency additions, avoidable files/symbols, unrelated refactoring",
+    off: "No analysis",
+};
+
+export const TRIGGER_DESCRIPTIONS = {
+    manual: "Only run when explicitly requested",
+    checkpoint: "Run automatically at meaningful task completion points",
+    continuous: "Run on meaningful debounced edit batches",
+    ci: "Run on committed diff / CI / PR context",
+    off: "Disable Frankly",
+};
+
+export const ACTION_DESCRIPTIONS = {
+    observe: "Analyze only. Never instruct the agent to change the patch.",
+    advise: "Return recommendations to the coding agent.",
+    correct: "Give the coding agent exactly one automatic correction/simplification opportunity.",
+    enforce: "Block completion when configured policies fail.",
+};

package/src/core/engine.ts

@@ -0,0 +1,143 @@
+import * as path from "node:path";
+import type { FranklyConfig } from "./config.js";
+import { loadConfig, loadRepositoryConfig } from "./config.js";
+import type { AnalysisResult, ChangedFile, ChangedSymbol, ExecutedTest, TaskPlan } from "./models.js";
+import { countDiffLines, Repository } from "../git/repository.js";
+import { ProjectDetector } from "../project/detector.js";
+import { SymbolExtractor } from "../graph/symbols.js";
+import { ChangeAnalyzer } from "../analysis/change-classifier.js";
+import { inspectRepository } from "../analysis/repository-intelligence.js";
+import { RedInkReviewBuilder } from "../review/red-ink-review.js";
+
+export interface AnalysisEngine {
+  analyze(task: string, configOverrides?: Partial<FranklyConfig>, executedTests?: ExecutedTest[]): Promise<AnalysisResult>;
+  plan(task: string): Promise<TaskPlan>;
+}
+
+export class FranklyAnalysisEngine implements AnalysisEngine {
+  constructor(
+    private readonly repository: Repository,
+    private readonly projectDetector: ProjectDetector,
+    private readonly symbolExtractor: SymbolExtractor,
+    private readonly config: FranklyConfig,
+  ) {}
+
+  async plan(task: string): Promise<TaskPlan> {
+    const analyzer = new ChangeAnalyzer();
+    const keywords = analyzer.extractTaskKeywords(task);
+    const diff = await this.repository.getWorkingTreeDiff();
+    const intelligence = inspectRepository(this.repository.getRootPath(), keywords, [], []);
+    const project = await this.projectDetector.detectProject();
+    const expected = Math.max(1, Math.min(6, Math.ceil(Math.max(1, keywords.length) / 2)));
+    return {
+      task,
+      normalizedIntent: analyzer.normalizeTaskIntent(task),
+      keywords,
+      estimatedFiles: expected,
+      expectedSymbols: [1, Math.max(2, expected * 2)],
+      expectedTests: /fix|bug|retry|behavior|feature/i.test(task) ? 1 : 0,
+      expectsDependency: /dependency|package|library|sdk/i.test(task),
+      expectsPublicContract: /api|public|export|contract|interface/i.test(task),
+      likelyTouchedAreas: intelligence.reuseCandidates.slice(0, 5),
+      reuseCandidates: intelligence.reuseCandidates,
+      confidence: keywords.length > 1 ? "medium" : "low",
+      concerns: [
+        ...(project.isWorkspace ? ["Confirm the change stays inside the affected workspace package."] : []),
+        ...(keywords.length === 0 ? ["Task text is too vague for reliable intent matching."] : []),
+      ],
+    };
+  }
+
+  async analyze(
+    task: string,
+    configOverrides?: Partial<FranklyConfig>,
+    executedTests: ExecutedTest[] = [],
+  ): Promise<AnalysisResult> {
+    const startTime = Date.now();
+    const config = loadConfig({ ...this.config, ...configOverrides });
+    const fileDiffs = await this.repository.getWorkingTreeDiff();
+    const analyzer = new ChangeAnalyzer();
+    const symbolMap = new Map<string, ReturnType<SymbolExtractor["extractSymbols"]>>();
+    const degradedFindings = [];
+
+    for (const file of fileDiffs) {
+      if (file.status === "deleted" || !/\.[cm]?[jt]sx?$/.test(file.path)) continue;
+      try {
+        symbolMap.set(file.path, this.symbolExtractor.extractSymbols(path.join(this.repository.getRootPath(), file.path)));
+      } catch (error) {
+        symbolMap.set(file.path, []);
+        degradedFindings.push({
+          id: `semantic-fallback-${file.path}`,
+          severity: "warning" as const,
+          confidence: "high" as const,
+          title: "Semantic analysis unavailable",
+          description: `Semantic analysis unavailable for ${file.path}; using reduced-confidence diff evidence.`,
+          affectedSymbols: [file.path],
+          evidence: [],
+        });
+      }
+    }
+
+    const classifications = analyzer.classifyChanges({ task, files: fileDiffs, symbols: symbolMap });
+    const symbols = classifications
+      .map((item) => item.symbol)
+      .filter((item): item is ChangedSymbol => "filePath" in item);
+    const files: ChangedFile[] = fileDiffs.map((file) => ({
+      path: file.path,
+      changeType: file.status,
+      ...countDiffLines(file),
+      changes: file.hunks.length,
+      symbols: symbols.filter((symbol) => symbol.filePath === file.path),
+    }));
+    const intelligence = inspectRepository(
+      this.repository.getRootPath(),
+      analyzer.extractTaskKeywords(task),
+      fileDiffs,
+      symbols,
+      executedTests,
+    );
+    for (const symbol of symbols) {
+      symbol.callers = intelligence.directCallers.filter((file) => file !== symbol.filePath);
+      symbol.relatedTests = intelligence.predictedTests.filter((test) => test.path.includes(path.basename(symbol.filePath).replace(/\.[^.]+$/, ""))).map((test) => test.path);
+    }
+
+    const review = new RedInkReviewBuilder().build({
+      task,
+      files,
+      classifications,
+      scopeDrift: analyzer.detectScopeDrift(classifications.filter((item) => !("filePath" in item.symbol)), files.length),
+      fileCount: files.length,
+      symbolCount: symbols.length,
+      intelligence,
+      executedTests,
+      personality: config.personality,
+      action: config.action,
+      intensity: config.intensity,
+      disabled: config.trigger === "off" || config.intensity === "off",
+      maxCorrectionPasses: config.maxCorrectionPasses,
+    });
+    if (config.trigger !== "off" && config.intensity !== "off") review.findings.push(...degradedFindings);
+
+    return {
+      schemaVersion: "1",
+      repository: this.repository.getRootPath(),
+      task,
+      files,
+      symbols,
+      classifications,
+      findings: review.findings,
+      review,
+      timestamp: Date.now(),
+      duration: Date.now() - startTime,
+    };
+  }
+}
+
+export async function createAnalysisEngine(repositoryPath: string): Promise<FranklyAnalysisEngine> {
+  return new FranklyAnalysisEngine(
+    new Repository(repositoryPath),
+    new ProjectDetector(repositoryPath),
+    new SymbolExtractor(repositoryPath),
+    loadRepositoryConfig(repositoryPath),
+  );
+}

package/src/core/errors.ts

@@ -0,0 +1,56 @@
+/**
+ * Core error types and utilities
+ */
+
+export class FranklyError extends Error {
+    constructor(
+        message: string,
+        public code: string,
+        public details?: Record<string, unknown>,
+    ) {
+        super(message);
+        this.name = "FranklyError";
+    }
+}
+
+export class RepositoryError extends FranklyError {
+    constructor(message: string, details?: Record<string, unknown>) {
+        super(message, "REPOSITORY_ERROR", details);
+        this.name = "RepositoryError";
+    }
+}
+
+export class GitError extends FranklyError {
+    constructor(message: string, details?: Record<string, unknown>) {
+        super(message, "GIT_ERROR", details);
+        this.name = "GitError";
+    }
+}
+
+export class ProjectError extends FranklyError {
+    constructor(message: string, details?: Record<string, unknown>) {
+        super(message, "PROJECT_ERROR", details);
+        this.name = "ProjectError";
+    }
+}
+
+export class SemanticError extends FranklyError {
+    constructor(message: string, details?: Record<string, unknown>) {
+        super(message, "SEMANTIC_ERROR", details);
+        this.name = "SemanticError";
+    }
+}
+
+export class ConfigError extends FranklyError {
+    constructor(message: string, details?: Record<string, unknown>) {
+        super(message, "CONFIG_ERROR", details);
+        this.name = "ConfigError";
+    }
+}
+
+export class AnalysisError extends FranklyError {
+    constructor(message: string, details?: Record<string, unknown>) {
+        super(message, "ANALYSIS_ERROR", details);
+        this.name = "AnalysisError";
+    }
+}

package/src/core/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Core module exports
+ */
+
+export * from "./models.js";
+export * from "./config.js";
+export * from "./errors.js";
+export * from "./engine.js";

package/src/core/models.ts

@@ -0,0 +1,280 @@
+/**
+ * Core data models for Frankly
+ * Foundation types for all analysis
+ */
+
+// ============================================================================
+// Change Symbols and Files
+// ============================================================================
+
+export type SymbolType =
+    | "function"
+    | "method"
+    | "class"
+    | "interface"
+    | "type"
+    | "enum"
+    | "variable"
+    | "constant"
+    | "export"
+    | "route"
+    | "controller"
+    | "service"
+    | "hook"
+    | "component"
+    | "schema"
+    | "configuration";
+
+export type ChangeType = "added" | "modified" | "deleted" | "renamed";
+
+export type Visibility = "public" | "private" | "protected" | "internal";
+
+export interface ChangedSymbol {
+    id: string;
+    name: string;
+    type: SymbolType;
+    filePath: string;
+    lineRange: [number, number]; // [start, end]
+    changeType: ChangeType;
+    visibility: Visibility;
+    isExported: boolean;
+    callers: string[];
+    callees: string[];
+    implementations: string[];
+    interfaces: string[];
+    referencedContracts: string[];
+    relatedTests: string[];
+    packageName?: string;
+    runtimeBoundary?: string;
+    evidence: Evidence[];
+}
+
+export interface ChangedFile {
+    path: string;
+    changeType: ChangeType;
+    additions: number;
+    deletions: number;
+    changes: number;
+    symbols: ChangedSymbol[];
+}
+
+// ============================================================================
+// Evidence Model
+// ============================================================================
+
+export type EvidenceType =
+    | "TASK_MATCH"
+    | "SYMBOL_REFERENCE"
+    | "CALLER_RELATION"
+    | "CALLEE_RELATION"
+    | "INTERFACE_IMPLEMENTATION"
+    | "IMPORT_DEPENDENCY"
+    | "EXPORT_CONTRACT"
+    | "TEST_REFERENCE"
+    | "CONFIG_REFERENCE"
+    | "RUNTIME_BOUNDARY"
+    | "GIT_COCHANGE"
+    | "SIMILAR_IMPLEMENTATION"
+    | "EXISTING_UTILITY"
+    | "DEPENDENCY_USAGE"
+    | "TYPE_REQUIREMENT"
+    | "COMPILE_REQUIREMENT"
+    | "DIFF_DEPENDENT"
+    | "HISTORICAL_PATTERN";
+
+export type Confidence = "high" | "medium" | "low";
+
+export interface Evidence {
+    type: EvidenceType;
+    confidence: Confidence;
+    explanation: string;
+    reference?: string;
+}
+
+// ============================================================================
+// Change Classification
+// ============================================================================
+
+export type ChangeClassification =
+    | "REQUIRED"
+    | "SUPPORTING"
+    | "TEST"
+    | "REFACTOR"
+    | "INCIDENTAL"
+    | "GENERATED"
+    | "SUSPICIOUS"
+    | "UNEXPLAINED";
+
+export interface ClassifiedChange {
+    symbol: ChangedSymbol | ChangedFile;
+    classification: ChangeClassification;
+    confidence: Confidence;
+    justification: string;
+    evidence: Evidence[];
+}
+
+// ============================================================================
+// Behavioral Changes
+// ============================================================================
+
+export type BehavioralChangeType =
+    | "API_BEHAVIOR"
+    | "CONTROL_FLOW"
+    | "ERROR_HANDLING"
+    | "STATE_MUTATION"
+    | "PERSISTENCE"
+    | "SECURITY"
+    | "AUTHORIZATION"
+    | "AUTHENTICATION"
+    | "CONCURRENCY"
+    | "RETRY"
+    | "CACHE"
+    | "CONFIGURATION"
+    | "DEPENDENCY"
+    | "DATABASE_SCHEMA"
+    | "PUBLIC_CONTRACT"
+    | "EVENT"
+    | "MESSAGE_SCHEMA"
+    | "TEST_ONLY"
+    | "REFACTOR_ONLY";
+
+// ============================================================================
+// Contract Changes
+// ============================================================================
+
+export type ContractChangeType =
+    | "ADDED"
+    | "REMOVED"
+    | "WIDENED"
+    | "NARROWED"
+    | "CHANGED";
+
+export interface ContractChange {
+    type: ContractChangeType;
+    location: string;
+    oldSignature?: string;
+    newSignature?: string;
+    severity: "breaking" | "potentially-breaking" | "compatible";
+    confidence: Confidence;
+    affectedCallers?: string[];
+}
+
+// ============================================================================
+// Findings and Recommendations
+// ============================================================================
+
+export type FindingSeverity = "error" | "warning" | "info";
+
+export interface Finding {
+    id: string;
+    severity: FindingSeverity;
+    confidence: Confidence;
+    title: string;
+    description: string;
+    affectedSymbols: string[];
+    evidence: Evidence[];
+    recommendation?: string;
+    autoCorrectible?: boolean;
+}
+
+// ============================================================================
+// Verdict and Review
+// ============================================================================
+
+export type Verdict = "CLEAN" | "REVIEW" | "SIMPLIFY" | "SPLIT" | "VERIFY" | "BLOCK";
+
+export interface RedInkReview {
+    task: string;
+    verdict: Verdict;
+    taskAlignment: "high" | "medium" | "low";
+    changeNecessity: number; // 0-100
+    changeSurface: "LOW" | "MEDIUM" | "HIGH";
+    scopeDrift: number; // 0-1 (percentage)
+    findings: Finding[];
+    blastRadius: {
+        directCallers: number;
+        transitiveCallers: number;
+        affectedPackages: number;
+        callers: string[];
+        packages: string[];
+    };
+    testImpact: {
+        likelyAffected: number;
+        possiblyAffected: number;
+        executed: number;
+        passed: number;
+        predicted: PredictedTest[];
+        executedResults: ExecutedTest[];
+    };
+    contractChanges: ContractChange[];
+    behavioralChanges: BehavioralChangeType[];
+    reuseCandidates: string[];
+    correction?: CorrectionPlan;
+    recommendation: string;
+    personality?: string;
+}
+
+// ============================================================================
+// Analysis Result
+// ============================================================================
+
+export interface AnalysisResult {
+    schemaVersion: "1";
+    repository: string;
+    task: string;
+    files: ChangedFile[];
+    symbols: ChangedSymbol[];
+    classifications: ClassifiedChange[];
+    findings: Finding[];
+    review: RedInkReview;
+    timestamp: number;
+    duration: number; // ms
+}
+
+export interface TaskPlan {
+    task: string;
+    normalizedIntent: string;
+    keywords: string[];
+    estimatedFiles: number;
+    expectedSymbols: [number, number];
+    expectedTests: number;
+    expectsDependency: boolean;
+    expectsPublicContract: boolean;
+    likelyTouchedAreas: string[];
+    reuseCandidates: string[];
+    confidence: "high" | "medium" | "low";
+    concerns: string[];
+}
+
+// ============================================================================
+// Test Impact
+// ============================================================================
+
+export type PredictedTestStatus = "LIKELY_AFFECTED" | "POSSIBLY_AFFECTED" | "UNLIKELY_AFFECTED";
+export type ExecutedTestStatus = "PASSED" | "FAILED" | "SKIPPED" | "NOT_RUN";
+
+export interface PredictedTest {
+    path: string;
+    name: string;
+    status: PredictedTestStatus;
+    evidence: Evidence[];
+}
+
+export interface ExecutedTest {
+    path: string;
+    name: string;
+    status: ExecutedTestStatus;
+    duration?: number;
+}
+
+// ============================================================================
+// Correction Plan
+// ============================================================================
+
+export interface CorrectionPlan {
+    pass: number;
+    removals: string[]; // symbol IDs
+    simplifications: { symbol: string; suggestion: string }[];
+    evidence: Evidence[];
+    instruction: string;
+}

package/src/git/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Core module exports
+ */
+
+export { Repository, createRepository } from "./repository.js";
+export type { FileDiff, DiffHunk } from "./repository.js";
+export { countDiffLines } from "./repository.js";