@orkestrel/scaffold 0.0.103 → 0.0.104

package/dist/host/tests/config.test.ts

@@ -323,16 +323,27 @@ describe('selected faces', () => {
 		}
 		const script =
 			'vite build --config configs/src/vite.styles.config.ts && vite build --config configs/src/vite.themes.config.ts'
-		expect(inspectSheetConfiguration(project, script)).toEqual([])
-		expect(
-			inspectSheetConfiguration(
-				{ test: { ...project.test, setupFiles: ['./tests/setup.ts', './tests/setupBrowser.ts'] } },
-				script,
-			),
-		).toContain('./tests/setupStyles.ts')
-		expect(
-			inspectSheetConfiguration(project, script.split(' && ').reverse().join(' && ')),
-		).toContain('themes order')
+		const scratch = createPolicyScratch({ prefix: 'config-sheet-setup-' })
+		const withoutStyles = {
+			test: { ...project.test, setupFiles: ['./tests/setup.ts', './tests/setupBrowser.ts'] },
+		}
+		try {
+			expect(inspectSheetConfiguration(withoutStyles, script, scratch.path)).toEqual([])
+			scratch.write('tests/setupStyles.ts', 'export {}\n')
+			expect(inspectSheetConfiguration(project, script, scratch.path)).toEqual([])
+			expect(inspectSheetConfiguration(withoutStyles, script, scratch.path)).toContain(
+				'./tests/setupStyles.ts',
+			)
+			expect(
+				inspectSheetConfiguration(
+					project,
+					script.split(' && ').reverse().join(' && '),
+					scratch.path,
+				),
+			).toContain('themes order')
+		} finally {
+			scratch.destroy()
+		}
 	})
 
 	it('resolves showcase and journey modes for every occupied application', async () => {
@@ -707,19 +718,24 @@ describe('root configuration', () => {
 			)
 				.filter(([, path]) => existsSync(resolve(POLICY_ROOT, path)))
 				.map(([label, , include, setup]): [string, PolicyProject] => [label, { include, setup }]),
-			...['policy', 'config', 'guides', 'conformance', 'distribution', 'integration']
-				.filter((label) => existsSync(resolve(POLICY_ROOT, `tests/${label}.test.ts`)))
+			...['policy', 'config', 'guides', 'conformance', 'tree', 'distribution', 'integration']
+				.filter((label) => readdirSync(resolve(POLICY_ROOT, 'tests')).includes(`${label}.test.ts`))
 				.map((label): [string, PolicyProject] => [
 					label,
 					{
 						include: `tests/${label}.test.ts`,
 						setup: [
 							'./tests/setup.ts',
-							...(label === 'conformance' ? ['./tests/setupServer.ts'] : []),
+							...(label === 'conformance' || label === 'tree' ? ['./tests/setupServer.ts'] : []),
 							...(label === 'integration' &&
 							(collectSheets(POLICY_ROOT).length > 0 ||
 								existsSync(resolve(POLICY_ROOT, 'src/styles/themes/index.scss')))
-								? ['./tests/setupBrowser.ts', './tests/setupStyles.ts']
+								? [
+										'./tests/setupBrowser.ts',
+										...(existsSync(resolve(POLICY_ROOT, 'tests/setupStyles.ts'))
+											? ['./tests/setupStyles.ts']
+											: []),
+									]
 								: []),
 						],
 					},
@@ -910,8 +926,8 @@ describe('root configuration', () => {
 		// before its result is read. Extra factories are ignored without validating their result shape.
 		expect(extraLoads).toStrictEqual([])
 		for (const [label, project] of expected) expect(configured.get(label)).toStrictEqual(project)
-		for (const label of ['setup', 'setup:browser']) {
-			const name = label === 'setup' ? 'setup' : 'setupBrowser'
+		for (const label of ['setup', 'setup:browser', 'tree']) {
+			const name = label === 'setup:browser' ? 'setupBrowser' : label
 			expect(projects.some((entry) => typeof entry === 'function' && entry.name === name)).toBe(
 				expected.has(label),
 			)
@@ -1281,6 +1297,7 @@ describe('root configuration', () => {
 		const distribution = Object.getOwnPropertyDescriptor(scripts, 'test:distribution')?.value
 		const integration = Object.getOwnPropertyDescriptor(scripts, 'test:integration')?.value
 		const conformance = Object.getOwnPropertyDescriptor(scripts, 'test:conformance')?.value
+		const tree = Object.getOwnPropertyDescriptor(scripts, 'test:tree')?.value
 		const service = Object.getOwnPropertyDescriptor(scripts, 'test:service')?.value
 		const studies = Object.getOwnPropertyDescriptor(scripts, 'test:studies')?.value
 		const publish = Object.getOwnPropertyDescriptor(scripts, 'prepublishOnly')?.value
@@ -1307,6 +1324,7 @@ describe('root configuration', () => {
 		expect(registered.has('config')).toBe(true)
 		expect(registered.has('control')).toBe(false)
 		const hasConformance = registered.has('conformance')
+		const hasTree = registered.has('tree')
 		const hasDistribution = registered.has('distribution')
 		const hasService = registered.has('service')
 		const hasStudies = registered.has('studies')
@@ -1349,6 +1367,13 @@ describe('root configuration', () => {
 		expect(typeof test === 'string' && test.includes('npm run test:conformance')).toBe(
 			hasConformance,
 		)
+		expect(tree).toBe(
+			hasTree
+				? 'vitest run --config vite.config.ts --no-cache --reporter=dot --project tree'
+				: undefined,
+		)
+		expect(typeof test === 'string' && test.includes('npm run test:tree')).toBe(hasTree)
+		expect(typeof publish === 'string' && publish.includes('npm run test:tree')).toBe(false)
 		expect(service).toBe(
 			hasService
 				? 'vitest run --config vite.config.ts --no-cache --reporter=dot --project service'
@@ -2916,72 +2941,89 @@ createSomething({
 					const pattern = readConfigRecord(patternValue)
 					const message = pattern.message
 					if (typeof message !== 'string') throw new Error('Missing pattern message')
-					const listed: ReadonlyArray<readonly [string, boolean]> = message.includes('URL schemes')
-						? [
-								['https://host/x', true],
-								['data:text/plain,x', true],
-								['node:fs', false],
-								['n:entry', true],
-								['no:entry', true],
-								['nod:entry', true],
-								['nodea:entry', true],
-								['1bad:entry', false],
-								['./data:entry', false],
-							]
-						: message.includes('noncanonical dot')
+					const alias = /@src\/(core|browser|server) alias/u.exec(message)?.[1]
+					const listed: ReadonlyArray<readonly [string, boolean]> =
+						alias !== undefined
 							? [
-									['../core/../server/index.js', true],
-									['../core/./index.js', true],
-									['../core/index.js', false],
-									['./index.js', false],
-									['../../core/index.js', false],
-									['.../../index.js', true],
-									['.name/../index.js', true],
+									[`../${alias}/index.js`, true],
+									[`../../${alias}/types.js`, true],
+									[`../../src/${alias}/index.js`, true],
+									[`../${alias}`, true],
+									[`../${alias}/`, true],
+									[`../${alias}?raw`, true],
+									[`../${alias}#fragment`, true],
+									[`@src/${alias}`, false],
+									[`./${alias}/index.js`, false],
+									[`../${alias}x/index.js`, false],
+									[`../${alias}.ext/index.js`, false],
 								]
-							: message.includes('sibling sheet')
+							: message.includes('URL schemes')
 								? [
-										['@src/print', true],
-										['../print/index.js', true],
-										['@src/core', false],
-										['@src/browser', false],
-										['@src/vue', false],
-										['@app/core', false],
-										['@app/browser', false],
-										['@src/corex', true],
-										['@src/', true],
-										['../src/print/index.js', true],
-										['../browser?x', true],
-										['../print.ext/index.js', false],
-										...(Array.isArray(block.files) &&
-										block.files.some(
-											(file: unknown) => typeof file === 'string' && file.startsWith('app/vue/'),
-										)
-											? [['@app/print', true] as const]
-											: []),
-									]
-								: [
-										[
-											message.includes('absolute paths')
-												? '/machine/module.js'
-												: message.includes('normalized traversal')
-													? './../core/index.js'
-													: message.includes('forward slashes')
-														? '..\\core\\index.js'
-														: message.includes('compiler API')
-															? 'typescript'
-															: message.includes('private app')
-																? '@app/core'
-																: message.includes('stylesheets')
-																	? './index.css'
-																	: message.includes('host-independent') ||
-																		  message.includes('Node or server')
-																		? 'node:fs'
-																		: message.includes('Vue extension')
-																			? '@src/vue'
-																			: '@src/browser',
-											true,
-										],
+										['https://host/x', true],
+										['data:text/plain,x', true],
+										['node:fs', false],
+										['n:entry', true],
+										['no:entry', true],
+										['nod:entry', true],
+										['nodea:entry', true],
+										['1bad:entry', false],
+										['./data:entry', false],
 									]
+								: message.includes('noncanonical dot')
+									? [
+											['../core/../server/index.js', true],
+											['../core/./index.js', true],
+											['../core/index.js', false],
+											['./index.js', false],
+											['../../core/index.js', false],
+											['.../../index.js', true],
+											['.name/../index.js', true],
+										]
+									: message.includes('sibling sheet')
+										? [
+												['@src/print', true],
+												['../print/index.js', true],
+												['@src/core', false],
+												['@src/browser', false],
+												['@src/vue', false],
+												['@app/core', false],
+												['@app/browser', false],
+												['@src/corex', true],
+												['@src/', true],
+												['../src/print/index.js', true],
+												['../browser?x', true],
+												['../print.ext/index.js', false],
+												...(Array.isArray(block.files) &&
+												block.files.some(
+													(file: unknown) =>
+														typeof file === 'string' && file.startsWith('app/vue/'),
+												)
+													? [['@app/print', true] as const]
+													: []),
+											]
+										: [
+												[
+													message.includes('absolute paths')
+														? '/machine/module.js'
+														: message.includes('normalized traversal')
+															? './../core/index.js'
+															: message.includes('forward slashes')
+																? '..\\core\\index.js'
+																: message.includes('compiler API')
+																	? 'typescript'
+																	: message.includes('private app')
+																		? '@app/core'
+																		: message.includes('stylesheets')
+																			? './index.css'
+																			: message.includes('host-independent') ||
+																				  message.includes('Node or server')
+																				? 'node:fs'
+																				: message.includes('Vue extension')
+																					? '@src/vue'
+																					: '@src/browser',
+													true,
+												],
+											]
 					const face =
 						message.includes('another styles face') && typeof pattern.regex === 'string'
 							? /@src\/(bootstrap|tailwindcss|styles)\(/u.exec(pattern.regex)?.[1]
@@ -3135,21 +3177,34 @@ createSomething({
 										]),
 								]
 							: []),
+						...(['src/browser', 'src/server', 'src/vue', 'src/bin'].includes(owner)
+							? ['../core/index.js', '../../src/core/index.js']
+							: []),
+						...(owner === 'src/vue' ? ['../browser/index.js', '../../src/browser/index.js'] : []),
+						...(owner === 'src/bin' ? ['../server/index.js', '../../src/server/index.js'] : []),
 					]
 					const admitted = [
 						...(owner.endsWith('/vue')
 							? [
 									'@src/core',
 									'@src/browser',
-									'../core/index.js',
-									'../browser/index.js',
 									'vue',
 									'@vue/runtime-core',
 									...(owner.startsWith('app/')
-										? ['@app/core', '@app/browser', '@src/vue', '../../src/vue/index.js']
+										? [
+												'@app/core',
+												'@app/browser',
+												'@src/vue',
+												'../../src/vue/index.js',
+												'../browser/index.js',
+											]
 										: []),
 								]
 							: ['@src/core']),
+						...(['src/browser', 'src/server', 'src/vue', 'src/bin'].includes(owner)
+							? []
+							: ['../core/index.js']),
+						...(owner === 'src/bin' ? ['@src/server'] : []),
 						...(sheet
 							? [
 									...faces
@@ -3177,7 +3232,6 @@ createSomething({
 								[
 									...admitted,
 									'./index.js',
-									'../core/index.js',
 									...(owner.endsWith('/server') || owner === 'src/bin' ? ['node:fs'] : []),
 								],
 								false,

package/dist/host/tests/policy.test.ts

@@ -88,10 +88,23 @@ describe('surface policy controls', () => {
 		}
 	})
 
-	it('refuses a target catalog row absent from the installed guides', () => {
+	it('ignores a target catalog row the installed scaffold does not stage', () => {
 		const scratch = createPolicySurfaceFixture()
 		try {
 			scratch.write(POLICY_CATALOG_FILE, createPolicyCatalog(['other', 'sample', 'uncovered']))
+			expect(inspectPolicyWorkspace(scratch.path)).toEqual([])
+		} finally {
+			scratch.destroy()
+		}
+	})
+
+	it('refuses a staged catalog row absent from the installed guides', () => {
+		const scratch = createPolicySurfaceFixture()
+		try {
+			scratch.write(
+				`${POLICY_SURFACE_HOST}/${POLICY_SURFACE_CATALOG}`,
+				createPolicyCatalog(['other', 'sample', 'uncovered']),
+			)
 			expect(inspectPolicyWorkspace(scratch.path)).toEqual([
 				{
 					rule: 'surface',
@@ -212,6 +225,31 @@ describe('surface policy controls', () => {
 		}
 	})
 
+	it('excludes the distribution harness in an adopter while reporting target-owned collisions', () => {
+		const scratch = createPolicySurfaceFixture()
+		try {
+			scratch.write('tests/setupDistribution.ts', 'export function readShared() {}\n')
+			expect(inspectPolicyWorkspace(scratch.path)).toEqual([])
+			scratch.write('tests/setupExtra.ts', 'export function readShared() {}\n')
+			expect(inspectPolicyWorkspace(scratch.path)).toEqual([
+				{
+					rule: 'mirror',
+					path: 'tests/setupExtra.ts',
+					message:
+						'exporting setup module requires its sibling proof or an import from tests/setup.test.ts',
+				},
+				{
+					rule: 'surface',
+					path: 'tests/setupExtra.ts',
+					line: 1,
+					message: 'surface name belongs to one package: readShared (other)',
+				},
+			])
+		} finally {
+			scratch.destroy()
+		}
+	})
+
 	it('refuses a barrel statement outside the relative star-export population', () => {
 		const scratch = createPolicySurfaceFixture()
 		try {

package/dist/host/tests/setupPolicy.ts

@@ -5,7 +5,7 @@ import {
 	hasCanonicalSegments,
 	resolveLink,
 } from '@orkestrel/guide'
-import { BASE_DEV_DEPENDENCIES, HOST_PATHS } from '@orkestrel/scaffold'
+import { BASE_DEV_DEPENDENCIES, DISTRIBUTION_SETUP_PATH, HOST_PATHS } from '@orkestrel/scaffold'
 import { spawnSync } from 'node:child_process'
 import { createRequire } from 'node:module'
 import {
@@ -172,7 +172,7 @@ export interface PolicyProject {
 	readonly setup: readonly string[]
 }
 
-/** Describes one physical negative control, including the population boundary it attacks. */
+/** Describes one physical negative control, including the population boundary it tests. */
 export interface PolicyControl {
 	readonly label: string
 	readonly membership: string
@@ -1104,9 +1104,28 @@ export function inspectPolicyMirrors(root: string): readonly PolicyViolation[] {
 	return [...inspectPolicyMirrorPaths(tests, modules), ...inspectPolicySetup(root)]
 }
 
+/**
+ * Checks whether a normalized path belongs to a scaffold-owned setup module.
+ * @param path - The workspace-relative module path.
+ * @param root - The workspace root whose manifest determines harness ownership.
+ * @returns True if scaffold owns the module; false otherwise.
+ */
+export function matchesScaffoldSetup(path: string, root: string): boolean {
+	const normalized = normalizePolicyPath(path)
+	const manifest = readPolicyJSON(join(root, 'package.json'))
+	return (
+		(normalized === DISTRIBUTION_SETUP_PATH &&
+			(!isPolicyRecord(manifest) || manifest.private !== true)) ||
+		HOST_PATHS.some(
+			(vendored) =>
+				normalized === normalizePolicyPath(vendored) ||
+				normalized.startsWith(normalizePolicyPath(vendored) + '/'),
+		)
+	)
+}
+
 /**
  * Inspects root setup modules and their proofs in both directions.
- *
  * @param root - The workspace root to inspect.
  * @returns Missing modules and uncovered exporting setup modules.
  */
@@ -1125,14 +1144,7 @@ export function inspectPolicySetup(root: string): readonly PolicyViolation[] {
 	)
 	return [...paths].sort().flatMap((path) => {
 		const module = path.endsWith('.test.ts') ? path.replace(/\.test\.ts$/u, '.ts') : path
-		if (
-			HOST_PATHS.some(
-				(vendored) =>
-					module === normalizePolicyPath(vendored) ||
-					module.startsWith(normalizePolicyPath(vendored) + '/'),
-			)
-		)
-			return []
+		if (matchesScaffoldSetup(module, root)) return []
 		if (path.endsWith('.test.ts')) {
 			return paths.has(module)
 				? []
@@ -3075,7 +3087,9 @@ export function readPolicySurface(root: string): PolicySurfacePopulation {
  *
  * @remarks
  * Source names claimed by the target's own hosted guide are grandfathered. Setup names have no
- * grandfather. An absent installed host falls back to checkout guides only with catalog coverage.
+ * grandfather. Catalog rows come from beside the guides: when reading installed guides, from the
+ * staged catalog and never from the target's own table, which can list a package without a guide in
+ * that host. An absent installed host falls back to checkout guides only with catalog coverage.
  * Missing comparison evidence and unread barrel statements produce surface violations.
  *
  * @param root - The workspace root to inspect.
@@ -3088,7 +3102,7 @@ export function inspectPolicySurface(root: string): readonly PolicyViolation[] {
 	const host = hosted ? installed : root
 	const catalog = hosted ? POLICY_SURFACE_CATALOG : POLICY_CATALOG_FILE
 	const directory = hosted ? `${POLICY_SURFACE_HOST}/guides` : 'guides'
-	const names = new Set([...readPolicyCatalog(host, catalog), ...readPolicyCatalog(root)])
+	const names = new Set(readPolicyCatalog(host, catalog))
 	if (!existsSync(join(host, 'guides')) || names.size === 0) {
 		return [
 			createPolicyViolation(
@@ -3153,12 +3167,7 @@ export function inspectPolicySurface(root: string): readonly PolicyViolation[] {
 		.map(normalizePolicyPath)
 		.sort()
 		.flatMap((path) =>
-			path.endsWith('.test.ts') ||
-			HOST_PATHS.some(
-				(vendored) =>
-					path === normalizePolicyPath(vendored) ||
-					path.startsWith(`${normalizePolicyPath(vendored)}/`),
-			)
+			path.endsWith('.test.ts') || matchesScaffoldSetup(path, root)
 				? []
 				: [collectPolicyDeclarations(root, path, readFileSync(join(root, path), 'utf8'))],
 		)
@@ -3392,6 +3401,13 @@ export const SETUP_POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
 			},
 		],
 	},
+	{
+		label: 'admits the distribution harness without a sibling proof',
+		membership: 'content-owned distribution setup module outside the mirror population',
+		rule: 'mirror',
+		files: [{ path: 'tests/setupDistribution.ts', content: 'export const DISTRIBUTION = 1\n' }],
+		violations: [],
+	},
 	{
 		label: 'admits an inventory-vendored setup module without proof',
 		membership: 'host-inventory setup modules outside the mirror population',
@@ -3399,12 +3415,30 @@ export const SETUP_POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
 		files: [{ path: 'tests/setupPolicy.ts', content: 'export const POLICY = 1\n' }],
 		violations: [],
 	},
+	{
+		label: 'requires a proof for a private workspace distribution module',
+		membership: 'target-owned distribution setup module in a private workspace',
+		rule: 'mirror',
+		files: [
+			{ path: 'package.json', content: '{"private":true}\n' },
+			{ path: 'tests/setupDistribution.ts', content: 'export const DISTRIBUTION = 1\n' },
+		],
+		violations: [
+			{
+				rule: 'mirror',
+				path: 'tests/setupDistribution.ts',
+				message:
+					'exporting setup module requires its sibling proof or an import from tests/setup.test.ts',
+			},
+		],
+	},
 ])
 
 /** Lists standalone sheet selections and their core-bearing control for the vendored proof. */
 export const SHEET_POLICY_SELECTIONS: ReadonlyArray<
 	Pick<Blueprint, 'src' | 'styles' | 'themes'> & {
 		readonly conformance?: boolean
+		readonly tree?: boolean
 		readonly integration?: boolean
 		readonly files?: readonly PolicySource[]
 		readonly control?: {
@@ -3416,8 +3450,25 @@ export const SHEET_POLICY_SELECTIONS: ReadonlyArray<
 > = Object.freeze([
 	{ src: [], styles: true, themes: true },
 	{ src: [], styles: false, themes: true },
-	{ src: [], styles: false, themes: true, integration: true },
+	{
+		src: [],
+		styles: false,
+		themes: true,
+		integration: true,
+		control: {
+			before: "existsSync(resolveWorkspacePath('tests/setupStyles.ts'))",
+			after: 'true',
+			failure: './tests/setupStyles.ts',
+		},
+	},
 	{ src: ['core'], styles: true, themes: true },
+	{
+		src: ['core'],
+		styles: false,
+		themes: false,
+		tree: true,
+		files: [{ path: 'tests/tree.test.ts', content: 'export {}\n' }],
+	},
 	{
 		src: ['core', 'browser'],
 		styles: true,
@@ -3457,10 +3508,10 @@ export const SHEET_POLICY_SELECTIONS: ReadonlyArray<
 		styles: true,
 		themes: false,
 		integration: true,
+		files: [{ path: 'tests/setupStyles.ts', content: 'export {}\n' }],
 		control: {
-			before:
-				"setupFiles: ['./tests/setup.ts', './tests/setupBrowser.ts', './tests/setupStyles.ts']",
-			after: "setupFiles: ['./tests/setup.ts', './tests/setupBrowser.ts']",
+			before: "? ['./tests/setupStyles.ts']",
+			after: '? []',
 			failure: './tests/setupStyles.ts',
 		},
 	},
@@ -4283,7 +4334,7 @@ export const PROSE_POLICY_MANIFEST = '{\n\t"name": "@orkestrel/sample"\n}\n'
  * Lists the physical controls for every prose-population boundary the workspace route reaches.
  *
  * @remarks
- * Each control that attacks an exclusion also writes the arrival file, whose different term proves
+ * Each control that tests an exclusion also writes the arrival file, whose different term proves
  * the sweep ran over the control workspace rather than reporting nothing because it found nothing.
  */
 export const PROSE_POLICY_CONTROLS: readonly PolicyControl[] = Object.freeze([
@@ -4559,15 +4610,22 @@ export function collectFaceWrappers(directory: string): readonly string[] {
  * Inspects sheet setup membership and themes ordering from configuration data.
  * @param project - The resolved sheet project.
  * @param script - The optional chained styles and themes build command.
+ * @param directory - The target workspace root; defaults to the policy root.
  * @returns Missing setup paths and invalid isolation or ordering fields.
  */
-export function inspectSheetConfiguration(project: unknown, script?: string): readonly string[] {
+export function inspectSheetConfiguration(
+	project: unknown,
+	script?: string,
+	directory: string = POLICY_ROOT,
+): readonly string[] {
 	const test = readConfigRecord(readConfigRecord(project).test)
 	const setup = test.setupFiles
 	return [
-		...['./tests/setup.ts', './tests/setupBrowser.ts', './tests/setupStyles.ts'].filter(
-			(path) => !Array.isArray(setup) || !setup.includes(path),
-		),
+		...[
+			'./tests/setup.ts',
+			'./tests/setupBrowser.ts',
+			...(existsSync(resolve(directory, 'tests/setupStyles.ts')) ? ['./tests/setupStyles.ts'] : []),
+		].filter((path) => !Array.isArray(setup) || !setup.includes(path)),
 		...(test.isolate !== false ? ['isolate'] : []),
 		...(script !== undefined &&
 		(!script.includes('vite.styles.config.ts') ||