@sarimarcus/content-sites-core 0.32.1 → 0.32.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,9 @@
2
2
 
3
3
  All packages in the platform release in lockstep; entries are per release version.
4
4
 
5
+ ## 0.32.2 (2026-10-09)
6
+
7
+ - `./articles` adds the article-format shape table and rules (SLA-3037): `ARTICLE_FORMATS` (the eight format names as a tuple for `z.enum`), `ARTICLE_SHAPE_UNION` (the sections, FAQ and keyFacts ranges that cover every format and mode: 3-6, 0-12, 3), `FORMATS`, `LEGACY_SHAPE`, `shapeFor`, `checkFormat`, `checkCounts`, `checkKeyFactCount`, `checkWords`, `countBodyWords`, `validateShape` and `articleShapeIssues(article)`, which a site schema's `superRefine` uses. Without `editorialFormat` it reproduces the sites' current evergreen and discover count rules and wording exactly. Additive: nothing has to adopt it; adoption (the `editorialFormat` field and the shared count rules in each site's `src/content.config.ts`) is SLA-3038.
5
8
  ## 0.32.1 (2026-10-09)
6
9
 
7
10
  - No changes; lockstep release with ui (SLA-3025).
@@ -0,0 +1,50 @@
1
+ export type Range = readonly [number, number];
2
+ export type ArticleMode = 'evergreen' | 'discover';
3
+ export interface ShapeRanges {
4
+ sections: Range;
5
+ faqs: Range;
6
+ keyFacts: Range;
7
+ }
8
+ export interface FormatCard extends ShapeRanges {
9
+ words: Range;
10
+ modes: readonly ArticleMode[];
11
+ discoverShape?: ShapeRanges & {
12
+ words: Range;
13
+ };
14
+ }
15
+ export interface ArticleShape extends ShapeRanges {
16
+ format: string | null;
17
+ mode: ArticleMode;
18
+ words?: Range;
19
+ }
20
+ export interface ShapeIssue {
21
+ path: string;
22
+ message: string;
23
+ }
24
+ export declare const LEGACY_SHAPE: Record<ArticleMode, ShapeRanges>;
25
+ /** Format names as a tuple, usable in `z.enum`. FORMATS is typed against it, so tsc rejects a missing or extra key. */
26
+ export declare const ARTICLE_FORMATS: readonly ["direct-answer", "explainer", "narrative-profile", "claim-check", "roundup", "how-to", "comparison", "faq-hub"];
27
+ export type ArticleFormat = (typeof ARTICLE_FORMATS)[number];
28
+ export declare const FORMATS: Record<ArticleFormat, FormatCard>;
29
+ export declare const FORMAT_NAMES: string[];
30
+ /** Widest range of each counted field across every format and mode, for the site schemas' array bounds. */
31
+ export declare const ARTICLE_SHAPE_UNION: ShapeRanges;
32
+ /** Effective ranges for an article, or null when its editorialFormat is not a known format. */
33
+ export declare function shapeFor(article: unknown): ArticleShape | null;
34
+ /** Format name and mode compatibility. Empty for an article without editorialFormat. */
35
+ export declare function checkFormat(article: unknown): string[];
36
+ /** H2 and FAQ counts. Legacy wording is kept verbatim for articles without a format. */
37
+ export declare function checkCounts(article: unknown): string[];
38
+ /** keyFacts count; the caller decides whether an absent field is an error. */
39
+ export declare function checkKeyFactCount(article: unknown): string[];
40
+ export declare function countBodyWords(article: unknown): number;
41
+ /** Body word range, formatted articles only (legacy has no word gate). */
42
+ export declare function checkWords(article: unknown): string[];
43
+ /** Every shape issue for an article. Pure; never throws on malformed input. */
44
+ export declare function validateShape(article: unknown): string[];
45
+ /**
46
+ * Count and mode issues for a site schema's superRefine, with the field path for `ctx.addIssue`. Without
47
+ * `editorialFormat` it reproduces the legacy site rules and wording (the array max is the union max, so the
48
+ * evergreen FAQ ceiling is checked here). discoverAngle rules stay in the sites. Never throws.
49
+ */
50
+ export declare function articleShapeIssues(article: unknown): ShapeIssue[];
@@ -0,0 +1,168 @@
1
+ // Single shape table for article formats (SLA-3037), consumed by the site schemas and the factory gate.
2
+ // Catalogue: .claude/skills/article-craft/references/formats.md. An article without `editorialFormat` keeps the
3
+ // legacy shape (article-craft §1 / discover-mode.md). Pure: no Node APIs, it runs in the Astro build.
4
+ const DISCOVER = { sections: [3, 6], faqs: [0, 3], words: [700, 1600] };
5
+ const EXPLAINER = { sections: [4, 6], faqs: [5, 9], words: [1500, 2100] };
6
+ export const LEGACY_SHAPE = {
7
+ evergreen: { sections: EXPLAINER.sections, faqs: EXPLAINER.faqs, keyFacts: [3, 3] },
8
+ discover: { sections: DISCOVER.sections, faqs: DISCOVER.faqs, keyFacts: [3, 3] },
9
+ };
10
+ const card = (sections, faqs, words, discover) => ({
11
+ sections, faqs, keyFacts: [3, 3], words,
12
+ modes: discover ? ['evergreen', 'discover'] : ['evergreen'],
13
+ ...(discover ? { discoverShape: { ...DISCOVER, ...discover, keyFacts: [3, 3] } } : {}),
14
+ });
15
+ /** Format names as a tuple, usable in `z.enum`. FORMATS is typed against it, so tsc rejects a missing or extra key. */
16
+ export const ARTICLE_FORMATS = [
17
+ 'direct-answer', 'explainer', 'narrative-profile', 'claim-check', 'roundup', 'how-to', 'comparison', 'faq-hub',
18
+ ];
19
+ export const FORMATS = {
20
+ 'direct-answer': card([4, 5], [5, 9], [900, 1400]),
21
+ explainer: card(EXPLAINER.sections, EXPLAINER.faqs, EXPLAINER.words, {}),
22
+ 'narrative-profile': card([4, 6], [5, 9], [1500, 2100], {}),
23
+ 'claim-check': card([3, 5], [3, 9], [900, 1400], { sections: [3, 5], words: [700, 1400] }),
24
+ roundup: card([4, 6], [3, 9], [1500, 2100]),
25
+ 'how-to': card([4, 6], [5, 9], [1500, 2100]),
26
+ comparison: card([5, 6], [5, 9], [1500, 3000]),
27
+ 'faq-hub': card([4, 6], [5, 12], [1500, 2100]),
28
+ };
29
+ export const FORMAT_NAMES = [...ARTICLE_FORMATS];
30
+ const allShapes = () => [
31
+ ...Object.values(LEGACY_SHAPE),
32
+ ...Object.values(FORMATS).flatMap((c) => (c.discoverShape ? [c, c.discoverShape] : [c])),
33
+ ];
34
+ const span = (pick) => {
35
+ const ranges = allShapes().map(pick);
36
+ return [Math.min(...ranges.map((r) => r[0])), Math.max(...ranges.map((r) => r[1]))];
37
+ };
38
+ /** Widest range of each counted field across every format and mode, for the site schemas' array bounds. */
39
+ export const ARTICLE_SHAPE_UNION = {
40
+ sections: span((s) => s.sections),
41
+ faqs: span((s) => s.faqs),
42
+ keyFacts: span((s) => s.keyFacts),
43
+ };
44
+ const fmt = ([min, max]) => (min === max ? `${min}` : `${min}–${max}`);
45
+ const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
46
+ const isFormat = (value) => typeof value === 'string' && Object.hasOwn(FORMATS, value);
47
+ const modeOf = (article) => article?.editorialMode === 'discover' ? 'discover' : 'evergreen';
48
+ /** Effective ranges for an article, or null when its editorialFormat is not a known format. */
49
+ export function shapeFor(article) {
50
+ const record = isObject(article) ? article : null;
51
+ const mode = modeOf(record);
52
+ const name = record?.editorialFormat;
53
+ if (name === undefined)
54
+ return { format: null, mode, ...LEGACY_SHAPE[mode] };
55
+ if (!isFormat(name))
56
+ return null;
57
+ const format = FORMATS[name];
58
+ const base = mode === 'discover' && format.discoverShape ? format.discoverShape : format;
59
+ return { format: name, mode, sections: base.sections, faqs: base.faqs, keyFacts: base.keyFacts, words: base.words };
60
+ }
61
+ /** Format name and mode compatibility. Empty for an article without editorialFormat. */
62
+ export function checkFormat(article) {
63
+ if (!isObject(article))
64
+ return ['article: expected a JSON object'];
65
+ const name = article.editorialFormat;
66
+ if (name === undefined)
67
+ return [];
68
+ if (!isFormat(name)) {
69
+ return [`editorialFormat: unknown format ${JSON.stringify(name)} (expected one of: ${FORMAT_NAMES.join(', ')})`];
70
+ }
71
+ const card = FORMATS[name];
72
+ if (article.editorialMode === 'discover' && !card.modes.includes('discover')) {
73
+ return [`editorialMode: discover is not allowed with editorialFormat "${name}" (allowed modes: ${card.modes.join(', ')})`];
74
+ }
75
+ return [];
76
+ }
77
+ /** H2 and FAQ counts. Legacy wording is kept verbatim for articles without a format. */
78
+ export function checkCounts(article) {
79
+ if (!isObject(article))
80
+ return ['article: expected a JSON object'];
81
+ const shape = shapeFor(article);
82
+ if (!shape)
83
+ return [];
84
+ const sections = Array.isArray(article.sections) ? article.sections.length : -1;
85
+ const faqs = Array.isArray(article.faqs) ? article.faqs.length : -1;
86
+ const issues = [];
87
+ const via = shape.format ? ` for format ${shape.format}${shape.mode === 'discover' ? ' (discover)' : ''}` : '';
88
+ if (sections < shape.sections[0] || sections > shape.sections[1])
89
+ issues.push(`sections: expected ${fmt(shape.sections)} H2 sections${via}, got ${sections}`);
90
+ if (faqs < shape.faqs[0] || faqs > shape.faqs[1])
91
+ issues.push(`faqs: expected ${fmt(shape.faqs)}${via}, got ${faqs}`);
92
+ return issues;
93
+ }
94
+ /** keyFacts count; the caller decides whether an absent field is an error. */
95
+ export function checkKeyFactCount(article) {
96
+ if (!isObject(article) || !Array.isArray(article.keyFacts))
97
+ return [];
98
+ const shape = shapeFor(article) ?? { format: null, ...LEGACY_SHAPE[modeOf(article)] };
99
+ const [min, max] = shape.keyFacts;
100
+ const count = article.keyFacts.length;
101
+ if (count >= min && count <= max)
102
+ return [];
103
+ return [`keyFacts has ${count} entries (need ${min === max ? 'exactly ' : ''}${fmt(shape.keyFacts)}${shape.format ? ` for format ${shape.format}` : ''})`];
104
+ }
105
+ export function countBodyWords(article) {
106
+ const words = (value) => (typeof value === 'string' ? value : '').replace(/\[\^\d+\]/g, ' ').split(/\s+/).filter(Boolean).length;
107
+ const list = (value) => (Array.isArray(value) ? value.filter(isObject) : []);
108
+ let total = 0;
109
+ for (const section of list(isObject(article) ? article.sections : undefined)) {
110
+ total += words(section.body);
111
+ for (const sub of list(section.subsections))
112
+ total += words(sub.body);
113
+ }
114
+ return total;
115
+ }
116
+ /** Body word range, formatted articles only (legacy has no word gate). */
117
+ export function checkWords(article) {
118
+ if (!isObject(article))
119
+ return [];
120
+ const shape = shapeFor(article);
121
+ if (!shape?.words)
122
+ return [];
123
+ const count = countBodyWords(article);
124
+ if (count >= shape.words[0] && count <= shape.words[1])
125
+ return [];
126
+ return [`words: about ${count} body words, expected ${shape.words[0]}–${shape.words[1]} for format ${shape.format}${shape.mode === 'discover' ? ' (discover)' : ''}`];
127
+ }
128
+ /** Every shape issue for an article. Pure; never throws on malformed input. */
129
+ export function validateShape(article) {
130
+ return [...checkFormat(article), ...checkCounts(article), ...checkKeyFactCount(article), ...checkWords(article)];
131
+ }
132
+ /**
133
+ * Count and mode issues for a site schema's superRefine, with the field path for `ctx.addIssue`. Without
134
+ * `editorialFormat` it reproduces the legacy site rules and wording (the array max is the union max, so the
135
+ * evergreen FAQ ceiling is checked here). discoverAngle rules stay in the sites. Never throws.
136
+ */
137
+ export function articleShapeIssues(article) {
138
+ if (!isObject(article))
139
+ return [{ path: '', message: 'article: expected a JSON object' }];
140
+ const name = article.editorialFormat;
141
+ const sections = Array.isArray(article.sections) ? article.sections.length : -1;
142
+ const faqs = Array.isArray(article.faqs) ? article.faqs.length : -1;
143
+ const issues = [];
144
+ if (name === undefined) {
145
+ const mode = modeOf(article);
146
+ const legacy = LEGACY_SHAPE[mode];
147
+ if (mode === 'discover') {
148
+ if (faqs > legacy.faqs[1])
149
+ issues.push({ path: 'faqs', message: `Discover articles allow ${fmt(legacy.faqs)} FAQs` });
150
+ }
151
+ else {
152
+ if (sections < legacy.sections[0])
153
+ issues.push({ path: 'sections', message: `Evergreen articles need ${fmt(legacy.sections)} sections` });
154
+ if (faqs < legacy.faqs[0] || faqs > legacy.faqs[1])
155
+ issues.push({ path: 'faqs', message: `Evergreen articles need ${fmt(legacy.faqs)} FAQs` });
156
+ }
157
+ return issues;
158
+ }
159
+ for (const message of checkFormat(article)) {
160
+ issues.push({ path: message.startsWith('editorialMode') ? 'editorialMode' : 'editorialFormat', message });
161
+ }
162
+ if (!isFormat(name))
163
+ return issues;
164
+ for (const message of checkCounts(article)) {
165
+ issues.push({ path: message.startsWith('sections') ? 'sections' : 'faqs', message });
166
+ }
167
+ return issues;
168
+ }
@@ -1,2 +1,4 @@
1
1
  export { selectFeaturedArticles, FEATURED_SHELF_SIZE, FEATURED_MAX_AGE_DAYS } from './featured.ts';
2
2
  export type { FeaturedSnapshot, FeaturedSelection } from './featured.ts';
3
+ export { ARTICLE_FORMATS, ARTICLE_SHAPE_UNION, FORMATS, FORMAT_NAMES, LEGACY_SHAPE, shapeFor, checkFormat, checkCounts, checkKeyFactCount, checkWords, countBodyWords, validateShape, articleShapeIssues, } from './formats.ts';
4
+ export type { ArticleFormat, ArticleMode, ArticleShape, FormatCard, Range, ShapeIssue, ShapeRanges } from './formats.ts';
@@ -1,2 +1,3 @@
1
1
  // Public surface of @sarimarcus/content-sites-core/articles.
2
2
  export { selectFeaturedArticles, FEATURED_SHELF_SIZE, FEATURED_MAX_AGE_DAYS } from "./featured.js";
3
+ export { ARTICLE_FORMATS, ARTICLE_SHAPE_UNION, FORMATS, FORMAT_NAMES, LEGACY_SHAPE, shapeFor, checkFormat, checkCounts, checkKeyFactCount, checkWords, countBodyWords, validateShape, articleShapeIssues, } from "./formats.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sarimarcus/content-sites-core",
3
- "version": "0.32.1",
3
+ "version": "0.32.2",
4
4
  "description": "Non-visual utilities, Astro config builders and SEO schema assembly shared by the content sites.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -0,0 +1,201 @@
1
+ // Single shape table for article formats (SLA-3037), consumed by the site schemas and the factory gate.
2
+ // Catalogue: .claude/skills/article-craft/references/formats.md. An article without `editorialFormat` keeps the
3
+ // legacy shape (article-craft §1 / discover-mode.md). Pure: no Node APIs, it runs in the Astro build.
4
+
5
+ export type Range = readonly [number, number];
6
+ export type ArticleMode = 'evergreen' | 'discover';
7
+
8
+ export interface ShapeRanges {
9
+ sections: Range;
10
+ faqs: Range;
11
+ keyFacts: Range;
12
+ }
13
+
14
+ export interface FormatCard extends ShapeRanges {
15
+ words: Range;
16
+ modes: readonly ArticleMode[];
17
+ discoverShape?: ShapeRanges & { words: Range };
18
+ }
19
+
20
+ export interface ArticleShape extends ShapeRanges {
21
+ format: string | null;
22
+ mode: ArticleMode;
23
+ words?: Range;
24
+ }
25
+
26
+ export interface ShapeIssue {
27
+ path: string;
28
+ message: string;
29
+ }
30
+
31
+ const DISCOVER = { sections: [3, 6], faqs: [0, 3], words: [700, 1600] } as const satisfies { sections: Range; faqs: Range; words: Range };
32
+ const EXPLAINER = { sections: [4, 6], faqs: [5, 9], words: [1500, 2100] } as const satisfies { sections: Range; faqs: Range; words: Range };
33
+
34
+ export const LEGACY_SHAPE: Record<ArticleMode, ShapeRanges> = {
35
+ evergreen: { sections: EXPLAINER.sections, faqs: EXPLAINER.faqs, keyFacts: [3, 3] },
36
+ discover: { sections: DISCOVER.sections, faqs: DISCOVER.faqs, keyFacts: [3, 3] },
37
+ };
38
+
39
+ const card = (
40
+ sections: Range,
41
+ faqs: Range,
42
+ words: Range,
43
+ discover?: { sections?: Range; faqs?: Range; words?: Range },
44
+ ): FormatCard => ({
45
+ sections, faqs, keyFacts: [3, 3], words,
46
+ modes: discover ? ['evergreen', 'discover'] : ['evergreen'],
47
+ ...(discover ? { discoverShape: { ...DISCOVER, ...discover, keyFacts: [3, 3] as Range } } : {}),
48
+ });
49
+
50
+ /** Format names as a tuple, usable in `z.enum`. FORMATS is typed against it, so tsc rejects a missing or extra key. */
51
+ export const ARTICLE_FORMATS = [
52
+ 'direct-answer', 'explainer', 'narrative-profile', 'claim-check', 'roundup', 'how-to', 'comparison', 'faq-hub',
53
+ ] as const;
54
+
55
+ export type ArticleFormat = (typeof ARTICLE_FORMATS)[number];
56
+
57
+ export const FORMATS: Record<ArticleFormat, FormatCard> = {
58
+ 'direct-answer': card([4, 5], [5, 9], [900, 1400]),
59
+ explainer: card(EXPLAINER.sections, EXPLAINER.faqs, EXPLAINER.words, {}),
60
+ 'narrative-profile': card([4, 6], [5, 9], [1500, 2100], {}),
61
+ 'claim-check': card([3, 5], [3, 9], [900, 1400], { sections: [3, 5], words: [700, 1400] }),
62
+ roundup: card([4, 6], [3, 9], [1500, 2100]),
63
+ 'how-to': card([4, 6], [5, 9], [1500, 2100]),
64
+ comparison: card([5, 6], [5, 9], [1500, 3000]),
65
+ 'faq-hub': card([4, 6], [5, 12], [1500, 2100]),
66
+ };
67
+
68
+ export const FORMAT_NAMES: string[] = [...ARTICLE_FORMATS];
69
+
70
+ const allShapes = (): ShapeRanges[] => [
71
+ ...Object.values(LEGACY_SHAPE),
72
+ ...Object.values(FORMATS).flatMap((c) => (c.discoverShape ? [c, c.discoverShape] : [c])),
73
+ ];
74
+ const span = (pick: (shape: ShapeRanges) => Range): Range => {
75
+ const ranges = allShapes().map(pick);
76
+ return [Math.min(...ranges.map((r) => r[0])), Math.max(...ranges.map((r) => r[1]))];
77
+ };
78
+
79
+ /** Widest range of each counted field across every format and mode, for the site schemas' array bounds. */
80
+ export const ARTICLE_SHAPE_UNION: ShapeRanges = {
81
+ sections: span((s) => s.sections),
82
+ faqs: span((s) => s.faqs),
83
+ keyFacts: span((s) => s.keyFacts),
84
+ };
85
+
86
+ const fmt = ([min, max]: Range): string => (min === max ? `${min}` : `${min}–${max}`);
87
+ const isObject = (value: unknown): value is Record<string, unknown> =>
88
+ value !== null && typeof value === 'object' && !Array.isArray(value);
89
+ const isFormat = (value: unknown): value is ArticleFormat => typeof value === 'string' && Object.hasOwn(FORMATS, value);
90
+ const modeOf = (article: Record<string, unknown> | null | undefined): ArticleMode =>
91
+ article?.editorialMode === 'discover' ? 'discover' : 'evergreen';
92
+
93
+ /** Effective ranges for an article, or null when its editorialFormat is not a known format. */
94
+ export function shapeFor(article: unknown): ArticleShape | null {
95
+ const record = isObject(article) ? article : null;
96
+ const mode = modeOf(record);
97
+ const name = record?.editorialFormat;
98
+ if (name === undefined) return { format: null, mode, ...LEGACY_SHAPE[mode] };
99
+ if (!isFormat(name)) return null;
100
+ const format = FORMATS[name]!;
101
+ const base = mode === 'discover' && format.discoverShape ? format.discoverShape : format;
102
+ return { format: name, mode, sections: base.sections, faqs: base.faqs, keyFacts: base.keyFacts, words: base.words };
103
+ }
104
+
105
+ /** Format name and mode compatibility. Empty for an article without editorialFormat. */
106
+ export function checkFormat(article: unknown): string[] {
107
+ if (!isObject(article)) return ['article: expected a JSON object'];
108
+ const name = article.editorialFormat;
109
+ if (name === undefined) return [];
110
+ if (!isFormat(name)) {
111
+ return [`editorialFormat: unknown format ${JSON.stringify(name)} (expected one of: ${FORMAT_NAMES.join(', ')})`];
112
+ }
113
+ const card = FORMATS[name]!;
114
+ if (article.editorialMode === 'discover' && !card.modes.includes('discover')) {
115
+ return [`editorialMode: discover is not allowed with editorialFormat "${name}" (allowed modes: ${card.modes.join(', ')})`];
116
+ }
117
+ return [];
118
+ }
119
+
120
+ /** H2 and FAQ counts. Legacy wording is kept verbatim for articles without a format. */
121
+ export function checkCounts(article: unknown): string[] {
122
+ if (!isObject(article)) return ['article: expected a JSON object'];
123
+ const shape = shapeFor(article);
124
+ if (!shape) return [];
125
+ const sections = Array.isArray(article.sections) ? article.sections.length : -1;
126
+ const faqs = Array.isArray(article.faqs) ? article.faqs.length : -1;
127
+ const issues: string[] = [];
128
+ const via = shape.format ? ` for format ${shape.format}${shape.mode === 'discover' ? ' (discover)' : ''}` : '';
129
+ if (sections < shape.sections[0] || sections > shape.sections[1]) issues.push(`sections: expected ${fmt(shape.sections)} H2 sections${via}, got ${sections}`);
130
+ if (faqs < shape.faqs[0] || faqs > shape.faqs[1]) issues.push(`faqs: expected ${fmt(shape.faqs)}${via}, got ${faqs}`);
131
+ return issues;
132
+ }
133
+
134
+ /** keyFacts count; the caller decides whether an absent field is an error. */
135
+ export function checkKeyFactCount(article: unknown): string[] {
136
+ if (!isObject(article) || !Array.isArray(article.keyFacts)) return [];
137
+ const shape = shapeFor(article) ?? { format: null, ...LEGACY_SHAPE[modeOf(article)] };
138
+ const [min, max] = shape.keyFacts;
139
+ const count = article.keyFacts.length;
140
+ if (count >= min && count <= max) return [];
141
+ return [`keyFacts has ${count} entries (need ${min === max ? 'exactly ' : ''}${fmt(shape.keyFacts)}${shape.format ? ` for format ${shape.format}` : ''})`];
142
+ }
143
+
144
+ export function countBodyWords(article: unknown): number {
145
+ const words = (value: unknown): number =>
146
+ (typeof value === 'string' ? value : '').replace(/\[\^\d+\]/g, ' ').split(/\s+/).filter(Boolean).length;
147
+ const list = (value: unknown): Record<string, unknown>[] => (Array.isArray(value) ? value.filter(isObject) : []);
148
+ let total = 0;
149
+ for (const section of list(isObject(article) ? article.sections : undefined)) {
150
+ total += words(section.body);
151
+ for (const sub of list(section.subsections)) total += words(sub.body);
152
+ }
153
+ return total;
154
+ }
155
+
156
+ /** Body word range, formatted articles only (legacy has no word gate). */
157
+ export function checkWords(article: unknown): string[] {
158
+ if (!isObject(article)) return [];
159
+ const shape = shapeFor(article);
160
+ if (!shape?.words) return [];
161
+ const count = countBodyWords(article);
162
+ if (count >= shape.words[0] && count <= shape.words[1]) return [];
163
+ return [`words: about ${count} body words, expected ${shape.words[0]}–${shape.words[1]} for format ${shape.format}${shape.mode === 'discover' ? ' (discover)' : ''}`];
164
+ }
165
+
166
+ /** Every shape issue for an article. Pure; never throws on malformed input. */
167
+ export function validateShape(article: unknown): string[] {
168
+ return [...checkFormat(article), ...checkCounts(article), ...checkKeyFactCount(article), ...checkWords(article)];
169
+ }
170
+
171
+ /**
172
+ * Count and mode issues for a site schema's superRefine, with the field path for `ctx.addIssue`. Without
173
+ * `editorialFormat` it reproduces the legacy site rules and wording (the array max is the union max, so the
174
+ * evergreen FAQ ceiling is checked here). discoverAngle rules stay in the sites. Never throws.
175
+ */
176
+ export function articleShapeIssues(article: unknown): ShapeIssue[] {
177
+ if (!isObject(article)) return [{ path: '', message: 'article: expected a JSON object' }];
178
+ const name = article.editorialFormat;
179
+ const sections = Array.isArray(article.sections) ? article.sections.length : -1;
180
+ const faqs = Array.isArray(article.faqs) ? article.faqs.length : -1;
181
+ const issues: ShapeIssue[] = [];
182
+ if (name === undefined) {
183
+ const mode = modeOf(article);
184
+ const legacy = LEGACY_SHAPE[mode];
185
+ if (mode === 'discover') {
186
+ if (faqs > legacy.faqs[1]) issues.push({ path: 'faqs', message: `Discover articles allow ${fmt(legacy.faqs)} FAQs` });
187
+ } else {
188
+ if (sections < legacy.sections[0]) issues.push({ path: 'sections', message: `Evergreen articles need ${fmt(legacy.sections)} sections` });
189
+ if (faqs < legacy.faqs[0] || faqs > legacy.faqs[1]) issues.push({ path: 'faqs', message: `Evergreen articles need ${fmt(legacy.faqs)} FAQs` });
190
+ }
191
+ return issues;
192
+ }
193
+ for (const message of checkFormat(article)) {
194
+ issues.push({ path: message.startsWith('editorialMode') ? 'editorialMode' : 'editorialFormat', message });
195
+ }
196
+ if (!isFormat(name)) return issues;
197
+ for (const message of checkCounts(article)) {
198
+ issues.push({ path: message.startsWith('sections') ? 'sections' : 'faqs', message });
199
+ }
200
+ return issues;
201
+ }
@@ -1,3 +1,8 @@
1
1
  // Public surface of @sarimarcus/content-sites-core/articles.
2
2
  export { selectFeaturedArticles, FEATURED_SHELF_SIZE, FEATURED_MAX_AGE_DAYS } from './featured.ts';
3
3
  export type { FeaturedSnapshot, FeaturedSelection } from './featured.ts';
4
+ export {
5
+ ARTICLE_FORMATS, ARTICLE_SHAPE_UNION, FORMATS, FORMAT_NAMES, LEGACY_SHAPE,
6
+ shapeFor, checkFormat, checkCounts, checkKeyFactCount, checkWords, countBodyWords, validateShape, articleShapeIssues,
7
+ } from './formats.ts';
8
+ export type { ArticleFormat, ArticleMode, ArticleShape, FormatCard, Range, ShapeIssue, ShapeRanges } from './formats.ts';