@design.estate/wcctools 6.0.0 → 6.1.0

package/ts/standards/rules/shared.ts

@@ -0,0 +1,127 @@
+import * as plugins from '../../plugins.js';
+import * as ast from '../helpers.ast.js';
+import { baseOf, dirOf, specifierFor } from '../helpers.paths.js';
+import type { IStandardElement, IStandardProperty, StandardProject } from '../classes.standardproject.js';
+import type { IFixBuilder } from '../rule.js';
+
+const ts = plugins.typescript;
+
+export const elementsDir = 'ts_web/elements';
+
+/** `ts_web/elements/00group-<area>` or `ts_web/elements` itself. */
+export const isElementParentDir = (dirArg: string): boolean =>
+  dirArg === elementsDir || /^ts_web\/elements\/00group-[^/]+$/.test(dirArg);
+
+/** Names the HTML specification reserves; `customElements.define` rejects them. */
+const reservedElementNames = ['annotation-xml', 'color-profile', 'font-face', 'font-face-src', 'font-face-uri', 'font-face-format', 'font-face-name', 'missing-glyph'];
+
+/**
+ * A valid custom element name in the ASCII subset the standard allows: a lowercase letter first,
+ * then lowercase letters, digits, `-`, `.` and `_`, at least one `-`, and not a reserved name. Such
+ * a tag is also a safe file and folder name, so only these tags feed fixes that derive paths or code.
+ */
+export const isCustomElementName = (tagArg: string): boolean =>
+  /^[a-z][a-z0-9._-]*$/.test(tagArg) && tagArg.includes('-') && !reservedElementNames.includes(tagArg);
+
+/** True when an element's entry file sits in its own element folder `…/<tag>/`. */
+export const isInElementFolder = (elementArg: IStandardElement): boolean => {
+  const folder = dirOf(elementArg.file);
+  return !!elementArg.tag && baseOf(folder) === elementArg.tag && isElementParentDir(dirOf(folder));
+};
+
+/** The `<area>` of `ts_web/elements/00group-<area>/…`, or null. */
+export const groupAreaOf = (fileArg: string): string | null => /^ts_web\/elements\/00group-([^/]+)\//.exec(fileArg)?.[1] ?? null;
+
+/** Elements outside demo files: the catalog's own elements. */
+export const catalogElements = (projectArg: StandardProject): IStandardElement[] =>
+  projectArg.elements.filter((elementArg) => !elementArg.inDemoFile);
+
+/** Public `@property` members outside demo files. */
+export const publicProperties = (projectArg: StandardProject): IStandardProperty[] =>
+  projectArg.properties.filter((propertyArg) => propertyArg.decorator === 'property' && propertyArg.isPublic && !propertyArg.inDemoFile);
+
+export const elementKey = (elementArg: IStandardElement): string => `${elementArg.file}#${elementArg.className ?? elementArg.tag ?? '?'}`;
+
+export const propertyKey = (propertyArg: IStandardProperty): string => `${propertyArg.file}#${propertyArg.name}`;
+
+/** The type annotation of a property member without `undefined` and `null` union members. */
+export const coreTypeOf = (propertyArg: IStandardProperty): ast.TTypeNode | null => {
+  const member = propertyArg.member;
+  const typeNode = ts.isPropertyDeclaration(member) ? member.type : undefined;
+  if (!typeNode) {
+    return null;
+  }
+  if (ts.isUnionTypeNode(typeNode)) {
+    const members = typeNode.types.filter((typeArg) =>
+      typeArg.kind !== ts.SyntaxKind.UndefinedKeyword
+      && !(ts.isLiteralTypeNode(typeArg) && typeArg.literal.kind === ts.SyntaxKind.NullKeyword));
+    if (members.length === 1) {
+      return members[0];
+    }
+    return typeNode;
+  }
+  return typeNode;
+};
+
+export const isArrayTypeNode = (typeArg: ast.TTypeNode): boolean => {
+  if (ts.isArrayTypeNode(typeArg)) {
+    return true;
+  }
+  if (ts.isTypeOperatorNode(typeArg) && typeArg.operator === ts.SyntaxKind.ReadonlyKeyword) {
+    return ts.isArrayTypeNode(typeArg.type);
+  }
+  return ts.isTypeReferenceNode(typeArg) && ts.isIdentifier(typeArg.typeName) && ['Array', 'ReadonlyArray'].includes(typeArg.typeName.text);
+};
+
+/** The position at the start of the line after the last `export … from` statement, or at the end of the file. */
+export const exportInsertionPoint = (sourceFileArg: ast.TSourceFile): { position: number; prefix: string } => {
+  let lastEnd = -1;
+  for (const statement of sourceFileArg.statements) {
+    if (ts.isExportDeclaration(statement)) {
+      lastEnd = statement.end;
+    }
+  }
+  const text = sourceFileArg.text;
+  if (lastEnd === -1) {
+    return { position: text.length, prefix: text.length > 0 && !text.endsWith('\n') ? '\n' : '' };
+  }
+  const newline = text.indexOf('\n', lastEnd);
+  return newline === -1 ? { position: text.length, prefix: '\n' } : { position: newline + 1, prefix: '' };
+};
+
+/** Adds `export * from '<target>';` to a barrel. */
+export const addReexport = (builderArg: IFixBuilder, projectArg: StandardProject, barrelArg: string, targetArg: string): void => {
+  const point = exportInsertionPoint(projectArg.sourceFile(barrelArg));
+  builderArg.edit(barrelArg, point.position, point.position, `${point.prefix}export * from '${specifierFor(barrelArg, targetArg, 'js')}';\n`);
+};
+
+/** Removes a whole statement including its line break; from the line start when only indentation precedes it. */
+export const removeStatement = (builderArg: IFixBuilder, fileArg: string, statementArg: ast.TNode): void => {
+  const text = statementArg.getSourceFile().text;
+  let start = statementArg.getStart();
+  const lineStart = text.lastIndexOf('\n', start - 1) + 1;
+  if (/^[ \t]*$/.test(text.slice(lineStart, start))) {
+    start = lineStart;
+  }
+  let end = statementArg.end;
+  const rest = /^[ \t]*\r?\n/.exec(text.slice(end));
+  if (rest) {
+    end += rest[0].length;
+  }
+  builderArg.edit(fileArg, start, end, '');
+};
+
+/** The identifier a `static demo` value refers to at its root, e.g. `demoFunc` or `demos` in `demos.main`. */
+export const rootIdentifier = (expressionArg: ast.TExpression): string | null => {
+  let current: ast.TExpression = expressionArg;
+  while (ts.isPropertyAccessExpression(current)) {
+    current = current.expression;
+  }
+  return ts.isIdentifier(current) ? current.text : null;
+};
+
+/** The start of the line following the line a position is on. */
+export const nextLineStart = (textArg: string, positionArg: number): number => {
+  const newline = textArg.indexOf('\n', positionArg);
+  return newline === -1 ? textArg.length : newline + 1;
+};

