tempest-react-sdk 0.76.0 → 0.78.0

package/bin/lib/component/generate.test.mjs

@@ -0,0 +1,336 @@
+import { spawnSync } from "node:child_process";
+import {
+    existsSync,
+    mkdirSync,
+    mkdtempSync,
+    readdirSync,
+    readFileSync,
+    rmSync,
+    symlinkSync,
+    writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ESLint } from "eslint";
+import ts from "typescript";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { componentFiles, normalizeComponentName } from "./generate.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO = resolve(HERE, "..", "..", "..");
+const CLI = join(REPO, "bin", "tempest.mjs");
+const TEMPLATE = join(REPO, "template");
+/**
+ * Component names that collide with something a generated file declares or
+ * imports: React built-in hooks (`use<Name>` would be `useMemo`), the `React`
+ * namespace, and globals the component function would shadow.
+ */
+const COLLIDING = [
+    "UserCard",
+    "Memo",
+    "State",
+    "Effect",
+    "Callback",
+    "LayoutEffect",
+    "React",
+    "ReactMemo",
+    "UseMemo",
+    "Object",
+    "Promise",
+    "Error",
+];
+const FILES = ["constants.ts", "hooks.ts", "index.tsx", "styles.module.css", "utils.ts"];
+
+describe("normalizeComponentName", () => {
+    it.each([
+        ["user card", "UserCard"],
+        ["user-card", "UserCard"],
+        ["user_card", "UserCard"],
+        ["userCard", "UserCard"],
+        ["UserCard", "UserCard"],
+        ["  button  ", "Button"],
+        ["api client", "ApiClient"],
+        ["APIClient", "APIClient"],
+        ["card2 header", "Card2Header"],
+    ])("%j → %s", (raw, expected) => {
+        expect(normalizeComponentName(raw)).toBe(expected);
+    });
+
+    it.each([
+        ["", /Missing component name/],
+        ["   ", /Missing component name/],
+        ["2fa", /must start with a letter/],
+        ["-card", /must start with a letter/],
+        ["user/card", /use ASCII letters, digits/],
+        ["../evil", /use ASCII letters, digits/],
+        ['card"; alert(1)', /use ASCII letters, digits/],
+        ["cartão", /use ASCII letters, digits/],
+        ["con", /reserved device name on Windows/],
+        ["NUL", /reserved device name on Windows/],
+        ["aux", /reserved device name on Windows/],
+        ["prn", /reserved device name on Windows/],
+        ["com1", /reserved device name on Windows/],
+        ["Lpt9", /reserved device name on Windows/],
+    ])("refuses %j", (raw, message) => {
+        expect(() => normalizeComponentName(raw)).toThrow(message);
+    });
+});
+
+describe("componentFiles", () => {
+    it("emits exactly the five files the issue asks for", () => {
+        const { name, files } = componentFiles("user card");
+        expect(name).toBe("UserCard");
+        expect(Object.keys(files).sort()).toEqual(FILES);
+    });
+
+    it("wires every file into index.tsx so none starts as dead code", () => {
+        const { files } = componentFiles("UserCard");
+        expect(files["index.tsx"]).toContain('from "./hooks"');
+        expect(files["index.tsx"]).toContain('from "./utils"');
+        expect(files["index.tsx"]).toContain('from "./styles.module.css"');
+        expect(files["hooks.ts"]).toContain('from "./constants"');
+    });
+
+    it("renames the hook when use<Name> is a React built-in hook", () => {
+        expect(componentFiles("Memo").files["hooks.ts"]).toContain(
+            "export function useMemoComponent(",
+        );
+        expect(componentFiles("State").files["index.tsx"]).toContain("useStateComponent(title)");
+        expect(componentFiles("Card").files["hooks.ts"]).toContain("export function useCard(");
+    });
+
+    it("writes no comment and no single-quoted string", () => {
+        const { files } = componentFiles("UserCard");
+        for (const [file, contents] of Object.entries(files)) {
+            expect(contents, file).not.toMatch(/\/\/|\/\*/);
+            expect(contents, file).not.toContain("'");
+        }
+    });
+
+    it.each(COLLIDING)(
+        "passes the app template's ESLint config as generated for %s",
+        async (componentName) => {
+            const dir = mkdtempSync(join(tmpdir(), "tempest-component-lint-"));
+            try {
+                const { files } = componentFiles(componentName);
+                for (const [file, contents] of Object.entries(files)) {
+                    writeFileSync(join(dir, file), contents);
+                }
+                const eslint = new ESLint({
+                    cwd: dir,
+                    overrideConfigFile: join(TEMPLATE, "eslint.config.js"),
+                });
+                const results = await eslint.lintFiles(["*.ts", "*.tsx"]);
+                const messages = results.flatMap((r) =>
+                    r.messages.map((m) => `${r.filePath}:${m.line} ${m.ruleId} ${m.message}`),
+                );
+                expect(results).toHaveLength(4);
+                expect(messages).toEqual([]);
+            } finally {
+                rmSync(dir, { recursive: true, force: true });
+            }
+        },
+    );
+
+    it.each(COLLIDING)(
+        "type-checks %s under the app template's strict tsconfig",
+        (componentName) => {
+            const { files } = componentFiles(componentName);
+            const tsconfig = ts.parseConfigFileTextToJson(
+                "tsconfig.json",
+                readFileSync(join(TEMPLATE, "tsconfig.json"), "utf8"),
+            ).config;
+            const { options } = ts.convertCompilerOptionsFromJson(
+                { ...tsconfig.compilerOptions, types: [], paths: undefined },
+                REPO,
+            );
+            const root = join(REPO, "__virtual_component__");
+            const virtual = new Map(
+                Object.entries(files)
+                    .filter(([file]) => !file.endsWith(".css"))
+                    .map(([file, contents]) => [join(root, file), contents]),
+            );
+            virtual.set(
+                join(root, "css-modules.d.ts"),
+                'declare module "*.module.css" {\n  const classes: Readonly<Record<string, string>>;\n  export default classes;\n}\n',
+            );
+            const host = ts.createCompilerHost(options);
+            const readFile = host.readFile.bind(host);
+            const fileExists = host.fileExists.bind(host);
+            host.readFile = (f) => virtual.get(f) ?? readFile(f);
+            host.fileExists = (f) => virtual.has(f) || fileExists(f);
+            const directoryExists = host.directoryExists?.bind(host);
+            host.directoryExists = (d) => d === root || (directoryExists?.(d) ?? true);
+            const getSourceFile = host.getSourceFile.bind(host);
+            host.getSourceFile = (f, lang) =>
+                virtual.has(f)
+                    ? ts.createSourceFile(f, virtual.get(f), lang)
+                    : getSourceFile(f, lang);
+            const program = ts.createProgram([...virtual.keys()], options, host);
+            const diagnostics = ts
+                .getPreEmitDiagnostics(program)
+                .map((d) => ts.flattenDiagnosticMessageText(d.messageText, "\n"));
+            expect(diagnostics).toEqual([]);
+        },
+    );
+});
+
+describe("tempest gen component (CLI)", () => {
+    let cwd;
+
+    beforeEach(() => {
+        cwd = mkdtempSync(join(tmpdir(), "tempest-component-cli-"));
+    });
+
+    afterEach(() => {
+        rmSync(cwd, { recursive: true, force: true });
+    });
+
+    /**
+     * Run the `tempest` CLI in the temporary project.
+     *
+     * @param {string[]} args - CLI arguments.
+     * @returns {{ status: number | null, out: string }}
+     */
+    function tempest(...args) {
+        const result = spawnSync(process.execPath, [CLI, ...args], { cwd, encoding: "utf8" });
+        return { status: result.status, out: result.stdout + result.stderr };
+    }
+
+    it("creates src/components/<Name>/ with the five files by default", () => {
+        const { status, out } = tempest("gen", "component", "user card");
+        expect(status).toBe(0);
+        expect(readdirSync(join(cwd, "src", "components", "UserCard")).sort()).toEqual(FILES);
+        expect(out).toContain('import { UserCard } from "@/components/UserCard";');
+    });
+
+    it("accepts `tempest new component`, the spelling from the issue", () => {
+        const { status } = tempest("new", "component", "Button");
+        expect(status).toBe(0);
+        expect(existsSync(join(cwd, "src", "components", "Button", "index.tsx"))).toBe(true);
+    });
+
+    it("refuses another `new` target instead of growing a second generator name", () => {
+        const { status, out } = tempest("new", "api");
+        expect(status).toBe(1);
+        expect(out).toMatch(/Unknown new target: api/);
+    });
+
+    it("honors --out", () => {
+        const { status, out } = tempest("gen", "component", "Card", "--out", "src/ui");
+        expect(status).toBe(0);
+        expect(existsSync(join(cwd, "src", "ui", "Card", "hooks.ts"))).toBe(true);
+        expect(out).toContain('from "@/ui/Card"');
+    });
+
+    it("refuses to touch an existing folder without --force", () => {
+        const dir = join(cwd, "src", "components", "Card");
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "index.tsx"), "mine");
+
+        const { status, out } = tempest("gen", "component", "Card");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/already exists.*--force/);
+        expect(readFileSync(join(dir, "index.tsx"), "utf8")).toBe("mine");
+    });
+
+    it("--force rewrites the five files and leaves the rest of the folder alone", () => {
+        const dir = join(cwd, "src", "components", "Card");
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "index.tsx"), "mine");
+        writeFileSync(join(dir, "Card.test.tsx"), "keep");
+
+        const { status } = tempest("gen", "component", "Card", "--force");
+
+        expect(status).toBe(0);
+        expect(readFileSync(join(dir, "index.tsx"), "utf8")).toContain("export function Card(");
+        expect(readFileSync(join(dir, "Card.test.tsx"), "utf8")).toBe("keep");
+    });
+
+    it("refuses to write through a symlinked folder even with --force", () => {
+        const outside = join(cwd, "outside");
+        mkdirSync(outside);
+        mkdirSync(join(cwd, "src", "components"), { recursive: true });
+        symlinkSync(outside, join(cwd, "src", "components", "Card"));
+
+        const { status, out } = tempest("gen", "component", "Card", "--force");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/symlink/);
+        expect(readdirSync(outside)).toEqual([]);
+    });
+
+    it.each([
+        [["gen", "component", "Card", "--out", "../x"], /outside the project/],
+        [["gen", "component", "Card", "--out", "/tmp/tempest-outside-abs"], /outside the project/],
+        [["gen", "component", "Card", "--out", "--force"], /--out needs a folder/],
+        [["gen", "component", "Card", "--out"], /--out needs a folder/],
+        [["gen", "component", "Card", "--out", ""], /--out needs a folder/],
+    ])("refuses an --out of %j", (args, message) => {
+        const { status, out } = tempest(...args);
+        expect(status).toBe(1);
+        expect(out).toMatch(message);
+        expect(existsSync(join(cwd, "src"))).toBe(false);
+        expect(existsSync(join(cwd, "--force"))).toBe(false);
+        expect(existsSync(join(dirname(cwd), "x"))).toBe(false);
+        expect(existsSync("/tmp/tempest-outside-abs")).toBe(false);
+    });
+
+    it("refuses an --out whose existing ancestor is a symlink leaving the project", () => {
+        const outside = mkdtempSync(join(tmpdir(), "tempest-component-outside-"));
+        try {
+            mkdirSync(join(cwd, "src"));
+            symlinkSync(outside, join(cwd, "src", "components"));
+
+            const { status, out } = tempest("gen", "component", "Card");
+
+            expect(status).toBe(1);
+            expect(out).toMatch(/outside the project/);
+            expect(readdirSync(outside)).toEqual([]);
+        } finally {
+            rmSync(outside, { recursive: true, force: true });
+        }
+    });
+
+    it("--force validates all five targets before writing any of them", () => {
+        const dir = join(cwd, "src", "components", "Card");
+        mkdirSync(join(dir, "utils.ts"), { recursive: true });
+        writeFileSync(join(dir, "index.tsx"), "mine");
+
+        const { status, out } = tempest("gen", "component", "Card", "--force");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/utils\.ts is not a regular file/);
+        expect(readFileSync(join(dir, "index.tsx"), "utf8")).toBe("mine");
+        expect(readdirSync(dir).sort()).toEqual(["index.tsx", "utils.ts"]);
+    });
+
+    it("prints the path with a warning instead of a wrong import outside src/", () => {
+        const { status, out } = tempest("gen", "component", "Card", "--out", "lib/ui");
+        expect(status).toBe(0);
+        expect(out).not.toMatch(/import \{ Card \}/);
+        expect(out).toMatch(/lib\/ui\/Card.*outside src\/.*@\//s);
+    });
+
+    it("keeps the @/ hint for a folder whose name merely starts with two dots", () => {
+        const { status, out } = tempest("gen", "component", "Card", "--out", "src/..ui");
+        expect(status).toBe(0);
+        expect(out).toContain('import { Card } from "@/..ui/Card";');
+    });
+
+    it.each([
+        [["gen", "component"], /Missing component name/],
+        [["gen", "component", "2fa"], /must start with a letter/],
+        [["gen", "component", "user", "card"], /Expected one component name, got 2/],
+        [["gen", "component", "Card", "--dry-run"], /Unknown option: --dry-run/],
+    ])("fails with a clear message for %j", (args, message) => {
+        const { status, out } = tempest(...args);
+        expect(status).toBe(1);
+        expect(out).toMatch(message);
+        expect(existsSync(join(cwd, "src"))).toBe(false);
+    });
+});

