@fraction12/deepclean 0.1.0-alpha.0

package/dist/verification.js

@@ -0,0 +1,111 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+export async function inferVerificationProfile(root) {
+    const [rootPackage, frontendPackage, adminPackage, makefile] = await Promise.all([
+        readPackageJson(path.join(root, "package.json")),
+        readPackageJson(path.join(root, "frontend", "package.json")),
+        readPackageJson(path.join(root, "admin", "package.json")),
+        readText(path.join(root, "Makefile")),
+    ]);
+    const rootCommands = packageCommands("", rootPackage);
+    const frontendCommands = packageCommands("frontend", frontendPackage);
+    const adminCommands = packageCommands("admin", adminPackage);
+    const pythonCommands = makefile
+        ? makeCommands(makefile)
+        : [];
+    return {
+        defaultCommands: unique([
+            ...rootCommands,
+            ...pythonCommands,
+            ...frontendCommands,
+            ...adminCommands,
+        ]).slice(0, 8),
+        pythonCommands: pythonCommands.length > 0 ? pythonCommands : rootCommands,
+        frontendCommands: frontendCommands.length > 0 ? frontendCommands : rootCommands,
+        adminCommands: adminCommands.length > 0 ? adminCommands : rootCommands,
+    };
+}
+export function commandsForFiles(profile, files, fallback = []) {
+    const commands = [];
+    const paths = files.map((file) => file.path);
+    if (paths.some((filePath) => filePath.startsWith("admin/"))) {
+        commands.push(...profile.adminCommands);
+    }
+    if (paths.some((filePath) => filePath.startsWith("frontend/"))) {
+        commands.push(...profile.frontendCommands);
+    }
+    if (paths.some((filePath) => (filePath.endsWith(".py")
+        || filePath.startsWith("backend/")
+        || filePath.startsWith("core/")
+        || filePath.startsWith("tests/")))) {
+        commands.push(...profile.pythonCommands);
+    }
+    const scoped = unique(commands).filter(Boolean);
+    if (scoped.length > 0) {
+        return scoped.slice(0, 6);
+    }
+    const defaults = profile.defaultCommands.length > 0 ? profile.defaultCommands : fallback;
+    return unique(defaults.length > 0 ? defaults : fallback).slice(0, 6);
+}
+export function mergeVerificationCommands(inferred, existing) {
+    const generic = new Set(["npm test", "npm run typecheck", "make test", "make typecheck"]);
+    const specific = existing.filter((command) => !generic.has(command));
+    const preferred = inferred.length > 0 ? inferred : existing;
+    return unique([...preferred, ...specific]).slice(0, 8);
+}
+function packageCommands(prefix, packageJson) {
+    const scripts = packageJson?.scripts;
+    if (!scripts) {
+        return [];
+    }
+    const commands = [];
+    if (scripts["typecheck"]) {
+        commands.push(npmCommand(prefix, "typecheck"));
+    }
+    if (scripts["lint"]) {
+        commands.push(npmCommand(prefix, "lint"));
+    }
+    if (scripts["test:run"]) {
+        commands.push(npmCommand(prefix, "test:run"));
+    }
+    else if (scripts["test"]) {
+        commands.push(npmCommand(prefix, "test"));
+    }
+    if (scripts["build"]) {
+        commands.push(npmCommand(prefix, "build"));
+    }
+    return commands;
+}
+function npmCommand(prefix, script) {
+    const command = `npm run ${script}`;
+    return prefix ? `cd ${prefix} && ${command}` : command;
+}
+function makeCommands(makefile) {
+    const targets = new Set(makefile
+        .split("\n")
+        .map((line) => line.match(/^([a-zA-Z0-9_-]+):/)?.[1])
+        .filter((value) => Boolean(value)));
+    return ["lint", "typecheck", "test"]
+        .filter((target) => targets.has(target))
+        .map((target) => `make ${target}`);
+}
+async function readPackageJson(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readText(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+//# sourceMappingURL=verification.js.map

package/dist/verification.js.map

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

package/docs/privacy-and-trust.md

@@ -0,0 +1,33 @@
+# Privacy And Trust
+
+Deepclean public alpha is report-first. It does not edit application source code.
+
+## Writes
+
+Deepclean writes state and artifacts under `.deepclean/` in the target repository:
+
+- `.deepclean/config.json`
+- `.deepclean/runs/`
+- `.deepclean/evidence/`
+- `.deepclean/candidates/`
+- `.deepclean/clusters/`
+- `.deepclean/reports/`
+- `.deepclean/plans/`
+- `.deepclean/handoffs/`
+- `.deepclean/triage/`
+
+Add `.deepclean/` to `.gitignore` unless a repo deliberately wants to share reports.
+
+## Local Evidence
+
+`deepclean scan` reads source files and repository metadata locally. It records structured evidence such as file metrics, duplicate windows, import graph summaries, TypeScript/Python structure, git churn, and test-discovery signals.
+
+## Codex Synthesis
+
+`deepclean scan --synthesize` invokes the local `codex` command in read-only mode. By default the prompt includes structured evidence and redacts source samples. It does not dynamically load OpenClaw skills or arbitrary local agent instructions; the built-in reviewer pack is recorded in candidate provenance.
+
+Use `--allow-source-in-model` only when the target repo and configured provider are allowed to receive source excerpts. This may include snippets from files that triggered local evidence.
+
+## Network
+
+Deepclean does not do web research in public alpha. `privacy.allowWebResearch` is reserved for a future explicit feature and defaults to `false`.

package/docs/public-readiness.md

@@ -0,0 +1,19 @@
+# Public Readiness Notes
+
+Deepclean is now shaped like a public CLI rather than a local experiment:
+
+- `.deepclean/`, local agent folders, logs, tarballs, dependencies, and build output are ignored.
+- CI runs typecheck, tests, build, package smoke, and optional OpenSpec validation.
+- `npm run release:check` validates the packed tarball and rejects private artifacts.
+- Reports are source-safe by default and source excerpts are not sent to Codex unless explicitly enabled.
+- External analyzer evidence can be ingested through SARIF and optional `jscpd`.
+- Codex synthesis now uses a built-in reviewer pack informed by a vendored MIT-licensed Matt Pocock skills snapshot, while keeping runtime prompts reproducible and source-safe.
+- Reports now separate the agent queue from raw candidate evidence, return explicit artifact paths in JSON, and infer verification commands from the target repository's Makefile and package scripts.
+
+## Still Deliberately Deferred
+
+- Naming and brand decisions.
+- Fix/recheck/open-pr loop.
+- npm publish.
+
+Those are product/release decisions, not accidental implementation gaps.

package/docs/reviewer-references.md

@@ -0,0 +1,33 @@
+# Reviewer References
+
+Deepclean keeps its synthesis reviewer pack built in, but it now uses a vendored Matt Pocock skills snapshot as a reference source for reviewer design.
+
+## Matt Pocock Skills Snapshot
+
+- Source: <https://github.com/mattpocock/skills>
+- Snapshot: `third_party/matt-pocock-skills/`
+- License: MIT, Copyright (c) 2026 Matt Pocock
+- Snapshot commit: recorded in `third_party/matt-pocock-skills/SNAPSHOT.md`
+
+The snapshot is not loaded dynamically during public-alpha scans. Runtime synthesis uses distilled reviewer rubrics in `src/reviewers.ts` so outputs are reproducible and package installs do not depend on private agent workspaces or live network access.
+
+## Distilled Reviewer Additions
+
+The default reviewer pack now includes Matt Pocock-inspired rubrics for:
+
+- deep module discipline
+- feedback loop discipline
+- agent-ready cleanup slices
+
+These complement the existing Deepclean reviewers for architecture, duplication, dependency graph shape, testability, domain language, AI-slop patterns, and critic pass.
+
+## Update Policy
+
+When refreshing the snapshot:
+
+1. Run `npm run sync:matt-skills`.
+2. Review upstream license and repository shape before copying any new guidance into reviewer rubrics.
+3. Keep the upstream MIT license and copyright notice.
+4. Confirm `third_party/matt-pocock-skills/SNAPSHOT.md` records the new commit.
+5. Distill useful engineering principles into built-in rubrics instead of dumping the full upstream skill text into every prompt.
+6. Run `npm run release:check` and `npm run spec:validate`.

package/docs/troubleshooting.md

@@ -0,0 +1,80 @@
+# Troubleshooting
+
+## Codex Is Missing
+
+Run:
+
+```bash
+codex --version
+```
+
+If that fails, install or configure the Codex CLI before using `deepclean scan --synthesize`. Plain `deepclean scan` still works without Codex.
+
+## Codex Auth Fails
+
+If synthesis reports an auth or login warning, re-authenticate Codex in the local environment and rerun:
+
+```bash
+deepclean scan --synthesize --json
+```
+
+Deepclean preserves local evidence and local candidates when synthesis fails.
+
+## Codex Times Out
+
+Increase `.deepclean/config.json`:
+
+```json
+{
+  "reviewSynthesis": {
+    "timeoutMs": 180000
+  }
+}
+```
+
+Large repos should also tune `candidateCaps` and `clusters` before synthesis.
+
+## Missing Git History
+
+The git-history adapter is skipped when the target directory is not a git repository. The rest of the scan still runs.
+
+## Noisy Reports
+
+Use candidate caps and broad-theme controls:
+
+```json
+{
+  "candidateCaps": {
+    "byKind": {
+      "duplicate-cluster": 8
+    },
+    "byKindAndArea": {
+      "large-file": 4
+    }
+  },
+  "clusters": {
+    "maxCandidates": 10,
+    "maxFiles": 12,
+    "splitBroad": true
+  }
+}
+```
+
+Themes marked `too-broad` should be split or triaged before handing work to an agent.
+
+## External Analyzer Evidence
+
+Deepclean can ingest SARIF files from tools such as Semgrep when they are present at configured paths:
+
+```bash
+semgrep scan --sarif --output semgrep.sarif
+deepclean scan --json
+```
+
+Optional `jscpd` evidence is disabled by default because it requires the `jscpd` command locally:
+
+```bash
+npm install -g jscpd
+```
+
+Then enable it in `.deepclean/config.json`.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@fraction12/deepclean",
+  "version": "0.1.0-alpha.0",
+  "private": false,
+  "description": "Clawpatch-style cleanup reports for working-but-sloppy codebases.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/fraction12/deepclean#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fraction12/deepclean.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fraction12/deepclean/issues"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs/privacy-and-trust.md",
+    "docs/public-readiness.md",
+    "docs/reviewer-references.md",
+    "docs/troubleshooting.md"
+  ],
+  "bin": {
+    "deepclean": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "ci": "npm run typecheck && npm test && npm run build && npm run smoke:package",
+    "dev": "tsx src/cli.ts",
+    "release:check": "npm run ci && node scripts/release-check.mjs",
+    "spec:validate": "node scripts/spec-validate.mjs",
+    "sync:matt-skills": "node scripts/sync-matt-pocock-skills.mjs",
+    "test": "vitest run src/cli.test.ts",
+    "smoke:package": "npm run build && node scripts/package-smoke.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "typescript": "^6.0.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "tsx": "^4.22.3",
+    "vitest": "^4.1.6"
+  }
+}