@oddkin/analyzer 0.0.0-stage → 1.0.0-beta.0

package/dist/examples.js

@@ -0,0 +1,185 @@
+/**
+ * Colocated `*.examples.ts` files (ADR 0021): find `defineExamples('tag', { name: { … } })`
+ * calls by parsing, never by executing, and record each example's name, fixture presence, and
+ * preview roles. Example files are development-only sources outside the package build, so they
+ * are discovered on disk rather than taken from the program.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import ts from 'typescript';
+const EXAMPLE_FILE = /\.examples\.(m?ts|m?js)$/;
+const SKIP = new Set(['node_modules', 'dist']);
+/** Example files under `dir`, sorted. */
+export function findExampleFiles(dir) {
+    const out = [];
+    const walk = (current) => {
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP.has(entry.name))
+                    walk(path);
+            }
+            else if (EXAMPLE_FILE.test(entry.name))
+                out.push(path);
+        }
+    };
+    walk(dir);
+    return out.sort();
+}
+const text = (node) => node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+    ? node.text
+    : undefined;
+const keyOf = (name) => ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
+const TAG = /<([a-z][a-z0-9]*-[a-z0-9-]*)[\s>/]/g;
+/** Custom-element tags written literally under `node`: markup in strings and templates, `createElement('x-y')`. */
+function literalTags(node) {
+    const tags = new Set();
+    const visit = (child) => {
+        if (ts.isStringLiteral(child) ||
+            ts.isNoSubstitutionTemplateLiteral(child) ||
+            ts.isTemplateHead(child) ||
+            ts.isTemplateMiddle(child) ||
+            ts.isTemplateTail(child)) {
+            for (const match of `${child.text} `.matchAll(TAG))
+                tags.add(match[1]);
+            if (ts.isStringLiteral(child) &&
+                /^[a-z][a-z0-9]*-[a-z0-9-]*$/.test(child.text) &&
+                ts.isCallExpression(child.parent) &&
+                ts.isPropertyAccessExpression(child.parent.expression) &&
+                child.parent.expression.name.text === 'createElement')
+                tags.add(child.text);
+        }
+        ts.forEachChild(child, visit);
+    };
+    visit(node);
+    return tags;
+}
+export function extractExamples(files, root) {
+    const examples = [];
+    const diagnostics = [];
+    for (const path of files) {
+        const file = relative(root, path).split(sep).join('/');
+        const source = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true);
+        const at = (node) => {
+            const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+            return { file, line: line + 1, column: character + 1 };
+        };
+        const dynamic = (node, message) => diagnostics.push({
+            code: 'analyzer.examples.dynamic',
+            severity: 'warning',
+            message,
+            source: at(node),
+            suggestion: 'Use a string literal tag and an object literal of examples with literal names.',
+        });
+        // Local names bound to `defineExamples` from the Workbench examples entry.
+        const names = new Set();
+        for (const statement of source.statements) {
+            if (ts.isImportDeclaration(statement) &&
+                text(statement.moduleSpecifier) === '@oddkin/workbench/examples' &&
+                statement.importClause?.namedBindings &&
+                ts.isNamedImports(statement.importClause.namedBindings)) {
+                for (const element of statement.importClause.namedBindings.elements)
+                    if ((element.propertyName ?? element.name).text === 'defineExamples')
+                        names.add(element.name.text);
+            }
+        }
+        const visit = (node) => {
+            if (ts.isCallExpression(node) &&
+                ts.isIdentifier(node.expression) &&
+                names.has(node.expression.text)) {
+                const [tagArg, setArg] = node.arguments;
+                const component = text(tagArg);
+                if (!component || !setArg || !ts.isObjectLiteralExpression(setArg)) {
+                    dynamic(node, 'defineExamples() needs a literal tag and an object literal of examples.');
+                    return;
+                }
+                for (const property of setArg.properties) {
+                    const name = property.name && keyOf(property.name);
+                    if (!ts.isPropertyAssignment(property) ||
+                        !name ||
+                        !ts.isObjectLiteralExpression(property.initializer)) {
+                        dynamic(property, `An example of <${component}> is not a literal entry.`);
+                        continue;
+                    }
+                    let hasFixture = false;
+                    let previewRoles;
+                    let incorrect;
+                    const texts = [];
+                    const authored = (node, field) => {
+                        const value = node && text(node);
+                        if (node && value)
+                            texts.push({
+                                text: value,
+                                subject: component,
+                                at: `example:${component}/${name} ${field}`,
+                                source: at(node),
+                            });
+                    };
+                    for (const field of property.initializer.properties) {
+                        const key = field.name && keyOf(field.name);
+                        if (key === 'fixture')
+                            hasFixture = true;
+                        if ((key === 'label' || key === 'guidance') && ts.isPropertyAssignment(field))
+                            authored(field.initializer, key);
+                        if (key === 'incorrect') {
+                            // Read literally: an example that cannot be shown to be a mistake is left out
+                            // rather than listed as a usable one.
+                            const value = ts.isPropertyAssignment(field) ? field.initializer : undefined;
+                            const read = (name) => value && ts.isObjectLiteralExpression(value)
+                                ? value.properties
+                                    .filter(ts.isPropertyAssignment)
+                                    .map((p) => (keyOf(p.name) === name ? text(p.initializer) : undefined))
+                                    .find((v) => v !== undefined)
+                                : undefined;
+                            const diagnostic = read('diagnostic');
+                            const correct = read('correct');
+                            if (value && ts.isObjectLiteralExpression(value))
+                                for (const p of value.properties)
+                                    if (ts.isPropertyAssignment(p) && keyOf(p.name) === 'explanation')
+                                        authored(p.initializer, 'explanation');
+                            incorrect = diagnostic && correct ? { diagnostic, correct } : null;
+                            if (!incorrect)
+                                dynamic(field, `Incorrect example "${name}" of <${component}> needs literal diagnostic and correct names; it is left out.`);
+                        }
+                        if (key !== 'previewRoles')
+                            continue;
+                        const value = ts.isPropertyAssignment(field) ? field.initializer : undefined;
+                        const roles = value && ts.isArrayLiteralExpression(value) ? value.elements.map(text) : undefined;
+                        if (!roles || roles.some((role) => role === undefined))
+                            dynamic(field, `Preview roles of example "${name}" of <${component}> are not literal.`);
+                        else
+                            previewRoles = roles;
+                    }
+                    if (incorrect === null)
+                        continue;
+                    const uses = [...literalTags(property.initializer)]
+                        .filter((tag) => tag !== component)
+                        .sort();
+                    examples.push({
+                        component,
+                        name,
+                        file,
+                        hasFixture,
+                        ...(previewRoles ? { previewRoles } : {}),
+                        ...(incorrect ? { incorrect } : {}),
+                        ...(uses.length ? { uses } : {}),
+                        ...(texts.length ? { texts } : {}),
+                        location: at(property),
+                    });
+                }
+                return;
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    return { examples, diagnostics };
+}
+//# sourceMappingURL=examples.js.map

package/dist/examples.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"examples.js","sourceRoot":"","sources":["../src/examples.ts"],"names":[],"mappings":"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"}

package/dist/extract.d.ts

@@ -0,0 +1,208 @@
+import ts from 'typescript';
+import { type StyleMapping, type TokenCss } from './style-mappings.js';
+export interface SourceLocation {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+}
+export interface AnalyzerDiagnostic {
+    readonly code: string;
+    readonly severity: 'error' | 'warning' | 'info';
+    readonly message: string;
+    readonly source?: SourceLocation;
+    readonly suggestion?: string;
+}
+export type Known<T> = {
+    readonly known: true;
+    readonly value: T;
+} | {
+    readonly known: false;
+};
+export interface PropertyInfo {
+    readonly name: string;
+    readonly kind: string;
+    readonly type: string;
+    readonly attribute: string | null;
+    readonly reflects: boolean;
+    /** JavaScript expression text of the default, when statically known. */
+    readonly default: Known<string>;
+    readonly values?: readonly string[];
+    readonly description?: string;
+    readonly deprecated?: Deprecation;
+    readonly inheritedFrom?: ClassRef;
+}
+/** `@deprecated` with its authored `@replacement` and `@migration` tags. */
+export interface Deprecation {
+    readonly reason?: string;
+    /** As written: a tag, a member name, or a stable id. */
+    readonly replacement?: string;
+    readonly migration?: string;
+    readonly location?: SourceLocation;
+}
+export interface EventInfo {
+    readonly name: string;
+    readonly detailType: string;
+    readonly bubbles: boolean;
+    readonly composed: boolean;
+    readonly cancelable: boolean;
+    readonly syncs?: string;
+    /** Declared `intent`; absent when the definition does not state it (unknown). */
+    readonly intent?: {
+        readonly value: 'user' | 'notification';
+        readonly source?: SourceLocation;
+    };
+    readonly description?: string;
+    readonly deprecated?: Deprecation;
+    readonly inheritedFrom?: ClassRef;
+}
+export interface MemberInfo {
+    readonly kind: 'field' | 'method';
+    readonly name: string;
+    readonly type: string;
+    readonly readonly: boolean;
+    readonly description?: string;
+}
+export interface NamedDoc {
+    readonly name: string;
+    readonly description?: string;
+}
+export interface ClassRef {
+    readonly name: string;
+    /** Library-relative source path, or the module path in `package` when that is set. */
+    readonly file: string;
+    /** Package that publishes the class, when it is not the analyzed library. */
+    readonly package?: string;
+}
+export interface ComponentInfo {
+    readonly name: string;
+    readonly file: string;
+    /** Package that publishes this class, for a base read from another package's metadata. */
+    readonly package?: string;
+    readonly location: SourceLocation;
+    readonly description?: string;
+    readonly superclass: {
+        readonly name: string;
+        readonly package?: string;
+        readonly file?: string;
+    };
+    readonly properties: readonly PropertyInfo[];
+    readonly events: readonly EventInfo[];
+    readonly members: readonly MemberInfo[];
+    readonly slots: readonly NamedDoc[];
+    readonly parts: readonly NamedDoc[];
+    readonly cssProperties: readonly NamedDoc[];
+    readonly cssStates: readonly NamedDoc[];
+    readonly tokenReads: readonly {
+        readonly token: string;
+        readonly readThrough: 'stylesheet';
+    }[];
+    /** Option or state → part → CSS property → token, where the definition's styles state it. */
+    readonly styleMappings?: readonly StyleMapping[];
+    readonly tags: Readonly<Record<string, readonly {
+        value: string;
+        location: SourceLocation;
+    }[]>>;
+    readonly exported: boolean;
+    /** Facts supplied by explicit metadata (`@oddkin-metadata file.json`), as stable member ids. */
+    readonly authored?: {
+        readonly file: string;
+        readonly ids: readonly string[];
+    };
+    /**
+     * Names found only by scanning `render()` and `static styles` (here or in a base class), so a
+     * definition's template and styles can replace them. JSDoc-declared names are not included.
+     */
+    readonly derived?: {
+        readonly slots: readonly string[];
+        readonly parts: readonly string[];
+        readonly cssProperties: readonly string[];
+        readonly tokens: readonly string[];
+    };
+}
+/** A named export in a source file (definition, template, or styles). */
+export interface SourceRef {
+    readonly name: string;
+    /** Library-relative source path, the package specifier when `external`, or the module path in `package`. */
+    readonly file: string;
+    /** Imported from another package's published declarations (e.g. shared styles). */
+    readonly external?: true;
+    /** Inherited from a definition another package publishes; `file` is that package's module path. */
+    readonly package?: string;
+}
+/** What a style source reads: CSS custom properties and tokens (`var(--odd-…)` or `token('…')`). */
+export interface StyleReads {
+    readonly cssProperties: readonly string[];
+    readonly tokens: readonly string[];
+    /** The CSS text, so packages that reuse the source can read its style mappings. */
+    readonly css?: TokenCss;
+}
+/** An exported template's anatomy, published so recomposing packages know what it provides. */
+export interface TemplateSource {
+    readonly ref: SourceRef;
+    readonly slots: readonly string[];
+    readonly parts: readonly string[];
+}
+/** An exported style source and what it reads. */
+export interface StyleSource extends StyleReads {
+    readonly ref: SourceRef;
+}
+/** A `compose()` definition resolved statically. */
+export interface DefinitionInfo {
+    readonly tag: string;
+    readonly className: string;
+    readonly classFile: string;
+    /** The variable holding the definition, when it is one. */
+    readonly ref?: SourceRef;
+    readonly template?: SourceRef;
+    readonly styles: readonly SourceRef[];
+    /** Named roles → tag names of dependency definitions. */
+    readonly dependencies: Readonly<Record<string, string>>;
+    /** Tag of the definition this one was recomposed from (`...base`). */
+    readonly extends?: string;
+    readonly location: SourceLocation;
+}
+export interface Registration {
+    readonly tag: string;
+    readonly className: string;
+    readonly classFile: string;
+    readonly file: string;
+    readonly location: SourceLocation;
+    /** Present when registered with `define(definition)`. */
+    readonly definition?: DefinitionInfo;
+}
+export interface RecipeInfo {
+    readonly name: string;
+    readonly regions: Readonly<Record<string, string>>;
+    readonly variants: Readonly<Record<string, readonly string[]>>;
+    readonly conditions: readonly string[];
+    readonly parts: readonly string[];
+    readonly container?: {
+        readonly selector?: string;
+        readonly name?: string;
+    };
+    readonly location: SourceLocation;
+}
+export interface ModelInfo {
+    readonly name: string;
+    readonly version: number;
+    readonly kinds: readonly string[];
+    readonly location: SourceLocation;
+}
+export interface Extraction {
+    readonly components: readonly ComponentInfo[];
+    readonly registrations: readonly Registration[];
+    readonly recipes: readonly RecipeInfo[];
+    readonly models: readonly ModelInfo[];
+    readonly definitions: readonly DefinitionInfo[];
+    readonly exports: ReadonlyMap<string, readonly string[]>;
+    /** Exported templates and style sources of the analyzed library. */
+    readonly sources: {
+        readonly templates: readonly TemplateSource[];
+        readonly styles: readonly StyleSource[];
+    };
+    readonly diagnostics: readonly AnalyzerDiagnostic[];
+}
+export declare function extract(program: ts.Program, root: string): Extraction;
+/** Resolve a path relative to `root` into an absolute path (helper for callers). */
+export declare const absolute: (root: string, file: string) => string;
+//# sourceMappingURL=extract.d.ts.map

package/dist/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"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"}