feat(ts-plugin): type-check <webjs-tag attr=\${expr}> interpolations

Extend the plugin with a fourth resolver: for every \${expr}
interpolation in attribute-value position of a reachable webjs tag,
look up the matching `declare attr: T` field on the component class
and assignability-check the expression's type against T using the
TypeScript type checker.

This works for custom types end-to-end — interfaces (`Student`),
type aliases, string-literal unions ('login' | 'signup'), generics,
and anything else `checker.isTypeAssignableTo` understands. Static
attribute values like `mode=123` are deliberately NOT checked: at
runtime they're plain template text (the string "123"), so flagging
them would be a false positive. Only \${expr} carries a real value
type worth checking.

Behaviour matrix:

  - Reachable tag, prop has `declare attr: T`, expr type fits T
    → silent.
  - Reachable tag, prop has `declare attr: T`, expr type doesn't fit
    → diagnostic: "Type 'X' is not assignable to attribute 'Y' of
    type 'Z' on <foo-bar>." Code 9001, source 'webjskit-ts-plugin'.
  - Reachable tag but prop has no `declare` (i.e. type is unknown)
    → skip; no noise. The convention check covers this separately.
  - Unreachable tag → skip; ts-lit-plugin's "unknown tag" warning
    surfaces the missing import on its own.

Bump @webjskit/ts-plugin → 0.3.0 (new feature). 6 new tests cover
number-vs-string mismatch, assignable string, string-literal-union
mismatch, static-text not flagged, no-declare skip, unreachable skip.

Author: vivek7405

