@apptoolkit/harness 1.0.0 → 1.0.2

package/dist/bun/npm/payload/author-style/source-policy.test.ts

@@ -1,70 +0,0 @@
-import assert from 'node:assert/strict';
-import { test } from 'node:test';
-import { findSourcePolicyIssues } from './source-policy.ts';
-
-test('separates real comments from strings, regular expressions and JSX text', () => {
-  const source = [
-    '/// <reference types="node" />',
-    "export const url = 'https://example.test';",
-    'export const pattern = /https?:\\/\\//;',
-    'export const label = <p>// literal {/* explanatory text */}</p>;',
-    'export const query = sql /* sql */`SELECT 1`;',
-    'export const number = 1; // explanatory suffix',
-    '/** explanatory docs */',
-    'export const end = 2;',
-    'export function empty(/* parameters */) { /* body */ }',
-    'export const options = [/* element */];',
-    'export const outside = /* sql */`SELECT 1`;',
-    '/// <reference explanatory text',
-  ].join('\n');
-
-  assert.deepEqual(
-    findSourcePolicyIssues(source, 'example.tsx').map(({ line }) => line),
-    [4, 6, 7, 9, 9, 10, 11, 12],
-  );
-});
-
-test('checks local schema aliases together and ignores aliases for imported schemas', () => {
-  const source = [
-    "import { z as contract } from 'zod';",
-    "import { shared } from './shared.ts';",
-    'const schema = contract.string();',
-    'type Input = contract.input<typeof schema>;',
-    'type Output = contract.output<typeof schema>;',
-    'const late = contract.number();',
-    'type Shared = contract.infer<typeof shared>;',
-    'type Late = contract.infer<typeof late>;',
-  ].join('\n');
-
-  assert.deepEqual(
-    findSourcePolicyIssues(source, 'example.ts').map(({ line }) => line),
-    [8],
-  );
-});
-
-test('recognizes a default or namespace binding from a versioned Zod entry point', () => {
-  for (const importText of ["import schema from 'zod/v4';", "import * as schema from 'zod/v3';"]) {
-    const source = [
-      importText,
-      'const profile = schema.string();',
-      'export const separator = 1;',
-      'export type Profile = schema.infer<typeof profile>;',
-    ].join('\n');
-
-    assert.match(findSourcePolicyIssues(source, 'example.ts')[0]?.message ?? '', /Place Profile alongside/);
-  }
-});
-
-test('rejects chained and parenthesized double assertions without rejecting satisfies', () => {
-  const source = [
-    'export const first = value as never as string;',
-    'export const second = (value as never) as string;',
-    'export const third = <string>(<never>value);',
-    'export const allowed = { id: 1 } as const satisfies { id: number };',
-  ].join('\n');
-
-  assert.deepEqual(
-    findSourcePolicyIssues(source, 'example.ts').map(({ line }) => line),
-    [1, 2, 3],
-  );
-});

package/dist/bun/npm/payload/author-style/source-policy.ts

@@ -1,215 +0,0 @@
-import ts from 'typescript';
-
-export type SourceIssue = {
-  line: number;
-  column: number;
-  message: string;
-};
-
-export function hasGeneratedHeader(source: string): boolean {
-  const leading = ts.getLeadingCommentRanges(source, ts.getShebang(source)?.length ?? 0);
-
-  return (
-    leading?.some(({ pos, end }) => {
-      const comment = source.slice(pos, end);
-
-      return /(?:^|\r?\n)\s*(?:\/\/|\/\*+|\*)\s*(?:@generated\b|Code generated\b)/i.test(comment);
-    }) ?? false
-  );
-}
-
-function collectComments(file: ts.SourceFile): Map<number, number> {
-  const comments = new Map<number, number>();
-
-  function collect(start: number, end: number): void {
-    comments.set(start, end);
-  }
-
-  function visit(node: ts.Node): void {
-    if (ts.isJsxText(node)) {
-      return;
-    }
-
-    const children = node.getChildren(file);
-
-    if (children.length === 0 && node.kind >= ts.SyntaxKind.FirstToken && node.kind <= ts.SyntaxKind.LastToken) {
-      const from = node.getFullStart();
-
-      ts.forEachLeadingCommentRange(file.text, from, collect);
-      ts.forEachTrailingCommentRange(file.text, from, collect);
-    }
-
-    for (const child of children) {
-      visit(child);
-    }
-  }
-
-  visit(file);
-
-  return comments;
-}
-
-function sqlMarkers(file: ts.SourceFile): Set<number> {
-  const markers = new Set<number>();
-
-  function visit(node: ts.Node): void {
-    if (
-      ts.isTaggedTemplateExpression(node) &&
-      ts.isIdentifier(node.tag) &&
-      ['sql', 'database', 'client', 'transaction'].includes(node.tag.text)
-    ) {
-      const start = node.tag.end;
-      const end = node.template.getStart(file);
-      const trivia = file.text.slice(start, end);
-
-      if (/^\s*\/\* sql \*\/\s*$/.test(trivia)) {
-        markers.add(start + trivia.indexOf('/* sql */'));
-      }
-    }
-
-    ts.forEachChild(node, visit);
-  }
-
-  visit(file);
-
-  return markers;
-}
-
-function zodBindings(file: ts.SourceFile): Set<string> {
-  const names = new Set<string>();
-
-  for (const statement of file.statements) {
-    if (
-      !ts.isImportDeclaration(statement) ||
-      !ts.isStringLiteral(statement.moduleSpecifier) ||
-      !['zod', 'zod/v3', 'zod/v4'].includes(statement.moduleSpecifier.text)
-    ) {
-      continue;
-    }
-
-    const clause = statement.importClause;
-    const bindings = clause?.namedBindings;
-
-    if (clause?.name) {
-      names.add(clause.name.text);
-    }
-
-    if (bindings && ts.isNamespaceImport(bindings)) {
-      names.add(bindings.name.text);
-    } else if (bindings) {
-      for (const binding of bindings.elements) {
-        if ((binding.propertyName ?? binding.name).text === 'z') {
-          names.add(binding.name.text);
-        }
-      }
-    }
-  }
-
-  return names;
-}
-
-function inferredLocalSchema(type: ts.TypeNode, bindings: ReadonlySet<string>): string | undefined {
-  if (!ts.isTypeReferenceNode(type) || !ts.isQualifiedName(type.typeName)) {
-    return undefined;
-  }
-
-  const { left, right } = type.typeName;
-  const query = type.typeArguments?.[0];
-
-  if (
-    !ts.isIdentifier(left) ||
-    !bindings.has(left.text) ||
-    !['infer', 'input', 'output'].includes(right.text) ||
-    !query ||
-    !ts.isTypeQueryNode(query) ||
-    !ts.isIdentifier(query.exprName)
-  ) {
-    return undefined;
-  }
-
-  return query.exprName.text;
-}
-
-function isDoubleAssertion(node: ts.Node): boolean {
-  if (!ts.isAsExpression(node) && !ts.isTypeAssertionExpression(node)) {
-    return false;
-  }
-
-  let value = node.expression;
-
-  while (ts.isParenthesizedExpression(value)) {
-    value = value.expression;
-  }
-
-  return ts.isAsExpression(value) || ts.isTypeAssertionExpression(value);
-}
-
-export function findSourcePolicyIssues(source: string, fileName: string): SourceIssue[] {
-  const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true);
-  const issues: SourceIssue[] = [];
-
-  function report(position: number, message: string): void {
-    const location = file.getLineAndCharacterOfPosition(position);
-
-    issues.push({ line: location.line + 1, column: location.character + 1, message });
-  }
-
-  function visit(node: ts.Node): void {
-    if (isDoubleAssertion(node)) {
-      report(node.getStart(file), 'Avoid double assertions. Validate or narrow the value before using it.');
-    }
-
-    ts.forEachChild(node, visit);
-  }
-
-  visit(file);
-
-  const references = [...file.referencedFiles, ...file.typeReferenceDirectives, ...file.libReferenceDirectives];
-  const markers = sqlMarkers(file);
-
-  for (const [start, end] of collectComments(file)) {
-    const recognizedReference =
-      source.startsWith('///', start) && references.some((reference) => reference.pos >= start && reference.end <= end);
-
-    if (!markers.has(start) && !recognizedReference) {
-      report(start, 'Use names and code structure to explain behavior. Move explanatory comments out of source.');
-    }
-  }
-
-  const localDeclarations = new Map<string, ts.VariableStatement>();
-
-  for (const statement of file.statements) {
-    if (ts.isVariableStatement(statement)) {
-      for (const declaration of statement.declarationList.declarations) {
-        if (ts.isIdentifier(declaration.name)) {
-          localDeclarations.set(declaration.name.text, statement);
-        }
-      }
-    }
-  }
-
-  const preceding = new Map<string, ts.Statement>();
-  const bindings = zodBindings(file);
-
-  for (const [index, statement] of file.statements.entries()) {
-    if (!ts.isTypeAliasDeclaration(statement)) {
-      continue;
-    }
-
-    const schema = inferredLocalSchema(statement.type, bindings);
-
-    if (!schema) {
-      continue;
-    }
-
-    const declaration = localDeclarations.get(schema);
-
-    if (declaration && file.statements[index - 1] !== (preceding.get(schema) ?? declaration)) {
-      report(statement.getStart(file), `Place ${statement.name.text} alongside its source schema ${schema}.`);
-    }
-
-    preceding.set(schema, statement);
-  }
-
-  return issues.sort((left, right) => left.line - right.line || left.column - right.column);
-}

