@neurcode-ai/cli 0.16.5 → 0.16.7

package/dist/commands/session-hook.js

@@ -42,6 +42,7 @@ const diff_parser_1 = require("@neurcode-ai/diff-parser");
 const structural_understanding_1 = require("../utils/structural-understanding");
 const consequence_nudges_1 = require("../utils/consequence-nudges");
 const agent_guard_supervisor_1 = require("../utils/agent-guard-supervisor");
+const local_repo_brain_1 = require("../utils/local-repo-brain");
 // ── Helpers ───────────────────────────────────────────────────────────────────
 /** Read the full hook JSON from stdin, or return {} on any error. */
 function readHookInput() {
@@ -146,6 +147,41 @@ function sessionAlreadyEmittedNudge(session, nudgeKey) {
         typeof event.detail === 'object' &&
         event.detail['nudgeKey'] === nudgeKey);
 }
+function reuseNudgeKey(artifactHash, finding) {
+    return [
+        'reuse',
+        artifactHash,
+        finding.changed.file,
+        finding.changed.name,
+        finding.existing.file,
+        finding.existing.name,
+        finding.matchType,
+    ].join(':');
+}
+function formatReuseNudge(finding) {
+    return finding.message;
+}
+function reuseNudgeFromArtifact(artifactHash, findings) {
+    const [finding] = findings;
+    if (!finding)
+        return null;
+    return {
+        nudgeVersion: 'reuse-v1',
+        nudgeKey: reuseNudgeKey(artifactHash, finding),
+        severity: 'medium',
+        headline: formatReuseNudge(finding),
+        consequenceClass: 'repo-reuse',
+        operatorAction: 'Review the existing helper before merging; reuse or intentionally explain the duplicate.',
+        reviewFocus: [finding.changed.file, finding.existing.file],
+        artifactHash,
+        reuseFinding: finding,
+        surfacedReuseFindings: findings.slice(0, 3),
+        provenance: 'deterministic-static',
+    };
+}
+function isReuseNudge(nudge) {
+    return nudge.nudgeVersion === 'reuse-v1';
+}
 function readWorkingDiff(repoRoot) {
     return (0, child_process_1.execFileSync)('git', ['-C', repoRoot, 'diff', '--no-ext-diff', 'HEAD'], {
         encoding: 'utf8',
@@ -168,10 +204,12 @@ async function maybeRecordConsequenceNudge(repoRoot, session) {
         });
         const nudges = (0, consequence_nudges_1.selectInFlowConsequenceNudges)(artifact, { max: 3 });
         const [nudge] = nudges;
-        if (!nudge)
+        const reuseNudge = reuseNudgeFromArtifact(artifact.artifactHash, artifact.reuseFindings);
+        const selectedNudge = nudge ?? reuseNudge;
+        if (!selectedNudge)
             return null;
         const latest = (0, governance_runtime_1.loadSession)(repoRoot, session.sessionId) || session;
-        if (sessionAlreadyEmittedNudge(latest, nudge.nudgeKey))
+        if (sessionAlreadyEmittedNudge(latest, selectedNudge.nudgeKey))
             return null;
         const artifactPath = (0, structural_understanding_1.writeStructuralUnderstanding)(repoRoot, session.sessionId, artifact);
         (0, governance_runtime_1.appendEvent)(repoRoot, session.sessionId, {
@@ -188,6 +226,8 @@ async function maybeRecordConsequenceNudge(repoRoot, session) {
                 changedFiles: artifact.changedFiles,
                 changedSymbols: artifact.changedSymbols,
                 digest: artifact.digest,
+                repoSymbolIndex: artifact.repoSymbolIndex,
+                reuseFindings: artifact.reuseFindings,
                 boundaryImpact: artifact.boundaryImpact,
                 suppressedArtifacts: artifact.suppressedArtifacts,
                 consequenceUnderstanding: {
@@ -205,103 +245,120 @@ async function maybeRecordConsequenceNudge(repoRoot, session) {
         (0, governance_runtime_1.appendEvent)(repoRoot, session.sessionId, {
             type: 'consequence_nudge',
             ts: new Date().toISOString(),
-            message: nudge.headline,
+            message: (nudge ?? reuseNudge)?.headline ?? 'Structural advisory recorded.',
             detail: {
-                nudgeVersion: nudge.nudgeVersion,
-                nudgeKey: nudge.nudgeKey,
-                severity: nudge.severity,
-                consequenceClass: nudge.consequenceClass,
-                operatorAction: nudge.operatorAction,
-                reviewFocus: nudge.reviewFocus,
-                artifactHash: nudge.artifactHash,
-                impact: nudge.impact ? {
-                    rank: nudge.impact.rank,
-                    score: nudge.impact.score,
-                    file: nudge.impact.file,
-                    symbol: nudge.impact.symbol,
-                    summary: nudge.impact.summary,
-                    findingTypes: nudge.impact.findingTypes,
-                    findingRanks: nudge.impact.findingRanks,
-                    findingCount: nudge.impact.findingCount,
-                    productionConsumerCount: nudge.impact.productionConsumerCount,
-                    testConsumerCount: nudge.impact.testConsumerCount,
-                    reachableProductionConsumerCount: nudge.impact.reachableProductionConsumerCount,
-                    externalProductionConsumerCount: nudge.impact.externalProductionConsumerCount,
-                    changedProductionConsumerCount: nudge.impact.changedProductionConsumerCount,
-                    sensitiveConsumerCount: nudge.impact.sensitiveConsumerCount,
-                    approvalRequiredConsumerCount: nudge.impact.approvalRequiredConsumerCount,
-                    runtimeGovernanceConsumerCount: nudge.impact.runtimeGovernanceConsumerCount,
-                    productionFiles: nudge.impact.productionFiles,
-                    changedProductionFiles: nudge.impact.changedProductionFiles,
-                    testFiles: nudge.impact.testFiles,
-                    sensitiveFiles: nudge.impact.sensitiveFiles,
-                    approvalRequiredFiles: nudge.impact.approvalRequiredFiles,
-                    runtimeGovernanceFiles: nudge.impact.runtimeGovernanceFiles,
-                    highFanout: nudge.impact.highFanout,
-                    architectureRelevant: nudge.impact.architectureRelevant,
-                    reasonCodes: nudge.impact.reasonCodes,
-                    provenance: nudge.impact.provenance,
-                } : null,
-                finding: {
-                    rank: nudge.finding.rank,
-                    score: nudge.finding.score,
-                    findingType: nudge.finding.findingType,
-                    file: nudge.finding.file,
-                    symbol: nudge.finding.symbol,
-                    summary: nudge.finding.summary,
-                    consumerCount: nudge.finding.consumerCount,
-                    nonTestConsumerCount: nudge.finding.nonTestConsumerCount,
-                    testConsumerCount: nudge.finding.testConsumerCount,
-                    externalConsumerCount: nudge.finding.externalConsumerCount,
-                    externalConsumerFiles: nudge.finding.externalConsumerFiles,
-                    consumerSummary: nudge.finding.consumerSummary,
-                    reasonCodes: nudge.finding.reasonCodes,
-                },
-                topImpacts: nudges
-                    .map((item) => item.impact)
-                    .filter((impact) => Boolean(impact))
-                    .map((impact) => ({
-                    rank: impact.rank,
-                    score: impact.score,
-                    file: impact.file,
-                    symbol: impact.symbol,
-                    summary: impact.summary,
-                    findingTypes: impact.findingTypes,
-                    findingCount: impact.findingCount,
-                    reachableProductionConsumerCount: impact.reachableProductionConsumerCount,
-                    externalProductionConsumerCount: impact.externalProductionConsumerCount,
-                    changedProductionConsumerCount: impact.changedProductionConsumerCount,
-                    productionFiles: impact.productionFiles,
-                    changedProductionFiles: impact.changedProductionFiles,
-                    sensitiveConsumerCount: impact.sensitiveConsumerCount,
-                    approvalRequiredConsumerCount: impact.approvalRequiredConsumerCount,
-                    runtimeGovernanceConsumerCount: impact.runtimeGovernanceConsumerCount,
-                    highFanout: impact.highFanout,
-                    architectureRelevant: impact.architectureRelevant,
-                    reasonCodes: impact.reasonCodes,
-                })),
-                topFindings: nudges.map((item) => ({
-                    nudgeKey: item.nudgeKey,
-                    severity: item.severity,
-                    consequenceClass: item.consequenceClass,
-                    operatorAction: item.operatorAction,
-                    reviewFocus: item.reviewFocus,
-                    findingType: item.finding.findingType,
-                    file: item.finding.file,
-                    symbol: item.finding.symbol,
-                    externalConsumerCount: item.finding.externalConsumerCount,
-                    externalConsumerFiles: item.finding.externalConsumerFiles,
-                    consumerSummary: item.finding.consumerSummary,
-                    reasonCodes: item.finding.reasonCodes,
-                })),
-                provenance: nudge.provenance,
+                ...(nudge
+                    ? {
+                        nudgeVersion: nudge.nudgeVersion,
+                        nudgeKey: nudge.nudgeKey,
+                        severity: nudge.severity,
+                        consequenceClass: nudge.consequenceClass,
+                        operatorAction: nudge.operatorAction,
+                        reviewFocus: nudge.reviewFocus,
+                        artifactHash: nudge.artifactHash,
+                        impact: nudge.impact ? {
+                            rank: nudge.impact.rank,
+                            score: nudge.impact.score,
+                            file: nudge.impact.file,
+                            symbol: nudge.impact.symbol,
+                            summary: nudge.impact.summary,
+                            findingTypes: nudge.impact.findingTypes,
+                            findingRanks: nudge.impact.findingRanks,
+                            findingCount: nudge.impact.findingCount,
+                            productionConsumerCount: nudge.impact.productionConsumerCount,
+                            testConsumerCount: nudge.impact.testConsumerCount,
+                            reachableProductionConsumerCount: nudge.impact.reachableProductionConsumerCount,
+                            externalProductionConsumerCount: nudge.impact.externalProductionConsumerCount,
+                            changedProductionConsumerCount: nudge.impact.changedProductionConsumerCount,
+                            sensitiveConsumerCount: nudge.impact.sensitiveConsumerCount,
+                            approvalRequiredConsumerCount: nudge.impact.approvalRequiredConsumerCount,
+                            runtimeGovernanceConsumerCount: nudge.impact.runtimeGovernanceConsumerCount,
+                            productionFiles: nudge.impact.productionFiles,
+                            changedProductionFiles: nudge.impact.changedProductionFiles,
+                            testFiles: nudge.impact.testFiles,
+                            sensitiveFiles: nudge.impact.sensitiveFiles,
+                            approvalRequiredFiles: nudge.impact.approvalRequiredFiles,
+                            runtimeGovernanceFiles: nudge.impact.runtimeGovernanceFiles,
+                            highFanout: nudge.impact.highFanout,
+                            architectureRelevant: nudge.impact.architectureRelevant,
+                            reasonCodes: nudge.impact.reasonCodes,
+                            provenance: nudge.impact.provenance,
+                        } : null,
+                        finding: {
+                            rank: nudge.finding.rank,
+                            score: nudge.finding.score,
+                            findingType: nudge.finding.findingType,
+                            file: nudge.finding.file,
+                            symbol: nudge.finding.symbol,
+                            summary: nudge.finding.summary,
+                            consumerCount: nudge.finding.consumerCount,
+                            nonTestConsumerCount: nudge.finding.nonTestConsumerCount,
+                            testConsumerCount: nudge.finding.testConsumerCount,
+                            externalConsumerCount: nudge.finding.externalConsumerCount,
+                            externalConsumerFiles: nudge.finding.externalConsumerFiles,
+                            consumerSummary: nudge.finding.consumerSummary,
+                            reasonCodes: nudge.finding.reasonCodes,
+                        },
+                        topImpacts: nudges
+                            .map((item) => item.impact)
+                            .filter((impact) => Boolean(impact))
+                            .map((impact) => ({
+                            rank: impact.rank,
+                            score: impact.score,
+                            file: impact.file,
+                            symbol: impact.symbol,
+                            summary: impact.summary,
+                            findingTypes: impact.findingTypes,
+                            findingCount: impact.findingCount,
+                            reachableProductionConsumerCount: impact.reachableProductionConsumerCount,
+                            externalProductionConsumerCount: impact.externalProductionConsumerCount,
+                            changedProductionConsumerCount: impact.changedProductionConsumerCount,
+                            productionFiles: impact.productionFiles,
+                            changedProductionFiles: impact.changedProductionFiles,
+                            sensitiveConsumerCount: impact.sensitiveConsumerCount,
+                            approvalRequiredConsumerCount: impact.approvalRequiredConsumerCount,
+                            runtimeGovernanceConsumerCount: impact.runtimeGovernanceConsumerCount,
+                            highFanout: impact.highFanout,
+                            architectureRelevant: impact.architectureRelevant,
+                            reasonCodes: impact.reasonCodes,
+                        })),
+                        topFindings: nudges.map((item) => ({
+                            nudgeKey: item.nudgeKey,
+                            severity: item.severity,
+                            consequenceClass: item.consequenceClass,
+                            operatorAction: item.operatorAction,
+                            reviewFocus: item.reviewFocus,
+                            findingType: item.finding.findingType,
+                            file: item.finding.file,
+                            symbol: item.finding.symbol,
+                            externalConsumerCount: item.finding.externalConsumerCount,
+                            externalConsumerFiles: item.finding.externalConsumerFiles,
+                            consumerSummary: item.finding.consumerSummary,
+                            reasonCodes: item.finding.reasonCodes,
+                        })),
+                        provenance: nudge.provenance,
+                    }
+                    : reuseNudge
+                        ? {
+                            nudgeVersion: reuseNudge.nudgeVersion,
+                            nudgeKey: reuseNudge.nudgeKey,
+                            severity: reuseNudge.severity,
+                            consequenceClass: reuseNudge.consequenceClass,
+                            operatorAction: reuseNudge.operatorAction,
+                            reviewFocus: reuseNudge.reviewFocus,
+                            artifactHash: reuseNudge.artifactHash,
+                            reuseFinding: reuseNudge.reuseFinding,
+                            topReuseFindings: reuseNudge.surfacedReuseFindings,
+                            provenance: reuseNudge.provenance,
+                        }
+                        : {}),
                 killSwitch: 'NEURCODE_DISABLE_CONSEQUENCE_NUDGES=1',
             },
         });
         const refreshed = (0, governance_runtime_1.loadSession)(repoRoot, session.sessionId);
         if (refreshed)
             await (0, runtime_live_1.publishRuntimeLiveStatus)(repoRoot, refreshed);
-        return nudge;
+        return nudge ?? reuseNudge;
     }
     catch (error) {
         diagnostic(`consequence nudge skipped: ${error instanceof Error ? error.message : String(error)}`);
@@ -1313,23 +1370,63 @@ async function handleCheck(cmdCwd) {
     const consequenceNudge = result.verdict === 'block'
         ? null
         : await maybeRecordConsequenceNudge(repoRoot, session);
+    // ── Repo brain facts (P0/P1) ─────────────────────────────────────────────
+    // Load source-free repo context for the blocked/warned path. Best-effort:
+    // if the artifact is missing the message is unchanged and recovery guidance
+    // is appended instead.
+    let repoBrainFileFacts = null;
+    let repoBrainMeta = {
+        artifactHash: null,
+        generatedAt: null,
+        status: 'missing',
+    };
+    try {
+        const brainCtx = (0, local_repo_brain_1.getRepoBrainContext)(repoRoot, [filePath]);
+        repoBrainMeta = { artifactHash: brainCtx.artifactHash, generatedAt: brainCtx.generatedAt, status: brainCtx.status };
+        repoBrainFileFacts = brainCtx.files[0] ?? null;
+    }
+    catch {
+        // Never let brain context loading break the enforcement path.
+    }
     // ── Emit hook response ────────────────────────────────────────────────────
     if (result.verdict === 'block') {
+        // Enrich deny message with source-free repo facts (P1).
+        const brainSuffix = repoBrainFileFacts
+            ? (0, local_repo_brain_1.formatRepoBrainFactsForMessage)(repoBrainFileFacts)
+            : repoBrainMeta.status === 'missing'
+                ? 'Run `neurcode brain index` for local source-free repo context.'
+                : '';
+        const enrichedMessage = brainSuffix
+            ? `${result.message} | ${brainSuffix}`
+            : result.message;
         // Include machine-readable approvalContext when the block is approval-required,
         // so the agent can surface a structured approval request to the human.
-        denyPreToolUse(result.message, {
+        denyPreToolUse(enrichedMessage, {
             ...(result.approvalContext ? { approvalContext: result.approvalContext } : {}),
             ...(result.blockType
                 ? {
-                    blockContext: blockContext({
-                        blockType: result.blockType,
-                        filePath,
-                        message: result.message,
-                        suggestedApprovalPath: result.approvalContext?.suggestedApprovalPath,
-                        owners: result.owners,
-                        proposalId: pendingScopeAmendmentProposalId,
-                        runtimeMode: runtimeMode(session),
-                    }),
+                    blockContext: {
+                        ...blockContext({
+                            blockType: result.blockType,
+                            filePath,
+                            message: enrichedMessage,
+                            suggestedApprovalPath: result.approvalContext?.suggestedApprovalPath,
+                            owners: result.owners,
+                            proposalId: pendingScopeAmendmentProposalId,
+                            runtimeMode: runtimeMode(session),
+                        }),
+                        ...(repoBrainFileFacts ? {
+                            repoBrainFacts: {
+                                sensitiveKinds: repoBrainFileFacts.sensitiveKinds,
+                                module: repoBrainFileFacts.module,
+                                hotspot: repoBrainFileFacts.hotspot,
+                                ownerBoundary: repoBrainFileFacts.ownerBoundary,
+                                reuseAdvisories: repoBrainFileFacts.reuseAdvisories,
+                                artifactHash: repoBrainMeta.artifactHash,
+                                generatedAt: repoBrainMeta.generatedAt,
+                            },
+                        } : { repoBrainStatus: 'missing', repoBrainRecovery: 'neurcode brain index' }),
+                    },
                 }
                 : {}),
         });
@@ -1347,6 +1444,28 @@ async function handleCheck(cmdCwd) {
         }) + '\n');
         process.exit(0);
     }
+    if (consequenceNudge && isReuseNudge(consequenceNudge)) {
+        process.stdout.write(JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'allow',
+                reason: consequenceNudge.headline,
+                reuseNudge: {
+                    nudgeVersion: consequenceNudge.nudgeVersion,
+                    nudgeKey: consequenceNudge.nudgeKey,
+                    severity: consequenceNudge.severity,
+                    consequenceClass: consequenceNudge.consequenceClass,
+                    operatorAction: consequenceNudge.operatorAction,
+                    reviewFocus: consequenceNudge.reviewFocus,
+                    artifactHash: consequenceNudge.artifactHash,
+                    finding: consequenceNudge.reuseFinding,
+                    surfacedFindingLimit: 3,
+                    topFindings: consequenceNudge.surfacedReuseFindings,
+                },
+            },
+        }) + '\n');
+        process.exit(0);
+    }
     if (consequenceNudge) {
         process.stdout.write(JSON.stringify({
             hookSpecificOutput: {