@orkestrel/scaffold 0.0.108 → 0.0.109

package/dist/host/configs/helpers.ts

@@ -756,6 +756,26 @@ export function readCompilerOutput(compiler: string, args: readonly string[]): s
 	return result.stdout ?? ''
 }
 
+/**
+ * Resolves the TypeScript command from its exported package manifest.
+ * @param path - The module or manifest path whose installation supplies TypeScript.
+ * @returns The absolute compiler command path on TypeScript 6 and 7.
+ * @throws An error when the package declares no `bin.tsc` command.
+ */
+export function resolveCompiler(path: string): string {
+	const load = createRequire(path)
+	const manifest = load.resolve('typescript/package.json')
+	const declared: unknown = load(manifest)
+	if (typeof declared !== 'object' || declared === null || !('bin' in declared)) {
+		throw new Error('The TypeScript package declares no bin.tsc command')
+	}
+	const bin = declared.bin
+	if (typeof bin !== 'object' || bin === null || !('tsc' in bin) || typeof bin.tsc !== 'string') {
+		throw new Error('The TypeScript package declares no bin.tsc command')
+	}
+	return resolvePath(dirname(manifest), bin.tsc)
+}
+
 /**
  * Parses a `tsc --showConfig` reading into the compiler scope a face's roll-up requires.
  *
@@ -886,7 +906,7 @@ export function declarationRollup(options: DeclarationRollupOptions): Plugin {
 				)
 			}
 			const load = createRequire(import.meta.url)
-			const compiler = load.resolve('typescript/bin/tsc')
+			const compiler = resolveCompiler(import.meta.url)
 			const scope = parseProjectScope(
 				readCompilerOutput(compiler, ['--showConfig', '-p', options.project]),
 				options.project,

package/dist/host/configs/policy.ts

@@ -12,8 +12,20 @@ export interface PolicyExpression extends PolicyNode {
 	readonly key?: PolicyExpression
 	readonly id?: PolicyExpression | null
 	readonly method?: boolean
-	readonly kind?: 'const' | 'get' | 'init' | 'let' | 'set' | 'var'
+	readonly kind?:
+		| 'const'
+		| 'get'
+		| 'global'
+		| 'init'
+		| 'let'
+		| 'module'
+		| 'namespace'
+		| 'set'
+		| 'var'
 	readonly expression?: boolean
+	readonly readonly?: boolean
+	readonly test?: PolicyExpression
+	readonly alternate?: PolicyExpression | null
 	readonly object?: PolicyExpression
 	readonly property?: PolicyExpression
 	readonly computed?: boolean
@@ -25,6 +37,7 @@ export interface PolicyExpression extends PolicyNode {
 	readonly quasis?: readonly PolicyExpression[]
 	readonly expressions?: readonly PolicyExpression[]
 	readonly accessibility?: 'private' | 'protected' | 'public' | null
+	readonly declare?: boolean
 	readonly declaration?: PolicyExpression
 	readonly declarations?: readonly PolicyExpression[]
 	readonly init?: PolicyExpression | null
@@ -52,12 +65,30 @@ export interface PolicyComment extends PolicyNode {
 	readonly value: string
 }
 
+/** Describes one reference the scope manager records to a declared variable. */
+export interface PolicyReference {
+	readonly identifier: PolicyNode
+	readonly init?: boolean
+	isWrite(): boolean
+}
+
+/** Describes one variable the scope manager records for a declaration. */
+export interface PolicyVariable {
+	readonly identifiers: readonly PolicyNode[]
+	readonly references: readonly PolicyReference[]
+}
+
 /** Lists the Oxlint source-text operations the comment rules read. */
 export interface PolicySourceCode {
 	readonly text: string
 	getAllComments(): readonly PolicyComment[]
 }
 
