feat(docs): CODEMAP como camada de documentação (v0.5.3) - #17
Merged
Conversation
Índice gerado do código, uma linha por arquivo, para a IA achar o arquivo certo sem ler os errados. Fecha a outra metade da economia que a regra das 200 linhas começou: arquivo curto é barato de ler, mas sem índice continua caro de achar. A descrição é extraída do cabeçalho `Purpose:` que a `code-style` já exigia — uma fonte de verdade, não duas. Arquivo sem cabeçalho aparece marcado no mapa, então o codemap fiscaliza a regra de cabeçalho de quebra. Escopo: o projeto derivado. Dentro do repo do OS o script sai 0 sem escrever nada, detectado pelo marcador `.aios-self` que o os-self-test já usava. Enforcement em quatro lugares porque mapa desatualizado é pior que mapa nenhum — o agente confia, pula a leitura e age com informação velha: CI, sprint-management, release-check e os-self-test. Novo: - scripts/codemap.js — gerador e verificador (--check sai 1 na divergência) - .claude/rules/codemap.md — 12ª regra - .claude/skills/codemap/SKILL.md — 28ª skill - templates/project/CODEMAP.template.md — placeholder do projeto novo - scripts/test/codemap.test.js — 17 testes (92 no total) Corrigido: - link do CODEMAP.template.md que resolvia na raiz do destino mas não da origem (pego pelo próprio os-self-test) - numeração duplicada no checklist "Close sprint" Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Warning Review limit reached
Next review available in: 10 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (10)
📝 WalkthroughWalkthroughThis change adds a generated ChangesCODEMAP workflow
Estimated code review effort: 3 (Moderate) | ~25 minutes Sequence Diagram(s)sequenceDiagram
participant ProjectSetup
participant CodemapCLI
participant Git
participant CI
ProjectSetup->>CodemapCLI: run generator
CodemapCLI->>Git: read tracked project files
Git-->>CodemapCLI: return source paths
CodemapCLI-->>ProjectSetup: write CODEMAP.md
CI->>CodemapCLI: run --check
CodemapCLI-->>CI: return freshness status
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 2📝 Generate docstrings 💡
🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (1)
.claude/skills/codemap/SKILL.md (1)
6-77: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winComplete the documented
SKILL.mdworkflow structure.This skill defines its trigger and main commands, but it does not define explicit Inputs, Outputs, Validation checklist, Related agents, or Failure modes. Add these sections so the workflow has a complete execution and verification contract.
As per
docs/skill-system.mdlines 104-115, everySKILL.mdshould document Purpose, When to use, Inputs, Steps, Outputs, Validation checklist, Related rules, Related agents, and Failure modes.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.claude/skills/codemap/SKILL.md around lines 6 - 77, Complete the Codemap SKILL.md workflow by adding explicit Purpose, When to use, Inputs, Steps, Outputs, Validation checklist, Related rules, Related agents, and Failure modes sections. Preserve the existing codemap commands and guidance, organizing them under the corresponding sections and documenting the required execution and verification behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/rules/codemap.md:
- Line 3: Atualize a descrição de CODEMAP.md para afirmar que ele lista todo
arquivo de código rastreado pelo Git, alinhando a reivindicação ao contrato
atual do gerador; não altere a lógica de coleta ou verificação de atualização.
- Around line 11-17: Update regeneration guidance in .claude/rules/codemap.md
lines 11-17, .claude/skills/codemap/SKILL.md line 37, and README.md lines
227-232 to trigger codemap generation after any line-count or Purpose: change,
as well as file creation, removal, renaming, or moving; retain 200 lines only as
a warning threshold in SKILL.md.
- Line 7: Make the read-first guidance conditional on operating in a derived
project or when the .aios-self marker is absent, rather than requiring
CODEMAP.md unconditionally. Update .claude/rules/codemap.md:7-7 and
.claude/skills/codemap/SKILL.md:8-12 consistently; both sites require direct
changes.
In `@CHANGELOG.md`:
- Line 33: Replace the unclear phrase “regra de cabeçalho de quebra” with “regra
de cabeçalho” or “regra de cabeçalho de código” in both release records:
CHANGELOG.md lines 33-33 and RELEASE-NOTES-v0.5.3.md lines 55-55.
In `@scripts/codemap.js`:
- Around line 71-75: The continuation check in the header parsing loop should
remove the applicable comment marker, including hash markers, before evaluating
indentation so wrapped `#` header lines append correctly. Update the relevant
expression in the codemap parsing logic and add a regression test covering a
wrapped `# Purpose:` header.
- Around line 99-103: Update the file-processing flow around the abs existence
check to call fs.lstatSync(abs) and skip entries whose stats identify a symbolic
link before invoking fs.readFileSync. Keep regular tracked files processed as
before, and ensure symlink targets are never read.
In `@templates/project/CODEMAP.template.md`:
- Around line 13-15: Remove the Markdown link syntax from the app.ts, login.ts,
and session.ts entries in the project codemap, leaving their filenames as plain
text while preserving the descriptions and metadata.
---
Nitpick comments:
In @.claude/skills/codemap/SKILL.md:
- Around line 6-77: Complete the Codemap SKILL.md workflow by adding explicit
Purpose, When to use, Inputs, Steps, Outputs, Validation checklist, Related
rules, Related agents, and Failure modes sections. Preserve the existing codemap
commands and guidance, organizing them under the corresponding sections and
documenting the required execution and verification behavior.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 7501a099-5358-41f0-ae74-7b71c5d7caed
📒 Files selected for processing (21)
.claude/rules/codemap.md.claude/rules/documentation-layers.md.claude/skills/codemap/SKILL.md.claude/skills/release-check/SKILL.md.claude/skills/sprint-management/SKILL.md.github/workflows/ci.ymlCHANGELOG.mdCLAUDE.mdREADME.mdRELEASE-NOTES-v0.5.3.mdWIZARD.mddocs/documentation-layers.mddocs/skill-system.mddocs/wizard/phase-5-chegada.mdscripts/codemap.jsscripts/os-self-test.jsscripts/test/codemap.test.jssession-log/2026-08-08-v0.5.3-codemap.mdsession-log/INDEX.mdtemplates/project/CLAUDE.mdtemplates/project/CODEMAP.template.md
O lychee resolvia os caminhos sintéticos do exemplo (src/app.ts, src/features/auth/*.ts) a partir de templates/project/, onde não existem. O os-self-test não pegou porque só valida links .md. Mesma classe do link da regra corrigido antes: o template é escrito de um lugar e lido de outro. A tabela agora fica dentro de uma cerca ```markdown — ela ilustra a saída do gerador, não é saída. No arquivo gerado os links são reais e resolvem. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Dois defeitos de código, ambos reproduzidos antes e depois: - symlink rastreado era seguido na leitura. Um `secrets.js` que fosse link para fora do repo tinha seu primeiro comentário copiado para dentro do CODEMAP.md commitado. Verificado: git registra `120000 link.js`, e o conteúdo externo aparecia no mapa. Agora `lstatSync` pula links. - continuação de cabeçalho `#` era descartada. O teste de indentação removia só `*`, então o `#` da segunda linha bloqueava o match e headers Python/shell quebrados em duas linhas perdiam a metade final. Quatro de documentação, a terceira sendo uma contradição real entre o que a skill dizia e o que o CI faz: - a skill afirmava "não precisa regenerar ao editar o corpo". Falso: o mapa grava a contagem exata de linhas, então quase toda edição o invalida e o --check acusa. Corrigido em 8 arquivos, com a surpresa explicitada em vez de escondida. - "todo arquivo de código" → "todo arquivo de código rastreado pelo Git": collect() lê git ls-files, arquivo não adicionado não aparece. - ler o CODEMAP.md era instrução incondicional, mas dentro do repo do OS o arquivo não existe por design. Agora a regra e a skill dizem o que fazer nesse caso. - "de quebra" ficava ambíguo colado em "regra de cabeçalho". Reescrito como "efeito colateral". 2 testes novos (94 no total): a continuação com `#`, e um de integração que roda o gerador num repo temporário com symlink e falha se o conteúdo externo vazar. O segundo se auto-pula onde symlink não é suportado. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
O problema
Duas regras deste OS resolvem metades diferentes do mesmo problema, e até agora só uma existia.
Arquivo de código abaixo de 200 linhas (
code-style) torna qualquer arquivo barato de ler. Mas barato de ler não é fácil de achar: um agente procurando "onde acontece o login" faz grep, pega resultados ambíguos, abre quatro arquivos e lê três que não queria. Os arquivos eram curtos; a busca é que foi cara.CODEMAP.mdfecha a outra metade — uma linha por arquivo de código, agrupada por diretório. Lê o mapa, abre o arquivo certo.Decisões
Escopo: o projeto derivado, não o OS. Dentro deste repo o script sai 0 sem escrever nada, detectado pelo marcador
.aios-selfque oos-self-testjá usava. Reaproveitar o marcador mantém um conceito de "qual repo é este" em vez de dois que podem discordar.Gerado, nunca escrito à mão. A descrição sai do cabeçalho
Purpose:que acode-stylejá exigia. Se fosse escrita à mão no mapa, existiriam duas fontes de verdade sobre o que um arquivo faz, e elas divergiriam na primeira refatoração. Fallback: bloco de comentário → comentário de linha →⚠️ sem cabeçalho.Esse último caso é de propósito, e rendeu um efeito colateral bom: arquivo sem cabeçalho aparece marcado no mapa, então o codemap fiscaliza a regra de cabeçalho — que até então ninguém verificava.
Gate de CI, não checklist. Mapa desatualizado é pior que mapa nenhum: o agente confia, pula a leitura e age com informação velha. Três session-logs deste repo registram o
os-self-testnão sendo rodado exatamente quando teria ajudado, na época em que dependia de alguém lembrar. Repetir isso na camada seguinte, um release depois, seria difícil de justificar.O que entrou
scripts/codemap.js--checksai 1 na divergência.claude/rules/codemap.md.claude/skills/codemap/SKILL.mdtemplates/project/CODEMAP.template.mdscripts/test/codemap.test.jsFiação:
documentation-layers(regra + doc),release-check,sprint-management,ci.yml,os-self-test.js(9º grupo),WIZARD.md5.1,phase-5-chegada.md,templates/project/CLAUDE.md, README edocs/skill-system.md.Verificação
os-self-test: 70 verificações, COERENTEnode --test scripts/test/*.test.js: 92/92codemap.jsvalidado em projeto derivado simulado: gera,--checkpassa,--checkfalha ao divergir, skip dentro do repo do OSCorrigido no caminho
templates/project/CODEMAP.template.mdlinkava.claude/rules/codemap.md— correto na raiz do projeto derivado, errado detemplates/project/. Pego pelo próprioos-self-test. Virou caminho em texto, com a razão anotada no arquivo.sprint-management.🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
CODEMAP.mdto help locate project source files and understand their purpose.Bug Fixes
Tests