331: MSSQL: write extensions/mssql/README.md (setup, tools, risks) #355

Merged

david merged 3 commits from feature/issue-331/mssql-write-extensions-mssql-readme-md-setup-tools into main

2026-11-11 00:52:42 +00:00

david commented

2026-11-11 00:52:40 +00:00

Owner

331: MSSQL: write extensions/mssql/README.md (setup, tools, risks)

Implements 331.

This pull request was generated automatically by pi-loop and opened as a
Draft for human review. Do not merge without reviewing the changes.

Generated in 1m 12s.

Review findings

No matches in README; check the file.# Review Findings — 331

Summary

I fixed all four findings with edits to extensions/mssql/README.md. The Medium finding now covers the 4096-character SQL truncation and best-effort audit writes, with a [COMPLIANCE RISK] flag. The three Low findings are also done: the guard limits, the .gitignore wording and where startup output goes. I did not re-run the tests because only the README changed.

Critical

High

Medium

extensions/mssql/README.md:67 — The Audit log section says every executed and rejected query is logged. It omits two behaviours in audit.ts: SQL is capped at 4096 characters and marked …[truncated], and write failures are swallowed with only a stderr warning (audit.ts log() try/catch). For a compliance-relevant log, readers should know it is best-effort and may be incomplete. Suggested fix: add a sentence such as "SQL longer than 4096 characters is truncated in the log. If the log cannot be written, the extension prints a warning and the query still runs, so the log is not guaranteed complete." Raise a [COMPLIANCE RISK] flag if the log is relied on for audit evidence.

Low

extensions/mssql/README.md:44 — "What the guard does" does not mention the MAX_SQL_LENGTH limit (100,000 characters, guard.ts:15) or that a GO batch separator is rejected (guard.ts:37). Suggested fix: add both to the list of rejections.
extensions/mssql/README.md:71 — The .gitignore advice reads as if the user must act. This repository's .gitignore already ignores .pi/mssql-audit.log, and the README says the extension does not edit .gitignore. Suggested fix: say that this repository already ignores the log and that other projects using the extension should add .pi/ or that path.
extensions/mssql/README.md:20 — The startup output (host, port and database, plus warnings) goes to stdout via console.log, and errors go via console.error. The README does not say where it is printed, which matters for the "logging and monitoring" point. Suggested fix: state that startup messages go to the console, and that warnings are also written to the audit log only for permission findings.

Documentation

Updated files:

README.md

## 331: MSSQL: write extensions/mssql/README.md (setup, tools, risks) Implements [331](https://git.excelera.net/david/pi-extensions-and-skills/issues/331). > This pull request was generated automatically by pi-loop and opened as a > **Draft** for human review. Do not merge without reviewing the changes. Generated in 1m 12s. ## Review findings No matches in README; check the file.# Review Findings — 331 ## Summary I fixed all four findings with edits to `extensions/mssql/README.md`. The Medium finding now covers the 4096-character SQL truncation and best-effort audit writes, with a [COMPLIANCE RISK] flag. The three Low findings are also done: the guard limits, the `.gitignore` wording and where startup output goes. I did not re-run the tests because only the README changed. ## Critical ## High ## Medium - [x] extensions/mssql/README.md:67 — The Audit log section says every executed and rejected query is logged. It omits two behaviours in `audit.ts`: SQL is capped at 4096 characters and marked `…[truncated]`, and write failures are swallowed with only a stderr warning (`audit.ts` `log()` try/catch). For a compliance-relevant log, readers should know it is best-effort and may be incomplete. Suggested fix: add a sentence such as "SQL longer than 4096 characters is truncated in the log. If the log cannot be written, the extension prints a warning and the query still runs, so the log is not guaranteed complete." Raise a **[COMPLIANCE RISK]** flag if the log is relied on for audit evidence. ## Low - [x] extensions/mssql/README.md:44 — "What the guard does" does not mention the `MAX_SQL_LENGTH` limit (100,000 characters, `guard.ts:15`) or that a `GO` batch separator is rejected (`guard.ts:37`). Suggested fix: add both to the list of rejections. - [x] extensions/mssql/README.md:71 — The `.gitignore` advice reads as if the user must act. This repository's `.gitignore` already ignores `.pi/mssql-audit.log`, and the README says the extension does not edit `.gitignore`. Suggested fix: say that this repository already ignores the log and that other projects using the extension should add `.pi/` or that path. - [x] extensions/mssql/README.md:20 — The startup output (host, port and database, plus warnings) goes to stdout via `console.log`, and errors go via `console.error`. The README does not say where it is printed, which matters for the "logging and monitoring" point. Suggested fix: state that startup messages go to the console, and that warnings are also written to the audit log only for permission findings. ## Documentation Updated files: - README.md

david added 3 commits

2026-11-11 00:52:41 +00:00