@ankhorage/rules-design 0.4.0 → 0.6.0
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 +12 -0
- package/README.md +2 -1
- package/dist/features/recognition/recognizeWebsiteDesignProperties.d.ts +4 -0
- package/dist/features/recognition/recognizeWebsiteDesignProperties.js +191 -0
- package/dist/features/recognition/tokenCandidates.d.ts +3 -0
- package/dist/features/recognition/tokenCandidates.js +77 -0
- package/dist/features/website-assessment/assessContactAddressMarkup.d.ts +3 -0
- package/dist/features/website-assessment/assessContactAddressMarkup.js +46 -0
- package/dist/features/website-assessment/assessCopyrightNotice.d.ts +3 -0
- package/dist/features/website-assessment/assessCopyrightNotice.js +33 -0
- package/dist/features/website-assessment/assessDuplicateMediaUse.d.ts +3 -0
- package/dist/features/website-assessment/assessDuplicateMediaUse.js +55 -0
- package/dist/features/website-assessment/assessLegalNotice.d.ts +3 -0
- package/dist/features/website-assessment/assessLegalNotice.js +44 -0
- package/dist/features/website-assessment/assessPrivacyNotice.d.ts +3 -0
- package/dist/features/website-assessment/assessPrivacyNotice.js +58 -0
- package/dist/features/website-assessment/assessTrackingConsent.d.ts +3 -0
- package/dist/features/website-assessment/assessTrackingConsent.js +63 -0
- package/dist/features/website-assessment/createWebsiteAssessmentRuleSet.d.ts +4 -0
- package/dist/features/website-assessment/createWebsiteAssessmentRuleSet.js +68 -0
- package/dist/features/website-assessment/isWebsiteAssessmentNonNull.d.ts +2 -0
- package/dist/features/website-assessment/isWebsiteAssessmentNonNull.js +5 -0
- package/dist/features/website-assessment/websiteAssessmentDefinitions.d.ts +3 -0
- package/dist/features/website-assessment/websiteAssessmentDefinitions.js +26 -0
- package/dist/features/website-assessment/websiteAssessmentResult.d.ts +3 -0
- package/dist/features/website-assessment/websiteAssessmentResult.js +21 -0
- package/dist/features/website-assessment/websiteAssessmentTestSupport.d.ts +13 -0
- package/dist/features/website-assessment/websiteAssessmentTestSupport.js +53 -0
- package/dist/features/website-assessment/websiteAssessmentValues.d.ts +7 -0
- package/dist/features/website-assessment/websiteAssessmentValues.js +17 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +2 -0
- package/dist/types/websiteAssessment.d.ts +35 -0
- package/dist/types/websiteAssessment.js +0 -0
- package/dist/types/websiteDesignRecognition.d.ts +54 -0
- package/dist/types/websiteDesignRecognition.js +0 -0
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.6.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 34695ae: Add factual website design-property recognition with retained provenance and unresolved evidence.
|
|
8
|
+
|
|
9
|
+
## 0.5.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- 9dab376: Add composable website, contact, privacy, tracking, and media assessment rules.
|
|
14
|
+
|
|
3
15
|
## 0.4.0
|
|
4
16
|
|
|
5
17
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
# @ankhorage/rules-design
|
|
5
5
|
|
|
6
|
-
         
