@salesforce/storefront-next-dev 1.4.0 → 1.4.1-alpha.0

package/dist/audit/catalog/categories/seo/rules/locale-alternates.md

@@ -0,0 +1,19 @@
+---
+id: seo/locale-alternates
+title: Language and Region Links (hreflang)
+severity: medium
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.main-document, source.code]
+---
+## Intent
+For sites with more than one locale, checks that each page links to its other-language versions with `hreflang` tags and that those versions link back. Search engines use these links to show shoppers the page in their language. Single-locale sites don't need them.
+## Inspect
+Determine locale scope, then verify reciprocal delivered hreflang URLs.
+## Evaluate
+Use not-applicable for single-locale sites; finding requires broken multi-locale output.
+## Evidence
+Cite locale config and delivered alternate pairs.
+## Remediation
+Emit reciprocal valid locale alternates.
+## Examples
+Compliant: reciprocal en/fr URLs. Problematic: hreflang points to 404. Ambiguous: locale scope unknown.

package/dist/audit/catalog/categories/seo/rules/meta-description.md

@@ -0,0 +1,19 @@
+---
+id: seo/meta-description
+title: Meta Description
+severity: medium
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.main-document, source.code]
+---
+## Intent
+Checks that each page has a `<meta name="description">` that is specific to that page, not missing or copied across pages. Search engines often show it as the text under the result.
+## Inspect
+Compare delivered descriptions across captured pages and source generation.
+## Evaluate
+Finding requires missing, duplicate, or unsuitable delivered content.
+## Evidence
+Cite page, delivered value, and source.
+## Remediation
+Generate concise page-specific descriptions.
+## Examples
+Compliant: PDP description reflects product. Problematic: absent description. Ambiguous: helper exists only.

package/dist/audit/catalog/categories/seo/rules/page-title.md

@@ -0,0 +1,19 @@
+---
+id: seo/page-title
+title: Page Title
+severity: high
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.main-document, source.code]
+---
+## Intent
+Checks that each page has a `<title>` that is unique and describes that page. The title is the main text of a search result and the label of the browser tab.
+## Inspect
+Compare delivered titles across pages and trace route metadata.
+## Evaluate
+Finding requires missing, duplicate, or misleading delivered title.
+## Evidence
+Cite page, title value, comparison, and source.
+## Remediation
+Emit page-specific route metadata.
+## Examples
+Compliant: product-specific PDP title. Problematic: all pages share Home. Ambiguous: title helper only.

package/dist/audit/catalog/categories/seo/rules/robots-indexing.md

@@ -0,0 +1,20 @@
+---
+id: seo/robots-indexing
+title: Search Engines Can Index the Site
+severity: critical
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.main-document, source.code, deployment.config]
+---
+
+## Intent
+Checks the production site for anything that tells search engines not to index it: `noindex` in a robots meta tag or `X-Robots-Tag` header, `Disallow` rules in `robots.txt`, or environment settings that turn these on. A leftover staging setting can remove the whole store from search results; blocking a staging site is fine.
+## Inspect
+Inspect delivered robots metadata, robots.txt, response headers, and environment gating for noindex/disallow controls.
+## Evaluate
+Finding requires production-target evidence of unintended blocking; staging noindex can be not-applicable.
+## Evidence
+Cite deployed URL, directive/header/file, and environment evidence.
+## Remediation
+Remove or correctly environment-gate the blocking directive and verify the deployed response.
+## Examples
+Compliant: staging-only noindex. Problematic: production home emits noindex. Ambiguous: ungated-looking source without deployment context.

package/dist/audit/catalog/categories/seo/rules/structured-data.md

@@ -0,0 +1,19 @@
+---
+id: seo/structured-data
+title: Structured Data (JSON-LD)
+severity: medium
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.main-document, source.code]
+---
+## Intent
+Checks that any JSON-LD structured data on the pages, such as `Product` or `BreadcrumbList`, is valid, suits the page type and matches what the page shows, for example the same price and availability. Search engines use it for rich results. Pages without structured data pass.
+## Inspect
+Parse delivered JSON-LD and compare types/values with visible content and generation source.
+## Evaluate
+Use finding for invalid or materially misleading data; absence alone is a pass.
+## Evidence
+Cite page, JSON-LD path/value, validation issue, and source.
+## Remediation
+Emit valid schema.org data from trusted page data.
+## Examples
+Compliant: accurate Product data. Problematic: wrong availability. Ambiguous: no business requirement established.

package/dist/audit/instructions/evaluate-rule.md

