DEV Community

CrabPascal
CrabPascal

Posted on

Audit Deep Dive: IDE, CI, and Docs | Auditoria: IDE, CI e documentação

#pascal #vscode #documentation #devops

Bilingual post · Post bilíngue

Jump to: English · Português

English {#english}

Audit Deep Dive: IDE, CI, and Docs

Series — Part 2: Previous: Audit Deep Dive: Tests and Harness (053-audit-tests-harness). Report: technical-debt/audit/05-rafael-ide-ci-docs.

Rafael's audit closes the five-part technical review with the surfaces users touch daily: VS Code/Cursor extension, CI harness, and documentation governance. Compiler internals can be brilliant; if Problems panel stays empty and docs claim v2.8.0, adoption stalls.

What Rafael audited

  • vscode-extension/extension.js and package.json
  • Problem matcher declarations vs actual diagnostic parsing
  • Version drift between docs, extension, and test README
  • CI fragility overlapping Marina's HTTP harness findings

Full details: technical-debt/audit/05-rafael-ide-ci-docs.

TD-IDE-001 — Problems panel not populated (P1)

The extension runs crab-pascal check but leaves a TODO at lines 185–190: parse stdout and show problems. Today it console.logs output — useful for developers with DevTools open, invisible for everyone else.

package.json declares problemMatchers with regex for file:line:col: severity message, yet no DiagnosticCollection integration was found in extension code.

Impact: Users miss structured errors in-editor. The IDE feels broken compared to Delphi or Rust analyzer UX.

Target: Sprint 16 (v2.24.0) — Rafael + Marina acceptance test: failing check must appear in Problems.

TD-IDE-002 — Extension "build" calls build-exe (P1)

Commands crabpascal.build and crabpascal.compile map to build-exe, not build. Users clicking "Build" never exercise the C codegen path the CLI documents as build.

Impact: Parity gaps between run, build, and build-exe stay hidden. Extension users assume native build parity that CI never validates.

Fix: Align command mapping; add CI step calling crab-pascal build directly (Sprint 10/S16).

TD-IDE-003 — Problem matcher without parser bridge (P2)

Manifest regex exists; extension does not transform compiler output into VS Code diagnostic objects. Even when stdout contains valid spans (post-Sprint 1), UI integration fails.

TD-CI-001 — HTTP-dependent example harness (P1)

Same root cause as TD-TEST-002: test_exemplos_completo.ps1 requires live Horse server on port 9001. Rafael's audit frames this as governance — release gates should not depend on localhost timing.

TD-DOCS-001 — Test docs version drift (P3)

tests/README.md header still says v2.8.0. Stakeholders reading docs get a false baseline; overlaps Marina's TD-TEST-004.

Developer experience today

What works:

// package.json contributes tasks and problemMatcher schema
"problemMatchers": [{ "owner": "crabpascal", "pattern": { ... } }]
Enter fullscreen mode Exit fullscreen mode 
// extension.js — check runs, but diagnostics don't reach UI yet
await runCrabPascal('check', uri.fsPath);
// TODO: Parse e mostre problemas
console.log(stdout);
Enter fullscreen mode Exit fullscreen mode

What users expect after Sprint 1 diagnostics investment:

  1. Open .pas file
  2. Save triggers check
  3. Red squiggles on exact line/column
  4. Problems panel lists all issues

We are between steps 2 and 3.

CI governance recommendations

Rafael's audit reinforces squad rules from roadmap/squad:

  • No release tag without acceptance tests passing
  • Harness flakes get skip + issue, not ignored red builds
  • Extension version bumps track binary Cargo.toml version

Suggested pipeline layers:

Layer Runs Environment
Fast cargo test, crab-pascal check fixtures Every PR
Parity run_build_parity Agents with GCC
Integration Horse HTTP harness Manual / nightly

Mintlify cross-links

  • usage/integracao-ide-completa-v2-0-0 — target IDE feature set
  • usage/guia-integracao-vscode-cursor — setup guide
  • technical-debt/audit-overview — full P0/P1 matrix
  • roadmap/squad — Rafael's squad lead responsibilities

Takeaway for users

Install the extension for command palette integration and optional auto-install of crab-pascal.exe. Until Sprint 16 lands, run check in terminal for reliable diagnostics with real spans. Do not assume Problems panel parity with Delphi yet.

Takeaway for contributors

IDE and docs debt is highly visible — fixes improve every user immediately. Pick TD-IDE-001 with a small PR wiring vscode.Diagnostic from existing check JSON or regex output.

Next: Learn Compilers Using CrabPascal (055-compiler-course-with-crabpascal) — shifting from audit to education.

Português {#portugus}

Auditoria: IDE, CI e documentação

Série — Parte 2: Anterior: Auditoria: testes e harness (053-audit-tests-harness). Relatório: technical-debt/audit/05-rafael-ide-ci-docs.

A auditoria do Rafael fecha a revisão técnica em cinco partes com as superfícies que usuários tocam diariamente: extensão VS Code/Cursor, harness de CI e governança de documentação. Internals brilhantes não adiantam se o painel Problems fica vazio e docs claimam v2.8.0 — adoção trava.

O que o Rafael auditou

  • vscode-extension/extension.js e package.json
  • Declarações de problem matcher vs parsing real de diagnósticos
  • Drift de versão entre docs, extensão e README de testes
  • Fragilidade de CI sobrepondo achados HTTP da Marina

Detalhes completos: technical-debt/audit/05-rafael-ide-ci-docs.

TD-IDE-001 — Painel Problems não populado (P1)

A extensão roda crab-pascal check mas deixa TODO nas linhas 185–190: parsear stdout e mostrar problemas. Hoje faz console.log da saída — útil para quem abre DevTools, invisível para o resto.

package.json declara problemMatchers com regex para file:line:col: severity message, porém nenhuma integração com DiagnosticCollection foi encontrada no código da extensão.

Impacto: Usuários perdem erros estruturados no editor. A IDE parece quebrada comparada a Delphi ou Rust analyzer.

Alvo: Sprint 16 (v2.24.0) — teste de aceitação Rafael + Marina: check falhando deve aparecer em Problems.

TD-IDE-002 — "Build" da extensão chama build-exe (P1)

Comandos crabpascal.build e crabpascal.compile mapeiam para build-exe, não build. Usuários clicando "Build" nunca exercitam o caminho de codegen C que a CLI documenta como build.

Impacto: Gaps de paridade entre run, build e build-exe ficam escondidos. Usuários da extensão assumem paridade de build nativo que o CI nunca valida.

Correção: Alinhar mapeamento de comandos; adicionar passo de CI chamando crab-pascal build diretamente (Sprint 10/S16).

TD-IDE-003 — Problem matcher sem ponte de parser (P2)

Regex no manifest existe; extensão não transforma saída do compilador em objetos Diagnostic do VS Code. Mesmo com stdout contendo spans válidos (pós-Sprint 1), integração na UI falha.

TD-CI-001 — Harness de exemplos dependente de HTTP (P1)

Mesma causa raiz de TD-TEST-002: test_exemplos_completo.ps1 exige servidor Horse ao vivo na porta 9001. A auditoria do Rafael enquadra como governança — gates de release não devem depender de timing em localhost.

TD-DOCS-001 — Drift de versão em docs de testes (P3)

Cabeçalho de tests/README.md ainda diz v2.8.0. Stakeholders lendo docs recebem baseline falso; sobrepõe TD-TEST-004 da Marina.

Experiência do desenvolvedor hoje

O que funciona:

// package.json contribui tasks e schema de problemMatcher
"problemMatchers": [{ "owner": "crabpascal", "pattern": { ... } }]
Enter fullscreen mode Exit fullscreen mode 
// extension.js — check roda, mas diagnósticos não chegam na UI
await runCrabPascal('check', uri.fsPath);
// TODO: Parse e mostre problemas
console.log(stdout);
Enter fullscreen mode Exit fullscreen mode

O que usuários esperam após investimento Sprint 1 em diagnósticos:

  1. Abrir arquivo .pas
  2. Save dispara check
  3. Squiggles vermelhos na linha/coluna exata
  4. Painel Problems lista todos os issues

Estamos entre os passos 2 e 3.

Recomendações de governança CI

A auditoria do Rafael reforça regras da squad em roadmap/squad:

  • Sem tag de release sem testes de aceitação passando
  • Flakes de harness ganham skip + issue, não builds vermelhos ignorados
  • Bumps de versão da extensão acompanham versão binária em Cargo.toml

Camadas sugeridas de pipeline:

Camada Roda Ambiente
Rápida cargo test, crab-pascal check fixtures Todo PR
Paridade run_build_parity Agents com GCC
Integração Harness HTTP Horse Manual / nightly

Cross-links Mintlify

  • usage/integracao-ide-completa-v2-0-0 — feature set alvo da IDE
  • usage/guia-integracao-vscode-cursor — guia de setup
  • technical-debt/audit-overview — matriz P0/P1 completa
  • roadmap/squad — responsabilidades do Rafael como squad lead

Conclusão para usuários

Instale a extensão para palette de comandos e auto-instalação opcional de crab-pascal.exe. Até Sprint 16, rode check no terminal para diagnósticos confiáveis com spans reais. Não assuma paridade do painel Problems com Delphi ainda.

Conclusão para contribuidores

Débito de IDE e docs é altamente visível — correções melhoram todo usuário imediatamente. Pegue TD-IDE-001 com PR pequeno ligando vscode.Diagnostic à saída JSON ou regex existente do check.

Próximo: Aprenda compiladores com CrabPascal (055-compiler-course-with-crabpascal) — da auditoria para educação.

Published on dev.to/@crabpascal · Código em CrabPascal

Top comments (0)