volaro 0.0.2 → 0.1.0-alpha.3

package/compiler/validator/vlcheck/test_ids.py

@@ -0,0 +1,98 @@
+"""Automation-hook source checks and bounded composed literal-ID analysis."""
+import json
+import re
+from dataclasses import fields, is_dataclass
+from . import ast_nodes as A
+from .diagnostics import Diagnostic, Severity
+
+TARGETS = set('col row stack grid card text img button input link spacer h1 h2 h3 h4 h5 h6 main nav status'.split())
+SEGMENT = re.compile(r'[a-z][a-z0-9-]{0,79}\Z')
+
+
+def literal(expr):
+    if isinstance(expr, A.Literal) and expr.kind == 'str' and not getattr(expr, 'interp_names', None):
+        try:
+            return json.loads(expr.raw)
+        except ValueError:
+            return None
+    return None
+
+
+def walk(node):
+    if isinstance(node, (list, tuple)):
+        for child in node:
+            yield from walk(child)
+    elif is_dataclass(node):
+        yield node
+        for f in fields(node):
+            yield from walk(getattr(node, f.name))
+
+
+def check_test_ids(module, filename):
+    errors = []
+    def error(code, node, message, fix='Use a literal test_id:"save" and an explicit public test_scope: for repetition.'):
+        errors.append(Diagnostic(code, Severity.ERROR, message, node.start, node.end, fix, filename))
+    views = {x.name: x for x in module.items if isinstance(x, A.ViewDecl)}
+    for node in walk(module):
+        if not isinstance(node, A.Element):
+            continue
+        for key in ('test_id', 'test_scope'):
+            vals = [v for k, v in node.attrs if k == key]
+            if len(vals) > 1:
+                error('E-TEST-ID', node, 'automation attribute repeated')
+            for value in vals:
+                if key == 'test_id':
+                    text = literal(value)
+                    if node.name not in TARGETS or not isinstance(text, str) or not SEGMENT.fullmatch(text):
+                        error('E-TEST-ID', node,
+                              'test_id must be a literal slug matching [a-z][a-z0-9-]{0,79} '
+                              '(lowercase letters, digits, hyphens; no underscore) on a '
+                              'supported element',
+                              fix='test_id:"edit-field"  (hyphens, not underscores)')
+                else:
+                    if node.name not in TARGETS | {'dialog', 'tabs'} | views.keys():
+                        error('E-TEST-ID-SCOPE', node, 'test_scope is unsupported on this target')
+                    if isinstance(value, A.Literal) and not getattr(value, 'interp_names', None) and (not isinstance(literal(value), str) or not SEGMENT.fullmatch(literal(value) or '')):
+                        error('E-TEST-ID-SCOPE', node, 'literal test_scope must be a lowercase slug (1–80 characters)')
+
+    def combine(parts, alternative=False):
+        out = {}
+        for part in parts:
+            for key, (count, node) in part.items():
+                previous = out.get(key, (0, node))[0]
+                out[key] = ((max(previous, count) if alternative else previous + count), node)
+        return out
+
+    def visit(nodes, scope=(), repeated=False, stack=()):
+        parts = []
+        for n in nodes:
+            if isinstance(n, A.Element):
+                attrs = dict(n.attrs)
+                current = scope
+                if 'test_scope' in attrs:
+                    s = literal(attrs['test_scope'])
+                    current = None if scope is None or s is None else (*scope, s)
+                local = literal(attrs.get('test_id'))
+                own = {}
+                if isinstance(local, str) and current is not None:
+                    own[(*current, local)] = (2 if repeated else 1, n)
+                children = visit(n.body, current, repeated, stack)
+                if n.name in views and n.name not in stack:
+                    children = combine([children, visit(views[n.name].body, current, repeated, (*stack, n.name))])
+                parts.append(combine([own, children]))
+            elif isinstance(n, A.If):
+                parts.append(combine([visit(n.then, scope, repeated, stack),
+                    *(visit(body, scope, repeated, stack) for _, body in n.elifs),
+                    visit(n.orelse, scope, repeated, stack)], True))
+            elif isinstance(n, A.ListBlock):
+                parts.append(visit(n.body, scope, True, stack))
+        return combine(parts)
+    # Check every view as an entry as well as its expansion from other views.
+    # Dynamic scope relationships remain a runtime check, never inferred safe.
+    seen = set()
+    for name, view in views.items():
+        for key, (count, node) in visit(view.body, stack=(name,)).items():
+            if count > 1 and (node.start, key) not in seen:
+                seen.add((node.start, key))
+                error('E-TEST-ID-DUP', node, 'automation ID can occur more than once in a composed view; add distinct scopes')
+    return errors

package/compiler/vlbuild/styling/README.md

