Referencia de la línea de comandos

Sinopsis

probe init [--repo PATH] [--language go|typescript|javascript|python|rust]
probe lint [--base main] [--head HEAD] [--ci] [flags]
probe review [--base main] [--reviewer=false] [--ci] [flags]
probe review [flags] BASE..HEAD
probe plan --intent-file FILE [--base main] [--ci]
probe review --plan .probe/PLAN.json [flags]
probe report [--input .probe/confidence-report.json] [--out DIR] [--format LIST] [--report-url URL]
probe version

• lint analiza un cambio de forma estática. Nunca ejecuta código del repositorio ni llama a un proveedor de IA.
• review añade comprobaciones en un sandbox de Docker, las etapas de evidencia opcionales (tests base modificados, tests afectados, fuzzing diferencial, mutación, preparación de dependencias) y, cuando hay un modelo configurado, una investigación con IA.
• plan pide al proveedor configurado un plan de implementación antes de escribir código, lo evalúa con reglas fijas y lo convierte en un contrato con el que lint --plan y review --plan contrastan el diff.
• Solo se analizan los archivos confirmados en un commit; las ediciones sin commit y los archivos no rastreados se ignoran.
• Por defecto, los informes se escriben en .probe/ dentro del repositorio. La salida de consola se mantiene breve.
• Las opciones aceptan uno o dos guiones (-ci o --ci). Los booleanos se activan con --ci o --ci=true y se desactivan con --checks=false. Un valor se indica como --base main o --base=main.
• Ejecuta probe <command> --help para ver las opciones de un comando.

Elegir revisiones

Ambos lados de una comparación se resuelven en ID de commit inmutables, que quedan registrados en el informe. Se gestionan los renombrados, las eliminaciones, los archivos binarios y los cambios de tipo de archivo.

Un rango puede aparecer antes o después de las opciones: probe review main..HEAD --ci y probe review --ci main..HEAD son equivalentes. Se acepta como máximo un rango. Funciona cualquier revisión que Git entienda: ramas, etiquetas, origin/main, HEAD~3 o un ID de commit. Los jobs de CI necesitan suficiente historial para resolver la base (por ejemplo fetch-depth: 0).

La política de confianza se lee siempre de la rama base, nunca del cambio en revisión, para que una pull request no pueda relajar sus propias reglas.

probe lint

Análisis estático de un cambio: comparación con Git, señales de riesgo y un informe. Sin Docker, sin llamadas a proveedores, sin ejecutar código del repositorio. Se puede ejecutar con seguridad en ramas no confiables.

probe lint HEAD~1..HEAD                 # the last commit
probe lint --base origin/main --ci      # this branch as a pull request, for CI
probe lint --base main --format json    # JSON report only
probe lint --base main --plan .probe/PLAN.json   # scope drift against an approved plan

probe review

Todo lo que hace lint, más los comandos test, typecheck, build y coverage de la política en contenedores Docker desechables, más una investigación con IA cuando hay un modelo configurado. Requiere Docker con contenedores Linux y una sandbox.image precargada.

probe review --base main --ci                        # typical pull request run
probe review HEAD~1..HEAD --reviewer=false           # checks only, no provider
probe review --base main --checks=false --reviewer=false   # static only, like lint
probe review --base main --intent-file PR.md         # give acceptance criteria
probe review --base main --impacted-tests --base-tests --ci   # run tests on both revisions
probe review --base main --format markdown,json,sarif,pr-comment --report-url "$RUN_URL"

La preparación de dependencias se ejecuta primero, cuando la política tiene un objeto prepare. Después, las comprobaciones se ejecutan en este orden: test, typecheck, build y coverage, seguidas de las etapas de evidencia y del revisor. Cada contenedor se ejecuta sin root, con la raíz y el código fuente montados en solo lectura, sin capacidades añadidas, sin red por defecto y con los límites de CPU, memoria, PID y tiempo de la política del sandbox. Nunca se montan el socket de Docker, tu copia de trabajo ni las claves de API. Si falta Docker o la imagen, la ejecución termina con el código 4; nunca se recurre a tu máquina anfitriona.

probe plan

Antes de escribir el cambio: el proveedor configurado simula, en solo lectura, cómo implementaría una intención sobre el commit base y envía un plan estructurado (archivos, símbolos, dependencias, pasos). Probe lo evalúa con reglas fijas y escribe PLAN.json y PLAN.md. El modelo produce el plan; nunca juzga su riesgo. No se modifica ni se ejecuta nada.

Las herramientas del planificador son de solo lectura y trabajan sobre una instantánea del commit base: list_files, read_file, search_code y las basadas en el índice find_references, inspect_symbol y find_callers, y después submit_plan una sola vez. La evaluación señala cuatro categorías a partir únicamente del plan y del commit base:

