@ankhorage/rules-design 0.9.4 → 0.10.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 CHANGED
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.10.0
4
+
5
+ ### Minor Changes
6
+
7
+ - d6ba244: Define versioned website Card recognition through the canonical Rules evaluator with reusable, inspectable owned-background and shadow signals. Decorative borders and radius no longer imply Cards.
8
+
3
9
  ## 0.9.4
4
10
 
5
11
  ### Patch 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.9.4](././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.10.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,4 @@
1
+ import type { RuleSet } from '@ankhorage/rules';
2
+ import type { WebsiteRecognitionRuleContext } from '../../types/websiteRecognitionRules';
3
+ /*** Declares the versioned, provider-neutral Card predicate in the canonical Rules format. */
4
+ export declare function createWebsiteRecognitionRuleSet(): RuleSet<WebsiteRecognitionRuleContext>;
@@ -0,0 +1,58 @@
1
+ import { websiteStructureEvidence } from './websiteStructureEvidence';
2
+ /*** Declares the versioned, provider-neutral Card predicate in the canonical Rules format. */
3
+ export function createWebsiteRecognitionRuleSet() {
4
+ return {
5
+ id: 'ankhorage.rules-design.website-recognition',
6
+ rules: [cardRecognitionRule],
7
+ };
8
+ }
9
+ const cardRecognitionRule = {
10
+ defaultSeverity: 'info',
11
+ dependencies: [],
12
+ identity: { id: 'design.website-recognition.card', version: '1.0.0' },
13
+ summary: 'A layout child owns a visible background or shadow independent of its layout cell.',
14
+ evaluate: ({ context }) => evaluateCardRecognition(context),
15
+ };
16
+ /*** PASS means Card match; FAIL means no match, not a quality or policy violation. */
17
+ function evaluateCardRecognition(context) {
18
+ const { node, parent, childNodesByParent } = context;
19
+ const evidence = websiteStructureEvidence(node, [], parent);
20
+ if (evidence.availableObservation === null)
21
+ return { findings: [], status: 'INCOMPLETE' };
22
+ if (!isLayoutGroup(parent) ||
23
+ ownsNestedSurfaceLayout(node, childNodesByParent) ||
24
+ !evidence.hasCardSurface)
25
+ return { findings: [], status: 'FAIL' };
26
+ return {
27
+ findings: [
28
+ {
29
+ evidence: {
30
+ signals: evidence.cardSurfaceReasons,
31
+ sourceRef: node.sourceRef,
32
+ },
33
+ message: 'This layout child owns a visible Card surface.',
34
+ ruleId: cardRecognitionRule.identity.id,
35
+ severity: 'info',
36
+ subjects: [{ id: node.sourceRef, kind: 'website-node' }],
37
+ },
38
+ ],
39
+ status: 'PASS',
40
+ };
41
+ }
42
+ /*** Prevents a layout owning separately bounded children from being their Card wrapper. */
43
+ function ownsNestedSurfaceLayout(node, childNodesByParent) {
44
+ if (!isLayoutGroup(node))
45
+ return false;
46
+ return (childNodesByParent.get(node.sourceRef) ?? []).some((child) => isGenericSurfaceNode(child) && websiteStructureEvidence(child, [], node).hasCardSurface);
47
+ }
48
+ /*** Checks measured Flex/Grid layout semantics without creating synthetic layout nodes. */
49
+ function isLayoutGroup(node) {
50
+ if (node === null)
51
+ return false;
52
+ const css = websiteStructureEvidence(node).availableObservation?.css;
53
+ return css !== null && css !== undefined && /grid|flex/u.test(css.display);
54
+ }
55
+ /*** Generic wrappers may own nested surfaces; semantic descendants retain their own type. */
56
+ function isGenericSurfaceNode(node) {
57
+ return ['div', 'span'].includes(node.dom.tagName.toLowerCase());
58
+ }
@@ -1,3 +1,5 @@
1
+ import { evaluateRules } from '@ankhorage/rules';
2
+ import { createWebsiteRecognitionRuleSet } from './createWebsiteRecognitionRuleSet';
1
3
  import { recognizeWebsiteStructureProps } from './recognizeWebsiteStructureProps';
2
4
  import { websiteStructureEvidence } from './websiteStructureEvidence';
3
5
  import { recognizeWebsiteStructureSemanticComponentType } from './websiteStructureSemantics';
@@ -151,25 +153,8 @@ function recognizeComponentType(node, parent, childNodesByParent) {
151
153
  return 'RichText';
152
154
  return websiteStructureEvidence(node).hasVisualRole ? 'Container' : 'Unknown';
153
155
  }
