opencode-code-archaeology 2.0.0

package/dist/types.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Core type definitions for Code Archaeology — OpenCode plugin for systematic
+ * codebase excavation, cataloging, and restoration.
+ *
+ * @module code-archaeology-types
+ */
+/** Valid operational modes. */
+export type ArchaeologyMode = "survey" | "excavate" | "restore";
+/** Supported programming languages. */
+export type TargetLanguage = "typescript" | "javascript" | "python" | "go" | "rust";
+/** Expedition phases in fixed order. */
+export type ExpeditionPhase = "survey" | "dead_code" | "legacy" | "dependencies" | "types_consolidate" | "types_harden" | "dry" | "errors" | "polish" | "final_verify";
+/** Confidence levels for findings. */
+export type ConfidenceLevel = "HIGH" | "MEDIUM" | "LOW";
+/** Status values for expedition progress. */
+export type ExpeditionStatus = "pending" | "running" | "complete" | "failed" | "skipped";
+/** Tool types used for analysis. */
+export type AnalysisTool = "knip" | "vulture" | "madge" | "pydeps" | "jscpd" | "tsc" | "mypy" | "ast_grep" | "manual";
+/** Event types emitted by the plugin. */
+export type EventType = "phase_complete" | "phase_failed" | "finding_detected" | "report_generated";
+/** Runtime parameters for an archaeology session. */
+export interface ArchaeologyConfig {
+    /** Absolute or relative path to repository root. */
+    repo_path: string;
+    /** Primary language for tooling and AST selection. */
+    language: TargetLanguage;
+    /** Operational mode. */
+    mode: ArchaeologyMode;
+    /** Whether to auto-restore medium-confidence findings. */
+    strict_mode: boolean;
+    /** Command to verify correctness (must exit 0 on success). */
+    test_command: string;
+    /** Command for static type verification. */
+    typecheck_command: string;
+    /** Git branch to create and work on. */
+    branch_name: string;
+}
+/** Default configuration values. */
+export declare const DEFAULT_CONFIG: ArchaeologyConfig;
+/** A single detected artifact (dead code, legacy pattern, etc.). */
+export interface Finding {
+    /** Unique identifier for this finding. */
+    id: string;
+    /** Expedition phase that detected this. */
+    phase: ExpeditionPhase;
+    /** File path relative to repo root. */
+    file: string;
+    /** Line number (1-indexed). */
+    line: number;
+    /** Column number (1-indexed). */
+    column?: number;
+    /** Type of artifact found. */
+    type: string;
+    /** Human-readable description. */
+    description: string;
+    /** Confidence in this finding. */
+    confidence: ConfidenceLevel;
+    /** Whether this would be auto-removed in restore mode. */
+    auto_removable: boolean;
+    /** Recommended action. */
+    recommendation: string;
+    /** Tool that detected this (or "manual"). */
+    detected_by: AnalysisTool;
+}
+/** A cluster of related findings (e.g., duplicate types). */
+export interface FindingCluster {
+    /** Cluster identifier. */
+    id: string;
+    /** Phase that produced this cluster. */
+    phase: ExpeditionPhase;
+    /** Human-readable name. */
+    name: string;
+    /** Findings in this cluster. */
+    findings: Finding[];
+    /** Consolidation/remediation plan. */
+    plan: string;
+    /** Whether this cluster is safe to auto-fix. */
+    auto_fixable: boolean;
+}
+/** State of an individual expedition phase. */
+export interface Expedition {
+    /** Phase identifier. */
+    phase: ExpeditionPhase;
+    /** Human-readable name. */
+    name: string;
+    /** Current status. */
+    status: ExpeditionStatus;
+    /** Number of findings detected. */
+    findings_count: number;
+    /** Path to the generated report. */
+    report_path?: string;
+    /** ISO-8601 timestamp when phase started. */
+    started_at?: string;
+    /** ISO-8601 timestamp when phase completed. */
+    completed_at?: string;
+    /** Error message if phase failed. */
+    error?: string;
+}
+/** Top-level structure of `.archaeology/session.json`. */
+export interface Session {
+    /** Schema version. */
+    version: number;
+    /** Plugin version. */
+    plugin_version: string;
+    /** Session identifier. */
+    session_id: string;
+    /** Configuration used for this session. */
+    config: ArchaeologyConfig;
+    /** ISO-8601 timestamp when session started. */
+    started_at: string;
+    /** ISO-8601 timestamp of last update. */
+    updated_at: string;
+    /** All expeditions and their status. */
+    expeditions: Expedition[];
+    /** Total findings across all expeditions. */
+    total_findings: number;
+    /** Number of auto-fixable findings. */
+    auto_fixable_count: number;
+    /** Baseline git commit SHA. */
+    baseline_commit?: string;
+    /** Whether the session completed successfully. */
+    completed: boolean;
+}
+/** File inventory entry from the site survey. */
+export interface FileEntry {
+    /** Relative path. */
+    path: string;
+    /** File size in bytes. */
+    size: number;
+    /** Line count. */
+    lines: number;
+    /** Language detected. */
+    language?: string;
+    /** Whether this is a test file. */
+    is_test: boolean;
+}
+/** Dependency entry from the site survey. */
+export interface DependencyEntry {
+    /** Package name. */
+    name: string;
+    /** Installed version. */
+    version: string;
+    /** Whether it's a dev dependency. */
+    is_dev: boolean;
+    /** Whether the package is deprecated. */
+    is_deprecated?: boolean;
+}
+/** Baseline metrics captured at survey time. */
+export interface BaselineMetrics {
+    /** Total files. */
+    total_files: number;
+    /** Total lines of code. */
+    total_lines: number;
+    /** Test file count. */
+    test_files: number;
+    /** External dependency count. */
+    dependencies: number;
+    /** Type error count. */
+    type_errors: number;
+    /** Lint error count. */
+    lint_errors: number;
+    /** Test pass/fail status. */
+    tests_passing: boolean;
+}
+/** Top-level structure of `.archaeology/site_survey.json`. */
+export interface SiteSurvey {
+    /** Schema version. */
+    version: number;
+    /** Baseline git commit. */
+    baseline_commit: string;
+    /** File inventory. */
+    files: FileEntry[];
+    /** Dependency inventory. */
+    dependencies: DependencyEntry[];
+    /** Baseline metrics. */
+    metrics: BaselineMetrics;
+}
+/** A single edge in the dependency graph. */
+export interface DependencyEdge {
+    /** Source module. */
+    from: string;
+    /** Target module. */
+    to: string;
+    /** Import statement or reference. */
+    import_statement?: string;
+}
+/** A circular dependency cycle. */
+export interface DependencyCycle {
+    /** Cycle identifier. */
+    id: string;
+    /** Files involved in the cycle. */
+    files: string[];
+    /** Edges forming the cycle. */
+    edges: DependencyEdge[];
+    /** Whether this is a direct cycle (A→B→A). */
+    is_direct: boolean;
+    /** Recommended fix strategy. */
+    fix_strategy: string;
+}
+/** Summary statistics for a single expedition report. */
+export interface ExpeditionReportSummary {
+    /** Phase identifier. */
+    phase: ExpeditionPhase;
+    /** Number of findings. */
+    findings: number;
+    /** Number of HIGH confidence findings. */
+    high_confidence: number;
+    /** Number of MEDIUM confidence findings. */
+    medium_confidence: number;
+    /** Number of LOW confidence findings. */
+    low_confidence: number;
+    /** Estimated lines of code affected. */
+    estimated_loc_impact: number;
+}
+/** Top-level structure of `FINAL_CATALOG.md` data. */
+export interface FinalCatalog {
+    /** Schema version. */
+    version: number;
+    /** Session summary. */
+    session: Session;
+    /** Per-expedition summaries. */
+    expeditions: ExpeditionReportSummary[];
+    /** Total lines added. */
+    lines_added: number;
+    /** Total lines removed. */
+    lines_removed: number;
+    /** Number of cycles broken. */
+    cycles_broken: number;
+    /** Number of types consolidated. */
+    types_consolidated: number;
+    /** Recommendations for future maintenance. */
+    recommendations: string[];
+}
+/** Minimal OpenCode plugin server shape. */
+export interface PluginServer {
+    /** Event handler (currently a no-op stub). */
+    event(): undefined;
+}
+/** CLI argument shape for `opencode-code-archaeology`. */
+export interface CliArgs {
+    /** Target repository path. */
+    repo?: string;
+    /** Target language. */
+    language?: TargetLanguage;
+    /** Operational mode. */
+    mode?: ArchaeologyMode;
+    /** Strict mode flag. */
+    strict?: boolean;
+    /** Specific phase to run (optional). */
+    phase?: ExpeditionPhase;
+    /** Test command override. */
+    testCommand?: string;
+    /** Typecheck command override. */
+    typecheckCommand?: string;
+    /** Branch name override. */
+    branch?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,17 @@
+/**
+ * Core type definitions for Code Archaeology — OpenCode plugin for systematic
+ * codebase excavation, cataloging, and restoration.
+ *
+ * @module code-archaeology-types
+ */
+/** Default configuration values. */
+export const DEFAULT_CONFIG = {
+    repo_path: ".",
+    language: "typescript",
+    mode: "survey",
+    strict_mode: false,
+    test_command: "npm test",
+    typecheck_command: "npx tsc --noEmit",
+    branch_name: "refactor/archaeology",
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoEH,oCAAoC;AACpC,MAAM,CAAC,MAAM,cAAc,GAAsB;IAC/C,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,YAAY;IACtB,IAAI,EAAE,QAAQ;IACd,WAAW,EAAE,KAAK;IAClB,YAAY,EAAE,UAAU;IACxB,iBAAiB,EAAE,kBAAkB;IACrC,WAAW,EAAE,sBAAsB;CACpC,CAAC"}

package/hooks/opencode/init.sh

@@ -0,0 +1,84 @@
+# Initialize .archaeology/ directory for Code Archaeology.
+
+set -euo pipefail
+
+ARCHAEOLOGY_DIR=".archaeology"
+SESSION_FILE="$ARCHAEOLOGY_DIR/session.json"
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+RELEASE_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+if [[ -f "$RELEASE_ROOT/VERSION" ]]; then
+  PLUGIN_VERSION="$(tr -d '[:space:]' < "$RELEASE_ROOT/VERSION")"
+else
+  PLUGIN_VERSION="dev"
+fi
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || {
+  echo "Error: not inside a git repository" >&2
+  exit 1
+}
+cd "$REPO_ROOT"
+
+echo "Code Archaeology v${PLUGIN_VERSION} initializing..."
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "Warning: jq not found. Install with: brew install jq" >&2
+fi
+
+mkdir -p "$ARCHAEOLOGY_DIR"
+mkdir -p "$ARCHAEOLOGY_DIR/patches"
+
+# Initialize session.json
+if [[ ! -f "$SESSION_FILE" ]]; then
+  NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  SESSION_ID="archaeology-$(date -u +%s)-$$"
+  BASELINE_COMMIT=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
+  
+  jq -n \
+    --arg sid "$SESSION_ID" \
+    --arg now "$NOW" \
+    --arg ver "$PLUGIN_VERSION" \
+    --arg baseline "$BASELINE_COMMIT" \
+    '{
+      version: 1,
+      plugin_version: $ver,
+      session_id: $sid,
+      config: {
+        repo_path: ".",
+        language: "typescript",
+        mode: "survey",
+        strict_mode: false,
+        test_command: "npm test",
+        typecheck_command: "npx tsc --noEmit",
+        branch_name: "refactor/archaeology"
+      },
+      started_at: $now,
+      updated_at: $now,
+      expeditions: [
+        {phase: "survey", name: "Site Survey \u0026 Baseline", status: "pending", findings_count: 0},
+        {phase: "dead_code", name: "Dead Code Excavation", status: "pending", findings_count: 0},
+        {phase: "legacy", name: "Legacy Stratum Removal", status: "pending", findings_count: 0},
+        {phase: "dependencies", name: "Circular Dependency Cartography", status: "pending", findings_count: 0},
+        {phase: "types_consolidate", name: "Type Catalog Consolidation", status: "pending", findings_count: 0},
+        {phase: "types_harden", name: "Type Restoration \u0026 Hardening", status: "pending", findings_count: 0},
+        {phase: "dry", name: "DRY Stratification", status: "pending", findings_count: 0},
+        {phase: "errors", name: "Error Handling Stratigraphy", status: "pending", findings_count: 0},
+        {phase: "polish", name: "Artifact Cleaning \u0026 Documentation", status: "pending", findings_count: 0},
+        {phase: "final_verify", name: "Site Preservation \u0026 Final Catalog", status: "pending", findings_count: 0}
+      ],
+      total_findings: 0,
+      auto_fixable_count: 0,
+      baseline_commit: $baseline,
+      completed: false
+    }' > "$SESSION_FILE"
+  echo "Initialized $SESSION_FILE"
+else
+  NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  jq --arg now "$NOW" \
+     --arg ver "$PLUGIN_VERSION" \
+     '.updated_at = $now | .plugin_version = $ver' \
+     "$SESSION_FILE" > "$SESSION_FILE.tmp" && mv "$SESSION_FILE.tmp" "$SESSION_FILE"
+  echo "Refreshed $SESSION_FILE"
+fi
+
+echo "Code Archaeology workspace ready at $ARCHAEOLOGY_DIR"

package/hooks/opencode/revert-phase.sh

@@ -0,0 +1,17 @@
+# Revert changes in the current working tree back to the last commit.
+# Usage: revert-phase.sh [phase-name]
+
+set -euo pipefail
+
+PHASE="${1:-unknown}"
+
+echo "[$PHASE] ⚠️ Reverting changes due to failure..."
+
+# Stash any changes and drop them
+git stash push -m "code-archaeology-revert-$PHASE" --include-untracked 2>/dev/null || true
+git stash drop 2>/dev/null || true
+
+# Reset to HEAD
+git reset --hard HEAD
+
+echo "[$PHASE] ✅ Reverted to last commit"

package/hooks/opencode/update-expedition.sh

@@ -0,0 +1,46 @@
+# Update expedition status in session.json
+# Usage: update-expedition.sh <phase> <status> [findings_count] [error_message]
+
+set -euo pipefail
+
+PHASE="$1"
+STATUS="$2"
+FINDINGS="${3:-0}"
+ERROR="${4:-}"
+
+ARCHAEOLOGY_DIR=".archaeology"
+SESSION_FILE="$ARCHAEOLOGY_DIR/session.json"
+
+if [[ ! -f "$SESSION_FILE" ]]; then
+  echo "Error: session.json not found. Run init.sh first." >&2
+  exit 1
+fi
+
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+if command -v jq >/dev/null 2>&1; then
+  if [[ -n "$ERROR" ]]; then
+    jq --arg phase "$PHASE" \
+       --arg status "$STATUS" \
+       --argjson findings "$FINDINGS" \
+       --arg error "$ERROR" \
+       --arg now "$NOW" \
+       '(.expeditions[] | select(.phase == $phase)) |= (.status = $status | .findings_count = $findings | .error = $error | .completed_at = $now) | .updated_at = $now' \
+       "$SESSION_FILE" > "$SESSION_FILE.tmp" && mv "$SESSION_FILE.tmp" "$SESSION_FILE"
+  else
+    jq --arg phase "$PHASE" \
+       --arg status "$STATUS" \
+       --argjson findings "$FINDINGS" \
+       --arg now "$NOW" \
+       '(.expeditions[] | select(.phase == $phase)) |= (.status = $status | .findings_count = $findings | .completed_at = $now) | .updated_at = $now' \
+       "$SESSION_FILE" > "$SESSION_FILE.tmp" && mv "$SESSION_FILE.tmp" "$SESSION_FILE"
+  fi
+  
+  # Update total findings
+  jq '(.total_findings = ([.expeditions[].findings_count] | add // 0))' \
+     "$SESSION_FILE" > "$SESSION_FILE.tmp" && mv "$SESSION_FILE.tmp" "$SESSION_FILE"
+     
+  echo "[$PHASE] Updated status: $STATUS (findings: $FINDINGS)"
+else
+  echo "[$PHASE] Status: $STATUS (findings: $FINDINGS) [jq not available, session not updated]"
+fi

package/hooks/opencode/verify-phase.sh

@@ -0,0 +1,31 @@
+# Verify that tests pass and typecheck succeeds.
+# Usage: verify-phase.sh [phase-name]
+
+set -euo pipefail
+
+PHASE="${1:-unknown}"
+ARCHAEOLOGY_DIR=".archaeology"
+SESSION_FILE="$ARCHAEOLOGY_DIR/session.json"
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Source config from session file if jq is available
+TEST_CMD="npm test"
+TYPECHECK_CMD="npx tsc --noEmit"
+if command -v jq >/dev/null 2>&1 && [[ -f "$SESSION_FILE" ]]; then
+  TEST_CMD=$(jq -r '.config.test_command // "npm test"' "$SESSION_FILE")
+  TYPECHECK_CMD=$(jq -r '.config.typecheck_command // "npx tsc --noEmit"' "$SESSION_FILE")
+fi
+
+echo "[$PHASE] Running test command: $TEST_CMD"
+if ! bash -c "$TEST_CMD"; then
+  echo "[$PHASE] ❌ Tests FAILED" >&2
+  exit 1
+fi
+
+echo "[$PHASE] Running typecheck: $TYPECHECK_CMD"
+if ! bash -c "$TYPECHECK_CMD" 2>/dev/null; then
+  echo "[$PHASE] ⚠️ Typecheck reported errors (non-blocking for some languages)" >&2
+fi
+
+echo "[$PHASE] ✅ Verification passed"

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "opencode-code-archaeology",
+  "version": "2.0.0",
+  "description": "Excavate, catalog, and restore a codebase by removing accumulated sediment—dead code, legacy fallbacks, circular dependencies, weak types, and defensive programming slop.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "opencode-code-archaeology": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "hooks",
+    "commands",
+    "skills",
+    "plugins",
+    "policies",
+    "schema",
+    "AGENTS.md",
+    "VERSION",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "verify:pack": "bash hooks/opencode/verify-package.sh",
+    "prepack": "tsc"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "refactor",
+    "cleanup",
+    "static-analysis",
+    "code-quality",
+    "archaeology"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Maleick/Code-Archaeology.git"
+  },
+  "homepage": "https://github.com/Maleick/Code-Archaeology",
+  "bugs": {
+    "url": "https://github.com/Maleick/Code-Archaeology/issues"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/plugins/code-archaeology.ts

@@ -0,0 +1,8 @@
+export {
+  id,
+  repoRoot,
+  version,
+  server,
+} from "../src/index.ts";
+
+export type * from "../src/types";

package/schema/expedition-report.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "code-archaeology/expedition-report",
+  "title": "Expedition Report",
+  "description": "Schema for individual expedition reports generated by Code Archaeology",
+  "type": "object",
+  "required": ["phase", "name", "findings", "generated_at"],
+  "properties": {
+    "phase": {
+      "type": "string",
+      "enum": [
+        "survey",
+        "dead_code",
+        "legacy",
+        "dependencies",
+        "types_consolidate",
+        "types_harden",
+        "dry",
+        "errors",
+        "polish",
+        "final_verify"
+      ],
+      "description": "Expedition phase identifier"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable phase name"
+    },
+    "findings": {
+      "type": "array",
+      "description": "Artifacts detected in this expedition",
+      "items": {
+        "type": "object",
+        "required": ["id", "file", "line", "type", "description", "confidence"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique finding identifier"
+          },
+          "file": {
+            "type": "string",
+            "description": "File path relative to repo root"
+          },
+          "line": {
+            "type": "integer",
+            "description": "Line number (1-indexed)"
+          },
+          "column": {
+            "type": "integer",
+            "description": "Column number (1-indexed)"
+          },
+          "type": {
+            "type": "string",
+            "description": "Type of artifact found"
+          },
+          "description": {
+            "type": "string",
+            "description": "Human-readable description"
+          },
+          "confidence": {
+            "type": "string",
+            "enum": ["HIGH", "MEDIUM", "LOW"],
+            "description": "Confidence level"
+          },
+          "recommendation": {
+            "type": "string",
+            "description": "Recommended action"
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "properties": {
+        "total_findings": {
+          "type": "integer"
+        },
+        "high_confidence": {
+          "type": "integer"
+        },
+        "medium_confidence": {
+          "type": "integer"
+        },
+        "low_confidence": {
+          "type": "integer"
+        },
+        "estimated_loc_impact": {
+          "type": "integer",
+          "description": "Estimated lines of code affected"
+        }
+      }
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp"
+    }
+  }
+}