+/** Adds the Oxlint scope operation the binding rule reads. */
+export interface PolicyScopeCode extends PolicySourceCode {
+	getDeclaredVariables(node: PolicyNode): readonly PolicyVariable[]
+}
+
 /** Pairs one doc block with the declared name its first sentence must not repeat. */
 export interface PolicyDoc {
 	readonly comment: PolicyComment
@@ -89,7 +120,7 @@ export interface PolicyContext {
 	readonly filename: string
 	/** Names the directory Oxlint resolves `filename` against. */
 	readonly cwd: string
-	readonly sourceCode: PolicySourceCode
+	readonly sourceCode: PolicyScopeCode
 	report(diagnostic: PolicyDiagnostic): void
 }
 
@@ -130,6 +161,7 @@ export interface PolicyVisitor {
 	readonly TSEnumDeclaration?: (node: PolicyNode) => void
 	readonly TSInterfaceDeclaration?: (node: PolicyNode) => void
 	readonly TSModuleDeclaration?: (node: PolicyNode) => void
+	readonly TSPropertySignature?: (node: PolicyNode) => void
 	readonly TSTypeAliasDeclaration?: (node: PolicyNode) => void
 	readonly VariableDeclaration?: (node: PolicyNode) => void
 }
@@ -266,6 +298,68 @@ export const POLICY_ENDING_GLOBS: readonly string[] = Object.freeze([
 	'src/**/*.ts',
 ])
 
+/** Lists every source extension the nested-function rule reads. */
+export const POLICY_CODE_EXTENSIONS: readonly string[] = Object.freeze([
+	'cjs',
+	'cts',
+	'js',
+	'jsx',
+	'mjs',
+	'mts',
+	'ts',
+	'tsx',
+	'vue',
+])
+
+/**
+ * Matches the lint population the nested-function rule runs over, as the Oxlint configuration
+ * declares it.
+ */
+export const POLICY_NESTED_GLOBS: readonly string[] = Object.freeze(
+	['src', 'app', 'tests', 'configs'].map(
+		(root) => `${root}/**/*.{${POLICY_CODE_EXTENSIONS.join(',')}}`,
+	),
+)
+
+/**
+ * Matches the lint population the skill-script rules run over, as the Oxlint configuration declares
+ * it.
+ */
+export const POLICY_SCRIPT_GLOBS: readonly string[] = Object.freeze([
+	'.agents/skills/*/scripts/*.ts',
+])
+
+/** Matches the workspace-relative path of a skill script, the file shape the script rule reads. */
+export const POLICY_SCRIPT_PATTERN = /^\.agents\/skills\/[^/]+\/scripts\/[^/]+\.ts$/u
+
+/** Holds the one entry guard a skill script runs `main` under, as its source text reads. */
+export const POLICY_ENTRY_GUARD =
+	'process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename'
+
+/** Lists every statement type that declares a name at module scope. */
+export const POLICY_DECLARATION_TYPES: readonly string[] = Object.freeze([
+	'ClassDeclaration',
+	'FunctionDeclaration',
+	'TSDeclareFunction',
+	'TSEnumDeclaration',
+	'TSInterfaceDeclaration',
+	'TSModuleDeclaration',
+	'TSTypeAliasDeclaration',
+	'VariableDeclaration',
+])
+
+/**
+ * Lists the type nodes a property signature's search for its owning declaration never crosses,
+ * because a parameter, call, or construct signature beyond one is an inline type.
+ */
+export const POLICY_INLINE_TYPES: readonly string[] = Object.freeze([
+	'TSCallSignatureDeclaration',
+	'TSConstructSignatureDeclaration',
+	'TSConstructorType',
+	'TSFunctionType',
+	'TSMethodSignature',
+])
+
 /**
  * Matches the file name shape an implementation file takes, holding the class that matches its
  * stem.
@@ -870,12 +964,37 @@ export function isPolicyVoiced(word: string): boolean {
 }
 
 /**
- * Pairs every exported top-level statement with the doc block written directly above it.
+ * Reads the doc block written directly above one top-level statement.
  *
  * @remarks
  * A statement takes the last comment that closes before it, and takes it only where that comment is
  * a doc block and nothing but whitespace separates the two. A blank line between them is still
- * whitespace, so the pairing survives one.
+ * whitespace, so the pairing survives one. Every comment is read where a `findLast` would stop at
+ * the nearest one.
+ *
+ * @param statement - The top-level statement to pair.
+ * @param comments - Every comment of the linted file, in source order.
+ * @param sourceCode - The source-text reader supplying the text between a comment and the statement.
+ * @returns The paired doc block, or `undefined` where the statement has none.
+ */
+export function statementToPolicyDoc(
+	statement: PolicyExpression,
+	comments: readonly PolicyComment[],
+	sourceCode: PolicySourceCode,
+): PolicyComment | undefined {
+	const start = statement.range[0]
+	const previous = Iterator.from(comments)
+		.flatMap((comment) => (comment.range[1] <= start ? [comment] : []))
+		.toArray()
+		.at(-1)
+	if (previous === undefined || previous.type !== 'Block') return undefined
+	if (!previous.value.startsWith('*')) return undefined
+	if (sourceCode.text.slice(previous.range[1], start).trim() !== '') return undefined
+	return previous
+}
+
+/**
+ * Pairs every exported top-level statement with the doc block written directly above it.
  *
  * @param node - The program node whose top-level statements are read.
  * @param sourceCode - The source-text reader supplying the comments and the text between them.
@@ -886,24 +1005,18 @@ export function programToPolicyDocs(
 	sourceCode: PolicySourceCode,
 ): readonly PolicyDoc[] {
 	// The iterator consumes one entry at a time and reads a hole as an `undefined` entry, as a
-	// `for…of` over the list would. The comments are read only for an export statement, once per
-	// statement, and every comment is read where a `findLast` would stop at the nearest one.
+	// `for…of` over the list would. The comments are read once, and a statement pairs with one only
+	// where it is an export.
 	const comments = sourceCode.getAllComments()
 	return Iterator.from(programToPolicyStatements(node))
 		.flatMap((statement) => {
 			if (!statement.type.startsWith('Export')) return []
-			const start = statement.range[0]
-			const previous = Iterator.from(comments)
-				.flatMap((comment) => (comment.range[1] <= start ? [comment] : []))
-				.toArray()
-				.at(-1)
-			if (previous === undefined || previous.type !== 'Block') return []
-			if (!previous.value.startsWith('*')) return []
-			if (sourceCode.text.slice(previous.range[1], start).trim() !== '') return []
+			const comment = statementToPolicyDoc(statement, comments, sourceCode)
+			if (comment === undefined) return []
 			const declaration = statement.declaration
 			return [
 				{
-					comment: previous,
+					comment,
 					name:
 						identifierToPolicyName(declaration?.id) ??
 						identifierToPolicyName(declaration?.declarations?.[0]?.id),
@@ -1023,6 +1136,54 @@ export function reportPrivacy(context: PolicyContext, node: PolicyExpression): v
 	}
 }
 
+/** Checks whether code writes a declared variable anywhere but in its own declaration. */
+export function isPolicyReassigned(variable: PolicyVariable): boolean {
+	return variable.references.some(
+		(reference) =>
+			reference.isWrite() &&
+			reference.init !== true &&
+			!variable.identifiers.includes(reference.identifier),
+	)
+}
+
+/**
+ * Checks whether a node sits inside a `declare` module, namespace, or global augmentation.
+ *
+ * @remarks
+ * A declaration inside such a block carries no `declare` flag of its own and no value, because the
+ * block is the ambient context. A `global` block is ambient wherever it stands.
+ */
+export function isPolicyInDeclaredModule(node: PolicyExpression): boolean {
+	const parent = node.parent
+	if (parent === undefined || parent === null) return false
+	return (
+		(parent.type === 'TSModuleDeclaration' &&
+			(parent.declare === true || parent.kind === 'global')) ||
+		isPolicyInDeclaredModule(parent)
+	)
+}
+
+/** Reports a let declaration that prefer-const leaves: one reassigned or declared without a value. */
+export function reportLet(context: PolicyContext, node: PolicyExpression): void {
+	if (
+		node.kind !== 'let' ||
+		node.declare === true ||
+		isPolicyAmbient(context.filename) ||
+		isPolicyInDeclaredModule(node)
+	) {
+		return
+	}
+	const head = node.parent?.type === 'ForInStatement' || node.parent?.type === 'ForOfStatement'
+	const bare =
+		!head &&
+		(node.declarations ?? []).some(
+			(declarator) => declarator.init === undefined || declarator.init === null,
+		)
+	if (bare || context.sourceCode.getDeclaredVariables(node).some(isPolicyReassigned)) {
+		context.report({ node, messageId: 'let' })
+	}
+}
+
 /** Reports a centralized declaration that carries no export. */
 export function reportHidden(context: PolicyContext, node: PolicyExpression): void {
 	if (isPolicyAmbient(context.filename)) return
@@ -1193,6 +1354,64 @@ export function reportEndingImport(context: PolicyContext, node: PolicyExpressio
 	if (importsPolicyTerminator(node)) context.report({ node, messageId: 'terminator' })
 }
 
+/** Reports whether a path is a skill script, the one file shape the script rule reads. */
+export function isPolicyScript(filename: string, cwd: string): boolean {
+	return POLICY_SCRIPT_PATTERN.test(pathToPolicyRelative(filename, cwd))
+}
+
+/** Reports whether a statement is the one entry guard a skill script runs its main under. */
+export function isPolicyGuard(statement: PolicyExpression, sourceCode: PolicySourceCode): boolean {
+	const test = statement.test
+	if (statement.type !== 'IfStatement' || test === undefined) return false
+	if (statement.alternate !== undefined && statement.alternate !== null) return false
+	const text = sourceCode.text.slice(test.range[0], test.range[1]).replace(/\s+/gu, ' ')
+	return text === POLICY_ENTRY_GUARD
+}
+
+/** Reports a skill script's top-level statement that is hidden, undocumented, or runs at import. */
+export function reportScript(context: PolicyContext, node: PolicyExpression): void {
+	if (isPolicyAmbient(context.filename) || !isPolicyScript(context.filename, context.cwd)) return
+	const sourceCode = context.sourceCode
+	const comments = sourceCode.getAllComments()
+	const statements = programToPolicyStatements(node)
+	const guard = statements.findIndex((statement) => isPolicyGuard(statement, sourceCode))
+	for (const [index, statement] of statements.entries()) {
+		if (statement.type === 'ImportDeclaration' || index === guard) continue
+		const declaration = statement.declaration
+		if (
+			statement.type === 'ExportNamedDeclaration' &&
+			declaration !== undefined &&
+			declaration !== null
+		) {
+			if (statementToPolicyDoc(statement, comments, sourceCode) === undefined) {
+				context.report({ node: statement, messageId: 'doc' })
+			}
+			continue
+		}
+		context.report({
+			node: statement,
+			messageId: POLICY_DECLARATION_TYPES.includes(statement.type) ? 'hidden' : 'entry',
+		})
+	}
+}
+
+/** Reports whether a property signature sits in an interface or in a type alias's object type. */
+export function isPolicyOwned(node: PolicyExpression): boolean {
+	const parent = node.parent
+	if (parent === undefined || parent === null) return false
+	if (parent.type === 'TSInterfaceDeclaration' || parent.type === 'TSTypeAliasDeclaration') {
+		return true
+	}
+	if (POLICY_INLINE_TYPES.includes(parent.type)) return false
+	return isPolicyOwned(parent)
+}
+
+/** Reports a property signature of an interface or type alias that is not readonly. */
+export function reportMutable(context: PolicyContext, node: PolicyExpression): void {
+	if (isPolicyAmbient(context.filename) || node.readonly === true) return
+	if (isPolicyOwned(node)) context.report({ node, messageId: 'mutable' })
+}
+
 /** Bans function declarations and assignments inside another function body. */
 export const NESTED_RULE: PolicyRuleInterface = {
 	meta: {
@@ -1262,6 +1481,25 @@ export const PRIVACY_RULE: PolicyRuleInterface = {
 	},
 }
 
+/** Bans a let declaration that prefer-const does not already report. */
+export const LET_RULE: PolicyRuleInterface = {
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Disallow a let declaration that is reassigned or declared without a value; prefer-const reports the rest.',
+		},
+		messages: {
+			let: 'Declare this binding with const and derive its value: an expression, a helper that returns it, or a for…of over entries() in place of a counter.',
+		},
+	},
+	create(context) {
+		return {
+			VariableDeclaration: (node) => reportLet(context, node),
+		}
+	},
+}
+
 /** Bans a centralized declaration that no export reaches. */
 export const HIDDEN_RULE: PolicyRuleInterface = {
 	meta: {
@@ -1546,6 +1784,49 @@ export const VOICE_RULE: PolicyRuleInterface = {
 	},
 }
 
+/** Bans a skill script top-level statement that is hidden, undocumented, or runs at import. */
+export const SCRIPT_RULE: PolicyRuleInterface = {
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Disallow an unexported declaration, an undocumented export, and a statement beyond the one guarded entry in a skill script.',
+		},
+		messages: {
+			hidden:
+				'Export this declaration; a skill script exports every declaration so its proof can test each one.',
+			doc: 'Write a one-sentence TSDoc summary directly above this export.',
+			entry:
+				'Move this statement into a function; a skill script holds imports, exported declarations, and the one process.argv[1] guard that runs main, and an import runs nothing.',
+		},
+	},
+	create(context) {
+		return {
+			Program: (node) => reportScript(context, node),
+		}
+	},
+}
+
+/** Bans a property signature in an interface or type alias that is not readonly. */
+export const MUTABLE_RULE: PolicyRuleInterface = {
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Disallow a property signature without readonly in an interface or in the object type of a type alias.',
+		},
+		messages: {
+			mutable:
+				'Declare this property readonly; a contract exposes its members and no holder rewrites them.',
+		},
+	},
+	create(context) {
+		return {
+			TSPropertySignature: (node) => reportMutable(context, node),
+		}
+	},
+}
+
 /** Bans a comment carrying a term the substitution table bans unconditionally. */
 export const TERM_RULE: PolicyRuleInterface = {
 	meta: {
@@ -1571,6 +1852,7 @@ export default {
 	rules: {
 		'no-mocking': MOCKING_RULE,
 		'no-keyword-privacy': PRIVACY_RULE,
+		'no-let': LET_RULE,
 		'no-nested-functions': NESTED_RULE,
 		'no-hidden-declaration': HIDDEN_RULE,
 		'no-misplaced-type': TYPE_RULE,
@@ -1586,5 +1868,7 @@ export default {
 		'no-host-line-endings': ENDING_RULE,
 		'no-malformed-summary': VOICE_RULE,
 		'no-banned-term': TERM_RULE,
+		'no-malformed-script': SCRIPT_RULE,
+		'no-mutable-property': MUTABLE_RULE,
 	},
 }

package/dist/host/dotfiles/oxlintrc.json

@@ -50,14 +50,20 @@
 		"no-unused-private-class-members": "error",
 		"no-var": "error",
 		"prefer-const": "error",
+		"no-param-reassign": "error",
+		"no-ex-assign": "error",
 		"no-debugger": "error",
 		"no-underscore-dangle": "warn",
 
 		"vitest/no-alias-methods": "error",
+		"vitest/no-identical-title": "error",
+		"vitest/no-focused-tests": "error",
+		"vitest/no-disabled-tests": "error",
 		"vitest/warn-todo": "off",
 
 		"policy/no-mocking": "error",
 		"policy/no-keyword-privacy": "error",
+		"policy/no-let": "error",
 		"policy/no-malformed-summary": "error",
 		"policy/no-banned-term": "error"
 	},
@@ -86,13 +92,27 @@
 			"files": [".agents/skills/*/scripts/*.ts"],
 			"rules": {
 				"policy/no-nested-functions": "error",
-				"policy/no-host-line-endings": "error"
+				"policy/no-host-line-endings": "error",
+				"policy/no-malformed-script": "error",
+				"no-restricted-imports": [
+					"error",
+					{
+						"patterns": [
+							{
+								"regex": "^(?:[^n]|n[^o]|no[^d]|nod[^e]|node[^:]|n$|no$|nod$|node$|$)",
+								"message": "a skill script is self-contained: import node: modules only and declare every helper in the script"
+							}
+						]
+					}
+				]
 			}
 		},
 		{
 			"files": [
 				"src/**/*.{cjs,cts,js,jsx,mjs,mts,ts,tsx,vue}",
-				"app/**/*.{cjs,cts,js,jsx,mjs,mts,ts,tsx,vue}"
+				"app/**/*.{cjs,cts,js,jsx,mjs,mts,ts,tsx,vue}",
+				"tests/**/*.{cjs,cts,js,jsx,mjs,mts,ts,tsx,vue}",
+				"configs/**/*.{cjs,cts,js,jsx,mjs,mts,ts,tsx,vue}"
 			],
 			"rules": {
 				"policy/no-nested-functions": "error"
@@ -110,7 +130,8 @@
 				"policy/no-misnamed-parser": "error",
 				"policy/no-misnamed-factory": "error",
 				"policy/no-misnamed-plugin": "error",
-				"policy/no-malformed-domain": "error"
+				"policy/no-malformed-domain": "error",
+				"policy/no-mutable-property": "error"
 			}
 		},
 		{
@@ -772,6 +793,119 @@
 					}
 				]
 			}
