refactor: remove dead code and add knip for dead export detection

.claude/agent-memory/archgate-developer/MEMORY.md

@@ -4,7 +4,7 @@
 
 Every work loop MUST end with these steps — no exceptions, even for trivial changes:
 
-1. **`bun run validate`** — lint, typecheck, format, test, ADR check (fail-fast)
+1. **`bun run validate`** — lint, typecheck, format, test, ADR check, knip, build check (fail-fast)
 2. **`@architect` skill** — Invoke via `Skill tool` with skill `"archgate:architect"`. Validates structural ADR compliance beyond automated rules.
 3. **`@quality-manager` skill** — Invoke via `Skill tool` with skill `"archgate:quality-manager"`. Captures learnings and governance gaps.
 
@@ -54,7 +54,7 @@ Skipping steps 2 or 3 is a workflow violation. The user should NEVER have to inv
 
 ## Validation Pipeline
 
-- `bun run validate` is the mandatory gate: lint → typecheck → format:check → test → ADR check → build:check
+- `bun run validate` is the mandatory gate: lint → typecheck → format:check → test → ADR check → knip → build:check
 - All ADR rule severities are `error` (not `warning`) — violations are hard blockers
 - The pipeline is fail-fast — fix failures in order
 

CLAUDE.md

@@ -7,7 +7,7 @@ Archgate is a CLI tool for AI governance via Architecture Decision Records (ADRs
 - **Runtime:** Bun (>=1.2.21) — not Node.js compatible
 - **Language:** TypeScript (strict mode, ESNext, ES modules)
 - **CLI framework:** Commander.js (`@commander-js/extra-typings`)
-- **Linter:** Oxlint | **Formatter:** Oxfmt | **Commits:** Conventional Commits
+- **Linter:** Oxlint | **Formatter:** Oxfmt | **Dead exports:** Knip | **Commits:** Conventional Commits
 
 ## Commands
 
@@ -18,14 +18,15 @@ bun run typecheck             # tsc --build
 bun run format                # oxfmt --write
 bun run format:check          # oxfmt --check
 bun test                      # all tests
-bun run validate              # MANDATORY: lint + typecheck + format + test + ADR check + build check
+bun run knip                  # dead export detection
+bun run validate              # MANDATORY: lint + typecheck + format + test + ADR check + knip + build check
 bun run build:check            # verify build compiles (CI builds binaries via release workflow)
 bun run commit                # conventional commit wizard
 ```
 
 ## Validation Gate
 
-**`bun run validate` must pass before any task is considered complete.** Fail-fast pipeline: lint → typecheck → format → test → ADR check → build check. Mirrors CI in `.github/workflows/code-pull-request.yml`.
+**`bun run validate` must pass before any task is considered complete.** Fail-fast pipeline: lint → typecheck → format → test → ADR check → knip → build check. Mirrors CI in `.github/workflows/code-pull-request.yml`.
 
 ## Architecture
 

knip.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/knip@6/schema.json",
+  "entry": ["tests/**/*.test.ts"],
+  "project": ["src/**/*.ts", "tests/**/*.ts"],
+  "ignore": ["tests/fixtures/**"],
+  "ignoreDependencies": [
+    "@commitlint/cli",
+    "@simple-release/npm",
+    "conventional-changelog-angular"
+  ],
+  "ignoreBinaries": ["tsc"],
+  "ignoreExportsUsedInFile": true,
+  "tags": ["-internal"]
+}

package.json

@@ -47,14 +47,15 @@
     "docs:preview": "cd docs && bunx --bun astro preview",
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check .",
+    "knip": "knip",
     "lint": "oxlint --deny-warnings .",
     "postinstall": "node scripts/postinstall.cjs",
     "test": "bun test --timeout 60000",
     "test:coverage": "bun test --timeout 60000 --coverage --reporter=junit --reporter-outfile=coverage/junit.xml",
     "test:watch": "bun test --watch --timeout 60000",
     "typecheck": "tsc --build",
-    "validate": "bun run lint && bun run typecheck && bun run format:check && bun run test && bun run check && bun run build:check",
-    "validate:coverage": "bun run lint && bun run typecheck && bun run format:check && bun run test:coverage && bun run check && bun run build:check"
+    "validate": "bun run lint && bun run typecheck && bun run format:check && bun run test && bun run check && bun run knip && bun run build:check",
+    "validate:coverage": "bun run lint && bun run typecheck && bun run format:check && bun run test:coverage && bun run check && bun run knip && bun run build:check"
   },
   "devDependencies": {
     "@commander-js/extra-typings": "14.0.0",
@@ -68,6 +69,7 @@
     "czg": "1.13.0",
     "fast-check": "4.7.0",
     "inquirer": "13.4.2",
+    "knip": "6.12.1",
     "meriyah": "7.1.0",
     "oxfmt": "0.47.0",
     "oxlint": "1.62.0",

src/commands/upgrade.ts

@@ -381,6 +381,7 @@ export function registerUpgradeCommand(program: Command) {
     });
 }
 
+/** @internal test hooks — consumed via dynamic import() in upgrade.test.ts */
 export {
   isBinaryInstall as _isBinaryInstall,
   isProtoInstall as _isProtoInstall,

src/engine/context.ts

@@ -5,7 +5,7 @@ import type { ReportSummary } from "./reporter";
 import { buildSummary } from "./reporter";
 import { runChecks } from "./runner";
 
-export interface AdrBriefing {
+interface AdrBriefing {
   id: string;
   title: string;
   domain: AdrDomain;
@@ -15,13 +15,13 @@ export interface AdrBriefing {
   dosAndDonts: string;
 }
 
-export interface DomainContext {
+interface DomainContext {
   domain: AdrDomain;
   changedFiles: string[];
   adrs: AdrBriefing[];
 }
 
-export interface ReviewContext {
+interface ReviewContext {
   allChangedFiles: string[];
   truncatedFiles: boolean;
   domains: DomainContext[];
@@ -69,7 +69,7 @@ export function extractAdrSections(
   return result;
 }
 
-export interface BriefAdrOptions {
+interface BriefAdrOptions {
   /** Max chars per section. 0 = unlimited. Default: 2000. */
   maxSectionChars?: number;
 }
@@ -190,7 +190,7 @@ const EMPTY_SUMMARY: ReportSummary = {
   durationMs: 0,
 };
 
-export interface BuildReviewContextOptions {
+interface BuildReviewContextOptions {
   runChecks?: boolean;
   staged?: boolean;
   domain?: AdrDomain;

src/engine/git-files.ts

@@ -56,11 +56,6 @@ export function getGitTrackedFiles(
   return promise;
 }
 
-/** Reset the tracked-files cache. For testing only. */
-export function _resetGitFilesCache(): void {
-  trackedFilesCache.clear();
-}
-
 /** Resolve scoped files for an ADR based on its files globs. Respects .gitignore. */
 export async function resolveScopedFiles(
   projectRoot: string,

src/engine/loader.ts

@@ -30,12 +30,12 @@ import { projectPaths } from "../helpers/paths";
 import { ensureRulesShim } from "../helpers/rules-shim";
 import { scanRuleSource } from "./rule-scanner";
 
-export interface LoadedAdr {
+interface LoadedAdr {
   adr: AdrDocument;
   ruleSet: RuleSet;
 }
 
-export interface BlockedAdr {
+interface BlockedAdr {
   adr: AdrDocument;
   error: string;
   violations: Array<{
@@ -137,7 +137,7 @@ function checkRuleSyntax(source: string): SyntaxViolation[] {
   return violations;
 }
 
-export interface ParsedAdrEntry {
+interface ParsedAdrEntry {
   file: string;
   adr: AdrDocument;
 }
@@ -153,11 +153,6 @@ export interface ParsedAdrEntry {
  */
 const parsedAdrsCache = new Map<string, Promise<ParsedAdrEntry[]>>();
 
-/** Reset the parsed-ADRs cache. For testing only. */
-export function _resetAdrParseCache(): void {
-  parsedAdrsCache.clear();
-}
-
 /**
  * Read and parse every ADR markdown file in the project, caching the result
  * per-process. Returns entries in directory order. Unparseable files are

src/engine/reporter.ts

@@ -36,7 +36,7 @@ export interface ReportSummary {
   durationMs: number;
 }
 
-export interface BuildSummaryOptions {
+interface BuildSummaryOptions {
   /** Maximum violations per rule. When exceeded, only the first N are kept. Omit or 0 for unlimited. */
   maxViolationsPerRule?: number;
 }

src/engine/runner.ts

@@ -56,7 +56,7 @@ function safeGlob(pattern: string): void {
 }
 const RULE_TIMEOUT_MS = 30_000;
 
-export interface RuleResult {
+interface RuleResult {
   ruleId: string;
   adrId: string;
   description: string;

src/engine/source-positions.ts

@@ -3,7 +3,7 @@
  * original TypeScript source, skipping matches in comments and strings.
  */
 
-export interface SourcePos {
+interface SourcePos {
   line: number;
   column: number;
   endLine: number;

src/formats/project-config.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
 export const DOMAIN_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
-export const DOMAIN_PREFIX_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+const DOMAIN_PREFIX_PATTERN = /^[A-Z][A-Z0-9_]*$/;
 
 export const DomainNameSchema = z
   .string()

src/helpers/adr-writer.ts

@@ -65,7 +65,7 @@ ${opts.body}
   });
 }
 
-export interface CreateAdrResult {
+interface CreateAdrResult {
   id: string;
   fileName: string;
   filePath: string;
@@ -138,7 +138,7 @@ export async function findAdrFileById(
   return results.find((adr) => adr?.frontmatter.id === id) ?? null;
 }
 
-export interface UpdateAdrResult {
+interface UpdateAdrResult {
   id: string;
   fileName: string;
   filePath: string;

src/helpers/auth.ts

@@ -27,7 +27,7 @@ const GITHUB_CLIENT_ID = "Ov23liZUI9Aiv2ZrSAgn";
 // Types
 // ---------------------------------------------------------------------------
 
-export interface DeviceCodeResponse {
+interface DeviceCodeResponse {
   device_code: string;
   user_code: string;
   verification_uri: string;
@@ -151,7 +151,7 @@ export async function pollForAccessToken(
   throw new Error("Device code expired. Please try again.");
 }
 
-export interface GitHubUserInfo {
+interface GitHubUserInfo {
   login: string;
   email: string | null;
 }

src/helpers/init-project.ts

@@ -29,21 +29,21 @@ export const EDITOR_LABELS: Record<EditorTarget, string> = {
   opencode: "opencode",
 };
 
-export interface InitOptions {
+interface InitOptions {
   editor?: EditorTarget;
   /** When true, attempt to install the archgate plugin using stored credentials. */
   installPlugin?: boolean;
 }
 
-export interface PluginResult {
+interface PluginResult {
   installed: boolean;
   /** For claude manual: marketplace URL; for cursor: file count summary */
   detail?: string;
   /** When true, plugin was auto-installed via editor CLI (no manual steps needed). */
   autoInstalled?: boolean;
 }
 
-export interface InitResult {
+interface InitResult {
   projectRoot: string;
   adrsDir: string;
   lintDir: string;

src/helpers/log.ts

@@ -31,11 +31,6 @@ export function setLogLevel(level: LogLevel): void {
   }
 }
 
-/** Get the current log level. */
-export function getLogLevel(): LogLevel {
-  return currentLevel;
-}
-
 function isEnabled(level: LogLevel): boolean {
   return LOG_LEVEL_PRIORITY[level] <= LOG_LEVEL_PRIORITY[currentLevel];
 }

src/helpers/paths.ts

@@ -70,24 +70,6 @@ export function copilotSessionStateDir(): string {
   return join(archgateHomeDir(), ".copilot", "session-state");
 }
 
-/**
- * Resolve the opencode data storage directory.
- *
- * Opencode stores sessions, messages, and parts under
- * `$XDG_DATA_HOME/opencode/storage/` (defaulting to
- * `~/.local/share/opencode/storage/`). This is distinct from the
- * config directory (`$XDG_CONFIG_HOME/opencode/`) used by
- * `opencodeAgentsDir()`.
- *
- * Resolved at call time (not cached) so tests can override HOME /
- * XDG_DATA_HOME.
- */
-export function opencodeStorageDir(): string {
-  const xdg = usableEnv(Bun.env.XDG_DATA_HOME);
-  const base = xdg ?? join(archgateHomeDir(), ".local", "share");
-  return join(base, "opencode", "storage");
-}
-
 /**
  * Resolve the opencode SQLite database path.
  *

src/helpers/platform.ts

@@ -97,13 +97,6 @@ export function isSupportedPlatform(): boolean {
   return runtime === "darwin" || runtime === "linux" || runtime === "win32";
 }
 
-/**
- * Reset the cached platform info. For testing only.
- */
-export function _resetPlatformCache(): void {
-  cachedPlatformInfo = null;
-}
-
 // ---------------------------------------------------------------------------
 // Path Conversion (async, WSL only)
 // ---------------------------------------------------------------------------

src/helpers/repo-probe.ts

@@ -55,11 +55,6 @@ export function _resetPublicProbeCache(): void {
   cachedPublicProbe = null;
 }
 
-/** Inject a probe result. For testing only. */
-export function _setPublicProbeForTest(value: boolean | null): void {
-  cachedPublicProbe = Promise.resolve(value);
-}
-
 // ---------------------------------------------------------------------------
 // Dispatch
 // ---------------------------------------------------------------------------

src/helpers/repo.ts

@@ -21,15 +21,11 @@
 import { createHash } from "node:crypto";
 
 import { logDebug } from "./log";
-import {
-  _resetPublicProbeCache,
-  _setPublicProbeForTest,
-  isPublicRepo,
-} from "./repo-probe";
+import { _resetPublicProbeCache, isPublicRepo } from "./repo-probe";
 
 // Re-export the public-visibility probe so commands / telemetry can import
 // everything repo-related from one place.
-export { isPublicRepo, _setPublicProbeForTest };
+export { isPublicRepo };
 
 // ---------------------------------------------------------------------------
 // Types

src/helpers/session-context-copilot.ts

@@ -10,15 +10,15 @@ import {
   getContentPreview,
 } from "./session-context";
 
-export interface CopilotSessionSummary {
+interface CopilotSessionSummary {
   sessionId: string;
   sessionFile: string;
   totalEntries: number;
   relevantEntries: number;
   transcript: Array<{ role: string; contentPreview: string }>;
 }
 
-export interface ReadCopilotSessionOptions extends ReadSessionOptions {
+interface ReadCopilotSessionOptions extends ReadSessionOptions {
   sessionId?: string;
 }
 

src/helpers/session-context-opencode.ts

@@ -12,14 +12,14 @@ import {
   getContentPreview,
 } from "./session-context";
 
-export interface OpencodeSessionSummary {
+interface OpencodeSessionSummary {
   sessionId: string;
   totalEntries: number;
   relevantEntries: number;
   transcript: Array<{ role: string; contentPreview: string }>;
 }
 
-export interface ReadOpencodeSessionOptions extends ReadSessionOptions {
+interface ReadOpencodeSessionOptions extends ReadSessionOptions {
   sessionId?: string;
 }