|
|
7
7
|
|
|
8
8
|
Declarative catalog for reusable design rules.
|
|
9
9
|
|
|
@@ -37,4 +37,5 @@ import { createRuleRegistry, evaluateRules } from '@ankhorage/rules';
|
|
|
37
37
|
- [Architecture overview](././paradox/diagrams/architecture-overview.mmd)
|
|
38
38
|
- [Module relationships](././paradox/diagrams/module-relationships.mmd)
|
|
39
39
|
- [Export graph](././paradox/diagrams/export-graph.mmd)
|
|
40
|
+
- [recognizeWebsiteDesignProperties sequence](././paradox/diagrams/sequences/recognize-website-design-properties.mmd)
|
|
40
41
|
- [selectDesignRuleProfile sequence](././paradox/diagrams/sequences/select-design-rule-profile.mmd)
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { WebsiteObservationDocument } from '@ankhorage/contracts/website';
|
|
2
|
+
import type { WebsiteDesignRecognition } from '../../types/websiteDesignRecognition';
|
|
3
|
+
/*** Recognizes exact design properties from validated website observations without evaluating them. */
|
|
4
|
+
export declare function recognizeWebsiteDesignProperties(document: WebsiteObservationDocument): WebsiteDesignRecognition;
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
import { tokenCandidates } from './tokenCandidates';
|
|
3
|
+
/*** Recognizes exact design properties from validated website observations without evaluating them. */
|
|
4
|
+
export function recognizeWebsiteDesignProperties(document) {
|
|
5
|
+
const nodes = document.pages.flatMap((page) => page.nodes.map((node) => recognizeNode(page.id, node)));
|
|
6
|
+
return { nodes, tokenCandidates: tokenCandidates(nodes) };
|
|
7
|
+
}
|
|
8
|
+
const colorProperties = ['color', 'backgroundColor', 'borderColor', 'opacity'];
|
|
9
|
+
const typographyProperties = [
|
|
10
|
+
'fontFamily',
|
|
11
|
+
'fontSize',
|
|
12
|
+
'fontStyle',
|
|
13
|
+
'fontWeight',
|
|
14
|
+
'letterSpacing',
|
|
15
|
+
'lineHeight',
|
|
16
|
+
'textAlign',
|
|
17
|
+
'textDecoration',
|
|
18
|
+
];
|
|
19
|
+
const layoutProperties = [
|
|
20
|
+
'display',
|
|
21
|
+
'position',
|
|
22
|
+
'visibility',
|
|
23
|
+
'borderRadius',
|
|
24
|
+
'borderWidth',
|
|
25
|
+
'boxShadow',
|
|
26
|
+
'margin',
|
|
27
|
+
'padding',
|
|
28
|
+
'alignContent',
|
|
29
|
+
'alignItems',
|
|
30
|
+
'alignSelf',
|
|
31
|
+
'gap',
|
|
32
|
+
'flexDirection',
|
|
33
|
+
'flexBasis',
|
|
34
|
+
'flexGrow',
|
|
35
|
+
'flexShrink',
|
|
36
|
+
'flexWrap',
|
|
37
|
+
'justifyContent',
|
|
38
|
+
'justifyItems',
|
|
39
|
+
'justifySelf',
|
|
40
|
+
'order',
|
|
41
|
+
'placeContent',
|
|
42
|
+
'placeItems',
|
|
43
|
+
'placeSelf',
|
|
44
|
+
'gridAutoColumns',
|
|
45
|
+
'gridAutoFlow',
|
|
46
|
+
'gridAutoRows',
|
|
47
|
+
'gridColumn',
|
|
48
|
+
'gridColumnEnd',
|
|
49
|
+
'gridColumnStart',
|
|
50
|
+
'gridRow',
|
|
51
|
+
'gridRowEnd',
|
|
52
|
+
'gridRowStart',
|
|
53
|
+
'gridTemplateColumns',
|
|
54
|
+
'gridTemplateRows',
|
|
55
|
+
'overflow',
|
|
56
|
+
'overflowX',
|
|
57
|
+
'overflowY',
|
|
58
|
+
'backgroundImage',
|
|
59
|
+
'backgroundPosition',
|
|
60
|
+
'backgroundRepeat',
|
|
61
|
+
'backgroundSize',
|
|
62
|
+
];
|
|
63
|
+
/*** Retains every available node style and safe semantic observation at its source identity. */
|
|
64
|
+
function recognizeNode(pageId, node) {
|
|
65
|
+
return {
|
|
66
|
+
sourceRef: node.sourceRef,
|
|
67
|
+
pageId,
|
|
68
|
+
colors: cssObservations(pageId, node, colorProperties),
|
|
69
|
+
typography: cssObservations(pageId, node, typographyProperties),
|
|
70
|
+
layout: cssObservations(pageId, node, layoutProperties),
|
|
71
|
+
responsive: responsiveObservations(pageId, node),
|
|
72
|
+
accessibility: accessibilityObservations(pageId, node),
|
|
73
|
+
media: node.media,
|
|
74
|
+
unresolved: unresolvedObservations(pageId, node),
|
|
75
|
+
};
|
|
76
|
+
}
|
|
77
|
+
/*** Projects exact available computed CSS values while retaining viewport, state, and provenance. */
|
|
78
|
+
function cssObservations(pageId, node, properties) {
|
|
79
|
+
return node.observations.flatMap((observation) => {
|
|
80
|
+
const { css } = observation;
|
|
81
|
+
return observation.availability.status === 'available' && css !== null
|
|
82
|
+
? properties.map((name) => cssObservation(pageId, node.sourceRef, observation, css, name))
|
|
83
|
+
: [];
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
/*** Creates one source-linked computed CSS observation without normalizing its original literal. */
|
|
87
|
+
function cssObservation(pageId, sourceRef, observation, css, name) {
|
|
88
|
+
return {
|
|
89
|
+
name,
|
|
90
|
+
value: cssValue(cssPropertyValue(css, name)),
|
|
91
|
+
viewportId: observation.viewportId,
|
|
92
|
+
stateId: observation.stateId,
|
|
93
|
+
sourceRef,
|
|
94
|
+
pageId,
|
|
95
|
+
provenance: observation.provenance,
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
/*** Reads a named computed CSS field without indexing an untrusted external object. */
|
|
99
|
+
function cssPropertyValue(css, name) {
|
|
100
|
+
const value = Object.entries(isRecord(css) ? css : {}).find(([property]) => property === name)?.[1];
|
|
101
|
+
if (value === undefined)
|
|
102
|
+
throw new TypeError(`Unknown computed CSS property: ${name}`);
|
|
103
|
+
return value;
|
|
104
|
+
}
|
|
105
|
+
/*** Converts the one structured CSS box value into a portable serializable value. */
|
|
106
|
+
function cssValue(value) {
|
|
107
|
+
if (typeof value === 'string')
|
|
108
|
+
return value;
|
|
109
|
+
if (isRecord(value) &&
|
|
110
|
+
typeof value.bottom === 'string' &&
|
|
111
|
+
typeof value.left === 'string' &&
|
|
112
|
+
typeof value.right === 'string' &&
|
|
113
|
+
typeof value.top === 'string')
|
|
114
|
+
return { bottom: value.bottom, left: value.left, right: value.right, top: value.top };
|
|
115
|
+
throw new TypeError('Computed CSS values must be strings or complete box edges.');
|
|
116
|
+
}
|
|
117
|
+
/*** Retains responsive geometry and CSS state samples without inventing source-authored breakpoints. */
|
|
118
|
+
function responsiveObservations(pageId, node) {
|
|
119
|
+
return node.observations.map((observation) => ({
|
|
120
|
+
name: 'observation',
|
|
121
|
+
value: {
|
|
122
|
+
availability: observation.availability.status,
|
|
123
|
+
rect: observation.rect === null
|
|
124
|
+
? null
|
|
125
|
+
: {
|
|
126
|
+
height: observation.rect.height,
|
|
127
|
+
width: observation.rect.width,
|
|
128
|
+
x: observation.rect.x,
|
|
129
|
+
y: observation.rect.y,
|
|
130
|
+
},
|
|
131
|
+
},
|
|
132
|
+
viewportId: observation.viewportId,
|
|
133
|
+
stateId: observation.stateId,
|
|
134
|
+
sourceRef: node.sourceRef,
|
|
135
|
+
pageId,
|
|
136
|
+
provenance: observation.provenance,
|
|
137
|
+
}));
|
|
138
|
+
}
|
|
139
|
+
/*** Retains semantic and accessible-name evidence without producing accessibility conclusions. */
|
|
140
|
+
function accessibilityObservations(pageId, node) {
|
|
141
|
+
const { sourceRef } = node;
|
|
142
|
+
const semantic = {
|
|
143
|
+
attributes: node.dom.attributes,
|
|
144
|
+
links: node.links.map((link) => ({
|
|
145
|
+
label: link.label,
|
|
146
|
+
sourceRef: link.sourceRef,
|
|
147
|
+
url: link.url,
|
|
148
|
+
})),
|
|
149
|
+
tagName: node.dom.tagName,
|
|
150
|
+
textRuns: node.textRuns.map((textRun) => ({
|
|
151
|
+
end: textRun.end,
|
|
152
|
+
sourceRef: textRun.sourceRef,
|
|
153
|
+
start: textRun.start,
|
|
154
|
+
text: textRun.text,
|
|
155
|
+
})),
|
|
156
|
+
};
|
|
157
|
+
return node.observations.map((observation) => ({
|
|
158
|
+
name: 'semantics',
|
|
159
|
+
value: semantic,
|
|
160
|
+
viewportId: observation.viewportId,
|
|
161
|
+
stateId: observation.stateId,
|
|
162
|
+
sourceRef,
|
|
163
|
+
pageId,
|
|
164
|
+
provenance: observation.provenance,
|
|
165
|
+
}));
|
|
166
|
+
}
|
|
167
|
+
/*** Records unavailable CSS or geometry samples with their producer-supplied missing reason. */
|
|
168
|
+
function unresolvedObservations(pageId, node) {
|
|
169
|
+
return node.observations.flatMap((observation) => {
|
|
170
|
+
const { availability } = observation;
|
|
171
|
+
if (availability.status !== 'missing' || availability.missing === null)
|
|
172
|
+
return [];
|
|
173
|
+
const { missing } = availability;
|
|
174
|
+
return unresolvedObservationKinds(observation).map((kind) => ({
|
|
175
|
+
kind,
|
|
176
|
+
missing,
|
|
177
|
+
provenance: observation.provenance,
|
|
178
|
+
sourceRef: node.sourceRef,
|
|
179
|
+
pageId,
|
|
180
|
+
stateId: observation.stateId,
|
|
181
|
+
viewportId: observation.viewportId,
|
|
182
|
+
}));
|
|
183
|
+
});
|
|
184
|
+
}
|
|
185
|
+
/*** Distinguishes each unavailable evidence channel without pretending it was observed. */
|
|
186
|
+
function unresolvedObservationKinds(observation) {
|
|
187
|
+
return [
|
|
188
|
+
...(observation.css === null ? ['computed-css'] : []),
|
|
189
|
+
...(observation.rect === null ? ['geometry'] : []),
|
|
190
|
+
];
|
|
191
|
+
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { WebsiteDesignNodeRecognition, WebsiteDesignTokenCandidate } from '../../types/websiteDesignRecognition';
|
|
2
|
+
/*** Finds repeated exact design literals and records them as role-free reusable token candidates. */
|
|
3
|
+
export declare function tokenCandidates(nodes: readonly WebsiteDesignNodeRecognition[]): readonly WebsiteDesignTokenCandidate[];
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
const tokenKinds = ['color', 'radius', 'shadow', 'spacing', 'typography'];
|
|
3
|
+
/*** Finds repeated exact design literals and records them as role-free reusable token candidates. */
|
|
4
|
+
export function tokenCandidates(nodes) {
|
|
5
|
+
return tokenKinds.flatMap((kind) => candidatesForKind(nodes, kind));
|
|
6
|
+
}
|
|
7
|
+
/*** Extracts deterministic repeated candidates for one design-token family. */
|
|
8
|
+
function candidatesForKind(nodes, kind) {
|
|
9
|
+
const observations = nodes.flatMap((node) => tokenObservationsForKind(node, kind));
|
|
10
|
+
return [
|
|
11
|
+
...Map.groupBy(observations, (observation) => `${observation.property}\u0000${observation.value}`).entries(),
|
|
12
|
+
]
|
|
13
|
+
.filter(([, values]) => sourceReferences(values).length > 1)
|
|
14
|
+
.map(([, values]) => ({
|
|
15
|
+
kind,
|
|
16
|
+
property: values[0].property,
|
|
17
|
+
value: values[0].value,
|
|
18
|
+
originalValues: [...new Set(values.map((item) => item.value))],
|
|
19
|
+
sourceRefs: sourceReferences(values),
|
|
20
|
+
confidence: sourceReferences(values).length / sourceReferences(observations).length,
|
|
21
|
+
inferredRole: null,
|
|
22
|
+
}))
|
|
23
|
+
.toSorted((left, right) => left.property.localeCompare(right.property) || left.value.localeCompare(right.value));
|
|
24
|
+
}
|
|
25
|
+
/*** Extracts deterministic page-qualified source identities so viewport samples do not fabricate repetition. */
|
|
26
|
+
function sourceReferences(observations) {
|
|
27
|
+
return [
|
|
28
|
+
...new Map(observations.map((observation) => [
|
|
29
|
+
sourceReferenceKey(observation),
|
|
30
|
+
{ pageId: observation.pageId, sourceRef: observation.sourceRef },
|
|
31
|
+
])).values(),
|
|
32
|
+
].toSorted((left, right) => sourceReferenceKey(left).localeCompare(sourceReferenceKey(right)));
|
|
33
|
+
}
|
|
34
|
+
/*** Serializes the two-part observed-node identity only for deterministic deduplication and ordering. */
|
|
35
|
+
function sourceReferenceKey(reference) {
|
|
36
|
+
return `${reference.pageId}\u0000${reference.sourceRef}`;
|
|
37
|
+
}
|
|
38
|
+
/*** Selects only the observations that belong to one factual token family. */
|
|
39
|
+
function tokenObservationsForKind(node, kind) {
|
|
40
|
+
return observationsForKind(node, kind).flatMap((observation) => tokenObservations(observation, kind));
|
|
41
|
+
}
|
|
42
|
+
/*** Retains each exact scalar or spacing-edge literal with its CSS-property ownership. */
|
|
43
|
+
function tokenObservations(observation, kind) {
|
|
44
|
+
if (typeof observation.value === 'string') {
|
|
45
|
+
return [
|
|
46
|
+
{ ...sourceReference(observation), property: observation.name, value: observation.value },
|
|
47
|
+
];
|
|
48
|
+
}
|
|
49
|
+
return kind === 'spacing' ? spacingEdgeTokenObservations(observation) : [];
|
|
50
|
+
}
|
|
51
|
+
/*** Expands a structured margin or padding value into its exact physical-edge token evidence. */
|
|
52
|
+
function spacingEdgeTokenObservations(observation) {
|
|
53
|
+
return isRecord(observation.value)
|
|
54
|
+
? Object.entries(observation.value).flatMap(([edge, value]) => typeof value === 'string' && ['top', 'right', 'bottom', 'left'].includes(edge)
|
|
55
|
+
? [{ ...sourceReference(observation), property: `${observation.name}.${edge}`, value }]
|
|
56
|
+
: [])
|
|
57
|
+
: [];
|
|
58
|
+
}
|
|
59
|
+
/*** Extracts the reusable page-qualified source identity from one design property observation. */
|
|
60
|
+
function sourceReference(observation) {
|
|
61
|
+
return { pageId: observation.pageId, sourceRef: observation.sourceRef };
|
|
62
|
+
}
|
|
63
|
+
/*** Selects only the property observations that belong to one factual token family. */
|
|
64
|
+
function observationsForKind(node, kind) {
|
|
65
|
+
switch (kind) {
|
|
66
|
+
case 'color':
|
|
67
|
+
return node.colors.filter((observation) => observation.name !== 'opacity');
|
|
68
|
+
case 'radius':
|
|
69
|
+
return node.layout.filter((observation) => observation.name === 'borderRadius');
|
|
70
|
+
case 'shadow':
|
|
71
|
+
return node.layout.filter((observation) => observation.name === 'boxShadow');
|
|
72
|
+
case 'spacing':
|
|
73
|
+
return node.layout.filter((observation) => ['gap', 'margin', 'padding'].includes(observation.name));
|
|
74
|
+
case 'typography':
|
|
75
|
+
return node.typography;
|
|
76
|
+
}
|
|
77
|
+
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { AssessmentFact, AssessmentResult } from '../../types/websiteAssessment';
|
|
2
|
+
/*** Assesses semantic contact placement and normalized contact-link matching. */
|
|
3
|
+
export declare function assessContactAddressMarkup(facts: readonly AssessmentFact[]): AssessmentResult;
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
import { validatedWebsiteAssessmentValues } from './isWebsiteAssessmentNonNull';
|
|
3
|
+
import { websiteAssessmentResult } from './websiteAssessmentResult';
|
|
4
|
+
import { websiteAssessmentValues } from './websiteAssessmentValues';
|
|
5
|
+
/*** Assesses semantic contact placement and normalized contact-link matching. */
|
|
6
|
+
export function assessContactAddressMarkup(facts) {
|
|
7
|
+
const observations = validatedWebsiteAssessmentValues(facts.map((fact) => contactObservation(fact.value, fact.id)));
|
|
8
|
+
if (observations === null)
|
|
9
|
+
return websiteAssessmentResult(null);
|
|
10
|
+
return websiteAssessmentResult(observations.flatMap((observation) => observation.context === 'address' && observation.links.every(Boolean)
|
|
11
|
+
? []
|
|
12
|
+
: [
|
|
13
|
+
contactFinding(observation.subject, observation.context === 'address' ? 'contact-link' : 'address-context', observation.id, observation.kind),
|
|
14
|
+
]));
|
|
15
|
+
}
|
|
16
|
+
/*** Parses a contact observation without retaining raw address or link content. */
|
|
17
|
+
function contactObservation(value, id) {
|
|
18
|
+
const subject = websiteAssessmentValues.subject(value.subject);
|
|
19
|
+
if (!Array.isArray(value.contactLinks) ||
|
|
20
|
+
subject === null ||
|
|
21
|
+
value.version !== 1 ||
|
|
22
|
+
(value.addressKind !== 'company' && value.addressKind !== 'person') ||
|
|
23
|
+
(value.addressContext !== 'address' && value.addressContext !== 'other'))
|
|
24
|
+
return null;
|
|
25
|
+
const links = value.contactLinks.map(contactLinkMatch);
|
|
26
|
+
const matches = validatedWebsiteAssessmentValues(links);
|
|
27
|
+
return matches === null
|
|
28
|
+
? null
|
|
29
|
+
: { context: value.addressContext, id, kind: value.addressKind, links: matches, subject };
|
|
30
|
+
}
|
|
31
|
+
/*** Validates a single normalized contact-link match without exposing its target. */
|
|
32
|
+
function contactLinkMatch(value) {
|
|
33
|
+
return isRecord(value) &&
|
|
34
|
+
(value.kind === 'email' || value.kind === 'phone') &&
|
|
35
|
+
typeof value.match === 'boolean'
|
|
36
|
+
? value.match
|
|
37
|
+
: null;
|
|
38
|
+
}
|
|
39
|
+
/*** Creates privacy-safe evidence for a contact semantic defect. */
|
|
40
|
+
function contactFinding(subject, issue, observationId, addressKind) {
|
|
41
|
+
return {
|
|
42
|
+
evidence: { addressKind, issue, observationId },
|
|
43
|
+
message: 'A recognized contact address lacks semantic address context or a matching contact link.',
|
|
44
|
+
subject,
|
|
45
|
+
};
|
|
46
|
+
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { AssessmentFact, AssessmentResult, WebsiteAssessmentRuleOptions } from '../../types/websiteAssessment';
|
|
2
|
+
/*** Assesses parser-normalized copyright placement and year semantics. */
|
|
3
|
+
export declare function assessCopyrightNotice(facts: readonly AssessmentFact[], options: WebsiteAssessmentRuleOptions): AssessmentResult;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { validatedWebsiteAssessmentValues } from './isWebsiteAssessmentNonNull';
|
|
2
|
+
import { websiteAssessmentResult } from './websiteAssessmentResult';
|
|
3
|
+
import { websiteAssessmentValues } from './websiteAssessmentValues';
|
|
4
|
+
/*** Assesses parser-normalized copyright placement and year semantics. */
|
|
5
|
+
export function assessCopyrightNotice(facts, options) {
|
|
6
|
+
const { referenceYear } = options;
|
|
7
|
+
const observations = validatedWebsiteAssessmentValues(facts.map((fact) => copyrightObservation(fact.value, fact.id)));
|
|
8
|
+
return referenceYear === undefined || observations === null
|
|
9
|
+
? websiteAssessmentResult(null)
|
|
10
|
+
: websiteAssessmentResult(observations.flatMap((observation) => observation.year < referenceYear && !observation.exception
|
|
11
|
+
? [copyrightFinding(observation)]
|
|
12
|
+
: []));
|
|
13
|
+
}
|
|
14
|
+
/*** Parses public parser output required for copyright assessment. */
|
|
15
|
+
function copyrightObservation(value, id) {
|
|
16
|
+
const subject = websiteAssessmentValues.subject(value.subject);
|
|
17
|
+
return value.version === 1 &&
|
|
18
|
+
value.noticeSyntax === 'recognized' &&
|
|
19
|
+
value.siteRole === 'footer' &&
|
|
20
|
+
websiteAssessmentValues.year(value.endYear) &&
|
|
21
|
+
typeof value.exception === 'boolean' &&
|
|
22
|
+
subject !== null
|
|
23
|
+
? { exception: value.exception, id, subject, year: value.endYear }
|
|
24
|
+
: null;
|
|
25
|
+
}
|
|
26
|
+
/*** Creates minimal year-only evidence for a stale copyright notice. */
|
|
27
|
+
function copyrightFinding(observation) {
|
|
28
|
+
return {
|
|
29
|
+
evidence: { issue: 'stale-year', noticeId: observation.id, year: observation.year },
|
|
30
|
+
message: 'A recognized copyright notice has a stale year.',
|
|
31
|
+
subject: observation.subject,
|
|
32
|
+
};
|
|
33
|
+
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
import { validatedWebsiteAssessmentValues } from './isWebsiteAssessmentNonNull';
|
|
3
|
+
import { websiteAssessmentResult } from './websiteAssessmentResult';
|
|
4
|
+
import { websiteAssessmentValues } from './websiteAssessmentValues';
|
|
5
|
+
/*** Reports repeated editorial identities while exempting system-only reuse. */
|
|
6
|
+
export function assessDuplicateMediaUse(facts) {
|
|
7
|
+
const inventories = validatedWebsiteAssessmentValues(facts.map((fact) => mediaUses(fact.value)));
|
|
8
|
+
if (inventories === null)
|
|
9
|
+
return websiteAssessmentResult(null);
|
|
10
|
+
const observations = inventories.flatMap((inventory) => inventory);
|
|
11
|
+
if (observations.length === 0)
|
|
12
|
+
return websiteAssessmentResult(null);
|
|
13
|
+
const groups = observations.reduce((all, use) => new Map(all).set(use.identity, [...(all.get(use.identity) ?? []), use]), new Map());
|
|
14
|
+
return websiteAssessmentResult([...groups.values()].flatMap((group) => group.length > 1 && group.some((use) => use.role === 'editorial')
|
|
15
|
+
? [duplicateFinding(group)]
|
|
16
|
+
: []));
|
|
17
|
+
}
|
|
18
|
+
/*** Parses one inventory while preserving the distinction between invalid and empty input. */
|
|
19
|
+
function mediaUses(value) {
|
|
20
|
+
if (value.version !== 1 || !Array.isArray(value.uses))
|
|
21
|
+
return null;
|
|
22
|
+
const uses = value.uses.map(mediaUse);
|
|
23
|
+
return validatedWebsiteAssessmentValues(uses);
|
|
24
|
+
}
|
|
25
|
+
/*** Parses a single opaque media use from an identity-bearing inventory entry. */
|
|
26
|
+
function mediaUse(value) {
|
|
27
|
+
if (!isRecord(value))
|
|
28
|
+
return null;
|
|
29
|
+
const subject = websiteAssessmentValues.subject(value.subject);
|
|
30
|
+
const identity = websiteAssessmentValues.text(value.contentHash) ??
|
|
31
|
+
websiteAssessmentValues.text(value.lineageId) ??
|
|
32
|
+
websiteAssessmentValues.text(value.assetId);
|
|
33
|
+
const pageId = websiteAssessmentValues.text(value.pageId);
|
|
34
|
+
const componentId = websiteAssessmentValues.text(value.componentId);
|
|
35
|
+
return subject !== null &&
|
|
36
|
+
identity !== null &&
|
|
37
|
+
pageId !== null &&
|
|
38
|
+
componentId !== null &&
|
|
39
|
+
(value.role === 'editorial' || value.role === 'system')
|
|
40
|
+
? { identity, location: `${pageId}:${componentId}`, role: value.role, subject }
|
|
41
|
+
: null;
|
|
42
|
+
}
|
|
43
|
+
/*** Produces sorted opaque evidence for one repeated asset identity. */
|
|
44
|
+
function duplicateFinding(group) {
|
|
45
|
+
const [first] = group;
|
|
46
|
+
return {
|
|
47
|
+
evidence: {
|
|
48
|
+
assetKey: first.identity,
|
|
49
|
+
locations: group.map((use) => use.location).sort(),
|
|
50
|
+
useCount: group.length,
|
|
51
|
+
},
|
|
52
|
+
message: 'A verified asset is reused in multiple editorial content locations.',
|
|
53
|
+
subject: first.subject,
|
|
54
|
+
};
|
|
55
|
+
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { AssessmentFact, AssessmentResult, WebsiteAssessmentRuleOptions } from '../../types/websiteAssessment';
|
|
2
|
+
/*** Applies configured legal-notice policy to independently observed link facts. */
|
|
3
|
+
export declare function assessLegalNotice(facts: readonly AssessmentFact[], options: WebsiteAssessmentRuleOptions): AssessmentResult;
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { isStringArray } from '@ankhorage/utility/array';
|
|
2
|
+
import { validatedWebsiteAssessmentValues } from './isWebsiteAssessmentNonNull';
|
|
3
|
+
import { websiteAssessmentResult } from './websiteAssessmentResult';
|
|
4
|
+
import { websiteAssessmentValues } from './websiteAssessmentValues';
|
|
5
|
+
/*** Applies configured legal-notice policy to independently observed link facts. */
|
|
6
|
+
export function assessLegalNotice(facts, options) {
|
|
7
|
+
const observations = validatedWebsiteAssessmentValues(facts.map((fact) => legalNoticeObservation(fact.value, fact.id)));
|
|
8
|
+
if (options.legalNoticePolicy === undefined || observations === null)
|
|
9
|
+
return websiteAssessmentResult(null);
|
|
10
|
+
return options.legalNoticePolicy === 'not-required'
|
|
11
|
+
? websiteAssessmentResult([])
|
|
12
|
+
: websiteAssessmentResult(observations.flatMap((observation) => observation.global && observation.reachable && observation.content === 'substantive'
|
|
13
|
+
? []
|
|
14
|
+
: [legalNoticeFinding(observation)]));
|
|
15
|
+
}
|
|
16
|
+
/*** Parses legal notice facts without promoting labels to legal conclusions. */
|
|
17
|
+
function legalNoticeObservation(value, id) {
|
|
18
|
+
const subject = websiteAssessmentValues.subject(value.subject);
|
|
19
|
+
return value.version === 1 &&
|
|
20
|
+
isStringArray(value.labels) &&
|
|
21
|
+
typeof value.global === 'boolean' &&
|
|
22
|
+
typeof value.reachable === 'boolean' &&
|
|
23
|
+
(value.content === 'substantive' ||
|
|
24
|
+
value.content === 'empty' ||
|
|
25
|
+
value.content === 'misleading') &&
|
|
26
|
+
subject !== null
|
|
27
|
+
? { content: value.content, global: value.global, id, reachable: value.reachable, subject }
|
|
28
|
+
: null;
|
|
29
|
+
}
|
|
30
|
+
/*** Creates a normalized legal notice failure without retaining page text. */
|
|
31
|
+
function legalNoticeFinding(observation) {
|
|
32
|
+
return {
|
|
33
|
+
evidence: {
|
|
34
|
+
issue: !observation.reachable
|
|
35
|
+
? 'unreachable'
|
|
36
|
+
: !observation.global
|
|
37
|
+
? 'not-site-wide'
|
|
38
|
+
: 'empty-or-misleading',
|
|
39
|
+
noticeId: observation.id,
|
|
40
|
+
},
|
|
41
|
+
message: 'A configured legal notice is not site-wide, reachable, and substantive.',
|
|
42
|
+
subject: observation.subject,
|
|
43
|
+
};
|
|
44
|
+
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { AssessmentFact, AssessmentResult, WebsiteAssessmentRuleOptions } from '../../types/websiteAssessment';
|
|
2
|
+
/*** Compares declared privacy purposes with observed processing purposes. */
|
|
3
|
+
export declare function assessPrivacyNotice(facts: readonly AssessmentFact[], options: WebsiteAssessmentRuleOptions): AssessmentResult;
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { isStringArray } from '@ankhorage/utility/array';
|
|
2
|
+
import { validatedWebsiteAssessmentValues } from './isWebsiteAssessmentNonNull';
|
|
3
|
+
import { websiteAssessmentResult } from './websiteAssessmentResult';
|
|
4
|
+
import { websiteAssessmentValues } from './websiteAssessmentValues';
|
|
5
|
+
/*** Compares declared privacy purposes with observed processing purposes. */
|
|
6
|
+
export function assessPrivacyNotice(facts, options) {
|
|
7
|
+
const observations = validatedWebsiteAssessmentValues(facts.map((fact) => privacyNoticeObservation(fact.value, fact.id)));
|
|
8
|
+
if (options.privacyNoticePolicy === undefined || observations === null)
|
|
9
|
+
return websiteAssessmentResult(null);
|
|
10
|
+
return options.privacyNoticePolicy === 'not-required'
|
|
11
|
+
? websiteAssessmentResult([])
|
|
12
|
+
: websiteAssessmentResult(observations.flatMap((observation) => observation.global &&
|
|
13
|
+
observation.reachable &&
|
|
14
|
+
observation.observed.every((purpose) => observation.declared.includes(purpose))
|
|
15
|
+
? []
|
|
16
|
+
: [privacyNoticeFinding(observation)]));
|
|
17
|
+
}
|
|
18
|
+
/*** Parses privacy facts using the fixed policy-purpose vocabulary. */
|
|
19
|
+
function privacyNoticeObservation(value, id) {
|
|
20
|
+
const declared = privacyPurposesFrom(value.declaredPurposes);
|
|
21
|
+
const observed = privacyPurposesFrom(value.observedPurposes);
|
|
22
|
+
const subject = websiteAssessmentValues.subject(value.subject);
|
|
23
|
+
return value.version === 1 &&
|
|
24
|
+
typeof value.global === 'boolean' &&
|
|
25
|
+
typeof value.reachable === 'boolean' &&
|
|
26
|
+
declared !== null &&
|
|
27
|
+
observed !== null &&
|
|
28
|
+
subject !== null
|
|
29
|
+
? { declared, global: value.global, id, observed, reachable: value.reachable, subject }
|
|
30
|
+
: null;
|
|
31
|
+
}
|
|
32
|
+
/*** Accepts only the policy-owned declared and observed processing vocabulary. */
|
|
33
|
+
function privacyPurposesFrom(value) {
|
|
34
|
+
if (!isStringArray(value))
|
|
35
|
+
return null;
|
|
36
|
+
const purposes = value.map(privacyPurpose);
|
|
37
|
+
return validatedWebsiteAssessmentValues(purposes);
|
|
38
|
+
}
|
|
39
|
+
/*** Narrows one declared processing purpose to the policy-owned vocabulary. */
|
|
40
|
+
function privacyPurpose(value) {
|
|
41
|
+
return value === 'analytics' || value === 'contact' ? value : null;
|
|
42
|
+
}
|
|
43
|
+
/*** Creates non-sensitive evidence for a missing privacy declaration. */
|
|
44
|
+
function privacyNoticeFinding(observation) {
|
|
45
|
+
return {
|
|
46
|
+
evidence: {
|
|
47
|
+
issue: !observation.reachable
|
|
48
|
+
? 'unreachable'
|
|
49
|
+
: !observation.global
|
|
50
|
+
? 'not-site-wide'
|
|
51
|
+
: 'undeclared-processing',
|
|
52
|
+
noticeId: observation.id,
|
|
53
|
+
observedPurposeCount: observation.observed.length,
|
|
54
|
+
},
|
|
55
|
+
message: 'The privacy notice is unreachable, not site-wide, or omits an observed processing purpose.',
|
|
56
|
+
subject: observation.subject,
|
|
57
|
+
};
|
|
58
|
+
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { AssessmentFact, AssessmentResult, WebsiteAssessmentRuleOptions } from '../../types/websiteAssessment';
|
|
2
|
+
/*** Applies an explicit regional policy to complete tracking runtime observations. */
|
|
3
|
+
export declare function assessTrackingConsent(facts: readonly AssessmentFact[], options: WebsiteAssessmentRuleOptions): AssessmentResult;
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
import { validatedWebsiteAssessmentValues } from './isWebsiteAssessmentNonNull';
|
|
3
|
+
import { websiteAssessmentResult } from './websiteAssessmentResult';
|
|
4
|
+
import { websiteAssessmentValues } from './websiteAssessmentValues';
|
|
5
|
+
/*** Applies an explicit regional policy to complete tracking runtime observations. */
|
|
6
|
+
export function assessTrackingConsent(facts, options) {
|
|
7
|
+
const policy = options.trackingConsentPolicy;
|
|
8
|
+
const observations = validatedWebsiteAssessmentValues(facts.map((fact) => trackingObservation(fact.value, fact.id)));
|
|
9
|
+
if (policy === undefined || observations === null)
|
|
10
|
+
return websiteAssessmentResult(null);
|
|
11
|
+
return websiteAssessmentResult(observations.flatMap((observation) => trackingFails(observation, policy) ? [trackingFinding(observation, policy)] : []));
|
|
12
|
+
}
|
|
13
|
+
/*** Parses fully covered tracking state observations. */
|
|
14
|
+
function trackingObservation(value, id) {
|
|
15
|
+
const subject = websiteAssessmentValues.subject(value.subject);
|
|
16
|
+
if (value.version !== 1 || subject === null || !Array.isArray(value.states))
|
|
17
|
+
return null;
|
|
18
|
+
const states = validatedWebsiteAssessmentValues(value.states.map(trackingState));
|
|
19
|
+
if (states === null)
|
|
20
|
+
return null;
|
|
21
|
+
return value.classification === 'essential-only'
|
|
22
|
+
? { id, states: [], subject }
|
|
23
|
+
: value.classification === 'optional' && hasCompleteConsentCoverage(states)
|
|
24
|
+
? { id, states, subject }
|
|
25
|
+
: null;
|
|
26
|
+
}
|
|
27
|
+
/*** Requires observations for each state that establishes an optional-tracking decision. */
|
|
28
|
+
function hasCompleteConsentCoverage(states) {
|
|
29
|
+
return ['accepted', 'before-choice', 'rejected'].every((requiredState) => states.some((state) => state.state === requiredState));
|
|
30
|
+
}
|
|
31
|
+
/*** Validates one complete runtime state without retaining tracker values. */
|
|
32
|
+
function trackingState(value) {
|
|
33
|
+
return isRecord(value) &&
|
|
34
|
+
(value.state === 'before-choice' ||
|
|
35
|
+
value.state === 'rejected' ||
|
|
36
|
+
value.state === 'accepted' ||
|
|
37
|
+
value.state === 'withdrawn') &&
|
|
38
|
+
typeof value.optionalTrackingObserved === 'boolean' &&
|
|
39
|
+
value.covered === true
|
|
40
|
+
? { observed: value.optionalTrackingObserved, state: value.state }
|
|
41
|
+
: null;
|
|
42
|
+
}
|
|
43
|
+
/*** Applies prior-consent and rejection behavior without assuming a jurisdiction. */
|
|
44
|
+
function trackingFails(observation, policy) {
|
|
45
|
+
return policy === 'eu-eea-prior-consent'
|
|
46
|
+
? observation.states
|
|
47
|
+
.filter((state) => state.state === 'before-choice' || state.state === 'rejected')
|
|
48
|
+
.some((state) => state.observed)
|
|
49
|
+
: observation.states.some((state) => state.state === 'rejected' && state.observed);
|
|
50
|
+
}
|
|
51
|
+
/*** Creates a stable tracking evidence code with no cookie values. */
|
|
52
|
+
function trackingFinding(observation, policy) {
|
|
53
|
+
return {
|
|
54
|
+
evidence: {
|
|
55
|
+
issue: policy === 'eu-eea-prior-consent'
|
|
56
|
+
? 'tracking-before-consent-or-after-rejection'
|
|
57
|
+
: 'tracking-after-rejection',
|
|
58
|
+
observationId: observation.id,
|
|
59
|
+
},
|
|
60
|
+
message: 'Optional tracking was observed in a state disallowed by the configured consent policy.',
|
|
61
|
+
subject: observation.subject,
|
|
62
|
+
};
|
|
63
|
+
}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { RuleSet } from '@ankhorage/rules';
|
|
2
|
+
import type { WebsiteAssessmentContext, WebsiteAssessmentRuleOptions } from '../../types/websiteAssessment';
|
|
3
|
+
/*** Creates the separately composable follow-on website and contact assessment rules. */
|
|
4
|
+
export declare function createWebsiteAssessmentRuleSet(options?: WebsiteAssessmentRuleOptions): RuleSet<WebsiteAssessmentContext>;
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
import { websiteAssessmentDefinitions } from './websiteAssessmentDefinitions';
|
|
3
|
+
/*** Creates the separately composable follow-on website and contact assessment rules. */
|
|
4
|
+
export function createWebsiteAssessmentRuleSet(options = {}) {
|
|
5
|
+
return {
|
|
6
|
+
id: 'ankhorage.rules-design.website-assessment',
|
|
7
|
+
rules: websiteAssessmentDefinitions.map((definition) => createWebsiteAssessmentRule(definition, options)),
|
|
8
|
+
};
|
|
9
|
+
}
|
|
10
|
+
/*** Builds one pure Rules adapter around a typed website assessment. */
|
|
11
|
+
function createWebsiteAssessmentRule(definition, options) {
|
|
12
|
+
return {
|
|
13
|
+
defaultSeverity: definition.severity,
|
|
14
|
+
dependencies: [],
|
|
15
|
+
evaluate: ({ context, scope }) => evaluateWebsiteAssessmentRule(definition, options, context.facts, scope),
|
|
16
|
+
identity: { id: definition.id, version: '1.0.0' },
|
|
17
|
+
requiredCapabilities: [definition.capability],
|
|
18
|
+
summary: definition.summary,
|
|
19
|
+
};
|
|
20
|
+
}
|
|
21
|
+
/*** Evaluates exact-scope observations and fails closed for missing or malformed facts. */
|
|
22
|
+
function evaluateWebsiteAssessmentRule(definition, options, facts, scope) {
|
|
23
|
+
const scopedFacts = facts.filter((fact) => fact.kind === definition.factKind &&
|
|
24
|
+
fact.scope.id === scope.id &&
|
|
25
|
+
fact.scope.kind === scope.kind);
|
|
26
|
+
const observations = scopedFacts.flatMap(toAssessmentFact);
|
|
27
|
+
if (scopedFacts.length === 0 || observations.length !== scopedFacts.length)
|
|
28
|
+
return incomplete(definition.id, scope);
|
|
29
|
+
const result = definition.evaluate(observations, options);
|
|
30
|
+
return {
|
|
31
|
+
findings: result.findings.map((finding) => ({
|
|
32
|
+
evidence: finding.evidence,
|
|
33
|
+
message: finding.message,
|
|
34
|
+
ruleId: definition.id,
|
|
35
|
+
severity: result.status === 'FAIL' ? definition.severity : 'info',
|
|
36
|
+
subjects: [finding.subject],
|
|
37
|
+
})),
|
|
38
|
+
status: result.status,
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
/*** Accepts a portable available record only after required fact identity fields are present. */
|
|
42
|
+
function toAssessmentFact(fact) {
|
|
43
|
+
return fact.status === 'available' &&
|
|
44
|
+
nonEmpty(fact.id) &&
|
|
45
|
+
nonEmpty(fact.contentHash) &&
|
|
46
|
+
isRecord(fact.value)
|
|
47
|
+
? [{ id: fact.id, value: fact.value }]
|
|
48
|
+
: [];
|
|
49
|
+
}
|
|
50
|
+
/*** Produces a canonical incomplete outcome without exposing host payloads. */
|
|
51
|
+
function incomplete(id, scope) {
|
|
52
|
+
return {
|
|
53
|
+
findings: [
|
|
54
|
+
{
|
|
55
|
+
evidence: { scopeId: scope.id, scopeKind: scope.kind },
|
|
56
|
+
message: 'Complete validated website assessment observations are unavailable.',
|
|
57
|
+
ruleId: id,
|
|
58
|
+
severity: 'info',
|
|
59
|
+
subjects: [{ id: scope.id, kind: scope.kind }],
|
|
60
|
+
},
|
|
61
|
+
],
|
|
62
|
+
status: 'INCOMPLETE',
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
/*** Narrows a stable fact identity string. */
|
|
66
|
+
function nonEmpty(value) {
|
|
67
|
+
return value.trim().length > 0;
|
|
68
|
+
}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
/*** Returns normalized assessment values only when every array element has been validated. */
|
|
2
|
+
export function validatedWebsiteAssessmentValues(values) {
|
|
3
|
+
const validated = values.filter((value) => value !== null);
|
|
4
|
+
return validated.length === values.length ? validated : null;
|
|
5
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { assessContactAddressMarkup } from './assessContactAddressMarkup';
|
|
2
|
+
import { assessCopyrightNotice } from './assessCopyrightNotice';
|
|
3
|
+
import { assessDuplicateMediaUse } from './assessDuplicateMediaUse';
|
|
4
|
+
import { assessLegalNotice } from './assessLegalNotice';
|
|
5
|
+
import { assessPrivacyNotice } from './assessPrivacyNotice';
|
|
6
|
+
import { assessTrackingConsent } from './assessTrackingConsent';
|
|
7
|
+
/*** Declares the fixed website-assessment catalog without allowing host verdicts as facts. */
|
|
8
|
+
export const websiteAssessmentDefinitions = [
|
|
9
|
+
definition('design.contact.address-markup', 'website.contact-observation', 'warning', 'Recognized contact addresses use semantic markup and valid contact links.', assessContactAddressMarkup),
|
|
10
|
+
definition('design.website.copyright-notice', 'website.copyright-observation', 'warning', 'Recognized copyright notices are available from site-wide footer evidence.', assessCopyrightNotice),
|
|
11
|
+
definition('design.website.legal-notice', 'website.legal-notice-observation', 'warning', 'Configured legal notices are discoverable, reachable, and sufficiently identified.', assessLegalNotice),
|
|
12
|
+
definition('design.website.privacy-notice', 'website.privacy-notice-observation', 'warning', 'Configured privacy notices are reachable and consistent with observed processing.', assessPrivacyNotice),
|
|
13
|
+
definition('design.website.tracking-consent', 'website.tracking-observation', 'error', 'Observed optional tracking follows the configured jurisdiction consent policy.', assessTrackingConsent),
|
|
14
|
+
definition('design.media.duplicate-use', 'website.media-inventory', 'warning', 'Repeated image assets are classified without treating intentional reuse as a defect.', assessDuplicateMediaUse),
|
|
15
|
+
];
|
|
16
|
+
/*** Creates one immutable definition with its capability-owned evaluator. */
|
|
17
|
+
function definition(id, factKind, severity, summary, evaluate) {
|
|
18
|
+
return {
|
|
19
|
+
capability: factKind,
|
|
20
|
+
evaluate,
|
|
21
|
+
factKind,
|
|
22
|
+
id,
|
|
23
|
+
severity,
|
|
24
|
+
summary,
|
|
25
|
+
};
|
|
26
|
+
}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { AssessmentFinding, AssessmentResult } from '../../types/websiteAssessment';
|
|
2
|
+
/*** Produces deterministic outcomes and generic incomplete evidence for website assessment rules. */
|
|
3
|
+
export declare function websiteAssessmentResult(findings: readonly AssessmentFinding[] | null): AssessmentResult;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/*** Produces deterministic outcomes and generic incomplete evidence for website assessment rules. */
|
|
2
|
+
export function websiteAssessmentResult(findings) {
|
|
3
|
+
if (findings === null)
|
|
4
|
+
return {
|
|
5
|
+
findings: [
|
|
6
|
+
{
|
|
7
|
+
evidence: { reason: 'incomplete-observation' },
|
|
8
|
+
message: 'The supplied structured observations are insufficient for a safe assessment.',
|
|
9
|
+
subject: incompleteSubject,
|
|
10
|
+
},
|
|
11
|
+
],
|
|
12
|
+
status: 'INCOMPLETE',
|
|
13
|
+
};
|
|
14
|
+
return findings.length === 0
|
|
15
|
+
? { findings: [], status: 'PASS' }
|
|
16
|
+
: {
|
|
17
|
+
findings: [...findings].sort((left, right) => left.subject.id.localeCompare(right.subject.id)),
|
|
18
|
+
status: 'FAIL',
|
|
19
|
+
};
|
|
20
|
+
}
|
|
21
|
+
const incompleteSubject = { id: 'website-assessment', kind: 'website' };
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { AvailableFactEnvelope } from '@ankhorage/contracts/rules';
|
|
2
|
+
import { type JsonValue } from '@ankhorage/rules';
|
|
3
|
+
declare const options: {
|
|
4
|
+
readonly legalNoticePolicy: "required";
|
|
5
|
+
readonly privacyNoticePolicy: "required";
|
|
6
|
+
readonly referenceYear: 2026;
|
|
7
|
+
readonly trackingConsentPolicy: "eu-eea-prior-consent";
|
|
8
|
+
};
|
|
9
|
+
/*** Evaluates one website assessment rule through the public Rules engine boundary. */
|
|
10
|
+
export declare function evaluateWebsiteAssessment(ruleId: string, facts: readonly AvailableFactEnvelope[], override?: Partial<typeof options>): import("@ankhorage/rules").RuleResult;
|
|
11
|
+
/*** Builds an available opaque test fact with a real SHA-256 content hash. */
|
|
12
|
+
export declare function websiteAssessmentFact(kind: string, value: JsonValue): AvailableFactEnvelope;
|
|
13
|
+
export {};
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
import { evaluateRules } from '@ankhorage/rules';
|
|
3
|
+
import { createWebsiteAssessmentRuleSet } from './createWebsiteAssessmentRuleSet';
|
|
4
|
+
const scope = { id: 'site', kind: 'website' };
|
|
5
|
+
const options = {
|
|
6
|
+
legalNoticePolicy: 'required',
|
|
7
|
+
privacyNoticePolicy: 'required',
|
|
8
|
+
referenceYear: 2026,
|
|
9
|
+
trackingConsentPolicy: 'eu-eea-prior-consent',
|
|
10
|
+
};
|
|
11
|
+
/*** Evaluates one website assessment rule through the public Rules engine boundary. */
|
|
12
|
+
export function evaluateWebsiteAssessment(ruleId, facts, override = {}) {
|
|
13
|
+
const rule = createWebsiteAssessmentRuleSet({ ...options, ...override }).rules.find((candidate) => candidate.identity.id === ruleId);
|
|
14
|
+
if (rule === undefined)
|
|
15
|
+
throw new Error(`Missing rule ${ruleId}`);
|
|
16
|
+
const [result] = evaluateRules({ facts }, [rule], {
|
|
17
|
+
capabilities: rule.requiredCapabilities,
|
|
18
|
+
scope,
|
|
19
|
+
}).results;
|
|
20
|
+
return result;
|
|
21
|
+
}
|
|
22
|
+
/*** Builds an available opaque test fact with a real SHA-256 content hash. */
|
|
23
|
+
export function websiteAssessmentFact(kind, value) {
|
|
24
|
+
const hash = createHash('sha256').update(canonical(value)).digest('hex');
|
|
25
|
+
return {
|
|
26
|
+
contentHash: `sha256:${hash}`,
|
|
27
|
+
id: `${kind}:${hash.slice(0, 12)}`,
|
|
28
|
+
kind,
|
|
29
|
+
provenance: {
|
|
30
|
+
collectedAt: '2026-11-11T00:00:00.000Z',
|
|
31
|
+
producer: { id: 'fixture', version: '1' },
|
|
32
|
+
source: { id: 'fixture', revision: null },
|
|
33
|
+
},
|
|
34
|
+
schemaVersion: 1,
|
|
35
|
+
scope: {
|
|
36
|
+
...scope,
|
|
37
|
+
target: { kind: 'application', projectId: 'project', targetId: 'site', tenantId: 'tenant' },
|
|
38
|
+
},
|
|
39
|
+
status: 'available',
|
|
40
|
+
value,
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
/*** Produces a stable serialization for real test content hashes. */
|
|
44
|
+
function canonical(value) {
|
|
45
|
+
if (Array.isArray(value))
|
|
46
|
+
return `[${value.map(canonical).join(',')}]`;
|
|
47
|
+
if (value !== null && typeof value === 'object')
|
|
48
|
+
return `{${Object.entries(value)
|
|
49
|
+
.sort(([left], [right]) => left.localeCompare(right))
|
|
50
|
+
.map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
|
|
51
|
+
.join(',')}}`;
|
|
52
|
+
return JSON.stringify(value);
|
|
53
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { JsonValue, RuleSubject } from '@ankhorage/rules';
|
|
2
|
+
/*** Validates privacy-safe, normalized values shared by website assessment rules. */
|
|
3
|
+
export declare const websiteAssessmentValues: {
|
|
4
|
+
subject(value: unknown): RuleSubject | null;
|
|
5
|
+
text(value: unknown): string | null;
|
|
6
|
+
year(value: JsonValue | undefined): value is number;
|
|
7
|
+
};
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
2
|
+
/*** Validates privacy-safe, normalized values shared by website assessment rules. */
|
|
3
|
+
export const websiteAssessmentValues = {
|
|
4
|
+
subject(value) {
|
|
5
|
+
if (!isRecord(value))
|
|
6
|
+
return null;
|
|
7
|
+
const id = this.text(value.id);
|
|
8
|
+
const kind = this.text(value.kind);
|
|
9
|
+
return id === null || kind === null ? null : { id, kind };
|
|
10
|
+
},
|
|
11
|
+
text(value) {
|
|
12
|
+
return typeof value === 'string' && value.trim().length > 0 ? value : null;
|
|
13
|
+
},
|
|
14
|
+
year(value) {
|
|
15
|
+
return typeof value === 'number' && Number.isInteger(value) && value >= 1000 && value <= 9999;
|
|
16
|
+
},
|
|
17
|
+
};
|
package/dist/index.d.ts
CHANGED
|
@@ -4,5 +4,9 @@ export { designRuleProviderManifest } from './features/catalog/designRuleProvide
|
|
|
4
4
|
export { filterDesignRuleCatalog } from './features/catalog/filterDesignRuleCatalog';
|
|
5
5
|
export { createDesignRuleProvider } from './features/provider/designRuleProvider';
|
|
6
6
|
export { selectDesignRuleProfile } from './features/provider/selectDesignRuleProfile';
|
|
7
|
+
export { recognizeWebsiteDesignProperties } from './features/recognition/recognizeWebsiteDesignProperties';
|
|
8
|
+
export { createWebsiteAssessmentRuleSet } from './features/website-assessment/createWebsiteAssessmentRuleSet';
|
|
7
9
|
export type { DesignAssessmentKind, DesignRuleCatalogEntry, DesignRuleCatalogFilter, DesignRuleEvidence, DesignRulePlanningManifest, DesignRuleProfile, DesignRuleProviderManifest, DesignRuleScope, DesignRuleStatus, } from './types/designRuleCatalog';
|
|
8
10
|
export type { DesignContext, DesignRuleProfileSelection, DesignRuleProvider, DesignRuleProviderOptions, } from './types/designRuleProvider';
|
|
11
|
+
export type { WebsiteAssessmentRuleOptions } from './types/websiteAssessment';
|
|
12
|
+
export type { WebsiteDesignNodeRecognition, WebsiteDesignPropertyObservation, WebsiteDesignRecognition, WebsiteDesignSourceReference, WebsiteDesignTokenCandidate, WebsiteDesignUnresolvedObservation, } from './types/websiteDesignRecognition';
|
package/dist/index.js
CHANGED
|
@@ -4,3 +4,5 @@ export { designRuleProviderManifest } from './features/catalog/designRuleProvide
|
|
|
4
4
|
export { filterDesignRuleCatalog } from './features/catalog/filterDesignRuleCatalog';
|
|
5
5
|
export { createDesignRuleProvider } from './features/provider/designRuleProvider';
|
|
6
6
|
export { selectDesignRuleProfile } from './features/provider/selectDesignRuleProfile';
|
|
7
|
+
export { recognizeWebsiteDesignProperties } from './features/recognition/recognizeWebsiteDesignProperties';
|
|
8
|
+
export { createWebsiteAssessmentRuleSet } from './features/website-assessment/createWebsiteAssessmentRuleSet';
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import type { FactEnvelope } from '@ankhorage/contracts/rules';
|
|
2
|
+
import type { JsonValue, RuleSubject } from '@ankhorage/rules';
|
|
3
|
+
/*** Configures explicit policies for the independently composable website assessment RuleSet. */
|
|
4
|
+
export interface WebsiteAssessmentRuleOptions {
|
|
5
|
+
readonly legalNoticePolicy?: 'not-required' | 'required';
|
|
6
|
+
readonly privacyNoticePolicy?: 'not-required' | 'required';
|
|
7
|
+
readonly referenceYear?: number;
|
|
8
|
+
readonly trackingConsentPolicy?: 'ch-information-and-objection' | 'eu-eea-prior-consent';
|
|
9
|
+
}
|
|
10
|
+
type WebsiteAssessmentRuleId = 'design.contact.address-markup' | 'design.website.copyright-notice' | 'design.website.legal-notice' | 'design.website.privacy-notice' | 'design.website.tracking-consent' | 'design.media.duplicate-use';
|
|
11
|
+
export interface WebsiteAssessmentContext {
|
|
12
|
+
readonly facts: readonly FactEnvelope[];
|
|
13
|
+
}
|
|
14
|
+
export interface AssessmentFact {
|
|
15
|
+
readonly id: string;
|
|
16
|
+
readonly value: Readonly<Record<string, JsonValue>>;
|
|
17
|
+
}
|
|
18
|
+
export interface AssessmentFinding {
|
|
19
|
+
readonly evidence: Readonly<Record<string, JsonValue>>;
|
|
20
|
+
readonly message: string;
|
|
21
|
+
readonly subject: RuleSubject;
|
|
22
|
+
}
|
|
23
|
+
export interface AssessmentResult {
|
|
24
|
+
readonly findings: readonly AssessmentFinding[];
|
|
25
|
+
readonly status: 'FAIL' | 'INCOMPLETE' | 'PASS';
|
|
26
|
+
}
|
|
27
|
+
export interface AssessmentDefinition {
|
|
28
|
+
readonly capability: string;
|
|
29
|
+
readonly factKind: string;
|
|
30
|
+
readonly id: WebsiteAssessmentRuleId;
|
|
31
|
+
readonly severity: 'error' | 'warning';
|
|
32
|
+
readonly summary: string;
|
|
33
|
+
readonly evaluate: (facts: readonly AssessmentFact[], options: WebsiteAssessmentRuleOptions) => AssessmentResult;
|
|
34
|
+
}
|
|
35
|
+
export {};
|
|
File without changes
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import type { SerializableValue } from '@ankhorage/contracts';
|
|
2
|
+
import type { WebsiteMediaReference, WebsiteMissingValue, WebsiteObservationProvenance } from '@ankhorage/contracts/website';
|
|
3
|
+
/*** Identifies one observed DOM node within the page that owns its local source reference. */
|
|
4
|
+
export interface WebsiteDesignSourceReference {
|
|
5
|
+
readonly pageId: string;
|
|
6
|
+
readonly sourceRef: string;
|
|
7
|
+
}
|
|
8
|
+
/*** Describes one exact observed design value without assigning a quality verdict. */
|
|
9
|
+
export interface WebsiteDesignPropertyObservation {
|
|
10
|
+
readonly name: string;
|
|
11
|
+
readonly value: SerializableValue;
|
|
12
|
+
readonly viewportId: string;
|
|
13
|
+
readonly stateId: string;
|
|
14
|
+
readonly sourceRef: string;
|
|
15
|
+
readonly pageId: string;
|
|
16
|
+
readonly provenance: WebsiteObservationProvenance;
|
|
17
|
+
}
|
|
18
|
+
/*** Retains an unavailable observation instead of substituting or silently omitting design evidence. */
|
|
19
|
+
export interface WebsiteDesignUnresolvedObservation {
|
|
20
|
+
readonly kind: 'computed-css' | 'geometry';
|
|
21
|
+
readonly viewportId: string;
|
|
22
|
+
readonly stateId: string;
|
|
23
|
+
readonly sourceRef: string;
|
|
24
|
+
readonly pageId: string;
|
|
25
|
+
readonly provenance: WebsiteObservationProvenance;
|
|
26
|
+
readonly missing: WebsiteMissingValue;
|
|
27
|
+
}
|
|
28
|
+
/*** Groups all factual design observations for one stable observed DOM node. */
|
|
29
|
+
export interface WebsiteDesignNodeRecognition {
|
|
30
|
+
readonly sourceRef: string;
|
|
31
|
+
readonly pageId: string;
|
|
32
|
+
readonly colors: readonly WebsiteDesignPropertyObservation[];
|
|
33
|
+
readonly typography: readonly WebsiteDesignPropertyObservation[];
|
|
34
|
+
readonly layout: readonly WebsiteDesignPropertyObservation[];
|
|
35
|
+
readonly responsive: readonly WebsiteDesignPropertyObservation[];
|
|
36
|
+
readonly accessibility: readonly WebsiteDesignPropertyObservation[];
|
|
37
|
+
readonly media: readonly WebsiteMediaReference[];
|
|
38
|
+
readonly unresolved: readonly WebsiteDesignUnresolvedObservation[];
|
|
39
|
+
}
|
|
40
|
+
/*** Records a repeated observed value as a reusable token candidate without inventing a role. */
|
|
41
|
+
export interface WebsiteDesignTokenCandidate {
|
|
42
|
+
readonly kind: 'color' | 'radius' | 'shadow' | 'spacing' | 'typography';
|
|
43
|
+
readonly property: string;
|
|
44
|
+
readonly value: string;
|
|
45
|
+
readonly originalValues: readonly string[];
|
|
46
|
+
readonly sourceRefs: readonly WebsiteDesignSourceReference[];
|
|
47
|
+
readonly confidence: number;
|
|
48
|
+
readonly inferredRole: null;
|
|
49
|
+
}
|
|
50
|
+
/*** Provides the factual design-property contribution for later website recognition assembly. */
|
|
51
|
+
export interface WebsiteDesignRecognition {
|
|
52
|
+
readonly nodes: readonly WebsiteDesignNodeRecognition[];
|
|
53
|
+
readonly tokenCandidates: readonly WebsiteDesignTokenCandidate[];
|
|
54
|
+
}
|
|
File without changes
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ankhorage/rules-design",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0",
|
|
4
4
|
"description": "Declarative catalog for reusable design rules.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://github.com/ankhorage/rules-design#readme",
|
|
@@ -58,7 +58,7 @@
|
|
|
58
58
|
"@ankhorage/paradox": "^0.3.6"
|
|
59
59
|
},
|
|
60
60
|
"dependencies": {
|
|
61
|
-
"@ankhorage/contracts": "^26.
|
|
61
|
+
"@ankhorage/contracts": "^26.6.0",
|
|
62
62
|
"@ankhorage/rules": "^0.4.0",
|
|
63
63
|
"@ankhorage/utility": "^1.10.0"
|
|
64
64
|
}
|