Repository navigation
Add repository hygiene, contributor docs, and honest package metadata - #189
Merged
Merged
Conversation
The first tranche of the packaging review: everything that does not change the shape of the published artifact, so the risky items can be done next with a safety net rather than alongside these. ## Metadata The description covered only lockfile scanning, which has been a fraction of what the package does for several releases — it now names the dependency inventory, the attack-surface map, the runtime guard and response hardening. Keywords gained the runtime-security terms someone would actually search (`runtime-security`, `rasp`, `virtual-patching`, `nodejs-security`, `application-security`, plus `waf`, `ssrf`, `secret-redaction`). `publishConfig` is explicit rather than relying on a registry default or an `--access` flag at the call site. A scoped package defaults to restricted, and a publish that quietly succeeds as private is indistinguishable from one that worked until somebody tries to install it. ## Line endings and editors `.gitattributes` pins LF. That matters more here than in most repositories: several committed artifacts are compared BYTE for byte across repositories — the vendored rule contract, the capability manifest, the canary map and rule — and CRLF slipping into one turns a cross-repository agreement check into a diff nobody can read. `*.lockb` is marked binary so nothing tries to normalise Bun's lockfile. `git add --renormalize .` produced no content change, which is the useful result: the tree was already LF-clean, so this is a guard against future drift rather than a mass rewrite hiding in a hygiene commit. `.editorconfig` matches it, and leaves trailing whitespace alone in Markdown: two trailing spaces are a hard line break, and trimming them silently rewrites shipped prose that agents read when auditing the package. `.node-version` records 24 — the version the release workflow builds with. `engines.node` stays `>=18`, which is the consumer contract and a different question. No `export-ignore` rules: `files` in `package.json` remains the single authoritative allowlist of what ships, and a second mechanism that can disagree with it is worse than none. ## Contributor-facing `CONTRIBUTING.md` is the human counterpart to `AGENTS.md` — setup, the loop, what to verify before opening a pull request, and the public-repository boundary in the short form, including that third-party confidential material is a separate obligation rather than a special case. It also tabulates the generated artifacts that must stay in step with their sources, because changing one without regenerating leaves two files disagreeing and the check that notices is not always the one that fails first. The bug-report form asks for the versions and reproduction that make a report actionable — Connect, Node, package manager, framework, OS — and requires confirming the report carries no credentials, customer data, third-party proprietary material or private implementation details. Blank issues are disabled so that prompt cannot be bypassed: this repository is public, and a pasted log with a token in it is not recoverable by deleting the issue. Nothing new ships: `npm pack --dry-run` still reports 39 files, 995 kB packed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Comprehensive repo hygiene and contributor docs additions enhance clarity and consistency. 🎯 Quality: 98% Elite · 📦 Size: Medium 📈 This month: Your 147th PR — above team average · Averaging Excellent |
Six corrections, all to prose that stated something untrue. `CONTRIBUTING.md` told contributors that how a fix was reasoned about belongs in the pull request. A pull request is public, and `AGENTS.md` places that material in the private engineering record. The section now says what it should: a comment and a public pull-request description state the current invariant and the externally observable reason it matters; investigation history is kept privately. Setup said `nvm use` reads `.node-version`. nvm looks for `.nvmrc`. The command is now `nvm use "$(cat .node-version)"`, with fnm and nodenv noted as reading the file directly, and one file stays the source of truth. Consumer support from Node 18 is called out as a separate contract. The loop ran the tests before the build. Several tests only run once `dist/` exists, so in that order they skip — which is indistinguishable from passing. Build first. The generated-artifact table pointed at a source file for the rule contract instead of naming `npm run rule-contract`, and the two check commands CI runs are now named. In the bug-report form, `npx @patchstack/connect --version` prints the help text, because no version flag exists; it asks for `npm ls @patchstack/connect --depth=0`. The reproduction example installed with `--save-dev`, while the runtime guard is imported in production and deployments prune dev dependencies — it matches the README's `--save`. Every command in the changed text was run: `nvm use "$(cat .node-version)"` resolves 24, `npm run rule-contract:check` and `npm run capabilities:check` exit 0, and `npm ls` prints the version from a consumer project. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
Author
|
/review |
mariojgt
approved these changes
Aug 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Repository hygiene, contributor documentation, and package metadata. No change to the shape of the published artifact.
Metadata
descriptionnames what the package does: dependency inventory, attack-surface mapping, the runtime guard, response hardening.keywordscovers the runtime-security terms a user would search —runtime-security,rasp,virtual-patching,nodejs-security,application-security,waf,ssrf,secret-redaction.publishConfigstatesaccess: publicand the registry explicitly. A scoped package is restricted by default, and a publish that succeeds as private is indistinguishable from one that worked until an install fails.Line endings and editors
.gitattributespins LF. Several artifacts in this repository are compared byte for byte by other systems — the vendored rule contract, the capability manifest, the canary map and rule — and a CRLF in one of them turns an agreement check into an unreadable diff.*.lockbis marked binary.git add --renormalize .reports no content change: the tree is already LF-clean, so this is a guard rather than a rewrite..editorconfigmatches, and leaves trailing whitespace alone in Markdown, where two trailing spaces are a hard line break in prose the package ships..node-versionrecords the Node version releases are built with.engines.noderemains the consumer contract, which is a separate question.filesinpackage.jsonstays the single allowlist of what ships. Noexport-ignorerules: a second mechanism that can disagree with it is worse than one.Contributor-facing
CONTRIBUTING.mdcovers setup, the build-then-test order, what to verify before opening a pull request, and the public-repository boundary — including that third-party confidential material is a separate obligation. It tabulates the generated artifacts that must stay in step with their sources, with the command that regenerates each.The bug-report form asks for the Connect, Node, package-manager, framework and OS versions, a reproduction, expected and actual behaviour, and sanitized logs, and requires confirming the report carries no credentials, customer data, third-party proprietary material or private implementation details. Blank issues are disabled so that confirmation cannot be bypassed.
Not included
CODEOWNERS, per review. If it is added later it needs a check against the/codeowners/errorsAPI alongside it: a rule GitHub cannot apply is accepted by the file and silently ignored, so it reads as review protection without being any.Verification
npm pack --dry-runreports 39 files and 995 kB, unchanged. Every command the changed documentation names was run:nvm use "$(cat .node-version)",npm run rule-contract:check,npm run capabilities:check, andnpm ls @patchstack/connect --depth=0from a consumer project.🤖 Generated with Claude Code