opencode-code-archaeology 2.0.0

package/AGENTS.md

@@ -0,0 +1,98 @@
+# Code Archaeology Agent Guide
+
+Code Archaeology is an OpenCode plugin for systematic codebase excavation, cataloging, and restoration.
+
+## Runtime Policy
+
+- OpenCode is the only supported worker runtime.
+- The plugin operates entirely within the target repository.
+- All changes are isolated to a configurable branch (`refactor/archaeology` by default).
+
+## Available Hooks
+
+Core hooks in `hooks/opencode/`:
+- `init.sh` — Initialize `.archaeology/` directory and session state
+- `verify-phase.sh` — Run tests and typecheck between phases
+- `revert-phase.sh` — Revert changes if a phase fails verification
+- `update-expedition.sh` — Update expedition status in session.json
+
+## Safety Hooks
+
+- `verify-phase.sh` — Mandatory test/typecheck gate between expeditions
+- `revert-phase.sh` — Automatic rollback on failure
+
+## Workflow
+
+1. Run `hooks/opencode/init.sh` to initialize the session
+2. For each expedition:
+   a. Run the expedition (generate reports or apply changes)
+   b. Run `hooks/opencode/verify-phase.sh <phase>` to verify
+   c. If verification fails, run `hooks/opencode/revert-phase.sh <phase>`
+   d. Run `hooks/opencode/update-expedition.sh <phase> <status> [findings]`
+3. Final verification runs all checks and generates `FINAL_CATALOG.md`
+
+## Local State
+
+`.archaeology/` is runtime state and must not be committed.
+
+Key files:
+- `session.json` — Expedition progress and configuration
+- `site_survey.md` — Baseline inventory
+- `expedition1-report.md` through `expedition8-report.md` — Per-expedition findings
+- `FINAL_CATALOG.md` — Completed excavation summary
+- `excavation_log.txt` — `git diff --stat`
+- `patches/` — Mock patches (excavate mode)
+
+## Modes
+
+| Mode | Behavior |
+|------|----------|
+| `survey` | Reports only, zero file changes |
+| `excavate` | Reports + mock patches, zero file changes |
+| `restore` | Apply approved changes, test-gated |
+
+## Constraints
+
+- NEVER commit directly to main or master
+- NEVER remove or modify code without writing a site report first
+- NEVER guess types; flag uncertain replacements for human review
+- ALWAYS run tests between phases; stop immediately on failure
+- ALWAYS revert changes if a phase introduces test failures
+- NEVER consolidate types before dead code and legacy removal
+- NEVER remove try/catch from I/O or external input boundaries
+
+## Verification
+
+Before claiming work is complete:
+
+```bash
+bash hooks/opencode/verify-phase.sh final_verify
+bash -n hooks/opencode/*.sh
+```
+
+## Language Support
+
+| Language | Dead Code | Dependencies | Types | DRY |
+|----------|-----------|--------------|-------|-----|
+| TypeScript | `knip` | `madge` | `tsc` | `jscpd` |
+| JavaScript | `knip` | `madge` | N/A | `jscpd` |
+| Python | `vulture` | `pydeps` | `mypy` | `pylint` |
+| Go | `deadcode` | `godepgraph` | `go vet` | `golangci-lint` |
+| Rust | `cargo-udeps` | `cargo-deps` | `rustc` | `clippy` |
+
+If tools are missing, the skill falls back to AST-based manual analysis.
+
+## Expedition Order
+
+The expeditions MUST run in this fixed order:
+
+1. Site Survey & Baseline
+2. Dead Code Excavation
+3. Legacy Stratum Removal
+4. Circular Dependency Cartography
+5. Type Catalog Consolidation
+6. Type Restoration & Hardening
+7. DRY Stratification
+8. Error Handling Stratigraphy
+9. Artifact Cleaning & Documentation
+10. Site Preservation & Final Catalog

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -0,0 +1,128 @@
+# Code Archaeology
+
+A systematic excavation plugin for OpenCode. Removes accumulated sediment from a codebase—dead code, legacy fallbacks, circular dependencies, weak types, and defensive programming slop—to restore the original architecture.
+
+## ⚠️ Site Safety
+
+This plugin modifies code. By default it runs in **survey** mode, producing site reports only. Review these before switching to `restore` mode.
+
+## Prerequisites
+
+- Git repo with clean working tree
+- Passing test suite (even if minimal)
+- Type checker / linter installed
+- `opencode` CLI available
+
+## Installation
+
+```bash
+# As an OpenCode plugin
+npm install -g opencode-code-archaeology
+
+# Or clone and link
+git clone https://github.com/Maleick/Code-Archaeology.git
+cd Code-Archaeology
+npm link
+```
+
+## Usage
+
+```bash
+# 1. Survey — catalog artifacts, zero changes
+opencode run code-archaeology --mode survey
+
+# 2. Review reports in .archaeology/
+cat .archaeology/expedition1-report.md
+# ... etc
+
+# 3. Restore high-confidence findings only
+opencode run code-archaeology --mode restore --strict_mode false
+
+# 4. Or restore medium+high confidence
+opencode run code-archaeology --mode restore --strict_mode true
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `repo_path` | `.` | Target repository |
+| `language` | `typescript` | Primary language |
+| `mode` | `survey` | `survey`, `excavate`, or `restore` |
+| `strict_mode` | `false` | Auto-restore medium-confidence findings |
+| `test_command` | `npm test` | Test runner command |
+| `typecheck_command` | `npx tsc --noEmit` | Type check command |
+| `branch_name` | `refactor/archaeology` | Git branch to create |
+
+## Output Artifacts
+
+All artifacts are written to `.archaeology/`:
+
+- `site_survey.md` — baseline inventory and stratum graph
+- `expedition1-report.md` through `expedition8-report.md` — per-expedition findings
+- `FINAL_CATALOG.md` — completed excavation metrics and recommendations
+- `excavation_log.txt` — `git diff --stat`
+
+## Expedition Order (Fixed)
+
+The expeditions MUST run in this order due to stratigraphic dependencies:
+
+1. Site Survey & Baseline
+2. Dead Code Excavation
+3. Legacy Stratum Removal
+4. Circular Dependency Cartography
+5. Type Catalog Consolidation
+6. Type Restoration & Hardening
+7. DRY Stratification
+8. Error Handling Stratigraphy
+9. Artifact Cleaning & Documentation
+10. Site Preservation & Final Catalog
+
+**Why this order?** You cannot consolidate types before removing dead code (you might catalog code that should be discarded). You cannot DRY before untangling cycles (abstractions over cyclic deps create worse stratification).
+
+## Language-Specific Tooling
+
+| Language | Dead Code | Dependencies | Types | DRY |
+|----------|-----------|--------------|-------|-----|
+| TypeScript | `knip`, `unimported` | `madge` | `tsc` | `jscpd` |
+| JavaScript | `knip`, `depcheck` | `madge` | N/A | `jscpd` |
+| Python | `vulture` | `pydeps` | `mypy` | `pylint` |
+| Go | `deadcode`, `staticcheck` | `godepgraph` | `go vet` | `golangci-lint` |
+| Rust | `cargo-udeps`, `rustc` | `cargo-deps` | `rustc` | `clippy` |
+
+If tools are missing, the skill falls back to AST-based manual analysis.
+
+## Architecture
+
+```
+Code-Archaeology/
+├── src/              # TypeScript source (plugin entry, types)
+├── plugins/          # OpenCode plugin entry point
+├── skills/           # Agent skill definitions (SKILL.md)
+├── commands/         # CLI command documentation
+├── hooks/            # Shell scripts for expedition workflow
+├── prompts/          # Detailed expedition prompts
+├── schema/           # JSON schemas for reports
+├── AGENTS.md         # Agent runtime guide
+└── README.md         # This file
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Type check
+npm run typecheck
+
+# Verify package
+npm run verify:pack
+```
+
+## License
+
+MIT

package/VERSION

@@ -0,0 +1 @@
+2.0.0

package/commands/code-archaeology-excavate.md

@@ -0,0 +1,51 @@
+---
+name: code-archaeology-excavate
+description: Run Code Archaeology in excavate mode — generate reports and mock patches for human review
+trigger:
+  - "archaeology excavate"
+  - "code archaeology excavate"
+  - "/archaeology-excavate"
+---
+
+# Code Archaeology — Excavate Mode
+
+Generate reports AND mock patch files for human review. Still zero actual file changes — this produces the patches you would apply.
+
+## Usage
+
+```
+Run: /code-archaeology-excavate
+```
+
+## What It Does
+
+Runs all 10 expeditions in excavate mode:
+- Catalogs every artifact found (same as survey)
+- Generates mock `.patch` files showing proposed changes
+- Labels each patch with confidence level (HIGH/MEDIUM/LOW)
+- Proposes specific line-by-line changes
+- Does NOT apply any patches
+
+## When to Use
+
+- After survey reports show promising findings
+- Team wants to review exact changes before applying
+- Need to estimate review effort
+- Want to batch-review multiple expeditions
+
+## Output
+
+- All survey reports in `.archaeology/`
+- Mock patch files in `.archaeology/patches/`
+- Patch index in `.archaeology/patch-index.json`
+
+## Review Process
+
+1. Read `expeditionN-report.md` files
+2. Review `.archaeology/patches/*.patch` files
+3. Approve/reject individual patches
+4. Run `/code-archaeology-restore` to apply approved patches
+
+## Parameters
+
+Same as `/code-archaeology`, defaults to `mode: excavate`.

package/commands/code-archaeology-restore.md

@@ -0,0 +1,62 @@
+---
+name: code-archaeology-restore
+description: Run Code Archaeology in restore mode — execute approved changes after survey/excavate review
+trigger:
+  - "archaeology restore"
+  - "code archaeology restore"
+  - "/archaeology-restore"
+---
+
+# Code Archaeology — Restore Mode
+
+Execute approved changes. Applies HIGH confidence findings by default. With `strict_mode: true`, also applies MEDIUM confidence findings.
+
+## Usage
+
+```
+Run: /code-archaeology-restore
+```
+
+## What It Does
+
+Runs all 10 expeditions in restore mode:
+- Applies HIGH confidence changes automatically
+- Applies MEDIUM confidence changes only if `strict_mode: true`
+- NEVER applies LOW confidence changes (flagged for manual review)
+- Runs tests after each expedition phase
+- Reverts immediately if tests fail
+- Generates final report with metrics
+
+## When to Use
+
+- Survey and excavate phases are complete
+- Team has reviewed and approved findings
+- You want automated cleanup of obvious issues
+- You have good test coverage to catch regressions
+
+## Safety
+
+- Creates `refactor/archaeology` branch (configurable)
+- Tests run between every phase
+- Automatic revert on test failure
+- LOW confidence findings never auto-applied
+- I/O boundary error handling never removed
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `strict_mode` | `false` | If `true`, also applies MEDIUM confidence findings |
+
+## Output
+
+- Applied changes on `refactor/archaeology` branch
+- `FINAL_CATALOG.md` with before/after metrics
+- `excavation_log.txt` with `git diff --stat`
+
+## Next Steps
+
+1. Review the branch: `git diff main..refactor/archaeology`
+2. Run full test suite
+3. Create PR for team review
+4. Merge when approved

package/commands/code-archaeology-survey.md

@@ -0,0 +1,48 @@
+---
+name: code-archaeology-survey
+description: Run Code Archaeology in survey mode — catalog artifacts only, zero file changes
+trigger:
+  - "archaeology survey"
+  - "code archaeology survey"
+  - "/archaeology-survey"
+---
+
+# Code Archaeology — Survey Mode
+
+Generate site reports only. Zero file changes. Use this for initial audits and management review.
+
+## Usage
+
+```
+Run: /code-archaeology-survey
+```
+
+## What It Does
+
+Runs all 10 expeditions in survey mode:
+- Catalogs every artifact found
+- Generates `.archaeology/expeditionN-report.md` for each phase
+- Produces `.archaeology/site_survey.md` baseline
+- Produces `.archaeology/FINAL_CATALOG.md` summary
+- Does NOT modify any source files
+
+## When to Use
+
+- First-time codebase audit
+- Management wants a technical debt report
+- Team is deciding whether to refactor
+- You want to know the scope before committing resources
+
+## Output
+
+All reports in `.archaeology/`:
+- `site_survey.md`
+- `expedition1-report.md` through `expedition8-report.md`
+- `FINAL_CATALOG.md`
+
+## Next Steps
+
+After reviewing reports:
+1. Decide which findings to address
+2. Run `/code-archaeology-excavate` to generate mock patches
+3. Or run `/code-archaeology-restore` to apply high-confidence fixes

package/commands/code-archaeology.md

@@ -0,0 +1,105 @@
+---
+name: code-archaeology
+description: Start a Code Archaeology expedition to excavate, catalog, and restore a codebase by removing technical debt systematically
+trigger:
+  - "start archaeology"
+  - "run archaeology"
+  - "code archaeology"
+  - "/archaeology"
+  - "/code-archaeology"
+---
+
+# Code Archaeology — Systematic Codebase Excavation
+
+Excavate, catalog, and restore a codebase by removing accumulated sediment: dead code, legacy fallbacks, circular dependencies, weak types, and defensive programming slop. Produces human-reviewable site reports before any artifacts are disturbed. Non-destructive by default.
+
+## Quick Start
+
+```
+Run: /code-archaeology
+```
+
+## What It Does
+
+1. **Surveys** the codebase — inventory, metrics, baseline
+2. **Excavates** dead code — unused exports, unreachable functions
+3. **Removes** legacy stratum — deprecated APIs, polyfills, shims
+4. **Maps** circular dependencies — cartography and remediation
+5. **Consolidates** types — deduplicate type definitions
+6. **Hardens** types — replace `any`/`unknown` with precise types
+7. **Enforces** DRY — extract semantic duplications
+8. **Fixes** error handling — remove suppression, add proper handling
+9. **Cleans** artifacts — documentation, formatting, remaining slop
+10. **Preserves** the site — final verification and catalog
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/code-archaeology` | Start full expedition (default: survey mode) |
+| `/code-archaeology-survey` | Site survey only — zero file changes |
+| `/code-archaeology-excavate` | Generate reports + mock patches for review |
+| `/code-archaeology-restore` | Execute approved changes after review |
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `repo_path` | `.` | Target repository |
+| `language` | `typescript` | Primary language |
+| `mode` | `survey` | `survey`, `excavate`, or `restore` |
+| `strict_mode` | `false` | Auto-restore medium-confidence findings |
+| `test_command` | `npm test` | Test runner command |
+| `typecheck_command` | `npx tsc --noEmit` | Type check command |
+| `branch_name` | `refactor/archaeology` | Git branch to create |
+
+## Requirements
+
+- Git repo with clean working tree
+- Passing test suite (even if minimal)
+- Type checker / linter installed
+- `opencode` CLI available
+
+## Safety
+
+- **Survey mode (default)**: Zero file changes. Only reports generated.
+- **Excavate mode**: Mock patches for human review. No actual modifications.
+- **Restore mode**: Applies approved changes. Always runs tests between phases.
+- **Branch isolation**: All work happens on `refactor/archaeology` (configurable).
+- **Test gating**: Any phase that breaks tests is automatically reverted.
+
+## Output Artifacts
+
+All artifacts are written to `.archaeology/`:
+
+- `site_survey.md` — baseline inventory and stratum graph
+- `expedition1-report.md` through `expedition8-report.md` — per-expedition findings
+- `FINAL_CATALOG.md` — completed excavation metrics and recommendations
+- `excavation_log.txt` — `git diff --stat`
+
+## Expedition Order (Fixed)
+
+The expeditions MUST run in this order due to stratigraphic dependencies:
+
+1. Site Survey & Baseline
+2. Dead Code Excavation
+3. Legacy Stratum Removal
+4. Circular Dependency Cartography
+5. Type Catalog Consolidation
+6. Type Restoration & Hardening
+7. DRY Stratification
+8. Error Handling Stratigraphy
+9. Artifact Cleaning & Documentation
+10. Site Preservation & Final Catalog
+
+## Language Support
+
+| Language | Dead Code | Dependencies | Types | DRY |
+|----------|-----------|--------------|-------|-----|
+| TypeScript | `knip` | `madge` | `tsc` | `jscpd` |
+| JavaScript | `knip` | `madge` | N/A | `jscpd` |
+| Python | `vulture` | `pydeps` | `mypy` | `pylint` |
+| Go | `deadcode` | `godepgraph` | `go vet` | `golangci-lint` |
+| Rust | `cargo-udeps` | `cargo-deps` | `rustc` | `clippy` |
+
+If tools are missing, falls back to AST-based manual analysis.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { PluginServer } from "./types.js";
+export declare const id = "code-archaeology";
+export declare const repoRoot: string;
+export declare const version: string;
+export declare function server(): Promise<PluginServer>;
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAO/C,eAAO,MAAM,EAAE,qBAAqB,CAAC;AACrC,eAAO,MAAM,QAAQ,QAAc,CAAC;AAGpC,eAAO,MAAM,OAAO,QAA2C,CAAC;AAEhE,wBAAsB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAMpD;AAED,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageRoot = resolve(__dirname, "..");
+export const id = "code-archaeology";
+export const repoRoot = packageRoot;
+const versionPath = resolve(packageRoot, "VERSION");
+export const version = readFileSync(versionPath, "utf8").trim();
+export async function server() {
+    return {
+        event() {
+            return undefined;
+        },
+    };
+}
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,MAAM,WAAW,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAE7C,MAAM,CAAC,MAAM,EAAE,GAAG,kBAAkB,CAAC;AACrC,MAAM,CAAC,MAAM,QAAQ,GAAG,WAAW,CAAC;AAEpC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AACpD,MAAM,CAAC,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;AAEhE,MAAM,CAAC,KAAK,UAAU,MAAM;IAC1B,OAAO;QACL,KAAK;YACH,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,cAAc,YAAY,CAAC"}