chore(tooling): fix #864, #865, #866, #867 contributor tooling and docs by AderonkeAfolabi · Pull Request #1250 · vjuliaife/TariffShield

AderonkeAfolabi · 2026-10-18T00:07:38Z

Closes #864, closes #865, closes #866, closes #867

This pull request resolves four contributor experience, developer tooling, and documentation gaps across the repository:

1. Issue #864: Local Lambda Invocation Harness for Backup Lambdas

Problem: scripts/backup-cleanup-lambda.ts and scripts/backup-compliance-report-lambda.ts were written as AWS Lambda handlers without a local invocation path. Contributors testing retention logic or compliance reporting either had to deploy to AWS or manually construct event/context stubs, and running locally triggered AWS credential authentication errors.
Solution: Introduced scripts/lib/invoke-lambda-local.ts, an in-process local runner that mocks @aws-sdk/client-rds, @aws-sdk/client-dynamodb, @aws-sdk/client-s3, and @aws-sdk/client-cloudtrail. It provides synthetic test data for snapshot policies, S3 objects, and DynamoDB audit records so contributors can perform dry-run smoke tests with zero AWS credentials. Documented invocation commands in both script headers and docs/OPERATIONS_RUNBOOK.md, and added automated regression tests in scripts/tests/invoke-lambda-local.test.ts.

2. Issue #865: VS Code Format-on-Save Configuration

Problem: Root .prettierrc and rustfmt.toml configurations existed, but no editor workspace settings enabled format-on-save. Code was only formatted at commit time via lint-staged, causing noisy diffs during active development.
Solution: Added .vscode/settings.json enabling editor.formatOnSave: true and configuring esbenp.prettier-vscode as the default formatter for TypeScript, JavaScript, JSON, YAML, and Markdown. Explicitly assigned [rust] to rust-lang.rust-analyzer to ensure Rust files defer to rustfmt.toml without Prettier conflicts. Added extension recommendations in .vscode/extensions.json and documented setup in docs/local-dev.md and CONTRIBUTING.md.

3. Issue #866: Reproducible Query Analysis & Benchmarking

Problem: docs/query-analysis.md documented EXPLAIN ANALYZE findings for hot-path PostgreSQL queries but did not explain how contributors could regenerate the query plans locally, what seed data volumes were assumed, or where the queries originated in apps/api/src.
Solution: Updated the query table with direct links to call sites in apps/api/src/routes/importers.ts for all 9 queries. Added a "Reproducing this analysis locally" section explaining why default seeds trigger Seq Scan on small tables, providing a self-contained SQL synthetic generator (generate_series) for realistic benchmark volumes ($\ge 1,000$ importers, $\ge 50,000$ events), and documenting parameterized EXPLAIN (ANALYZE, BUFFERS) commands. Cross-referenced from CONTRIBUTING.md's Testing section as an optional performance regression check.

4. Issue #867: Contributor Local Setup Support Channel

Problem: docs/runbooks/support-escalation.md covers production on-call escalation, but there was no documented channel for contributors stuck on local environment setup.
Solution: Added a "Stuck on local setup?" section to docs/local-dev.md pointing to GitHub Issues with the [dev-setup] title convention. Cross-linked the support channel at the top of docs/FAQ.md and in CONTRIBUTING.md, while keeping production incident escalation in docs/runbooks/support-escalation.md strictly separated.

Changed

scripts/backup-cleanup-lambda.ts has no documented local invocation path for contributors without AWS SAM/CDK tooling #864: Added scripts/lib/invoke-lambda-local.ts supporting programmatic and CLI invocations (--dry-run and --live) with in-process AWS SDK mocking.
scripts/backup-cleanup-lambda.ts has no documented local invocation path for contributors without AWS SAM/CDK tooling #864: Updated scripts/backup-cleanup-lambda.ts and scripts/backup-compliance-report-lambda.ts with invocation documentation and optional (event?, context?) handler parameters.
scripts/backup-cleanup-lambda.ts has no documented local invocation path for contributors without AWS SAM/CDK tooling #864: Added Section 8 ("Backup Lambda local invocation and maintenance") to docs/OPERATIONS_RUNBOOK.md.
scripts/backup-cleanup-lambda.ts has no documented local invocation path for contributors without AWS SAM/CDK tooling #864: Added scripts/__tests__/invoke-lambda-local.test.ts providing 7 automated regression subtests for Lambda local execution.
.prettierrc exists but VS Code editor setup instructions never mention enabling format-on-save #865: Added .vscode/settings.json configuring format-on-save for Prettier and delegating Rust formatting to rust-analyzer.
.prettierrc exists but VS Code editor setup instructions never mention enabling format-on-save #865: Added .vscode/extensions.json recommending Prettier, ESLint, and rust-analyzer extensions.
.prettierrc exists but VS Code editor setup instructions never mention enabling format-on-save #865: Updated .gitignore to track .vscode/settings.json and .vscode/extensions.json while ignoring personal workspace files.
.prettierrc exists but VS Code editor setup instructions never mention enabling format-on-save #865: Updated docs/local-dev.md and CONTRIBUTING.md with VS Code format-on-save instructions.
docs/query-analysis.md documents slow-query findings with no instructions for reproducing the analysis locally #866: Added source code links for queries 1–9 to docs/query-analysis.md pointing directly to apps/api/src/routes/importers.ts.
docs/query-analysis.md documents slow-query findings with no instructions for reproducing the analysis locally #866: Added "Reproducing this analysis locally" in docs/query-analysis.md with synthetic data generation (generate_series) and parameterized EXPLAIN (ANALYZE, BUFFERS) statements.
docs/query-analysis.md documents slow-query findings with no instructions for reproducing the analysis locally #866: Added query performance check cross-reference to CONTRIBUTING.md Testing section.
docs/runbooks/support-escalation.md gives production incident escalation paths but no equivalent guidance for contributors stuck on local setup #867: Added "Stuck on local setup?" section to docs/local-dev.md with guidelines on searching and filing GitHub Issues.
docs/runbooks/support-escalation.md gives production incident escalation paths but no equivalent guidance for contributors stuck on local setup #867: Added cross-reference banner to the top of docs/FAQ.md.
docs/runbooks/support-escalation.md gives production incident escalation paths but no equivalent guidance for contributors stuck on local setup #867: Maintained strict isolation of production escalation runbook (docs/runbooks/support-escalation.md unchanged).

