Skip to content

[doc] split script API into README overview + docs/API.md (config section) - #15

Merged
vt128 merged 3 commits into
masterfrom
docs/split-api
Jun 15, 2026
Merged

vt128 merged 3 commits into
masterfrom
docs/split-api

Conversation

@vt128

@vt128 vt128 commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

What

Restructure the script-facing documentation into the two-layer doc standard (decided 2026-06-15): a one-screen README.md overview plus a complete reference in docs/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 ## Configuration section documenting every base-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 both get_ and set_ (the table notes that a secret option would expose only set_).
  • 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 to docs/API.md. The long per-function detail now lives in docs/API.md.
  • .github/workflows/build.yml — re-pin the reusable workflow to the meta SHA carrying the opt-in config gate, and add doc-coverage-file: docs/API.md + doc-coverage-config: true so doccov now gates docs/API.md for 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.
  • Markdown clean on the linted rules (bare URLs, blank-line surrounds, fenced-language tags, no skipped heading levels); names/signatures verified against the source.

🤖 Generated with Claude Code

…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>
@codacy-production

codacy-production Bot commented Jun 15, 2026 •

Copy link
Copy Markdown

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

Run reviewer

TIP This summary will be updated as you push new changes.

@codacy-production codacy-production Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread docs/API.md
Comment on lines +1019 to +1021
host in Go, not from a script.

- **Bound result size — `max_rows`.** A query helper materializes every returned

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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.

Comment thread docs/API.md
- `params` (list): Optional list of parameters
- **Returns:** Dictionary representing the first row, or `None`.

#### `close()`

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ 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:

Suggested change
#### `close()`
#### `close()` (Prepared Statement)

vt128 and others added 2 commits June 15, 2026 23:16
…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>
@vt128 vt128 closed this Jun 15, 2026
@vt128 vt128 reopened this Jun 15, 2026
@vt128
vt128 merged commit eb37d18 into master Jun 15, 2026
16 checks passed
@vt128
vt128 deleted the docs/split-api branch June 15, 2026 15:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant