@payconductor/houndsman 0.11.0 → 0.12.0

package/src/core/rule-text.ts

@@ -1,14 +1,10 @@
 /**
- * Texto de regra (biblioteca) — fonte única de polaridade e prefixos reservados.
+ * Texto de regra (biblioteca) — fonte única dos prefixos de polaridade.
  *
- * `RuleAnalyzer`, `registry-check` e o harness usam as mesmas listas: evita
- * divergência entre “Promover/Evitar” no analyzer e as validações anti-drift.
- * Também define o vocabulário de findings emergentes (lógica/domínio).
+ * `registry-check` usa a mesma lista para validar que a regra declara
+ * “Promover/Evitar” explicitamente.
  */
 
-/** Intenção de uma regra. */
-export type RuleIntent = "promote" | "avoid";
-
 /** Palavras que abrem uma regra de “deve acontecer”. */
 export const PROMOTE_PREFIXES = [
 	"promover",
@@ -29,12 +25,6 @@ export const AVOID_PREFIXES = [
 	"jamais",
 ] as const;
 
-/** Conjunto normalizado (usado para remover polaridade das keywords). */
-export const POLARITY_WORDS: ReadonlySet<string> = new Set([
-	...PROMOTE_PREFIXES,
-	...AVOID_PREFIXES,
-]);
-
 /** Escapa um literal para uso em regex. */
 function escapeWord(word: string): string {
 	return word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -48,50 +38,8 @@ function patternFor(words: readonly string[]): RegExp {
 const PROMOTE_PATTERN = patternFor(PROMOTE_PREFIXES);
 const AVOID_PATTERN = patternFor(AVOID_PREFIXES);
 
-/** Polaridade explícita; sem prefixo conhecido, assume `avoid`. */
-export function polarityOf(text: string): RuleIntent {
-	const normalized = text.trim().toLowerCase();
-	if (PROMOTE_PATTERN.test(normalized)) return "promote";
-	if (AVOID_PATTERN.test(normalized)) return "avoid";
-	return "avoid";
-}
-
 /** `true` quando a regra declara polaridade explícita. */
 export function hasExplicitPolarity(text: string): boolean {
 	const normalized = text.trim().toLowerCase();
 	return PROMOTE_PATTERN.test(normalized) || AVOID_PATTERN.test(normalized);
 }
-
-/** Prefixos reservados para findings emergentes (fora das regras explícitas). */
-export const EMERGENT_PREFIXES = {
-	logic: "Lógica:",
-	domain: "Domínio:",
-} as const;
-
-/** Espécie de finding emergente. */
-export type EmergentKind = keyof typeof EMERGENT_PREFIXES;
-
-/** Espécie de um finding emergente (`null` quando não é emergente). */
-export function emergentKind(rule: string): EmergentKind | null {
-	const normalized = rule.trim();
-	if (normalized.startsWith(EMERGENT_PREFIXES.logic)) return "logic";
-	if (normalized.startsWith(EMERGENT_PREFIXES.domain)) return "domain";
-	return null;
-}
-
-/** `true` quando a regra usa um prefixo emergente. */
-export function isEmergentRule(rule: string): boolean {
-	return emergentKind(rule) !== null;
-}
-
-/** Texto que sobra após o prefixo (vazio é inválido). */
-export function emergentText(rule: string): string {
-	const kind = emergentKind(rule);
-	if (!kind) return "";
-	return rule.trim().slice(EMERGENT_PREFIXES[kind].length).trim();
-}
-
-/** Monta o texto de um finding emergente. */
-export function emergentRule(kind: EmergentKind, text: string): string {
-	return `${EMERGENT_PREFIXES[kind]} ${text.trim()}`;
-}

package/src/core/services/git-repository.ts

@@ -138,6 +138,14 @@ export class GitRepository {
 		return parseNumstat(this.run(["diff", "--numstat", "-z", range]));
 	}
 
+	/**
+	 * Patch com contexto zero (`git diff -U0 range`), sem truncar por arquivo.
+	 * É compacto e exato nas linhas — base do escopo do diff e do delta AST.
+	 */
+	patchZeroContext(range: string): Map<string, string> {
+		return parseDiffIndex(this.run(["diff", "-U0", range]));
+	}
+
 	/** Patch por arquivo de um intervalo, opcionalmente restrito a `paths`. */
 	diffPatch(
 		range: string,

package/src/core/storage/types.ts

@@ -110,7 +110,6 @@ export type ArtifactKind =
 	| "ai"
 	| "ai-usage"
 	| "ai-brief"
-	| "harness-transcript"
 	| "other";
 
 /** Artefato persistido de uma review. */

package/src/core/types.ts

@@ -8,6 +8,7 @@
 
 import type { BriefPlan } from "./ai/schemas";
 import type { AstFileBrief } from "./ast/types";
+import type { ChangedScope } from "./changed-scope";
 import type { JevRuleSpec } from "./jev/jev-types";
 
 /** Severidade de um achado. `blocking` bloqueia o merge. */
@@ -29,19 +30,6 @@ export const SEVERITY_EMOJI: Record<Severity, string> = {
 	nit: "🔎",
 };
 
-/**
- * Sinais opcionais de uma regra: ajudam o `RuleAnalyzer` a transformar texto
- * em checagens concretas (símbolos, imports, decorators, paths e tools).
- */
-export type RuleHints = {
-	symbols?: string[];
-	imports?: string[];
-	decorators?: string[];
-	paths?: string[];
-	/** Nomes de tools sugeridos (ex.: `symbol_context`). */
-	checks?: string[];
-};
-
 /**
  * Regra do watchdog: severidade + texto. O texto declara a polaridade de forma
  * explícita — `Promover:` (algo que DEVE acontecer) ou `Evitar:`/`Não`/`Nunca`
@@ -54,7 +42,6 @@ export type Rule = {
 	severity: Severity;
 	text: string;
 	jev?: JevRuleSpec;
-	hints?: RuleHints;
 };
 
 /**
@@ -144,6 +131,8 @@ export type WatchdogRenderArgs = {
 	ast?: readonly AstFileBrief[];
 	/** Plano de revisão sugerido por IA (nunca substitui as regras). */
 	aiPlan?: BriefPlan;
+	/** Escopo do diff por arquivo (símbolos alterados; hunks como fallback). */
+	changedScope?: ChangedScope;
 };
 
 /** Definição completa de um watchdog — 1 por arquivo em `project/watchdogs/`. */

package/src/index.ts

@@ -7,7 +7,6 @@
 
 export type {
 	AiResult,
-	AiTool,
 	AiUsage,
 	ModelProvider,
 	ModelRequest,
@@ -26,7 +25,14 @@ export {
 } from "./core/ai";
 export { ArgParser } from "./core/arg-parser";
 export { assetPath, OUTPUT_FORMAT_FILE } from "./core/assets";
-export { computeDelta, emptyDelta, parseHunks } from "./core/ast/diff";
+export {
+	changedAnchorLines,
+	changedAnchors,
+	changedNewLines,
+	computeDelta,
+	emptyDelta,
+	parseHunks,
+} from "./core/ast/diff";
 export { buildImpact, resolveImport } from "./core/ast/impact";
 export { AstParser, languageForPath } from "./core/ast/parser";
 export { AstService } from "./core/ast/service";
@@ -44,6 +50,23 @@ export type {
 	AstSymbolKind,
 } from "./core/ast/types";
 export { defaultRenderBrief, PROCEDURE, renderBrief } from "./core/brief";
+export type {
+	BuildChangedScopeInput,
+	ChangedScope,
+	ChangedScopeSource,
+	ChangedSymbol,
+	FileChangedScope,
+	LineRange,
+	ScopeEntry,
+} from "./core/changed-scope";
+export {
+	buildChangedScope,
+	formatRanges,
+	formatSymbols,
+	isLineInScope,
+	mergeRanges,
+	summarizeScope,
+} from "./core/changed-scope";
 export type { FindingsCommandResult } from "./core/commands/findings";
 export { runFindingsCommand, runVerifyCommand } from "./core/commands/findings";
 export { ProjectScaffolder } from "./core/commands/scaffold";
@@ -231,7 +254,6 @@ export type {
 	FileStatus,
 	FileStatusMap,
 	Rule,
-	RuleHints,
 	Severity,
 	WatchdogDefinition,
 	WatchdogMeta,

package/src/server/client/utils/constants.ts

@@ -97,7 +97,6 @@ const KIND_ORDER: ArtifactKind[] = [
 	"ai",
 	"ai-usage",
 	"ai-brief",
-	"harness-transcript",
 	"context",
 	"context-brief",
 	"context-summary",
@@ -119,10 +118,9 @@ const GROUP_BY_KIND: Record<ArtifactKind, { key: string; label: string; order: n
 		candidates: { key: "core", label: "Núcleo da revisão", order: 3 },
 		ast: { key: "core", label: "Núcleo da revisão", order: 3 },
 		"ast-impact": { key: "core", label: "Núcleo da revisão", order: 3 },
-		ai: { key: "ai", label: "IA e harness", order: 4 },
-		"ai-usage": { key: "ai", label: "IA e harness", order: 4 },
-		"ai-brief": { key: "ai", label: "IA e harness", order: 4 },
-		"harness-transcript": { key: "ai", label: "IA e harness", order: 4 },
+		ai: { key: "ai", label: "IA", order: 4 },
+		"ai-usage": { key: "ai", label: "IA", order: 4 },
+		"ai-brief": { key: "ai", label: "IA", order: 4 },
 		context: { key: "context", label: "Contexto da PR", order: 5 },
 		"context-brief": { key: "context", label: "Contexto da PR", order: 5 },
 		"context-summary": { key: "context", label: "Contexto da PR", order: 5 },
@@ -146,7 +144,6 @@ export const ARTIFACT_KIND_LABELS: Record<ArtifactKind, string> = {
 	ai: "ia",
 	"ai-usage": "uso ia",
 	"ai-brief": "plano ia",
-	"harness-transcript": "transcript",
 	context: "contexto",
 	"context-brief": "brief ctx",
 	"context-summary": "resumo ctx",

package/src/server/client/utils/types.ts

@@ -70,7 +70,6 @@ export type ArtifactKind =
 	| "ai"
 	| "ai-usage"
 	| "ai-brief"
-	| "harness-transcript"
 	| "other";
 
 /** Metadados de artefato retornados pela API (sem conteúdo). */

package/src/skill/OUTPUT-FORMAT.md

@@ -69,6 +69,11 @@ staging global da review:
 - Sem achados → `"findings": []` (arquivo **obrigatório**).
 - Um achado por regra violada; não agrupar regras diferentes.
 - `file:line` sempre que possível; `evidence` quando o achado não é óbvio.
+- **Escopo do diff:** a `line` deve cair dentro das faixas listadas em
+  *Escopo do diff (símbolos alterados)* no brief. Código fora delas é contexto — não é
+  achado desta revisão. Se a alteração quebra código não alterado, ancore o finding na
+  linha alterada que causou o problema.
+- Achado **sem linha** só quando for inerente à alteração (vira comentário de arquivo).
 - Não inventar achados — se não houver violação, o array fica vazio.
 
 ## Findings emergentes (opt-in)

package/src/skill/README.md

@@ -18,7 +18,8 @@ Um único skill (`/houndsman`), quatro capabilities (detalhadas em `hunt.md`, `t
 
 - **houndsman** — o orquestrador/treinador (CLI + motor).
 - **watchdog** — cada agente especialista por domínio que audita o diff.
-- **brief** — instruções prontas para um watchdog (o prompt do subagente).
+- **brief** — instruções prontas para um watchdog (o prompt do subagente), incluindo o
+  **escopo do diff** (faixas/símbolos alterados que podem virar finding).
 - **findings** — os achados que o subagente grava em JSON (único output consumido).
 - **candidato (Jev)** — indício automático; **não** é achado (o watchdog confirma ou refuta).
 - **churn** — linhas adicionadas/removidas por arquivo; usado para priorizar a leitura.

package/src/skill/SETUP.md

@@ -9,7 +9,7 @@ no seu projeto é **autocontida** — não exige nenhuma dependência local do p
 - **git** — o diff usa `git diff <base>...<head> --name-status`.
 - **gh** (Opcional) — Obtém contexto da PR e dispara comentários para o GitHub
 - **`HOUNDSMAN_TYPE_SAFE_API_KEY`** (opcional) — pré-análise Jev.
-- **`HOUNDSMAN_DEEP_SEEK_API_KEY`** (opcional) — IA própria do `hunt` nativo e das features de IA.
+- **`HOUNDSMAN_DEEP_SEEK_API_KEY`** (opcional) — features de IA (briefs, contexto, classificação, resumo técnico).
 - **`HOUNDSMAN_OPENAI_API_KEY`** / **`HOUNDSMAN_ANTHROPIC_API_KEY`** (opcional) — apenas se
   `ai.provider` for `openai`/`anthropic`.
 

package/src/skill/fix.md

@@ -132,7 +132,7 @@ Volte ao passo 1. A fila encolhe a cada volta; o `batch` traz o próximo grupo s
 
 ## Perguntas de decisão ao usuário
 
-Pergunte (ferramenta de perguntas do harness) **antes** de corrigir quando o achado for:
+Pergunte (ferramenta de perguntas do agente) **antes** de corrigir quando o achado for:
 
 - ambíguo ou com **múltiplas correções válidas**;
 - uma mudança de **produto/arquitetura** (não é "só código");

package/src/skill/hunt.md

@@ -25,12 +25,6 @@ Traduza o pedido do usuário para flags **antes** de começar:
 **Quando usar:** revisar PR antes de merge · code review de feature branch · validar
 mudanças antes de push.
 
-> **Harness nativo (opcional):** além deste skill, o CLI tem `houndsman hunt` — o mesmo
-> fluxo executado pelo próprio houndsman, com tools read-only, investigação por evidência
-> e `VERIFY` obrigatório. Use `houndsman hunt --dry-run` para inspecionar sem IA. Para uma
-> PR específica, `houndsman hunt --pr 456` roda no worktree automaticamente. Detalhes em
-> `docs/HARNESS.md`.
-
 ## Quem executa o quê
 
 - **Você** só invoca o skill: `/houndsman [hunt]`. Não precisa rodar nenhum script à mão.
@@ -62,6 +56,8 @@ mudanças antes de push.
 - **As regras refletem os padrões APLICADOS hoje** — não validar práticas que o projeto
   não adota. Regra sem aplicação real no código gera falso positivo.
 - Cada watchdog recebe apenas seus arquivos relevantes (brief pronto) — nunca o diff completo.
+- O brief traz o **escopo do diff** (símbolos alterados e faixas revisáveis); achado fora
+  dessas faixas é código pré-existente, não escopo desta revisão.
 - Saída estruturada (JSON) por watchdog → consolidada e deduplicada automaticamente.
 
 ---

package/src/tests/__snapshots__/baseline.test.ts.snap

@@ -11,7 +11,7 @@ exports[`baseline — brief defaultRenderBrief (contexto, churn, overflow, candi
 
 Watchdog baseline.
 
-## Escopo
+## Escopo do domínio
 
 src/alpha/**
 
@@ -63,10 +63,10 @@ src/alpha/**
 ## Procedimento
 
 1. **FILTER** — descarte o que não for do seu domínio (ver *Prioridade de leitura* e *Não carregar*).
-2. **READ HEAD** — leia os arquivos seletivamente (primeiras ~30 linhas). NUNCA o diff completo.
-3. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações.
-4. **DEEP-READ** — aprofunde apenas os arquivos com suspeita de violação.
-5. **CONCLUDE** — grave o JSON no caminho de output, com \`reviewedFiles\` preenchido. Sem achados → \`"findings": []\` (arquivo obrigatório). Não escreva markdown livre."
+2. **READ SCOPE** — carregue apenas as faixas alteradas em *Escopo do diff*; o restante do arquivo é só contexto.
+3. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações nas faixas alteradas.
+4. **DEEP-READ** — aprofunde apenas as faixas com suspeita de violação dentro do escopo.
+5. **CONCLUDE** — grave o JSON no caminho de output, com \`reviewedFiles\` preenchido e \`line\` dentro das faixas alteradas. Sem achados → \`"findings": []\` (arquivo obrigatório). Não escreva markdown livre."
 `;
 
 exports[`baseline — relatório renderReport consolidado 1`] = `
@@ -405,16 +405,6 @@ export type Rule = {
 	severity: Severity;
 	text: string;
 	jev?: JevRuleSpec;
-	hints?: RuleHints;
-};
-
-/** Sinais opcionais de uma regra (símbolos, imports, decorators, paths, checks). */
-export type RuleHints = {
-	symbols?: string[];
-	imports?: string[];
-	decorators?: string[];
-	paths?: string[];
-	checks?: string[];
 };
 
 /** Como o watchdog casa um arquivo alterado. \`value\` é sempre regex. */
@@ -509,20 +499,15 @@ export type HoundsmanAiFeatures = {
 /** Overrides de IA por watchdog. */
 export type HoundsmanAiWatchdog = {
 	model?: string;
-	maxSteps?: number;
-	maxOutputTokens?: number;
 };
 
-/** Configuração da camada de IA (briefs, contexto, classificação e hunt nativo). */
+/** Configuração da camada de IA (briefs, contexto, classificação, pré-análise, verify). */
 export type HoundsmanAi = {
 	enabled?: boolean;
 	provider?: AiProviderKind;
 	model?: string;
 	baseURL?: string;
 	concurrency?: number;
-	maxSteps?: number;
-	maxOutputTokens?: number;
-	temperature?: number;
 	providerOptions?: AiProviderOptions;
 	timeoutMs?: number;
 	maxCallsPerReview?: number;
@@ -665,15 +650,15 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/OUTPUT-FORMAT.md",
-    "sha256": "94ea2b8def871784",
+    "sha256": "a78ed16d4d211889",
   },
   {
     "file": ".houndsman/core/skill/README.md",
-    "sha256": "1738ef9c6d9ec919",
+    "sha256": "9aadf51b48c7f304",
   },
   {
     "file": ".houndsman/core/skill/SETUP.md",
-    "sha256": "b74af7e1979bf1b4",
+    "sha256": "5e5335870f493aba",
   },
   {
     "file": ".houndsman/core/skill/example-review.md",
@@ -681,11 +666,11 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/fix.md",
-    "sha256": "9f10b2d846dc7db5",
+    "sha256": "5782f4880af78d29",
   },
   {
     "file": ".houndsman/core/skill/hunt.md",
-    "sha256": "1cf68076325da4ab",
+    "sha256": "dfaec1a665d7ee65",
   },
   {
     "file": ".houndsman/core/skill/train.md",
@@ -702,6 +687,7 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
 "Discovery: 1 watchdog(s) ativado(s), 3 arquivo(s), 1 deletado(s).
 Briefs: <cwd>/.home/work/<uuid>/briefs/
 Deletado (breaking change): src/alpha/old.ts
+Escopo: 2 arquivo(s), 0 símbolo(s) em 2 faixa(s) alterada(s).
 Jev: pulado (desativado (--no-jev)).
 AST: desabilitado ou sem grammar compatível.
 Sem contexto da PR (rode \`bun run houndsman context\` antes, se houver PR).
@@ -753,7 +739,29 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
   },
   "excludedCount": 0,
   "headSha": "<sha>",
-  "mode": "full"
+  "mode": "full",
+  "changedScope": {
+    "src/alpha/a.ts": {
+      "ranges": [
+        {
+          "start": 1,
+          "end": 2
+        }
+      ],
+      "symbols": [],
+      "source": "hunks"
+    },
+    "src/alpha/b.ts": {
+      "ranges": [
+        {
+          "start": 1,
+          "end": 1
+        }
+      ],
+      "symbols": [],
+      "source": "hunks"
+    }
+  }
 }
 "
 `;
@@ -827,10 +835,20 @@ exports[`baseline — artefatos de prepare/finalize gera classification, brief,
 
 Watchdog baseline.
 
-## Escopo
+## Escopo do domínio
 
 src/alpha/**
 
+## Escopo do diff (símbolos alterados)
+
+> **Regra de escopo:** um finding só é válido quando a \`line\` está nas faixas
+> abaixo. Código fora delas é contexto — use para entender o impacto, nunca
+> como achado. Se a mudança quebra código não alterado, ancore o finding na
+> linha alterada que causou o problema.
+
+- \`src/alpha/a.ts\` — linhas 1-2 _(faixas do diff)_
+- \`src/alpha/b.ts\` — linhas 1 _(faixas do diff)_
+
 ## Regras (por severidade)
 
 - ❌ **blocking** — Nunca usar \`any\`.
@@ -852,10 +870,10 @@ src/alpha/**
 ## Procedimento
 
 1. **FILTER** — descarte o que não for do seu domínio (ver *Prioridade de leitura* e *Não carregar*).
-2. **READ HEAD** — leia os arquivos seletivamente (primeiras ~30 linhas). NUNCA o diff completo.
-3. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações.
-4. **DEEP-READ** — aprofunde apenas os arquivos com suspeita de violação.
-5. **CONCLUDE** — grave o JSON no caminho de output, com \`reviewedFiles\` preenchido. Sem achados → \`"findings": []\` (arquivo obrigatório). Não escreva markdown livre.
+2. **READ SCOPE** — carregue apenas as faixas alteradas em *Escopo do diff*; o restante do arquivo é só contexto.
+3. **GREP** — use as regras críticas/anti-padrões como heurística para localizar violações nas faixas alteradas.
+4. **DEEP-READ** — aprofunde apenas as faixas com suspeita de violação dentro do escopo.
+5. **CONCLUDE** — grave o JSON no caminho de output, com \`reviewedFiles\` preenchido e \`line\` dentro das faixas alteradas. Sem achados → \`"findings": []\` (arquivo obrigatório). Não escreva markdown livre.
 "
 `;
 

package/src/tests/changed-scope.test.ts

@@ -0,0 +1,197 @@
+/**
+ * Escopo do diff — âncoras, símbolos alterados e fallback nos hunks.
+ *
+ * Congela a regra que impede o watchdog de reportar código pré-existente: só as
+ * faixas tocadas pela revisão (símbolo folha do AST ou hunk) são revisáveis.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { changedAnchors } from "../core/ast/diff";
+import type { AstAnalysis, AstFacts, AstSymbol } from "../core/ast/types";
+import {
+	buildChangedScope,
+	formatRanges,
+	formatSymbols,
+	isLineInScope,
+	mergeRanges,
+	summarizeScope,
+} from "../core/changed-scope";
+import type { DiffSource } from "../core/diff-source";
+
+/** Cabecalho padrão de um patch de arquivo. */
+function patch(body: string): string {
+	return `diff --git a/src/a.ts b/src/a.ts\n--- a/src/a.ts\n+++ b/src/a.ts\n${body}`;
+}
+
+function diffOf(patchText: string): DiffSource {
+	return {
+		byFile: new Map([["src/a.ts", patchText]]),
+		churn: new Map(),
+	};
+}
+
+function symbol(
+	overrides: Partial<AstSymbol> & Pick<AstSymbol, "name" | "kind">,
+): AstSymbol {
+	return {
+		exported: false,
+		startLine: 1,
+		endLine: 1,
+		...overrides,
+	};
+}
+
+function analysis(facts: AstFacts): AstAnalysis {
+	return { facts };
+}
+
+const FACTS: AstFacts = {
+	language: "typescript",
+	imports: [],
+	exports: [],
+	decorators: [],
+	hasSyntaxErrors: false,
+	symbols: [
+		symbol({ name: "Outer", kind: "class", startLine: 1, endLine: 20 }),
+		symbol({ name: "Outer.inner", kind: "method", startLine: 5, endLine: 10 }),
+		symbol({ name: "top", kind: "function", startLine: 25, endLine: 30 }),
+	],
+};
+
+describe("changedAnchors", () => {
+	test("adições e remoções apontam para o lado novo", () => {
+		const anchors = changedAnchors(
+			patch(
+				"@@ -10,3 +10,4 @@\n const before = 1;\n-const old = 2;\n+const current = 2;\n+const extra = 3;\n const after = 4;\n",
+			),
+		);
+
+		expect([...anchors.added].sort((a, b) => a - b)).toEqual([11, 12]);
+		expect([...anchors.deletedAt]).toEqual([11]);
+	});
+
+	test("remoção pura ancora no ponto do arquivo (sem consumir linha nova)", () => {
+		const anchors = changedAnchors(patch("@@ -10,2 +10,0 @@\n-a\n-b\n"));
+
+		expect([...anchors.added]).toEqual([]);
+		expect([...anchors.deletedAt]).toEqual([10]);
+	});
+});
+
+describe("buildChangedScope", () => {
+	const entries = [{ path: "src/a.ts", status: "modified" }];
+
+	test("âncora dentro de símbolo folha vira o intervalo do símbolo", () => {
+		const text = patch(
+			[
+				"@@ -2,0 +3,1 @@",
+				"+export const header = 1;",
+				"@@ -7,0 +8,1 @@",
+				"+  const inside = 1;",
+				"@@ -26,0 +27,1 @@",
+				"+  return 1;",
+				"",
+			].join("\n"),
+		);
+		const scope = buildChangedScope({
+			entries,
+			diff: diffOf(text),
+			ast: new Map([["src/a.ts", analysis(FACTS)]]),
+		});
+
+		const file = scope["src/a.ts"];
+		expect(file?.source).toBe("ast");
+		// `inner` (5-10) e `top` (25-30); o container `Outer` não expande.
+		expect(file?.symbols.map((item) => item.name)).toEqual(["Outer.inner", "top"]);
+		// Cabeçalho da classe (linha 3) fica como faixa avulsa.
+		expect(file?.ranges).toEqual([
+			{ start: 3, end: 3 },
+			{ start: 5, end: 10 },
+			{ start: 25, end: 30 },
+		]);
+	});
+
+	test("sem AST cai para os hunks do diff", () => {
+		const text = patch("@@ -10,0 +11,2 @@\n+a\n+b\n");
+		const scope = buildChangedScope({ entries, diff: diffOf(text) });
+
+		const file = scope["src/a.ts"];
+		expect(file?.source).toBe("hunks");
+		expect(file?.symbols).toEqual([]);
+		expect(file?.ranges).toEqual([{ start: 11, end: 12 }]);
+	});
+
+	test("rename/binário sem hunks fica sem faixas", () => {
+		const scope = buildChangedScope({
+			entries: [{ path: "src/a.ts", status: "renamed" }],
+			diff: diffOf(patch("")),
+		});
+
+		expect(scope["src/a.ts"]).toEqual({ ranges: [], symbols: [], source: "hunks" });
+	});
+
+	test("arquivo deletado nem entra no escopo", () => {
+		const scope = buildChangedScope({
+			entries: [{ path: "src/a.ts", status: "deleted" }],
+			diff: diffOf(patch("@@ -1,1 +0,0 @@\n-x\n")),
+		});
+
+		expect(scope["src/a.ts"]).toBeUndefined();
+	});
+});
+
+describe("helpers de escopo", () => {
+	test("isLineInScope respeita as faixas", () => {
+		const scope = {
+			"src/a.ts": {
+				ranges: [{ start: 5, end: 10 }],
+				symbols: [],
+				source: "hunks" as const,
+			},
+		};
+
+		expect(isLineInScope(scope, "src/a.ts", 7)).toBe(true);
+		expect(isLineInScope(scope, "src/a.ts", 11)).toBe(false);
+		expect(isLineInScope(scope, "src/b.ts", 7)).toBe(false);
+	});
+
+	test("mergeRanges une sobrepostos e adjacentes", () => {
+		expect(
+			mergeRanges([
+				{ start: 10, end: 12 },
+				{ start: 11, end: 15 },
+				{ start: 16, end: 18 },
+				{ start: 30, end: 30 },
+			]),
+		).toEqual([
+			{ start: 10, end: 18 },
+			{ start: 30, end: 30 },
+		]);
+	});
+
+	test("formatadores compactos", () => {
+		expect(formatRanges([])).toBe("sem linhas alteradas");
+		expect(
+			formatRanges([
+				{ start: 10, end: 14 },
+				{ start: 22, end: 22 },
+			]),
+		).toBe("10-14, 22");
+		expect(
+			formatSymbols([
+				{ name: "foo", kind: "function", startLine: 10, endLine: 14 },
+			]),
+		).toBe("`foo` (10-14)");
+		expect(
+			summarizeScope({
+				"src/a.ts": {
+					ranges: [{ start: 1, end: 2 }],
+					symbols: [
+						{ name: "foo", kind: "function", startLine: 1, endLine: 2 },
+					],
+					source: "ast",
+				},
+			}),
+		).toEqual({ files: 1, ranges: 1, symbols: 1 });
+	});
+});