154
- /*** Recognizes one rendered layout child with an independently visible surface boundary as a card. */
156
+ /*** Evaluates the versioned canonical Card rule before committing a primary module type. */
155
157
  function isCard(node, parent, childNodesByParent) {
156
- return (parent !== null &&
157
- isLayoutGroup(parent) &&
158
- websiteStructureEvidence(node, [], parent).hasCardSurface &&
159
- !ownsNestedSurfaceLayout(node, childNodesByParent));
160
- }
161
- /*** Keeps a layout container distinct when it owns independently bounded layout children. */
162
- function ownsNestedSurfaceLayout(node, childNodesByParent) {
163
- if (!isLayoutGroup(node))
164
- return false;
165
- return (childNodesByParent.get(node.sourceRef) ?? []).some((child) => isGenericSurfaceNode(child) && websiteStructureEvidence(child, [], node).hasCardSurface);
166
- }
167
- /*** Limits nested layout ownership to generic wrappers so semantic content never hides its card root. */
168
- function isGenericSurfaceNode(node) {
169
- return ['div', 'span'].includes(node.dom.tagName.toLowerCase());
170
- }
171
- /*** Tests whether a parent has measured Grid or Flex grouping semantics. */
172
- function isLayoutGroup(node) {
173
- const css = websiteStructureEvidence(node).availableObservation?.css;
174
- return css === null || css === undefined ? false : /grid|flex/.test(css.display);
158
+ const evaluation = evaluateRules({ childNodesByParent, node, parent }, createWebsiteRecognitionRuleSet().rules, { scope: { id: node.sourceRef, kind: 'website-node' } });
159
+ return evaluation.results.some((result) => result.status === 'PASS');
175
160
  }
@@ -3,6 +3,7 @@ import type { WebsiteNodeObservation, WebsiteObservedNode } from '@ankhorage/con
3
3
  export declare function websiteStructureEvidence(node: WebsiteObservedNode, children?: readonly WebsiteObservedNode[], parent?: WebsiteObservedNode | null): WebsiteStructureEvidence;
