@0xcraft/powershot 1.1.4 → 1.2.0

package/dist/verifiers/foreign-tokens.js

@@ -1,14 +1,28 @@
+import { posix } from 'node:path';
 import { nodesOfType, walk } from '#app/lang/packs.js';
+import { implementationFingerprint } from '#app/reinvention.js';
 /**
- * In tree-sitter-rust and -go a `string_literal` has exactly two children, the quotes,
- * and the text between them belongs to no node — so walking to leaves loses it, and
- * two files differing only in what their strings say tokenize identically. Atomic.
+ * Some wasm grammars leave meaningful text outside child nodes: Rust/Go string
+ * contents and Kotlin's nullable `?` are examples. Keep those enclosing nodes atomic
+ * so a value or contract change cannot disappear from the fingerprint.
  */
-const ATOMIC = /string|char|raw_|heredoc|interpolat/;
+const ATOMIC = /string|char|raw_|heredoc|interpolat|nullable_type/;
 /** The token stream: what a compiler sees, minus layout and comments. */
-export function tokensFor(root, pack) {
+function nodeKey(node) {
+    return [
+        node.type,
+        node.startPosition.row,
+        node.startPosition.column,
+        node.endPosition.row,
+        node.endPosition.column,
+    ].join(':');
+}
+export function tokensFor(root, pack, exclude) {
     const out = [];
+    const excluded = new Set((exclude === undefined ? [] : Array.isArray(exclude) ? exclude : [exclude]).map(nodeKey));
     const visit = (n) => {
+        if (excluded.has(nodeKey(n)))
+            return;
         if (pack.nodes.comment.includes(n.type))
             return;
         if (ATOMIC.test(n.type)) {
@@ -29,6 +43,13 @@ export function tokensFor(root, pack) {
     visit(root);
     return out;
 }
+/** Tokens that affect compilation, including comment-shaped file constraints. */
+export function sourceTokensFor(root, pack, exclude) {
+    return [
+        ...(pack.fileConstraints?.(root) ?? []).map((text) => ({ type: '__file_constraint__', text })),
+        ...tokensFor(root, pack, exclude),
+    ];
+}
 export function commentText(root, pack) {
     const parts = [];
     walk(root, (n) => {
@@ -52,6 +73,16 @@ export function documentsSomething(root, pack) {
 export function same(a, b) {
     return a.length === b.length && a.every((t, i) => t.type === b[i].type && t.text === b[i].text);
 }
+/** Layout-insensitive identity of a file's declared package/module, when it has one. */
+export function fileScopeIdentity(root, pack) {
+    const tokens = root.namedChildren
+        .filter((child) => pack.nodes.fileScope.includes(child.type))
+        .flatMap((child) => tokensFor(child, pack));
+    const constraints = pack.fileConstraints?.(root) ?? [];
+    return tokens.length === 0 && constraints.length === 0
+        ? undefined
+        : 'file:' + JSON.stringify({ tokens, constraints });
+}
 export function finding(file, node, f) {
     return {
         id: '',
@@ -78,20 +109,198 @@ export function declaredName(decl, pack) {
     // C and C++ wrap the name in a declarator; look inside that, never wider
     return nodesOfType(field, pack.nodes.identifier)[0]?.text;
 }
-/** Module level only: two classes sharing a method name is polymorphism. */
-export function topLevelDeclarations(root, pack) {
-    const all = nodesOfType(root, pack.nodes.declaration);
-    const out = new Map();
-    for (const decl of all) {
-        const nested = all.some((other) => other !== decl &&
-            other.startPosition.row <= decl.startPosition.row &&
-            other.endPosition.row >= decl.endPosition.row);
-        if (nested)
-            continue;
-        const name = declaredName(decl, pack);
-        if (name)
-            out.set(name, decl);
+export function reusableDeclarations(root, pack, bindingPath = '') {
+    const raw = [];
+    const contexts = [];
+    const bindings = [];
+    const namesIn = (tokens) => [
+        ...new Set(tokens.filter((token) => pack.nodes.bindingIdentifier.includes(token.type)).map((token) => token.text)),
+    ];
+    const addBinding = (scope, node, tokens, indexNames) => {
+        if (indexNames.length > 0) {
+            bindings.push({
+                node,
+                tokens,
+                scope,
+                indexNames,
+                references: namesIn(tokens),
+                fingerprint: implementationFingerprint([
+                    { type: '__binding_scope__', text: JSON.stringify(scope) },
+                    ...tokens,
+                ]),
+            });
+        }
+    };
+    const visit = (container, scope, fingerprintRoot) => {
+        let prefix = [];
+        let blocked = false;
+        for (const child of container.namedChildren) {
+            if (pack.nodes.comment.includes(child.type))
+                continue;
+            if (pack.nodes.reusablePrefix.includes(child.type)) {
+                prefix.push(child);
+                continue;
+            }
+            if (pack.nodes.reusableBlocker.includes(child.type)) {
+                blocked = true;
+                continue;
+            }
+            if (pack.nodes.bindingContext.includes(child.type)) {
+                contexts.push({ scope, node: child, tokens: tokensFor(child, pack) });
+                prefix = [];
+                blocked = false;
+                continue;
+            }
+            if (pack.nodes.reusableDeclaration.includes(child.type)) {
+                if (blocked || (pack.reusableAcrossFiles && !pack.reusableAcrossFiles(child))) {
+                    prefix = [];
+                    blocked = false;
+                    continue;
+                }
+                const name = declaredName(child, pack);
+                if (!name) {
+                    if (pack.nodes.bindingDeclaration.includes(child.type)) {
+                        const bindingTokens = tokensFor(child, pack);
+                        addBinding(scope, child, bindingTokens, namesIn(bindingTokens));
+                    }
+                    prefix = [];
+                    blocked = false;
+                    continue;
+                }
+                const ownTokens = [
+                    ...prefix.flatMap((node) => tokensFor(node, pack)),
+                    ...tokensFor(fingerprintRoot ?? child, pack),
+                ];
+                raw.push({
+                    scope,
+                    name,
+                    node: child,
+                    tokens: ownTokens,
+                });
+                addBinding(scope, child, ownTokens, [name]);
+                prefix = [];
+                blocked = false;
+                continue;
+            }
+            if (pack.nodes.bindingDeclaration.includes(child.type)) {
+                const bindingTokens = tokensFor(child, pack);
+                addBinding(scope, child, bindingTokens, namesIn(bindingTokens));
+                prefix = [];
+                blocked = false;
+                continue;
+            }
+            if (!pack.nodes.reusableContainer.includes(child.type)) {
+                prefix = [];
+                blocked = false;
+                continue;
+            }
+            let nextScope = scope;
+            if (pack.nodes.reusableScope.includes(child.type)) {
+                const name = child.childForFieldName('name')?.text;
+                // An anonymous namespace cannot provide a cross-file reuse candidate.
+                if (!name)
+                    continue;
+                nextScope = [...scope, name];
+            }
+            visit(child, nextScope, fingerprintRoot ?? (pack.nodes.reusableWrapper.includes(child.type) ? child : undefined));
+            prefix = [];
+            blocked = false;
+        }
+    };
+    const fileScope = fileScopeIdentity(root, pack);
+    visit(root, fileScope ? [fileScope] : []);
+    const scopeKey = (scope) => JSON.stringify(scope);
+    const scopePrefixes = (scope) => Array.from({ length: scope.length + 1 }, (_, length) => scopeKey(scope.slice(0, length)));
+    const byName = new Map();
+    for (const binding of bindings) {
+        for (const name of binding.indexNames) {
+            const byScope = byName.get(name) ?? new Map();
+            const scoped = byScope.get(scopeKey(binding.scope)) ?? [];
+            scoped.push(binding);
+            byScope.set(scopeKey(binding.scope), scoped);
+            byName.set(name, byScope);
+        }
     }
-    return out;
+    const needsBindingDirectory = (tokens) => {
+        const text = tokens.map((token) => token.text).join(' ');
+        return /\brequire_relative\b|\b(?:require|include)(?:_once)?\b|\bfrom\s+\.+|["']\.\.?\/|#\s*include\s*"|\buse\s+(?:self|super)\s*::|\bmod\s+[A-Za-z_]\w*\s*;/.test(text);
+    };
+    const contextsByScope = new Map();
+    for (const context of contexts) {
+        const scoped = contextsByScope.get(scopeKey(context.scope)) ?? [];
+        scoped.push(context);
+        contextsByScope.set(scopeKey(context.scope), scoped);
+    }
+    const contextCache = new Map();
+    const contextFor = (scope) => {
+        const key = scopeKey(scope);
+        const known = contextCache.get(key);
+        if (known)
+            return known;
+        const visibleContexts = scopePrefixes(scope)
+            .flatMap((prefix) => contextsByScope.get(prefix) ?? [])
+            .sort((left, right) => left.node.startPosition.row - right.node.startPosition.row ||
+            left.node.startPosition.column - right.node.startPosition.column);
+        const ordered = visibleContexts.flatMap((context) => [
+            { type: '__binding_scope__', text: JSON.stringify(context.scope) },
+            ...context.tokens,
+        ]);
+        const value = {
+            tokens: ordered.length === 0
+                ? []
+                : [{ type: '__binding_context__', text: implementationFingerprint(ordered) }],
+            needsDirectory: visibleContexts.some((context) => needsBindingDirectory(context.tokens)),
+        };
+        contextCache.set(key, value);
+        return value;
+    };
+    const identity = (node) => [
+        node.type,
+        node.startPosition.row,
+        node.startPosition.column,
+        node.endPosition.row,
+        node.endPosition.column,
+    ].join(':');
+    return raw.map((declaration) => {
+        const context = contextFor(declaration.scope);
+        const selected = new Map();
+        const pending = namesIn(declaration.tokens);
+        const visitedNames = new Set();
+        const target = identity(declaration.node);
+        while (pending.length > 0) {
+            const name = pending.pop();
+            if (visitedNames.has(name))
+                continue;
+            visitedNames.add(name);
+            const byScope = byName.get(name);
+            for (const binding of scopePrefixes(declaration.scope).flatMap((prefix) => byScope?.get(prefix) ?? [])) {
+                const key = identity(binding.node);
+                if (key === target || selected.has(key))
+                    continue;
+                selected.set(key, binding);
+                // More than this is a generated binding graph, not a helper a human can
+                // meaningfully reuse. Abstain instead of doing quadratic work on it.
+                if (selected.size > 512)
+                    return [];
+                for (const referenced of binding.references) {
+                    if (!visitedNames.has(referenced))
+                        pending.push(referenced);
+                }
+            }
+        }
+        const bindingTokens = [...selected.values()]
+            .sort((left, right) => left.node.startPosition.row - right.node.startPosition.row ||
+            left.node.startPosition.column - right.node.startPosition.column)
+            .map((binding) => ({ type: '__binding__', text: binding.fingerprint }));
+        const directoryToken = bindingPath !== '' && (context.needsDirectory ||
+            needsBindingDirectory(declaration.tokens) ||
+            [...selected.values()].some((binding) => needsBindingDirectory(binding.tokens)))
+            ? [{ type: '__binding_directory__', text: posix.dirname(bindingPath.replaceAll('\\', '/')) }]
+            : [];
+        return [{
+                ...declaration,
+                tokens: [...directoryToken, ...context.tokens, ...bindingTokens, ...declaration.tokens],
+            }];
+    }).flat();
 }
 //# sourceMappingURL=foreign-tokens.js.map

package/dist/verifiers/guard-diff.js

@@ -0,0 +1,138 @@
+import { packFor } from '#app/lang/packs.js';
+import { implementationFingerprint, typescriptSourceFingerprint } from '#app/reinvention.js';
+import { sourceTokensFor } from './foreign-tokens.js';
+const NATIVE_SOURCE = /\.[cm]?[jt]sx?$/i;
+const EXECUTABLE_CHANGES = new WeakMap();
+function executableChanges(g) {
+    const known = EXECUTABLE_CHANGES.get(g);
+    if (known)
+        return known;
+    const changed = new Set();
+    const represented = new Set();
+    for (const file of g.files) {
+        represented.add(file.changed.path);
+        const after = typescriptSourceFingerprint(file.sf.getFullText());
+        const before = typescriptSourceFingerprint(file.before?.getFullText() ?? '');
+        if (!after || !before || after !== before || file.changed.beforePath !== undefined) {
+            changed.add(file.changed.path);
+        }
+    }
+    for (const file of g.foreign) {
+        represented.add(file.path);
+        const after = implementationFingerprint(sourceTokensFor(file.tree.rootNode, file.pack));
+        const before = implementationFingerprint(file.beforeTree ? sourceTokensFor(file.beforeTree.rootNode, file.pack) : []);
+        if (after !== before || file.changed.beforePath !== undefined)
+            changed.add(file.path);
+    }
+    const supported = (path) => path !== undefined && (NATIVE_SOURCE.test(path) || packFor(path) !== undefined);
+    for (const file of g.inventory ?? g.changed) {
+        if (represented.has(file.path))
+            continue;
+        if (supported(file.path) || supported(file.beforePath))
+            changed.add(file.path);
+    }
+    EXECUTABLE_CHANGES.set(g, changed);
+    return changed;
+}
+/**
+ * A guard transfer into another changed file is outside a local syntax proof. Keep a
+ * HIGH/proven result only when every other supported source file is token-stable.
+ */
+export function hasOtherExecutableChange(g, currentPath) {
+    const changed = executableChanges(g);
+    return changed.size > (changed.has(currentPath) ? 1 : 0);
+}
+/**
+ * Return the guards removed by an otherwise token-identical block rewrite.
+ *
+ * This is deliberately a narrow proof. A helper extraction, inserted validation call,
+ * changed continuation, or moved statement makes the block ambiguous and produces no
+ * deterministic finding. Those changes need semantic judgement; a pre/post syntax
+ * oracle cannot honestly call them lost guards.
+ */
+function guardOnlyDeletion(before, after) {
+    const removed = [];
+    let left = 0;
+    let right = 0;
+    while (left < before.entries.length && right < after.entries.length) {
+        const old = before.entries[left];
+        const current = after.entries[right];
+        if (old.fingerprint === current.fingerprint) {
+            left++;
+            right++;
+            continue;
+        }
+        if (old.guard !== undefined) {
+            // A guard only protects a continuation in its own block. If it is the last
+            // meaningful statement, deleting it is not the failure this check promises.
+            if (before.entries.slice(left + 1).some((entry) => entry.guard === undefined)) {
+                removed.push({ id: old.id, ...old.guard });
+            }
+            left++;
+            continue;
+        }
+        return undefined;
+    }
+    if (right !== after.entries.length)
+        return undefined;
+    while (left < before.entries.length) {
+        const old = before.entries[left];
+        if (old.guard === undefined)
+            return undefined;
+        if (before.entries.slice(left + 1).some((entry) => entry.guard === undefined)) {
+            removed.push({ id: old.id, ...old.guard });
+        }
+        left++;
+    }
+    return removed.length > 0 ? removed : undefined;
+}
+/**
+ * Guards whose removal is the only executable change in a uniquely matched block.
+ * Ambiguous duplicate blocks are skipped rather than paired by traversal order.
+ */
+export function provenGuardRemovals(before, after) {
+    // A name is not a callable contract. Changing a parameter, receiver, owner, or
+    // return type can make a formerly necessary guard obsolete.
+    if (before.identity !== after.identity)
+        return [];
+    const uniqueByPath = (blocks) => {
+        const out = new Map();
+        for (const block of blocks) {
+            if (out.has(block.path))
+                out.set(block.path, undefined);
+            else
+                out.set(block.path, block);
+        }
+        return out;
+    };
+    const current = uniqueByPath(after.blocks);
+    const remainingGuards = new Set(after.blocks.flatMap((block) => block.entries.flatMap((entry) => entry.guard === undefined ? [] : [entry.guard.key])));
+    const structurallyRemoved = [];
+    for (const [path, previous] of uniqueByPath(before.blocks)) {
+        const now = current.get(path);
+        if (!previous || !now)
+            continue;
+        structurallyRemoved.push(...(guardOnlyDeletion(previous, now) ?? []));
+    }
+    if (structurallyRemoved.length === 0)
+        return [];
+    // A block-local diff is not enough: another branch or sibling statement may have
+    // changed the guarantee that made the guard obsolete. Remove the candidate guard
+    // nodes from the old callable and require every remaining compiler-visible token
+    // to equal the new callable. This is the fact behind the `proven` confidence.
+    const omitted = new Set(structurallyRemoved.map((guard) => guard.id));
+    const previousResidual = before.residualFingerprint(omitted);
+    const currentResidual = after.residualFingerprint(new Set());
+    if (!previousResidual || previousResidual !== currentResidual)
+        return [];
+    const reportable = new Map();
+    for (const guard of structurallyRemoved) {
+        // A syntactically identical guard elsewhere in the callable may dominate the
+        // continuation. Without a control-flow graph, abstaining is the only proof-safe
+        // answer; false negatives are preferable to a false HIGH/proven defect.
+        if (!remainingGuards.has(guard.key))
+            reportable.set(guard.key, guard.label);
+    }
+    return [...reportable.values()];
+}
+//# sourceMappingURL=guard-diff.js.map

package/dist/verifiers/reinvented.js

@@ -11,12 +11,12 @@ const GENERIC = new Set([
     'handler', 'handle', 'create', 'update', 'remove', 'delete', 'list', 'find',
     'parse', 'format', 'load', 'save', 'toString', 'default', 'config', 'options',
 ]);
-function declaredNames(sf) {
+function declaredNames(sf, bindingPath) {
     const out = [];
     for (const fn of sf.getFunctions()) {
         const name = fn.getName();
         const id = fn.getNameNode();
-        const fingerprint = typescriptImplementationFingerprint(fn);
+        const fingerprint = typescriptImplementationFingerprint(fn, bindingPath);
         if (name && id && fingerprint) {
             out.push({ name, line: fn.getStartLineNumber(), span: locate(sf, id.getStart(), id.getWidth()).span, fingerprint });
         }
@@ -27,7 +27,7 @@ function declaredNames(sf) {
             continue;
         if (init.isKind(SyntaxKind.ArrowFunction) || init.isKind(SyntaxKind.FunctionExpression)) {
             const id = v.getNameNode();
-            const fingerprint = typescriptImplementationFingerprint(v);
+            const fingerprint = typescriptImplementationFingerprint(v, bindingPath);
             if (fingerprint) {
                 out.push({ name: v.getName(), line: v.getStartLineNumber(), span: locate(sf, id.getStart(), id.getWidth()).span, fingerprint });
             }
@@ -49,10 +49,12 @@ export const reinvented = {
             // tests describing the same scenario naturally share a name
             if (TEST_FILE.test(file))
                 continue;
-            const baseDeclarations = before ? declaredNames(before) : [];
-            for (const { name, line, span, fingerprint } of declaredNames(sf)) {
+            const baseDeclarations = before ? declaredNames(before, changed.beforePath ?? file) : [];
+            for (const { name, line, span, fingerprint } of declaredNames(sf, file)) {
                 if (!changed.added.has(line))
                     continue;
+                if (changed.beforePath && changed.beforePath !== changed.path)
+                    continue;
                 if (name.length < 6 || GENERIC.has(name) || GENERIC.has(name.toLowerCase()))
                     continue;
                 const existedHere = baseDeclarations.some((declaration) => normalizeName(declaration.name) === normalizeName(name) &&

package/docs/architecture.md

@@ -121,6 +121,14 @@ A branch or commit review reads source from the target revision, not from whatev
 currently present in the working directory. Grounding, verification, bundling, and
 positioning all receive the same tree.
 
+### Delegation shares file selection
+
+`psh delegate` builds the same target snapshot, `SelectionPlan`, and parser ground as
+`psh review`, then stops before deterministic verification, model calls, sessions, or
+manifests. Its Markdown brief and `powershot.delegate/v1` JSON are renderings of one
+task object. Both therefore expose the same selected, waived, and failed files and the
+same bounded judge units; an output adapter cannot silently choose a different scope.
+
 ### Capabilities belong to files
 
 A run can contain a typed TypeScript file beside a Python file or a TypeScript file
@@ -151,6 +159,31 @@ Python dependency grounding follows the same rule. Local modules are discovered
 direct entries on each changed file's ancestor chain and conventional `src`, `lib`, or
 `python` roots. It never recursively crawls an unrelated monorepo tree.
 
+### Proven findings have one proof shape
+
+A syntax oracle abstains when a refactor falls outside the exact fact it can prove.
+`dropped-guard` pairs stable module bindings, owner, bodyless callable contract, and
+structural block path. It then removes only the candidate guard nodes from the old file
+and requires every remaining compiler-visible token to equal the new file. Any other
+executable change in a supported source file also makes the check abstain, because the
+guard may have moved across that boundary. An import, type, ancestor condition, sibling
+statement, helper extraction, or moved continuation therefore cannot become a
+HIGH/proven defect. The check also abstains when the same token-normalized guard remains
+elsewhere in the callable. The changed-source index is built once from the complete diff
+inventory, including renamed, deleted, and policy-waived paths, so the proof stays linear
+in a large monorepo instead of rescanning the change for every callable.
+
+`reinvented` follows only language-declared module wrappers, includes decorators and
+templates in the token fingerprint, and keeps package and namespace identity separate.
+Its syntax evidence does not claim semantic accessibility: it requires matching declared
+visibility, wrappers, imports, referenced module bindings, conditional compilation, and
+relative binding directory before calling a declaration plausibly reusable.
+Go also requires the same source directory because its import path, not its package
+clause alone, defines cross-file reuse. Anonymous namespaces and file-private
+declarations are excluded. Type bodies, receiver implementations, and nested test
+support are not treated as interchangeable module-level alternatives. Ambiguous
+identities stay available to the optional judge instead of becoming verified facts.
+
 ### Grammar memory is isolated by language
 
 Tree-sitter WASM compilation outlives its JavaScript parser objects. Keeping every

package/docs/ci.md

@@ -90,10 +90,15 @@ newest unmarked legacy `## PowerShot` summary from v1.1.2 or older without claim
 ambiguous legacy comment through `PATCH`.
 
 The comment leads with the verdict, effective severity threshold, review mode, and
-aggregate file/check counts. Portable gaps and files outside parser coverage stay
-visible under a collapsed coverage section without filling the timeline with paths.
-The generated `powershot.manifest.json` keeps the per-file accounting for workflows
-that want to persist it as an artifact.
+reviewed/changed file ratio and check count. Portable gaps and files outside parser
+coverage stay visible under a collapsed coverage section without filling the timeline
+with paths. The generated `powershot.manifest.json` keeps the per-file accounting for
+workflows that want to persist it as an artifact.
+
+For a `pull_request` from a fork, GitHub gives the workflow token read-only pull-request
+permissions. PowerShot still runs and writes the complete report to the job summary,
+but skips summary comments, inline comments, and approval because those operations
+require a write-capable token.
 
 PowerShot checks the target head throughout reconciliation and removes its own
 just-created candidate if it observes a changed head. Simultaneous same-head runs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xcraft/powershot",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "Oracle-first code review for machine-written code, with deterministic verification and CI-ready reports.",
   "license": "Apache-2.0",
   "author": "aglumova <alina.glumova@gmail.com>",