docs: align the public package surface to the Angular AI agent UI category, and gate it - #1001
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
blove
enabled auto-merge (squash)
September 4, 2026 21:55
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
Contributor
…nt UI category Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The unit gate read `apps/website/content/**` only, so every word a component renders and every line of the published package READMEs was invisible to it. Both gaps have already shipped violations: the homepage FAQ asserted "Installation is inert" and linked `/docs/telemetry/guides/browser`, and `libs/telemetry/README.md` carried three barred claims live on npm. `src/**` is scanned through the TypeScript parser rather than as bytes, so only string literals, static template chunks and JSX text are compared. Comments and regex literals — which is how this repository legitimately discusses the barred phrases — are skipped by construction, not by an ignore list, which keeps the exclusions down to the contract module and `*.spec.*`. The READMEs are prose and get the same plain line scan `content/**` gets. Fixtures reconstruct the shipped FAQ answer so the gate stays provably non-vacuous, and the spec states what it catches and what only the e2e crawl can. Adds ~1s to the suite. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…te comment
scripts/mit-cutover.spec.mjs bans that vocabulary anywhere under
apps/website/src, so a comment explaining that the two gates do not overlap
named the banned words and turned it red. That spec assembles its own list with
.join('') for exactly this reason; the comment now says so and points at the
list instead of repeating it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
blove
force-pushed
the
blove/public-surface-category
branch
from
September 4, 2026 23:00
17d9305 to
1bc37b3
Compare
Contributor
Contributor
Contributor
Contributor
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.
Two related changes: bring the README and npm pages into the category the homepage now leads with, and close the gate that let banned copy reach those surfaces in the first place.
The package surface said something different from the site
For many developers the npm page is first contact and the install surface, and it still carried the older positioning. The README, the seven published
libs/*/package.jsondescriptions and their READMEs now lead with the same category, install commands copied verbatim from the website'sINSTALL_OPTIONS, and a first success that starts withprovideFakeAgent().Three things were wrong rather than merely stale, and are fixed:
description, so the field was authored and silently dropped at publish. Confirmed by building and reading the emitted manifest.Every factual claim was verified against a manifest before it was written: license, Angular peer range, package names, peer lists. Claims that could not be sourced were deleted, including an absolute "never collects" that nothing keeps true.
The gate that should have caught this
libs/telemetry/README.mdwas tripping three patterns in the repo's own public-copy contract, including "Installation is inert". Those files are the npm package pages, so the phrases were live. Nothing looked at them: the unit scan read onlyapps/website/content/**, markdown is not linted, and the licensing check covers different vocabulary in two files.The scan now covers
apps/website/src/**and every README.Source files get a real TypeScript parse, not a byte scan. Only text that can reach a visitor is compared: string literals, static template chunks, JSX text. Identifiers, comments and regex literals are skipped by construction. That is forced by the tree rather than chosen for elegance — a byte scan goes red today on two components that deliberately name the retired claim in a comment so nobody reintroduces it. Flag those and someone adds a suppression within a month and the gate is dead. Parsing means the exclusion list is two rules and there is no allowlist at all.
READMEs get a plain line scan, the same treatment
content/**already gets, including fenced code.Proving it is not vacuous
The historical regression was reconstructed in the real component: the shipped FAQ answer with "Installation is inert" and a link to the retired route. Both assertions go red on the exact lines. The same was done in a README, where all three README patterns plus the retired route fire. Both reverted and verified byte-identical afterwards.
Because a gate like this decays by being narrowed, six fixture tests pin the historical answer and the extractor's behaviour, and three walk-level guards assert the scan is not looking at an empty tree: file counts, fragment counts by kind, and specific files that must be present. The spec states in its own comment what it catches and, at length, what it still cannot — substituted strings, copy from outside the tree, alt text,
package.jsondescriptions. The preview crawl remains the backstop.Zero violations on the current tree, and no copy was weakened to get there.
Verification
Website suite green, 1132 tests; 0 lint errors across website and the four published libs; the release and Angular-support scripts pass. The scan adds about 1 second to a 90 second suite, memoized to a single parse pass.
Not changed, for you to confirm
The GitHub repo description still reads "Angular SDK for Building Agentic Apps + Generative UI". Suggested:
The AI agent UI framework for Angular — chat, durable threads, human approvals, and generative UI for LangGraph and AG-UI.plus topicslanggraph,ag-ui,signals,generative-ui. Left alone as an outward-facing account setting.🤖 Generated with Claude Code