@apptoolkit/harness 0.0.0-stage → 1.0.0

package/dist/npm/payload/author-style/react-module.ts

@@ -0,0 +1,255 @@
+import ts from 'typescript';
+
+import type { SourceIssue } from './source-policy.ts';
+
+type ReactBindings = { types: Set<string>; wrappers: Set<string>; namespaces: Map<string, boolean> };
+
+const componentTypes = new Set(['FC', 'FunctionComponent']);
+const componentWrappers = new Set(['memo', 'forwardRef']);
+const componentName = /^[A-Z][A-Za-z0-9]*$/;
+const { AmpersandAmpersandToken, BarBarToken, QuestionQuestionToken } = ts.SyntaxKind;
+const renderOperators = new Set([BarBarToken, QuestionQuestionToken]);
+
+function reactBindings(file: ts.SourceFile): ReactBindings {
+  const bindings: ReactBindings = { types: new Set(), wrappers: new Set(), namespaces: new Map() };
+
+  for (const statement of file.statements.filter(ts.isImportDeclaration)) {
+    if (!ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== 'react') {
+      continue;
+    }
+
+    const clause = statement.importClause;
+
+    if (clause?.name) {
+      bindings.namespaces.set(clause.name.text, !clause.isTypeOnly);
+    }
+
+    const named = clause?.namedBindings;
+
+    if (!named) {
+      continue;
+    }
+
+    if (ts.isNamespaceImport(named)) {
+      bindings.namespaces.set(named.name.text, !clause.isTypeOnly);
+      continue;
+    }
+
+    for (const specifier of named.elements) {
+      const imported = (specifier.propertyName ?? specifier.name).text;
+      const valueImport = !clause.isTypeOnly && !specifier.isTypeOnly;
+
+      if (componentTypes.has(imported)) {
+        bindings.types.add(specifier.name.text);
+      }
+
+      if (componentWrappers.has(imported) && valueImport) {
+        bindings.wrappers.add(specifier.name.text);
+      }
+
+      if (imported === 'default') {
+        bindings.namespaces.set(specifier.name.text, valueImport);
+      }
+    }
+  }
+
+  return bindings;
+}
+
+function unwrap(expression: ts.Expression): ts.Expression {
+  while (
+    ts.isParenthesizedExpression(expression) ||
+    ts.isAsExpression(expression) ||
+    ts.isSatisfiesExpression(expression) ||
+    ts.isNonNullExpression(expression)
+  ) {
+    expression = expression.expression;
+  }
+
+  return expression;
+}
+
+function isJsxResult(expression: ts.Expression): boolean {
+  const node = unwrap(expression);
+
+  if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) {
+    return true;
+  }
+
+  if (ts.isConditionalExpression(node)) {
+    return isJsxResult(node.whenTrue) || isJsxResult(node.whenFalse);
+  }
+
+  if (ts.isBinaryExpression(node)) {
+    if (node.operatorToken.kind === AmpersandAmpersandToken) {
+      return isJsxResult(node.right);
+    }
+
+    return renderOperators.has(node.operatorToken.kind) && (isJsxResult(node.left) || isJsxResult(node.right));
+  }
+
+  return ts.isArrayLiteralExpression(node) && node.elements.some(isJsxResult);
+}
+
+function returnsJsx(body: ts.ConciseBody): boolean {
+  if (!ts.isBlock(body)) {
+    return isJsxResult(body);
+  }
+
+  function visit(node: ts.Node): boolean {
+    if (ts.isReturnStatement(node)) {
+      return node.expression !== undefined && isJsxResult(node.expression);
+    }
+
+    if (ts.isFunctionLike(node) || ts.isClassLike(node)) {
+      return false;
+    }
+
+    return ts.forEachChild(node, visit) === true;
+  }
+
+  return visit(body);
+}
+
+function hasReactType(type: ts.TypeNode | undefined, bindings: ReactBindings): boolean {
+  if (!type || !ts.isTypeReferenceNode(type)) {
+    return false;
+  }
+
+  const name = type.typeName;
+
+  if (ts.isIdentifier(name)) {
+    return bindings.types.has(name.text);
+  }
+
+  return ts.isIdentifier(name.left) && bindings.namespaces.has(name.left.text) && componentTypes.has(name.right.text);
+}
+
+function isReactWrapper(node: ts.Expression, bindings: ReactBindings): boolean {
+  if (!ts.isCallExpression(node)) {
+    return false;
+  }
+
+  const callee = unwrap(node.expression);
+
+  if (ts.isIdentifier(callee)) {
+    return bindings.wrappers.has(callee.text);
+  }
+
+  if (!ts.isPropertyAccessExpression(callee) || !ts.isIdentifier(callee.expression)) {
+    return false;
+  }
+
+  return bindings.namespaces.get(callee.expression.text) === true && componentWrappers.has(callee.name.text);
+}
+
+function defaultTargets(file: ts.SourceFile): Set<string> {
+  const names = new Set<string>();
+
+  for (const statement of file.statements) {
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+      const value = unwrap(statement.expression);
+
+      if (ts.isIdentifier(value)) {
+        names.add(value.text);
+      }
+    }
+
+    if (ts.isExportDeclaration(statement) && !statement.isTypeOnly && !statement.moduleSpecifier) {
+      const clause = statement.exportClause;
+
+      for (const specifier of clause && ts.isNamedExports(clause) ? clause.elements : []) {
+        if (!specifier.isTypeOnly && specifier.name.text === 'default') {
+          names.add((specifier.propertyName ?? specifier.name).text);
+        }
+      }
+    }
+  }
+
+  return names;
+}
+
+function isJsxFunction(node: ts.Expression): boolean {
+  return (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && returnsJsx(node.body);
+}
+
+export function findReactModuleIssues(source: string, fileName: string): SourceIssue[] {
+  if (!fileName.endsWith('.tsx')) {
+    return [];
+  }
+
+  const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const bindings = reactBindings(file);
+  const defaults = defaultTargets(file);
+  const issues: SourceIssue[] = [];
+  let seenComponent = false;
+
+  function checkComponent(node: ts.Node, name?: string, needsReactType = false): void {
+    const position = file.getLineAndCharacterOfPosition(node.getStart(file));
+    const location = { line: position.line + 1, column: position.character + 1 };
+
+    if (seenComponent) {
+      issues.push({ ...location, message: 'Keep one React component per file.' });
+    }
+
+    seenComponent = true;
+
+    if (!name || !componentName.test(name)) {
+      issues.push({ ...location, message: 'Declare a named const component in PascalCase and export it as default.' });
+
+      return;
+    }
+
+    if (!defaults.has(name)) {
+      issues.push({ ...location, message: "Export the file's named React component as default." });
+    }
+
+    if (needsReactType) {
+      issues.push({
+        ...location,
+        message: 'Annotate React arrow components and function expressions with an imported React FC type.',
+      });
+    }
+  }
+
+  for (const statement of file.statements) {
+    if (ts.isVariableStatement(statement)) {
+      const constant = (statement.declarationList.flags & ts.NodeFlags.BlockScoped) === ts.NodeFlags.Const;
+
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name) || !declaration.initializer) {
+          continue;
+        }
+
+        const name = declaration.name.text;
+        const value = unwrap(declaration.initializer);
+        const namedRender = (componentName.test(name) || defaults.has(name)) && isJsxFunction(value);
+        const hasType = hasReactType(declaration.type, bindings);
+        const wrapped = isReactWrapper(value, bindings);
+
+        if (hasType || wrapped || namedRender) {
+          checkComponent(declaration, constant ? name : undefined, !hasType && !wrapped);
+        }
+      }
+    }
+
+    if (ts.isFunctionDeclaration(statement) && statement.body && returnsJsx(statement.body)) {
+      const name = statement.name?.text ?? '';
+      const isDefault = statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword);
+
+      if (isDefault || defaults.has(name) || componentName.test(name)) {
+        checkComponent(statement);
+      }
+    }
+
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+      const value = unwrap(statement.expression);
+
+      if (isJsxFunction(value) || isReactWrapper(value, bindings)) {
+        checkComponent(statement);
+      }
+    }
+  }
+
+  return issues;
+}

package/dist/npm/payload/author-style/source-policy.llm.md

@@ -0,0 +1,17 @@
+# Source policy map
+
+- [Comments and protected headers](#comments-and-protected-headers)
+- [Type patterns](#type-patterns)
+- [Tests](#tests)
+
+## Comments and protected headers
+
+`hasGeneratedHeader` examines leading comment trivia. `collectComments` visits syntax tokens without mistaking JSX text and literals for comments. `sqlMarkers` identifies supported marker positions. Parsed TypeScript reference directives are handled by `findSourcePolicyIssues`.
+
+## Type patterns
+
+`zodBindings` and `inferredLocalSchema` identify aliases bound to supported Zod imports. `findSourcePolicyIssues` verifies adjacency for local top-level declarations. `isDoubleAssertion` detects chained assertions, including parenthesized forms.
+
+## Tests
+
+`source-policy.test.ts` covers comment boundaries, valid directives, inferred types, recognized Zod imports and double assertions. Native type checks remain separate.

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

@@ -0,0 +1,70 @@
+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/npm/payload/author-style/source-policy.ts

@@ -0,0 +1,215 @@
+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/npm/payload/author-style/spacing.llm.md

@@ -0,0 +1,17 @@
+# 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.