@0xcraft/powershot 1.1.4 → 1.2.0

package/README.md

@@ -123,8 +123,8 @@ oracle is never counted as a pass in either profile.
 | `phantom-dep` | Imports absent from project manifests | Dependency manifests |
 | `phantom-config` | Configuration keys with no declared source | Repository config index |
 | `contract-drift` | Signature changes with callers left behind | Types and references |
-| `reinvented` | New callables that exactly repeat an implementation already present in the same package | Base symbol + token fingerprint |
-| `dropped-guard` | Removed guards, early returns, protective branches | Pre/post AST |
+| `reinvented` | New cross-file declarations with a token-identical implementation, package, visibility, wrapper, and binding context | Base declaration + scoped token fingerprint |
+| `dropped-guard` | Early-exit guards deleted while every other token in the file and changed source set stays unchanged | Pre/post control-flow AST |
 | `swallowed-error` | Empty or ineffective error handling | AST shape |
 | `vacuous-test` | Tests that do not assert behavior | Test AST |
 | `assertion-drift` | Expectations changed under stable behavior | Pre/post test AST |
@@ -180,8 +180,8 @@ commands.
 flowchart LR
     START["Selected files and checks"] --> ACCOUNT{"Required work accounted for?"}
     ACCOUNT -- "yes" --> DEPTH{"Enriched semantic depth available?"}
-    DEPTH -- "yes" --> FULL["full coverage"]
-    DEPTH -- "no · portable policy" --> PORTABLE["portable coverage · gaps named"]
+    DEPTH -- "yes" --> FULL["full applicable-oracle coverage"]
+    DEPTH -- "no · portable policy" --> PORTABLE["portable oracle coverage · gaps named"]
     FULL --> FINDINGS{"Findings?"}
     PORTABLE --> FINDINGS
     FINDINGS -- "no" --> CLEAN["exit 0 · complete and clean"]
@@ -206,11 +206,11 @@ flowchart LR
 | `2` | Command or Git input was invalid |
 | `3` | Review is incomplete; findings may be missing |
 
-A clean report names its effective severity threshold, deterministic/model mode, file
-and check counts, and coverage level. A partial or failed review instead says it is not
-a verdict and keeps the missing work visible. Use `--format manifest` to inspect file
-dispositions, executed and unavailable checks, failures, judge units, and
-`notLookedAt`.
+A clean report names its effective severity threshold, deterministic/model mode,
+reviewed/changed file ratio, check count, and oracle coverage level. A partial or
+failed review instead says it is not a verdict and keeps the missing work visible. Use
+`--format manifest` to inspect file dispositions, executed and unavailable checks,
+failures, judge units, and `notLookedAt`.
 
 ## CI integration
 