package/dist/bun/npm/payload/author-style/spacing.llm.md

@@ -1,17 +0,0 @@
-# Statement spacing map
-
-- [Binding discovery](#binding-discovery)
-- [Phase detection](#phase-detection)
-- [Diagnostics](#diagnostics)
-
-## Binding discovery
-
-`findBindings` identifies supported hook and assertion names from syntax. `isSeparatedHookCall` and `isAssertion` recognize the supported expression shapes. They do not resolve arbitrary runtime aliases or lexical shadowing.
-
-## Phase detection
-
-`statementPhase` groups declarations, operations and assertions and identifies independent control flow. `hasBlankLine` measures the boundary outside comment ownership. Class member spacing has a separate check in `member-spacing.ts`.
-
-## Diagnostics
-
-`findSpacingIssues` checks parse errors and visits statement lists without changing source. `spacing.test.ts` covers independent phases, grouped declarations and assertions, imports, hooks, comments and parse failures. See the [check matrix](README.md#deterministic-checks) for scope.

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

@@ -1,174 +0,0 @@
-import assert from 'node:assert/strict';
-import test from 'node:test';
-
-import { findSpacingIssues } from './spacing.ts';
-
-function issueLines(source: string, fileName = 'example.ts'): number[] {
-  return findSpacingIssues(source, fileName).map((issue) => issue.line);
-}
-
-test('reports transitions while preserving declaration, operation, and assertion groups', () => {
-  const source = [
-    "import { expect as verify } from '@playwright/test';",
-    "import { build } from './fixtures';",
-    '',
-    'async function scenario() {',
-    '  const first = build();',
-    '  const second = build();',
-    '  await first.save();',
-    '  await second.save();',
-    '  await verify.poll(read).toBe(1);',
-    '  (expect(first)).toBeDefined();',
-    '  run("verify(first)");',
-    '  return first;',
-    '}',
-  ].join('\n');
-
-  assert.deepEqual(issueLines(source), [7, 9, 11, 12]);
-  assert.deepEqual(findSpacingIssues(source, 'example.spec.ts')[0], {
-    line: 7,
-    column: 3,
-    message: 'Separate statement phases with a blank line.',
-  });
-});
-
-test('preserves adjacent imports and schema type pairs', () => {
-  const source = [
-    "import { z } from 'zod';",
-    "import { read } from './input';",
-    'const schema = z.string();',
-    'type Value = z.infer<typeof schema>;',
-    'const value: Value = schema.parse(read());',
-  ].join('\n');
-
-  assert.deepEqual(issueLines(source), []);
-});
-
-test('recognizes TypeScript and TSX hooks while preserving ordinary declarations', () => {
-  const source = [
-    "import * as ReactAlias from 'react';",
-    "import { useForm as makeForm } from 'react-hook-form';",
-    "import { useState as state } from 'react';",
-    '',
-    'export function Component() {',
-    '  const id = 1;',
-    '  const [value] = state(id);',
-    '  const title = (ReactAlias.useMemo(() => value, [value]) satisfies number);',
-    '  const form = makeForm({});',
-    '  ReactAlias.useEffect(() => {}, []);',
-    '  return <button id={form.id}>{title}</button>;',
-    '}',
-  ].join('\n');
-
-  assert.deepEqual(issueLines(source, 'Component.tsx'), [8, 9, 10, 11]);
-});
-
-test('preserves type-only imports, unsupported hook aliases and namespace assertions', () => {
-  const source = [
-    "import { type useMemo as memo } from 'react';",
-    "import { useForm as form } from 'other';",
-    "import type { expect as verify } from '@playwright/test';",
-    "import * as checks from '@playwright/test';",
-    '',
-    'function example() {',
-    '  const first = memo(() => value, []);',
-    '  const second = form();',
-    '  const third = other.useEffect(run);',
-    '  const fourth = wrap(useMemo(run, []));',
-    '',
-    '  inspect();',
-    '  checks.expect(first);',
-    '  verify(second);',
-    '}',
-  ].join('\n');
-
-  assert.deepEqual(issueLines(source), []);
-});
-
-test('recognizes default React bindings and direct hooks inside typed wrappers', () => {
-  const source = [
-    "import ReactAlias from 'react';",
-    '',
-    'function example() {',
-    '  let before;',
-    '  const first = <number>ReactAlias.useMemo(() => 1, []);',
-    '  const second = useCallback(run, [])!;',
-    '  const third = useReducer(reducer, 0) as State;',
-    '  const fourth = useForm({});',
-    '  const after = 1;',
-    '}',
-  ].join('\n');
-
-  assert.deepEqual(issueLines(source), [5, 6, 7, 8, 9]);
-});
-
-test('uses the full control-flow statement as one phase and leaves block edges alone', () => {
-  const phases = [
-    'if (ready) { act(); } else if (pending) { wait(); } else { reset(); }',
-    'for (;;) {}',
-    'for (const item of items) {}',
-    'for (const key in record) {}',
-    'while (ready) {}',
-    'do {} while (ready);',
-    'switch (value) { default: break; }',
-    'try { act(); } catch (cause) { fail(cause); }',
-    'class Fixture {}',
-    'function nested() {}',
-    'throw new Error("Synthetic failure.");',
-  ];
-
-  for (const phase of phases) {
-    const source = ['function run() {', '  prepare();', `  ${phase}`, '  finish();', '}'].join('\n');
-
-    assert.deepEqual(issueLines(source), [3, 4], phase);
-  }
-});
-
-test('scans namespaces and switch cases independently and sorts findings by source position', () => {
-  const source = [
-    'namespace Example {',
-    '  const start = read();',
-    '  run(start);',
-    '  switch (start) {',
-    '    case 1:',
-    '      const item = read();',
-    '      run(item);',
-    '      break;',
-    '    default:',
-    '      const other = read();',
-    '      run(other);',
-    '  }',
-    '  finish();',
-    '}',
-    'function after() {}',
-  ].join('\n');
-
-  assert.deepEqual(issueLines(source), [3, 4, 7, 11, 13, 15]);
-});
-
-test('handles CRLF and ignores blank lines inside leading or trailing comments', () => {
-  const source =
-    'function run() {\r\n  prepare(); /* trailing\r\n\r\n  detail */\r\n  /* leading\r\n\r\n  detail */\r\n  return value;\r\n}\r\n';
-  const spaced = source.replace('detail */\r\n  /*', 'detail */\r\n \t\r\n  /*');
-
-  assert.deepEqual(issueLines(source), [8]);
-  assert.deepEqual(issueLines(spaced), []);
-});
-
-test('reports same-line phases without modifying the supplied source', () => {
-  const source = 'function run() { inspect(); return value; }';
-
-  assert.deepEqual(findSpacingIssues(source, 'example.ts'), [
-    { line: 1, column: source.indexOf('return') + 1, message: 'Separate statement phases with a blank line.' },
-  ]);
-});
-
-test('skips generated source and surfaces syntax and invalid input errors', () => {
-  assert.deepEqual(issueLines('// @generated\nconst = invalid;'), []);
-  assert.deepEqual(issueLines(''), []);
-  assert.throws(() => findSpacingIssues('const = invalid;', 'broken.ts'), {
-    name: 'SyntaxError',
-    message: /Cannot check statement spacing in broken\.ts:/,
-  });
-  assert.throws(() => findSpacingIssues('const value = 1;', ''), /fileName/);
-});

package/dist/bun/npm/payload/author-style/spacing.ts

@@ -1,211 +0,0 @@
-import ts from 'typescript';
-import { z } from 'zod';
-import { hasGeneratedHeader } from './source-policy.ts';
-
-type SpacingIssue = { line: number; column: number; message: string };
-type StatementPhase = 'declaration' | 'operation' | 'assertion' | 'independent' | 'other';
-
-type SpacingBindings = {
-  assertions: Set<string>;
-  hooks: Set<string>;
-  hookNamespaces: Map<string, ReadonlySet<string>>;
-};
-
-const spacingInput = z.object({ source: z.string(), fileName: z.string().min(1) });
-const spacingMessage = 'Separate statement phases with a blank line.';
-const reactHooks = new Set(['useEffect', 'useMemo', 'useCallback', 'useReducer']);
-const formHooks = new Set(['useForm']);
-const supportedHooks = new Map([
-  ['react', reactHooks],
-  ['@tanstack/react-form', formHooks],
-  ['react-hook-form', formHooks],
-]);
-
-function findBindings(file: ts.SourceFile): SpacingBindings {
-  const bindings: SpacingBindings = {
-    assertions: new Set(['expect']),
-    hooks: new Set([...reactHooks, ...formHooks]),
-    hookNamespaces: new Map([['React', reactHooks]]),
-  };
-
-  for (const statement of file.statements) {
-    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
-      continue;
-    }
-
-    const clause = statement.importClause;
-
-    if (!clause || clause.isTypeOnly) {
-      continue;
-    }
-
-    const hookNames = supportedHooks.get(statement.moduleSpecifier.text);
-    const namedBindings = clause.namedBindings;
-
-    if (hookNames && clause.name) {
-      bindings.hookNamespaces.set(clause.name.text, hookNames);
-    }
-
-    if (hookNames && namedBindings && ts.isNamespaceImport(namedBindings)) {
-      bindings.hookNamespaces.set(namedBindings.name.text, hookNames);
-    }
-
-    if (!namedBindings || !ts.isNamedImports(namedBindings)) {
-      continue;
-    }
-
-    for (const element of namedBindings.elements) {
-      if (element.isTypeOnly) {
-        continue;
-      }
-
-      const importedName = element.propertyName?.text ?? element.name.text;
-
-      if (importedName === 'expect') {
-        bindings.assertions.add(element.name.text);
-      }
-
-      if (hookNames?.has(importedName)) {
-        bindings.hooks.add(element.name.text);
-      }
-    }
-  }
-
-  return bindings;
-}
-
-function isSeparatedHookCall(expression: ts.Expression, bindings: SpacingBindings): boolean {
-  if (
-    ts.isParenthesizedExpression(expression) ||
-    ts.isAssertionExpression(expression) ||
-    ts.isSatisfiesExpression(expression) ||
-    ts.isNonNullExpression(expression)
-  ) {
-    return isSeparatedHookCall(expression.expression, bindings);
-  }
-
-  if (!ts.isCallExpression(expression)) {
-    return false;
-  }
-
-  const callee = expression.expression;
-
-  if (ts.isIdentifier(callee)) {
-    return bindings.hooks.has(callee.text);
-  }
-
-  return (
-    ts.isPropertyAccessExpression(callee) &&
-    ts.isIdentifier(callee.expression) &&
-    (bindings.hookNamespaces.get(callee.expression.text)?.has(callee.name.text) ?? false)
-  );
-}
-
-function isAssertion(expression: ts.Expression, names: ReadonlySet<string>): boolean {
-  if (
-    ts.isCallExpression(expression) ||
-    ts.isPropertyAccessExpression(expression) ||
-    ts.isAwaitExpression(expression) ||
-    ts.isParenthesizedExpression(expression)
-  ) {
-    return isAssertion(expression.expression, names);
-  }
-
-  return ts.isIdentifier(expression) && names.has(expression.text);
-}
-
-function statementPhase(statement: ts.Statement, bindings: SpacingBindings): StatementPhase {
-  if (ts.isVariableStatement(statement)) {
-    const hasHook = statement.declarationList.declarations.some((declaration) => {
-      return declaration.initializer !== undefined && isSeparatedHookCall(declaration.initializer, bindings);
-    });
-
-    return hasHook ? 'independent' : 'declaration';
-  }
-
-  if (ts.isExpressionStatement(statement)) {
-    const expression = statement.expression;
-
-    if (isSeparatedHookCall(expression, bindings)) {
-      return 'independent';
-    }
-
-    return isAssertion(expression, bindings.assertions) ? 'assertion' : 'operation';
-  }
-
-  if (
-    ts.isIfStatement(statement) ||
-    ts.isFunctionDeclaration(statement) ||
-    ts.isClassDeclaration(statement) ||
-    ts.isIterationStatement(statement, false) ||
-    ts.isSwitchStatement(statement) ||
-    ts.isTryStatement(statement) ||
-    ts.isThrowStatement(statement)
-  ) {
-    return 'independent';
-  }
-
-  return 'other';
-}
-
-function hasBlankLine(previous: ts.Statement, current: ts.Statement, file: ts.SourceFile): boolean {
-  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);
-
-  return /\r?\n[^\S\r\n]*\r?\n/.test(file.text.slice(previousEnd, currentStart));
-}
-
-export function findSpacingIssues(source: string, fileName: string): readonly SpacingIssue[] {
-  spacingInput.parse({ source, fileName });
-
-  if (hasGeneratedHeader(source)) {
-    return [];
-  }
-
-  const parsed = ts.transpileModule(source, {
-    fileName: fileName.replace(/\.d\.(c|m)?ts$/, '.$1ts'),
-    reportDiagnostics: true,
-  });
-  const errors = parsed.diagnostics?.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
-
-  if (errors && errors.length > 0) {
-    const details = errors.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
-
-    throw new SyntaxError(`Cannot check statement spacing in ${fileName}: ${details.join(' ')}`);
-  }
-
-  const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true);
-  const bindings = findBindings(file);
-  const issues: SpacingIssue[] = [];
-
-  function visit(node: ts.Node): void {
-    if (ts.isSourceFile(node) || ts.isBlock(node) || ts.isModuleBlock(node) || ts.isCaseOrDefaultClause(node)) {
-      let previous: ts.Statement | undefined;
-      let previousPhase: StatementPhase = 'other';
-
-      for (const current of node.statements) {
-        const currentPhase = statementPhase(current, bindings);
-        const changesPhase = previousPhase !== 'other' && currentPhase !== 'other' && previousPhase !== currentPhase;
-        const independent = previousPhase === 'independent' || currentPhase === 'independent';
-        const needsSeparation = independent || changesPhase || ts.isReturnStatement(current);
-
-        if (previous && needsSeparation && !hasBlankLine(previous, current, file)) {
-          const { line, character } = file.getLineAndCharacterOfPosition(current.getStart(file));
-
-          issues.push({ line: line + 1, column: character + 1, message: spacingMessage });
-        }
-
-        previous = current;
-        previousPhase = currentPhase;
-      }
-    }
-
-    ts.forEachChild(node, visit);
-  }
-
-  visit(file);
-
-  return issues.sort((left, right) => left.line - right.line || left.column - right.column);
-}