@sigil-engine/core 0.1.0

package/src/diff.ts

@@ -0,0 +1,421 @@
+/**
+ * Context diff engine — structural comparison of two context documents.
+ *
+ * Compares entities, components, routes, exports, patterns, conventions,
+ * stack, and dependencies. Outputs a structured DiffResult.
+ *
+ * PURE: No I/O. Takes two documents, returns a diff.
+ */
+
+import type {
+  ContextDocument,
+  Entity,
+  Component,
+  Route,
+  ExportedSymbol,
+} from "./schema.js";
+
+// ---------------------------------------------------------------------------
+// Diff result types
+// ---------------------------------------------------------------------------
+
+export type ChangeType = "added" | "removed" | "modified" | "renamed";
+
+export type ChangeCategory =
+  | "entity"
+  | "component"
+  | "route"
+  | "export"
+  | "pattern"
+  | "convention"
+  | "stack"
+  | "dependency";
+
+export interface Change<T = unknown> {
+  type: ChangeType;
+  name: string;
+  category: ChangeCategory;
+  old?: T;
+  new?: T;
+  details?: string[];
+}
+
+export interface DiffResult {
+  summary: {
+    total_changes: number;
+    added: number;
+    removed: number;
+    modified: number;
+  };
+  changes: Change[];
+  stack_changes: Change[];
+  pattern_changes: Change[];
+  convention_changes: Change[];
+}
+
+// ---------------------------------------------------------------------------
+// Main diff
+// ---------------------------------------------------------------------------
+
+export function diffContexts(oldDoc: ContextDocument, newDoc: ContextDocument): DiffResult {
+  const changes: Change[] = [];
+
+  changes.push(...diffNamedList(oldDoc.entities, newDoc.entities, "entity", diffEntity));
+  changes.push(...diffNamedList(oldDoc.components, newDoc.components, "component", diffComponent));
+  changes.push(...diffByKey(oldDoc.routes, newDoc.routes, "route", (r) => r.path, diffRoute));
+  changes.push(...diffNamedList(oldDoc.exports, newDoc.exports, "export", diffExport));
+  changes.push(...diffDependencies(oldDoc, newDoc));
+
+  const stack_changes = diffRecord(oldDoc.stack ?? {}, newDoc.stack ?? {}, "stack");
+  const pattern_changes = diffRecord(
+    oldDoc.patterns as Record<string, unknown>,
+    newDoc.patterns as Record<string, unknown>,
+    "pattern",
+  );
+  const convention_changes = diffRecord(
+    oldDoc.conventions as Record<string, unknown>,
+    newDoc.conventions as Record<string, unknown>,
+    "convention",
+  );
+
+  const allChanges = [...changes, ...stack_changes, ...pattern_changes, ...convention_changes];
+
+  return {
+    summary: {
+      total_changes: allChanges.length,
+      added: allChanges.filter((c) => c.type === "added").length,
+      removed: allChanges.filter((c) => c.type === "removed").length,
+      modified: allChanges.filter((c) => c.type === "modified").length,
+    },
+    changes,
+    stack_changes,
+    pattern_changes,
+    convention_changes,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Named list diffing (entities, components, exports)
+// ---------------------------------------------------------------------------
+
+interface Named {
+  name: string;
+  _meta?: { file: string; symbol?: string };
+}
+
+function diffNamedList<T extends Named>(
+  oldList: T[],
+  newList: T[],
+  category: ChangeCategory,
+  detailDiff: (old: T, neu: T) => string[],
+): Change[] {
+  const changes: Change[] = [];
+
+  const oldMap = new Map<string, T>();
+  for (const item of oldList) {
+    const key = item._meta ? `${item._meta.file}::${item.name}` : item.name;
+    oldMap.set(key, item);
+  }
+
+  const newMap = new Map<string, T>();
+  for (const item of newList) {
+    const key = item._meta ? `${item._meta.file}::${item.name}` : item.name;
+    newMap.set(key, item);
+  }
+
+  for (const [key, newItem] of newMap) {
+    const oldItem = oldMap.get(key);
+    if (!oldItem) {
+      const byName = oldList.find((o) => o.name === newItem.name);
+      if (byName) {
+        const details = detailDiff(byName, newItem);
+        if (details.length > 0 || byName._meta?.file !== newItem._meta?.file) {
+          const allDetails = byName._meta?.file !== newItem._meta?.file
+            ? [`moved: ${byName._meta?.file} → ${newItem._meta?.file}`, ...details]
+            : details;
+          changes.push({ type: "modified", name: newItem.name, category, old: byName, new: newItem, details: allDetails });
+        }
+      } else {
+        changes.push({ type: "added", name: newItem.name, category, new: newItem });
+      }
+    } else {
+      const details = detailDiff(oldItem, newItem);
+      if (details.length > 0) {
+        changes.push({ type: "modified", name: newItem.name, category, old: oldItem, new: newItem, details });
+      }
+    }
+  }
+
+  for (const [key, oldItem] of oldMap) {
+    if (!newMap.has(key)) {
+      const byName = newList.find((n) => n.name === oldItem.name);
+      if (!byName) {
+        changes.push({ type: "removed", name: oldItem.name, category, old: oldItem });
+      }
+    }
+  }
+
+  return changes;
+}
+
+// ---------------------------------------------------------------------------
+// Key-based diffing (routes)
+// ---------------------------------------------------------------------------
+
+function diffByKey<T>(
+  oldList: T[],
+  newList: T[],
+  category: ChangeCategory,
+  keyFn: (item: T) => string,
+  detailDiff: (old: T, neu: T) => string[],
+): Change[] {
+  const changes: Change[] = [];
+  const oldMap = new Map(oldList.map((item) => [keyFn(item), item]));
+  const newMap = new Map(newList.map((item) => [keyFn(item), item]));
+
+  for (const [key, newItem] of newMap) {
+    const oldItem = oldMap.get(key);
+    if (!oldItem) {
+      changes.push({ type: "added", name: key, category, new: newItem });
+    } else {
+      const details = detailDiff(oldItem, newItem);
+      if (details.length > 0) {
+        changes.push({ type: "modified", name: key, category, old: oldItem, new: newItem, details });
+      }
+    }
+  }
+
+  for (const [key, oldItem] of oldMap) {
+    if (!newMap.has(key)) {
+      changes.push({ type: "removed", name: key, category, old: oldItem });
+    }
+  }
+
+  return changes;
+}
+
+// ---------------------------------------------------------------------------
+// Record diffing (stack, patterns, conventions)
+// ---------------------------------------------------------------------------
+
+function diffRecord(
+  oldObj: Record<string, unknown>,
+  newObj: Record<string, unknown>,
+  category: ChangeCategory,
+): Change[] {
+  const changes: Change[] = [];
+  const allKeys = new Set([...Object.keys(oldObj), ...Object.keys(newObj)]);
+
+  for (const key of allKeys) {
+    const oldVal = oldObj[key];
+    const newVal = newObj[key];
+
+    if (oldVal === undefined && newVal !== undefined) {
+      changes.push({ type: "added", name: key, category, new: newVal });
+    } else if (oldVal !== undefined && newVal === undefined) {
+      changes.push({ type: "removed", name: key, category, old: oldVal });
+    } else if (!deepEqual(oldVal, newVal)) {
+      changes.push({
+        type: "modified",
+        name: key,
+        category,
+        old: oldVal,
+        new: newVal,
+        details: [`${JSON.stringify(oldVal)} → ${JSON.stringify(newVal)}`],
+      });
+    }
+  }
+
+  return changes;
+}
+
+// ---------------------------------------------------------------------------
+// Dependency diffing
+// ---------------------------------------------------------------------------
+
+function diffDependencies(oldDoc: ContextDocument, newDoc: ContextDocument): Change[] {
+  const changes: Change[] = [];
+  const oldDeps = new Map((oldDoc.dependencies ?? []).map((d) => [d.name, d.version]));
+  const newDeps = new Map((newDoc.dependencies ?? []).map((d) => [d.name, d.version]));
+
+  for (const [name, version] of newDeps) {
+    if (!oldDeps.has(name)) {
+      changes.push({ type: "added", name, category: "dependency", new: version });
+    } else if (oldDeps.get(name) !== version) {
+      changes.push({
+        type: "modified", name, category: "dependency",
+        old: oldDeps.get(name), new: version,
+        details: [`${oldDeps.get(name)} → ${version}`],
+      });
+    }
+  }
+  for (const [name] of oldDeps) {
+    if (!newDeps.has(name)) {
+      changes.push({ type: "removed", name, category: "dependency", old: oldDeps.get(name) });
+    }
+  }
+
+  return changes;
+}
+
+// ---------------------------------------------------------------------------
+// Detail diff functions
+// ---------------------------------------------------------------------------
+
+function diffEntity(old: Entity, neu: Entity): string[] {
+  const details: string[] = [];
+  const oldFields = new Map(old.fields.map((f) => [f.name, f]));
+  const newFields = new Map(neu.fields.map((f) => [f.name, f]));
+
+  for (const [name, newField] of newFields) {
+    if (!oldFields.has(name)) {
+      details.push(`+ field: ${name} (${newField.type})`);
+    } else {
+      const oldField = oldFields.get(name)!;
+      if (oldField.type !== newField.type) details.push(`~ field ${name}: type ${oldField.type} → ${newField.type}`);
+      if (oldField.nullable !== newField.nullable) details.push(`~ field ${name}: nullable ${oldField.nullable} → ${newField.nullable}`);
+      if (oldField.unique !== newField.unique) details.push(`~ field ${name}: unique ${oldField.unique} → ${newField.unique}`);
+    }
+  }
+  for (const name of oldFields.keys()) {
+    if (!newFields.has(name)) details.push(`- field: ${name}`);
+  }
+
+  const oldRels = new Set(old.relations.map((r) => `${r.to}:${r.type}`));
+  const newRels = new Set(neu.relations.map((r) => `${r.to}:${r.type}`));
+  for (const rel of newRels) if (!oldRels.has(rel)) details.push(`+ relation: ${rel}`);
+  for (const rel of oldRels) if (!newRels.has(rel)) details.push(`- relation: ${rel}`);
+
+  return details;
+}
+
+function diffComponent(old: Component, neu: Component): string[] {
+  const details: string[] = [];
+
+  const oldProps = new Map(old.props.map((p) => [p.name, p]));
+  const newProps = new Map(neu.props.map((p) => [p.name, p]));
+  for (const [name, newProp] of newProps) {
+    if (!oldProps.has(name)) {
+      details.push(`+ prop: ${name}: ${newProp.type}`);
+    } else if (oldProps.get(name)!.type !== newProp.type) {
+      details.push(`~ prop ${name}: ${oldProps.get(name)!.type} → ${newProp.type}`);
+    }
+  }
+  for (const name of oldProps.keys()) {
+    if (!newProps.has(name)) details.push(`- prop: ${name}`);
+  }
+
+  const addedDeps = neu.dependencies.filter((d) => !old.dependencies.includes(d));
+  const removedDeps = old.dependencies.filter((d) => !neu.dependencies.includes(d));
+  for (const d of addedDeps) details.push(`+ dep: ${d}`);
+  for (const d of removedDeps) details.push(`- dep: ${d}`);
+
+  return details;
+}
+
+function diffRoute(old: Route, neu: Route): string[] {
+  const details: string[] = [];
+  const allMethods = new Set([...Object.keys(old.methods), ...Object.keys(neu.methods)]);
+
+  for (const method of allMethods) {
+    if (!old.methods[method] && neu.methods[method]) {
+      details.push(`+ method: ${method}`);
+    } else if (old.methods[method] && !neu.methods[method]) {
+      details.push(`- method: ${method}`);
+    } else if (old.methods[method] && neu.methods[method]) {
+      if (old.methods[method].auth !== neu.methods[method].auth) {
+        details.push(`~ ${method} auth: ${old.methods[method].auth} → ${neu.methods[method].auth}`);
+      }
+    }
+  }
+
+  return details;
+}
+
+function diffExport(old: ExportedSymbol, neu: ExportedSymbol): string[] {
+  const details: string[] = [];
+  if (old.kind !== neu.kind) details.push(`~ kind: ${old.kind} → ${neu.kind}`);
+  if (old.signature !== neu.signature) details.push(`~ signature changed`);
+  return details;
+}
+
+// ---------------------------------------------------------------------------
+// Deep equality (replaces JSON.stringify comparison)
+// ---------------------------------------------------------------------------
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((val, i) => deepEqual(val, b[i]));
+  }
+
+  if (typeof a === "object" && typeof b === "object") {
+    const aObj = a as Record<string, unknown>;
+    const bObj = b as Record<string, unknown>;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+    if (aKeys.length !== bKeys.length) return false;
+    return aKeys.every((key) => deepEqual(aObj[key], bObj[key]));
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Format diff for terminal output
+// ---------------------------------------------------------------------------
+
+export function formatDiff(result: DiffResult): string {
+  const lines: string[] = [];
+
+  lines.push(`\n  Context Diff Summary`);
+  lines.push(`  ${"─".repeat(20)}`);
+  lines.push(`  ${result.summary.total_changes} changes: +${result.summary.added} added, -${result.summary.removed} removed, ~${result.summary.modified} modified\n`);
+
+  const allChanges = [
+    ...result.stack_changes,
+    ...result.pattern_changes,
+    ...result.convention_changes,
+    ...result.changes,
+  ];
+
+  const grouped = new Map<string, Change[]>();
+  for (const change of allChanges) {
+    const list = grouped.get(change.category) ?? [];
+    list.push(change);
+    grouped.set(change.category, list);
+  }
+
+  const labels: Record<string, string> = {
+    stack: "Stack", pattern: "Patterns", convention: "Conventions",
+    entity: "Entities", component: "Components", route: "Routes",
+    export: "Exports", dependency: "Dependencies",
+  };
+
+  for (const [cat, label] of Object.entries(labels)) {
+    const changes = grouped.get(cat);
+    if (!changes || changes.length === 0) continue;
+
+    lines.push(`  ${label}`);
+    for (const change of changes) {
+      const symbol = change.type === "added" ? "+" : change.type === "removed" ? "-" : "~";
+      lines.push(`    ${symbol} ${change.name}`);
+      if (change.details) {
+        for (const detail of change.details) {
+          lines.push(`      ${detail}`);
+        }
+      }
+    }
+    lines.push("");
+  }
+
+  if (result.summary.total_changes === 0) {
+    lines.push("  No changes detected.\n");
+  }
+
+  return lines.join("\n");
+}

package/src/extract.ts

@@ -0,0 +1,196 @@
+/**
+ * Extraction orchestrator — discovers plugins, runs them, merges results.
+ *
+ * PURE: This module returns a ContextDocument. It does NOT write to disk.
+ * I/O is handled by the CLI or calling code.
+ */
+
+import { execSync } from "child_process";
+import { resolve, basename } from "path";
+import { existsSync, readFileSync } from "fs";
+import { createEmptyDocument, type ContextDocument } from "./schema.js";
+import {
+  detectPlugins,
+  getPlugins,
+  type ExtractorPlugin,
+  type ParsedProject,
+  type ExtractResult,
+  type ProgressCallback,
+} from "./plugin.js";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface ExtractOptions {
+  /** Absolute path to the project root */
+  projectPath: string;
+  /** Specific plugins to run (by name). If empty, auto-detect. */
+  plugins?: string[];
+  /** Progress callback for reporting extraction status */
+  onProgress?: ProgressCallback;
+}
+
+/**
+ * Extract a ContextDocument from a project.
+ *
+ * This is the primary API — it discovers applicable plugins,
+ * runs them, and merges results into a unified document.
+ *
+ * Returns a ContextDocument. Does NOT write to disk.
+ */
+export async function extractContext(opts: ExtractOptions): Promise<ContextDocument> {
+  const startTime = Date.now();
+  const projectPath = resolve(opts.projectPath);
+  const projectName = inferProjectName(projectPath);
+  const progress = opts.onProgress ?? (() => {});
+
+  progress({ phase: "init", message: `Parsing ${projectName} at ${projectPath}` });
+
+  // Discover which plugins apply to this project
+  progress({ phase: "detect", message: "Detecting project type..." });
+
+  let plugins: ExtractorPlugin[];
+  if (opts.plugins && opts.plugins.length > 0) {
+    // Use explicitly specified plugins
+    const allPlugins = getPlugins();
+    plugins = allPlugins.filter((p) => opts.plugins!.includes(p.name));
+    if (plugins.length === 0) {
+      throw new Error(
+        `No registered plugins match: ${opts.plugins.join(", ")}. ` +
+        `Available: ${allPlugins.map((p) => p.name).join(", ") || "none"}`
+      );
+    }
+  } else {
+    // Auto-detect
+    plugins = await detectPlugins(projectPath);
+    if (plugins.length === 0) {
+      throw new Error(
+        "No plugins detected support for this project. " +
+        "Install a parser plugin (e.g., @sigil-engine/parser-typescript)."
+      );
+    }
+  }
+
+  progress({
+    phase: "detect",
+    message: `Detected plugins: ${plugins.map((p) => p.name).join(", ")}`,
+  });
+
+  // Create the document
+  const doc = createEmptyDocument(projectName);
+
+  // Run each plugin: init → extract → merge
+  for (const plugin of plugins) {
+    progress({
+      phase: "extract",
+      plugin: plugin.name,
+      message: `Running ${plugin.name} plugin...`,
+    });
+
+    const project = await plugin.init(projectPath);
+
+    progress({
+      phase: "extract",
+      plugin: plugin.name,
+      message: `${plugin.name}: found ${project.sourceFiles.length} source files`,
+    });
+
+    const result = await plugin.extract(project);
+
+    progress({
+      phase: "merge",
+      plugin: plugin.name,
+      message: `Merging ${plugin.name} results...`,
+    });
+
+    mergeResult(doc, result);
+  }
+
+  // Finalize metadata
+  const elapsed = Date.now() - startTime;
+  doc._extraction = {
+    extracted_at: new Date().toISOString(),
+    sigil_version: "0.1.0",
+    source_commit: getGitCommit(projectPath),
+    extraction_ms: elapsed,
+    plugins_used: plugins.map((p) => `${p.name}@${p.version}`),
+  };
+
+  progress({
+    phase: "done",
+    message: `Done in ${elapsed}ms — ${doc.entities.length} entities, ${doc.components.length} components, ${doc.routes.length} routes, ${doc.exports.length} exports`,
+    elapsed_ms: elapsed,
+  });
+
+  return doc;
+}
+
+// ---------------------------------------------------------------------------
+// Merge plugin results into document
+// ---------------------------------------------------------------------------
+
+function mergeResult(doc: ContextDocument, result: ExtractResult): void {
+  // Arrays: concatenate
+  if (result.entities) doc.entities.push(...result.entities);
+  if (result.components) doc.components.push(...result.components);
+  if (result.routes) doc.routes.push(...result.routes);
+  if (result.exports) doc.exports.push(...result.exports);
+  if (result.call_graph) doc.call_graph.push(...result.call_graph);
+  if (result.component_graph) doc.component_graph.push(...result.component_graph);
+  if (result.env_vars) doc.env_vars.push(...result.env_vars);
+  if (result.dependencies) doc.dependencies.push(...result.dependencies);
+
+  // Records: merge (later plugins can override earlier ones)
+  if (result.stack) Object.assign(doc.stack, result.stack);
+  if (result.patterns) Object.assign(doc.patterns, result.patterns);
+  if (result.conventions) Object.assign(doc.conventions, result.conventions);
+
+  // Extensions: deep merge
+  if (result.extensions) {
+    doc.extensions = doc.extensions ?? {};
+    Object.assign(doc.extensions, result.extensions);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Deduplication — remove exports already captured as components/entities
+// ---------------------------------------------------------------------------
+
+export function deduplicateExports(doc: ContextDocument): void {
+  const componentNames = new Set(doc.components.map((c) => c.name));
+  const entitySymbols = new Set(doc.entities.map((e) => e._meta.symbol));
+  doc.exports = doc.exports.filter(
+    (exp) => !componentNames.has(exp.name) && !entitySymbols.has(exp.name),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function inferProjectName(projectPath: string): string {
+  const pkgPath = resolve(projectPath, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      if (pkg.name && !pkg.name.startsWith("@")) return pkg.name;
+      if (pkg.name) return pkg.name.split("/").pop() ?? basename(projectPath);
+    } catch {
+      // fall through
+    }
+  }
+  return basename(projectPath);
+}
+
+function getGitCommit(projectPath: string): string | undefined {
+  try {
+    return execSync("git rev-parse --short HEAD", {
+      cwd: projectPath,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return undefined;
+  }
+}

package/src/index.ts

@@ -0,0 +1,94 @@
+/**
+ * @sigil-engine/core — Public API
+ *
+ * The core engine for Sigil. Language-agnostic schema, plugin system,
+ * extraction orchestrator, diff engine, and serialization.
+ *
+ * Usage:
+ *   import { extractContext, diffContexts, registerPlugin } from '@sigil-engine/core';
+ *
+ *   registerPlugin(typescriptPlugin);
+ *   const doc = await extractContext({ projectPath: './my-app' });
+ */
+
+// Schema types
+export type {
+  ContextDocument,
+  Meta,
+  MetaType,
+  StackInfo,
+  ExtractionMeta,
+  Entity,
+  EntityField,
+  EntityRelation,
+  Component,
+  ComponentProp,
+  Route,
+  RouteMethod,
+  ExportedSymbol,
+  Patterns,
+  Conventions,
+  Dependency,
+  CallEdge,
+  ComponentEdge,
+  EnvVar,
+} from "./schema.js";
+
+export { createEmptyDocument } from "./schema.js";
+
+// Plugin system
+export type {
+  ExtractorPlugin,
+  ParsedProject,
+  ExtractResult,
+  ApplyIntent,
+  ApplyResult,
+  IntentType,
+  IntentConfidence,
+  ProgressCallback,
+  ProgressEvent,
+  ProgressPhase,
+} from "./plugin.js";
+
+export {
+  registerPlugin,
+  getPlugins,
+  detectPlugins,
+  clearPlugins,
+} from "./plugin.js";
+
+// Extraction
+export type { ExtractOptions } from "./extract.js";
+export { extractContext, deduplicateExports } from "./extract.js";
+
+// Diff
+export type { DiffResult, Change, ChangeType, ChangeCategory } from "./diff.js";
+export { diffContexts, formatDiff } from "./diff.js";
+
+// Serialization
+export {
+  serializeYaml,
+  serializeJson,
+  deserializeYaml,
+  deserializeJson,
+  writeContextFile,
+  readContextFile,
+} from "./serialize.js";
+
+// Cache
+export type { FileCache, ChangedFiles } from "./cache.js";
+export {
+  readCache,
+  writeCache,
+  buildCacheFromFiles,
+  getChangedFiles,
+} from "./cache.js";
+
+// Safety (apply module)
+export type { SafetyCheckpoint, ValidationResult, ConfirmCallback } from "./safety.js";
+export {
+  preApplySafety,
+  postApplyValidation,
+  rollbackApply,
+  getGitStatus,
+} from "./safety.js";