Conventions config: single canonical surface + new /docs/no-build page#12
Merged
Conversation
…rt pkg.webjs.conventions
loadOverrides now reads exactly one place: package.json
"webjs": { "conventions": { … } }. Returns {} when the key is
absent (every default rule active). Removes the old top-level
"conventions" fallback, the webjs.conventions.js file path, and
the deprecation-warning machinery, leaving a 15-line loader.
Exports loadConventionOverrides() so the CLI can inspect a
project's overrides without running the full check pipeline.
Tests cover the canonical path plus negative coverage that legacy
shapes are now ignored, so a future reintroduction would fail
loudly.
Reads the project's overrides via loadConventionOverrides(), then annotates each rule line as [enabled] or [disabled by override]. Header text states the default-on invariant explicitly so AI agents reading the output cannot misinterpret it. Makes the CLI the canonical way to discover the active rule set for any webjs project. Docs no longer maintain a hand-typed rule list.
…ules CONVENTIONS.md owns architectural prose. The lint config lives in package.json webjs.conventions. The RULES catalogue lives in check.js and is surfaced via webjs check --rules. Each surface has one job and other places defer. Removes the inline rule list that was drifting from the code. Adds explicit "no override = all defaults active" invariant and a workflow for AI agents to discover active rules at runtime rather than from prose.
…g surface Scaffolded apps now ship a CONVENTIONS.md that describes the two-surface model: this markdown for architectural conventions, package.json webjs.conventions for lint rule overrides. The rule list is no longer duplicated here; readers are pointed at webjs check --rules. Same payoff as the framework-side AGENTS.md change: AI agents working in a scaffolded app discover the active rule set from the canonical CLI command instead of stale prose.
Public docs page no longer carries a hand-typed rule list (which had drifted, missing 4 of 10 rules). Now points readers at webjs check --rules for the canonical catalogue with descriptions and current enabled state, and at the package.json webjs.conventions block for overrides. JSON example uses the canonical nested shape.
New page is the single source of truth for how no-build works: per-file ESM, importmap, module graph + modulepreload hints, TS stripping with the rare esbuild fallback, vendor auto-bundling with the architecture-decision rationale (no importmap-rails DX tax), 103 Early Hints, granular cache invalidation, HTTP/2 at the edge, dev vs prod, honest tradeoffs. Sidebar entry sits in Getting Started between Architecture and Configuration so newcomers find it before reading deployment.
deployment: keeps the deployment-specific guidance (PaaS edges, nginx/Caddy/Traefik, Docker layer caching, 103 forwarding) but removes the duplicated mechanic explanation (importmap, module graph, vendor bundling). Cross-links to /docs/no-build for the mechanism story. ai-first: "transforms TypeScript via esbuild on import" was out of date. The primary stripper is Node 24+'s built-in module.stripTypeScriptTypes; esbuild is only a fallback for non-erasable syntax in third-party deps. Now accurate plus cross-links to /docs/no-build.
Adds a short package.json (lint rule overrides) section between tsconfig.json and Environment Variables. Discoverable for readers scanning Configuration for "what knobs can I turn", without duplicating the rule list or workflow (which live in /docs/conventions and webjs check --rules respectively).
vivek7405
added a commit
that referenced
this pull request
May 21, 2026
Conventions config: single canonical surface + new /docs/no-build page
vivek7405
added a commit
that referenced
this pull request
May 21, 2026
PostToolUse hook on Edit/Write/MultiEdit/NotebookEdit that counts working-tree changes after each tool call. When the count crosses a threshold (default 4, override via WEBJS_COMMIT_NUDGE_THRESHOLD), injects a reminder into the model's context via hookSpecificOutput. Soft nudge by design. Does not block edits. Skipped on main/master (guard-branch-context.sh handles that case) and outside a git work tree. Threshold of 4 catches the common batching failure mode without firing for trivial work. Motivation: I just shipped PR #12 with too many changes in too few commits. The text guidance in AGENTS.md is easy to ignore. A hook is harder.
vivek7405
added a commit
that referenced
this pull request
May 21, 2026
Replaces the soft 'commit and push freely' wording with explicit directives: commit per logical unit, do not pile changes, push after each commit, and respect the nudge-uncommitted hook reminder at threshold 4. Reframes 'meaningful commit messages' to say the body explains the reason rather than the diff. Driven by the failure mode in PR #12, where 8 logical units collapsed into 1 batched diff before being split at the end.
vivek7405
added a commit
that referenced
this pull request
May 21, 2026
For agents without a programmatic hooks API (Windsurf, Copilot) and as a baseline source of truth for all agents: * .cursorrules: Cursor's rule file * .windsurfrules: Windsurf's rule file * .github/copilot-instructions.md: GitHub Copilot's rule file * .github/pull_request_template.md: PR template * .editorconfig: editor settings (indent, line endings) All copied verbatim from packages/cli/templates/, including the strengthened commit-frequency wording and hook references from PRs #12 and #13.
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
1 participant
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.
Summary
Two themes in this PR, split into 8 small commits so each is independently reviewable.
1. Conventions config: collapse to one canonical surface
pkg.webjs.conventionsis now the only supported way to disable lint rules. Legacy fallbacks (top-levelpkg.conventions,webjs.conventions.jsfile) are gone, with negative-coverage tests that confirm they're ignored.webjs check --rulesis the canonical way to enumerate rules. It now reads the project's overrides and annotates each rule as[enabled]or[disabled by override], with header text stating the default-on invariant explicitly.AGENTS.md,templates/CONVENTIONS.md,/docs/conventions,/docs/configuration) now defer towebjs check --rulesinstead of duplicating the rule list. The docs site list had drifted (missing 4 of 10 rules); now there is one place where rules are described, and it is theRULESarray incheck.js.2. New
/docs/no-buildcanonical mechanism page/docs/deployment(deployment-specific bits stay; mechanism story is gone, replaced with a cross-link)./docs/ai-first(was: "transforms TypeScript via esbuild on import"; now: Node 24+module.stripTypeScriptTypes, with esbuild as a rare fallback).Test plan
npm testpasses (896/896, including 3 new tests for the override surface).webjs check --rulesoutput verified manually in a temp project with one override.http://localhost:4000(smoke-tested all touched pages).webjs checkcount (4 false positives in docs prose unchanged frommain).