packages/ts-plugin/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@webjskit/ts-plugin",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "commonjs",
-  "description": "TypeScript language-service plugin for webjs — go-to-definition + ts-lit-plugin diagnostic suppression + attribute auto-complete for custom elements registered via Class.register('tag').",
+  "description": "TypeScript language-service plugin for webjs — go-to-definition + ts-lit-plugin diagnostic suppression + attribute auto-complete + attribute-value type-check (against `declare propName: T`) for custom elements registered via Class.register('tag').",
   "main": "src/index.js",
   "peerDependencies": {
     "typescript": ">=5.0.0"

packages/ts-plugin/src/index.js

@@ -69,8 +69,11 @@ function init(modules) {
     // diagnostic must stay.
     proxy.getSemanticDiagnostics = (fileName) => {
       const diags = inner.getSemanticDiagnostics(fileName);
-      try { return filterLitTagDiagnostics(info, fileName, diags); }
-      catch (e) {
+      try {
+        const filtered = filterLitTagDiagnostics(info, fileName, diags);
+        const attrDiags = webjsAttrValueDiagnostics(info, fileName);
+        return attrDiags.length ? [...filtered, ...attrDiags] : filtered;
+      } catch (e) {
         info.project.projectService.logger?.info?.(
           `@webjskit/ts-plugin: getSemanticDiagnostics threw: ${String(e)}`,
         );
@@ -817,6 +820,195 @@ function init(modules) {
 
     return { tag: tagArg.text, className: classArg.text };
   }
+
+  /* ================================================================
+   * Resolver 4: type-check `<webjs-tag attr=${expr}>` interpolations
+   * against the property's declared TypeScript type.
+   * ================================================================ */
+
+  /**
+   * Walk every html`` template in the file. For each `${expr}` that
+   * sits in attribute-value position of a reachable webjs tag, look up
+   * the matching `declare attr: T` field on the component class and
+   * assignability-check `typeof expr` against `T`. Emit a diagnostic
+   * for any mismatch.
+   *
+   * Static (non-interpolated) attribute values like `mode="login"` are
+   * not checked — they're plain template text and at runtime always
+   * coerce to strings. Only interpolations carry a real value type
+   * worth checking.
+   *
+   * @param {import('typescript/lib/tsserverlibrary').server.PluginCreateInfo} info
+   * @param {string} fileName
+   * @returns {import('typescript').Diagnostic[]}
+   */
+  function webjsAttrValueDiagnostics(info, fileName) {
+    /** @type {import('typescript').Diagnostic[]} */
+    const out = [];
+    const program = info.languageService.getProgram();
+    if (!program) return out;
+    const sf = program.getSourceFile(fileName);
+    if (!sf) return out;
+
+    const registry = buildRegistry(program);
+    if (registry.components.size === 0) return out;
+    const reachable = collectReachableTags(program, sf, registry);
+    if (reachable.size === 0) return out;
+
+    const checker = program.getTypeChecker();
+
+    /** @param {import('typescript').Node} node */
+    function visit(node) {
+      if (ts.isTaggedTemplateExpression(node) && tagMatches(node.tag, 'html')) {
+        collectFromTemplate(node);
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    /** @param {import('typescript').TaggedTemplateExpression} expr */
+    function collectFromTemplate(expr) {
+      const tpl = expr.template;
+      if (ts.isNoSubstitutionTemplateLiteral(tpl)) return;
+      // tpl is a TemplateExpression: head + spans[].
+      const segments = [tpl.head, ...tpl.templateSpans.map((s) => s.literal)];
+      // segments[i].text is the cooked text *between* the (i-1)th hole and
+      // the ith hole (segments[0] is the head, before the first hole).
+      // Walk text segment-by-segment, tracking which interpolation each
+      // hole belongs to.
+      // Stitch the cooked text together with placeholders to track tags.
+      // Simpler: just inspect the trailing text of each segment that
+      // precedes a span — does it look like `<webjs-tag … attr=`?
+      for (let i = 0; i < tpl.templateSpans.length; i++) {
+        // Text immediately preceding the i-th interpolation.
+        const preceding = i === 0 ? tpl.head.text : tpl.templateSpans[i - 1].literal.text;
+        // Build the *full* preceding text for this interpolation (head +
+        // all earlier segments). We need this so an opening `<` from a
+        // previous segment is still visible. Use the cumulative slice
+        // ending at segment `i`.
+        const cumulative = i === 0
+          ? preceding
+          : segments.slice(0, i + 1).map((s) => s.text).join('•'); // any non-tag char as placeholder
+        const ctx = findAttrContext(cumulative);
+        if (!ctx) continue;
+        if (!reachable.has(ctx.tag)) continue;
+        const ref = registry.components.get(ctx.tag);
+        if (!ref) continue;
+        // Skip if the attr name doesn't match a known prop.
+        if (!ref.attributes.includes(ctx.attr)) continue;
+
+        const propType = resolvePropType(program, ref, ctx.attr, checker);
+        if (!propType) continue; // no `declare` annotation → can't check
+
+        const span = tpl.templateSpans[i];
+        const exprNode = span.expression;
+        const exprType = checker.getTypeAtLocation(exprNode);
+
+        if (checker.isTypeAssignableTo(exprType, propType)) continue;
+
+        out.push({
+          file: sf,
+          start: exprNode.getStart(sf),
+          length: exprNode.getEnd() - exprNode.getStart(sf),
+          messageText:
+            `Type '${checker.typeToString(exprType)}' is not assignable to ` +
+            `attribute '${ctx.attr}' of type '${checker.typeToString(propType)}' on <${ctx.tag}>.`,
+          category: ts.DiagnosticCategory.Error,
+          code: 9001,
+          source: 'webjskit-ts-plugin',
+        });
+      }
+    }
+
+    visit(sf);
+    return out;
+  }
+
+  /**
+   * Inspect the tail of `text` (cumulative html`` segments preceding an
+   * interpolation) and return the enclosing tag + attribute name if the
+   * interpolation sits in attribute-value position of an open tag.
+   *
+   * @param {string} text
+   * @returns {{ tag: string, attr: string } | undefined}
+   */
+  function findAttrContext(text) {
+    // Find the last unclosed `<`. We want the opener whose `>` hasn't
+    // appeared yet.
+    let depth = 0;
+    let openIdx = -1;
+    for (let i = 0; i < text.length; i++) {
+      if (text[i] === '<') { openIdx = i; depth = 1; }
+      else if (text[i] === '>' && depth === 1) { depth = 0; openIdx = -1; }
+    }
+    if (openIdx === -1) return undefined;
+    const tagPart = text.slice(openIdx + 1);
+    // First token after `<` is the tag name.
+    const tm = /^([a-zA-Z][\w-]*)/.exec(tagPart);
+    if (!tm) return undefined;
+    const tag = tm[1].toLowerCase();
+    if (!tag.includes('-')) return undefined;
+    // Trailing pattern: ` attrName=` optionally followed by an open quote.
+    const am = /\s+([A-Za-z_][\w-]*)\s*=\s*['"`]?$/.exec(tagPart);
+    if (!am) return undefined;
+    return { tag, attr: am[1] };
+  }
+
+  /**
+   * Resolve the declared type of `attr` on the given component class.
+   * Looks for a class member with that name and a TypeNode annotation
+   * (typically a `declare attr: T` field). Returns undefined if no
+   * annotation is present — the user hasn't told us the type, so we
+   * can't check it.
+   *
+   * @param {import('typescript').Program} program
+   * @param {ComponentRef} ref
+   * @param {string} attrName
+   * @param {import('typescript').TypeChecker} checker
+   * @returns {import('typescript').Type | undefined}
+   */
+  function resolvePropType(program, ref, attrName, checker) {
+    const compSf = program.getSourceFile(ref.fileName);
+    if (!compSf) return undefined;
+    const cls = findClassDeclaration(compSf, ref.className);
+    if (!cls) return undefined;
+    for (const member of cls.members) {
+      if (!ts.isPropertyDeclaration(member)) continue;
+      if (!member.name) continue;
+      let memberName;
+      if (ts.isIdentifier(member.name) || ts.isPrivateIdentifier(member.name)) {
+        memberName = member.name.text;
+      } else if (ts.isStringLiteralLike(member.name)) {
+        memberName = member.name.text;
+      }
+      if (memberName !== attrName) continue;
+      if (!member.type) return undefined;
+      return checker.getTypeFromTypeNode(member.type);
+    }
+    return undefined;
+  }
+
+  /**
+   * Locate `class <name> { … }` inside a source file. Returns the
+   * ClassDeclaration node, or undefined if not found.
+   *
+   * @param {import('typescript').SourceFile} sf
+   * @param {string} className
+   * @returns {import('typescript').ClassDeclaration | undefined}
+   */
+  function findClassDeclaration(sf, className) {
+    /** @type {import('typescript').ClassDeclaration | undefined} */
+    let found;
+    function walk(node) {
+      if (found) return;
+      if (ts.isClassDeclaration(node) && node.name && node.name.text === className) {
+        found = /** @type any */ (node);
+        return;
+      }
+      ts.forEachChild(node, walk);
+    }
+    walk(sf);
+    return found;
+  }
 }
 
 module.exports = init;

test/ts-plugin.test.js

@@ -498,6 +498,152 @@ test('completes static-properties keys after typing `<webjs-tag `', () => {
   assert.ok(names.includes('then'), `expected "then" in ${JSON.stringify(names)}`);
 });
 
+/* ================================================================
+ * Attribute-value type-check on `<webjs-tag attr=${expr}>` interpolations
+ * ================================================================ */
+
+test('flags number passed where string is declared', () => {
+  const svc = makeService({
+    '/auth.ts':
+      `import { WebComponent } from '@webjskit/core';\n` +
+      `export class AuthForms extends WebComponent {\n` +
+      `  static properties = { mode: { type: String } };\n` +
+      `  declare mode: string;\n` +
+      `}\n` +
+      `AuthForms.register('auth-forms');\n`,
+    '/page.ts':
+      `import { html } from '@webjskit/core';\n` +
+      `import './auth.ts';\n` +
+      `const x: number = 42;\n` +
+      `export default function P() {\n` +
+      `  return html\`<auth-forms mode=\${x}></auth-forms>\`;\n` +
+      `}\n`,
+  });
+  const diags = svc.getSemanticDiagnostics('/page.ts');
+  const ours = diags.filter((d) => d.source === 'webjskit-ts-plugin');
+  assert.equal(ours.length, 1, `expected one webjs diagnostic, got ${ours.length}`);
+  const m = ours[0].messageText;
+  assert.ok(/'number'/.test(m) && /'mode'/.test(m) && /'string'/.test(m),
+    `unexpected message: ${m}`);
+});
+
+test('passes when interpolated value is assignable to declared string type', () => {
+  const svc = makeService({
+    '/auth.ts':
+      `import { WebComponent } from '@webjskit/core';\n` +
+      `export class AuthForms extends WebComponent {\n` +
+      `  static properties = { mode: { type: String } };\n` +
+      `  declare mode: string;\n` +
+      `}\n` +
+      `AuthForms.register('auth-forms');\n`,
+    '/page.ts':
+      `import { html } from '@webjskit/core';\n` +
+      `import './auth.ts';\n` +
+      `const m: string = 'login';\n` +
+      `export default function P() {\n` +
+      `  return html\`<auth-forms mode=\${m}></auth-forms>\`;\n` +
+      `}\n`,
+  });
+  const diags = svc.getSemanticDiagnostics('/page.ts');
+  const ours = diags.filter((d) => d.source === 'webjskit-ts-plugin');
+  assert.equal(ours.length, 0, `unexpected diagnostics: ${ours.map((d) => d.messageText).join('; ')}`);
+});
+
+test('flags string-or-number against a string-literal-union type', () => {
+  const svc = makeService({
+    '/auth.ts':
+      `import { WebComponent } from '@webjskit/core';\n` +
+      `type Mode = 'login' | 'signup';\n` +
+      `export class AuthForms extends WebComponent {\n` +
+      `  static properties = { mode: { type: String } };\n` +
+      `  declare mode: Mode;\n` +
+      `}\n` +
+      `AuthForms.register('auth-forms');\n`,
+    '/page.ts':
+      `import { html } from '@webjskit/core';\n` +
+      `import './auth.ts';\n` +
+      `declare const x: string | number;\n` +
+      `export default function P() {\n` +
+      `  return html\`<auth-forms mode=\${x}></auth-forms>\`;\n` +
+      `}\n`,
+  });
+  const diags = svc.getSemanticDiagnostics('/page.ts');
+  const ours = diags.filter((d) => d.source === 'webjskit-ts-plugin');
+  assert.equal(ours.length, 1, `expected one diagnostic for string|number against Mode`);
+});
+
+test('does not type-check static (non-interpolated) attribute values', () => {
+  // <auth-forms mode=123> is plain template text — at runtime it's just
+  // the string "123", not a number. We deliberately don't flag it.
+  const svc = makeService({
+    '/auth.ts':
+      `import { WebComponent } from '@webjskit/core';\n` +
+      `export class AuthForms extends WebComponent {\n` +
+      `  static properties = { mode: { type: String } };\n` +
+      `  declare mode: string;\n` +
+      `}\n` +
+      `AuthForms.register('auth-forms');\n`,
+    '/page.ts':
+      `import { html } from '@webjskit/core';\n` +
+      `import './auth.ts';\n` +
+      `export default function P() {\n` +
+      `  return html\`<auth-forms mode=123></auth-forms>\`;\n` +
+      `}\n`,
+  });
+  const diags = svc.getSemanticDiagnostics('/page.ts');
+  const ours = diags.filter((d) => d.source === 'webjskit-ts-plugin');
+  assert.equal(ours.length, 0, 'static attribute value should not produce a webjs diagnostic');
+});
+
+test('skips check when component is reachable but the prop has no `declare` annotation', () => {
+  // If the user hasn't typed the prop, we can't check — fall back to
+  // silence rather than noise.
+  const svc = makeService({
+    '/auth.ts':
+      `import { WebComponent } from '@webjskit/core';\n` +
+      `export class AuthForms extends WebComponent {\n` +
+      `  static properties = { mode: { type: String } };\n` +
+      `}\n` + // no `declare mode: …`
+      `AuthForms.register('auth-forms');\n`,
+    '/page.ts':
+      `import { html } from '@webjskit/core';\n` +
+      `import './auth.ts';\n` +
+      `declare const x: number;\n` +
+      `export default function P() {\n` +
+      `  return html\`<auth-forms mode=\${x}></auth-forms>\`;\n` +
+      `}\n`,
+  });
+  const diags = svc.getSemanticDiagnostics('/page.ts');
+  const ours = diags.filter((d) => d.source === 'webjskit-ts-plugin');
+  assert.equal(ours.length, 0, 'no declare → no check, no diagnostic');
+});
+
+test('does not check tags that are not reachable through imports', () => {
+  // The component class exists in the program but page.ts forgets to
+  // import it. Reachability gating means we don't synthesise a value
+  // diagnostic — the missing import is already surfaced via the kept
+  // "unknown tag" warning from ts-lit-plugin.
+  const svc = makeService({
+    '/auth.ts':
+      `import { WebComponent } from '@webjskit/core';\n` +
+      `export class AuthForms extends WebComponent {\n` +
+      `  static properties = { mode: { type: String } };\n` +
+      `  declare mode: string;\n` +
+      `}\n` +
+      `AuthForms.register('auth-forms');\n`,
+    '/page.ts':
+      // No import './auth.ts'.
+      `import { html } from '@webjskit/core';\n` +
+      `declare const x: number;\n` +
+      `export default function P() {\n` +
+      `  return html\`<auth-forms mode=\${x}></auth-forms>\`;\n` +
+      `}\n`,
+  });
+  const diags = svc.getSemanticDiagnostics('/page.ts');
+  const ours = diags.filter((d) => d.source === 'webjskit-ts-plugin');
+  assert.equal(ours.length, 0, 'unreachable tag → no value-check (lit-plugin keeps its own "unknown tag" warning)');
+});
+
 test('attribute completions are NOT offered when the component is not imported', () => {
   const svc = makeService({
     '/auth.ts':