wizz-method 2.23.0 → 2.25.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wizz-method",
-  "version": "2.23.0",
+  "version": "2.25.0",
   "description": "Wizz Method: método de agência orientado por IA em PT-BR",
   "keywords": [
     "agile",

package/skills-registry.yaml

@@ -207,8 +207,9 @@ areas:
       # estilo copiar antes de voz, timing, efeitos e montagem.
       - id: wizz-video-styles
         door: motion
-        when: "Decidir QUAL estilo de vídeo curto copiar a partir do inventário do material (pessoa real, só voz, b-roll, telas, produto) e entregar a receita medida em 110 vídeos reais (ritmo de corte, legenda, áudio, zoom, gancho), para qualquer nicho, inclusive clipe com a letra da música, tipografia cinética (texto como imagem, cortes na batida) e vídeo do app só com a interface (UI morph: uma forma vira cada tela, cursor conduz, estilo Dribbble). Gatilhos: 'estilo do vídeo', 'editar no estilo de', 'copiar a edição de', 'que estilo usar no reel', 'o vídeo ficou amador', 'clipe com a letra', 'tipografia cinética', 'vídeo do app mexendo', 'anima o app num vídeo', 'animação da interface tipo Dribbble'."
+        when: "Decidir QUAL estilo de vídeo curto copiar a partir do inventário do material (pessoa real, só voz, b-roll, telas, produto) e entregar a receita medida em 110 vídeos reais (ritmo de corte, legenda, áudio, zoom, gancho), para qualquer nicho, inclusive reel de música / vídeo de música / lyric video / vídeo com a letra / edição no ritmo da música, no estilo tipografia-cinetica (texto como imagem, cortes na batida, sem rosto nem narração) e vídeo do app só com a interface (UI morph: uma forma vira cada tela, cursor conduz, estilo Dribbble). Gatilhos: 'estilo do vídeo', 'editar no estilo de', 'copiar a edição de', 'que estilo usar no reel', 'o vídeo ficou amador', 'clipe com a letra', 'tipografia cinética', 'reel de música', 'vídeo de música', 'lyric video', 'vídeo com a letra', 'edição no ritmo da música', 'vídeo do app mexendo', 'anima o app num vídeo', 'animação da interface tipo Dribbble'."
         not_when:
+          - "Só roteirizar/montar Reel narrado com b-roll ou captar imagens de apoio, sem pedir escolha de estilo: música em alta como trilha não implica tipografia-cinetica. Roteiro é wizz-social-content, captação é get-brolls e montagem é wizz-remotion-best-practices. Só escolher a música em alta, sem pedir estilo ou vídeo musical, não aciona esta entrada."
           - "Decidir efeitos e SFX por evento, volume, LUFS e portões de zona segura: é wizz-video-effects; esta skill escolhe o estilo que ele depois refina."
           - "Montar o filme em React (cenas, legenda, <Audio>): é wizz-remotion-best-practices."
           - "Animar componente dentro do código do app (hover, transição de página, modal): é wizz-animate; aqui é vídeo para divulgar."
@@ -678,6 +679,7 @@ areas:
       - id: wizz-social-content
         when: "Criar/agendar conteúdo de social (LinkedIn, X, TikTok, IG...), o que inclui ESCREVER o texto: post, story, carrossel, legenda, thread. Gatilhos: 'escreve copy pra story', 'post pro LinkedIn', 'legenda do carrossel', 'thread pro X'."
         not_when:
+          - "Reel de música / lyric video só com música e tipografia, sem rosto nem narração: escolher a receita é wizz-video-styles, estilo tipografia-cinetica (designer), antes de escrever roteiro; nunca music-to-video externa. Música em alta como trilha de Reel narrado com b-roll mantém o roteiro aqui."
           - "Editar/revisar texto de social já escrito: aí é wizz-copy-editing."
           - "Pedir SÓ o asset de um Reel/vídeo — b-roll, 'imagens de apoio', 'cenas de apoio', imagem de corte, footage — sem que o texto ou o roteiro façam parte do pedido: a captação é get-brolls, na área designer. Esta entrada entra quando o TEXTO ou o ROTEIRO é parte do que se pede; se o pedido junta roteiro E captação, são 2 áreas."
         rel:
@@ -1219,3 +1221,7 @@ squads:
     domain: "Claude Code, tooling de agentes, automação de dev."
     advises: [dev, architect]
     when: "Dominar Claude Code, hooks, skills, workflows de agente."
+
+# Pacotes inertes opt-in, separados de skills/MCPs/CLIs: wizz templates --list.
+# Contrato e exemplos: tools/installer/templates.md. Nunca instalados por área.
+templates: []

package/src/bmm-skills/1-analysis/wizz-document-project/references/static-dependencies.md

@@ -0,0 +1,124 @@
+# Mapa estático de dependências
+
+Gere o mapa em scans deep/exhaustive de `initial_scan`/`full_rescan`, ou após a
+confirmação do alvo em `deep_dive`. Quick Scan não lê fontes nem gera o mapa.
+O script não chama modelos, executa código do projeto ou envia fontes a serviços.
+O cache de imports não substitui a leitura literal exigida pelo deep-dive.
+
+## Ferramenta e instalação
+
+JS/TS: `dependency-cruiser` 17.4.3 com TypeScript 5.9.3. Requer Python 3.10+
+e Node compatível com as versões fixadas. Python orquestra Git, cache, impacto e
+exportação; não analisa imports Python. Repositórios sem commits são aceitos
+(`commit: null`). Confirme os requisitos no ambiente usado.
+
+Se a ferramenta não estiver instalada, obtenha autorização antes de baixar
+pacotes. Instale em uma pasta de ferramentas confiável fora do projeto:
+
+```sh
+npm install --prefix /caminho/ferramentas-wizz --no-audit --no-fund dependency-cruiser@17.4.3 typescript@5.9.3
+```
+
+Passe um executável absoluto confiável por `--cruiser` ou `WIZZ_DEPCRUISE`.
+O script resolve links e recusa executáveis dentro do checkout. Nunca use o
+caminho lido de um cache como autorização para executá-lo. `refresh` exige a mesma
+entrada explícita e não recupera ferramenta/configuração executável do cache.
+Repita também o `--tsconfig` explicitamente, se necessário para aliases.
+
+```sh
+python3 "{skill-root}/scripts/dependencies.py" --root /caminho/projeto scan --cruiser /caminho/ferramentas-wizz/node_modules/.bin/depcruise --tsconfig tsconfig.json
+python3 "{skill-root}/scripts/dependencies.py" --root /caminho/projeto export
+```
+
+## Cache canônico e base estável
+
+Sem `--output`, todos os comandos usam
+`~/.cache/wizz/dependencies/<primeiros-24-hex-do-SHA256-do-root-resolvido>/`.
+Esse cache externo ao checkout não entra em Git. `--output` pode indicar outra
+pasta externa exclusiva; saídas dentro do repositório são recusadas. Documentos
+versionados citam a convenção/cobertura, sem copiar caminhos absolutos locais.
+`graph.json` e `obsidian/` ficam apenas nesse cache externo.
+
+O cache compara tamanho, mtime, ctime e inode; só relê fontes com metadados
+alterados e só reanalisa aquelas cujo hash mudou. JSONs de configuração
+(inclusive arquivos estendidos pelo tsconfig dentro do inventário), manifests e
+lockfiles são relidos para invalidar resolução. Inclusões/exclusões de qualquer
+arquivo inventariado, inclusive assets JSON/CSS, invalidam todos os importadores.
+Mudanças na ferramenta/capacidades/configuração também forçam análise completa.
+Arquivos ignorados não rastreados ficam fora do inventário; estado externo não
+inventariado exige regenerar o cache após alteração.
+
+`baseline_commit` fica ancorado na primeira varredura válida. A união conservadora
+acumula todas as arestas observadas desde essa base, incluindo as removidas; não
+é substituída a cada scan ou commit. Vários refreshes com mudanças não perdem
+impacto histórico. Pode haver falsos positivos. Para iniciar outra base, use uma
+nova pasta de saída externa, preferencialmente a partir do checkout limpo da base
+desejada; um scan inicial já com mudanças não recupera arestas apagadas antes dele.
+
+Cache ausente, corrompido/incompatível ou commit anterior inexistente causa scan
+completo com nova base, não exige apagar o arquivo manualmente. Compare a base
+retornada antes de inferir cobertura histórica. `impact`/`export` com cache inválido
+falham com diagnóstico; não retornam um impacto vazio fictício. Subprocessos têm
+timeout de 120 segundos. Não rode scans concorrentes na mesma pasta de saída.
+
+No-op reporta `source_hash_reads=0` e `modules_parsed=0`. Isso não significa zero
+I/O: Git, stat, cache, configurações e capacidades da ferramenta são lidos.
+
+## Impacto no review
+
+Somente após o checkpoint confirmado do review, atualize o cache e use o diff
+completo selecionado, incluindo manifests e lockfiles:
+
+```sh
+python3 "{skill-root}/scripts/dependencies.py" --root /caminho/projeto refresh --cruiser /caminho/ferramentas-wizz/node_modules/.bin/depcruise --tsconfig tsconfig.json
+python3 "{skill-root}/scripts/dependencies.py" --root /caminho/projeto impact --diff /caminho/review.diff
+```
+
+Alternativas: `--base <ref>` compara com a árvore de trabalho; `--files <json>`
+recebe array de strings de caminhos relativos ou absolutos dentro do root.
+Normaliza `./`; recusa traversal, tipos inválidos e paths externos. Diff aceita
+prefixos Git padrão, `--no-prefix`, renames e conteúdo não UTF-8. Se gerado com
+`--relative=<pasta>`, forneça a mesma pasta via `--diff-relative <pasta>`; não
+adivinhe a base de um diff fornecido. Diffs vazios/malformados falham.
+
+A saída distingue `touched`, dependentes `direct` e dependentes `transitive`
+(além dos diretos), com proteção contra ciclos. Informe `commit`,
+`baseline_commit` e limites de cobertura. A base do diff pode anteceder a base
+observada: nesse caso, as arestas históricas anteriores não são conhecidas.
+Ausência de impacto estático nunca comprova ausência de impacto em runtime.
+
+## Cobertura e Obsidian
+
+Fontes JS/TS rastreadas e não rastreadas permitidas pelo Git, sem symlinks.
+Imports de tipo, dinâmicos literais, aliases e ciclos são cobertos pelo scanner.
+Vue/Svelte/Python/Swift, imports calculados e resolução específica de bundler não
+têm garantia. Bibliotecas externas são arestas, não módulos percorridos.
+
+`export` gera notas e wikilinks com nomes únicos; imports externos/não resolvidos
+apontam para nós identificados sem nota de código. Só notas `module-` geradas
+são removidas quando obsoletas. Abra a pasta externa `obsidian/` como vault.
+**Aceite visual manual no Obsidian permanece pendente.** Validar Markdown não
+conclui esse aceite.
+
+## Comparação e referências
+
+- [dependency-cruiser CLI](https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md):
+  JSON direto, imports TS e resolução via tsconfig, sem seguir dependências.
+- [pydeps](https://github.com/thebjorn/pydeps): grafo por modulefinder/bytecode,
+  outro contrato de resolução. Suporte Python não implementado nem testado.
+- [Swift dependency scanner](https://github.com/swiftlang/swift/blob/main/docs/Lexicon.md):
+  grafo de módulos/compilação, com SDK e paths; não equivale a imports por arquivo.
+  Suporte Swift não implementado nem testado.
+
+Opções do dependency-cruiser conferidas via Context7. Não instalar pydeps ou
+anunciar fallback Swift por regex.
+
+## Verificação
+
+```sh
+python3 -m unittest discover -s "{skill-root}/scripts" -p 'test_*.py' -v
+```
+
+Os testes unitários de cache/impacto/paths sempre rodam sem scanner. O runner
+recusa uma suíte inteira pulada. `WIZZ_DEPCRUISE` habilita adicionalmente os testes
+de integração com o executável real; ausência dele pula apenas essa camada.

package/src/bmm-skills/1-analysis/wizz-document-project/scripts/dependencies.py

@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+"""Deterministic JS/TS dependency cache, reverse impact and Obsidian export."""
+import argparse
+import hashlib
+import json
+import os
+import re
+from pathlib import Path
+from urllib.parse import quote
+import subprocess
+import tempfile
+import sys
+import posixpath
+
+SCHEMA = 2
+EXTENSIONS = {'.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts'}
+
+
+def run(root, *args):
+    return subprocess.check_output(args, cwd=root, timeout=120, stderr=subprocess.PIPE).decode('utf-8', 'surrogateescape')
+
+
+def git(root, *args):
+    return run(root, 'git', *args)
+
+
+def digest(path):
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def save(path, value):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(mode='w', dir=path.parent, delete=False) as stream:
+        json.dump(value, stream, indent=2, sort_keys=True)
+        stream.write('\n')
+        temporary = stream.name
+    os.replace(temporary, path)
+
+
+def inventory(root):
+    names = git(root, 'ls-files', '--cached', '--others', '--exclude-standard', '-z')
+    return sorted({name for name in names.split('\0') if name and
+                   (root / name).is_file() and not (root / name).is_symlink()})
+
+
+def canonical_output(root):
+    # Outside the checkout: neither PR content nor absolute local paths enter Git.
+    key = hashlib.sha256(os.fsencode(root)).hexdigest()[:24]
+    return Path.home() / '.cache' / 'wizz' / 'dependencies' / key
+
+
+def load_graph(output, root, recover=False):
+    try:
+        graph = json.loads((output / 'graph.json').read_text())
+        if (not isinstance(graph, dict) or graph.get('schema') != SCHEMA or
+                graph.get('root') != str(root) or
+                not all(isinstance(graph.get(key), dict) for key in
+                        ('modules', 'previous_modules', 'hashes', 'stats', 'config')) or
+                not isinstance(graph.get('inventory'), list) or
+                not (graph.get('commit') is None or isinstance(graph.get('commit'), str)) or
+                not all(isinstance(name, str) for name in graph['inventory']) or
+                not all(isinstance(value, str) for value in graph['hashes'].values()) or
+                not set(graph['modules']).issubset(graph['hashes'])):
+            raise ValueError('Invalid or incompatible dependency cache')
+        for modules in (graph['modules'], graph['previous_modules']):
+            if any(not isinstance(name, str) or not isinstance(deps, list) or
+                   any(not isinstance(dep, dict) for dep in deps)
+                   for name, deps in modules.items()):
+                raise ValueError('Invalid dependency edges')
+        return graph
+    except (OSError, ValueError, TypeError):
+        if recover:
+            return {}
+        raise ValueError('Dependency cache unavailable or invalid; run scan with a trusted --cruiser') from None
+
+
+def current_commit(root):
+    try:
+        return git(root, 'rev-parse', '--verify', 'HEAD').strip()
+    except subprocess.CalledProcessError:
+        return None
+
+
+def union_modules(*graphs):
+    result = {}
+    for modules in graphs:
+        for source, dependencies in modules.items():
+            edges = result.setdefault(source, [])
+            for dependency in dependencies:
+                if dependency not in edges:
+                    edges.append(dependency)
+    return result
+
+
+def trusted_tool(root, value):
+    if not value or not Path(value).is_absolute():
+        raise ValueError('Pass a trusted absolute --cruiser or WIZZ_DEPCRUISE outside the repository')
+    tool = Path(value).resolve()
+    if tool.is_relative_to(root.resolve()) or not tool.is_file() or not os.access(tool, os.X_OK):
+        raise ValueError('Trusted cruiser must be an executable outside the repository')
+    return tool
+
+
+def scan(args, root, output):
+    names = inventory(root)
+    sources = [name for name in names if Path(name).suffix in EXTENSIONS]
+    configs = [name for name in names if Path(name).suffix == '.json' or Path(name).name in
+               {'package.json', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'} or
+               Path(name).name.startswith(('tsconfig', 'jsconfig'))]
+    # Hash configuration every time; zero rereads applies to source modules.
+    tool = trusted_tool(root, args.cruiser)
+    config = {name: digest(root / name) for name in configs}
+    config['cruiser'] = str(tool)
+    config['cruiser_version'] = run(root, str(tool), '--version').strip()
+    capabilities = run(root, str(tool), '--info')
+    config['capabilities'] = hashlib.sha256(capabilities.encode()).hexdigest()
+    if any(Path(name).suffix in {'.ts', '.tsx', '.mts', '.cts'} for name in sources):
+        if re.search(r'^\s*x \.ts\s*$', capabilities, re.MULTILINE):
+            raise ValueError('TypeScript transpiler unavailable; install a compatible TypeScript beside dependency-cruiser')
+    config['tsconfig'] = args.tsconfig
+    cache_path = output / 'graph.json'
+    old = load_graph(output, root, recover=True)
+    commit = current_commit(root)
+    if old.get('commit'):
+        try:
+            git(root, 'cat-file', '-e', old['commit'] + '^{commit}')
+        except subprocess.CalledProcessError:
+            old = {}  # Rebase/gc recovery: full scan, explicitly new baseline.
+    compatible = (old.get('schema') == SCHEMA and old.get('root') == str(root)
+                  and old.get('config') == config)
+    previous = old.get('modules', {}) if compatible else {}
+    stats, hashes, changed = {}, {}, []
+    reads = 0
+    for name in sources:
+        stat = (root / name).stat()
+        stamp = [stat.st_size, stat.st_mtime_ns, stat.st_ctime_ns, stat.st_ino]
+        stats[name] = stamp
+        if compatible and name in old['hashes'] and old.get('stats', {}).get(name) == stamp:
+            hashes[name] = old['hashes'][name]
+        else:
+            hashes[name] = digest(root / name)
+            reads += 1
+        if not compatible or hashes[name] != old.get('hashes', {}).get(name):
+            changed.append(name)
+    # New/deleted modules can change resolution of previously unresolved imports.
+    if set(names) != set(old.get('inventory', [])):
+        changed = sources[:]
+    modules = {name: previous[name] for name in sources if name in previous}
+    for offset in range(0, len(changed), 80):
+        batch = changed[offset:offset + 80]
+        command = [str(tool), '--no-config', '--do-not-follow', '.',
+                   '--ts-pre-compilation-deps', '--output-type', 'json']
+        if args.tsconfig:
+            command += ['--ts-config', args.tsconfig]
+        result = json.loads(run(root, *command, '--', *batch))
+        by_name = {module['source']: module for module in result['modules']}
+        for name in batch:
+            if name not in by_name:
+                raise ValueError('Scanner omitted input: ' + name)
+            modules[name] = by_name[name].get('dependencies', [])
+    commit_changes = []
+    if old.get('commit') and commit and old['commit'] != commit:
+        commit_changes = git(root, 'diff', '--name-only', '--no-renames', '-z',
+                             old['commit'] + '..HEAD', '--').split('\0')
+    # Monotonic union since a stable baseline; unrelated scans never discard
+    # removed edges. May over-report. A fresh output starts a new baseline.
+    historical = union_modules(old.get('previous_modules', {}), old.get('modules', {}))
+    graph = dict(schema=SCHEMA, root=str(root), commit=commit, config=config,
+                 baseline_commit=old.get('baseline_commit', commit),
+                 modules=modules, hashes=hashes, stats=stats, inventory=names,
+                 previous_modules=historical,
+                 metrics=dict(source_hash_reads=reads, modules_parsed=len(changed),
+                              source_count=len(sources)),
+                 commit_changes=[name for name in commit_changes if name])
+    save(cache_path, graph)
+    print(json.dumps(graph['metrics'], sort_keys=True))
+
+
+def normalize_files(values, root, relative='.'):
+    if not isinstance(values, list) or any(not isinstance(name, str) or not name or
+                                           '\0' in name or '\\' in name for name in values):
+        raise ValueError('Files must be a JSON array of nonempty path strings')
+    root = root.resolve()
+    prefix = Path(relative)
+    if prefix.is_absolute() or '..' in prefix.parts:
+        raise ValueError('Diff relative directory must be inside the repository')
+    result = []
+    for name in values:
+        candidate = Path(name)
+        if candidate.is_absolute():
+            try:
+                name = str(candidate.resolve().relative_to(root))
+            except ValueError:
+                raise ValueError('Path outside repository: ' + name) from None
+        else:
+            if '..' in candidate.parts:
+                raise ValueError('Traversal path rejected: ' + name)
+            name = str(prefix / candidate)
+        name = posixpath.normpath(name)
+        if name == '.' or name.startswith('../'):
+            raise ValueError('Invalid file path: ' + name)
+        result.append(name)
+    return sorted(set(result))
+
+
+def diff_files(root, diff, relative='.'):
+    raw = Path(diff).read_bytes()
+    if not raw.strip():
+        raise ValueError('Empty diff; impact unavailable')
+    sections = re.split(rb'(?m)(?=^diff --git )', raw)
+    names = []
+    for section in sections:
+        if section.strip():
+            names.extend(diff_section_files(root, section))
+    if not names:
+        raise ValueError('Diff contains no parseable file changes; impact unavailable')
+    return normalize_files(names, root, relative)
+
+
+def diff_section_files(root, raw):
+    # Git parses binary/non-UTF8 content and C-quoted filenames. Parse sections
+    # separately because selected diffs can mix Git/no-index prefix styles.
+    data = subprocess.check_output(['git', 'apply', '--numstat', '-z', '-p0'],
+                                   input=raw, cwd=root, timeout=120,
+                                   stderr=subprocess.PIPE)
+    records = iter(data.decode('utf-8', 'surrogateescape').split('\0'))
+    names = []
+    try:
+        for record in records:
+            if not record:
+                continue
+            fields = record.split('\t', 2)
+            if len(fields) != 3:
+                raise ValueError('Invalid numstat record')
+            name = fields[2]
+            if name:
+                names.append(name)
+            else:
+                names.extend([next(records), next(records)])
+    except StopIteration:
+        raise ValueError('Truncated numstat record') from None
+    # Also collect the source of a deletion/rename. --numstat alone only
+    # reports the destination of pure renames. Git's raw diff parser emits both
+    # via --summary, but rename headers are already unprefixed Git paths.
+    def unquote(value):
+        if value.startswith(b'"'):
+            import codecs
+            if not value.endswith(b'"'):
+                raise ValueError('Invalid quoted Git path')
+            value = codecs.escape_decode(value[1:-1])[0]
+        return value.decode('utf-8', 'surrogateescape')
+    lines = raw.splitlines()
+    standard = any(line.startswith((b'--- a/', b'--- "a/')) for line in lines) or any(
+        line.startswith((b'+++ b/', b'+++ "b/')) for line in lines)
+    # A no-prefix path may itself start with a/ or b/: establish standard
+    # prefixes from paired diff --git headers, including add/delete sections.
+    headers = [line for line in lines if line.startswith(b'diff --git ')]
+    if headers:
+        standard = all(re.match(rb'diff --git (?:"a/|a/).+ (?:"b/|b/)', line) for line in headers)
+    rename_targets = [unquote(line[len(b'rename to '):]) for line in lines if line.startswith(b'rename to ')]
+    if rename_targets and any(name in rename_targets for name in names):
+        standard = False
+    if standard:
+        names = [name[2:] if name.startswith(('a/', 'b/')) else name for name in names]
+    for line in lines:
+        for marker in (b'rename from ', b'rename to ', b'copy from ', b'copy to '):
+            if line.startswith(marker):
+                names.append(unquote(line[len(marker):]))
+    if not names:
+        raise ValueError('Diff contains no parseable file changes; impact unavailable')
+    return names
+
+
+def impact(args, root, output):
+    graph = load_graph(output, root)
+    if args.base:
+        touched = normalize_files([name for name in git(
+            root, 'diff', '--name-only', '--no-renames', '-z',
+            args.base, '--').split('\0') if name], root)
+    elif args.files:
+        touched = normalize_files(json.loads(Path(args.files).read_text()), root)
+    else:
+        touched = diff_files(root, args.diff, getattr(args, 'diff_relative', '.'))
+    reverse = {}
+    for modules in [graph['previous_modules'], graph['modules']]:
+        for source, dependencies in modules.items():
+            for dependency in dependencies:
+                target = dependency.get('resolved')
+                if target and not dependency.get('couldNotResolve'):
+                    reverse.setdefault(target, set()).add(source)
+    direct = set().union(*(reverse.get(name, set()) for name in touched)) - set(touched)
+    visited, queue = set(touched), touched[:]
+    while queue:
+        for dependent in reverse.get(queue.pop(), set()):
+            if dependent not in visited:
+                visited.add(dependent)
+                queue.append(dependent)
+    result = dict(commit=graph['commit'], baseline_commit=graph.get('baseline_commit'),
+                  touched=touched, direct=sorted(direct),
+                  transitive=sorted(visited - set(touched) - direct),
+                  coverage='Static JS/TS imports; conservative edge union since baseline; historical edges before baseline unavailable; not a completeness guarantee')
+    print(json.dumps(result, indent=2))
+
+
+def export(root, output):
+    graph = load_graph(output, root)
+    if graph['root'] != str(root):
+        raise ValueError('Graph belongs to another checkout')
+    # Encoded path plus digest avoids duplicate basenames and wiki metacharacters.
+    notes = output / 'obsidian'
+    notes.mkdir(parents=True, exist_ok=True)
+    modules = graph['modules']
+    identifiers = {name: 'module-' + quote(name, safe='')[:140] + '-' + hashlib.sha256(name.encode()).hexdigest()
+                   for name in modules}
+    expected = {identifier + '.md' for identifier in identifiers.values()}
+    for stale in notes.glob('module-*.md'):
+        if stale.name not in expected:
+            stale.unlink()
+    for name, dependencies in sorted(modules.items()):
+        lines = ['# ' + name, '', 'Source: `' + name + '`', '', '## Imports', '']
+        for dependency in dependencies:
+            target = dependency.get('resolved')
+            if target in identifiers:
+                lines.append('- [[' + identifiers[target] + ']]')
+            else:
+                external = (name + ':' + dependency['module'] if dependency.get('couldNotResolve')
+                            else target or dependency['module'])
+                identifier = ('external-' + quote(external, safe='')[:140] + '-' +
+                              hashlib.sha256(external.encode()).hexdigest())
+                lines.append('- [[' + identifier + ']] (external or unresolved: `' +
+                             dependency['module'] + '`)')
+        (notes / (identifiers[name] + '.md')).write_text('\n'.join(lines) + '\n')
+    print(json.dumps({'notes': len(modules), 'directory': str(notes)}))
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--root', default='.')
+    parser.add_argument('--output', help='External artifact directory (default: canonical user cache)')
+    commands = parser.add_subparsers(dest='command', required=True)
+    for name in ('scan', 'refresh'):
+        scanner = commands.add_parser(name)
+        scanner.add_argument('--cruiser', default=os.environ.get('WIZZ_DEPCRUISE'),
+                             help='Trusted absolute external executable; never taken from cache')
+        scanner.add_argument('--tsconfig', help='Explicit project-relative tsconfig for aliases')
+    reviewer = commands.add_parser('impact')
+    selection = reviewer.add_mutually_exclusive_group(required=True)
+    selection.add_argument('--base', help='Git ref compared with working tree, including index')
+    selection.add_argument('--files', help='JSON array of repository-relative paths')
+    selection.add_argument('--diff', help='Unified diff selected by code-review')
+    commands.add_parser('export')
+    reviewer.add_argument('--diff-relative', default='.', help='Explicit Git --relative directory, relative to root')
+    args = parser.parse_args()
+    root = Path(args.root).resolve()
+    root = Path(git(root, 'rev-parse', '--show-toplevel').strip()).resolve()
+    output = (Path(args.output) if args.output else canonical_output(root)).resolve()
+    if output.is_relative_to(root):
+        raise ValueError('Dependency output must be outside the repository; omit --output for canonical cache')
+    if args.command in ('scan', 'refresh'):
+        if args.tsconfig:
+            args.tsconfig = normalize_files([args.tsconfig], root)[0]
+        scan(args, root, output)
+    elif args.command == 'impact':
+        impact(args, root, output)
+    else:
+        export(root, output)
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except (ValueError, OSError, KeyError, TypeError, subprocess.SubprocessError) as error:
+        print('Dependency error: ' + str(error), file=sys.stderr)
+        sys.exit(1)