Códigos de salida: 0; 2 con --ci cuando se señala una categoría; 3 uso o configuración; 4 fallo del proveedor o ningún plan aceptado.

Desviación del alcance: --plan

lint --plan y review --plan leen el contrato del plan y lo comparan con el diff real. Cada diferencia en el diff se convierte además en una señal plan_drift. La sección queda en drifted cuando un elemento es de gravedad media o superior.

probe plan --intent-file task.md --ci                     # 1. plan; exit 2: a human validates it
# 2. an agent implements the plan
probe review --base origin/main --plan .probe/PLAN.json --ci   # 3-4. exit 0: merge; exit 2: review

El plan gate

review --plan termina con una decisión, plan_drift.decision, que se imprime en stdout y al principio de la sección Plan Conformance. Con --ci, es el código de salida.

Las marcas y el contrato guardados en PLAN.json nunca se consideran de confianza: el contrato se vuelve a derivar de la propuesta, de modo que un plan editado no puede ampliar el alcance sin evaluación, y probe report recalcula la decisión a partir del informe registrado. El gate es una decisión de proceso, no un veredicto sobre la corrección. Un plan que no señala nada no demuestra que el cambio sea seguro, y la desviación no comprueba que el cambio implemente la intención. Consulta planes previos al cambio y la receta de CI.

probe init

Escribe un .probe.json inicial para el proyecto. Se niega a sobrescribir un archivo existente. Revisa los comandos y la imagen y, después, haz commit del archivo en tu rama base.

probe report

Vuelve a generar un informe JSON guardado, por ejemplo para regenerar el Markdown o producir SARIF en CI. No se vuelve a ejecutar nada, y regenerar no autentica las evidencias que contiene; cada estado se vuelve a derivar de las comprobaciones registradas, así que un informe editado se corrige en lugar de darse por bueno.

probe version y ayuda

Códigos de salida

Ningún código significa "aprobado". Un 0 indica que no se reprodujo nada, no que el cambio sea correcto.

Variables de entorno

El proveedor de IA pertenece al despliegue y no al repositorio, así que estos ajustes pueden venir del entorno. Nada más puede hacerlo: la imagen, los comandos, los presupuestos y las rutas sensibles los decide siempre la política de confianza.

Una variable vacía cuenta como no definida. Los archivos de claves se leen enteros, sin los espacios en blanco del principio y del final, con un límite de 8 KiB, y deben contener una sola línea. Cuando se ejecuta el revisor, el registro indica de dónde procede cada valor, nunca el valor en sí. Quien controla este entorno elige adónde se envía el código fuente redactado: mantenlo fuera de los jobs que ejecutan código de forks no confiables.

Archivos de salida

Añade .probe/ a .gitignore. La consola muestra un único resumen: archivos y líneas modificados, número de señales y de problemas reproducidos, la superficie de revisión enfocada y la ejecución de las líneas modificadas.

Señales de riesgo

Las señales son motivos para mirar, no defectos confirmados. Los archivos de Go reciben un análisis sintáctico; TypeScript/JavaScript, Python, Rust y otros lenguajes usan heurísticas de texto etiquetadas. Las señales sobre las mismas líneas se fusionan en un único rango de revisión en el informe. Las señales de archivo (sensitive_path, dependency_change, migration_change, infrastructure_change, binary_change, file_deleted, file_type_change, large_change, branch_growth, no_test_change, prepare_input_changed, plan_drift) afectan al archivo, no a una línea: el informe las muestra bajo el archivo como archivo completo, y el JSON las marca con "scope": "file". Su line solo las sitúa en la primera línea modificada del archivo.

Análisis de impacto

Con --impact (el valor predeterminado), lint y review construyen en el host un índice estático del commit candidato, a partir de los objetos de Git confirmados, sin ejecutar código del repositorio. Para cada función modificada, enumera los lugares del código sin cambios que la llaman y los tests existentes que la alcanzan en 3 llamadas como máximo, añade señales impacted_caller bajas y da soporte a las herramientas find_references, inspect_symbol y find_callers del revisor.

Todas las respuestas son aproximadas: un llamador listado es un lugar que revisar, y la ausencia de llamadores no demuestra que no exista ninguno. --impacted-tests solo ejecuta tests de Go que alcanzan el cambio. Consulta análisis de impacto.

Lenguajes

Archivo de política: .probe.json

La política decide qué comandos se ejecutan, en qué imagen, con qué límites y si se usa un proveedor de IA. Se lee de .probe.json en la rama base o de --config PATH. Si no hay ninguna, se aplican los valores predeterminados integrados para el lenguaje detectado. Las claves que omitas toman los valores predeterminados que se muestran a continuación.

El archivo debe ser un único objeto JSON de 1 MiB como máximo. Las claves desconocidas, los nombres de comando desconocidos y las claves duplicadas se rechazan con el código 3, de modo que un binario antiguo rechaza una clave que no conoce.

