@ankhorage/rules-design 0.4.0 → 0.5.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.
Files changed (31) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +1 -1
  3. package/dist/features/website-assessment/assessContactAddressMarkup.d.ts +3 -0
  4. package/dist/features/website-assessment/assessContactAddressMarkup.js +46 -0
  5. package/dist/features/website-assessment/assessCopyrightNotice.d.ts +3 -0
  6. package/dist/features/website-assessment/assessCopyrightNotice.js +33 -0
  7. package/dist/features/website-assessment/assessDuplicateMediaUse.d.ts +3 -0
  8. package/dist/features/website-assessment/assessDuplicateMediaUse.js +55 -0
  9. package/dist/features/website-assessment/assessLegalNotice.d.ts +3 -0
  10. package/dist/features/website-assessment/assessLegalNotice.js +44 -0
  11. package/dist/features/website-assessment/assessPrivacyNotice.d.ts +3 -0
  12. package/dist/features/website-assessment/assessPrivacyNotice.js +58 -0
  13. package/dist/features/website-assessment/assessTrackingConsent.d.ts +3 -0
  14. package/dist/features/website-assessment/assessTrackingConsent.js +63 -0
  15. package/dist/features/website-assessment/createWebsiteAssessmentRuleSet.d.ts +4 -0
  16. package/dist/features/website-assessment/createWebsiteAssessmentRuleSet.js +68 -0
  17. package/dist/features/website-assessment/isWebsiteAssessmentNonNull.d.ts +2 -0
  18. package/dist/features/website-assessment/isWebsiteAssessmentNonNull.js +5 -0
  19. package/dist/features/website-assessment/websiteAssessmentDefinitions.d.ts +3 -0
  20. package/dist/features/website-assessment/websiteAssessmentDefinitions.js +26 -0
  21. package/dist/features/website-assessment/websiteAssessmentResult.d.ts +3 -0
  22. package/dist/features/website-assessment/websiteAssessmentResult.js +21 -0
  23. package/dist/features/website-assessment/websiteAssessmentTestSupport.d.ts +13 -0
  24. package/dist/features/website-assessment/websiteAssessmentTestSupport.js +53 -0
  25. package/dist/features/website-assessment/websiteAssessmentValues.d.ts +7 -0
  26. package/dist/features/website-assessment/websiteAssessmentValues.js +17 -0
  27. package/dist/index.d.ts +2 -0
  28. package/dist/index.js +1 -0
  29. package/dist/types/websiteAssessment.d.ts +35 -0
  30. package/dist/types/websiteAssessment.js +0 -0
  31. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.5.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 9dab376: Add composable website, contact, privacy, tracking, and media assessment rules.
8
+
3
9
  ## 0.4.0
4
10
 
5
11
  ### Minor Changes
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
 
4
4
  # @ankhorage/rules-design
5
5
 
6
- ![license: MIT](././paradox/badges/license.svg) ![npm: v0.4.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![paradox: canonical](././paradox/badges/docs.svg)
6
+ ![license: MIT](././paradox/badges/license.svg) ![npm: v0.5.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![paradox: canonical](././paradox/badges/docs.svg)
7
7
 
8
8
  Declarative catalog for reusable design rules.
9
9
 
@@ -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,3 @@
1
+ import type { AssessmentFact, AssessmentResult } from '../../types/websiteAssessment';
2
+ /*** Reports repeated editorial identities while exempting system-only reuse. */
3
+ export declare function assessDuplicateMediaUse(facts: readonly AssessmentFact[]): AssessmentResult;
@@ -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,2 @@
1
+ /*** Returns normalized assessment values only when every array element has been validated. */
2
+ export declare function validatedWebsiteAssessmentValues<Value>(values: readonly (Value | null)[]): readonly Value[] | null;
@@ -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,3 @@
1
+ import type { AssessmentDefinition } from '../../types/websiteAssessment';
2
+ /*** Declares the fixed website-assessment catalog without allowing host verdicts as facts. */
3
+ export declare const websiteAssessmentDefinitions: readonly AssessmentDefinition[];
@@ -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,7 @@ 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 { createWebsiteAssessmentRuleSet } from './features/website-assessment/createWebsiteAssessmentRuleSet';
7
8
  export type { DesignAssessmentKind, DesignRuleCatalogEntry, DesignRuleCatalogFilter, DesignRuleEvidence, DesignRulePlanningManifest, DesignRuleProfile, DesignRuleProviderManifest, DesignRuleScope, DesignRuleStatus, } from './types/designRuleCatalog';
8
9
  export type { DesignContext, DesignRuleProfileSelection, DesignRuleProvider, DesignRuleProviderOptions, } from './types/designRuleProvider';
10
+ export type { WebsiteAssessmentRuleOptions } from './types/websiteAssessment';
package/dist/index.js CHANGED
@@ -4,3 +4,4 @@ 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 { 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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ankhorage/rules-design",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Declarative catalog for reusable design rules.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/ankhorage/rules-design#readme",