@@ -298,6 +298,20 @@ psh delegate > /tmp/powershot-brief.md
 psh review --verify-only --absorb /tmp/powershot-findings.json
 ```
 
+Delegation uses the same `SelectionPlan` and target snapshot as a real review. The
+brief names every changed file as selected, policy-waived, or failed, so unsupported
+or oversized files cannot disappear between task creation and absorption. For an
+agent that consumes structured input, request the versioned task directly:
+
+```bash
+psh delegate --format json > /tmp/powershot-task.json
+```
+
+`powershot.delegate/v1` contains the resolved file dispositions, applicable judges,
+bounded review units, changed-line excerpts, intent, and the exact output contract.
+Creating either form is LLM-free and does not create a session. Deterministic checks
+run when the returned finding array is absorbed by `psh review --verify-only`.
+
 ## Language coverage
 
 | Language | Available oracles |

package/dist/cli/args.js

@@ -6,7 +6,8 @@ psh — code review for machine-written code
   psh review --from main --to feat/x  branch range
   psh review --commit <hash>          a single commit
   psh scan <path>                     audit existing files, no git history needed
-  psh delegate                        emit the judging work for an agent you already pay for
+  psh delegate [--format text|markdown|json]
+                                      emit a selection-accounted task for your existing agent
   psh session list | view <id>        runs that can be resumed, or replayed as a page
   psh session diff <a> <b>            what one review found that the other did not
   psh dismiss <id> [--reason "..."]   record that a finding is correct, and stop showing it

package/dist/cli/review-command.js

@@ -1,8 +1,8 @@
 import { createHash } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { Budget, parseLimits } from '#app/budget.js';
 import { loadConfig, policyChanged } from '#app/config.js';
-import { absorbDelegated, delegateBrief } from '#app/delegate.js';
+import { absorbDelegated, buildDelegateTask, delegateBrief, delegateJson } from '#app/delegate.js';
 import { baseRefOf, checkRange, headSha, repoRoot, shaOf } from '#app/git.js';
 import { JUDGES } from '#app/judges/prompts.js';
 import { RunManifest, coverageProblems, hashOf, writeManifest } from '#app/manifest.js';
@@ -13,6 +13,7 @@ import { progress, stage } from '#app/report/terminal.js';
 import { summarizeRun } from '#app/report/summary.js';
 import { review } from '#app/review.js';
 import { scanPaths } from '#app/scan.js';
+import { SelectionPlan } from '#app/plan.js';
 import { Session } from '#app/session.js';
 import { withTargetTree } from '#app/snapshot.js';
 import { SEVERITIES } from '#app/types.js';
@@ -33,6 +34,10 @@ export async function runReviewCommand(command, values, positionals) {
         process.stderr.write('--format must be one of: ' + REPORT_FORMATS.join(', ') + '\n');
         return 2;
     }
+    if (command === 'delegate' && !['text', 'markdown', 'json'].includes(values.format)) {
+        process.stderr.write('delegate --format must be one of: text, markdown, json\n');
+        return 2;
+    }
     if ((values.from && !values.to) || (values.to && !values.from)) {
         process.stderr.write('--from and --to must be given together.\n');
         return 2;
@@ -142,19 +147,32 @@ export async function runReviewCommand(command, values, positionals) {
     if (command === 'delegate') {
         const { buildGround } = await import('#app/ground.js');
         const { collectChanges, statedIntent } = await import('#app/git.js');
-        const { matchesAny } = await import('#app/config.js');
-        const changes = collectChanges(root, range).filter((change) => !matchesAny(change.path, config.ignore));
-        if (changes.length === 0) {
+        const all = collectChanges(root, range);
+        if (all.length === 0) {
             process.stderr.write('Nothing to review.\n');
             return 0;
         }
-        const ground = await withTargetTree(root, range, (tree) => buildGround(tree, changes));
-        process.stdout.write(delegateBrief(ground, config, {
-            intent: statedIntent(root, range),
-            maxBundleLines: maxBundle,
-            checks: requestedChecks,
-        }));
-        return 0;
+        const task = await withTargetTree(root, range, async (tree) => {
+            const plan = SelectionPlan.build(tree, all, config);
+            const selected = plan.keep(all);
+            const ground = await buildGround(tree, selected, undefined, all);
+            plan.accountForGround(selected, ground);
+            return buildDelegateTask(ground, config, plan.items(), {
+                intent: statedIntent(root, range),
+                maxBundleLines: maxBundle,
+                checks: requestedChecks,
+                target: { from: values.from, to: values.to, commit: values.commit },
+            });
+        });
+        const rendered = values.format === 'json' ? delegateJson(task) : delegateBrief(task);
+        if (values.output !== undefined) {
+            writeFileSync(values.output, rendered);
+            process.stderr.write(dim(' written to ' + values.output) + '\n');
+        }
+        else {
+            process.stdout.write(rendered);
+        }
+        return task.state === 'failed' ? 3 : 0;
     }
     const canceller = new AbortController();
     let interrupted = false;

package/dist/cli/session-command.js

@@ -46,6 +46,7 @@ export function runSessionCommand(positionals) {
             verifyOnly: session.report.verifyOnly,
             minSeverity: session.report.minSeverity,
             filesReviewed: session.report.filesReviewed,
+            filesChanged: session.report.filesChanged,
             deterministicChecks: session.report.deterministicChecks,
             scopeDetails: session.report.scopeDetails,
         }));

package/dist/delegate.js

@@ -2,44 +2,120 @@ import { bundle, bundleName } from './bundle.js';
 import { renderChanges } from './judges/judge.js';
 import { COMMON, JUDGES } from './judges/prompts.js';
 import { enabled } from './config.js';
-export function delegateBrief(g, cfg, opts) {
+import { stripPath } from './text.js';
+export const DELEGATE_SCHEMA = 'powershot.delegate/v1';
+export function buildDelegateTask(g, cfg, files, opts) {
     const units = bundle(g, opts.maxBundleLines ?? 1200);
     const judges = JUDGES.filter((j) => opts.checks ? opts.checks.includes(j.name) : enabled(cfg.judges, j.name));
+    return {
+        schema: DELEGATE_SCHEMA,
+        state: files.some((file) => file.disposition === 'failed') ? 'failed' : 'complete',
+        target: opts.target ?? {},
+        intent: opts.intent,
+        files: files.map(({ path, disposition, reason, bytes, addedLines, language }) => ({
+            path,
+            disposition,
+            reason,
+            bytes,
+            addedLines,
+            language,
+        })),
+        judges: judges.map((judge) => {
+            const usesIntent = judge.needsIntent === true;
+            const applicable = !usesIntent || Boolean(opts.intent);
+            return {
+                name: judge.name,
+                brief: judge.brief,
+                applicable,
+                usesIntent,
+                reason: applicable ? undefined : 'no stated intent available',
+            };
+        }),
+        instructions: {
+            summary: 'Perform only the judgement work in this task. PowerShot runs its deterministic checks when these findings are absorbed.',
+            groundRules: COMMON,
+            output: {
+                type: 'json-array',
+                empty: [],
+                example: [{
+                        file: 'src/a.ts',
+                        line: 12,
+                        severity: 'high',
+                        confidence: 'firm',
+                        check: 'plausible-logic',
+                        title: '…',
+                        why: '…',
+                        fix: '…',
+                    }],
+            },
+        },
+        units: units.map((unit, index) => ({
+            id: index + 1,
+            name: bundleName(unit, g.root),
+            files: unit.files.map((file) => file.path),
+            changes: renderChanges(unit.files),
+        })),
+    };
+}
+const cell = (value) => stripPath(value).replace(/\|/g, '\\|');
+export function delegateBrief(task) {
+    const scope = task.files.length === 0
+        ? ['_No changed files._']
+        : [
+            '| File | Disposition | Language | Added | Reason |',
+            '|---|---|---|---:|---|',
+            ...task.files.map((file) => '| ' + cell(file.path) + ' | ' + file.disposition + ' | ' + file.language + ' | ' + file.addedLines +
+                ' | ' + cell(file.reason ?? '') + ' |'),
+        ];
     const out = [
         '# PowerShot review brief',
         '',
-        'The deterministic checks have already run; what follows is the judgement work.',
+        task.instructions.summary,
         'Act as each judge below over each review unit, then reply with a single JSON array',
         'combining every finding. Add nothing outside the array.',
         '',
+        '## Scope',
+        '',
+        'Task state: **' + task.state + '**.',
+        '',
+        ...scope,
+        '',
         '## Output contract',
         '',
         '```json',
