@invariant-ui/cli 0.0.0-stage → 0.2.0

package/dist/cli/workflow.js

@@ -0,0 +1,52 @@
+import { CLI_VERSION, NPM_PACKAGE } from "./version.js";
+export const WORKFLOW_PATH = ".github/workflows/invariant.yml";
+/**
+ * Steps that install a project's dependencies, for a project that gets its contract from a package. The package manager
+ * is the one the lockfile says. Returns steps already indented for the workflow.
+ */
+export function installStepsFor(has) {
+    if (has("pnpm-lock.yaml"))
+        return ["      - uses: pnpm/action-setup@v4", "      - run: pnpm install --frozen-lockfile"];
+    if (has("yarn.lock"))
+        return ["      - run: yarn install --frozen-lockfile"];
+    if (has("package-lock.json"))
+        return ["      - run: npm ci"];
+    return ["      - run: npm install"];
+}
+/**
+ * The GitHub Actions job `setup` offers to add. It runs on every pull request commit, pins the exact version it was
+ * written for so a later release cannot change what CI does, and needs only Node: npx fetches the package. Paths are
+ * quoted, since they come from the project's folder names.
+ */
+export function workflowYaml(paths, installSteps = []) {
+    const targets = (paths.length > 0 ? paths : ["src"]).map((p) => `'${p.replace(/'/g, "''")}'`).join(" ");
+    const run = `npx ${NPM_PACKAGE}@${CLI_VERSION}`;
+    return `# Added by \`invariant setup\`. Checks every commit on a pull request against your design system contract.
+name: Invariant
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+permissions:
+  contents: read
+concurrency:
+  group: invariant-\${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  invariant:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+${installSteps.length > 0 ? `${installSteps.join("\n")}\n` : ""}      # Fails if the committed contract (the invariant/ folder) is stale or was edited by hand.
+      - name: Verify the contract is current
+        run: ${run} verify --fresh
+      # Annotates the pull request. Violations listed in invariant.baseline.json are hidden; new ones fail the check.
+      - name: Validate code against the contract
+        run: ${run} validate ${targets} --format github
+`;
+}
+//# sourceMappingURL=workflow.js.map

package/dist/compiler-angular/adapter.js

