Skip to content

Enforce WebJs brand casing with one simple prose-only hook rule #858

Description

@vivek7405

Problem

The brand WebJs is a proper noun and should read capitalized wherever it names the project in prose (sentence start AND mid-sentence), staying lowercase webjs only as a literal code token. PR #851 added enforcement for the sentence-start position only. A follow-up attempt used a hardcoded ~60-word English verb allowlist to catch mid-sentence uses, which is brittle by construction (an open word class is never complete and is unmaintainable).

This issue tracks replacing both with one simple, blunt rule, plus a one-time corpus fix, following the em-dash pattern the repo already uses (purge existing violations, then block new ones).

Design / approach

One unified inverted rule. A standalone lowercase webjs in prose IS the brand and is flagged, with only two structurally-detectable exclusions (no open-ended word list):

  1. Literal code. Fenced and inline code spans are stripped, and the token forms (@webjsdev, webjs.dev, "webjs", WEBJS_*, webjsdev/webjs, <webjs-suspense>, bare identifiers like const webjs =) are excluded for free by the word boundary and the follower rule.
  2. The CLI command surface. webjs <subcommand> is the one finite, real, closed list that is subtracted, kept in sync with the CLI by a drift-guard test.

The follower is a following word or a sentence-ending period only, so the rule never false-blocks real code (biases to false negatives like the em-dash rule).

Implementation notes (for the implementing agent)

  • Enforcement: .claude/hooks/block-prose-punctuation.sh, rule 5 (the same hook that bans em-dashes as rule 1). Replaces the prior sentence-start block and the rejected verb allowlist. The webjs_cli variable holds the subcommand list.
  • Tests: test/hooks/block-prose-punctuation.test.mjs, including the drift-guard that asserts the hook list covers the case labels in packages/cli/bin/webjs.js.
  • Doc: AGENTS.md invariant item 11.
  • Landmine: the hook is repo-only. The scaffold copy at packages/cli/templates/.claude/hooks/block-prose-punctuation.sh and the examples/blog copy deliberately carry NO brand rule (a generated user app is not webjs-branded). Do not add it there.
  • Landmine: a one-time fix across docs must skip literal code. Markdown backtick masking can drift on backtick-dense lines and wrongly capitalize a backticked literal (this happened once with VS Code command titles and was caught in review). Verify by parsing code spans, not just grepping.
  • Excluded from the one-time fix: changelog/ (auto-generated), scaffold templates, .sh hooks, CI.

Acceptance criteria

  • One unified brand rule in the hook, no verb/noun allowlist
  • Catches every mid-sentence brand use, not a fixed verb set
  • Never false-blocks real code (if (!webjs), const webjs = ..., CLI commands, token forms)
  • CLI drift-guard test against bin/webjs.js
  • One-time corpus fix across AGENTS/README/agent-docs/docs-site/website/package-comments
  • AGENTS.md invariant updated
  • Tests green (19/19)

Shipped in #855 (this issue is filed retroactively for board tracking; supersedes the sentence-start-only enforcement from #851).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

  • Status
    Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions