@apptoolkit/harness 0.0.0-stage → 1.0.1

package/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/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/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/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")
+}

package/payload/author-style/plugins/event-handler-names.grit

@@ -0,0 +1,110 @@
+language js(typescript, jsx)
+
+pattern implementation() {
+  or {
+    JsArrowFunctionExpression(),
+    JsFunctionExpression(),
+    JsCallExpression(callee=$hook, arguments=JsCallArguments(args=[$callback, $dependencies])) where {
+      $hook <: or {
+        `useCallback`,
+        `React.useCallback`
+      },
+      $callback <: or {
+        JsArrowFunctionExpression(),
+        JsFunctionExpression()
+      }
+    }
+  }
+}
+
+pattern local_handler($name) {
+  or {
+    JsFunctionDeclaration(id=$name, body=JsFunctionBody()),
+    JsVariableDeclarator(id=$name, initializer=JsInitializerClause(expression=implementation()))
+  }
+}
+
+pattern call_target($name) { JsCallExpression(callee=JsIdentifierExpression() as $callee) where { $callee <: $name } }
+
+pattern adapted_call($name) {
+  or {
+    call_target($name),
+    JsAwaitExpression(argument=call_target($name)),
+    JsUnaryExpression(argument=$call) as $unary where {
+      $unary <: r"(?s)void\b.*",
+      $call <: or {
+        call_target($name),
+        JsAwaitExpression(argument=call_target($name))
+      }
+    }
+  }
+}
+
+pattern callback_target($name) {
+  or {
+    JsIdentifierExpression() as $reference where { $reference <: $name },
+    JsArrowFunctionExpression(body=adapted_call($name)),
+    JsArrowFunctionExpression(body=JsParenthesizedExpression(expression=adapted_call($name)))
+  }
+}
+
+pattern jsx_reference($name) {
+  JsxAttribute(name=$attribute, initializer=JsxAttributeInitializerClause(value=JsxExpressionAttributeValue(expression=$callback))) where {
+    $attribute <: r"on[A-Z].*",
+    $callback <: or {
+      callback_target($name),
+      form_reference($name)
+    }
+  }
+}
+
+pattern form_reference($name) {
+  JsCallExpression(callee=$factory, arguments=JsCallArguments(args=$arguments)) where {
+    $factory <: or {
+      `handleSubmit`,
+      JsStaticMemberExpression(member=$method) where { $method <: r"handleSubmit" }
+    },
+    $arguments <: or {
+      [callback_target($name)],
+      [callback_target($name), $invalid],
+      [$valid, callback_target($name)]
+    }
+  }
+}
+
+pattern native_reference($name, $items) {
+  JsCallExpression(callee=$callee, arguments=JsCallArguments(args=$arguments)) where {
+    $callee <: r"(?s)(?:window|document)\s*\.\s*addEventListener",
+    $arguments <: or {
+      [$event, callback_target($name)],
+      [$event, callback_target($name), $options]
+    },
+    not $items <: contains JsIdentifierBinding() as $target where { $target <: r"(?:window|document)" }
+  }
+}
+
+local_handler($name) as $declaration where {
+  not $name <: r"handle[A-Z][A-Za-z0-9]*",
+  $declaration <: within JsModule(items=$items),
+  $items <: contains or {
+    jsx_reference($name),
+    native_reference($name, $items)
+  },
+  not $items <: contains JsIdentifierBinding() as $parameter where {
+    $parameter <: $name,
+    $parameter <: within JsParameters()
+  },
+  not $items <: contains JsArrowFunctionExpression(parameters=JsIdentifierBinding() as $parameter) where {
+    $parameter <: $name
+  },
+  not $items <: contains JsIdentifierBinding() as $imported where {
+    $imported <: $name,
+    $imported <: within JsImport()
+  },
+  not $items <: contains JsIdentifierBinding() as $caught where { $caught <: $name, $caught <: within JsCatchClause() },
+  not $items <: contains JsVariableDeclarator(id=$binding, initializer=$initializer) where {
+    not $initializer <: JsInitializerClause(expression=implementation()),
+    $binding <: contains JsIdentifierBinding() as $forwarded where { $forwarded <: $name }
+  },
+  register_diagnostic(span=$name, message="Name locally implemented event handlers with a descriptive handle prefix, such as handleDelete.", severity="error")
+}

package/payload/author-style/plugins/explicit-arrow-body.grit