package/ts/standards/rules/style.bdtheme.ts

@@ -0,0 +1,31 @@
+import * as plugins from '../../plugins.js';
+import * as ast from '../helpers.ast.js';
+import type { IRuleFinding, IStandardRule } from '../rule.js';
+
+const ts = plugins.typescript;
+
+/** The one module that may call `bdTheme()`: the token bridge. */
+export const bdThemeBridge = 'ts_web/elements/00theme.ts';
+
+/** dees: no new `cssManager.bdTheme()` call outside `ts_web/elements/00theme.ts`. A ratchet: baselines only. */
+export const styleBdThemeRule: IStandardRule = {
+  id: 'style/bdtheme',
+  severity: { dees: 'error' },
+  fixMode: 'none',
+  detect: ({ project }) => {
+    const findings: IRuleFinding[] = [];
+    for (const file of project.webFiles) {
+      if (file === bdThemeBridge) {
+        continue;
+      }
+      const visit = (nodeArg: ast.TNode): void => {
+        if (ts.isCallExpression(nodeArg) && ast.calleeName(nodeArg.expression) === 'bdTheme') {
+          findings.push({ file, position: nodeArg.getStart(), key: file, message: 'bdTheme() call; use --dees-* tokens' });
+        }
+        ts.forEachChild(nodeArg, visit);
+      };
+      visit(project.sourceFile(file));
+    }
+    return findings;
+  },
+};

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/wcctools',
-  version: '6.0.0',
+  version: '6.1.0',
   description: 'A set of web component tools for creating element catalogues, enabling the structured development and documentation of custom elements and pages.'
 }