@@ -0,0 +1,115 @@
+import { DEFAULT_IGNORED_DIRS, hashText, IrBuilder, walk } from "../compiler-core/index.js";
+import { hashJson } from "../shared/index.js";
+import { analyzePackage } from "./analyze.js";
+import { CAPABILITIES, emitComponent, emitModule } from "./emit.js";
+export const ADAPTER_ID = "angular";
+export const ADAPTER_VERSION = "0.1.0";
+const SOURCE_FILE = /\.(?:[cm]?[jt]sx?|html|css|scss|sass|less)$|(?:^|\/)tsconfig[^/]*\.json$/;
+const MAX_FILE_BYTES = 1_000_000;
+/**
+ * Angular adapter. For every workspace package that declares `@angular/core` it reads decorated classes
+ * with the TypeScript API (what the Angular compiler reads from decorators, evaluated statically):
+ * components and directives, decorator and signal inputs and outputs, `model()`, selectors, standalone
+ * metadata and imports, content projection, host bindings, templates and styles, and NgModules.
+ * Nothing is executed. `node_modules` is read only for a package opted in as a declaration root, from its `.d.ts` files.
+ */
+export const angularAdapter = {
+    id: ADAPTER_ID,
+    version: ADAPTER_VERSION,
+    type: "angular",
+    async discover({ fs, project }) {
+        const sources = [];
+        const used = new Set();
+        for (const pkg of project.packages.filter((p) => p.frameworks.some((f) => f.name === "angular"))) {
+            const others = project.packages.filter((p) => p.id !== pkg.id && p.dir !== "." && (pkg.dir === "." || p.dir.startsWith(`${pkg.dir}/`)));
+            const { files, hashes } = await readPackageFiles(fs, pkg, others);
+            const slug = (pkg.name ?? pkg.dir)
+                .toLowerCase()
+                .replace(/[^a-z0-9._-]+/g, "-")
+                .replace(/^[^a-z0-9]+|[-.]+$/g, "") || "root";
+            let id = `angular-${slug}`;
+            for (let n = 2; used.has(id); n++)
+                id = `angular-${slug}-${n}`;
+            used.add(id);
+            sources.push({
+                id,
+                type: "angular",
+                location: pkg.dir,
+                config: { packageId: pkg.id, files: [...files.keys()] },
+                ...(pkg.version ? { version: { kind: "package-version", value: pkg.version } } : {}),
+                inputHash: hashJson(hashes)
+            });
+        }
+        return { sources, diagnostics: [] };
+    },
+    async extract({ fs, project, source, clock }, config) {
+        const pkg = project.packages.find((p) => p.id === config.packageId);
+        if (!pkg)
+            throw new Error(`Package ${config.packageId} is not in the project discovery`);
+        const files = new Map();
+        for (const path of config.files)
+            files.set(path, await fs.readFile(path));
+        const analysis = analyzePackage({
+            ...(pkg.name ? { packageName: pkg.name } : {}),
+            packageDir: pkg.dir,
+            entryPoints: pkg.entryPoints,
+            files
+        });
+        const builder = new IrBuilder({
+            source: {
+                id: source.id,
+                type: source.type,
+                location: source.location,
+                ...(source.version ? { version: source.version } : {}),
+                inputHash: source.inputHash,
+                adapter: { name: ADAPTER_ID, version: ADAPTER_VERSION }
+            },
+            extractor: { name: "angular-ts", version: ADAPTER_VERSION },
+            capabilities: CAPABILITIES,
+            clock
+        });
+        for (const component of analysis.components)
+            emitComponent(builder, component, pkg);
+        for (const module of analysis.modules)
+            emitModule(builder, module);
+        for (const d of analysis.diagnostics)
+            builder.diagnostic(d);
+        return { ir: builder.build(analysis.components.some((c) => !c.propsComplete) ? "partial" : "complete") };
+    },
+    async validate({ ir }) {
+        return !ir.entities.some((e) => e.kind === "component")
+            ? [
+                {
+                    code: "angular.no-components",
+                    severity: "info",
+                    message: `No Angular components or directives were found in the entry points of ${ir.source.id}`,
+                    sourceId: ir.source.id
+                }
+            ]
+            : [];
+    }
+};
+async function readPackageFiles(fs, pkg, nested) {
+    // An installed package (opted in through a declaration root) keeps its declaration files in build output.
+    const installed = pkg.dir.split("/").includes("node_modules");
+    const walked = await walk(fs, {
+        ignoreDirs: new Set(installed
+            ? DEFAULT_IGNORED_DIRS.filter((d) => !["dist", "build", "out"].includes(d))
+            : DEFAULT_IGNORED_DIRS),
+        maxFiles: 20_000,
+        start: pkg.dir
+    });
+    const files = new Map();
+    const hashes = [];
+    for (const path of walked.files) {
+        if (!SOURCE_FILE.test(path) || nested.some((n) => path === n.dir || path.startsWith(`${n.dir}/`)))
+            continue;
+        const text = await fs.readFile(path);
+        if (text.length > MAX_FILE_BYTES)
+            continue;
+        files.set(path, text);
+        hashes.push([path, hashText(text)]);
+    }
+    return { files, hashes };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/compiler-angular/analyze.js

@@ -0,0 +1,222 @@
+import { createAnalysis, cssVariableReferences, declarationOf, isProjectNode, posix, resolveSymbol, tsconfigPaths } from "../compiler-core/index.js";
+import ts from "typescript";
+import { readClass } from "./classes.js";
+import { readDeclaredClass } from "./declared.js";
+import { matchesSelector, parseSelector, scanTemplate } from "./template.js";
+const NON_SOURCE = /\.(?:test|spec|stories)\.[cm]?[jt]sx?$|(?:^|\/)__(?:tests|mocks)__\//;
+/** Public components and directives (class exports of the entry points) plus every NgModule, read statically. */
+export function analyzePackage(input) {
+    const diagnostics = [];
+    const note = (severity, code, message, location) => {
+        diagnostics.push({ code, severity, message, ...(location ? { location } : {}) });
+    };
+    const codeFiles = new Map([...input.files].filter(([path]) => /\.[cm]?[jt]sx?$/.test(path) && !NON_SOURCE.test(path)));
+    // A library imports its own entry points by package name (`@scope/lib/accordion`): map those to files.
+    const paths = { ...tsconfigPaths(input.files, input.packageDir) };
+    if (input.packageName) {
+        for (const entry of input.entryPoints) {
+            if (entry.file)
+                paths[entry.subpath === "."
+                    ? input.packageName
+                    : `${input.packageName}/${entry.subpath.replace(/^\.\//, "")}`] = [entry.file];
+        }
+    }
+    const analysis = createAnalysis(codeFiles, { paths });
+    const publicClasses = new Map();
+    for (const entry of input.entryPoints) {
+        const sf = entry.file ? analysis.sourceFile(entry.file) : undefined;
+        const moduleSymbol = sf ? analysis.checker.getSymbolAtLocation(sf) : undefined;
+        if (!sf || !moduleSymbol)
+            continue;
+        for (const exported of analysis.checker.getExportsOfModule(moduleSymbol)) {
+            const decl = declarationOf(resolveSymbol(analysis.checker, exported));
+            if (decl && ts.isClassDeclaration(decl) && isProjectNode(analysis, decl))
+                publicClasses.set(decl, [
+                    ...(publicClasses.get(decl) ?? []),
+                    { subpath: entry.subpath, name: exported.name }
+                ]);
+        }
+    }
+    const metas = new Map();
+    const modules = [];
+    for (const sf of analysis.program.getSourceFiles()) {
+        if (!analysis.relativePath(sf.fileName))
+            continue;
+        for (const statement of sf.statements) {
+            if (!ts.isClassDeclaration(statement))
+                continue;
+            const meta = readClass(analysis, statement) ?? readDeclaredClass(analysis, statement);
+            if (!meta)
+                continue;
+            metas.set(statement, meta);
+            if (meta.kind === "module")
+                modules.push({ ref: `angular:${meta.file}#${meta.name}`, meta, public: publicClasses.has(statement) });
+        }
+    }
+    const publicComponents = [...publicClasses.keys()].flatMap((decl) => {
+        const meta = metas.get(decl);
+        return meta && meta.kind !== "module" ? [{ decl, meta }] : [];
+    });
+    const selectors = new Map();
+    const refs = new Map();
+    for (const { decl, meta } of publicComponents) {
+        refs.set(decl, `angular:${meta.file}#${meta.name}`);
+        if (meta.selector)
+            selectors.set(refs.get(decl), parseSelector(meta.selector));
+    }
+    const components = publicComponents.map(({ decl, meta }) => {
+        const ref = refs.get(decl);
+        const template = readTemplate(meta, input.files, note);
+        const styling = readStyling(meta, input.files, note);
+        const renders = new Map();
+        for (const element of template?.info.elements ?? []) {
+            for (const [targetRef, parsed] of selectors) {
+                if (targetRef !== ref && matchesSelector(element, parsed))
+                    renders.set(targetRef, (renders.get(targetRef) ?? 0) + 1);
+            }
+        }
+        const { inputs, outputs, complete } = withMetadataMembers(meta);
+        if (!meta.selector && meta.kind === "component")
+            note("info", "angular.no-selector", `${meta.name} has no static selector`, {
+                path: meta.file,
+                line: meta.line
+            });
+        for (const message of meta.notes)
+            note("info", "angular.unsupported", `${meta.name}: ${message}`, { path: meta.file, line: meta.line });
+        if (meta.inheritsFrom.length > 0)
+            note("info", "angular.base-class-external", `${meta.name} extends ${meta.inheritsFrom.join(", ")}, whose inputs and outputs are not enumerated`, { path: meta.file, line: meta.line });
+        const a11y = accessibilityOf(template?.info);
+        return {
+            ref,
+            meta,
+            exports: (publicClasses.get(decl) ?? []).sort((a, b) => a.subpath < b.subpath ? -1 : a.subpath > b.subpath ? 1 : a.name < b.name ? -1 : 1),
+            inputs,
+            outputs,
+            ...(template ? { template } : {}),
+            accessibility: a11y,
+            styling,
+            renders: [...renders]
+                .map(([target, count]) => ({ target, count }))
+                .sort((a, b) => (a.target < b.target ? -1 : 1)),
+            modules: modulesOf(meta, modules),
+            propsComplete: complete && meta.inheritsFrom.length === 0 && meta.hostDirectives.length === 0
+        };
+    });
+    components.sort((a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0));
+    modules.sort((a, b) => (a.ref < b.ref ? -1 : 1));
+    return { components, modules, diagnostics };
+}
+function readTemplate(meta, files, note) {
+    const template = meta.template;
+    if (!template)
+        return undefined;
+    if ("inline" in template)
+        return {
+            source: "inline",
+            file: meta.file,
+            line: template.line,
+            info: scanTemplate(template.inline, template.line)
+        };
+    const file = posix.normalize(posix.join(posix.dirname(meta.file), template.url));
+    const text = files.get(file);
+    if (text === undefined) {
+        note("warning", "angular.templateurl-missing", `${meta.name}: template file ${file} was not found`, {
+            path: meta.file,
+            line: meta.line
+        });
+        return undefined;
+    }
+    return { source: "file", file, line: 1, info: scanTemplate(text, 1) };
+}
+function readStyling(meta, files, note) {
+    const variables = new Map();
+    const styleFiles = [];
+    for (const s of meta.styles) {
+        for (const ref of cssVariableReferences(s.text))
+            if (!variables.has(ref.name))
+                variables.set(ref.name, { file: meta.file, line: s.line + ref.line - 1 });
+    }
+    for (const url of meta.styleUrls) {
+        const file = posix.normalize(posix.join(posix.dirname(meta.file), url));
+        const text = files.get(file);
+        if (text === undefined) {
+            note("warning", "angular.styleurl-missing", `${meta.name}: stylesheet ${file} was not found`, {
+                path: meta.file,
+                line: meta.line
+            });
+            continue;
+        }
+        styleFiles.push(file);
+        for (const ref of cssVariableReferences(text))
+            if (!variables.has(ref.name))
+                variables.set(ref.name, { file, line: ref.line });
+    }
+    return {
+        files: styleFiles.sort(),
+        variables: [...variables].map(([name, v]) => ({ name, ...v })).sort((a, b) => (a.name < b.name ? -1 : 1)),
+        preprocessors: [
+            ...new Set(styleFiles.flatMap((f) => /\.(scss|sass|less)$/.exec(f)?.[1] ? [/\.(scss|sass|less)$/.exec(f)?.[1]] : []))
+        ].sort()
+    };
+}
+function accessibilityOf(info) {
+    const roles = new Set();
+    const attributes = new Set();
+    for (const element of info?.elements ?? []) {
+        // Native elements only: custom elements (with a dash) are Angular components.
+        if (element.tag.includes("-") || /^[A-Z]/.test(element.tag) || element.tag === "ng-content")
+            continue;
+        for (const a of element.attributes) {
+            if (a.name === "role" && !a.bound && a.value)
+                roles.add(a.value);
+            if (a.name.startsWith("aria-"))
+                attributes.add(a.name);
+        }
+    }
+    return { roles: [...roles].sort(), attributes: [...attributes].sort() };
+}
+/** `inputs: ['a', 'b: alias']` and `outputs: [...]` in the decorator, for names with no declared member. */
+function withMetadataMembers(meta) {
+    const inputs = [...meta.inputs];
+    const outputs = [...meta.outputs];
+    for (const spec of meta.metadataInputs) {
+        const [property = "", alias] = spec.split(":").map((s) => s.trim());
+        const name = alias || property;
+        if (!property || inputs.some((i) => i.name === name))
+            continue;
+        inputs.push({
+            name,
+            property,
+            kind: "input",
+            typeText: "unknown",
+            typeKind: "unknown",
+            required: false,
+            ...(alias ? { alias } : {}),
+            node: meta.node
+        });
+    }
+    for (const spec of meta.metadataOutputs) {
+        const [property = "", alias] = spec.split(":").map((s) => s.trim());
+        const name = alias || property;
+        if (!property || outputs.some((o) => o.name === name))
+            continue;
+        outputs.push({ name, property, kind: "output", ...(alias ? { alias } : {}), node: meta.node });
+    }
+    inputs.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    outputs.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return { inputs, outputs, complete: true };
+}
+function modulesOf(meta, modules) {
+    const matches = (refs) => refs.some((r) => r.file === meta.file && r.localName === meta.name);
+    return {
+        declaredIn: modules
+            .filter((m) => matches(m.meta.declarations))
+            .map((m) => m.meta.name)
+            .sort(),
+        exportedBy: modules
+            .filter((m) => matches(m.meta.exports))
+            .map((m) => m.meta.name)
+            .sort()
+    };
+}
+//# sourceMappingURL=analyze.js.map