[no-issue] docs: complete usage & configuration guide per product (EN+PT)#16
Conversation
Add a "Complete usage and configuration" section to each scanner page (python, javascript, robot, skill) and its PT sibling: install channels, invocation, every output format (text/json/sarif/junit, +robot), configuration (disable/enable, inline suppression, project config file, --config-audit with the real PL codes, --baseline, --diagnostics, precedence), exit codes, and CI (GitHub Actions + SARIF upload + pre-commit). For the skill: the full analyze + fix flag tables, provider config (anthropic/openai/gemini/openai-compatible with base-url + env keys, incl reasoning-model endpoints Nvidia/Fireworks/Groq), and per-host enable steps. EN/PT lockstep, explicit heading anchors. Co-authored-by: homesellerq-coder <294912019+homesellerq-coder@users.noreply.github.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4aeb98cf31
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ```bash | ||
| npx falsegreen-skill analyze tests/test_orders.py # single file | ||
| npx falsegreen-skill analyze tests/test_orders.py tests/test_pay.py # multiple (separate calls) | ||
| npx falsegreen-skill analyze tests/ --json --fail-on-high # CI gate: exits 2 on a HIGH finding |
There was a problem hiding this comment.
The falsegreen-skill CLI help/implementation takes analyze <file...> and reads each argument directly as a file; it does not expand directories. In this CI-gate example, passing tests/ will fail on the directory instead of scanning the suite, so users copying the documented command cannot run the gate. Use explicit files/globs expanded before invoking the CLI, or document directory support only after the CLI implements traversal.
Useful? React with 👍 / 👎.
| `# falsegreen: ignore` (no brackets) silences every code on that line; `ignore[C16,C20]` silences | ||
| only the listed codes. Only the exact `falsegreen:` token suppresses; a plain `# ignore` does not. | ||
|
|
||
| **Diagnostics group (default off).** The maintainability codes (`D2`, `M2`) are not false-green, |
There was a problem hiding this comment.
rffalsegreen's project config only honors disable, diagnostics, long_test, and verify_keywords, and the CLI exposes --diagnostics; there is no per-code severity key for Robot. Users following this sentence will add a severity setting that is ignored with an unknown-key warning, leaving D2/M2 disabled instead of enabling the intended diagnostics.
Useful? React with 👍 / 👎.
| **Pre-commit hook.** Add to `.pre-commit-config.yaml`: | ||
|
|
||
| ```yaml | ||
| - repo: https://github.com/vinicq/falsegreen |
There was a problem hiding this comment.
pre-commit expects .pre-commit-config.yaml to contain a top-level repos: list; this snippet starts directly with an indented - repo, so a user following “Add to .pre-commit-config.yaml” in a new project gets invalid YAML/a config that won't validate. Add the surrounding repos: key (same issue in the JS and Robot snippets) or explicitly say this block belongs under an existing repos: list.
Useful? React with 👍 / 👎.
| falsegreen --write-baseline tests/ # write .falsegreen-baseline.json, exit 0 | ||
| falsegreen --baseline tests/ # suppress recorded findings, fail on new ones |
There was a problem hiding this comment.
With the current argparse definition, --baseline and --write-baseline take an optional value, so in these examples tests/ is consumed as the baseline file path rather than a scan target. falsegreen --write-baseline tests/ tries to write the JSON baseline to the tests/ directory, and falsegreen --baseline tests/ loads from that directory while scanning the cwd, so users copying the ratchet commands fail or gate the wrong scope; put tests/ before the flag or use an explicit baseline path.
Useful? React with 👍 / 👎.
| `pre-commit autoupdate` rewrites the `rev`. Bypass once with `git commit --no-verify`, or set | ||
| `FALSEGREEN_BLOCK=0` to make the hook warn-only. To run on push instead of commit, set |
There was a problem hiding this comment.
This paragraph is still describing the pre-commit framework hook, whose manifest runs falsegreen --staged directly; the scanner exits 20 for HIGH findings and never reads FALSEGREEN_BLOCK. In that setup, setting FALSEGREEN_BLOCK=0 will not make the hook warn-only (only the raw hook_install wrapper below implements that env var), so users will still have blocked commits despite following the docs.
Useful? React with 👍 / 👎.
| **Project config file.** `[tool.falsegreen]` in `pyproject.toml`, or a flat `.falsegreen.toml` | ||
| at the repo root (`.falsegreen.toml` wins if both exist). Point at a specific file with | ||
| `--config PATH`. |
There was a problem hiding this comment.
In the advertised Python 3.8+ no-dependency install, Python 3.8-3.10 do not have tomllib, and the package does not depend on tomli; the scanner silently falls back to an empty config when no TOML reader is available. Users on those supported versions who add this pyproject.toml/.falsegreen.toml config will have disables, excludes, and severity overrides ignored unless they also install tomli, so the docs should call out that requirement or narrow the config support.
Useful? React with 👍 / 👎.
| falsegreen tests/ --output .falsegreen/ # write report.<ext> into a directory | ||
| ``` | ||
|
|
||
| - **`json`** carries the full envelope: tool, version, judgments, and the findings list. |
There was a problem hiding this comment.
The Python scanner's render_json currently returns a bare list of finding dicts, not an object with tool, version, or judgments. Any CI/parser written from this new reference will look for envelope fields that never exist and fail to consume the report; describe the actual list shape or change the scanner before documenting the envelope.
Useful? React with 👍 / 👎.
1 participant
Each scanner page (python/javascript/robot/skill, EN+PT) gets a complete usage+config section: install channels, every output format, configuration (disable/suppress/config-file/config-audit/baseline/diagnostics), exit codes, CI (Actions+SARIF+pre-commit); skill gets full analyze+fix flags, provider config incl openai-compatible (Nvidia/Fireworks/Groq), and per-host enable steps. mkdocs --strict passes.