@conduction/nextcloud-vue 2.2.0-vue3.13 → 2.2.0-vue3.14

package/scripts/check-jsdoc.js

@@ -0,0 +1,230 @@
+/* eslint-disable no-console, n/no-process-exit */
+/**
+ * JSDoc completeness ratchet (G2 of the auto-update guarantee).
+ *
+ * For every Cn* SFC, scores the JSDoc coverage on its props, events, and
+ * named slots, then compares against a per-component baseline committed
+ * at scripts/.jsdoc-baselines.json. CI fails when any component's score
+ * regresses below baseline; new components (no baseline entry) must
+ * score 100%.
+ *
+ * Spec: openspec/changes/unify-component-docs/specs/component-reference/
+ *       spec.md "Requirement: JSDoc completeness ratchet"
+ *
+ * Modes:
+ *   node scripts/check-jsdoc.js           Verify against baseline (CI mode)
+ *   node scripts/check-jsdoc.js --update  Regenerate baseline file
+ *   node scripts/check-jsdoc.js --json    Emit raw scores as JSON
+ *
+ * Why we resolve vue-docgen-api from docusaurus/node_modules:
+ *   The package is already installed there as a transitive dep of
+ *   vue-docgen-cli. Adding it as a separate root devdep would duplicate
+ *   the install and complicate the lockfile. The script is a developer
+ *   tool, not part of the published library bundle.
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+const ROOT = path.resolve(__dirname, '..')
+const COMPONENTS_DIR = path.join(ROOT, 'src/components')
+const BASELINE_FILE = path.join(__dirname, '.jsdoc-baselines.json')
+const DOCGEN_API_PATH = path.join(ROOT, 'docusaurus/node_modules/vue-docgen-api')
+
+// Resolve vue-docgen-api from the docusaurus install. If it's missing, the
+// dev hasn't run `cd docusaurus && npm install` yet — give a clear hint.
+let parse
+try {
+	parse = require(DOCGEN_API_PATH).parse
+} catch (err) {
+	// `npm ci` — NOT `npm install --legacy-peer-deps`, which this hint used to
+	// recommend and which CLAUDE.md forbids outright. The lockfile resolves
+	// cleanly and CI installs these deps with a plain `npm ci`
+	// (code-quality.yml: `frontend-setup-command: cd docusaurus && npm ci`), so
+	// the flag was never needed. A hint pointing at a banned workaround makes
+	// the gate look unrunnable, which gets it skipped rather than fixed.
+	console.error(
+		'[check-jsdoc] Failed to load vue-docgen-api from docusaurus/node_modules.\n'
+		+ '             Run `cd docusaurus && npm ci` first.',
+	)
+	process.exit(2)
+}
+
+const args = process.argv.slice(2)
+const UPDATE_MODE = args.includes('--update')
+const JSON_MODE = args.includes('--json')
+
+/**
+ * @returns {string[]} Absolute paths to every `CnFoo/CnFoo.vue` SFC.
+ */
+function findCnSfcs() {
+	const dirs = fs.readdirSync(COMPONENTS_DIR, { withFileTypes: true })
+		.filter(d => d.isDirectory() && d.name.startsWith('Cn'))
+	return dirs
+		.map(d => path.join(COMPONENTS_DIR, d.name, `${d.name}.vue`))
+		.filter(p => fs.existsSync(p))
+}
+
+/**
+ * Score one component. A documented item counts 1; an undocumented item
+ * counts 0. The score is documented / total. Components with no
+ * props/events/slots score 1.0 (vacuously documented).
+ *
+ * Documentation rules (per spec):
+ *  - Prop: non-empty description.
+ *  - Event: non-empty description (incl. JSDoc on $emit site).
+ *  - Slot: non-empty description.
+ *
+ * @returns {{component, score, total, documented, missing}}
+ */
+async function scoreSfc(sfcPath) {
+	const componentName = path.basename(sfcPath, '.vue')
+	const doc = await parse(sfcPath)
+
+	const items = []
+
+	for (const p of doc.props || []) {
+		items.push({
+			kind: 'prop',
+			name: p.name,
+			documented: Boolean((p.description || '').trim()),
+		})
+	}
+
+	// vue-docgen-api emits each $emit site separately AND any @event JSDoc
+	// tag, so the same logical event can appear twice. Dedupe by name and
+	// take the richest description. The character class allows `:` (e.g.
+	// `update:mode`, `update:expanded-ids`) and `.` (e.g. `field.changed`)
+	// in event names — the original `[\w-]+` regex left those events
+	// permanently flagged as undocumented because the colon couldn't be
+	// captured, see ncv#333.
+	const eventByName = new Map()
+	for (const e of doc.events || []) {
+		const m = e.name.match(/^([\w:.-]+)\s+(.+)$/s)
+		const cleanName = m ? m[1] : e.name
+		const inferredDesc = m ? m[2].trim() : ''
+		const desc = ((e.description || '').trim() || inferredDesc).trim()
+		const existing = eventByName.get(cleanName)
+		if (!existing || desc.length > existing.length) {
+			eventByName.set(cleanName, desc)
+		}
+	}
+	for (const [name, desc] of eventByName) {
+		items.push({ kind: 'event', name, documented: Boolean(desc) })
+	}
+
+	for (const s of doc.slots || []) {
+		items.push({
+			kind: 'slot',
+			name: s.name,
+			documented: Boolean((s.description || '').trim()),
+		})
+	}
+
+	const total = items.length
+	const documented = items.filter(i => i.documented).length
+	const score = total === 0 ? 1.0 : documented / total
+	const missing = items.filter(i => !i.documented).map(i => `${i.kind}:${i.name}`)
+
+	return { component: componentName, score, total, documented, missing }
+}
+
+/**
+ * Round to 2 decimals so baseline diffs are stable across reruns.
+ */
+function round(n) {
+	return Math.round(n * 100) / 100
+}
+
+async function main() {
+	const sfcs = findCnSfcs()
+	const results = []
+	for (const sfc of sfcs) {
+		try {
+			results.push(await scoreSfc(sfc))
+		} catch (err) {
+			console.error(`[check-jsdoc] Failed to parse ${path.relative(ROOT, sfc)}: ${err.message}`)
+			process.exit(2)
+		}
+	}
+	results.sort((a, b) => a.component.localeCompare(b.component))
+
+	if (JSON_MODE) {
+		console.log(JSON.stringify(results, null, 2))
+		return
+	}
+
+	if (UPDATE_MODE) {
+		const baseline = {}
+		for (const r of results) baseline[r.component] = round(r.score)
+		baseline.__schema__ = {
+			generatedBy: 'scripts/check-jsdoc.js --update',
+			rule: 'CI fails if any component score < baseline. New components require 1.0.',
+		}
+		fs.writeFileSync(BASELINE_FILE, JSON.stringify(baseline, null, 2) + '\n')
+		console.log(`[check-jsdoc] Wrote baseline for ${results.length} components → ${path.relative(ROOT, BASELINE_FILE)}`)
+		return
+	}
+
+	let baseline = {}
+	if (fs.existsSync(BASELINE_FILE)) {
+		baseline = JSON.parse(fs.readFileSync(BASELINE_FILE, 'utf8'))
+	}
+
+	const failures = []
+	for (const r of results) {
+		const key = r.component
+		const observed = round(r.score)
+		const expected = key in baseline ? baseline[key] : 1.0
+		const isNew = !(key in baseline)
+		if (observed < expected) {
+			failures.push({ ...r, observed, expected, isNew })
+		}
+	}
+
+	// Pretty print: per-component score table.
+	const longestName = Math.max(0, ...results.map(r => r.component.length))
+	console.log('\nJSDoc completeness scores (Cn* components):')
+	console.log('─'.repeat(longestName + 30))
+	for (const r of results) {
+		const pct = (r.score * 100).toFixed(0).padStart(3) + '%'
+		const baselineMark = r.component in baseline
+			? `(baseline ${(baseline[r.component] * 100).toFixed(0)}%)`
+			: '(NEW — must be 100%)'
+		console.log(`  ${r.component.padEnd(longestName)}  ${pct}  ${r.documented}/${r.total}  ${baselineMark}`)
+	}
+	console.log('─'.repeat(longestName + 30))
+
+	if (failures.length === 0) {
+		console.log(`✓ All ${results.length} components meet their JSDoc baseline.`)
+		console.log('  Tip: improve coverage in a PR, then `npm run jsdoc-baselines:update` to bump the bar.\n')
+		return
+	}
+
+	console.error('\n✗ JSDoc completeness regression(s):\n')
+	for (const f of failures) {
+		const expectedPct = (f.expected * 100).toFixed(0)
+		const observedPct = (f.observed * 100).toFixed(0)
+		const lead = f.isNew
+			? `${f.component} is a new component and MUST score 100%`
+			: `${f.component} score dropped from baseline ${expectedPct}% to ${observedPct}%`
+		console.error(`  • ${lead}`)
+		console.error(`    File: src/components/${f.component}/${f.component}.vue`)
+		console.error(`    Missing JSDoc on:`)
+		for (const m of f.missing) {
+			console.error(`      - ${m}`)
+		}
+		console.error('')
+	}
+	console.error('How to fix:')
+	console.error('  1. Add the missing JSDoc to the SFC (see CLAUDE.md "Documenting components").')
+	console.error('  2. Re-run `npm run check:jsdoc` to confirm.')
+	console.error('  3. If you intentionally improved coverage, run `npm run jsdoc-baselines:update`')
+	console.error('     and commit the bumped baseline.\n')
+	process.exit(1)
+}
+
+main().catch(err => {
+	console.error(err)
+	process.exit(2)
+})