Testing

The changes were verified using the following commands:

# 1. Run automated regression tests for local Lambda runner (#864)
npx tsx --test --test-force-exit scripts/__tests__/invoke-lambda-local.test.ts
# Result: 7 tests passed (0 failures) in 256ms

# 2. Verify CLI dry-run smoke test: backup cleanup (#864)
npx tsx scripts/lib/invoke-lambda-local.ts cleanup --dry-run
# Result: Deleted 2 expired snapshots, created 2 audit records, exited with code 0

# 3. Verify CLI dry-run smoke test: compliance report (#864)
npx tsx scripts/lib/invoke-lambda-local.ts compliance-report --dry-run
# Result: Generated compliance report, uploaded mock S3 object, exited with code 0

# 4. Verify code formatting against root .prettierrc (#865)
npx prettier --check .vscode/settings.json .vscode/extensions.json scripts/lib/invoke-lambda-local.ts scripts/__tests__/invoke-lambda-local.test.ts scripts/backup-cleanup-lambda.ts scripts/backup-compliance-report-lambda.ts docs/local-dev.md docs/FAQ.md docs/OPERATIONS_RUNBOOK.md docs/query-analysis.md CONTRIBUTING.md
# Result: All files formatted cleanly

Scope Notes

Tooling & Docs Only: No changes to production smart contracts (contracts/tariff-shield/) or API route business logic (apps/api/src/routes/).
No Dependencies Added: The Lambda runner uses native Node.js module interception without adding external packages to package.json.
Zero Production Runbook Disruption: docs/runbooks/support-escalation.md remains completely unmodified.

Push Command

git push -u origin fix/contributor-enhancements-864-865-866-867

…iaife#867 contributor tooling and docs

vercel · 2026-10-18T00:07:43Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
tariff-shield-web	Error		Oct 18, 2026 12:46am UTC

drips-wave · 2026-10-18T00:07:43Z

@AderonkeAfolabi Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

+import {
+  invokeLambdaLocal,
+  createMockLambdaContext,
+  createMockLambdaEvent,
+  getDefaultMockAwsData,
+} from '../lib/invoke-lambda-local';


+  DeleteDBSnapshotCommand,
+} from '@aws-sdk/client-rds';
+import { DynamoDBClient, PutItemCommand } from '@aws-sdk/client-dynamodb';
+import { CloudTrailClient, LookupEventsCommand } from '@aws-sdk/client-cloudtrail';


+
+const rds = new RDSClient({ region: process.env.AWS_REGION || 'us-east-1' });
+const dynamodb = new DynamoDBClient({ region: process.env.AWS_REGION || 'us-east-1' });
+const cloudtrail = new CloudTrailClient({ region: process.env.AWS_REGION || 'us-east-1' });


chore(tooling): fix vjuliaife#864, vjuliaife#865, vjuliaife#866, vjul…

1dcf7ad

…iaife#867 contributor tooling and docs

vercel Bot had a problem deploying to Preview October 18, 2026 00:07 Failure

github-advanced-security Bot found potential problems Oct 18, 2026

View reviewed changes

Merge branch 'main' into fix/contributor-enhancements-864-865-866-867

555fbf9

vercel Bot had a problem deploying to Preview October 18, 2026 00:46 Failure

vjuliaife merged commit 959ca85 into vjuliaife:main Oct 18, 2026
10 of 27 checks passed

Navigation Menu

Repository navigation

chore(tooling): fix #864, #865, #866, #867 contributor tooling and docs - #1250

chore(tooling): fix #864, #865, #866, #867 contributor tooling and docs#1250
vjuliaife merged 2 commits into
vjuliaife:mainfrom
AderonkeAfolabi:fix/contributor-enhancements-864-865-866-867

AderonkeAfolabi commented Oct 18, 2026

Uh oh!

vercel Bot commented Oct 18, 2026 •

edited

Loading

Uh oh!

drips-wave Bot commented Oct 18, 2026

Uh oh!

Uh oh!

This branch had an error being deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

AderonkeAfolabi commented Oct 18, 2026

1. Issue #864: Local Lambda Invocation Harness for Backup Lambdas

2. Issue #865: VS Code Format-on-Save Configuration

3. Issue #866: Reproducible Query Analysis & Benchmarking

4. Issue #867: Contributor Local Setup Support Channel

Changed

Testing

Scope Notes

Push Command

Uh oh!

vercel Bot commented Oct 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

drips-wave Bot commented Oct 18, 2026

Uh oh!

Uh oh!

This branch had an error being deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vercel Bot commented Oct 18, 2026 •

edited

Loading