fix(render): scope strict lint to composition

packages/cli/src/commands/render.ts

@@ -807,7 +807,8 @@ export default defineCommand({
 
     // ── Pre-render lint ──────────────────────────────────────────────────
     {
-      const lintResult = await lintProject(project.dir);
+      const explicitEntry = args.composition && args.composition !== "." ? entryFile : undefined;
+      const lintResult = await lintProject(project.dir, explicitEntry);
       if (!quiet && (lintResult.totalErrors > 0 || lintResult.totalWarnings > 0)) {
         console.log("");
         for (const line of formatLintFindings(lintResult, { errorsFirst: true })) console.log(line);

packages/cli/src/utils/lintProject.test.ts

@@ -876,6 +876,20 @@ describe("texture_mask_asset_not_found", () => {
 });
 
 describe("multiple_root_compositions", () => {
+  it("scopes lint to an explicit render composition entry", async () => {
+    const project = makeProject(validHtml());
+    const standalone = join(project, "standalone.html");
+    writeFileSync(standalone, validHtml("standalone"));
+
+    const { totalErrors, results } = await lintProject(project, standalone);
+
+    expect(totalErrors).toBe(0);
+    expect(results.map((result) => result.file)).toEqual(["standalone.html"]);
+    expect(
+      results[0]?.result.findings.find((finding) => finding.code === "multiple_root_compositions"),
+    ).toBeUndefined();
+  });
+
   it("fires when two HTML files have data-composition-id", async () => {
     const project = makeProject(validHtml());
     writeFileSync(

packages/lint/src/project.ts

@@ -180,8 +180,13 @@ function resolveCssAssetCandidates(
   return resolveLocalAssetCandidates(projectDir, url);
 }
 
-export async function lintProject(projectDir: string): Promise<ProjectLintResult> {
-  const indexPath = resolve(projectDir, "index.html");
+export async function lintProject(
+  projectDir: string,
+  entryFile?: string,
+): Promise<ProjectLintResult> {
+  const indexPath = entryFile ? resolve(entryFile) : resolve(projectDir, "index.html");
+  const rootFile = relative(resolve(projectDir), indexPath).replace(/\\/g, "/") || "index.html";
+  const rootCompSrcPath = rootFile === "index.html" ? undefined : rootFile;
   const results: Array<{ file: string; result: HyperframeLintResult }> = [];
   let totalErrors = 0;
   let totalWarnings = 0;
@@ -190,16 +195,16 @@ export async function lintProject(projectDir: string): Promise<ProjectLintResult
   const rootHtml = readFileSync(indexPath, "utf-8");
   const rootResult = await lintHyperframeHtml(rootHtml, {
     filePath: indexPath,
-    externalStyles: collectExternalStyles(projectDir, rootHtml),
+    externalStyles: collectExternalStyles(projectDir, rootHtml, rootCompSrcPath),
   });
-  results.push({ file: "index.html", result: rootResult });
+  results.push({ file: rootFile, result: rootResult });
   totalErrors += rootResult.errorCount;
   totalWarnings += rootResult.warningCount;
   totalInfos += rootResult.infoCount;
 
-  const allHtmlSources: HtmlSource[] = [{ html: rootHtml }];
+  const allHtmlSources: HtmlSource[] = [{ html: rootHtml, compSrcPath: rootCompSrcPath }];
   const compositionsDir = resolve(projectDir, "compositions");
-  if (existsSync(compositionsDir)) {
+  if (!entryFile && existsSync(compositionsDir)) {
     const collectHtmlFiles = (dir: string, rel: string): string[] => {
       const out: string[] = [];
       for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -239,7 +244,7 @@ export async function lintProject(projectDir: string): Promise<ProjectLintResult
     ...lintAudioSrcNotFound(projectDir, allHtmlSources),
     ...lintMissingLocalAsset(projectDir, allHtmlSources),
     ...lintTextureMaskAssetNotFound(projectDir, allHtmlSources),
-    ...lintMultipleRootCompositions(projectDir),
+    ...(!entryFile ? lintMultipleRootCompositions(projectDir) : []),
     ...lintDuplicateAudioTracks(allHtmlSources),
     ...lintMissingOrEmptySubComposition(projectDir, rootHtml),
   ];