@@ -0,0 +1,39 @@
+# Tailwind build-tool foundation
+
+The internal adapter is integrated with `vlbuild` theme/recipe/class lowering.
+The present capability boundaries live in the repository's `ROADMAP.md`.
+This private build package is not an npm-distribution or publication change.
+
+Install reproducibly from the repository root:
+
+```sh
+npm ci --ignore-scripts --no-audit --no-fund --prefix prototype/vlbuild/styling
+./verify.sh
+```
+
+The private package pins upstream Tailwind and its CLI, plus PostCSS and its
+selector parser for output verification. The lockfile records transitive
+dependencies. No global install, CDN, browser compiler or server-runtime
+dependency is involved. Unstyled `vlbuild` builds remain dependency-free;
+the required compiler test gate now also tests this local toolchain.
+
+`build-css.mjs` accepts JSON on stdin with `candidates` (each has `class` and
+`origin`) and optional compiler-generated `themeCss`. It returns JSON containing
+verified CSS and sorted unique candidates. `vlbuild.styling.compile_css` is the
+Python bridge. Neither writes application output files.
+
+Only the explicit temporary candidate file is scanned. Automatic discovery is
+disabled and Preflight is omitted. Unknown candidates are errors even if
+Tailwind succeeds. CSS selectors are parsed, not searched as raw strings;
+responsive, state and arbitrary-value escapes are covered. Only `group`, `peer`
+and their simple named markers are exempt from standalone-rule verification.
+Presence of a rule does not prove its visual effectiveness or accessibility.
+
+`build_file` invokes this bridge before writing a styled bundle. Runtime
+compatibility CSS occupies `vl-legacy`, before generated utility styles;
+recipe/inline-style conflicts are checked during lowering. See `style_config.py`
+for bounded sibling discovery and recipe resolution. Unstyled builds retain
+their legacy colour variables and do not require an `app.css` file.
+
+Upstream integration: [Tailwind CLI](https://tailwindcss.com/docs/installation/tailwind-cli)
+and [explicit source detection](https://tailwindcss.com/docs/detecting-classes-in-source-files).

package/compiler/vlbuild/styling/build-css.mjs

@@ -0,0 +1,103 @@
+/** Build-only adapter. Explicit candidates in; verified CSS out.
+ * No repository scanning, shell execution, network fallback, or runtime CSS.
+ * This is the toolchain foundation, not yet a public vlbuild styling flag.
+ */
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import postcss from 'postcss';
+import selectorParser from 'postcss-selector-parser';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cli = join(here, 'node_modules/@tailwindcss/cli/dist/index.mjs');
+const theme = join(here, 'node_modules/tailwindcss/theme.css');
+const utilities = join(here, 'node_modules/tailwindcss/utilities.css');
+
+export class StylingError extends Error {
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.code = code;
+  }
+}
+
+// Markers do not emit their own rules. Keep the exemption narrow: a typo
+// beginning with "group" is not a marker. Variant utilities are NOT exempt.
+export function isStructuralMarker(candidate) {
+  return /^(group|peer)(\/[A-Za-z0-9_-]+)?$/.test(candidate);
+}
+
+export function verifyCandidates(css, candidates) {
+  const emitted = new Set();
+  let ast;
+  try {
+    ast = postcss.parse(css);
+    ast.walkRules(rule => {
+      // Nested variant rules are traversed too. The selector parser decodes
+      // CSS escapes, including arbitrary values, rather than guessing escapes.
+      selectorParser(selectors => {
+        selectors.walkClasses(node => emitted.add(node.value));
+      }).processSync(rule.selector);
+    });
+  } catch (error) {
+    throw new StylingError('E-CSS-OUTPUT', `cannot parse generated CSS: ${error.message}`);
+  }
+  for (const { class: candidate, origin } of candidates) {
+    if (!emitted.has(candidate) && !isStructuralMarker(candidate)) {
+      throw new StylingError('E-CLASS-NO-CSS',
+        `${JSON.stringify(candidate)} from ${origin} produced no CSS rule; ` +
+        'check the utility spelling and the available theme scales');
+    }
+  }
+}
+
+export function buildCss({ candidates, themeCss = '' }) {
+  if (!Array.isArray(candidates) || typeof themeCss !== 'string') {
+    throw new StylingError('E-CSS-MANIFEST', 'expected candidates and generated theme CSS');
+  }
+  for (const entry of candidates) {
+    if (!entry || typeof entry.class !== 'string' || !entry.class ||
+        /\s/.test(entry.class) || typeof entry.origin !== 'string' || !entry.origin) {
+      throw new StylingError('E-CSS-MANIFEST', 'each candidate needs one class and a source origin');
+    }
+  }
+  const unique = [...new Set(candidates.map(entry => entry.class))].sort();
+  // Only the generated compiler theme is trusted CSS. User class strings go
+  // into a plain source file, never into CSS directives or command arguments.
+  const dir = mkdtempSync(join(tmpdir(), 'volaro-css-'));
+  try {
+    writeFileSync(join(dir, 'candidates.txt'), unique.join('\n') + '\n');
+    const input = join(dir, 'input.css');
+    const output = join(dir, 'output.css');
+    // No preflight: keep existing generated HTML defaults intact. Cascade
+    // integration with vlrt.css belongs to the emitter integration slice.
+    writeFileSync(input,
+      `@import ${JSON.stringify(theme)} layer(theme);\n` +
+      `@import ${JSON.stringify(utilities)} layer(utilities) source(none);\n` +
+      '@source "./candidates.txt";\n' + themeCss + '\n');
+    const result = spawnSync(process.execPath, [cli, '-i', input, '-o', output, '--minify'], {
+      cwd: dir, encoding: 'utf8', timeout: 30000, maxBuffer: 4 * 1024 * 1024,
+    });
+    if (result.error || result.status !== 0) {
+      throw new StylingError('E-CSS-BUILD', result.error?.message || result.stderr ||
+        `Tailwind exited ${result.status}`);
+    }
+    const css = readFileSync(output, 'utf8');
+    verifyCandidates(css, candidates);
+    return { css, candidates: unique };
+  } finally {
+    // Only the concrete directory returned by mkdtemp is ever deleted.
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  try {
+    const request = JSON.parse(readFileSync(0, 'utf8'));
+    process.stdout.write(JSON.stringify(buildCss(request)));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  }
+}