docs(site): document new severity config

Author: JamieMason

site/astro.config.mjs

@@ -117,11 +117,13 @@ export default defineConfig({
             'config/max-concurrent-requests',
             'config/minimum-release-age',
             { label: 'semverGroups', link: '/semver-groups/' },
+            'config/severity',
             'config/sort-az',
             'config/sort-exports',
             'config/sort-first',
             'config/sort-packages',
             'config/source',
+            'config/source-mode',
             'config/strict',
             { label: 'updateGroups', link: '/update-groups/', badge: 'New' },
             { label: 'versionGroups', link: '/version-groups/' },

site/remark-plugins/link-aliases.mjs

@@ -21,6 +21,8 @@ export function linkAliases() {
     CONFIG_SORT_FIRST: '/config/sort-first/',
     CONFIG_SORT_PACKAGES: '/config/sort-packages/',
     CONFIG_SOURCE: '/config/source/',
+    CONFIG_SOURCE_MODE: '/config/source-mode/',
+    CONFIG_STRICT: '/config/strict/',
     CONFIG_SYNCPACKRC: '/config/syncpackrc/',
     CONFIG_UPDATE_GROUPS: '/update-groups/',
     CONFIG_VERSION_GROUPS: '/version-groups/',
@@ -29,8 +31,15 @@ export function linkAliases() {
 
     REF_DEPENDENCY_TYPES: '/dependency-types/',
     REF_GLOSSARY: '/glossary/',
+    REF_SEVERITY: '/config/severity/',
     REF_SPECIFIER_TYPES: '/specifier-types/',
+
     REF_STATUS_CODES: '/status/',
+    REF_STATUS_CODES_VALID: '/status/#valid',
+    REF_STATUS_CODES_FIXABLE: '/status/#fixable',
+    REF_STATUS_CODES_SUSPECT: '/status/#suspect',
+    REF_STATUS_CODES_UNFIXABLE: '/status/#unfixable',
+    REF_STATUS_CODES_CONFLICT: '/status/#conflict',
 
     TERM_CUSTOM_TYPE: '/glossary/#custom-type',
     TERM_DEPENDENCY: '/glossary/#dependency',
@@ -42,6 +51,7 @@ export function linkAliases() {
     TERM_SEMVER: '/glossary/#semver',
     TERM_SEMVER_GROUP: '/glossary/#semver-group',
     TERM_SEMVER_RANGE: '/glossary/#semver-range',
+    TERM_SEVERITY: '/glossary/#severity',
     TERM_SPECIFIER: '/glossary/#specifier',
     TERM_SPECIFIER_TYPE: '/glossary/#specifier-type',
     TERM_STATUS_CODE: '/glossary/#status-code',

site/src/_partials/how-packages-are-resolved.mdx

@@ -9,4 +9,4 @@ Syncpack will look in the following places for [glob](HREF_GLOB) patterns matchi
 
 ### Adding sources without replacing discovery
 
-By default, `--source` and `source` *replace* the discovered patterns. To keep workspace discovery and add extra patterns on top, set [`sourceMode`](CONFIG_SOURCE) to `"extend"` (or pass `--source-mode extend`). Discovered patterns come first; your patterns are appended last, so gitignore-style negations such as `!apps/legacy` can exclude discovered entries.
+By default, `--source` and `source` replace the discovered patterns. To keep workspace discovery and add extra patterns on top, set [`sourceMode`](CONFIG_SOURCE_MODE) to `"extend"` (or pass `--source-mode extend`). Discovered patterns come first; your patterns are appended last, so gitignore-style negations such as `!apps/legacy` can exclude discovered entries.

site/src/_partials/option/interactive.mdx

@@ -4,10 +4,10 @@ Pick which updates to apply through an interactive prompt instead of writing eve
 
 Keys:
 
-- `↑` `↓` — navigate
-- `space` — toggle the highlighted row
-- `a` — toggle all rows
-- `enter` — confirm and write selected updates
-- `esc` — cancel without writing
+- `↑` `↓`: navigate
+- `space`: toggle the highlighted row
+- `a`: toggle all rows
+- `enter`: confirm and write selected updates
+- `esc`: cancel without writing
 
 <Code code={`syncpack ${props.command} --interactive`} lang="bash" />

site/src/_partials/option/reporter-fix.mdx

@@ -1,6 +1,6 @@
 import { Code } from "astro:components";
 
-Set the output format. Defaults to `pretty` which prints human-readable output with colours and formatting. Use `json` to output one line of newline-delimited JSON (NDJSON) per fixable instance — the same shape as the [json](COMMAND_JSON) command.
+Set the output format. Defaults to `pretty` which prints human-readable output with colours and formatting. Use `json` to output one line of newline-delimited JSON (NDJSON) per fixable instance, with the same shape as the [json](COMMAND_JSON) command.
 
 Each line has the type [`JsonOutput`](https://github.com/JamieMason/syncpack/blob/14.1.0/npm/syncpack.ts#L174-L194):
 

site/src/_partials/option/source-mode.mdx

@@ -0,0 +1,11 @@
+import { Code } from "astro:components";
+
+Control how `--source` (and the rcfile [`source`](CONFIG_SOURCE)) combine with workspace discovery. `replace` (default) uses only the supplied patterns and skips discovery; `extend` appends them after discovered patterns from `workspaces` / `pnpm-workspace.yaml` / `lerna.json`. Overrides [`sourceMode`](CONFIG_SOURCE_MODE) from the rcfile.
+
+<Code
+code={`# Replace discovered patterns with the supplied ones (default)
+syncpack ${props.command} --source-mode replace --source 'packages/*/package.json'
+# Append the supplied pattern to discovered workspace packages
+syncpack ${props.command} --source-mode extend --source 'tools/scripts/package.json'`}
+lang="bash"
+/>

site/src/_partials/option/target.mdx

@@ -1,6 +1,6 @@
 import { Code } from "astro:components";
 
-Limit updates to only those within the given semver portion. For per-dependency control, see [updateGroups](CONFIG_UPDATE_GROUPS) — when both apply to the same instance, the stricter of the two wins.
+Limit updates to only those within the given semver portion. For per-dependency control, see [updateGroups](CONFIG_UPDATE_GROUPS). When both apply to the same instance, the stricter of the two wins.
 
 <Code
 code={`

site/src/_partials/severity/group-section.mdx

@@ -0,0 +1,17 @@
+import { KEYS } from "@partials/severity/keys.js";
+
+Override the default [severity](REF_SEVERITY) of any [status code](#status-codes) this group can produce.
+
+{props.children}
+
+**Permitted keys:**
+
+<ul>
+  {KEYS[props.group].map((k) => (
+    <li>
+      <a href={`/status/${k.slug}/#severity`}>
+        <code>{k.name}</code>
+      </a>
+    </li>
+  ))}
+</ul>

site/src/_partials/severity/keys.js

@@ -0,0 +1,86 @@
+// Single source of truth for which severity keys each version group accepts.
+// Used by:
+//   - site/src/_partials/severity/group-section.mdx (per-group page rendering)
+//   - site/src/content/docs/config/severity.mdx ('Configurable keys per group' table)
+// When the Rust validation in src/version_group/severity.rs changes, update this map.
+
+export const KEYS = {
+  banned: [{ name: 'IsBanned', slug: 'is-banned' }],
+  pinned: [
+    { name: 'DiffersToPin', slug: 'differs-to-pin' },
+    { name: 'PinOverridesSemverRange', slug: 'pin-overrides-semver-range' },
+    {
+      name: 'PinOverridesSemverRangeMismatch',
+      slug: 'pin-overrides-semver-range-mismatch',
+    },
+    { name: 'RefuseToPinLocal', slug: 'refuse-to-pin-local' },
+  ],
+  highestSemver: [
+    { name: 'SemverRangeMismatch', slug: 'semver-range-mismatch' },
+    { name: 'DiffersToLocal', slug: 'differs-to-local' },
+    { name: 'DiffersToCatalog', slug: 'differs-to-catalog' },
+    {
+      name: 'DiffersToHighestOrLowestSemver',
+      slug: 'differs-to-highest-or-lowest-semver',
+    },
+  ],
+  lowestSemver: [
+    { name: 'SemverRangeMismatch', slug: 'semver-range-mismatch' },
+    { name: 'DiffersToLocal', slug: 'differs-to-local' },
+    { name: 'DiffersToCatalog', slug: 'differs-to-catalog' },
+    {
+      name: 'DiffersToHighestOrLowestSemver',
+      slug: 'differs-to-highest-or-lowest-semver',
+    },
+  ],
+  sameRange: [{ name: 'SemverRangeMismatch', slug: 'semver-range-mismatch' }],
+  sameMinor: [
+    {
+      name: 'DiffersToHighestOrLowestSemverMinor',
+      slug: 'differs-to-highest-or-lowest-semver-minor',
+    },
+    { name: 'SemverRangeMismatch', slug: 'semver-range-mismatch' },
+    {
+      name: 'SameMinorOverridesSemverRange',
+      slug: 'same-minor-overrides-semver-range',
+    },
+    {
+      name: 'SameMinorOverridesSemverRangeMismatch',
+      slug: 'same-minor-overrides-semver-range-mismatch',
+    },
+  ],
+  snappedTo: [
+    { name: 'DiffersToSnapTarget', slug: 'differs-to-snap-target' },
+    { name: 'SemverRangeMismatch', slug: 'semver-range-mismatch' },
+    { name: 'RefuseToSnapLocal', slug: 'refuse-to-snap-local' },
+  ],
+  catalog: [
+    { name: 'NotUsingCatalog', slug: 'not-using-catalog' },
+    { name: 'MissingFromCatalog', slug: 'missing-from-catalog' },
+  ],
+  ignored: [],
+};
+
+export const GROUP_LABELS = {
+  banned: 'Banned',
+  pinned: 'Pinned',
+  highestSemver: 'Highest Semver',
+  lowestSemver: 'Lowest Semver',
+  sameRange: 'Same Range',
+  sameMinor: 'Same Minor',
+  snappedTo: 'Snapped To',
+  catalog: 'Catalog',
+  ignored: 'Ignored',
+};
+
+export const GROUP_LINKS = {
+  banned: '/version-groups/banned/',
+  pinned: '/version-groups/pinned/',
+  highestSemver: '/version-groups/highest-semver/',
+  lowestSemver: '/version-groups/lowest-semver/',
+  sameRange: '/version-groups/same-range/',
+  sameMinor: '/version-groups/same-minor/',
+  snappedTo: '/version-groups/snapped-to/',
+  catalog: '/version-groups/catalog/',
+  ignored: '/version-groups/ignored/',
+};

site/src/_partials/severity/suspect-default.mdx

@@ -0,0 +1 @@
+Not configurable via [`severity`](REF_SEVERITY){props.reason ? `: ${props.reason}` : ''}. Defaults to `"warn"` (or `"error"` under [`strict: true`](CONFIG_STRICT)).