@apptoolkit/harness 0.0.0-stage → 1.0.0

package/dist/npm/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/npm/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/npm/payload/author-style/package-lock.json

@@ -0,0 +1,180 @@
+{
+  "name": "harness-author-style",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "harness-author-style",
+      "devDependencies": {
+        "@biomejs/biome": "2.5.15",
+        "typescript": "5.9.3",
+        "zod": "4.6.7"
+      },
+      "engines": {
+        "node": ">=24"
+      }
+    },
+    "node_modules/@biomejs/biome": {
+      "version": "2.5.15",
+      "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.5.15.tgz",
+      "integrity": "sha512-WZTW4slm/pdkh92K6t/3aEN++44JD1PQ7squ7RCMLI1flHGl43DVOIGXvCjHiZgBMO1V4uYxoFNtqrIA4qGuIQ==",
+      "dev": true,
+      "bin": {
+        "biome": "bin/biome"
+      },
+      "engines": {
+        "node": ">=14.21.3"
+      },
+      "optionalDependencies": {
+        "@biomejs/cli-darwin-arm64": "2.5.15",
+        "@biomejs/cli-darwin-x64": "2.5.15",
+        "@biomejs/cli-linux-arm64": "2.5.15",
+        "@biomejs/cli-linux-arm64-musl": "2.5.15",
+        "@biomejs/cli-linux-x64": "2.5.15",
+        "@biomejs/cli-linux-x64-musl": "2.5.15",
+        "@biomejs/cli-win32-arm64": "2.5.15",
+        "@biomejs/cli-win32-x64": "2.5.15"
+      }
+    },
+    "node_modules/@biomejs/cli-darwin-arm64": {
+      "version": "2.5.15",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.5.15.tgz",
+      "integrity": "sha512-BZVzFhJ/mUvTLMYbc9x6el0o2Uv5zP7bACYyhFb6fSc1giroXm7PL0a5KqMJ9F+/BnkYRjagD/ROSDVOZ6eapg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@biomejs/cli-darwin-x64": {
+      "version": "2.5.15",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.5.15.tgz",
+      "integrity": "sha512-V5Kw63V+fVGNFhFrizDxMbGXAzZCh8kYzJpy3GI6gTapWDg7bZK9oYC9CbVgQSEdTnupz0U5Efz8Ev+5vdBBXw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@biomejs/cli-linux-arm64": {
+      "version": "2.5.15",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.5.15.tgz",
+      "integrity": "sha512-XaG7P7eeSLYETD3K9grfB0mQmpLQZjygdbsxekWBJAg4am79fGAtRpfRyNnTvXB2fZFNnJZG3nXm7HBat0+VUw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@biomejs/cli-linux-arm64-musl": {
+      "version": "2.5.15",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.5.15.tgz",
+      "integrity": "sha512-tGzZUTcJCV7tj5Adh/Gn6nR4MycqA3iohq2LEcrarAgRBkU0h0OKd2UzCRkOsOYOuUGaUJb4YmqRqyy2feGGSw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@biomejs/cli-linux-x64": {
+      "version": "2.5.15",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.5.15.tgz",
+      "integrity": "sha512-xE4iEW/3LqlYj9GFgGrFsFSH51dEEpUbYWBfeOv0q87WkUDxK2o/HhreSb7qMJqck70RVM6Lg96hgedcAYcOkA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@biomejs/cli-linux-x64-musl": {
+      "version": "2.5.15",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.5.15.tgz",
+      "integrity": "sha512-IlxUcyxilVGPsE008x13pWdkTbU3nQpP2i9b5UrbOYj6goBkKsRX1XB7yJLcV+O1H9LBchIIm4adOaVLZBX0ZQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@biomejs/cli-win32-arm64": {
+      "version": "2.5.15",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.5.15.tgz",
+      "integrity": "sha512-2kPKzhNlm8C+Ru3GcO0Me2ODkCBLrVOUNuyi84RJyWDVKAA4+Kjj3jMjL938lF6BRfvltC4vB2nPY9SvN51Ovg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@biomejs/cli-win32-x64": {
+      "version": "2.5.15",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.5.15.tgz",
+      "integrity": "sha512-yAzh4UqEImV6Hcy0zjUqNfJAsUhoD64FBQCdTG8Md/Z2wQeVP/ZmJ3XRYAs1g8J9fjTFyl2fCtc5FB5til47+g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.6.7",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.7.tgz",
+      "integrity": "sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/dist/npm/payload/author-style/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "harness-author-style",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "check": "node check.ts",
+    "test": "node --test *.test.ts"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "typescript": "5.9.3",
+    "zod": "4.6.7"
+  }
+}

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