mandrel-platform 0.19.2 → 0.20.1

package/README.md

@@ -13,7 +13,7 @@ hand-maintaining its own copies and drifting apart over time.
 | ------ | ---------------- |
 | **Reusable workflows** | `workflow_call` CI, deploy, secret-scan, release, and CodeQL pipelines, consumed by tag/SHA pin. |
 | **Composite action** | `setup-toolchain` — pnpm + Node + frozen install in one step. |
-| **Config bases (npm)** | `extends`-able baselines: TypeScript, Biome, Knip, Stryker, commitlint, dependency-cruiser, size-limit, Lighthouse. |
+| **Config bases (npm)** | `extends`-able baselines: TypeScript, Biome, Knip, Stryker, commitlint, dependency-cruiser, secretlint, size-limit, Lighthouse. |
 | **Edge-security middleware (npm)** | Per-env closed-allowlist CORS, security headers, and app-layer rate limiting for Astro + Hono. |
 | **Guardrail scripts (npm)** | Dependency-free policy checks: CVE gate, action-pin ratchet, coverage floor, destructive-migration guard, workflow-portability, required-contexts, docs-staleness. |
 | **Renovate preset** | Shared dependency-update policy, including auto-bumping this repo's own `uses:` pins. |
@@ -143,10 +143,11 @@ upgrade to 2.x before adopting this base (refs #153).
 
 ### Code-quality tooling base configs
 
-The package also ships shared base configs for the five code-quality /
+The package also ships shared base configs for the code-quality /
 hygiene tools every consumer runs — **Knip**, **Stryker**,
-**dependency-cruiser**, **size-limit**, and **Lighthouse**. Each is the
-best-of-breed union of the consumers' previously hand-maintained configs.
+**dependency-cruiser**, **markdownlint**, **secretlint**, **size-limit**,
+and **Lighthouse**. Each is the best-of-breed union of the consumers'
+previously hand-maintained configs.
 Adoption is opt-in via `extends` (or a spread / deep-merge where the tool
 has no native `extends`), and every project-specific knob — entrypoints,
 mutate globs, bundle paths, score floors, and budgets — stays
@@ -238,6 +239,92 @@ resolve the package export and add repo-specific rules
 }
 ```
 
+#### `markdownlint.base.jsonc`
+
+Shared markdownlint **content** rule base — the union of the fleet's three
+previously per-repo configs, which had diverged only by accretion (~90%
+identical). Ships the common core (`default: true`) narrowed by `MD013: false`
+(line-length — Prettier owns wrap), `MD024: { siblings_only: true }`
+(duplicate headings allowed under different parents), `MD033: false` (inline
+HTML), `MD041: false` (first-line-heading), and `MD060: false` (GFM table
+style — Prettier owns table reflow).
+
+**Canonical runner: `markdownlint-cli2`.** It is the maintained, recommended
+runner and two of the three consumers already run it; new adopters standardize
+on it (classic `markdownlint` consumes the same `MDxxx` rule IDs, so the base
+is compatible either way). markdownlint-cli2 resolves `extends` to a package
+path, so a consumer's local config reduces to the extend plus repo-specific
+**ignore globs** — which stay local, since generated/vendored trees differ per
+repo (`.markdownlint.jsonc`):
+
+```jsonc
+// .markdownlint.jsonc — extend the shared content base
+{
+  "extends": "mandrel-platform/markdownlint.base.jsonc"
+  // ...repo-specific rule overrides (rare)
+}
+```
+
+```jsonc
+// .markdownlint-cli2.jsonc — ignore globs stay consumer-local
+{
+  "ignores": ["CHANGELOG.md"]
+}
+```
+
+The base carries **content rules only, never `ignores`**. Excluding the
+release-please-generated `CHANGELOG.md` is a mandatory per-consumer ignore
+documented in
+[`docs/reusable-workflows.md`](docs/reusable-workflows.md). markdownlint gates
+content rules Prettier does not — the two are **complementary**, not
+substitutes: keep both.
+
+#### `secretlint.base.json`
+
+The single source of truth for the **local pre-commit secret-scan mirror**
+of the CI gitleaks tiers — the shift-left dev-experience twin that catches
+a secret at `git commit` time before it ever reaches the CI gitleaks gate.
+The ruleset ships the recommended preset
+(`@secretlint/secretlint-rule-preset-recommend`); single-sourcing it here
+means a rule change lands fleet-wide in one place instead of drifting across
+each consumer's hand-copied `.secretlintrc.json`.
+
+secretlint's `.secretlintrc` has **no native file-level `extends`**, so
+consumers adopt this base one of two ways. The **husky hook _wiring_ stays
+consumer-local** either way — only the _ruleset_ is single-sourced.
+
+**Reference the base directly from the husky hook (simplest — no local
+config file).** Point the pre-commit hook's `--secretlintrc` at the package
+export; there is no `.secretlintrc.json` to maintain:
+
+```sh
+# .husky/pre-commit — scan staged files against the shared ruleset
+npx secretlint --secretlintrc node_modules/mandrel-platform/config/secretlint.base.json --maskSecrets "$(git diff --cached --name-only)"
+```
+
+**Or import + spread into a JS-module `.secretlintrc.mjs`** when the repo has
+genuine, explicitly-listed local overrides (an extra rule, an
+`allowMessageIds` suppression). Keep the local file to the base plus **only**
+the deltas:
+
+```js
+// .secretlintrc.mjs — spread the shared ruleset, layer repo-specific deltas only
+import base from "mandrel-platform/secretlint.base.json" with { type: "json" };
+
+export default {
+  ...base,
+  // repo-specific overrides ONLY — e.g. an additional rule, or an
+  // allowMessageIds suppression for a known-safe fixture. Leave empty
+  // to inherit the shared ruleset verbatim.
+};
+```
+
+> **Local mirror, not a CI replacement.** This base is the *local* shift-left
+> scanner; the blocking secret-scan gate remains the shared CI gitleaks
+> tiers (see [reusable-workflows.md](docs/reusable-workflows.md)). Swapping
+> the local tool for a local↔CI gitleaks-parity scan is a deliberate separate
+> question, out of scope for this base.
+
 #### `size-limit.base.json`
 
 size-limit's own config is a per-entry **array** whose paths and limits
@@ -722,6 +809,8 @@ repo is developed with — dev-time only, and not shipped in the npm package.
 | `mandrel-platform/stryker.base.json`            | `config/stryker.base.json`            |
 | `mandrel-platform/commitlint.base.mjs`          | `config/commitlint.base.mjs`          |
 | `mandrel-platform/dependency-cruiser.base.json` | `config/dependency-cruiser.base.json` |
+| `mandrel-platform/markdownlint.base.jsonc`      | `config/markdownlint.base.jsonc`      |
+| `mandrel-platform/secretlint.base.json`         | `config/secretlint.base.json`         |
 | `mandrel-platform/size-limit.base.json`         | `config/size-limit.base.json`         |
 | `mandrel-platform/lighthouse.base.json`         | `config/lighthouse.base.json`         |
 | `mandrel-platform/lighthouse-thresholds.base.json` | `config/lighthouse-thresholds.base.json` |

package/config/markdownlint.base.jsonc

@@ -0,0 +1,58 @@
+// markdownlint.base.jsonc — shared markdownlint rule base for
+// mandrel-platform consumers.
+//
+// Single-sources the fleet's common-core markdownlint content rules so the
+// three consumers stop hand-maintaining ~90%-identical rule sets that diverge
+// only by accretion. This is the union of the previously per-repo configs
+// (domio / athportal / swarm-os), keyed by the same underlying `markdownlint`
+// MDxxx rule IDs both `markdownlint-cli2` and classic `markdownlint` consume.
+//
+// CANONICAL RUNNER: markdownlint-cli2. Two of the three consumers already run
+// it; it is the maintained, recommended runner. New adopters standardize on it.
+//
+// ADOPTION (markdownlint-cli2): consumers reference this base via the
+// `extends` property in their own `.markdownlint.jsonc` /
+// `.markdownlint-cli2.jsonc` and keep only repo-local ignore globs there:
+//
+//   // .markdownlint.jsonc
+//   {
+//     "extends": "mandrel-platform/markdownlint.base.jsonc"
+//     // ...repo-specific rule overrides (rare)
+//   }
+//
+//   // .markdownlint-cli2.jsonc — ignores stay local (e.g. generated CHANGELOG.md)
+//   { "ignores": ["CHANGELOG.md"] }
+//
+// The base carries CONTENT rules only — it does NOT carry `ignores`. Ignore
+// globs are inherently repo-specific (generated files, vendored trees) and
+// stay consumer-tunable locally. Excluding the release-please `CHANGELOG.md`
+// in particular is documented in docs/reusable-workflows.md.
+//
+// This base is complementary to Prettier's markdown FORMATTING (line wrap,
+// list markers) — markdownlint gates CONTENT rules Prettier does not, and the
+// two are not substitutes.
+{
+  // Start from the full default rule set, then narrow.
+  "default": true,
+
+  // MD013 line-length: off. Prose reflow is Prettier's job; a hard line-length
+  // gate on hand-authored docs produces noise, not signal.
+  "MD013": false,
+
+  // MD024 no-duplicate-heading: allow same-text headings under DIFFERENT
+  // parents (siblings_only). Repeated "### Notes" under distinct sections is
+  // legitimate structure, not a mistake.
+  "MD024": { "siblings_only": true },
+
+  // MD033 no-inline-html: off. Docs legitimately embed <details>, <kbd>,
+  // <br>, and alignment attributes GitHub-flavored Markdown renders.
+  "MD033": false,
+
+  // MD041 first-line-heading: off. Files that open with front-matter, a
+  // badge row, or an admonition before the first heading are valid.
+  "MD041": false,
+
+  // MD060 (table column style / GFM table hygiene): off. Table formatting is
+  // owned by Prettier's GFM table reflow, not a markdownlint content gate.
+  "MD060": false
+}

package/config/secretlint.base.json

@@ -0,0 +1,8 @@
+{
+  "_comment": "Shared secretlint config for mandrel-platform consumers — the single source of truth for the LOCAL pre-commit secret-scan mirror of the CI gitleaks tiers (shift-left dev-experience). secretlintrc has NO native file-level `extends`, so consumers reference this base instead of hand-copying the ruleset: point the husky pre-commit hook at it directly (`secretlint --secretlintrc node_modules/mandrel-platform/config/secretlint.base.json`) or import + spread it into a JS-module `.secretlintrc.mjs` layering only genuine repo-specific overrides. See README § secretlint.base.json for the adoption pattern. The husky hook *wiring* stays consumer-local; the *ruleset* is single-sourced here so a rule change lands fleet-wide in one place.",
+  "rules": [
+    {
+      "id": "@secretlint/secretlint-rule-preset-recommend"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "0.19.2",
+  "version": "0.20.1",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,8 @@
     "./stryker.base.json": "./config/stryker.base.json",
     "./commitlint.base.mjs": "./config/commitlint.base.mjs",
     "./dependency-cruiser.base.json": "./config/dependency-cruiser.base.json",
+    "./markdownlint.base.jsonc": "./config/markdownlint.base.jsonc",
+    "./secretlint.base.json": "./config/secretlint.base.json",
     "./size-limit.base.json": "./config/size-limit.base.json",
     "./lighthouse.base.json": "./config/lighthouse.base.json",
     "./lighthouse-thresholds.base.json": "./config/lighthouse-thresholds.base.json",