@pseolint/core 0.6.4 → 0.6.5

package/README.md

@@ -223,6 +223,70 @@ const md   = formatMarkdown(summary);
 const html = formatHtml(summary);
 ```
 
+## JSON output contract
+
+`formatJson(summary)` (and `pseolint --format json`) serializes the `AuditSummary` shape verbatim. This is the surface CI gates and other programmatic consumers (pseolint-gate-style scripts) should read. A machine-readable **JSON Schema (draft 2020-12)** is published with the package at [`schemas/audit-summary.schema.json`](./schemas/audit-summary.schema.json) — validate against it instead of hand-rolling shape assumptions.
+
+### `schemaVersion` — read it, branch on it
+
+```jsonc
+{
+  "schemaVersion": "2026-06-v0.6",  // bumps on EVERY breaking OR additive-public output change
+  "verdict": "caution",             // "ready" | "caution" | "concerning" | "critical"
+  "risk": 42,                       // 0-100, lower = better. Never shown to humans; use for CI thresholds.
+  "headline": "3 ship-blockers, 16 should-fix",
+  "categories": { /* 5 fixed keys → { grade, issues } */ },
+  "issues":     { /* severity buckets — see below */ },
+  "templates":  [ /* v0.6 per-template breakdown; may be [] or absent */ ],
+  "pageCount":  150
+  // ... diagnostics, auditedUrls, truncated, etc.
+}
+```
+
+The `schemaVersion` string carries a `YYYY-MM-vX.Y` tag (matching the `$id` of the published schema). **It bumps whenever the output shape changes** — breaking *or* additive. Gate scripts should assert the version they were written against (or accept a known range) so a shape change surfaces as a clear failure rather than silent misread.
+
+### `issues` is SEVERITY-bucketed (not a flat array, not category-keyed)
+
+This is the most common thing consumers get wrong:
+
+```jsonc
+"issues": {
+  "blockers":      [ /* RuleResult — severity error | critical */ ],
+  "shouldFix":     [ /* RuleResult — severity warning */ ],
+  "informational": [ /* RuleResult — severity info */ ]
+}
+```
+
+It is **not** `issues: RuleResult[]` and **not** `issues: { aeo: [...], spam: [...] }`. To get a single flat list for a gate:
+
+```ts
+const all = [...summary.issues.blockers, ...summary.issues.shouldFix, ...summary.issues.informational];
+const shouldFail = summary.issues.blockers.length > 0; // typical gate
+```
+
+`categories` (keyed by `integrity` | `discoverability` | `citation` | `data` | `audit`) carries **grades + counts only** — the per-category issue arrays live under `issues`, bucketed by severity, not under `categories`.
+
+### `truncated: true` means partial coverage
+
+When the crawl did not complete (e.g. the backpressure watchdog aborted on a degraded origin), the report sets `truncated: true` and a human-readable `truncatedReason`. The report still carries whatever findings were collected, but **CI gates MUST treat `pageCount`, `risk`, `verdict`, and all counts as LOWER bounds** — a "ready" verdict on a truncated run does not mean the site is clean, only that nothing was found before the abort. Gate on `truncated` explicitly if a partial pass should not count as a pass.
+
+### Validating in your own pipeline
+
+```ts
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import schema from "@pseolint/core/schemas/audit-summary.schema.json" with { type: "json" };
+
+const ajv = new Ajv2020({ strict: false });
+addFormats(ajv);
+const validate = ajv.compile(schema);
+
+const report = JSON.parse(stdout);           // pseolint --format json
+if (!validate(report)) throw new Error(ajv.errorsText(validate.errors));
+```
+
+The schema's `additionalProperties` is permissive, so it pins the contract consumers gate on without rejecting forward-compatible field additions.
+
 ### AI triage
 
 When `ai.enabled` is set, findings are clustered into root-causes by an LLM. Providers are loaded lazily from optional peer deps — install only the one you need:

package/dist/ai/tools/fetch-sitemap.js

@@ -77,7 +77,8 @@ export const fetchSitemapTool = defineTool({
         const urls = [];
         if (isSitemapIndex(rootXml) && maxDepth > 0) {
             const childUrls = extractLocs(rootXml);
-            childSitemaps.push(...childUrls);
+            for (const u of childUrls)
+                childSitemaps.push(u);
             for (const child of childUrls) {
                 if (urls.length >= maxUrls)
                     break;

package/dist/ai/tools/fetch-sitemap.js.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-sitemap.js","sourceRoot":"","sources":["../../../src/ai/tools/fetch-sitemap.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fetch-sitemap.js","sourceRoot":"","sources":["../../../src/ai/tools/fetch-sitemap.ts"],"names":[],"mappings":"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"}

package/dist/auditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auditor.d.ts","sourceRoot":"","sources":["../src/auditor.ts"],"names":[],"mappings":"AAmEA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAGZ,WAAW,EAUX,UAAU,EAIX,MAAM,YAAY,CAAC;AAQpB,OAAO,EAA8D,KAAK,kBAAkB,EAAiB,MAAM,sBAAsB,CAAC;AA+D1I,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEvE;AA6xBD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,UAAU,EAAE,EACtB,cAAc,EAAE,kBAAkB,GAAG,SAAS,GAC7C,UAAU,EAAE,CAed;AA6WD,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBjG;AAqhBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAimC/F"}
+{"version":3,"file":"auditor.d.ts","sourceRoot":"","sources":["../src/auditor.ts"],"names":[],"mappings":"AAmEA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAGZ,WAAW,EAUX,UAAU,EAIX,MAAM,YAAY,CAAC;AAQpB,OAAO,EAA8D,KAAK,kBAAkB,EAAiB,MAAM,sBAAsB,CAAC;AA+D1I,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEvE;AA6xBD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,UAAU,EAAE,EACtB,cAAc,EAAE,kBAAkB,GAAG,SAAS,GAC7C,UAAU,EAAE,CAed;AAoYD,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBjG;AAsoBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAirC/F"}