@@ -0,0 +1,15 @@
+language js(typescript, jsx)
+
+JsArrowFunctionExpression(body=$body) where {
+  not $body <: or {
+    JsFunctionBody(),
+    JsxTagExpression(),
+    JsParenthesizedExpression(expression=JsxTagExpression())
+  },
+  $body <: or {
+    r"(?s).*\n.*",
+    contains JsConditionalExpression(),
+    contains JsSequenceExpression()
+  },
+  register_diagnostic(span=$body, message="Use a block and an explicit return for a multiline or branching arrow body.", severity="error")
+}

package/payload/author-style/plugins/explicit-source-constructs.grit

@@ -0,0 +1,10 @@
+language js(typescript, jsx)
+
+or {
+  TsUnknownType() as $type where {
+    register_diagnostic(span=$type, message="Use an explicit domain type and validate external values at the boundary.", severity="error")
+  },
+  or { JsPreUpdateExpression(), JsPostUpdateExpression() } as $expression where {
+    register_diagnostic(span=$expression, message="Use an explicit update and preserve the original value if the expression consumes it.", severity="error")
+  }
+}

package/payload/author-style/plugins/react-arrow-body.grit

@@ -0,0 +1,85 @@
+language js(typescript, jsx)
+
+pattern bare_call() {
+  or {
+    JsCallExpression(),
+    JsParenthesizedExpression(expression=JsCallExpression())
+  }
+}
+
+pattern void_call() {
+  JsUnaryExpression(argument=$argument) as $unary where {
+    $unary <: r"(?s)void\b.*",
+    $argument <: or {
+      bare_call(),
+      JsAwaitExpression(argument=bare_call())
+    }
+  }
+}
+
+pattern handler_call() {
+  or {
+    bare_call(),
+    JsAwaitExpression(argument=bare_call()),
+    void_call(),
+    JsParenthesizedExpression(expression=JsAwaitExpression(argument=bare_call())),
+    JsParenthesizedExpression(expression=void_call())
+  }
+}
+
+pattern inline_handler() {
+  handler_call() as $body where {
+    not $body <: contains JsFunctionBody(),
+    not $body <: contains JsFunctionExpression(),
+    not $body <: contains JsSequenceExpression(),
+    not $body <: contains JsAssignmentExpression(),
+    not $body <: contains JsPreUpdateExpression(),
+    not $body <: contains JsPostUpdateExpression(),
+    not $body <: contains JsArrowFunctionExpression(body=JsConditionalExpression()),
+    not $body <: contains JsArrowFunctionExpression(body=JsParenthesizedExpression(expression=JsConditionalExpression()))
+  }
+}
+
+pattern jsx_handler($callback) {
+  JsxAttribute(name=$name, initializer=JsxAttributeInitializerClause(value=JsxExpressionAttributeValue(expression=$callback))) where {
+    $name <: r"on[A-Z].*"
+  }
+}
+
+pattern compact_return($expression) {
+  JsFunctionBody(statements=[JsReturnStatement(argument=$expression)]) as $body where {
+    $expression <: inline_handler(),
+    not $body <: r"(?s).*(?:/\*|//).*"
+  }
+}
+
+or {
+  JsArrowFunctionExpression(body=$body) as $arrow where {
+    not $body <: JsFunctionBody(),
+    not $body <: or {
+      JsxTagExpression(),
+      JsParenthesizedExpression(expression=JsxTagExpression())
+    },
+    not and { $body <: handler_call(), $arrow <: within jsx_handler($arrow) },
+    $body <: or {
+      r"(?s).*\n.*",
+      contains JsConditionalExpression(),
+      contains JsSequenceExpression()
+    },
+    register_diagnostic(span=$body, message="Use a block and an explicit return for a multiline or branching arrow body.", severity="error", fix_kind="safe"),
+    $body => `{ return $body; }`
+  },
+  jsx_handler(JsArrowFunctionExpression(body=$body)) where {
+    $body <: compact_return($expression),
+    register_diagnostic(span=$body, message="Keep an inline JSX handler as one call expression. Extract logic into a named component-level useCallback.", severity="error", fix_kind="safe"),
+    $body => `$expression`
+  },
+  jsx_handler(JsArrowFunctionExpression(body=$body)) where {
+    not $body <: inline_handler(),
+    not $body <: compact_return(),
+    register_diagnostic(span=$body, message="Keep an inline JSX handler as one call expression. Extract logic into a named component-level useCallback.", severity="error")
+  },
+  jsx_handler(JsFunctionExpression() as $callback) where {
+    register_diagnostic(span=$callback, message="Use a named component-level useCallback instead of an inline JSX function.", severity="error")
+  }
+}