tabsmith-lint 0.1.0

package/dist/parse/extract-api-calls.js

@@ -0,0 +1,189 @@
+import { walk } from "./parse-script.js";
+const ROOTS = new Set(["chrome", "browser"]);
+const GLOBALS = new Set(["globalThis", "window", "self"]);
+const SENSITIVE_PROPS = new Set(["url", "pendingUrl", "title", "favIconUrl"]);
+// Match identifiers that name a tab: `tab`, `tabs`, `activeTab`, `currentTab`,
+// `tabs[0]` (via recursion) — but NOT `table`, `stable`, `dataTable`, `crontab`.
+// Requires `tab`/`tabs` as a trailing word or camelCase segment.
+const TAB_NAME = /(?:^|[^a-zA-Z])[Tt]abs?$|[a-z][Tt]abs?$/;
+// The chrome.tabs.onUpdated callback's changeInfo carries `url`/`title` only when
+// `tabs` is granted, but its param is conventionally named changeInfo/changes
+// (not tab-like). A sensitive read off these names is a real Tab read. (Reads of
+// non-sensitive props like `info.status` never reach this check.)
+const TAB_CONTEXT = new Set(["changeInfo", "changes"]);
+const MEMBER = new Set(["MemberExpression", "OptionalMemberExpression"]);
+function flatten(node) {
+    const accesses = [];
+    let cur = node;
+    while (cur && MEMBER.has(cur.type)) {
+        accesses.unshift({ computed: cur.computed, property: cur.property });
+        cur = cur.object;
+    }
+    return { base: cur, accesses };
+}
+/** Resolve a member chain to a chrome/browser path, or null if not rooted there. */
+function resolveChain(node, aliases) {
+    const { base, accesses } = flatten(node);
+    if (!base || base.type !== "Identifier")
+        return null;
+    let root;
+    const path = [];
+    if (ROOTS.has(base.name)) {
+        root = base.name;
+    }
+    else if (aliases.has(base.name)) {
+        const a = aliases.get(base.name);
+        root = a.root;
+        path.push(...a.path);
+    }
+    else if (GLOBALS.has(base.name) &&
+        accesses[0] &&
+        !accesses[0].computed &&
+        accesses[0].property?.type === "Identifier" &&
+        ROOTS.has(accesses[0].property.name)) {
+        root = accesses.shift().property.name;
+    }
+    else {
+        return null;
+    }
+    for (const acc of accesses) {
+        const p = acc.property;
+        if (acc.computed) {
+            if (p?.type === "StringLiteral")
+                path.push(p.value);
+            else
+                return { root, path, dynamic: true };
+        }
+        else if (p?.type === "Identifier") {
+            path.push(p.name);
+        }
+        else if (p?.type === "StringLiteral") {
+            path.push(p.value);
+        }
+        else {
+            return { root, path, dynamic: true };
+        }
+    }
+    return { root, path, dynamic: false };
+}
+/** Static-only resolution used while building the alias table (no alias lookup). */
+function resolveStatic(node) {
+    if (!node)
+        return null;
+    if (node.type === "Identifier" && ROOTS.has(node.name)) {
+        return { root: node.name, path: [] };
+    }
+    if (MEMBER.has(node.type)) {
+        const r = resolveChain(node, new Map());
+        if (r && !r.dynamic)
+            return { root: r.root, path: r.path };
+    }
+    // Cross-browser polyfill idioms: `chrome || browser`, `browser ?? chrome`,
+    // `typeof browser !== 'undefined' ? browser : chrome`. Alias resolves to
+    // whichever side is a chrome/browser root.
+    if (node.type === "LogicalExpression") {
+        return resolveStatic(node.left) ?? resolveStatic(node.right);
+    }
+    if (node.type === "ConditionalExpression") {
+        return resolveStatic(node.consequent) ?? resolveStatic(node.alternate);
+    }
+    return null;
+}
+function buildAliases(ast) {
+    const map = new Map();
+    walk(ast, (node) => {
+        if (node.type !== "VariableDeclarator" || !node.init)
+            return;
+        const base = resolveStatic(node.init);
+        if (!base)
+            return;
+        if (node.id?.type === "Identifier") {
+            map.set(node.id.name, { root: base.root, path: base.path });
+        }
+        else if (node.id?.type === "ObjectPattern") {
+            for (const prop of node.id.properties) {
+                if (prop.type === "ObjectProperty" &&
+                    prop.key?.type === "Identifier" &&
+                    prop.value?.type === "Identifier") {
+                    map.set(prop.value.name, { root: base.root, path: [...base.path, prop.key.name] });
+                }
+            }
+        }
+    });
+    return map;
+}
+function walkParent(node, parent, visit) {
+    if (!node || typeof node !== "object")
+        return;
+    if (typeof node.type === "string")
+        visit(node, parent);
+    for (const key of Object.keys(node)) {
+        if (key === "loc")
+            continue;
+        const child = node[key];
+        if (Array.isArray(child))
+            child.forEach((c) => walkParent(c, node, visit));
+        else if (child && typeof child === "object" && typeof child.type === "string")
+            walkParent(child, node, visit);
+    }
+}
+function isTabish(obj) {
+    if (!obj)
+        return false;
+    if (obj.type === "Identifier")
+        return TAB_NAME.test(obj.name) || TAB_CONTEXT.has(obj.name);
+    if (MEMBER.has(obj.type))
+        return isTabish(obj.object);
+    return false;
+}
+function isAbsoluteUrlArg(arg) {
+    return arg?.type === "StringLiteral" && /^https?:\/\//i.test(arg.value);
+}
+export function extractFromScripts(scripts) {
+    const apiCalls = [];
+    const sensitiveTabReads = [];
+    const dynamicApiAccess = [];
+    const hostAccessSignals = [];
+    for (const script of scripts) {
+        if (!script.ast || script.parseError)
+            continue;
+        const file = script.relPath;
+        const aliases = buildAliases(script.ast);
+        walkParent(script.ast, null, (node, parent) => {
+            if (MEMBER.has(node.type)) {
+                const line = node.loc?.start.line;
+                // Sensitive tab property read — can appear ANYWHERE in a chain, e.g.
+                // `tab.url.startsWith(...)`, so check every member node, not just the top.
+                if (!node.computed && node.property?.type === "Identifier" && SENSITIVE_PROPS.has(node.property.name) && isTabish(node.object)) {
+                    sensitiveTabReads.push({ property: node.property.name, file, line });
+                }
+                // chrome/browser chain resolution only at the top of a chain (the top
+                // member carries the whole expression; resolving inner ones double-counts).
+                const isTop = !(parent && MEMBER.has(parent.type) && parent.object === node);
+                if (isTop) {
+                    const r = resolveChain(node, aliases);
+                    if (r) {
+                        if (r.dynamic) {
+                            dynamicApiAccess.push({ root: r.root, file, line });
+                        }
+                        else if (r.path.length >= 1) {
+                            apiCalls.push({ root: r.root, namespace: r.path[0], path: r.path, file, line, column: node.loc?.start.column, confidence: "high" });
+                        }
+                    }
+                }
+                return;
+            }
+            // Cross-origin fetch
+            if (node.type === "CallExpression" && node.callee?.type === "Identifier" && node.callee.name === "fetch") {
+                if (isAbsoluteUrlArg(node.arguments?.[0])) {
+                    hostAccessSignals.push({ kind: "fetch", file, line: node.loc?.start.line });
+                }
+            }
+            // XMLHttpRequest construction
+            if (node.type === "NewExpression" && node.callee?.type === "Identifier" && node.callee.name === "XMLHttpRequest") {
+                hostAccessSignals.push({ kind: "xhr", file, line: node.loc?.start.line });
+            }
+        });
+    }
+    return { apiCalls, sensitiveTabReads, dynamicApiAccess, hostAccessSignals };
+}

