docs: grep-first rule for shared code + advisory duplication count - #3061
Conversation
Adds a REQUIRED "Before you add a type, schema, or helper" section to agent_docs/code_style.md: grep for the operation rather than the name you were about to give it, plus a map of the nine common-utils modules that carry ~90% of cross-package imports. common-utils has no root barrel, so grep is the only index. The escape-hatch ratchet now counts `@source packages/...` port markers, and agent_docs documents the marker for the first time. The count is advisory rather than gated: unlike `as any`, deleting an `@source` line removes the record of a copy, not the copy, so failing on an increase would only discourage annotating ports.
|
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
github-actions
Bot
added
the
review/tier-2
🔵 Tier 2 — Low RiskSmall, isolated change with no API route or data model modifications. Why this tier:
Review process: AI review + quick human skim (target: 5–15 min). Reviewer validates AI assessment and checks for domain-specific concerns. Stats
|
Greptile SummaryThe PR documents a grep-first policy for shared types, schemas, helpers, and components, and adds advisory tracking for whole-file
Confidence Score: 5/5The PR appears safe to merge with no actionable defects identified. Advisory counting is isolated from existing fatal ratchet checks, generated and baseline count shapes remain aligned, and the documentation marker examples are excluded from source-file counting.
|
| Filename | Overview |
|---|---|
| scripts/ci/ratchet.mjs | Adds @source as an advisory-only ratchet pattern while preserving fatal behavior for existing gated patterns. |
| scripts/ci/tests/ratchet.test.mjs | Adds focused coverage showing advisory increases remain nonfatal and cannot mask gated increases. |
| scripts/ci/ratchet-baseline.json | Adds aligned @source baseline entries for every tracked workspace package. |
| agent_docs/code_style.md | Introduces the required grep-first shared-code guidance and documents whole-file source markers. |
| packages/cli/AGENTS.md | Documents source tags for CLI files ported from the web frontend. |
Reviews (1): Last reviewed commit: "docs: grep-first rule for shared code, p..." | Re-trigger Greptile
![github-actions[bot]](https://avatars.github.com/in/15368?s=60&v=4){kind=small}
PR Review3 finding(s): 🔴 0 critical · 🟠 1 major · 🔵 2 minor 2 posted as inline comment(s) on the changed lines. 1 listed below. Findings outside the changed lines
Severity is the reviewer's own estimate and is used for ordering, not filtering. |
Deep ReviewScope is a docs + CI-script change: prose adds a "grep-first before adding shared code" rule, and 🟡 P2 — recommended
🔵 P3 nitpicks (3)
Reviewers (3): correctness, testing, maintainability. Testing gaps: The advisory comparison logic (warn-not-fail, and an advisory rise not masking a gated rise) is well covered with value assertions; the untested surface is the regex actually matching |
E2E Test Results✅ All tests passed • 335 passed • 1 skipped • 1412s
Tests ran across 4 shards in parallel. |
2 participants
Summary
Trying to cut down on duplicated code. Two parts:
Grep-first rule (
agent_docs/code_style.md) — before adding a type, schema, helper, or component, grep for the operation it performs, not the name you'd give it.common-utilshas no root barrel, so there's no index to read; the doc adds a map of the nine modules holding ~90% of cross-package imports.A check (
scripts/ci/ratchet.mjs) — the ratchet now counts@source packages/...markers on files ported wholesale intopackages/cli. 37 today. Advisory only: it warns, never fails. Gating it would just teach people to drop the marker, since deleting the comment removes the record of a copy, not the copy.No existing duplicates are removed here.
How to test on Vercel preview
N/A — non-UI change.
References