bitboss-ui 3.0.0-beta.47 → 3.0.0-beta.49

package/scripts/lib/helper-canon.mjs

@@ -0,0 +1,176 @@
+/**
+ * The canonical hash of a helper file (Q43.11 Q4, owner ruling 2026-10-07):
+ * a sha256 of its Babel syntax tree with positions, raw spellings, redundant
+ * parentheses and comments dropped. Two files with the same canonical hash run
+ * the same code, whatever formatter ran over them; a comment never counts.
+ *
+ * The parser is the Babel that Vue ships (`babelParse` from `vue/compiler-sfc`,
+ * a required peer, the same parser `bitboss-ui check` uses), never the app's
+ * TypeScript (TypeScript 7 has no JS parser). Design, rules and test matrix:
+ * plans/reviews/q43-11-copy-in-2026-09-30/Q4-CANONICAL-HASH.md.
+ *
+ * Every failure points one way: `null`, which the CLI reads as "edited", so a
+ * file it cannot canonicalise is kept, never overwritten.
+ */
+import { createHash } from 'node:crypto';
+
+/** Bumped whenever the form changes; part of every hash. */
+export const CANON_VERSION = 'bb-canon/1';
+const MAX_BYTES = 64 * 1024;
+const MAX_DEPTH = 500;
+
+/** Babel bookkeeping and every comment: never part of the form. */
+const META = new Set([
+	'type',
+	'start',
+	'end',
+	'loc',
+	'range',
+	'extra',
+	'leadingComments',
+	'trailingComments',
+	'innerComments',
+	'errors',
+	'comments',
+	'tokens',
+]);
+
+/** Nodes whose non-computed `key` is a property name (`{'a': 1}` = `{a: 1}`). */
+const KEYED = new Set([
+	'ObjectProperty',
+	'ObjectMethod',
+	'ClassProperty',
+	'ClassMethod',
+	'ClassAccessorProperty',
+	'TSPropertySignature',
+	'TSMethodSignature',
+	'TSDeclareMethod',
+	'TSAbstractClassProperty',
+	'TSAbstractMethodDefinition',
+]);
+
+const PARSE_OPTIONS = {
+	sourceType: 'module',
+	plugins: ['typescript'],
+	errorRecovery: false,
+	attachComment: false,
+	tokens: false,
+};
+
+function keyName(key) {
+	if (key?.type === 'Identifier') return key.name;
+	if (key?.type === 'StringLiteral') return key.value;
+	if (key?.type === 'NumericLiteral') return String(key.value);
+	return null;
+}
+
+function serialise(node, depth) {
+	if (depth > MAX_DEPTH) throw new Error('canon: nested too deep');
+	if (node === null || node === undefined || node === false) return null;
+	if (Array.isArray(node)) {
+		const items = node
+			.filter((n) => n?.type !== 'EmptyStatement')
+			.map((n) => serialise(n, depth + 1) ?? 'null');
+		return items.length ? `[${items.join(' ')}]` : null;
+	}
+	if (typeof node !== 'object') return JSON.stringify(node);
+	const { type } = node;
+	if (type === 'TSParenthesizedType')
+		return serialise(node.typeAnnotation, depth + 1);
+	if (type === 'ParenthesizedExpression')
+		return serialise(node.expression, depth + 1);
+	if (
+		(type === 'TSUnionType' || type === 'TSIntersectionType') &&
+		node.types.length === 1
+	)
+		return serialise(node.types[0], depth + 1);
+	const parts = [];
+	for (const key of Object.keys(node)
+		.filter((k) => !META.has(k))
+		.sort()) {
+		const value = node[key];
+		let out;
+		if (type === 'NumericLiteral' && key === 'value')
+			out = JSON.stringify(String(value));
+		else if (type === 'BigIntLiteral' && key === 'value')
+			out = JSON.stringify(BigInt(String(value).replace(/_/g, '')).toString());
+		else if (type === 'RegExpLiteral' && key === 'flags')
+			out = JSON.stringify([...value].sort().join(''));
+		else if (
+			((key === 'key' && KEYED.has(type) && !node.computed) ||
+				(key === 'id' && type === 'TSEnumMember')) &&
+			keyName(value) !== null
+		)
+			out = `(Key ${JSON.stringify(keyName(value))})`;
+		else if (key === 'shorthand') out = null;
+		else out = serialise(value, depth + 1);
+		if (out !== null) parts.push(`${key}=${out}`);
+	}
+	// `type` is undefined on plain value objects (a template element's
+	// `{ raw, cooked }`): they serialise by their keys alone.
+	return `(${type ?? '{}'}${parts.length ? ` ${parts.join(' ')}` : ''})`;
+}
+
+function parse(text, babelParse) {
+	if (typeof text !== 'string' || text.length > MAX_BYTES) return null;
+	try {
+		return babelParse(text.replace(/^\uFEFF/, ''), PARSE_OPTIONS);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The canonical sha256 of `text`, or `null` when it has none (syntax error,
+ * over 64 KB, nested too deep, any parser failure).
+ */
+export function canonicalHash(text, babelParse) {
+	const ast = parse(text, babelParse);
+	if (!ast) return null;
+	try {
+		const tree = serialise(ast.program, 0);
+		return createHash('sha256')
+			.update(`${CANON_VERSION}\n${tree}`)
+			.digest('hex');
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The file's comments, each line trimmed: what a `stale` write would lose
+ * that the canonical hash ignores. `null` when the file does not parse.
+ */
+export function commentList(text, babelParse) {
+	const ast = parse(text, babelParse);
+	if (!ast) return null;
+	return (ast.comments ?? []).map((c) =>
+		c.value
+			.split(/\r?\n/)
+			.map((line) => line.trim())
+			.join('\n')
+	);
+}
+
+/**
+ * Which Babel AST shape this parser builds: `babel7` or `babel8` (Babel 8
+ * renamed the TS function-type fields), or `null` when it is neither or does
+ * not parse at all. Canonical hashes are only comparable within one dialect.
+ */
+export function canonDialect(babelParse) {
+	try {
+		const ast = babelParse('type F = (a: A) => B', PARSE_OPTIONS);
+		const fn = ast.program.body[0].typeAnnotation;
+		if (fn.type !== 'TSFunctionType') return null;
+		if ('parameters' in fn && 'typeAnnotation' in fn) return 'babel7';
+		if ('params' in fn && 'returnType' in fn) return 'babel8';
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/** CRLF-normalised sha256: the byte hash the lock and the published list use. */
+export function lfHash(text) {
+	return createHash('sha256').update(text.replace(/\r\n/g, '\n')).digest('hex');
+}