@apptoolkit/harness 0.0.0-stage → 1.0.0

package/dist/bun/native/payload/author-style/check.ts

@@ -0,0 +1,181 @@
+import { spawnSync } from 'node:child_process';
+import { lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { z } from 'zod';
+import { findMemberSpacingIssues } from './member-spacing.ts';
+import { findReactModuleIssues } from './react-module.ts';
+import { findSourcePolicyIssues, hasGeneratedHeader } from './source-policy.ts';
+import { findSpacingIssues } from './spacing.ts';
+
+const requestSchema = z.object({
+  root: z.string().refine(isAbsolute, 'Supply the absolute project directory with --root.'),
+  profile: z.enum(['core', 'react', 'sql']),
+  lintOnly: z.boolean(),
+  files: z.array(z.string().min(1)).min(1, 'Supply the files you changed.'),
+});
+
+const sourceExtension = /\.(?:[cm]?ts|tsx)$/;
+const protectedDirectories = new Set(['node_modules', '.git', '.next', 'coverage', 'dist', 'out']);
+const nativeConfigurations = ['biome.json', 'biome.jsonc'];
+const configurations = { core: 'biome-core.json', react: 'biome-react.json', sql: 'biome-sql.json' };
+const requireFromProfile = createRequire(import.meta.url);
+
+function targetRelativePath(root: string, file: string): string {
+  const path = relative(root, file);
+
+  if (!path || path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)) {
+    throw new Error(`Choose a source file inside ${root}: ${file}`);
+  }
+
+  return path;
+}
+
+function configuredBiome(file: string): string | undefined {
+  let directory = dirname(file);
+
+  for (;;) {
+    for (const name of nativeConfigurations) {
+      const path = join(directory, name);
+
+      if (lstatSync(path, { throwIfNoEntry: false })) {
+        return path;
+      }
+    }
+
+    const parent = dirname(directory);
+
+    if (directory === parent) {
+      return undefined;
+    }
+
+    directory = parent;
+  }
+}
+
+function checkFiles(argumentsList: string[]): number {
+  const parsed = parseArgs({
+    args: argumentsList,
+    allowPositionals: true,
+    options: {
+      root: { type: 'string' },
+      profile: { type: 'string', default: 'core' },
+      'lint-only': { type: 'boolean', default: false },
+    },
+  });
+  const request = requestSchema.parse({
+    root: parsed.values.root,
+    profile: parsed.values.profile,
+    lintOnly: parsed.values['lint-only'],
+    files: parsed.positionals,
+  });
+  const requestedRoot = resolve(request.root);
+  const root = realpathSync(requestedRoot);
+
+  if (!statSync(root).isDirectory()) {
+    throw new Error(`The project root must be a directory: ${root}`);
+  }
+
+  const sources = new Map<string, string>();
+
+  for (const file of request.files) {
+    const requestedPath = resolve(requestedRoot, file);
+    let lexicalRoot = requestedRoot;
+
+    if (isAbsolute(file) && requestedPath.startsWith(`${root}${sep}`)) {
+      lexicalRoot = root;
+    }
+
+    const path = targetRelativePath(lexicalRoot, requestedPath);
+    const expectedPath = join(root, path);
+    const sourcePath = realpathSync(expectedPath);
+
+    if (expectedPath !== sourcePath) {
+      throw new Error(`Use the direct source path instead of a symbolic link: ${path}`);
+    }
+
+    if (!sourceExtension.test(path) || !statSync(sourcePath).isFile()) {
+      throw new Error(`Choose an authored TypeScript or TSX file: ${path}`);
+    }
+
+    if (path.split(sep).some((part) => protectedDirectories.has(part))) {
+      throw new Error(`Choose an authored file outside generated, dependency and Git directories: ${path}`);
+    }
+
+    const existingConfiguration = configuredBiome(sourcePath);
+
+    if (existingConfiguration) {
+      throw new Error(`Use the project's configured Biome checks for ${path}: ${existingConfiguration}`);
+    }
+
+    const source = readFileSync(sourcePath, 'utf8');
+
+    if (hasGeneratedHeader(source)) {
+      throw new Error(`Choose an authored source file instead of a generated artifact: ${path}`);
+    }
+
+    sources.set(path, source);
+  }
+
+  const config = fileURLToPath(new URL(configurations[request.profile], import.meta.url));
+  const biome = requireFromProfile.resolve('@biomejs/biome/bin/biome');
+  const runtimeArguments = process.versions.bun ? ['--no-env-file', '--no-install'] : [];
+  const environment = { ...process.env };
+
+  delete environment.BIOME_BINARY;
+
+  const result = spawnSync(
+    process.execPath,
+    [
+      ...runtimeArguments,
+      biome,
+      request.lintOnly ? 'lint' : 'check',
+      `--config-path=${config}`,
+      '--error-on-warnings',
+      '--',
+      ...sources.keys(),
+    ],
+    { cwd: root, env: environment, stdio: 'inherit' },
+  );
+
+  if (result.error) {
+    throw new Error(`Cannot launch Biome in ${root}: ${result.error.message}`, { cause: result.error });
+  }
+
+  if (result.status === null) {
+    throw new Error(`Biome did not complete in ${root}${result.signal ? ` (${result.signal})` : ''}.`);
+  }
+
+  if (result.status !== 0) {
+    return result.status;
+  }
+
+  let count = 0;
+
+  for (const [path, source] of sources) {
+    const spacing = request.lintOnly
+      ? []
+      : [...findSpacingIssues(source, path), ...findMemberSpacingIssues(source, path)];
+    const react = request.profile === 'react' ? findReactModuleIssues(source, path) : [];
+
+    if (readFileSync(join(root, path), 'utf8') !== source) {
+      throw new Error(`The source changed during verification. Run the check again: ${path}`);
+    }
+
+    for (const { line, column, message } of [...findSourcePolicyIssues(source, path), ...spacing, ...react]) {
+      process.stderr.write(`${path}:${line}:${column} ${message}\n`);
+      count += 1;
+    }
+  }
+
+  return count > 0 ? 1 : 0;
+}
+
+try {
+  process.exitCode = checkFiles(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/dist/bun/native/payload/author-style/member-spacing.test.ts

@@ -0,0 +1,172 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { findMemberSpacingIssues } from './member-spacing.ts';
+
+const memberMessage = 'Leave one blank line between class members.';
+const overloadMessage = 'Keep adjacent signatures and the implementation of an overload together.';
+
+function check(lines: readonly string[]) {
+  return findMemberSpacingIssues(lines.join('\n'), 'example.ts');
+}
+
+test('requires one blank line between authored properties, methods and accessors', () => {
+  assert.deepEqual(
+    check([
+      'class Example {',
+      '  public value = 1;',
+      '  public other = 2;',
+      '',
+      '',
+      '  public get label() { return this.value; }',
+      '',
+      '  public set label(value: number) { this.value = value; }',
+      '}',
+    ]),
+    [
+      { line: 3, column: 3, message: memberMessage },
+      { line: 6, column: 3, message: memberMessage },
+    ],
+  );
+});
+
+test('groups same-name overloads and constructor overloads with their implementations', () => {
+  assert.deepEqual(
+    check([
+      'class Example {',
+      '  public constructor(value: string);',
+      '  public constructor(value: number);',
+      '  public constructor(public value: string | number) {}',
+      '',
+      '  public lookup(value: string): string;',
+      "  public 'lookup'(value: number): number;",
+      "  public ['lookup'](value: string | number): string | number { return value; }",
+      '',
+      '  public static lookup(value: string): string;',
+      '  public static lookup(value: number): number;',
+      '  public static lookup(value: string | number): string | number { return value; }',
+      '}',
+    ]),
+    [],
+  );
+});
+
+test('reports breaks within overloads and separates distinct overload groups', () => {
+  assert.deepEqual(
+    check([
+      'class Example {',
+      '  public constructor(value: string);',
+      '',
+      '  public constructor(public value: string) {}',
+      '  public lookup(value: string): string;',
+      '',
+      '  public lookup(value: number): number;',
+      '  public lookup(value: string | number): string | number { return value; }',
+      '',
+      '  public static lookup(value: string): string;',
+      '',
+      '  public static lookup(value: string): string { return value; }',
+      '}',
+    ]),
+    [
+      { line: 4, column: 3, message: overloadMessage },
+      { line: 5, column: 3, message: memberMessage },
+      { line: 7, column: 3, message: overloadMessage },
+      { line: 12, column: 3, message: overloadMessage },
+    ],
+  );
+});
+
+test('keeps bodyless members separate if a matching adjacent member is absent', () => {
+  assert.deepEqual(
+    check([
+      'abstract class Example {',
+      '  public abstract read(value: string): string;',
+      '  public static read(value: string): string { return value; }',
+      '  public abstract write(value: string): void;',
+      '  public value = 1;',
+      '',
+      '  public writeOther(): void {}',
+      '}',
+    ]),
+    [
+      { line: 3, column: 3, message: memberMessage },
+      { line: 4, column: 3, message: memberMessage },
+      { line: 5, column: 3, message: memberMessage },
+    ],
+  );
+});
+
+test('groups overload declarations in ambient and abstract classes without requiring a body', () => {
+  assert.deepEqual(
+    check([
+      'declare class Ambient {',
+      '  public lookup(value: string): string;',
+      '  public lookup(value: number): number;',
+      '}',
+      'abstract class Example {',
+      '  public abstract lookup(value: string): string;',
+      '',
+      '  public abstract lookup(value: number): number;',
+      '}',
+    ]),
+    [{ line: 8, column: 3, message: overloadMessage }],
+  );
+});
+
+test('matches overloads with the same computed or private name', () => {
+  assert.deepEqual(
+    check([
+      'class Example {',
+      '  public [Symbol.iterator](value: string): string;',
+      '  public [Symbol.iterator](value: string): string { return value; }',
+      '',
+      '  #lookup(value: string): string;',
+      '  #lookup(value: string): string { return value; }',
+      '}',
+    ]),
+    [],
+  );
+});
+
+test('counts spacing outside comments and preserves comment ownership with CRLF', () => {
+  const source = [
+    'class Example {',
+    '  public value = 1; /* trailing',
+    '',
+    '  details */',
+    '  /* leading',
+    '',
+    '  details */',
+    '  public next = 2;',
+    '',
+    '  // Attached to the following member.',
+    '  public final = 3;',
+    '}',
+  ].join('\r\n');
+
+  assert.deepEqual(findMemberSpacingIssues(source, 'example.ts'), [{ line: 8, column: 3, message: memberMessage }]);
+  assert.deepEqual(findMemberSpacingIssues(source.replace('*/\r\n  /*', '*/\r\n \t\r\n  /*'), 'example.ts'), []);
+});
+
+test('visits class expressions and nested classes in source order and ignores non-class members', () => {
+  const source = [
+    'interface Shape { x: number; y: number }',
+    'const shape = { x: 1, y: 2 };',
+    'const Example = class {',
+    '  public nested = class {',
+    '    public first = 1;',
+    '    public second = 2;',
+    '  };',
+    '  static { run(); }',
+    '}',
+    'class Empty { ; }',
+    'class Single { public value = 1; }',
+    'export const view = <button>Save</button>;',
+  ].join('\n');
+
+  assert.deepEqual(findMemberSpacingIssues(source, 'example.tsx'), [
+    { line: 6, column: 5, message: memberMessage },
+    { line: 8, column: 3, message: memberMessage },
+  ]);
+});

package/dist/bun/native/payload/author-style/member-spacing.ts

@@ -0,0 +1,106 @@
+import ts from 'typescript';
+
+type MemberSpacingIssue = { line: number; column: number; message: string };
+type OverloadMember = ts.ConstructorDeclaration | ts.MethodDeclaration;
+
+function isOverloadMember(member: ts.ClassElement): member is OverloadMember {
+  return ts.isConstructorDeclaration(member) || ts.isMethodDeclaration(member);
+}
+
+function methodName(member: ts.MethodDeclaration, file: ts.SourceFile): string {
+  const name = member.name;
+
+  if (ts.isComputedPropertyName(name)) {
+    if (ts.isStringLiteral(name.expression) || ts.isNumericLiteral(name.expression)) {
+      return `literal:${name.expression.text}`;
+    }
+
+    return `computed:${name.getText(file)}`;
+  }
+
+  if (ts.isPrivateIdentifier(name)) {
+    return `private:${name.text}`;
+  }
+
+  return `literal:${name.text}`;
+}
+
+function belongsToOverload(signature: OverloadMember, following: OverloadMember, file: ts.SourceFile): boolean {
+  if (ts.isConstructorDeclaration(signature) || ts.isConstructorDeclaration(following)) {
+    return ts.isConstructorDeclaration(signature) && ts.isConstructorDeclaration(following);
+  }
+
+  const signatureStatic = ts.getCombinedModifierFlags(signature) & ts.ModifierFlags.Static;
+  const followingStatic = ts.getCombinedModifierFlags(following) & ts.ModifierFlags.Static;
+
+  return signatureStatic === followingStatic && methodName(signature, file) === methodName(following, file);
+}
+
+function findGroupedSignatures(members: readonly ts.ClassElement[], file: ts.SourceFile): Set<ts.ClassElement> {
+  const signatures = new Set<ts.ClassElement>();
+  let following: OverloadMember | undefined;
+
+  for (const member of members.toReversed()) {
+    if (isOverloadMember(member)) {
+      if (!member.body && following && belongsToOverload(member, following, file)) {
+        signatures.add(member);
+      }
+
+      following = member;
+    } else {
+      following = undefined;
+    }
+  }
+
+  return signatures;
+}
+
+function countBlankLines(previous: ts.ClassElement, current: ts.ClassElement, file: ts.SourceFile): number {
+  const trailingComments = ts.getTrailingCommentRanges(file.text, previous.end);
+  const previousEnd = trailingComments?.at(-1)?.end ?? previous.end;
+  const leadingComments = ts.getLeadingCommentRanges(file.text, previousEnd);
+  const currentStart = leadingComments?.[0]?.pos ?? current.getStart(file);
+  const gap = file.text.slice(previousEnd, currentStart);
+
+  return gap
+    .split(/\r?\n/)
+    .slice(1, -1)
+    .filter((line) => /^[^\S\r\n]*$/.test(line)).length;
+}
+
+export function findMemberSpacingIssues(source: string, fileName: string): readonly MemberSpacingIssue[] {
+  const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true);
+  const issues: MemberSpacingIssue[] = [];
+
+  function visit(node: ts.Node): void {
+    if (ts.isClassLike(node)) {
+      const members = node.members.filter((member) => !ts.isSemicolonClassElement(member));
+      const signatures = findGroupedSignatures(members, file);
+      let previous: ts.ClassElement | undefined;
+
+      for (const member of members) {
+        if (previous) {
+          const inOverloadGroup = signatures.has(previous);
+          const requiredBlankLines = inOverloadGroup ? 0 : 1;
+
+          if (countBlankLines(previous, member, file) !== requiredBlankLines) {
+            const { line, character } = file.getLineAndCharacterOfPosition(member.getStart(file));
+            const message = inOverloadGroup
+              ? 'Keep adjacent signatures and the implementation of an overload together.'
+              : 'Leave one blank line between class members.';
+
+            issues.push({ line: line + 1, column: character + 1, message });
+          }
+        }
+
+        previous = member;
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(file);
+
+  return issues.sort((left, right) => left.line - right.line || left.column - right.column);
+}

package/dist/bun/native/payload/author-style/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "harness-author-style",
+  "private": true,
+  "type": "module",
+  "packageManager": "bun@1.4.2",
+  "scripts": {
+    "check": "bun --no-env-file --no-install check.ts",
+    "test": "bun test"
+  },
+  "engines": {
+    "bun": ">=1.4.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "typescript": "5.9.3",
+    "zod": "4.6.7"
+  }
+}

package/dist/bun/native/payload/author-style/plugins/class-member-order.grit

@@ -0,0 +1,133 @@
+language js(typescript, jsx)
+
+pattern property($modifiers) {
+  or {
+    JsPropertyClassMember(modifiers=$modifiers, name=$name),
+    TsPropertySignatureClassMember(modifiers=$modifiers, name=$name),
+    TsInitializedPropertySignatureClassMember(modifiers=$modifiers, name=$name)
+  } where { not $name <: JsPrivateClassMemberName() }
+}
+
+pattern method($modifiers) {
+  or {
+    JsMethodClassMember(modifiers=$modifiers, name=$name),
+    JsGetterClassMember(modifiers=$modifiers, name=$name),
+    JsSetterClassMember(modifiers=$modifiers, name=$name),
+    TsMethodSignatureClassMember(modifiers=$modifiers, name=$name),
+    TsGetterSignatureClassMember(modifiers=$modifiers, name=$name),
+    TsSetterSignatureClassMember(modifiers=$modifiers, name=$name)
+  } where { not $name <: JsPrivateClassMemberName() }
+}
+
+pattern internal() {
+  contains TsAccessibilityModifier() as $accessibility where { $accessibility <: r"(?:private|protected)" }
+}
+
+pattern private_static_property() {
+  property($modifiers) where { $modifiers <: contains JsStaticModifier(), $modifiers <: internal() }
+}
+
+pattern public_static_property() {
+  property($modifiers) where { $modifiers <: contains JsStaticModifier(), not $modifiers <: internal() }
+}
+
+pattern private_static_method() {
+  method($modifiers) where { $modifiers <: contains JsStaticModifier(), $modifiers <: internal() }
+}
+
+pattern public_static_method() {
+  method($modifiers) where { $modifiers <: contains JsStaticModifier(), not $modifiers <: internal() }
+}
+
+pattern constructor_member() {
+  or {
+    JsConstructorClassMember(),
+    TsConstructorSignatureClassMember()
+  }
+}
+
+pattern private_property() {
+  property($modifiers) where { not $modifiers <: contains JsStaticModifier(), $modifiers <: internal() }
+}
+
+pattern public_property() {
+  property($modifiers) where { not $modifiers <: contains JsStaticModifier(), not $modifiers <: internal() }
+}
+
+pattern private_method() {
+  method($modifiers) where { not $modifiers <: contains JsStaticModifier(), $modifiers <: internal() }
+}
+
+pattern public_method() {
+  method($modifiers) where { not $modifiers <: contains JsStaticModifier(), not $modifiers <: internal() }
+}
+
+or {
+  property(),
+  method(),
+  constructor_member()
+} as $second where {
+  $second <: after $first,
+  $first <: or {
+    property(),
+    method(),
+    constructor_member()
+  },
+  or {
+    and { $second <: private_static_property(), not $first <: private_static_property() },
+    and {
+      $second <: public_static_property(),
+      not $first <: or {
+        private_static_property(),
+        public_static_property()
+      }
+    },
+    and {
+      $second <: private_static_method(),
+      $first <: or {
+        public_static_method(),
+        constructor_member(),
+        private_property(),
+        public_property(),
+        private_method(),
+        public_method()
+      }
+    },
+    and {
+      $second <: public_static_method(),
+      $first <: or {
+        constructor_member(),
+        private_property(),
+        public_property(),
+        private_method(),
+        public_method()
+      }
+    },
+    and {
+      $second <: constructor_member(),
+      $first <: or {
+        private_property(),
+        public_property(),
+        private_method(),
+        public_method()
+      }
+    },
+    and {
+      $second <: private_property(),
+      $first <: or {
+        public_property(),
+        private_method(),
+        public_method()
+      }
+    },
+    and {
+      $second <: public_property(),
+      $first <: or {
+        private_method(),
+        public_method()
+      }
+    },
+    and { $second <: private_method(), $first <: public_method() }
+  },
+  register_diagnostic(span=$second, message="Follow the class member order. Move this member before the preceding group.", severity="error")
+}