codesentry 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Reis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# CodeSentry
+
+CLI de verificação de vulnerabilidades e qualidade de código. O scanner
+combina regras próprias para JavaScript/TypeScript e o ruleset OWASP do
+Semgrep CE para as linguagens suportadas por ele.
+
+## O que o CodeSentry faz
+
+Rodando `codesentry scan` num projeto, dois motores de análise trabalham
+juntos e o resultado sai unificado em um único relatório:
+
+- **Motor nativo** — regras próprias em TypeScript, sem dependências
+  externas, cobrindo JS/TS/JSX/TSX: segredos hardcoded, SQL injection,
+  XSS, command injection, JWT mal configurado, CORS permissivo, hash/
+  cifra fracos, promises sem tratamento de erro, complexidade excessiva
+  (funções longas, aninhamento profundo, muitos `if`/`for`/`try`), entre
+  outras. A lista completa e sempre atualizada está em `codesentry rules`.
+- **Semgrep CE embutido** — roda o ruleset `p/owasp-top-ten` sobre todas
+  as linguagens que o Semgrep suporta (não só JS/TS), cobrindo os riscos
+  do OWASP Top 10 de forma mais ampla que regras hand-rolled sozinhas
+  conseguiriam.
+
+Cada achado no relatório mostra o arquivo, a linha, a severidade e qual
+motor encontrou o problema (prefixo `semgrep/` para achados do Semgrep).
+Saídas disponíveis: tabela no console, JSON (`--json`) e, quando há mais
+de 20 problemas, um relatório Markdown detalhado é gerado automaticamente.
+
+## Como funciona por baixo dos panos
+
+O ponto central do design é **zero fricção de instalação**: o usuário final
+roda `npm install -g codesentry` e não precisa instalar Python, Docker,
+Semgrep, nem criar conta em lugar nenhum.
+
+Isso é possível porque o Semgrep CE e um Python portátil vêm empacotados
+como **dependências opcionais** específicas da plataforma
+(`codesentry-semgrep-linux-x64` / `-win32-x64`), resolvidas
+automaticamente pelo npm na instalação. O ruleset OWASP também é
+distribuído como pacote próprio (`codesentry-semgrep-rules`), como um
+snapshot local fixado por versão — o scan nunca consulta a Semgrep
+Registry nem envia métricas, e funciona 100% offline depois de instalado.
+O racional completo está na [ADR 0004](docs/adr/0004-bundled-semgrep-runtime.md).
+
+## Instalação
+
+Em uma release publicada, basta uma instalação:
+
+```bash
+npm install -g codesentry
+```
+
+O pacote compatível de Semgrep CE e Python portátil é instalado como
+dependência opcional automaticamente. Não é necessário instalar Python,
+Docker, Semgrep, criar conta ou autenticar em um site.
+
+As plataformas inicialmente suportadas são Linux x64 e Windows x64. Os
+pacotes têm tamanho de dezenas de MB porque incluem o runtime; essa é a troca
+para o scan funcionar offline após a instalação. Durante o desenvolvimento,
+use `npm link`:
+
+```bash
+git clone git@github.com:Ivan-ReisDev/code-sentry.git
+cd code-sentry
+npm install
+npm run build
+npm link
+```
+
+Depois disso, o comando `codesentry` fica disponível em qualquer
+diretório do seu terminal.
+
+## Uso
+
+### `codesentry scan [path]`
+
+Analisa um diretório (padrão: diretório atual) em busca de
+vulnerabilidades e problemas de qualidade.
+
+```bash
+codesentry scan .
+codesentry scan ./src
+codesentry scan . --json
+codesentry scan . --concurrency 4
+codesentry scan . --config ./rules/security.yml
+```
+
+O Semgrep CE embutido é executado automaticamente depois das regras nativas,
+usando um snapshot local do ruleset OWASP e `--metrics=off`. O comando não
+consulta a Semgrep Registry, não envia métricas e não requer internet após a
+instalação.
+
+`--concurrency <n>` limita o processamento paralelo do scanner nativo; use
+apenas inteiros positivos. Sem valor, o limite é ajustado para a máquina
+(`min(8, availableParallelism())`). Não há `--config` remoto: atualizações de
+Semgrep e das regras OWASP chegam em novas releases do CodeSentry. Quando
+necessário, `--config` aceita exclusivamente um arquivo YAML local.
+
+Em macOS, ARM e plataformas sem runtime publicado, o comando interrompe
+explicitamente em vez de declarar uma análise parcial como completa.
+
+### `codesentry rules`
+
+Lista as regras de análise disponíveis.
+
+```bash
+codesentry rules
+```
+
+### `codesentry long-functions [path]`
+
+Analisa um diretório (padrão: diretório atual) em busca apenas de
+funções com mais de 30 linhas (severidade `low`). Essa mesma regra
+também roda automaticamente como parte do `codesentry scan`.
+
+```bash
+codesentry long-functions .
+codesentry long-functions ./src --json
+```
+
+### `codesentry help`
+
+Lista os comandos disponíveis.
+
+```bash
+codesentry help
+```
+
+### `codesentry init`
+
+Assistente interativo para configurar o CodeSentry no projeto atual.
+
+```bash
+codesentry init
+```
+
+> A persistência da configuração em arquivo ainda não está implementada
+> (ver `src/config/config.ts`).
+
+## Desenvolvimento
+
+```bash
+npm install       # instala as dependências
+npm run dev        # roda a CLI direto do TypeScript (via tsx)
+npm run build      # gera o build de produção em dist/
+npm run typecheck  # checagem de tipos (tsc --noEmit)
+npm test           # roda a suíte de testes uma vez
+npm run test:watch # roda os testes em modo watch
+```
+
+Este projeto segue **TDD obrigatório**: toda nova regra, comando ou
+comportamento do scanner/reporter deve começar por um teste que falha,
+em `tests/`, antes de qualquer implementação.
+
+Para entender a estrutura de pastas e o fluxo de dados
+(`command → scanner → rules → reporter`), veja
+[docs/architecture.md](docs/architecture.md). Para o racional por trás
+das bibliotecas usadas na CLI, veja
+[docs/adr/0001-cli-libs.md](docs/adr/0001-cli-libs.md).
+
+## Licença
+
+[MIT](LICENSE)