package/dist/parse/parse-script.js

@@ -0,0 +1,50 @@
+import { parse } from "@babel/parser";
+// ponytail: @babel/parser is the committed parser. oxc-parser was the planned
+// primary but is a native binding with a churny API, and its only v0.1 edge
+// (perf on large/minified files) is explicitly out of scope. The parseScript()
+// seam below is the single point where oxc could later slot in.
+function pluginsFor(relPath) {
+    const lower = relPath.toLowerCase();
+    if (lower.endsWith(".tsx"))
+        return ["typescript", "jsx"];
+    if (lower.endsWith(".ts"))
+        return ["typescript"];
+    return ["jsx"]; // .js/.mjs/.cjs/.jsx
+}
+/** Parse one file behind the seam. Never throws — a parse failure yields a
+ *  ScriptFile with ast=null and parseError=true so other files still process. */
+export function parseScript(file) {
+    try {
+        const ast = parse(file.content, {
+            sourceType: "unambiguous",
+            allowReturnOutsideFunction: true,
+            allowAwaitOutsideFunction: true,
+            errorRecovery: true,
+            plugins: pluginsFor(file.relPath),
+        });
+        return { ...file, ast, parseError: false };
+    }
+    catch {
+        return { ...file, ast: null, parseError: true };
+    }
+}
+/** Depth-first walk over a babel AST. Calls visitor(node) for every node that
+ *  carries a string `type`. Lazy generic traversal — no @babel/traverse, no scope. */
+export function walk(node, visitor) {
+    if (!node || typeof node !== "object")
+        return;
+    if (typeof node.type === "string")
+        visitor(node);
+    for (const key of Object.keys(node)) {
+        if (key === "loc" || key === "leadingComments" || key === "trailingComments")
+            continue;
+        const child = node[key];
+        if (Array.isArray(child)) {
+            for (const c of child)
+                walk(c, visitor);
+        }
+        else if (child && typeof child === "object" && typeof child.type === "string") {
+            walk(child, visitor);
+        }
+    }
+}