4
4
  interface WebsiteStructureEvidence {
5
5
  readonly availableObservation: WebsiteNodeObservation | null;
6
+ readonly cardSurfaceReasons: readonly string[];
6
7
  readonly hasCardSurface: boolean;
7
8
  readonly hasDividerEvidence: boolean;
8
9
  readonly hasVisualRole: boolean;
@@ -1,8 +1,10 @@
1
1
  /*** Collects complete evidence needed to classify an observed website structure node. */
2
2
  export function websiteStructureEvidence(node, children = [], parent = null) {
3
+ const cardSurfaceReasons = cardSurfaceReasonsForNode(node, parent);
3
4
  return {
4
5
  availableObservation: availableObservation(node),
5
- hasCardSurface: hasCardSurface(node, parent),
6
+ cardSurfaceReasons,
7
+ hasCardSurface: cardSurfaceReasons.length > 0,
6
8
  hasDividerEvidence: hasDividerEvidence(node),
7
9
  hasVisualRole: hasVisualRole(node),
8
10
  isTransparentWrapper: isTransparentWrapper(node, children),
@@ -35,12 +37,13 @@ function isVisibleObservation(observation) {
35
37
  observation.css.visibility !== 'collapse' &&
36
38
  observation.css.opacity !== '0');
37
39
  }
38
- /*** Finds a visible node-owned surface boundary without inferring one from padding or radius. */
39
- function hasCardSurface(node, parent) {
40
- return node.observations.some((observation) => {
41
- const parentObservation = parent === null ? null : observationFor(parent, observation);
42
- return (isVisibleObservation(observation) && hasVisibleSurfaceBoundary(observation, parentObservation));
43
- });
40
+ /*** Finds all independently owned Card-surface signals across visible viewport observations. */
41
+ function cardSurfaceReasonsForNode(node, parent) {
42
+ return [
43
+ ...new Set(node.observations.flatMap((observation) => isVisibleObservation(observation)
44
+ ? cardSurfaceReasonsForObservation(observation, parent === null ? null : observationFor(parent, observation))
45
+ : [])),
46
+ ];
44
47
  }
45
48
  /*** Identifies a visible horizontal or vertical line with independent divider semantics or geometry. */
46
49
  function hasDividerEvidence(node) {
@@ -64,15 +67,29 @@ function hasDividerGeometry(width, height) {
64
67
  const longerSide = Math.max(width, height);
65
68
  return shorterSide <= 4 && longerSide >= 16 && longerSide / Math.max(shorterSide, 1) >= 8;
66
69
  }
67
- /*** Requires one directly visible boundary feature owned by the node. */
68
- function hasVisibleSurfaceBoundary(observation, parentObservation) {
70
+ /*** Lists reusable visual-surface predicates; borders, radius and padding cannot match. */
71
+ function cardSurfaceReasonsForObservation(observation, parentObservation) {
69
72
  const { css } = observation;
70
73
  if (css === null)
71
- return false;
72
- return (hasVisibleBackground(css.backgroundColor, parentObservation?.css?.backgroundColor ?? null) ||
73
- css.backgroundImage !== 'none' ||
74
- (hasNonZeroCssValue(css.borderWidth) && !isTransparentColor(css.borderColor)) ||
75
- hasVisibleBoxShadow(css.boxShadow));
74
+ return [];
75
+ return [
76
+ ...(hasVisibleBackground(css.backgroundColor, parentObservation?.css?.backgroundColor ?? null)
77
+ ? ['background-color']
78
+ : []),
79
+ ...(css.backgroundImage !== 'none' ? ['background-image'] : []),
80
+ ...(hasVisibleBoxShadow(css.boxShadow) ? ['box-shadow'] : []),
81
+ ];
82
+ }
83
+ /*** Shares the same owned-surface predicates with independent divider evidence. */
84
+ function hasOwnedCardSurface(observation, parentObservation) {
85
+ return cardSurfaceReasonsForObservation(observation, parentObservation).length > 0;
86
+ }
87
+ /*** Retains visible border evidence for actual dividers, not card classification. */
88
+ function hasVisibleSurfaceBoundary(observation, parentObservation) {
89
+ const { css } = observation;
90
+ return (css !== null &&
91
+ (hasOwnedCardSurface(observation, parentObservation) ||
92
+ (hasNonZeroCssValue(css.borderWidth) && !isTransparentColor(css.borderColor))));
76
93
  }
77
94
  /*** Compares composited CSS colors so transparent backgrounds remain surface evidence when visible. */
78
95
  function hasVisibleBackground(backgroundColor, parentBackgroundColor) {
package/dist/index.d.ts CHANGED
@@ -7,8 +7,10 @@ export { selectDesignRuleProfile } from './features/provider/selectDesignRulePro
7
7
  export { recognizeWebsiteDesignProperties } from './features/recognition/recognizeWebsiteDesignProperties';
8
8
  export { recognizeWebsiteDocument } from './features/recognition/recognizeWebsiteDocument';
9
9
  export { createWebsiteAssessmentRuleSet } from './features/website-assessment/createWebsiteAssessmentRuleSet';
10
+ export { createWebsiteRecognitionRuleSet } from './features/website-recognition/createWebsiteRecognitionRuleSet';
10
11
  export { recognizeWebsiteStructure } from './features/website-recognition/recognizeWebsiteStructure';
11
12
  export type { DesignAssessmentKind, DesignRuleCatalogEntry, DesignRuleCatalogFilter, DesignRuleEvidence, DesignRulePlanningManifest, DesignRuleProfile, DesignRuleProviderManifest, DesignRuleScope, DesignRuleStatus, } from './types/designRuleCatalog';
12
13
  export type { DesignContext, DesignRuleProfileSelection, DesignRuleProvider, DesignRuleProviderOptions, } from './types/designRuleProvider';
13
14
  export type { WebsiteAssessmentRuleOptions } from './types/websiteAssessment';
14
15
  export type { WebsiteDesignNodeRecognition, WebsiteDesignPropertyObservation, WebsiteDesignRecognition, WebsiteDesignSourceReference, WebsiteDesignTokenCandidate, WebsiteDesignUnresolvedObservation, } from './types/websiteDesignRecognition';
16
+ export type { WebsiteRecognitionRuleContext } from './types/websiteRecognitionRules';
package/dist/index.js CHANGED
@@ -7,4 +7,5 @@ export { selectDesignRuleProfile } from './features/provider/selectDesignRulePro
7
7
  export { recognizeWebsiteDesignProperties } from './features/recognition/recognizeWebsiteDesignProperties';
8
8
  export { recognizeWebsiteDocument } from './features/recognition/recognizeWebsiteDocument';
9
9
  export { createWebsiteAssessmentRuleSet } from './features/website-assessment/createWebsiteAssessmentRuleSet';
10
+ export { createWebsiteRecognitionRuleSet } from './features/website-recognition/createWebsiteRecognitionRuleSet';
10
11
  export { recognizeWebsiteStructure } from './features/website-recognition/recognizeWebsiteStructure';
@@ -0,0 +1,7 @@
1
+ import type { WebsiteObservedNode } from '@ankhorage/contracts/website';
2
+ /*** Source-linked facts used by the canonical Rules evaluation for website modules. */
3
+ export interface WebsiteRecognitionRuleContext {
4
+ readonly childNodesByParent: ReadonlyMap<string, readonly WebsiteObservedNode[]>;
5
+ readonly node: WebsiteObservedNode;
6
+ readonly parent: WebsiteObservedNode | null;
7
+ }
File without changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ankhorage/rules-design",
3
- "version": "0.9.4",
3
+ "version": "0.10.0",
4
4
  "description": "Declarative catalog for reusable design rules.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/ankhorage/rules-design#readme",