@@ -0,0 +1,42 @@
+# Evaluating a site audit rule
+
+The contract for evaluating one AI-analyzed rule from a `sfnext audit prepare` run. `<run>` is the run folder holding `prepared.json`.
+
+For each rule id, find its entry in `<run>/prepared.json` `rules`, then read:
+
+- the rule `file` and its category's `CATEGORY.md` (`../CATEGORY.md` from the rule file), and follow the rule's `Intent`, `Inspect`, `Evaluate`, `Evidence` and `Remediation` sections;
+- the entry's `data` file, if it has one (compact script output; start there);
+- only the evidence the rule's `inputs` point to, using the table below. `pages` in `prepared.json` maps each page label to its URL and Playhouse `archiveDir` (relative to the run folder).
+
+Don't read other rules, other `results/` files, earlier audit workspaces or the audit tool's source. The audited project is read-only.
+
+| input | where to look |
+|---|---|
+| `playhouse.main-document` | `curl -sL <page url>` (the archive keeps document metadata, not the HTML); cite what you saw as `manual` evidence |
+| `playhouse.document` | `<archiveDir>/runs/mobile-cold-1/document.json` (status and response headers; any `runs/<cell>-<n>/` works) |
+| `playhouse.network-har` | `<archiveDir>/network-mobile-cold.har` (standard HAR, a few MB; use `jq`). Rules that name a `harArtifact` in their data use that run's `runs/<run id>/network.har`, whose query values are redacted; cite the artifact the data names. |
+| `playhouse.summary`, `playhouse.summary-*` | `<archiveDir>/summary*.json` |
+| `playhouse.opportunities` | `<archiveDir>/opportunities.json` |
+| `playhouse.diagnostics` | `<archiveDir>/diagnostics-mobile-cold.json` |
+| `playhouse.scripts` | `<archiveDir>/scripts/index.json` lists every script each run loaded; inline scripts have the page URL as `url`, and their text is `<archiveDir>/scripts/<body.sha256>.js` |
+| `playhouse.lighthouse` | `<archiveDir>/runs/mobile-cold-1/lhr.json` (the full Lighthouse result; use `jq` on `.audits["<audit id>"]`) |
+| `source.*`, `project.config`, `deployment.config` | the project repo (`grep`, read files) |
+| `manual.*`, `dependency.advisories` | not collected by the audit; decide from the rule's other inputs, or use `not-verified` when nothing else can settle it |
+
+Write one file per rule at the entry's `output` path:
+
+```json
+{ "ruleId": "seo/meta-description", "disposition": "finding", "severity": "low",
+  "summary": "The PDP has no meta description.", "remediation": "Render a product-specific description in the PDP route meta.",
+  "evidence": [{ "type": "source", "file": "src/routes/_app.product.$id.tsx", "line": 42 }] }
+```
+
+- `disposition`: reach a conclusion. Use `finding` when you can point to a concrete problem; when you are unsure how much it matters, lower the severity rather than holding back the finding. Use `pass` when you checked what the rule asks and it is met, and cite what you checked: a pass needs evidence just like a finding. Use `not-applicable` when the rule doesn't apply to this project (e.g. locale alternates on a single-locale site). Use `not-verified` only when the evidence the rule needs can't be collected at all (e.g. a real checkout); its `summary` must say what would verify it. Not-verified rules are listed for manual review and don't affect the launch guidance. A rule without a file is reported as `not-verified`.
+- Give every `finding` a `severity` (`critical`, `high`, `medium`, `low` or `info`), normally the rule's frontmatter `severity`. That severity is a ceiling: you may lower it when the impact is smaller, but a higher or missing value is reported at the rule's severity. `remediation` is optional.
+- Evidence types, one example each:
+  - `{ "type": "source", "file": "src/root.tsx", "line": 12, "excerpt": "…" }`, where `file` is project-relative;
+  - `{ "type": "playhouse", "page": "home", "artifact": "network-mobile-cold.har", "pointer": "/log/entries/3/response/headers", "value": "…" }`, where `artifact` is a path relative to that page's `archiveDir` (`diagnostics-mobile-cold.json`, not `playhouse/runs/…/diagnostics-mobile-cold.json`; never `main-document`) and `pointer` is an optional JSON pointer;
+  - `{ "type": "manual", "description": "Checkout was not exercised.", "location": "pdp" }`, also used for a `curl` result: `{ "type": "manual", "description": "curl -sL https://example.com/: <link rel=\"canonical\" href=\"https://example.com/\"/>", "location": "home" }`.
+- Cite each fact once per page, from the mobile cold-cache artifact when the rule doesn't name one; don't repeat it for every form factor and cache state. Make a Playhouse `value` readable on its own (e.g. `max-age=15552000; includeSubDomains`); the dashboard shows the page, the artifact and that value, not the pointer.
+- Some rules ask for an extra output field in their `Evidence` section (for example `waterfall` or `recommendations`); include it exactly as described there.
+- Never include secrets, cookies, authorization headers or response bodies.