{
  "version": 1,
  "language": "go",
  "commands": {
    "test": ["go", "test", "./..."],
    "typecheck": ["go", "vet", "./..."],
    "build": ["go", "build", "./..."],
    "generated_test": ["go", "test", "{package}"],
    "coverage": ["go", "test", "-covermode=count", "-coverprofile={coverage_out}", "./..."]
  },
  "sandbox": { "image": "golang:1.26-bookworm", "network": false, "timeout_seconds": 120,
               "max_runtime_seconds": 600, "max_output_bytes": 65536, "memory_mb": 1024, "cpus": 2 },
  "reviewer": { "endpoint": "https://api.openai.com/v1/chat/completions", "model": "",
                "api_key_env": "PROBE_API_KEY", "max_iterations": 20, "max_generated_tests": 10,
                "timeout_seconds": 600, "max_input_bytes": 131072 },
  "sensitive_paths": ["**/auth/**", "**/payment*/**", "**/migrations/**", ".github/workflows/**", ".probe.json"]
}

commands

Cada comando es un array argv, no una cadena de shell: ["npm", "test"], nunca "npm test". Como máximo 128 argumentos; configura solo las comprobaciones que tu proyecto ofrece.

sandbox

reviewer

sensitive_paths

Globs de rutas que, al cambiar, generan siempre una señal sensitive_path alta. Las rutas son relativas a la raíz del repositorio, con barras normales; * coincide dentro de un segmento de ruta y ** a través de segmentos. Se rechazan las rutas absolutas, las barras invertidas y ...

fuzz v0.4

Pasa las mismas entradas con semilla por cada función de Go de nivel de paquete modificada y cada función exportada de TS/JS modificada (con la firma sin cambios), sobre la base y el candidato, y compara lo que registraron las dos revisiones. Una función diverged es una observación, nunca un defecto: solicita revisión (código 2 con --ci) y nunca produce el código 1. {} lo activa con los valores predeterminados.

mutation v0.4

Hace pequeños cambios deterministas en las líneas añadidas de los archivos de Go modificados que no son de test y ejecuta los tests del paquete una vez por mutante. Un mutante que ningún test detecta se convierte en una señal surviving_mutant media; no se calcula ninguna puntuación. Las cuatro claves son obligatorias.

"mutation": {
  "command": ["go", "test", "-json", "-count=1", "-failfast", "{package}"],
  "max_mutants": 20, "timeout_seconds": 60, "max_runtime_seconds": 300
}

prepare v0.4

Permite que la política de confianza de la rama base construya la capa de dependencias: antes de que se ejecute código del candidato, su comando se ejecuta una vez, en un contenedor acotado, sobre los archivos de dependencias exportados del commit base, y el contenedor se convierte en la imagen local de todas las comprobaciones. Una revisión posterior con la misma base y las mismas entradas la reutiliza. Si no produce ninguna imagen, la revisión termina con el código 4; nunca recurre a la imagen sin preparar.

"prepare": { "command": ["go", "mod", "download"], "inputs": ["go.mod", "go.sum"], "network": true }

Valores predeterminados por lenguaje

Los escribe probe init y se usan cuando la rama base no tiene política. Las imágenes estándar de Node.js, Python y Rust no contienen tus dependencias: construye una imagen que las incluya, o añade un objeto prepare, y adapta los comandos.

Revisor de IA

Opcional. Cuando hay un modelo configurado, review le permite investigar el cambio con herramientas acotadas: leer archivos y diffs redactados, buscar en el código fuente, consultar referencias y llamadores en el índice estático, ejecutar comprobaciones existentes y crear y ejecutar tests temporales sobre la base y el candidato. No tiene shell ni forma de descargar URL. Sus afirmaciones siguen siendo hipótesis hasta que un test reproduce una diferencia.

{
  "reviewer": {
    "endpoint": "https://your-provider.example/v1",
    "model": "your-tool-capable-model",
    "api_key_env": "PROBE_API_KEY"
  }
}

export PROBE_API_KEY=…                       # from your shell or CI secret store
probe review --base main --config .probe.json   # try it before committing
probe review --base main --reviewer=false            # turn it off for one run

• Solo la política de confianza, --config o el entorno de despliegue pueden activar el revisor; una pull request no puede.
• Se envía al proveedor un contexto de código fuente acotado y redactado. El enmascaramiento de secretos se hace lo mejor posible, sin garantías; usa un proveedor local (por ejemplo http://127.0.0.1:1234/v1) si el código fuente debe quedarse en local.
• Las claves de API nunca entran en los contenedores de test. lint nunca llama a un proveedor.
• Los fallos del proveedor y los presupuestos agotados conservan los resultados deterministas y marcan la investigación como incompleta; con --ci, eso requiere revisión humana.