|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +// [#28473] A package namespace too long to have a paired customization |
| 4 | +// namespace (ADR-0146 D3) warns at author time. The verdict is |
| 5 | +// `customizationNamespace`'s own (`@objectstack/spec/kernel`), so the boundary |
| 6 | +// cases below are the helper's boundary: 13 characters is silent, 14 warns. |
| 7 | + |
| 8 | +import { describe, expect, it } from 'vitest'; |
| 9 | + |
| 10 | +import { |
| 11 | + CUSTOMIZATION_NAMESPACE_SUFFIX, |
| 12 | + MAX_CUSTOMIZATION_BASE_NAMESPACE_LENGTH, |
| 13 | + customizationNamespace, |
| 14 | +} from '@objectstack/spec/kernel'; |
| 15 | + |
| 16 | +import { AUTHORING_COMMANDS, AUTHORING_RULES, runAuthoringRules } from './authoring-rules.js'; |
| 17 | +import * as indexBarrel from './index.js'; |
| 18 | +import { RULE_EXPLANATIONS } from './rule-explanations.js'; |
| 19 | +import { |
| 20 | + NAMESPACE_NO_CUSTOMIZATION_PAIR, |
| 21 | + validateCustomizationNamespace, |
| 22 | +} from './validate-customization-namespace.js'; |
| 23 | + |
| 24 | +/** 13 characters: the longest base namespace that has a pair namespace. */ |
| 25 | +const AT_LIMIT = 'warehouse_ops'; |
| 26 | +/** 14 characters: one past it. */ |
| 27 | +const PAST_LIMIT = 'warehouse_mgmt'; |
| 28 | + |
| 29 | +const single = (namespace: unknown, id: unknown = 'com.acme.warehouse') => ({ |
| 30 | + manifest: { id, version: '1.0.0', type: 'app', namespace }, |
| 31 | +}); |
| 32 | + |
| 33 | +describe('validateCustomizationNamespace', () => { |
| 34 | + it('the boundary fixtures sit on the helper\'s own boundary', () => { |
| 35 | + expect(AT_LIMIT).toHaveLength(MAX_CUSTOMIZATION_BASE_NAMESPACE_LENGTH); |
| 36 | + expect(PAST_LIMIT).toHaveLength(MAX_CUSTOMIZATION_BASE_NAMESPACE_LENGTH + 1); |
| 37 | + expect(customizationNamespace(AT_LIMIT)).toEqual({ ok: true, value: `${AT_LIMIT}${CUSTOMIZATION_NAMESPACE_SUFFIX}` }); |
| 38 | + expect(customizationNamespace(PAST_LIMIT)).toEqual({ ok: false, reason: 'base_namespace_too_long' }); |
| 39 | + }); |
| 40 | + |
| 41 | + it('is silent on a namespace of 13 characters', () => { |
| 42 | + expect(validateCustomizationNamespace(single(AT_LIMIT))).toEqual([]); |
| 43 | + }); |
| 44 | + |
| 45 | + it('warns on a namespace of 14 characters, at manifest.namespace', () => { |
| 46 | + const findings = validateCustomizationNamespace(single(PAST_LIMIT)); |
| 47 | + expect(findings).toHaveLength(1); |
| 48 | + const [finding] = findings; |
| 49 | + expect(finding.severity).toBe('warning'); |
| 50 | + expect(finding.rule).toBe(NAMESPACE_NO_CUSTOMIZATION_PAIR); |
| 51 | + expect(finding.path).toBe('manifest.namespace'); |
| 52 | + expect(finding.where).toBe('package "com.acme.warehouse"'); |
| 53 | + }); |
| 54 | + |
| 55 | + it('the message names the pair namespace the package cannot have, and the hint the limit', () => { |
| 56 | + const [finding] = validateCustomizationNamespace(single(PAST_LIMIT)); |
| 57 | + expect(finding.message).toContain(`"${PAST_LIMIT}${CUSTOMIZATION_NAMESPACE_SUFFIX}"`); |
| 58 | + expect(finding.message).toContain(`"${PAST_LIMIT}"`); |
| 59 | + expect(finding.hint).toContain(`${MAX_CUSTOMIZATION_BASE_NAMESPACE_LENGTH} characters or fewer`); |
| 60 | + }); |
| 61 | + |
| 62 | + it('is silent when the package is itself a pair: a pair is never paired again', () => { |
| 63 | + const pairNamespace = `${AT_LIMIT}${CUSTOMIZATION_NAMESPACE_SUFFIX}`; |
| 64 | + expect(validateCustomizationNamespace(single(pairNamespace, 'com.acme.warehouse.custom'))).toEqual([]); |
| 65 | + // Control: the same namespace on a base package does warn. |
| 66 | + expect(validateCustomizationNamespace(single(pairNamespace))).toHaveLength(1); |
| 67 | + }); |
| 68 | + |
| 69 | + it('judges only the helper\'s too-long refusal: no namespace, or one the grammar refuses otherwise, is silent', () => { |
| 70 | + expect(validateCustomizationNamespace(single(undefined))).toEqual([]); |
| 71 | + expect(validateCustomizationNamespace(single(''))).toEqual([]); |
| 72 | + // `Warehouse` fails the manifest grammar (uppercase): `os validate`'s refusal, not this rule's. |
| 73 | + expect(customizationNamespace('Warehouse')).toEqual({ ok: false, reason: 'base_namespace_invalid' }); |
| 74 | + expect(validateCustomizationNamespace(single('Warehouse'))).toEqual([]); |
| 75 | + }); |
| 76 | + |
| 77 | + it('still judges the namespace when the manifest carries no id', () => { |
| 78 | + const findings = validateCustomizationNamespace({ manifest: { namespace: PAST_LIMIT } }); |
| 79 | + expect(findings.map((f) => [f.where, f.path])).toEqual([['package manifest', 'manifest.namespace']]); |
| 80 | + }); |
| 81 | + |
| 82 | + it('is silent on a stack with no manifest', () => { |
| 83 | + expect(validateCustomizationNamespace({ objects: [] })).toEqual([]); |
| 84 | + }); |
| 85 | + |
| 86 | + describe('an ADR-0130 artifact: the packages one install delivers', () => { |
| 87 | + const artifact = { |
| 88 | + // The artifact's own wrapper manifest is not a package and is not judged. |
| 89 | + manifest: { id: 'com.acme.bundle', version: '1.0.0', type: 'app', namespace: 'acme_bundle_wrapper' }, |
| 90 | + packages: [ |
| 91 | + { manifest: { id: 'com.acme.core', version: '1.0.0', type: 'app', namespace: AT_LIMIT } }, |
| 92 | + { manifest: { id: 'com.acme.orders', version: '1.0.0', type: 'app', namespace: PAST_LIMIT } }, |
| 93 | + ], |
| 94 | + }; |
| 95 | + |
| 96 | + it('judges each packages[] body, at its own path, and never the wrapper manifest', () => { |
| 97 | + const findings = validateCustomizationNamespace(artifact); |
| 98 | + expect(findings.map((f) => [f.where, f.path])).toEqual([ |
| 99 | + ['package "com.acme.orders"', 'packages[1].manifest.namespace'], |
| 100 | + ]); |
| 101 | + }); |
| 102 | + |
| 103 | + // The CLI's per-package pass (`runPerPackageAuthoringRules`) hands each body |
| 104 | + // back as `{ ...body, manifest: body, packages }` and drops any finding the |
| 105 | + // union run already reported (same rule, where, message and path). This |
| 106 | + // rule reads `packages[]` whenever it is present, so the per-package view |
| 107 | + // yields exactly the union's findings and adds no second copy of one. |
| 108 | + it('the per-package view of each body yields the union run\'s findings, byte for byte', () => { |
| 109 | + const union = validateCustomizationNamespace(artifact); |
| 110 | + for (const entry of artifact.packages) { |
| 111 | + const asStack = { ...entry.manifest, manifest: entry.manifest, packages: artifact.packages }; |
| 112 | + expect(validateCustomizationNamespace(asStack)).toEqual(union); |
| 113 | + } |
| 114 | + }); |
| 115 | + }); |
| 116 | +}); |
| 117 | + |
| 118 | +describe('validateCustomizationNamespace in the authoring registry', () => { |
| 119 | + it('is registered as an advisory rule on all three commands, CLI surface only', () => { |
| 120 | + const entry = AUTHORING_RULES.find((r) => r.name === 'validateCustomizationNamespace'); |
| 121 | + expect(entry).toBeDefined(); |
| 122 | + expect(entry!.tier).toBe('advisory'); |
| 123 | + expect([...entry!.commands].sort()).toEqual([...AUTHORING_COMMANDS].sort()); |
| 124 | + expect(entry!.surfaces).toEqual(['cli']); |
| 125 | + }); |
| 126 | + |
| 127 | + it('reaches every authoring command\'s findings as a warning', () => { |
| 128 | + const stack = single(PAST_LIMIT); |
| 129 | + for (const command of AUTHORING_COMMANDS) { |
| 130 | + const findings = runAuthoringRules(command, { normalized: stack, parsed: stack }) |
| 131 | + .filter((f) => f.rule === NAMESPACE_NO_CUSTOMIZATION_PAIR); |
| 132 | + expect(findings.map((f) => [f.severity, f.path]), command).toEqual([['warning', 'manifest.namespace']]); |
| 133 | + } |
| 134 | + }); |
| 135 | + |
| 136 | + it('exports its rule id from the root barrel and has an os explain entry', () => { |
| 137 | + expect(indexBarrel.NAMESPACE_NO_CUSTOMIZATION_PAIR).toBe(NAMESPACE_NO_CUSTOMIZATION_PAIR); |
| 138 | + expect(RULE_EXPLANATIONS[NAMESPACE_NO_CUSTOMIZATION_PAIR]?.rule).toBe(NAMESPACE_NO_CUSTOMIZATION_PAIR); |
| 139 | + }); |
| 140 | +}); |
![objectstack-fleet[bot]](https://avatars.githubusercontent.com/u/254823548?v=4&size=40){kind=avatar}
0 commit comments