package/dist/reporters/human.js

@@ -0,0 +1,73 @@
+import { SEVERITY_ORDER } from "../engine/verdict.js";
+// Optional interest-signal line, shown once after a human-mode run (suppressed in
+// JSON and under --min-severity reject). Off by default in v0.1 — enable only when
+// WAITLIST_URL points to a real page. Behind a constant so it's easy to toggle.
+export const SHOW_DEMAND_LINE = false;
+export const WAITLIST_URL = "https://tabsmith-lint.dev/monitor-waitlist";
+const VERDICT_HEADER = {
+    pass: "PASS",
+    needs_fixes: "NEEDS FIXES",
+    high_rejection_risk: "HIGH REJECTION RISK",
+};
+const VERDICT_WORDS = {
+    pass: "pass",
+    needs_fixes: "needs fixes",
+    high_rejection_risk: "high rejection risk",
+};
+export function renderHuman(report, minSeverity = "info") {
+    const chrome = report.browsers.chrome;
+    const lines = [];
+    lines.push(`tabsmith-lint v${report.version} analyzing ${report.inputPath}`);
+    const mv = report.manifestVersion !== undefined ? `Manifest V${report.manifestVersion}` : "Manifest version unknown";
+    lines.push(`${mv}, ${chrome.stats.filesScanned} files scanned, ${chrome.stats.scriptsParsed} scripts parsed`);
+    lines.push("");
+    lines.push(`CHROME: ${VERDICT_HEADER[chrome.verdict]}`);
+    lines.push("");
+    if (chrome.findings.length === 0) {
+        lines.push("No findings.");
+    }
+    else {
+        for (const severity of SEVERITY_ORDER) {
+            for (const f of chrome.findings.filter((x) => x.severity === severity)) {
+                lines.push(...renderFinding(f));
+                lines.push("");
+            }
+        }
+    }
+    lines.push(`Verdict: ${VERDICT_WORDS[chrome.verdict]} (${countLabel(chrome.findings)})`);
+    if (SHOW_DEMAND_LINE && minSeverity !== "reject") {
+        lines.push("");
+        lines.push(`Want alerts if your published extension is removed or its review status changes? → ${WAITLIST_URL}`);
+    }
+    return lines.join("\n");
+}
+function renderFinding(f) {
+    const out = [];
+    const violation = f.chromeViolationId ? ` (${f.chromeViolationId})` : "";
+    out.push(`[${f.severity}] ${f.ruleId} ${f.title}${violation}`);
+    if (f.file) {
+        let loc = f.file;
+        if (f.line !== undefined)
+            loc += `:${f.line}`;
+        if (f.column !== undefined)
+            loc += `:${f.column}`;
+        out.push(`  ${loc}`);
+    }
+    out.push(`  ${f.message}`);
+    if (f.fixHint)
+        out.push(`  Fix: ${f.fixHint}`);
+    return out;
+}
+function countLabel(findings) {
+    const counts = { reject: 0, fix: 0, info: 0 };
+    for (const f of findings)
+        counts[f.severity]++;
+    const parts = [];
+    if (counts.reject)
+        parts.push(`${counts.reject} reject`);
+    if (counts.fix)
+        parts.push(`${counts.fix} fix`);
+    if (counts.info)
+        parts.push(`${counts.info} info`);
+    return parts.length ? parts.join(", ") : "no findings";
+}

package/dist/reporters/json.js

@@ -0,0 +1,3 @@
+export function renderJson(report) {
+    return JSON.stringify(report, null, 2);
+}

package/dist/rules/files.js

