wrec 0.34.0 → 0.35.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "wrec",
   "description": "a library that greatly simplifies building web components",
   "author": "R. Mark Volkmann",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -29,6 +29,7 @@
     }
   },
   "bin": {
+    "wrec-declare": "./scripts/declare.js",
     "wrec-lint": "./scripts/lint.js",
     "wrec-scaffold": "./scripts/scaffold.js",
     "wrec-usedby": "./scripts/used-by.js"
@@ -36,6 +37,7 @@
   "files": [
     "dist",
     "scripts/ast-utils.js",
+    "scripts/declare.js",
     "scripts/lint.js",
     "scripts/scaffold.js",
     "scripts/template.ts",

package/scripts/declare.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+
+// This script inspects a given Wrec component source file and
+// generates TypeScript `declare` statements for the properties
+// found in the component's `static properties` declaration.
+//
+// To run this, enter `npx wrec-declare [--dry] {file-path}`
+//
+// Include the --dry flag to report whether changes are needed
+// without writing the modified source back to the file.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import ts from 'typescript';
+import {
+  collectWrecClasses,
+  getMemberName,
+  hasStaticModifier
+} from './ast-utils.js';
+
+const cwd = process.cwd();
+const DECLARE_TYPE_MAP = new Map([
+  ['Array', 'unknown[]'],
+  ['Boolean', 'boolean'],
+  ['Number', 'number'],
+  ['Object', 'object'],
+  ['String', 'string']
+]);
+
+// Analyzes a parsed source file and returns any proposed `declare` edits.
+function analyzeSourceFile(sourceFile) {
+  const edits = [];
+  const classNodes = collectWrecClasses(sourceFile);
+
+  for (const classNode of classNodes) {
+    const propertiesMember = getLastPropertiesDeclaration(classNode);
+    if (!propertiesMember) continue;
+
+    const declareLines = [];
+    for (const property of propertiesMember.initializer.properties) {
+      if (!ts.isPropertyAssignment(property)) continue;
+
+      const propName = getMemberName(property);
+      if (!propName || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(propName)) continue;
+
+      const declareType = getDeclareType(property.initializer);
+      if (!declareType) continue;
+      declareLines.push(createDeclareLine(propName, declareType));
+    }
+
+    const start = propertiesMember.end;
+    const end = findDeclareBlockEnd(classNode, propertiesMember, sourceFile);
+    const nextText = buildDeclareBlock(
+      sourceFile,
+      classNode,
+      propertiesMember,
+      declareLines
+    );
+    const currentText = sourceFile.text.slice(start, end);
+
+    if (nextText !== currentText) {
+      edits.push({end, start, text: nextText});
+    }
+  }
+
+  if (classNodes.length === 0) {
+    return {changed: false, foundWrecSubclass: false, text: sourceFile.text};
+  }
+
+  if (edits.length === 0) {
+    return {changed: false, foundWrecSubclass: true, text: sourceFile.text};
+  }
+
+  let nextSource = sourceFile.text;
+  edits.sort((a, b) => b.start - a.start);
+
+  for (const edit of edits) {
+    nextSource =
+      nextSource.slice(0, edit.start) + edit.text + nextSource.slice(edit.end);
+  }
+
+  return {changed: true, foundWrecSubclass: true, text: nextSource};
+}
+
+// Builds the `declare` block that should appear after `static properties`.
+function buildDeclareBlock(sourceFile, classNode, propertiesMember, declareLines) {
+  const {text} = sourceFile;
+  const memberIndent = getIndent(text, propertiesMember.getStart(sourceFile));
+  const startIndex = classNode.members.indexOf(propertiesMember) + 1;
+  let nextMember = null;
+
+  for (let index = startIndex; index < classNode.members.length; index += 1) {
+    const member = classNode.members[index];
+    if (isDeclarePropertyDeclaration(member)) continue;
+
+    nextMember = member;
+    break;
+  }
+
+  const nextIndent = nextMember
+    ? getIndent(text, nextMember.getStart(sourceFile))
+    : '';
+
+  if (declareLines.length === 0) {
+    return nextMember ? `\n\n${nextIndent}` : '\n';
+  }
+
+  const content = declareLines
+    .map(line => `${memberIndent}${line}`)
+    .join('\n');
+  return nextMember ? `\n${content}\n\n${nextIndent}` : `\n${content}\n`;
+}
+
+// Creates a single `declare` statement for a component property.
+function createDeclareLine(propName, declareType) {
+  return `declare ${propName}: ${declareType};`;
+}
+
+// Determines what changes, if any, should be made in a source file.
+export function evaluateSourceFile(filePath, options = {}) {
+  const {dry = false} = options;
+  const absFilePath = path.resolve(cwd, filePath);
+  validateFile(absFilePath);
+
+  const text = fs.readFileSync(absFilePath, 'utf8');
+  const result = evaluateSourceText(absFilePath, text);
+
+  if (!result.foundWrecSubclass) {
+    throw new Error('No class extending Wrec was found.');
+  }
+
+  if (!dry && result.changed) {
+    fs.writeFileSync(absFilePath, result.text);
+  }
+
+  return result;
+}
+
+// Determines what changes, if any, should be made in source file text.
+export function evaluateSourceText(filePath, text) {
+  const scriptKind = filePath.endsWith('.ts')
+    ? ts.ScriptKind.TS
+    : ts.ScriptKind.JS;
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+    scriptKind
+  );
+  return analyzeSourceFile(sourceFile);
+}
+
+// Finds the end of the contiguous `declare` block after `static properties`.
+function findDeclareBlockEnd(classNode, propertiesMember, sourceFile) {
+  const startIndex = classNode.members.indexOf(propertiesMember) + 1;
+
+  for (let index = startIndex; index < classNode.members.length; index += 1) {
+    const member = classNode.members[index];
+    if (isDeclarePropertyDeclaration(member)) continue;
+    return member.getStart(sourceFile);
+  }
+
+  return classNode.end - 1;
+}
+
+// Gets the TypeScript type string for a property configuration object.
+function getDeclareType(initializer) {
+  if (!ts.isObjectLiteralExpression(initializer)) return null;
+
+  for (const property of initializer.properties) {
+    if (
+      !ts.isPropertyAssignment(property) ||
+      getMemberName(property) !== 'type' ||
+      !ts.isIdentifier(property.initializer)
+    ) {
+      continue;
+    }
+
+    return DECLARE_TYPE_MAP.get(property.initializer.text) ?? null;
+  }
+
+  return null;
+}
+
+// Gets the leading indentation in the line that contains a given position.
+function getIndent(text, pos) {
+  const lineStart = text.lastIndexOf('\n', pos - 1) + 1;
+  const match = /^[ \t]*/.exec(text.slice(lineStart));
+  return match ? match[0] : '';
+}
+
+// Gets the last `static properties = { ... }` declaration in a class.
+function getLastPropertiesDeclaration(classNode) {
+  let propertiesMember = null;
+
+  for (const member of classNode.members) {
+    if (
+      ts.isPropertyDeclaration(member) &&
+      hasStaticModifier(member) &&
+      getMemberName(member) === 'properties' &&
+      member.initializer &&
+      ts.isObjectLiteralExpression(member.initializer)
+    ) {
+      propertiesMember = member;
+    }
+  }
+
+  return propertiesMember;
+}
+
+// Determines whether a class member is a `declare` property declaration.
+function isDeclarePropertyDeclaration(member) {
+  return (
+    ts.isPropertyDeclaration(member) &&
+    ts.canHaveModifiers(member) &&
+    ts
+      .getModifiers(member)
+      ?.some(mod => mod.kind === ts.SyntaxKind.DeclareKeyword) === true
+  );
+}
+
+// Handles CLI arguments and runs the script.
+function main() {
+  const args = process.argv.slice(2);
+  const unknownFlags = args.filter(
+    arg => arg.startsWith('--') && arg !== '--dry'
+  );
+  if (unknownFlags.length > 0) {
+    throw new Error(`unknown option: ${unknownFlags[0]}`);
+  }
+
+  const inputPaths = args.filter(arg => !arg.startsWith('--'));
+  if (inputPaths.length !== 1) {
+    throw new Error('Specify a single source file');
+  }
+
+  const dry = args.includes('--dry');
+  const result = evaluateSourceFile(inputPaths[0], {dry});
+
+  if (dry) {
+    if (result.changed) process.exit(1);
+    console.info('no changes needed');
+    return;
+  }
+
+  if (result.changed) {
+    console.info('updated source file');
+  } else {
+    console.info('no changes needed');
+  }
+}
+
+// Validates that a source file exists and has a supported extension.
+function validateFile(absFilePath) {
+  if (!fs.existsSync(absFilePath)) throw new Error('File not found');
+
+  const stat = fs.statSync(absFilePath);
+  if (!stat.isFile()) throw new Error('Not a file');
+
+  if (!/\.(js|ts)$/.test(absFilePath) || /\.d\.ts$/.test(absFilePath)) {
+    throw new Error('Unsupported file type');
+  }
+}
+
+// Runs the CLI when this module is executed directly.
+if (import.meta.main) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/scripts/lint.js

@@ -119,6 +119,13 @@ const THIS_CALL_RE = /this\.([A-Za-z_$][\w$]*)\s*\(/g;
 const THIS_REF_RE = /this\.([A-Za-z_$][\w$]*)(\.[A-Za-z_$][\w$]*)*/g;
 const PLACEHOLDER_PREFIX = '__WREC_PLACEHOLDER__';
 const RESERVED_PROPERTY_NAMES = new Set(['class', 'style']);
+const SUPPORTED_PROPERTY_TYPE_NAMES = new Set([
+  'Array',
+  'Boolean',
+  'Number',
+  'Object',
+  'String'
+]);
 const GETTER_PREFIX = 'get ';
 const SUPPORTED_EVENT_NAMES = new Set([
   'blur',
@@ -806,27 +813,28 @@ function formatReport(
 
   const hasIssues =
     findings.duplicateProperties.length > 0 ||
-    findings.reservedProperties.length > 0 ||
-    findings.invalidUsedByReferences.length > 0 ||
+    findings.extraArguments.length > 0 ||
+    findings.incompatibleArguments.length > 0 ||
     findings.invalidCheckedBindings.length > 0 ||
     findings.invalidComputedProperties.length > 0 ||
-    findings.invalidRefAttributes.length > 0 ||
-    findings.invalidValuesConfigurations.length > 0 ||
     findings.invalidDefaultValues.length > 0 ||
+    findings.invalidEventHandlers.length > 0 ||
     findings.invalidFormAssocValues.length > 0 ||
+    findings.invalidHtmlNesting.length > 0 ||
+    findings.invalidRefAttributes.length > 0 ||
+    findings.invalidTypeProperties.length > 0 ||
+    findings.invalidUsedByReferences.length > 0 ||
     findings.invalidUseStateMaps.length > 0 ||
+    findings.invalidValuesConfigurations.length > 0 ||
     findings.missingFormAssociatedProperty.length > 0 ||
     findings.missingTypeProperties.length > 0 ||
-    findings.undefinedProperties.length > 0 ||
+    findings.reservedProperties.length > 0 ||
+    findings.typeErrors.length > 0 ||
     findings.undefinedContextFunctions.length > 0 ||
     findings.undefinedMethods.length > 0 ||
-    findings.extraArguments.length > 0 ||
-    findings.incompatibleArguments.length > 0 ||
-    findings.invalidEventHandlers.length > 0 ||
-    findings.invalidHtmlNesting.length > 0 ||
-    findings.unsupportedHtmlAttributes.length > 0 ||
+    findings.undefinedProperties.length > 0 ||
     findings.unsupportedEventNames.length > 0 ||
-    findings.typeErrors.length > 0;
+    findings.unsupportedHtmlAttributes.length > 0;
 
   if (showFileHeader) lines.push(`file: ${fileLabel}`);
 
@@ -859,14 +867,31 @@ function formatReport(
     findings.duplicateProperties.forEach(name => lines.push(`  ${name}`));
   }
 
-  if (findings.reservedProperties.length > 0) {
-    lines.push('reserved property names:');
-    findings.reservedProperties.forEach(name => lines.push(`  ${name}`));
+  if (findings.extraArguments.length > 0) {
+    lines.push('extra arguments:');
+    findings.extraArguments.forEach(finding => {
+      lines.push(
+        `  ${finding.methodName}: argument ${finding.argumentIndex} ` +
+          `"${finding.argument}" exceeds the ` +
+          `${finding.parameterCount}-parameter signature`
+      );
+    });
   }
 
-  if (findings.invalidUsedByReferences.length > 0) {
-    lines.push('invalid usedBy references:');
-    findings.invalidUsedByReferences.forEach(message =>
+  if (findings.incompatibleArguments.length > 0) {
+    lines.push('incompatible arguments:');
+    findings.incompatibleArguments.forEach(finding => {
+      lines.push(
+        `  ${finding.methodName}: argument "${finding.argument}" ` +
+          `has type ${finding.argumentType}, but parameter ` +
+          `"${finding.parameterName}" expects ${finding.parameterType}`
+      );
+    });
+  }
+
+  if (findings.invalidCheckedBindings.length > 0) {
+    lines.push('invalid checked bindings:');
+    findings.invalidCheckedBindings.forEach(message =>
       lines.push(`  ${message}`)
     );
   }
@@ -878,13 +903,32 @@ function formatReport(
     );
   }
 
-  if (findings.invalidCheckedBindings.length > 0) {
-    lines.push('invalid checked bindings:');
-    findings.invalidCheckedBindings.forEach(message =>
+  if (findings.invalidDefaultValues.length > 0) {
+    lines.push('invalid default values:');
+    findings.invalidDefaultValues.forEach(message =>
       lines.push(`  ${message}`)
     );
   }
 
+  if (findings.invalidEventHandlers.length > 0) {
+    lines.push('invalid event handler references:');
+    findings.invalidEventHandlers.forEach(message =>
+      lines.push(`  ${message}`)
+    );
+  }
+
+  if (findings.invalidFormAssocValues.length > 0) {
+    lines.push('invalid form-assoc values:');
+    findings.invalidFormAssocValues.forEach(message =>
+      lines.push(`  ${message}`)
+    );
+  }
+
+  if (findings.invalidHtmlNesting.length > 0) {
+    lines.push('invalid html nesting:');
+    findings.invalidHtmlNesting.forEach(message => lines.push(`  ${message}`));
+  }
+
   if (findings.invalidRefAttributes.length > 0) {
     lines.push('invalid ref attributes:');
     findings.invalidRefAttributes.forEach(message =>
@@ -892,23 +936,28 @@ function formatReport(
     );
   }
 
-  if (findings.invalidValuesConfigurations.length > 0) {
-    lines.push('invalid values configurations:');
-    findings.invalidValuesConfigurations.forEach(message =>
+  if (findings.invalidTypeProperties.length > 0) {
+    lines.push('invalid type properties:');
+    findings.invalidTypeProperties.forEach(message =>
       lines.push(`  ${message}`)
     );
   }
 
-  if (findings.invalidDefaultValues.length > 0) {
-    lines.push('invalid default values:');
-    findings.invalidDefaultValues.forEach(message =>
+  if (findings.invalidUsedByReferences.length > 0) {
+    lines.push('invalid usedBy references:');
+    findings.invalidUsedByReferences.forEach(message =>
       lines.push(`  ${message}`)
     );
   }
 
-  if (findings.invalidFormAssocValues.length > 0) {
-    lines.push('invalid form-assoc values:');
-    findings.invalidFormAssocValues.forEach(message =>
+  if (findings.invalidUseStateMaps.length > 0) {
+    lines.push('invalid useState map entries:');
+    findings.invalidUseStateMaps.forEach(message => lines.push(`  ${message}`));
+  }
+
+  if (findings.invalidValuesConfigurations.length > 0) {
+    lines.push('invalid values configurations:');
+    findings.invalidValuesConfigurations.forEach(message =>
       lines.push(`  ${message}`)
     );
   }
@@ -927,9 +976,16 @@ function formatReport(
     );
   }
 
-  if (findings.undefinedProperties.length > 0) {
-    lines.push('undefined properties:');
-    findings.undefinedProperties.forEach(name => lines.push(`  ${name}`));
+  if (findings.reservedProperties.length > 0) {
+    lines.push('reserved property names:');
+    findings.reservedProperties.forEach(name => lines.push(`  ${name}`));
+  }
+
+  if (findings.typeErrors.length > 0) {
+    lines.push('type errors:');
+    findings.typeErrors.forEach(finding => {
+      lines.push(`  ${finding.expression}: ${finding.message}`);
+    });
   }
 
   if (findings.undefinedContextFunctions.length > 0) {
@@ -942,50 +998,16 @@ function formatReport(
     findings.undefinedMethods.forEach(name => lines.push(`  ${name}`));
   }
 
-  if (findings.invalidEventHandlers.length > 0) {
-    lines.push('invalid event handler references:');
-    findings.invalidEventHandlers.forEach(message =>
-      lines.push(`  ${message}`)
-    );
-  }
-
-  if (findings.invalidUseStateMaps.length > 0) {
-    lines.push('invalid useState map entries:');
-    findings.invalidUseStateMaps.forEach(message => lines.push(`  ${message}`));
-  }
-
-  if (findings.invalidHtmlNesting.length > 0) {
-    lines.push('invalid html nesting:');
-    findings.invalidHtmlNesting.forEach(message => lines.push(`  ${message}`));
-  }
-
-  if (findings.extraArguments.length > 0) {
-    lines.push('extra arguments:');
-    findings.extraArguments.forEach(finding => {
-      lines.push(
-        `  ${finding.methodName}: argument ${finding.argumentIndex} ` +
-          `"${finding.argument}" exceeds the ` +
-          `${finding.parameterCount}-parameter signature`
-      );
-    });
-  }
-
-  if (findings.incompatibleArguments.length > 0) {
-    lines.push('incompatible arguments:');
-    findings.incompatibleArguments.forEach(finding => {
-      lines.push(
-        `  ${finding.methodName}: argument "${finding.argument}" ` +
-          `has type ${finding.argumentType}, but parameter ` +
-          `"${finding.parameterName}" expects ${finding.parameterType}`
-      );
-    });
+  if (findings.undefinedProperties.length > 0) {
+    lines.push('undefined properties:');
+    findings.undefinedProperties.forEach(name => lines.push(`  ${name}`));
   }
 
-  if (findings.typeErrors.length > 0) {
-    lines.push('type errors:');
-    findings.typeErrors.forEach(finding => {
-      lines.push(`  ${finding.expression}: ${finding.message}`);
-    });
+  if (findings.unsupportedEventNames.length > 0) {
+    lines.push('unsupported event names:');
+    findings.unsupportedEventNames.forEach(message =>
+      lines.push(`  ${message}`)
+    );
   }
 
   if (findings.unsupportedHtmlAttributes.length > 0) {
@@ -995,13 +1017,6 @@ function formatReport(
     );
   }
 
-  if (findings.unsupportedEventNames.length > 0) {
-    lines.push('unsupported event names:');
-    findings.unsupportedEventNames.forEach(message =>
-      lines.push(`  ${message}`)
-    );
-  }
-
   if (!hasIssues && showNoIssuesMessage) lines.push('no issues found');
 
   return `${lines.join('\n')}\n`;
@@ -1360,8 +1375,9 @@ export function lintSource(filePath, sourceText, options = {}) {
     invalidFormAssocValues: [],
     invalidHtmlNesting: [],
     invalidRefAttributes: [],
-    invalidUseStateMaps: [],
+    invalidTypeProperties: [],
     invalidUsedByReferences: [],
+    invalidUseStateMaps: [],
     invalidValuesConfigurations: [],
     missingFormAssociatedProperty: [],
     missingTypeProperties: [],
@@ -1370,8 +1386,8 @@ export function lintSource(filePath, sourceText, options = {}) {
     undefinedContextFunctions: [],
     undefinedMethods: [],
     undefinedProperties: [],
-    unsupportedHtmlAttributes: [],
-    unsupportedEventNames: []
+    unsupportedEventNames: [],
+    unsupportedHtmlAttributes: []
   };
   const templateExprs = extractTemplateExpressions(
     classNode,
@@ -1464,8 +1480,9 @@ export function lintSource(filePath, sourceText, options = {}) {
   findings.invalidFormAssocValues.sort();
   findings.invalidHtmlNesting.sort();
   findings.invalidRefAttributes.sort();
-  findings.invalidUseStateMaps.sort();
+  findings.invalidTypeProperties.sort();
   findings.invalidUsedByReferences.sort();
+  findings.invalidUseStateMaps.sort();
   findings.invalidValuesConfigurations.sort();
   findings.missingFormAssociatedProperty.sort();
   findings.missingTypeProperties.sort();
@@ -1474,8 +1491,8 @@ export function lintSource(filePath, sourceText, options = {}) {
   findings.undefinedContextFunctions.sort();
   findings.undefinedMethods.sort();
   findings.undefinedProperties.sort();
-  findings.unsupportedHtmlAttributes.sort();
   findings.unsupportedEventNames.sort();
+  findings.unsupportedHtmlAttributes.sort();
 
   return formatReport(
     filePath,
@@ -1870,6 +1887,13 @@ function validatePropertyConfigs(
       findings.missingTypeProperties.push(
         `property "${propName}" does not specify a type`
       );
+    } else if (
+      !SUPPORTED_PROPERTY_TYPE_NAMES.has(typeExpressionKind(typeExpression))
+    ) {
+      findings.invalidTypeProperties.push(
+        `property "${propName}" type must be one of ` +
+          'Boolean, Number, String, Object, or Array'
+      );
     }
 
     if (usedByProp && ts.isPropertyAssignment(usedByProp)) {