@moretea-labs/forge 1.5.1 → 1.7.0

package/src/cli/controller/context/source-materializer.ts

@@ -0,0 +1,278 @@
+import ts from 'typescript';
+import type { McpPolicy } from '../../mcp/types';
+import { redactMcpText } from '../../mcp/redaction';
+import { readRepositoryRange, type RepositoryReadSession } from '../../repository/inspector';
+
+const DEFAULT_CONTEXT_BEFORE = 12;
+const DEFAULT_CONTEXT_AFTER = 28;
+const COMPLETE_FILE_MAX_LINES = 240;
+
+export type SourceMaterializationKind = 'complete_file' | 'symbol' | 'line_window';
+
+export interface MaterializedSourceSnippet {
+  path: string;
+  startLine: number;
+  endLine: number;
+  totalLines: number;
+  sha256: string;
+  content: string;
+  truncated: boolean;
+  redactions: Array<{ type: string; count: number }>;
+  reason: string;
+  cacheHit?: boolean;
+  materialization: SourceMaterializationKind;
+  symbol?: {
+    kind: string;
+    name?: string;
+    enclosing?: string;
+  };
+}
+export interface MaterializeSourceOptions {
+  repoRoot: string;
+  policy: McpPolicy;
+  path: string;
+  hitLines: number[];
+  reasons: string[];
+  maxSnippets: number;
+  maxCharsPerSnippet: number;
+  session?: RepositoryReadSession;
+}
+
+interface SymbolRange {
+  startLine: number;
+  endLine: number;
+  kind: string;
+  name?: string;
+  enclosing?: string;
+}
+
+interface IndexedDeclaration {
+  node: ts.Node;
+  kind: string;
+  fullStart: number;
+  end: number;
+}
+
+interface SourceSymbolIndex {
+  sourceFile: ts.SourceFile;
+  declarations: IndexedDeclaration[];
+}
+
+const SOURCE_SYMBOL_INDEX_CACHE_MAX_ENTRIES = 32;
+const sourceSymbolIndexCache = new Map<string, SourceSymbolIndex>();
+let sourceSymbolIndexCacheHits = 0;
+let sourceSymbolIndexCacheMisses = 0;
+
+export function sourceSymbolIndexCacheSnapshotForTest(): { entries: number; hits: number; misses: number } {
+  return {
+    entries: sourceSymbolIndexCache.size,
+    hits: sourceSymbolIndexCacheHits,
+    misses: sourceSymbolIndexCacheMisses,
+  };
+}
+
+export function clearSourceSymbolIndexCacheForTest(): void {
+  sourceSymbolIndexCache.clear();
+  sourceSymbolIndexCacheHits = 0;
+  sourceSymbolIndexCacheMisses = 0;
+}
+
+function boundedContent(content: string, maxChars: number): { content: string; truncated: boolean } {
+  if (content.length <= maxChars) return { content, truncated: false };
+  return { content: `${content.slice(0, maxChars)}\n... <snippet truncated>`, truncated: true };
+}
+
+function plainSource(numbered: string): string {
+  return numbered
+    .split(/\r?\n/)
+    .map((line) => line.replace(/^\d+: /, ''))
+    .join('\n');
+}
+
+function sliceNumbered(numbered: string, startLine: number, endLine: number): string {
+  return numbered
+    .split(/\r?\n/)
+    .slice(Math.max(0, startLine - 1), Math.max(startLine, endLine))
+    .join('\n');
+}
+
+function mergeHitLines(lines: number[]): number[] {
+  const sorted = Array.from(new Set(lines.filter((line) => line > 0))).sort((left, right) => left - right);
+  const merged: number[] = [];
+  for (const line of sorted) {
+    const previous = merged[merged.length - 1];
+    if (previous !== undefined && line - previous <= DEFAULT_CONTEXT_BEFORE + DEFAULT_CONTEXT_AFTER) continue;
+    merged.push(line);
+  }
+  return merged;
+}
+
+function scriptKind(path: string): ts.ScriptKind | undefined {
+  if (/\.tsx$/i.test(path)) return ts.ScriptKind.TSX;
+  if (/\.jsx$/i.test(path)) return ts.ScriptKind.JSX;
+  if (/\.(?:mts|cts|ts)$/i.test(path)) return ts.ScriptKind.TS;
+  if (/\.(?:mjs|cjs|js)$/i.test(path)) return ts.ScriptKind.JS;
+  return undefined;
+}
+
+function declarationName(node: ts.Node): string | undefined {
+  const named = node as ts.Node & { name?: ts.Node };
+  if (!named.name) return undefined;
+  return named.name.getText().slice(0, 200);
+}
+
+function declarationKind(node: ts.Node): string | undefined {
+  if (ts.isFunctionDeclaration(node)) return 'function';
+  if (ts.isMethodDeclaration(node)) return 'method';
+  if (ts.isConstructorDeclaration(node)) return 'constructor';
+  if (ts.isGetAccessorDeclaration(node)) return 'getter';
+  if (ts.isSetAccessorDeclaration(node)) return 'setter';
+  if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) return 'class';
+  if (ts.isInterfaceDeclaration(node)) return 'interface';
+  if (ts.isTypeAliasDeclaration(node)) return 'type';
+  if (ts.isEnumDeclaration(node)) return 'enum';
+  if (ts.isModuleDeclaration(node)) return 'module';
+  if (ts.isVariableStatement(node) && node.declarationList.declarations.some((declaration) =>
+    declaration.initializer && (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer)))) return 'function-variable';
+  return undefined;
+}
+
+function enclosingName(node: ts.Node): string | undefined {
+  let current = node.parent;
+  while (current) {
+    if (ts.isClassDeclaration(current) || ts.isClassExpression(current) || ts.isInterfaceDeclaration(current) || ts.isModuleDeclaration(current)) {
+      const kind = declarationKind(current) ?? 'container';
+      const name = declarationName(current);
+      return name ? `${kind}:${name}` : kind;
+    }
+    current = current.parent;
+  }
+  return undefined;
+}
+
+function buildSourceSymbolIndex(path: string, source: string, kind: ts.ScriptKind): SourceSymbolIndex {
+  const sourceFile = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, kind);
+  const declarations: IndexedDeclaration[] = [];
+  const visit = (node: ts.Node): void => {
+    const candidateKind = declarationKind(node);
+    if (candidateKind) {
+      declarations.push({
+        node,
+        kind: candidateKind,
+        fullStart: node.getFullStart(),
+        end: node.end,
+      });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return { sourceFile, declarations };
+}
+
+function cachedSourceSymbolIndex(path: string, fileSha: string, numberedSource: string): SourceSymbolIndex | undefined {
+  const kind = scriptKind(path);
+  if (kind === undefined) return undefined;
+  const key = `${kind}:${fileSha}`;
+  const cached = sourceSymbolIndexCache.get(key);
+  if (cached) {
+    sourceSymbolIndexCache.delete(key);
+    sourceSymbolIndexCache.set(key, cached);
+    sourceSymbolIndexCacheHits += 1;
+    return cached;
+  }
+
+  sourceSymbolIndexCacheMisses += 1;
+  const built = buildSourceSymbolIndex(path, plainSource(numberedSource), kind);
+  sourceSymbolIndexCache.set(key, built);
+  while (sourceSymbolIndexCache.size > SOURCE_SYMBOL_INDEX_CACHE_MAX_ENTRIES) {
+    const oldest = sourceSymbolIndexCache.keys().next().value as string | undefined;
+    if (!oldest) break;
+    sourceSymbolIndexCache.delete(oldest);
+  }
+  return built;
+}
+
+function symbolAtLine(index: SourceSymbolIndex | undefined, line: number): SymbolRange | undefined {
+  if (!index) return undefined;
+  const { sourceFile, declarations } = index;
+  const targetLine = Math.min(Math.max(1, line), sourceFile.getLineAndCharacterOfPosition(sourceFile.end).line + 1);
+  const position = sourceFile.getPositionOfLineAndCharacter(targetLine - 1, 0);
+  let selected: IndexedDeclaration | undefined;
+  for (const candidate of declarations) {
+    if (candidate.fullStart > position || candidate.end < position) continue;
+    if (!selected || (candidate.end - candidate.fullStart) < (selected.end - selected.fullStart)) selected = candidate;
+  }
+  if (!selected) return undefined;
+  return {
+    startLine: sourceFile.getLineAndCharacterOfPosition(selected.node.getStart(sourceFile)).line + 1,
+    endLine: sourceFile.getLineAndCharacterOfPosition(selected.node.end).line + 1,
+    kind: selected.kind,
+    name: declarationName(selected.node),
+    enclosing: enclosingName(selected.node),
+  };
+}
+
+function materializedSnippet(
+  full: ReturnType<typeof readRepositoryRange>,
+  range: { startLine: number; endLine: number },
+  options: MaterializeSourceOptions,
+  materialization: SourceMaterializationKind,
+  symbol?: SymbolRange,
+): MaterializedSourceSnippet {
+  const numbered = sliceNumbered(full.content, range.startLine, range.endLine);
+  const redacted = redactMcpText(numbered);
+  const bounded = boundedContent(redacted.text, options.maxCharsPerSnippet);
+  return {
+    path: full.path,
+    startLine: range.startLine,
+    endLine: range.endLine,
+    totalLines: full.totalLines,
+    sha256: full.sha256,
+    content: bounded.content,
+    truncated: bounded.truncated,
+    redactions: redacted.redactions,
+    reason: options.reasons.join(', '),
+    cacheHit: full.cacheHit,
+    materialization,
+    ...(symbol ? { symbol: { kind: symbol.kind, name: symbol.name, enclosing: symbol.enclosing } } : {}),
+  };
+}
+
+/**
+ * Materialize current source in semantic units. Complete small files and
+ * complete TypeScript/JavaScript declarations win; a fixed line window is the
+ * bounded fallback for unsupported languages or unmatched top-level text.
+ */
+export function materializeSource(options: MaterializeSourceOptions): MaterializedSourceSnippet[] {
+  if (options.maxSnippets <= 0) return [];
+  const full = readRepositoryRange(
+    options.repoRoot,
+    options.policy,
+    options.path,
+    1,
+    Number.MAX_SAFE_INTEGER,
+    options.session,
+  );
+  if (full.totalLines <= COMPLETE_FILE_MAX_LINES && full.content.length <= options.maxCharsPerSnippet) {
+    return [materializedSnippet(full, { startLine: 1, endLine: full.totalLines }, options, 'complete_file')];
+  }
+
+  const symbolIndex = cachedSourceSymbolIndex(options.path, full.sha256, full.content);
+  const snippets: MaterializedSourceSnippet[] = [];
+  const seen = new Set<string>();
+  for (const line of mergeHitLines(options.hitLines.length > 0 ? options.hitLines : [1])) {
+    if (snippets.length >= options.maxSnippets) break;
+    const symbol = symbolAtLine(symbolIndex, line);
+    const range = symbol
+      ? { startLine: symbol.startLine, endLine: symbol.endLine }
+      : {
+          startLine: Math.max(1, line - DEFAULT_CONTEXT_BEFORE),
+          endLine: Math.min(full.totalLines, line + DEFAULT_CONTEXT_AFTER),
+        };
+    const key = `${range.startLine}:${range.endLine}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    snippets.push(materializedSnippet(full, range, options, symbol ? 'symbol' : 'line_window', symbol));
+  }
+  return snippets;
+}

package/src/cli/controller/context/structural.ts

@@ -0,0 +1,16 @@
+import type { CodeGraphNodeSummary, CodeGraphReadProviderResponse } from '../../../runtime/context/codegraph-read-provider';
+
+export function structuralResult(response: CodeGraphReadProviderResponse): {
+  nodes: CodeGraphNodeSummary[];
+  entryPoints: CodeGraphNodeSummary[];
+  relatedFiles: string[];
+  truncated: boolean;
+} {
+  const result = response.result ?? {};
+  return {
+    nodes: Array.isArray(result.nodes) ? result.nodes as CodeGraphNodeSummary[] : [],
+    entryPoints: Array.isArray(result.entryPoints) ? result.entryPoints as CodeGraphNodeSummary[] : [],
+    relatedFiles: Array.isArray(result.relatedFiles) ? result.relatedFiles.filter((value): value is string => typeof value === 'string') : [],
+    truncated: result.truncated === true,
+  };
+}

package/src/cli/controller/context/types.ts

@@ -0,0 +1,286 @@
+import type { RepositoryReadSession } from '../../repository/inspector';
+import type { CodeGraphIndexMetadata, CodeGraphNodeSummary, CodeGraphReadProviderResponse } from '../../../runtime/context/codegraph-read-provider';
+import type { queryCodeGraphReadProvider, queryCodeGraphReadProviderAsync } from '../../../runtime/context/codegraph-read-provider';
+import type { MaterializedSourceSnippet } from './source-materializer';
+
+export const CONTEXT_PACK_SCHEMA_VERSION = 10;
+export type StructuralContextMode = 'off' | 'auto' | 'required';
+export type ControllerContextRetrievalMode = 'implementation' | 'plan' | 'debug' | 'review';
+export type ControllerEvidenceReadinessStatus = 'ready' | 'degraded' | 'insufficient';
+export type ControllerSemanticEvidenceStatus = 'not_requested' | 'ready' | 'partial' | 'unavailable' | 'error';
+export const CONTROLLER_CONTEXT_IMPACT_DOMAINS = [
+  'persistence', 'scheduler', 'notification', 'timeline', 'events', 'cache', 'api', 'concurrency',
+] as const;
+export type ControllerContextImpactDomain = (typeof CONTROLLER_CONTEXT_IMPACT_DOMAINS)[number];
+export type GovernanceRuleLevel = 'kernel' | 'capability' | 'platform' | 'project';
+export type GovernanceRuleSeverity = 'info' | 'warning' | 'error';
+export type GovernanceCheckCostClass = 'L0' | 'L1' | 'L2' | 'L3' | 'L4';
+export type GovernanceCheckRiskFloor = 'readonly' | 'low' | 'medium' | 'high' | 'destructive';
+export type GovernanceCheckPhase = 'pre_edit' | 'post_edit' | 'pre_finalize' | 'release';
+
+export interface ControllerContextPackOptions {
+  description?: string;
+  issueId?: string;
+  taskId?: string;
+  knownPaths?: string[];
+  includeGlobs?: string[];
+  excludeGlobs?: string[];
+  searchTerms?: string[];
+  maxFiles?: number;
+  maxSnippets?: number;
+  maxCharsPerSnippet?: number;
+  structuralContext?: StructuralContextMode;
+  structuralIndexRoot?: string;
+  retrievalMode?: ControllerContextRetrievalMode;
+  impactDomains?: ControllerContextImpactDomain[];
+  session?: RepositoryReadSession;
+}
+
+export interface ControllerContextPackDependencies {
+  queryCodeGraph?: typeof queryCodeGraphReadProvider;
+  queryCodeGraphAsync?: typeof queryCodeGraphReadProviderAsync;
+}
+
+export type ControllerContextPackSnippet = MaterializedSourceSnippet;
+
+export interface ControllerContextPackFile {
+  path: string;
+  reasons: string[];
+  hitLines: number[];
+  snippetCount: number;
+  snippets: ControllerContextPackSnippet[];
+}
+
+export interface ControllerEvidenceReadiness {
+  status: ControllerEvidenceReadinessStatus;
+  sourceRevision: string | null;
+  rawSource: {
+    status: 'current' | 'partial' | 'unavailable';
+    materializedFileCount: number;
+    snippetTruncated: boolean;
+  };
+  structural: {
+    requested: StructuralContextMode;
+    status: 'disabled' | 'ready' | 'stale' | 'unavailable' | 'degraded';
+    requiredSatisfied: boolean;
+    baselineRevisionMatches: boolean;
+    overlayChangedFileCount: number;
+  };
+  semantic: {
+    status: ControllerSemanticEvidenceStatus;
+    reasonCodes: string[];
+  };
+  retrieval: {
+    searchTruncated: boolean;
+    omittedCandidateCount: number;
+    policyDeniedCandidateCount: number;
+    likelyRelatedNotInspectedCount: number;
+  };
+  unresolvedReasonCodes: string[];
+  readyForHighConfidenceMutation: boolean;
+}
+
+export interface ControllerContextExpansionState {
+  waveCount: number;
+  expansionPerformed: boolean;
+  expansionBudgetUsed: number;
+  expansionBudgetMax: number;
+  discoveredPaths: string[];
+  materializedPaths: string[];
+}
+
+export interface ControllerContextPackProjection {
+  schemaVersion: typeof CONTEXT_PACK_SCHEMA_VERSION;
+  generatedAt: string;
+  source: 'controller-context-pack';
+  focus: { issueId?: string; issueTitle?: string; taskId?: string; taskTitle?: string; taskStatus?: string };
+  goal: string;
+  git: { branch: string | null; status: string; diffStat: string; dirty: boolean };
+  search: {
+    terms: string[];
+    impactDomains: ControllerContextImpactDomain[];
+    impactCoverage: Array<{
+      domain: ControllerContextImpactDomain;
+      queries: string[];
+      matchedFiles: string[];
+      selectedFiles: string[];
+      omittedFileCount: number;
+      status: 'selected' | 'matched_not_selected' | 'no_evidence';
+    }>;
+    includeGlobs: string[];
+    excludeGlobs: string[];
+    scannedFiles: number;
+    policyDeniedFiles: number;
+    skippedLargeFiles: number;
+    skippedBinaryFiles: number;
+    truncated: boolean;
+    cacheHit: boolean;
+  };
+  instructionContext: {
+    status: 'none' | 'ready' | 'degraded';
+    authority: 'guidance_only';
+    targetPaths: string[];
+    contracts: Array<{
+      path: string;
+      appliesTo: string[];
+      content: string;
+      truncated: boolean;
+    }>;
+    coverageGaps: string[];
+    truncated: boolean;
+  };
+  governanceContext: {
+    status: 'none' | 'ready' | 'degraded';
+    authority: 'repository_rule_registry';
+    registry: { rulesPath: string; exceptionsPath: string };
+    activeRules: Array<{
+      id: string;
+      title: string;
+      level: GovernanceRuleLevel;
+      severity: GovernanceRuleSeverity;
+      invariant: string;
+      owner?: string;
+      version?: number;
+      matchedPaths: string[];
+      matchedSignals: string[];
+      checkIds: string[];
+      partialExceptionIds: string[];
+      suppressedPaths: string[];
+    }>;
+    suppressedRules: Array<{
+      id: string;
+      title: string;
+      level: GovernanceRuleLevel;
+      severity: GovernanceRuleSeverity;
+      invariant: string;
+      owner?: string;
+      version?: number;
+      matchedPaths: string[];
+      matchedSignals: string[];
+      checkIds: string[];
+      partialExceptionIds: string[];
+      suppressedPaths: string[];
+      exceptionIds: string[];
+    }>;
+    recommendedCheckIds: string[];
+    recommendedChecks: Array<{
+      checkId: string;
+      ruleIds: string[];
+      available: boolean;
+      costClass?: GovernanceCheckCostClass;
+      riskFloor?: GovernanceCheckRiskFloor;
+      phases?: GovernanceCheckPhase[];
+    }>;
+    expiredExceptionIds: string[];
+    coverageGaps: string[];
+    metrics: {
+      rulesLoaded: number;
+      rulesEvaluated: number;
+      exceptionsLoaded: number;
+      filesScanned: number;
+      bytesScanned: number;
+      elapsedMs: number;
+    };
+  };
+  structuralContext: {
+    provider: 'codegraph';
+    requestedMode: StructuralContextMode;
+    status: 'disabled' | 'ready' | 'stale' | 'unavailable' | 'degraded';
+    requiredSatisfied: boolean;
+    indexSource: 'current_checkout' | 'repository_baseline';
+    overlayChangedFiles: string[];
+    baselineRevisionMatches: boolean;
+    query?: string;
+    entryPoints: Array<Pick<CodeGraphNodeSummary, 'id' | 'kind' | 'name' | 'filePath' | 'startLine' | 'endLine'>>;
+    relatedFiles: string[];
+    metadata?: Pick<CodeGraphIndexMetadata, 'initialized' | 'lastIndexedAt' | 'buildVersion' | 'extractionVersion' | 'staleEngine' | 'changedFiles' | 'ignoredChangedFileCount'>;
+    fallbackReason?: string;
+    timingsMs?: CodeGraphReadProviderResponse['timingsMs'];
+    truncated: boolean;
+  };
+  impactContext: {
+    status: 'not_requested' | 'ready' | 'degraded';
+    confidence: 'low' | 'medium' | 'high';
+    primaryTargets: string[];
+    structuralHints: string[];
+    mustInspect: string[];
+    likelyAffected: string[];
+    relevantTests: string[];
+    relevantChecks: string[];
+    architectureContracts: string[];
+    coverageGaps: string[];
+    relationSources: Array<'codegraph' | 'lexical' | 'forge_checks'>;
+    freshness: {
+      structuralStatus: 'disabled' | 'ready' | 'stale' | 'unavailable' | 'degraded';
+      lastIndexedAt?: number | null;
+      changedFileCount: number;
+      indexSource: 'current_checkout' | 'repository_baseline';
+      overlayChangedFileCount: number;
+      baselineRevisionMatches: boolean;
+    };
+  };
+  readiness: ControllerEvidenceReadiness;
+  expansion: ControllerContextExpansionState;
+  files: ControllerContextPackFile[];
+  coverage: {
+    inspectedFiles: string[];
+    likelyRelatedNotInspected: string[];
+    unresolvedRelationships: string[];
+    relevantTests: string[];
+    exactKnownPaths: { requested: string[]; materialized: string[]; missing: string[] };
+    skippedCandidates: {
+      omittedFiles: number;
+      policyDeniedFiles: number;
+      largeFiles: number;
+      binaryFiles: number;
+      searchTruncated: boolean;
+      structuralTruncated: boolean;
+    };
+    materialization: { completeFiles: number; symbols: number; fallbackWindows: number };
+  };
+  cache: {
+    sessionBound: boolean;
+    lexicalHit: boolean;
+    structuralHits: number;
+    structuralMisses: number;
+    rangeHits: number;
+    rangeMisses: number;
+    reused: boolean;
+  };
+  timingsMs: {
+    gitAndFocus: number;
+    structural: number;
+    lexical: number;
+    materialization: number;
+    governance: number;
+    total: number;
+    parallelFirstPass?: boolean;
+    parallelPrefetch?: number;
+    structuralPrefetchBudgetMs?: number;
+    structuralPrefetchDeferred?: boolean;
+    structuralPrefetchReusedInFlight?: boolean;
+    waveCount: number;
+    expansionBudgetUsed: number;
+    expansionBudgetMax: number;
+  };
+  deniedPaths: Array<{ path: string; reason: string }>;
+  omitted: Array<{ path: string; reason: string }>;
+  limits: {
+    maxFiles: number;
+    maxSnippets: number;
+    maxCharsPerSnippet: number;
+    requestedMaxFiles: number;
+    requestedMaxSnippets: number;
+    reservedExactKnownFiles: number;
+  };
+  validation: { policy: 'task-targeted' | 'minimal'; checks: string[] };
+  contextContract: {
+    strategy: string;
+    retrievalMode: ControllerContextRetrievalMode;
+    semanticSufficiencyAuthority: 'chatgpt';
+    rawCodeRequiredForImplementation: boolean;
+    expansionSignals: string[];
+    notes: string[];
+  };
+  next: string[];
+}