@@ -0,0 +1,71 @@
+import { existsSync, statSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { findLine } from "../engine/source-lines.js";
+import { isWithinRoot, refToRelPath } from "../engine/file-discovery.js";
+// FUNC001 (missing file → reject) + FUNC002 (case-only mismatch → fix).
+//
+// We compare the manifest reference against actual readdir() entry names with
+// case-sensitive string equality, rather than relying on existsSync(). This is
+// deliberate: on a case-insensitive filesystem (macOS APFS default) existsSync
+// would resolve "Popup.html" to "popup.html" and silently hide the mismatch
+// that Chrome's case-sensitive packaging would reject.
+function fileRefs(model) {
+    const findings = [];
+    for (const ref of model.manifestRefs) {
+        // A reference that escapes the package root is invalid packaging — treat it
+        // as missing rather than statting an out-of-package path.
+        if (!isWithinRoot(model.rootDir, ref.ref)) {
+            findings.push({
+                ruleId: "FUNC001",
+                severity: "reject",
+                confidence: "high",
+                title: `Manifest reference points outside the package: "${ref.ref}"`,
+                message: `"${ref.ref}" (${ref.source}) resolves outside the extension directory and cannot be packaged.`,
+                file: "manifest.json",
+                line: findLine(model.manifestRaw, ref.ref),
+                chromeViolationId: "Yellow Magnesium",
+                fixHint: `Use a path inside the extension package for "${ref.source}".`,
+            });
+            continue;
+        }
+        const parts = refToRelPath(ref.ref).split("/").filter(Boolean);
+        const base = parts.pop();
+        const parentAbs = join(model.rootDir, ...parts);
+        let entries = [];
+        if (existsSync(parentAbs) && statSync(parentAbs).isDirectory()) {
+            entries = readdirSync(parentAbs, { withFileTypes: true });
+        }
+        const exact = entries.find((e) => e.name === base);
+        if (exact?.isFile())
+            continue;
+        const caseMatch = entries.find((e) => e.name.toLowerCase() === base.toLowerCase())?.name;
+        const line = findLine(model.manifestRaw, ref.ref);
+        if (caseMatch) {
+            findings.push({
+                ruleId: "FUNC002",
+                severity: "fix",
+                confidence: "high",
+                title: `Case-sensitivity mismatch for "${ref.ref}"`,
+                message: `Manifest references "${ref.ref}" (${ref.source}) but the file on disk is "${caseMatch}". Chrome Web Store packaging is case-sensitive.`,
+                file: "manifest.json",
+                line,
+                fixHint: `Rename the file or update the manifest path to match exact case.`,
+            });
+        }
+        else {
+            findings.push({
+                ruleId: "FUNC001",
+                severity: "reject",
+                confidence: "high",
+                title: `Manifest-referenced file is missing: "${ref.ref}"`,
+                message: `"${ref.ref}" (${ref.source}) is referenced by the manifest but does not exist in the package.`,
+                file: "manifest.json",
+                line,
+                chromeViolationId: "Yellow Magnesium",
+                fixHint: `Add the missing file or remove the "${ref.source}" reference.`,
+            });
+        }
+    }
+    return findings;
+}
+export const fileRules = [fileRefs];

package/dist/rules/index.js

@@ -0,0 +1,10 @@
+import { SEVERITY_RANK } from "../engine/verdict.js";
+import { permissionRules } from "./permissions.js";
+import { mv3Rules } from "./mv3.js";
+import { fileRules } from "./files.js";
+export const allRules = [...permissionRules, ...mv3Rules, ...fileRules];
+/** Run every rule and return all findings, ordered reject → fix → info. */
+export function runRules(model) {
+    const findings = allRules.flatMap((rule) => rule(model));
+    return findings.sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]);
+}

package/dist/rules/mv3.js

