Repository navigation
[doc] split script API into README overview + docs/API.md (config section) - #15
Conversation
…tion) Restructure the script-facing docs into the two-layer standard: a one-screen README overview plus a full reference in docs/API.md. - docs/API.md: the complete per-builtin / per-object-method reference moved out of the README (signatures, params, returns, errors, examples), plus a new Configuration section documenting every base-generated accessor (get_<key>/set_<key>) as a table with env var, default, and description. No option is secret, so all eight expose both get_ and set_. - README.md: trimmed to title+badges, Overview, Installation, a short Quickstart, a compact "Starlark API at a glance" list, a Configuration pointer, and a prominent link to docs/API.md. - build.yml: re-pin the reusable workflow and turn on doc-coverage-file: docs/API.md + doc-coverage-config so doccov gates docs/API.md (every builtin and every config accessor) instead of the README. doccov -readme docs/API.md -config . passes (29/29 builtins, 16/16 accessors); gofmt/vet/build/test clean; no .go changes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Up to standards ✅🟢 Issues
|
There was a problem hiding this comment.
Pull Request Overview
The documentation restructure and CI updates align with the technical requirements. However, the PR is currently not up to standards due to four linting issues (duplicate headings) in docs/API.md that break HTML anchors. More importantly, the 'Host hardening' section contains functional contradictions: it claims certain parameters cannot be configured via script while simultaneously documenting public Starlark setters (e.g., set_max_rows, set_database) for those same parameters. These discrepancies should be resolved to prevent potential security confusion or bypasses.
Test suggestions
- Verify that all 29 builtins and 16 configuration accessors (get/set for 8 keys) are listed in docs/API.md
- Check that the CI workflow correctly points to docs/API.md for doc-coverage enforcement
- Ensure the 'Configuration' table in docs/API.md correctly maps environment variables and default values for all 8 module options
TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback
| host in Go, not from a script. | ||
|
|
||
| - **Bound result size — `max_rows`.** A query helper materializes every returned |
There was a problem hiding this comment.
🟡 MEDIUM RISK
There is a contradiction between the hardening instructions and the API table. The text claims max_rows cannot be configured from a script, yet set_max_rows is documented as a public setter. If this is intended for host hardening, ensure the setter is either disabled for untrusted scripts or that the documentation clarifies how host-side configuration overrides script-side attempts to change it.
| - `params` (list): Optional list of parameters | ||
| - **Returns:** Dictionary representing the first row, or `None`. | ||
|
|
||
| #### `close()` |
There was a problem hiding this comment.
⚪ LOW RISK
This heading content is identical to an earlier instance (likely line 102). Qualify the heading with its object context to ensure unique anchors and fix the linting error.
This might be a simple fix:
| #### `close()` | |
| #### `close()` (Prepared Statement) |
…onversion - table_info: notnull/pk return ints (1/0 and 1-based PK position), not bools; dflt_value is a string-or-None. The previous "(bool)" was inaccurate (the test asserts col["notnull"] != 1). - type-conversion tables: add the time<->timestamp mapping (startime.Time is handled in both starlarkToSQLiteValue and sqliteToStarlarkValue) — it was the only supported type missing from the reference. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…kdownlint Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
What
Restructure the script-facing documentation into the two-layer doc standard (decided 2026-06-15): a one-screen
README.mdoverview plus a complete reference indocs/API.md. Content reorganization only — no API invented, no code changed.Changes
docs/API.md(new) — the full per-builtin / per-object-method reference moved out of the README: signature, parameters, returns, errors, and examples for every script builtin and every connection / transaction / prepared-statement method. Adds a dedicated## Configurationsection documenting everybase-generated accessor as a table: option,get_<key>/set_<key>, env var (SQLITE_<KEY>), default, and description. None of the eight options is secret, so each exposes bothget_andset_(the table notes that a secret option would expose onlyset_).README.md— slimmed to title + badges, Overview, Installation, a short Quickstart (2 examples), a compact "Starlark API at a glance" one-line-per-builtin list, a one-line Configuration pointer, and a prominent link todocs/API.md. The long per-function detail now lives indocs/API.md..github/workflows/build.yml— re-pin the reusable workflow to the meta SHA carrying the opt-in config gate, and adddoc-coverage-file: docs/API.md+doc-coverage-config: trueso doccov now gatesdocs/API.mdfor every builtin and every config accessor.Verification
doccov -readme docs/API.md -config .→ 29/29 builtins, 16/16 config accessors documented, exit 0.gofmt -l .empty,go vet ./...clean,go build ./...ok,go test ./...passing.🤖 Generated with Claude Code