package/bin/lib/css/analyze.test.mjs

@@ -1,4 +1,4 @@
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -64,6 +64,26 @@ describe("analyzeCss — collection", () => {
         expect(analysis.stats.files).toBe(1);
     });
 
+    it("skips a sheet reached through a symlink leaving the project, so fix never rewrites it", () => {
+        const outside = mkdtempSync(join(tmpdir(), "tempest-css-outside-"));
+        try {
+            const before = ".a {\n    color: red;\n    color: red;\n}\n";
+            writeFileSync(join(outside, "a.css"), before);
+            symlinkSync(outside, join(root, "src"), "dir");
+
+            const analysis = analyze(["src"]);
+            applyCssFixes({ analysis });
+
+            expect(analysis.stats.files).toBe(0);
+            expect(analysis.skipped[0]).toMatchObject({
+                reason: "resolves outside the project through a symlink",
+            });
+            expect(readFileSync(join(outside, "a.css"), "utf8")).toBe(before);
+        } finally {
+            rmSync(outside, { recursive: true, force: true });
+        }
+    });
+
     it("sorts findings error → warn → info", () => {
         write("src/a.css", ".a {\n    color: ;\n}\n.b {\n    color: red;\n    color: red;\n}\n");
         const severities = analyze().findings.map((f) => f.severity);

package/bin/lib/css/collect.mjs

@@ -4,6 +4,8 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 
+import { landsInside } from "../fs/contain.mjs";
+
 const SKIP_DIRS = new Set([
     "node_modules",
     "dist",
@@ -19,6 +21,9 @@ const SKIP_DIRS = new Set([
     ".cache",
 ]);
 
+/** `skipped` reason for a sheet that resolves outside the project. */
+export const OUTSIDE_PROJECT = "resolves outside the project through a symlink";
+
 /** Above this size a stylesheet is treated as generated, not authored. */
 const MAX_BYTES = 512 * 1024;
 
@@ -35,6 +40,11 @@ export function looksMinified(text) {
 /**
  * Collect the project's own `.css` files.
  *
+ * A sheet that resolves outside the project once symlinks are followed is
+ * skipped with a reason: an explicit target that is a link (`tempest fix src`
+ * with `src -> /elsewhere`) is walked through it, and `fix` would rewrite sheets
+ * that are not the project's.
+ *
  * @param {object} params
  * @param {string} params.root - Project root; relative targets resolve against it.
  * @param {string[]} [params.targets] - Positional paths from the command line.
@@ -62,6 +72,10 @@ export function collectStylesheets({ root, targets = ["."], maxFiles = MAX_FILES
             skipped.push({ path, reason: "larger than 512 KB — treated as generated" });
             return;
         }
+        if (!landsInside(root, path)) {
+            skipped.push({ path, reason: OUTSIDE_PROJECT });
+            return;
+        }
         if (/\.min\.css$/.test(path)) {
             skipped.push({ path, reason: "minified" });
             return;

package/bin/lib/css/extract.mjs

@@ -18,13 +18,17 @@
 //     dead and take the remaining styles down with it;
 //   - the class is only ever read as `styles.row` / `styles["row"]`, never
 //     through a computed key or by handing the whole object around;
-//   - the target global sheet exists AND some source file imports it, because
-//     appending to a stylesheet nobody loads is a silent no-op;
+//   - no declaration carries a line terminator, so the appended rule is the
+//     same lines it was in the module and cannot open a new line of its own;
+//   - the target global sheet is a regular file (not a symlink) whose realpath is
+//     inside the project, AND some source file imports it, because appending to a
+//     stylesheet nobody loads is a silent no-op;
 //   - the new global name collides with nothing already in that sheet.
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 
 import { discoverAlias } from "../alias/discover.mjs";
+import { landsInside, lstatOrNull } from "../fs/contain.mjs";
 import { loadTypeScript, typeScriptUnavailableReason } from "../alias/typescript.mjs";
 import { collectSources, indexClassUses, resolveSpecifier } from "./references.mjs";
 import { parseCss } from "./parse.mjs";
@@ -33,6 +37,9 @@ import { declSignature } from "./semantic.mjs";
 /** A repeated block is only worth extracting from this many declarations up. */
 const MIN_DECLS = 3;
 
+/** CSS newlines (`\n`, `\r`, `\f`) plus the two Unicode line separators. */
+const LINE_TERMINATOR = /[\n\r\f\u2028\u2029]/;
+
 /** Stylesheets treated as "the project's global sheet", in order of preference. */
 const TARGET_CANDIDATES = [
     "src/styles/globals.css",
@@ -82,7 +89,7 @@ export function classNamesIn(parsed) {
  */
 export function findGlobalSheet({ root, explicit, alias }) {
     const candidates = explicit ? [explicit] : TARGET_CANDIDATES;
-    const found = candidates.map((rel) => join(root, rel)).find(existsSync);
+    const found = candidates.map((rel) => join(root, rel)).find((path) => lstatOrNull(path));
     if (!found) {
         return {
             error: explicit
@@ -95,6 +102,9 @@ export function findGlobalSheet({ root, explicit, alias }) {
             error: `${relative(root, found)} é um CSS Module — a folha alvo tem que ser global`,
         };
     }
+    const unsafe = unsafeTargetReason(root, found);
+    if (unsafe) return { error: `${relative(root, found)} ${unsafe} — recusado` };
+    const realFound = realpathSync(found);
 
     const imported = collectSources({ root }).some((file) => {
         let text;
@@ -106,7 +116,7 @@ export function findGlobalSheet({ root, explicit, alias }) {
         if (!text.includes(".css")) return false;
         for (const match of text.matchAll(/["']([^"']+\.css)["']/g)) {
             const target = resolveSpecifier({ specifier: match[1], fromFile: file, alias });
-            if (target === found) return true;
+            if (target !== null && realpathOrNull(target) === realFound) return true;
         }
         return false;
     });
@@ -118,6 +128,47 @@ export function findGlobalSheet({ root, explicit, alias }) {
     return { path: found, file: relative(root, found) };
 }
 
+/**
+ * `realpath` that answers `null` for a missing or dangling path.
+ *
+ * @param {string} path - Absolute path.
+ * @returns {string | null}
+ */
+function realpathOrNull(path) {
+    try {
+        return realpathSync(path);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Why the candidate global sheet must not be appended to, or `null`.
+ *
+ * `writeFileSync` follows symlinks, so a `src/index.css` that is a link — or
+ * that sits under a linked folder pointing out of the project — carries the
+ * append to wherever it points: measured before this check, a link to a shell rc
+ * file got the extracted rule appended, and a custom property value with a
+ * newline in it became a line the shell ran.
+ *
+ * The rule matches the generators': the sheet itself must be a regular file
+ * (`lstat`, so a link — dangling included — is refused), and its `realpath` must
+ * land inside `realpath(root)`. A symlinked folder that stays inside the project
+ * (a monorepo's `src -> app/src`) is accepted — the write lands in the project
+ * either way, and refusing it would switch the pass off for a legitimate layout.
+ *
+ * @param {string} root - Project root.
+ * @param {string} path - Absolute candidate path, which `lstat` sees.
+ * @returns {string | null} A phrase completing "`<file>` …", or `null`.
+ */
+function unsafeTargetReason(root, path) {
+    const stat = lstatOrNull(path);
+    if (stat?.isSymbolicLink()) return "é um symlink, e a escrita seguiria o link";
+    if (!stat?.isFile()) return "não é um arquivo comum";
+    if (!landsInside(root, path)) return "fica fora do projeto depois de resolver symlinks";
+    return null;
+}
+
 /** Group the analysed sheets by identical declaration block. */
 function groupBySignature(sheets) {
     const groups = new Map();
@@ -145,6 +196,13 @@ function occurrenceRefusal({ sheet, block, className, uses, opaqueModules }) {
     }
     if (!className) return `\`${block.prelude}\` não é uma classe simples`;
 
+    const broken = block.decls.find(
+        (d) => LINE_TERMINATOR.test(d.prop) || LINE_TERMINATOR.test(d.value),
+    );
+    if (broken) {
+        return `a declaração \`${broken.prop.split(LINE_TERMINATOR)[0]}\` tem quebra de linha — copiada pra folha global, viraria uma linha nova fora da regra`;
+    }
+
     const mentions = sheet.parsed.blocks.filter(
         (other) =>
             other !== block && new RegExp(`\\.${className}(?![A-Za-z0-9_-])`).test(other.prelude),

package/bin/lib/css/extract.test.mjs

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import { analyzeCss } from "./analyze.mjs";
@@ -295,6 +295,20 @@ describe("planExtraction — refusals", () => {
         expect(result.message).toContain("é um CSS Module");
     });
 
+    it("refuses a declaration with a line break instead of copying it into the global sheet", () => {
+        twoCopies();
+        const broken =
+            ".row {\n    --payload: x\necho INJECTED\n;\n    display: flex;\n    align-items: center;\n    gap: 8px;\n}\n.title {\n    font-weight: 600;\n}\n";
+        write("src/components/Card.module.css", broken);
+        write("src/components/List.module.css", broken.replace(".row", ".line"));
+        const result = plan();
+        expect(result.groups).toEqual([]);
+        expect(result.refusals.map((r) => r.reason)).toEqual([
+            expect.stringContaining("tem quebra de linha"),
+            expect.stringContaining("tem quebra de linha"),
+        ]);
+    });
+
     it("reports a missing TypeScript instead of guessing at the call sites", () => {
         twoCopies();
         rmSync(join(root, "node_modules", "typescript"), { recursive: true, force: true });
@@ -302,3 +316,98 @@ describe("planExtraction — refusals", () => {
         expect(result.status).toBe("no-typescript");
     });
 });
+
+describe("planExtraction — the global sheet stays inside the project (#483)", () => {
+    let outside;
+
+    beforeEach(() => {
+        project();
+        twoCopies();
+        outside = mkdtempSync(join(tmpdir(), "tempest-extract-outside-"));
+    });
+
+    afterEach(() => {
+        rmSync(outside, { recursive: true, force: true });
+    });
+
+    /** Plan and apply, the way `tempest fix --extract-css` does. */
+    const run = () => {
+        const result = plan();
+        applyExtraction({ plan: result });
+        return result;
+    };
+
+    it("refuses a src/index.css that is a symlink to a file outside the project", () => {
+        const victim = join(outside, "victimrc");
+        writeFileSync(victim, "echo ORIGINAL\n");
+        rmSync(join(root, "src/index.css"));
+        symlinkSync(victim, join(root, "src/index.css"));
+
+        const result = run();
+
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("é um symlink");
+        expect(readFileSync(victim, "utf8")).toBe("echo ORIGINAL\n");
+    });
+
+    it("refuses a dangling src/index.css symlink instead of falling through to another sheet", () => {
+        rmSync(join(root, "src/index.css"));
+        symlinkSync(join(outside, "not-yet.css"), join(root, "src/index.css"));
+        write("src/app.css", ":root {}\n");
+        write("src/main.tsx", 'import "./index.css";\nimport "./app.css";\n');
+
+        const result = run();
+
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("src/index.css é um symlink");
+    });
+
+    it("refuses a global sheet under a folder that is a symlink leaving the project", () => {
+        writeFileSync(join(outside, "globals.css"), ":root {}\n");
+        symlinkSync(outside, join(root, "src/styles"));
+        write("src/main.tsx", 'import "./styles/globals.css";\n');
+
+        const result = run();
+
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("fica fora do projeto");
+        expect(readFileSync(join(outside, "globals.css"), "utf8")).toBe(":root {}\n");
+    });
+
+    /**
+     * Reversed on purpose. The first version of #483 refused any symlink on the
+     * path, so a monorepo layout like `src/styles -> theme` switched the pass off
+     * with a `!` and exit 0. The write lands inside the project either way; what
+     * is refused is a link on the sheet itself and a realpath that leaves the
+     * project — the same rule as `gen api`/`gen component`.
+     */
+    it("accepts a symlinked folder that stays inside the project, as the generators do", () => {
+        write("theme/globals.css", ":root {}\n");
+        symlinkSync(join(root, "theme"), join(root, "src/styles"));
+        write("src/main.tsx", 'import "./styles/globals.css";\n');
+
+        const result = run();
+
+        expect(result.status).toBe("ok");
+        expect(result.groups).toHaveLength(1);
+        expect(readFileSync(join(root, "theme/globals.css"), "utf8")).toContain(".u-row {");
+    });
+
+    it("refuses a --css-target outside the project", () => {
+        writeFileSync(join(outside, "x.css"), "");
+        const result = plan({ target: relative(root, join(outside, "x.css")) });
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("fora do projeto");
+    });
+
+    it("matches importers by realpath, so a project under a symlinked path still works", () => {
+        const linked = join(outside, "linked-project");
+        symlinkSync(root, linked);
+        const result = planExtraction({
+            analysis: analyzeCss({ root: linked, targets: ["."], selfDir: SELF_DIR }),
+            root: linked,
+        });
+        expect(result.status).toBe("ok");
+        expect(result.groups).toHaveLength(1);
+    });
+});