@@ -0,0 +1,121 @@
+import { walk } from "../parse/parse-script.js";
+import { findLineByIndex } from "../engine/source-lines.js";
+// MV3002 (string execution: eval/new Function/string timers) ships at `fix`, not
+// `reject`, in v0.1. The pattern is a real MV3 CSP concern, but static analysis
+// cannot tell whether the call is reachable or runs in a sandboxed context — and
+// it commonly appears in bundled libraries (LESS/CSS compilers, JSON-parse
+// fallbacks) of extensions that are published and working. Flagging those as
+// "high rejection risk" cries wolf and erodes trust. Surface it to verify, don't
+// condemn. Single constant so it can be promoted once context analysis exists.
+// (MV3001 remote code and MV3003 manifest_version 2 stay `reject` — deterministic.)
+export const MV3002_SEVERITY = "fix";
+const REMOTE_SCRIPT_RE = /<script[^>]*\bsrc\s*=\s*["']((?:https?:)?\/\/[^"']+)["']/gi;
+/** MV3001 — remotely hosted code (HTML remote <script src>, remote import/import()). */
+function mv3001(model) {
+    const findings = [];
+    for (const html of model.htmlFiles) {
+        let m;
+        REMOTE_SCRIPT_RE.lastIndex = 0;
+        while ((m = REMOTE_SCRIPT_RE.exec(html.content)) !== null) {
+            findings.push({
+                ruleId: "MV3001",
+                severity: "reject",
+                confidence: "high",
+                title: "Remotely hosted code referenced",
+                message: `<script src="${m[1]}"> loads code from a remote URL, which Manifest V3 forbids.`,
+                file: html.relPath,
+                line: findLineByIndex(html.content, m.index),
+                chromeViolationId: "Blue Argon",
+                fixHint: "Bundle the script inside the extension package instead of loading it remotely.",
+            });
+        }
+    }
+    for (const script of model.scriptFiles) {
+        if (!script.ast)
+            continue;
+        walk(script.ast, (node) => {
+            // static import of a remote URL
+            if (node.type === "ImportDeclaration" && isRemote(node.source?.value)) {
+                findings.push(remoteImport(script.relPath, node, node.source.value));
+            }
+            // dynamic import() of a remote URL
+            if (node.type === "CallExpression" && node.callee?.type === "Import" && isRemote(node.arguments?.[0]?.value)) {
+                findings.push(remoteImport(script.relPath, node, node.arguments[0].value));
+            }
+        });
+    }
+    return findings;
+}
+function isRemote(v) {
+    return typeof v === "string" && /^(https?:)?\/\//i.test(v);
+}
+function remoteImport(file, node, url) {
+    return {
+        ruleId: "MV3001",
+        severity: "reject",
+        confidence: "high",
+        title: "Remotely hosted code referenced",
+        message: `import of "${url}" loads code from a remote URL, which Manifest V3 forbids.`,
+        file,
+        line: node.loc?.start.line,
+        chromeViolationId: "Blue Argon",
+        fixHint: "Bundle the dependency inside the extension package instead of importing it remotely.",
+    };
+}
+const STRING_TIMERS = new Set(["setTimeout", "setInterval"]);
+/** MV3002 — string execution (eval, new Function, string-form timers). */
+function mv3002(model) {
+    const findings = [];
+    for (const script of model.scriptFiles) {
+        if (!script.ast)
+            continue;
+        walk(script.ast, (node) => {
+            let what = null;
+            if (node.type === "CallExpression" && node.callee?.type === "Identifier" && node.callee.name === "eval") {
+                what = "eval()";
+            }
+            else if (node.type === "NewExpression" && node.callee?.type === "Identifier" && node.callee.name === "Function") {
+                what = "new Function()";
+            }
+            else if (node.type === "CallExpression" &&
+                node.callee?.type === "Identifier" &&
+                STRING_TIMERS.has(node.callee.name) &&
+                isStringArg(node.arguments?.[0])) {
+                what = `${node.callee.name}("...")`;
+            }
+            if (what) {
+                findings.push({
+                    ruleId: "MV3002",
+                    severity: MV3002_SEVERITY,
+                    confidence: "medium",
+                    title: `String execution via ${what}`,
+                    message: `${what} executes a string as code. Manifest V3's CSP blocks this in extension contexts unless it runs in a sandboxed page or is unreachable. Verify whether this code path actually runs.`,
+                    file: script.relPath,
+                    line: node.loc?.start.line,
+                    column: node.loc?.start.column,
+                    chromeViolationId: "Blue Argon",
+                    fixHint: "Replace string execution with a real function, or confine it to a sandboxed page if it must remain.",
+                });
+            }
+        });
+    }
+    return findings;
+}
+function isStringArg(arg) {
+    return arg?.type === "StringLiteral" || arg?.type === "TemplateLiteral";
+}
+/** MV3003 — Manifest V2. */
+function mv3003(model) {
+    if (model.manifest.manifest_version !== 2)
+        return [];
+    return [{
+            ruleId: "MV3003",
+            severity: "reject",
+            confidence: "high",
+            title: "Manifest V2 is no longer accepted",
+            message: "manifest_version is 2. Chrome Web Store requires Manifest V3.",
+            file: "manifest.json",
+            fixHint: "Migrate the extension to Manifest V3.",
+        }];
+}
+export const mv3Rules = [mv3001, mv3002, mv3003];