package/scripts/check-peer-consistency.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+/**
+ * Peer-dependency consistency gate.
+ *
+ * A `peerDependencies` block can be internally CONTRADICTORY: package A is
+ * declared at a range whose versions all require package B at a range that
+ * shares no version with the range we declare for B. npm 7+ resolves peers
+ * strictly, so every correctly-behaving consumer then hits ERESOLVE and has to
+ * add an `overrides` entry — or, worse, installs with `--legacy-peer-deps` and
+ * silently gets an unsupported tree.
+ *
+ * That is not hypothetical. Shipped in every release up to 2.1.0-vue3.15:
+ *
+ *     "@nextcloud/capabilities":  "^1.2.1"     ← requires initial-state ^3.0.0
+ *     "@nextcloud/vue":           "^9.0.0"     ← requires initial-state ^3.0.0
+ *     "@nextcloud/initial-state": "^2.2.0"     ← no overlap with either
+ *
+ * openregister had to add an override just to install. Nothing in CI noticed,
+ * because the library's own `npm ci` installs its DEV tree — where the peers
+ * are resolved from devDependencies and the contradiction never surfaces.
+ *
+ * OFFLINE BY DESIGN
+ * -----------------
+ * This gate reads the already-installed `node_modules` rather than querying
+ * the registry: a network call in CI is a flake waiting to happen, and the
+ * installed tree is what the repo actually builds and tests against. The
+ * trade-off is coverage — it checks the resolved version of each peer, not
+ * every version the declared range admits. A `--registry` pass would be
+ * strictly stronger and is a reasonable follow-up; this catches the class of
+ * bug that has actually shipped.
+ *
+ * Exit codes:
+ *   0 — no contradiction found among the installed peers
+ *   1 — at least one installed peer requires another peer at a range that
+ *       cannot be satisfied together with our own declaration
+ */
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const ROOT = path.resolve(__dirname, '..')
+
+/**
+ * Read a package.json, returning null when it is absent or unparseable.
+ *
+ * @param {string} file Absolute path.
+ *
+ * @return {object|null} Parsed manifest.
+ */
+function readJson(file) {
+	try {
+		return JSON.parse(fs.readFileSync(file, 'utf8'))
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Whether two semver ranges can be satisfied by a common version.
+ *
+ * @param {object} semver The `semver` module.
+ * @param {string} a First range.
+ * @param {string} b Second range.
+ *
+ * @return {boolean} True when the ranges intersect.
+ */
+function rangesIntersect(semver, a, b) {
+	try {
+		return semver.intersects(a, b, { includePrerelease: true })
+	} catch {
+		// A range this resolver cannot parse (a git URL, `*`, a workspace
+		// protocol) is not evidence of a conflict. Say nothing rather than
+		// manufacture a failure.
+		return true
+	}
+}
+
+/**
+ * Run the gate.
+ *
+ * @return {void}
+ */
+function main() {
+	const pkg = readJson(path.join(ROOT, 'package.json'))
+	const peers = (pkg && pkg.peerDependencies) || {}
+	const names = Object.keys(peers)
+
+	if (names.length === 0) {
+		console.log('✓ peer consistency: no peerDependencies declared')
+		process.exit(0)
+	}
+
+	let semver
+	try {
+		// eslint-disable-next-line global-require
+		semver = require('semver')
+	} catch {
+		console.error('  (peer-consistency gate skipped: `semver` is not installed)')
+		process.exit(0)
+	}
+
+	const failures = []
+	let inspected = 0
+
+	for (const name of names) {
+		const manifest = readJson(path.join(ROOT, 'node_modules', name, 'package.json'))
+		if (manifest === null) {
+			// Not installed — an optional peer the dev tree does not pull in.
+			// Absence is not a finding.
+			continue
+		}
+		inspected++
+
+		// A peer's own requirements on ANOTHER of our peers, whether it lists
+		// them as dependencies or as peerDependencies. Both constrain the
+		// consumer's tree.
+		const constraints = { ...(manifest.peerDependencies || {}), ...(manifest.dependencies || {}) }
+
+		for (const [other, range] of Object.entries(constraints)) {
+			if (!Object.prototype.hasOwnProperty.call(peers, other)) {
+				continue
+			}
+			if (!rangesIntersect(semver, range, peers[other])) {
+				failures.push(
+					`${name}@${manifest.version} requires ${other}@${range}, `
+					+ `but we declare ${other}@${peers[other]} — no version satisfies both.\n`
+					+ `      Widen our ${other} peer (e.g. "${peers[other]} || ${range}") `
+					+ 'or lower the peer that demands it.',
+				)
+			}
+		}
+	}
+
+	if (inspected === 0) {
+		// Positive control: a run that inspected nothing must not report a
+		// clean bill of health. That shape — a check that cannot match
+		// anything, printing a tick — is indistinguishable from a real pass.
+		console.error('✗ peer consistency: no declared peer is installed — run `npm ci` first')
+		process.exit(1)
+	}
+
+	if (failures.length > 0) {
+		console.error('✗ peer consistency gate failed:')
+		for (const failure of failures) {
+			console.error(`  - ${failure}`)
+		}
+		console.error(
+			'\nA contradictory peer block makes `npm install` fail with ERESOLVE for every\n'
+			+ 'consumer that does not add an override. See scripts/check-peer-consistency.js.',
+		)
+		process.exit(1)
+	}
+
+	console.log(`✓ peer consistency: ${inspected} installed peer(s) agree with our declared ranges`)
+	process.exit(0)
+}
+
+main()

package/scripts/generate-nl-icons.mjs

@@ -0,0 +1,98 @@
+/**
+ * One-off generator: turn CC0/EUPL government icon SVGs into compact
+ * data-URI catalogue modules for @conduction/nextcloud-vue.
+ *
+ * Each emitted entry is `{ key, label, url }` where `url` is a tiny
+ * `data:image/svg+xml,...` URI — consumed via CnIconBrowser's `url-icons`
+ * prop and rendered as `<img>`, so multi-path / illustrative icons render
+ * faithfully (the single-path catalogue path cannot represent them).
+ */
+import { readdirSync, readFileSync, writeFileSync, statSync, mkdirSync } from 'node:fs'
+import { join, basename, extname } from 'node:path'
+
+const SRC = process.env.SRC_ROOT
+const OUT = process.env.OUT_DIR
+if (!SRC || !OUT) { throw new Error('SRC_ROOT and OUT_DIR required') }
+mkdirSync(OUT, { recursive: true })
+
+/** Recursively collect *.svg files under dir. */
+function walk(dir) {
+	const out = []
+	for (const name of readdirSync(dir)) {
+		const p = join(dir, name)
+		const st = statSync(p)
+		if (st.isDirectory()) { out.push(...walk(p)) } else if (extname(name).toLowerCase() === '.svg') { out.push(p) }
+	}
+	return out
+}
+
+/** Humanise a file base name into a label. */
+function humanize(name) {
+	return name
+		.replace(/\.svg$/i, '')
+		.replace(/^.*__/, '') // strip category prefix (denhaag arrows__x)
+		.replace(/[-_]+/g, ' ')
+		.replace(/([a-z])([A-Z])/g, '$1 $2')
+		.trim()
+		.replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+/** Slug for a stable key. */
+function slug(s) {
+	return s.toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+}
+
+/**
+ * Mini SVG → data-URI (Taylor Hunt / tigt "mini-svg-data-uri" algorithm):
+ * single-quote attrs, collapse whitespace, encodeURIComponent, then decode
+ * the handful of hex pairs that are safe & shorter unencoded.
+ */
+function svgToTinyDataUri(svg) {
+	const reWs = /\s+/g
+	const reHex = /%[\dA-F]{2}/g
+	const decode = (m) => ({ '%20': ' ', '%3D': '=', '%3A': ':', '%2F': '/' }[m.toUpperCase()] || m.toLowerCase())
+	let s = svg
+		.replace(/<\?xml[\s\S]*?\?>/gi, '')
+		.replace(/<!--[\s\S]*?-->/g, '')
+		.replace(/<!DOCTYPE[\s\S]*?>/gi, '')
+		.replace(/<title>[\s\S]*?<\/title>/gi, '')
+		.trim()
+		.replace(reWs, ' ')
+		.replace(/> </g, '><')
+		.replace(/"/g, "'")
+	s = encodeURIComponent(s).replace(reHex, decode)
+	return 'data:image/svg+xml,' + s
+}
+
+const SETS = [
+	{ name: 'rvo', exportName: 'rvoIcons', dir: join(SRC, 'nlrvo-assets/package/icons'), keyPrefix: 'rvo' },
+	{ name: 'openGemeenten', exportName: 'openGemeentenIcons', dir: join(SRC, 'og/Iconenset-master/Svg/Line'), keyPrefix: 'og' },
+	{ name: 'denHaag', exportName: 'denHaagIcons', dir: join(SRC, 'denhaag-svg'), keyPrefix: 'dh' },
+]
+
+const summary = []
+for (const set of SETS) {
+	const files = walk(set.dir).sort()
+	const seen = new Set()
+	const entries = []
+	let bytes = 0
+	for (const f of files) {
+		const raw = readFileSync(f, 'utf8')
+		if (!raw.includes('<svg')) { continue }
+		const label = humanize(basename(f))
+		let id = `${set.keyPrefix}-${slug(basename(f).replace(/\.svg$/i, ''))}`
+		let n = 2
+		while (seen.has(id)) { id = `${set.keyPrefix}-${slug(basename(f).replace(/\.svg$/i, ''))}-${n++}` }
+		seen.add(id)
+		const url = svgToTinyDataUri(raw)
+		bytes += url.length
+		entries.push({ id, label, url })
+	}
+	entries.sort((a, b) => a.label.localeCompare(b.label))
+	const header = `/**\n * SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>\n * SPDX-License-Identifier: EUPL-1.2\n *\n * AUTO-GENERATED by scripts/generate-nl-icons.mjs — do not edit by hand.\n * Icon artwork: see icons/ATTRIBUTION.md for upstream sources & licences.\n *\n * ${entries.length} icons, each an { id, label, url } entry whose \`url\` is a\n * self-contained data:image/svg+xml URI (render via CnIconBrowser url-icons).\n */\n`
+	const body = `export const ${set.exportName} = ${JSON.stringify(entries, null, '\t')}\n\nexport default ${set.exportName}\n`
+	writeFileSync(join(OUT, `${set.name}.js`), header + body)
+	summary.push({ set: set.name, icons: entries.length, kb: Math.round(bytes / 1024) })
+}
+writeFileSync(join(OUT, 'index.js'), `/**\n * SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>\n * SPDX-License-Identifier: EUPL-1.2\n *\n * Barrel for the bundled NL-government icon catalogues.\n *\n * Prefer a per-set subpath import (\`@conduction/nextcloud-vue/src/icons/rvo.js\`)\n * so bundlers only pull the set you use. \`NL_DESIGN_ICON_GROUPS\` and the combined\n * \`NL_DESIGN_ICONS\` reference all three sets, so importing them pulls every set.\n *\n * Group shape: { key, label, icons: [{ id, label, url }] } — feed straight to\n * CnIconBrowser's \`url-icon-groups\` prop for a tab per set.\n */\nimport { rvoIcons } from './rvo.js'\nimport { openGemeentenIcons } from './openGemeenten.js'\nimport { denHaagIcons } from './denHaag.js'\n\nexport { rvoIcons, openGemeentenIcons, denHaagIcons }\n\nexport const NL_DESIGN_ICON_GROUPS = [\n\t{ key: 'rvo', label: 'RVO', icons: rvoIcons },\n\t{ key: 'open-gemeenten', label: 'Gemeente', icons: openGemeentenIcons },\n\t{ key: 'den-haag', label: 'Den Haag', icons: denHaagIcons },\n]\n\n/** Flat combined list of every bundled NL-government icon ({ id, label, url }). */\nexport const NL_DESIGN_ICONS = [...rvoIcons, ...openGemeentenIcons, ...denHaagIcons]\n`)
+console.log(JSON.stringify(summary, null, 2))

package/scripts/precommit-regenerate-features.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# Regenerates docs/features.json whenever staged changes touch openspec/specs/
+# or the features overlay (see CONVENTIONS.md in ConductionNL/.github,
+# § "features.json is generated at commit time, never by CI").
+#
+# Best-effort by design: any failure only warns and never blocks the commit —
+# the CI gate (features-check/features-extract → Quality Report) enforces.
+
+if git diff --cached --name-only | grep -qE "^openspec/(specs/|features\.overlay\.json)"; then
+  CACHE=".git/extract-features.py"
+  # Fetch the canonical script (single source of truth in ConductionNL/.github);
+  # fall back to a previously cached copy when offline.
+  curl -sf --max-time 10 \
+    https://raw.githubusercontent.com/ConductionNL/.github/main/scripts/extract-features.py \
+    -o "$CACHE" 2>/dev/null || true
+
+  if [ -f "$CACHE" ]; then
+    if command -v python3 >/dev/null 2>&1; then PY="python3";
+    elif command -v py >/dev/null 2>&1; then PY="py -3";
+    else PY="python"; fi
+
+    if $PY "$CACHE" --app-root . >/dev/null 2>&1; then
+      git add docs/features.json
+      echo "pre-commit: docs/features.json regenerated from openspec/specs/."
+    else
+      echo "pre-commit: WARNING — could not regenerate docs/features.json (python or pyyaml missing?). CI features-check will verify." >&2
+    fi
+  else
+    echo "pre-commit: WARNING — could not fetch extract-features.py (offline?). CI features-check will verify." >&2
+  fi
+fi
+
+exit 0

package/scripts/precommit-regenerate-partials.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Pre-commit hook: G3.5 of the auto-update guarantee.
+#
+# When a `src/components/Cn*/Cn*.vue` file is in the staged set,
+# regenerate `docs/components/_generated/<name>.md` via vue-docgen-cli
+# and stage the result so the commit lands the SFC + the auto-doc
+# partial atomically.
+#
+# Without this hook, the freshness gate in `code-quality.yml` (G1)
+# still catches stale partials at CI time, but the author has to
+# remember to run `cd docusaurus && npm run prebuild:docs` manually
+# before pushing. This hook closes that loop locally.
+#
+# Spec: openspec/specs/component-reference/spec.md
+#       Requirement: Auto-regeneration on commit (developer ergonomics)
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------
+# Pluggable integration registry parity gate (AD-11/AD-13).
+#
+# When any src/integrations/ file is staged, run the parity check so a
+# descriptor missing its `tab` or `widget` is caught at commit time
+# rather than only at CI (code-quality.yml's "Integration parity gate"
+# step). Cheap — just requires one Node module. Runs before the Cn*
+# SFC early-exit below so it isn't skipped on integrations-only commits.
+# ---------------------------------------------------------------------
+if git diff --cached --name-only --diff-filter=ACMR \
+     | grep -qE '^src/integrations/'; then
+  echo '[pre-commit] src/integrations/ staged — running integration parity gate'
+  node scripts/check-integration-parity.js
+fi
+
+# Bail unless at least one Cn* SFC is staged. The check runs O(staged
+# files), so the cost is trivial when nothing in src/components/ moves.
+if ! git diff --cached --name-only --diff-filter=ACMR \
+     | grep -qE '^src/components/Cn[^/]+/Cn[^/]+\.vue$'; then
+  exit 0
+fi
+
+# Skip silently if docusaurus deps aren't installed yet. New
+# contributors haven't necessarily run `cd docusaurus && npm install`
+# before their first commit; failing the commit on this would be a
+# bad first-impression. CI's freshness gate still catches the stale
+# partial when they push, with a clear "run this command" hint.
+if [ ! -x docusaurus/node_modules/.bin/vue-docgen ]; then
+  cat <<'EOF' >&2
+[pre-commit] Skipping auto-regen: docusaurus/ deps not installed.
+[pre-commit] Install once with `cd docusaurus && npm install --legacy-peer-deps`
+[pre-commit] to enable automatic partial regeneration on commit. Without it,
+[pre-commit] CI's freshness gate will still catch stale _generated/ files,
+[pre-commit] just at push time instead of commit time.
+EOF
+  exit 0
+fi
+
+echo '[pre-commit] Cn* SFC staged — regenerating docs/components/_generated/'
+
+# Regenerate. The script is idempotent — if the partials already match
+# the source, the diff is empty and `git add` is a no-op.
+( cd docusaurus && npm run --silent prebuild:docs )
+
+# Stage every regenerated partial. Even if the author only touched one
+# component, vue-docgen-cli rewrites column padding across the whole
+# table when widths shift (rare but possible) and any drift would fail
+# the freshness gate at push time. Re-staging the whole _generated/
+# tree keeps things in lockstep.
+git add docs/components/_generated/

package/scripts/sync-l10n-ellipsis.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * Mirrors the @nextcloud/l10n-enforce-ellipsis lint fix into the l10n
+ * translation catalogs. ESLint only touches source files; this rewrites
+ * `...` (exactly three ASCII dots, not adjacent to another dot) to `…`
+ * in l10n/*.json — keys and values both, since runtime lookups match
+ * the exact source string.
+ *
+ * Implemented as a textual substitution to preserve all unrelated
+ * formatting (whitespace, key order, even duplicate keys) so the diff
+ * is strictly the ellipsis change.
+ *
+ * Runs as part of `npm run lint-fix`.
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+const ELLIPSIS_RE = /(?<!\.)\.{3}(?!\.)/g
+
+function processFile(file) {
+	const original = fs.readFileSync(file, 'utf8')
+	const rewritten = original.replace(ELLIPSIS_RE, '…')
+	if (rewritten === original) return false
+	fs.writeFileSync(file, rewritten)
+	return true
+}
+
+const l10nDir = path.join(__dirname, '..', 'l10n')
+if (!fs.existsSync(l10nDir)) {
+	process.exit(0)
+}
+
+let changed = 0
+for (const entry of fs.readdirSync(l10nDir)) {
+	if (!entry.endsWith('.json')) continue
+	const file = path.join(l10nDir, entry)
+	if (processFile(file)) {
+		changed++
+		console.log(`sync-l10n-ellipsis: rewrote ${path.relative(process.cwd(), file)}`)
+	}
+}
+
+if (changed === 0) {
+	console.log('sync-l10n-ellipsis: no changes')
+}