+		},
+		{
+			"files": ["tests/setup*.ts"],
+			"rules": {
+				"no-restricted-imports": [
+					"error",
+					{
+						"paths": [
+							{
+								"name": "vitest",
+								"importNames": ["describe", "it", "test", "expect"],
+								"message": "a setup module owns everything an assertion needs and nothing an assertion is: register and assert in a test file"
+							}
+						],
+						"patterns": [
+							{
+								"regex": "^typescript(?:[/?#]|$)",
+								"message": "the in-process compiler API is not a surface the fleet uses"
+							}
+						]
+					}
+				]
+			}
+		},
+		{
+			"files": ["tests/setup*.test.ts"],
+			"rules": {
+				"no-restricted-imports": [
+					"error",
+					{
+						"patterns": [
+							{
+								"regex": "^typescript(?:[/?#]|$)",
+								"message": "the in-process compiler API is not a surface the fleet uses"
+							}
+						]
+					}
+				]
+			}
+		},
+		{
+			"files": ["tests/setup.ts"],
+			"rules": {
+				"no-restricted-imports": [
+					"error",
+					{
+						"paths": [
+							{
+								"name": "vitest",
+								"importNames": ["describe", "it", "test", "expect"],
+								"message": "a setup module owns everything an assertion needs and nothing an assertion is: register and assert in a test file"
+							}
+						],
+						"patterns": [
+							{
+								"regex": "^typescript(?:[/?#]|$)",
+								"message": "the in-process compiler API is not a surface the fleet uses"
+							},
+							{
+								"regex": "^node:",
+								"message": "tests/setup.ts must stay host-independent: import no node: module"
+							},
+							{
+								"regex": "^(?:vue(?:[/?#]|$)|@vue/)",
+								"message": "tests/setup.ts must stay host-independent: import no Vue module"
+							}
+						]
+					}
+				]
+			}
+		},
+		{
+			"files": ["tests/setupBrowser.ts", "tests/setupStyles.ts"],
+			"rules": {
+				"no-restricted-imports": [
+					"error",
+					{
+						"paths": [
+							{
+								"name": "vitest",
+								"importNames": ["describe", "it", "test", "expect"],
+								"message": "a setup module owns everything an assertion needs and nothing an assertion is: register and assert in a test file"
+							}
+						],
+						"patterns": [
+							{
+								"regex": "^typescript(?:[/?#]|$)",
+								"message": "the in-process compiler API is not a surface the fleet uses"
+							},
+							{
+								"regex": "^node:",
+								"message": "the browser and styles setup modules hold no Node: import no node: module"
+							}
+						]
+					}
+				]
+			}
+		},
+		{
+			"files": ["configs/policy.ts"],
+			"rules": {
+				"no-restricted-imports": [
+					"error",
+					{
+						"patterns": [
+							{
+								"regex": ".",
+								"message": "configs/policy.ts imports nothing, so it resolves in every workspace"
+							}
+						]
+					}
+				]
+			}
 		}
 	]
 }