@ankhorage/rules-design 0.3.3 → 0.4.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.4.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 416c5b3: Register all Design rule families and the C.R.A.P. composition graph through a configured provider factory, with executable C.R.A.P. and 60-30-10 profile selection.
8
+
3
9
  ## 0.3.3
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.3.3](././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.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)
7
7
 
8
8
  Declarative catalog for reusable design rules.
9
9
 
@@ -23,7 +23,7 @@ ankh rules-design --help
23
23
 
24
24
  ### Evaluate Design Evidence
25
25
 
26
- Register the Design provider with the generic Rules evaluator.
26
+ Register the configured Design provider and evaluate a named profile.
27
27
 
28
28
  ```ts
29
29
  import { createRuleRegistry, evaluateRules } from '@ankhorage/rules';
@@ -37,3 +37,4 @@ 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
+ - [selectDesignRuleProfile sequence](././paradox/diagrams/sequences/select-design-rule-profile.mmd)
@@ -1,3 +1,3 @@
1
1
  import type { DesignRuleProviderManifest } from '../../types/designRuleCatalog';
2
- /*** Declares the released MIT provider surface without exposing unclassified planned rules. */
2
+ /*** Declares every central-provider rule identity published through the released package surface. */
3
3
  export declare const designRuleProviderManifest: DesignRuleProviderManifest;
@@ -1,7 +1,8 @@
1
- /*** Declares the released MIT provider surface without exposing unclassified planned rules. */
1
+ import { designRuleCatalog } from './designRuleCatalog';
2
+ /*** Declares every central-provider rule identity published through the released package surface. */
2
3
  export const designRuleProviderManifest = {
3
4
  packageName: '@ankhorage/rules-design',
4
5
  providerId: 'ankhorage.rules-design',
5
- publishedRuleIds: [],
6
+ publishedRuleIds: designRuleCatalog.map((entry) => entry.id),
6
7
  schemaVersion: '1',
7
8
  };
@@ -40,7 +40,7 @@ function createColorPolicyRule(ruleId, policy) {
40
40
  }
41
41
  /*** Assesses each normalized raw observation with the rule-specific trusted policy. */
42
42
  function evaluateColorPolicyRule(ruleId, policy, input) {
43
- const facts = (input.context.facts ?? []).filter((fact) => fact.kind === ruleId && sameScope(fact, input));
43
+ const facts = input.context.facts.filter((fact) => fact.kind === ruleId && sameScope(fact, input));
44
44
  const observations = facts.map((fact) => ({ fact, observation: parseObservation(fact) }));
45
45
  if (facts.length === 0 || observations.some(({ observation }) => observation === undefined))
46
46
  return incomplete(ruleId, input);
@@ -20,7 +20,7 @@ function createUsageRule(policy) {
20
20
  }
21
21
  /*** Keeps exact rule scope, breakpoint, theme, and coverage measurements isolated. */
22
22
  function evaluateUsage(input, policy) {
23
- const facts = (input.context.facts ?? []).filter((fact) => fact.kind === 'design.color.usage-distribution' && exactScope(fact, input));
23
+ const facts = input.context.facts.filter((fact) => fact.kind === 'design.color.usage-distribution' && exactScope(fact, input));
24
24
  const observations = facts.map(parseObservation);
25
25
  if (facts.length === 0 || observations.some((value) => value === undefined))
26
26
  return incomplete(input, 'No complete normalized rendered-area fact was supplied.');
@@ -0,0 +1,4 @@
1
+ import type { Rule } from '@ankhorage/rules';
2
+ import type { DesignContext } from '../../types/designRuleProvider';
3
+ /*** Creates the five C.R.A.P. composition nodes from the registered atomic Design rules. */
4
+ export declare function createDesignCrapRules(atomicRules: readonly Rule<DesignContext>[]): readonly Rule<DesignContext>[];
@@ -0,0 +1,51 @@
1
+ /*** Creates the five C.R.A.P. composition nodes from the registered atomic Design rules. */
2
+ export function createDesignCrapRules(atomicRules) {
3
+ const atomicRuleIds = atomicRules.map((rule) => rule.identity.id);
4
+ return crapDefinitions(atomicRuleIds).map(createDesignCrapRule);
5
+ }
6
+ /*** Declares C.R.A.P. dependencies from canonical atomic IDs without reimplementing group rules. */
7
+ function crapDefinitions(atomicRuleIds) {
8
+ const children = (prefixes) => atomicRuleIds.filter((id) => prefixes.some((prefix) => id.startsWith(prefix)));
9
+ return [
10
+ definition('design.crap.contrast', children(['design.color.', 'design.contrast.']), 'Compose Color and Contrast results into the C.R.A.P. contrast principle.'),
11
+ definition('design.crap.repetition', children(['design.repetition.', 'design.typography.']), 'Compose Repetition and Typography results into the C.R.A.P. repetition principle.'),
12
+ definition('design.crap.alignment', children(['design.alignment.', 'design.layout.', 'design.responsive.']), 'Compose Alignment, Layout, and Responsive results into the C.R.A.P. alignment principle.'),
13
+ definition('design.crap.proximity', children(['design.spacing.', 'design.proximity.']), 'Compose Spacing and Proximity results into the C.R.A.P. proximity principle.'),
14
+ definition('design.crap', [
15
+ 'design.crap.contrast',
16
+ 'design.crap.repetition',
17
+ 'design.crap.alignment',
18
+ 'design.crap.proximity',
19
+ ], 'Compose exactly four C.R.A.P. principle results without calculating a design score.'),
20
+ ];
21
+ }
22
+ /*** Defines one stable composite identity and its evaluator-owned dependency edges. */
23
+ function definition(id, dependencies, summary) {
24
+ return { dependencies, id, summary };
25
+ }
26
+ /*** Adapts one declared C.R.A.P. node to the generic dependency-result contract. */
27
+ function createDesignCrapRule(definition) {
28
+ return {
29
+ defaultSeverity: 'warning',
30
+ dependencies: definition.dependencies.map((ruleId) => ({ ruleId })),
31
+ evaluate: (input) => evaluateDesignCrapRule(definition, input),
32
+ identity: { id: definition.id, version: '1.0.0' },
33
+ summary: definition.summary,
34
+ };
35
+ }
36
+ /*** Reports failed child principles as advisory findings while the engine propagates incomplete ones. */
37
+ function evaluateDesignCrapRule(definition, input) {
38
+ const failedChildren = input.dependencyResults.filter((result) => result.status === 'FAIL');
39
+ return failedChildren.length === 0
40
+ ? { findings: [], status: 'PASS' }
41
+ : {
42
+ findings: failedChildren.map((result) => ({
43
+ evidence: { childRuleId: result.rule.id, childStatus: result.status },
44
+ message: `${definition.id} includes a failed child rule: ${result.rule.id}.`,
45
+ ruleId: definition.id,
46
+ severity: 'warning',
47
+ subjects: [{ id: input.scope.id, kind: input.scope.kind }],
48
+ })),
49
+ status: 'FAIL',
50
+ };
51
+ }
@@ -1,3 +1,3 @@
1
- import type { DesignRuleProvider } from '../../types/designRuleProvider';
2
- /*** Exposes the reusable Design provider through the generic Rules RuleSet contract. */
3
- export declare const designRuleProvider: DesignRuleProvider;
1
+ import type { DesignRuleProvider, DesignRuleProviderOptions } from '../../types/designRuleProvider';
2
+ /*** Creates the complete registered Design provider from its explicit group-local policies. */
3
+ export declare function createDesignRuleProvider(options: DesignRuleProviderOptions): DesignRuleProvider;
@@ -1,9 +1,37 @@
1
- /*** Exposes the reusable Design provider through the generic Rules RuleSet contract. */
2
- export const designRuleProvider = {
3
- id: 'ankhorage.rules-design',
4
- packageName: '@ankhorage/rules-design',
5
- ruleSet: {
1
+ import { createAccessibilityRules } from '../accessibility/createAccessibilityRules';
2
+ import { createAlignmentRules } from '../alignment/createAlignmentRules';
3
+ import { createColorRuleSet } from '../color/createColorRuleSet';
4
+ import { createContrastRules } from '../contrast/createContrastRules';
5
+ import { createMediaRuleSet } from '../media/createMediaRuleSet';
6
+ import { createRepetitionRules } from '../repetition/createRepetitionRules';
7
+ import { createResponsiveRules } from '../responsive/createResponsiveRules';
8
+ import { createSpacingProximityRuleSet } from '../spacing-proximity/createSpacingProximityRuleSet';
9
+ import { createTypographyRuleSet } from '../typography/createTypographyRuleSet';
10
+ import { createDesignCrapRules } from './createDesignCrapRules';
11
+ /*** Creates the complete registered Design provider from its explicit group-local policies. */
12
+ export function createDesignRuleProvider(options) {
13
+ const atomicRules = createAtomicRules(options);
14
+ return {
6
15
  id: 'ankhorage.rules-design',
7
- rules: [],
8
- },
9
- };
16
+ packageName: '@ankhorage/rules-design',
17
+ ruleSet: {
18
+ id: 'ankhorage.rules-design',
19
+ rules: [...atomicRules, ...createDesignCrapRules(atomicRules)],
20
+ },
21
+ };
22
+ }
23
+ /*** Collects each independently owned atomic contribution at the central registration boundary. */
24
+ function createAtomicRules(options) {
25
+ const ruleSets = [
26
+ createColorRuleSet(options.color),
27
+ { id: 'ankhorage.rules-design.contrast', rules: createContrastRules() },
28
+ createTypographyRuleSet(options.typography),
29
+ createSpacingProximityRuleSet(),
30
+ { id: 'ankhorage.rules-design.alignment', rules: createAlignmentRules(options.alignment) },
31
+ { id: 'ankhorage.rules-design.repetition', rules: createRepetitionRules() },
32
+ { id: 'ankhorage.rules-design.responsive', rules: createResponsiveRules() },
33
+ { id: 'ankhorage.rules-design.accessibility', rules: createAccessibilityRules() },
34
+ createMediaRuleSet(options.media),
35
+ ];
36
+ return ruleSets.flatMap((ruleSet) => ruleSet.rules);
37
+ }
@@ -0,0 +1,3 @@
1
+ import type { DesignRuleProfileSelection } from '../../types/designRuleProvider';
2
+ /*** Resolves one named profile independently from the Rule IDs it selects. */
3
+ export declare function selectDesignRuleProfile(profileId: string): DesignRuleProfileSelection;
@@ -0,0 +1,12 @@
1
+ import { designRuleProfiles } from '../catalog/designRuleProfiles';
2
+ /*** Resolves one named profile independently from the Rule IDs it selects. */
3
+ export function selectDesignRuleProfile(profileId) {
4
+ const profile = designRuleProfiles.find((candidate) => candidate.id === profileId);
5
+ if (profile === undefined)
6
+ throw new RangeError(`Unknown Design profile: ${profileId}.`);
7
+ return { profileId: profile.id, selection: selection(profile.rootRuleIds) };
8
+ }
9
+ /*** Creates a fresh generic selection so callers cannot mutate catalog-owned profile declarations. */
10
+ function selection(rootRuleIds) {
11
+ return { rootRuleIds: [...rootRuleIds] };
12
+ }
@@ -1,4 +1,4 @@
1
- import type { FactEnvelope } from '@ankhorage/contracts/rules';
2
1
  import type { RuleSet } from '@ankhorage/rules';
2
+ import type { DesignContext } from '../../types/designRuleProvider';
3
3
  /*** Creates the independently owned Spacing and Proximity Rules contribution. */
4
- export declare function createSpacingProximityRuleSet(): RuleSet<readonly FactEnvelope[]>;
4
+ export declare function createSpacingProximityRuleSet(): RuleSet<DesignContext>;
@@ -29,7 +29,7 @@ function createRule(definition) {
29
29
  return {
30
30
  defaultSeverity: definition.severity,
31
31
  dependencies: [],
32
- evaluate: ({ context, scope }) => evaluate(context, definition, scope),
32
+ evaluate: ({ context, scope }) => evaluate(context.facts, definition, scope),
33
33
  facets: facets(definition),
34
34
  identity: { id: definition.id, version: '1.0.0' },
35
35
  requiredCapabilities: [definition.capability],
@@ -72,7 +72,7 @@ function definition(id, summary, evaluate, measurementsComplete, severity = 'err
72
72
  }
73
73
  /*** Reads scoped Typography facts without discarding malformed or unavailable evidence. */
74
74
  function typographyEvidence(context, capability, scope) {
75
- const factObservations = (context.facts ?? [])
75
+ const factObservations = context.facts
76
76
  .filter((fact) => fact.kind === capability && fact.scope.id === scope.id && fact.scope.kind === scope.kind)
77
77
  .map((fact) => fact.status === 'available' ? parseTypographyObservation(fact.value, fact.id) : []);
78
78
  return [
package/dist/index.d.ts CHANGED
@@ -2,6 +2,7 @@ export { designRuleCatalog } from './features/catalog/designRuleCatalog';
2
2
  export { designRuleProfiles } from './features/catalog/designRuleProfiles';
3
3
  export { designRuleProviderManifest } from './features/catalog/designRuleProviderManifest';
4
4
  export { filterDesignRuleCatalog } from './features/catalog/filterDesignRuleCatalog';
5
- export { designRuleProvider } from './features/provider/designRuleProvider';
5
+ export { createDesignRuleProvider } from './features/provider/designRuleProvider';
6
+ export { selectDesignRuleProfile } from './features/provider/selectDesignRuleProfile';
6
7
  export type { DesignAssessmentKind, DesignRuleCatalogEntry, DesignRuleCatalogFilter, DesignRuleEvidence, DesignRulePlanningManifest, DesignRuleProfile, DesignRuleProviderManifest, DesignRuleScope, DesignRuleStatus, } from './types/designRuleCatalog';
7
- export type { DesignContext, DesignEvidence, DesignRuleProvider } from './types/designRuleProvider';
8
+ export type { DesignContext, DesignRuleProfileSelection, DesignRuleProvider, DesignRuleProviderOptions, } from './types/designRuleProvider';
package/dist/index.js CHANGED
@@ -2,4 +2,5 @@ export { designRuleCatalog } from './features/catalog/designRuleCatalog';
2
2
  export { designRuleProfiles } from './features/catalog/designRuleProfiles';
3
3
  export { designRuleProviderManifest } from './features/catalog/designRuleProviderManifest';
4
4
  export { filterDesignRuleCatalog } from './features/catalog/filterDesignRuleCatalog';
5
- export { designRuleProvider } from './features/provider/designRuleProvider';
5
+ export { createDesignRuleProvider } from './features/provider/designRuleProvider';
6
+ export { selectDesignRuleProfile } from './features/provider/selectDesignRuleProfile';
@@ -1,14 +1,19 @@
1
1
  import type { FactEnvelope } from '@ankhorage/contracts/rules';
2
- import type { RuleSet } from '@ankhorage/rules';
3
- /*** One provider-neutral design observation supplied by a Design context. */
4
- export interface DesignEvidence {
5
- readonly id: string;
6
- readonly kind: string;
7
- }
2
+ import type { RuleSelection, RuleSet } from '@ankhorage/rules';
3
+ import type { AlignmentRuleOptions } from '../features/alignment/createAlignmentRules';
4
+ import type { ColorRulePolicy } from '../features/color/createColorRuleSet';
5
+ import type { MediaRuleOptions } from '../features/media/createMediaRuleSet';
6
+ import type { TypographyRulePolicy } from './typography';
8
7
  /*** The minimal context shared by Design rules without prescribing its source. */
9
8
  export interface DesignContext {
10
- readonly evidence: readonly DesignEvidence[];
11
- readonly facts?: readonly FactEnvelope[];
9
+ readonly facts: readonly FactEnvelope[];
10
+ }
11
+ /*** Configures the group-local policy needed to create one complete Design provider. */
12
+ export interface DesignRuleProviderOptions {
13
+ readonly alignment?: AlignmentRuleOptions;
14
+ readonly color: ColorRulePolicy;
15
+ readonly media?: MediaRuleOptions;
16
+ readonly typography: TypographyRulePolicy;
12
17
  }
13
18
  /*** The public identity and generic Rules contribution for the Design provider. */
14
19
  export interface DesignRuleProvider {
@@ -16,3 +21,8 @@ export interface DesignRuleProvider {
16
21
  readonly packageName: '@ankhorage/rules-design';
17
22
  readonly ruleSet: RuleSet<DesignContext>;
18
23
  }
24
+ /*** Maps a named Design profile to the generic Rules engine selection contract. */
25
+ export interface DesignRuleProfileSelection {
26
+ readonly profileId: string;
27
+ readonly selection: RuleSelection;
28
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ankhorage/rules-design",
3
- "version": "0.3.3",
3
+ "version": "0.4.0",
4
4
  "description": "Declarative catalog for reusable design rules.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/ankhorage/rules-design#readme",