-        '[{"file":"src/a.ts","line":12,"severity":"high","confidence":"firm",',
-        '  "check":"plausible-logic","title":"…","why":"…","fix":"…"}]',
+        JSON.stringify(task.instructions.output.example, null, 2),
         '```',
         '',
-        'Return `[]` when a judge finds nothing. An empty array is a success, not a failure.',
+        'Return `' + JSON.stringify(task.instructions.output.empty) +
+            '` when a judge finds nothing. An empty array is a success, not a failure.',
         '',
         '## Ground rules',
         '',
-        COMMON,
+        task.instructions.groundRules,
         '',
     ];
-    for (const judge of judges) {
+    for (const judge of task.judges) {
         out.push('## Judge: ' + judge.name, '', judge.brief, '');
-        if (judge.needsIntent) {
-            out.push(opts.intent
-                ? 'This change states that it does the following:\n\n> ' + opts.intent.split('\n').join('\n> ')
+        if (judge.usesIntent) {
+            out.push(task.intent
+                ? 'This change states that it does the following:\n\n> ' + task.intent.split('\n').join('\n> ')
                 : '_No stated intent available (no commit in range) — skip this judge._', '');
         }
     }
     out.push('## Review units', '');
-    units.forEach((unit, i) => {
-        out.push('### Unit ' + (i + 1) + ' — ' + bundleName(unit, g.root), '', '```', renderChanges(unit.files), '```', '');
-    });
+    if (task.units.length === 0) {
+        out.push('_No judgement units. Every changed file was excluded or failed preparation; inspect Scope._', '');
+    }
+    else {
+        task.units.forEach((unit) => {
+            out.push('### Unit ' + unit.id + ' — ' + cell(unit.name), '', '```', unit.changes, '```', '');
+        });
+    }
     return out.join('\n');
 }
+export function delegateJson(task) {
+    return JSON.stringify(task, null, 2) + '\n';
+}
 export function absorbDelegated(json) {
     let parsed;
     try {

package/dist/git.js

@@ -89,7 +89,7 @@ function changedPaths(raw) {
         }
         const path = fields[i++];
         if (path)
-            out.push({ path, beforePath: status === 'A' ? undefined : path });
+            out.push({ path, beforePath: status === 'A' ? undefined : path, deleted: status === 'D' });
     }
     return out;
 }
@@ -195,9 +195,9 @@ export function collectChanges(root, range) {
     }
     const files = [];
     const tracked = changedPaths(git(root, [
-        'diff', '--name-status', '-z', '--diff-filter=ACMRT', '--find-renames', ...diffArgs,
+        'diff', '--name-status', '-z', '--diff-filter=ACDMRT', '--find-renames', ...diffArgs,
     ]));
-    for (const { path, beforePath } of tracked) {
+    for (const { path, beforePath, deleted } of tracked) {
         const pathspecs = beforePath && beforePath !== path
             ? [':(literal)' + beforePath, ':(literal)' + path]
             : [':(literal)' + path];
@@ -207,6 +207,8 @@ export function collectChanges(root, range) {
         ]);
         files.push({
             path,
+            beforePath: beforePath && beforePath !== path ? beforePath : undefined,
+            deleted,
             added: addedLinesInPatch(patch),
             before: beforePath === undefined ? undefined : fileAtRef(root, baseRef, beforePath),
         });

package/dist/ground.js

@@ -4,7 +4,7 @@ import { decode } from './text.js';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { PACKS, packFor, parseIsolated } from './lang/packs.js';
 import { insideRepo, isSymlink, repoPath } from './fspolicy.js';
-import { createReinventionScopeResolver, typescriptImplementationFingerprint } from './reinvention.js';
+import { createReinventionScopeResolver, exportedDeclarations, typescriptImplementationFingerprint } from './reinvention.js';
 const CODE_EXT = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
 const TS_CONFIG = /^tsconfig(?:\..+)?\.json$/i;
 const MISSING_TYPE_PREFIXES = [
@@ -216,7 +216,7 @@ function makeDepsFor(root) {
  * packages, a syntax-only project for unconfigured changes and the base-ref trees,
  * and one deduplicated symbol index over the relevant project closures.
  */
-export async function buildGround(root, changed, signal) {
+export async function buildGround(root, changed, signal, inventory = changed) {
     root = resolve(root);
     const directoryCache = new Map();
     const projectCache = new Map();
@@ -253,6 +253,7 @@ export async function buildGround(root, changed, signal) {
         }
     }
     const beforeProject = new Project({ useInMemoryFileSystem: true });
+    const beforeSources = new Map();
     const files = [];
     for (const c of changed) {
         if (!CODE_EXT.test(c.path))
@@ -264,7 +265,12 @@ export async function buildGround(root, changed, signal) {
         const sf = configured?.project.getSourceFile(abs) ?? syntaxProject.getSourceFile(abs);
         if (!sf)
             continue;
-        const before = c.before === undefined ? undefined : beforeProject.createSourceFile(`/before/${c.path}`, c.before, { overwrite: true });
+        const beforeKey = c.beforePath ?? c.path;
+        let before = c.before === undefined ? undefined : beforeSources.get(beforeKey);
+        if (c.before !== undefined && !before) {
+            before = beforeProject.createSourceFile(`/before/${beforeKey}`, c.before);
+            beforeSources.set(beforeKey, before);
+        }
         files.push({
             sf,
             changed: c,
@@ -289,6 +295,7 @@ export async function buildGround(root, changed, signal) {
         configFiles,
         beforeProject,
         changed,
+        inventory,
         files,
         symbolIndex: buildSymbolIndex(sourceFiles, root, changed, beforeProject),
         deps: depsFor(join(root, 'x.ts')),
@@ -465,24 +472,18 @@ function buildSymbolIndex(sourceFiles, root, changed, beforeProject) {
         // proof of where the file is
         if (path.includes('/node_modules/') || !insideRepo(root, path))
             continue;
-        for (const [name, decls] of sf.getExportedDeclarations()) {
+        for (const { name, node: decl } of exportedDeclarations(sf)) {
             const key = normalizeName(name);
             // Fingerprint only names the change could have introduced. This keeps index
             // construction proportional to the diff even when the project closure is a
             // very large monorepo.
             if (!relevantNames.has(key))
                 continue;
-            const decl = decls[0];
-            if (!decl)
-                continue;
             // only index things that could plausibly be reimplemented
             const kind = decl.getKind();
             if (kind !== SyntaxKind.FunctionDeclaration &&
                 kind !== SyntaxKind.VariableDeclaration)
                 continue;
-            const fingerprint = typescriptImplementationFingerprint(decl);
-            if (!fingerprint)
-                continue;
             // A barrel alias can be new in this change even when its underlying callable
             // predates it. Index the declaration from its own module, where both its name
             // and base existence can be proved, rather than manufacturing history for the
@@ -493,9 +494,15 @@ function buildSymbolIndex(sourceFiles, root, changed, beforeProject) {
             if (declPath.includes('/node_modules/') || !insideRepo(root, declPath))
                 continue;
             const rel = repoPath(root, declPath);
+            const fingerprint = typescriptImplementationFingerprint(decl, rel);
+            if (!fingerprint)
+                continue;
             const change = changes.get(rel);
-            const before = change?.before === undefined ? undefined : beforeProject.getSourceFile('/before/' + rel);
-            const existedInBase = change === undefined || (before?.getExportedDeclarations().get(name) ?? []).some((baseDeclaration) => typescriptImplementationFingerprint(baseDeclaration) === fingerprint);
+            const beforePath = change?.beforePath ?? rel;
+            const before = change?.before === undefined ? undefined : beforeProject.getSourceFile('/before/' + beforePath);
+            const sameScope = scopeFor(beforePath) === scopeFor(rel);
+            const existedInBase = change === undefined || (sameScope && before ? exportedDeclarations(before).some((baseDeclaration) => baseDeclaration.name === name &&
+                typescriptImplementationFingerprint(baseDeclaration.node, beforePath) === fingerprint) : false);
             const list = index.get(key) ?? [];
             if (list.some((e) => e.file === rel && e.line === decl.getStartLineNumber()))
                 continue;