tabsmith-lint 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rsub122
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# tabsmith-lint
+
+A pre-submission compliance linter for browser extensions. v0.1 analyzes an unpacked
+Manifest V3 Chrome extension directory and reports likely Chrome Web Store rejection
+risks **before** you submit — unused/excessive permissions, missing permissions, MV3
+violations, and broken file references — with a clear verdict and actionable fixes.
+
+**Catch the "Purple Potassium" permission rejection before you submit.** The most
+common Chrome Web Store rejection is excessive/unused permissions — declaring `tabs`,
+`bookmarks`, `cookies`, or `<all_urls>` your code never actually uses. tabsmith-lint
+statically checks your manifest against your code and maps findings to the violations
+Chrome reviewers flag:
+
+| Violation ID | What it means | tabsmith rules |
+|---|---|---|
+| Purple Potassium | Excessive / unused permissions | PERM001, PERM003, PERM004, PERM005 |
+| Blue Argon | Remotely hosted code / string execution | MV3001, MV3002 |
+| Yellow Magnesium | Functionality / broken packaging | FUNC001, FUNC002 |
+
+```bash
+npx tabsmith-lint ./my-extension
+npx tabsmith-lint ./my-extension --format json
+npx tabsmith-lint ./my-extension --min-severity reject
+```
+
+Exit codes: `0` pass · `1` needs fixes · `2` high rejection risk · `3` tool error.
+
+> **Status:** the package is publish-ready (verified via `npm pack` + a real install)
+> but **not yet on npm**, so `npx tabsmith-lint` resolves only after the first
+> `npm publish`. Until then, run it from a clone: `npm install && npm run build &&
+> node dist/cli.js ./my-extension`.
+
+## Develop
+
+```bash
+npm install
+npm test      # vitest: unit + e2e (one fixture per rule)
+npm run build # tsc → dist/
+node dist/cli.js ./my-extension
+```
+
+## Validate against real extensions
+
+Beyond the unit/e2e fixtures, the linter is validated on **real** extensions —
+both Google's clean MV3 samples and real published, **built/minified** OSS
+extensions (uBlock Origin, Dark Reader, Stylus, ...). All fetched on demand — see
+`corpus/`:
+
+```bash
+npm run build               # required first — the scripts use dist/
+npm run validate            # robustness: ~100 clean extensions, gate on 0 crashes
+npm run score               # accuracy: PERM001 false-positive rate vs ground truth
+npm run validate:releases   # robustness on real minified extensions
+npm run score:releases      # accuracy on the messy corpus
+npm run demo                # print reports for recognizable real extensions
+```
+
+`npm run score` gates promoting PERM001 to `reject`: under 5% false positives.
+Across **28 hand-labeled extensions (22 samples + 6 minified releases): 0% false
+positives, 0 false negatives, all verdicts matched** — independently audited.
+Building this corpus caught and fixed **six** real false positives (plus a
+prototype-safety crash) the synthetic fixtures missed — see `corpus/README.md`. CI
+runs the suite and all validation gates on every push (`.github/workflows/ci.yml`).
+
+## PERM001 accuracy gate
+
+PERM001 (declared-but-unused permission) is the flagship rule, and its
+false-positive rate is make-or-break — a wrong "remove this permission" suggestion
+destroys trust. In v0.1 it ships at **`fix` severity, never `reject`** (the single
+constant `PERM001_SEVERITY` in `src/rules/permissions.ts`). Promoting it to `reject`
+is gated on validating under 5% false positives against a hand-labeled corpus of
+20–30 real extensions, where the label is "permission actually used by
+implementation" — not "extension passed review". That corpus is deferred; until it
+exists, leave the severity at `fix`.
+
+## Status
+
+v0.1. Chrome-only, directory input, 10 rules (PERM001-005, MV3001-003, FUNC001-002).
+
+Firefox/Edge, ZIP/CRX input, SARIF, and a GitHub Action are on the roadmap.
+
+Two rules are intentionally conservative in v0.1 (trust is the product): **PERM001**
+(unused permission) and **MV3002** (string execution: `eval`/`new Function`) both ship
+at `fix` severity, not `reject` — a static linter can't always tell a real problem from
+a sandboxed or unreachable one, so they surface for you to verify rather than condemn.
+Each is gated behind a single severity constant for later promotion.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/cli.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { analyze } from "./engine/analyze.js";
+import { ManifestError } from "./engine/manifest.js";
+import { verdictExitCode } from "./engine/verdict.js";
+import { renderHuman } from "./reporters/human.js";
+import { renderJson } from "./reporters/json.js";
+const USAGE = "Usage: tabsmith-lint <extension-dir> [--format human|json] [--browser chrome] [--min-severity reject|fix|info]";
+function version() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        return JSON.parse(readFileSync(join(here, "../package.json"), "utf8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function helpText() {
+    return `tabsmith-lint v${version()} - pre-submission compliance linter for Manifest V3 Chrome extensions
+
+Point it at an unpacked extension directory and it flags likely Chrome Web Store
+rejection risks before you submit:
+  - unused / excessive permissions (the "Purple Potassium" rejection)
+  - Manifest V3 violations: remotely hosted code, string execution, Manifest V2
+  - broken packaging: missing or wrong-case file references
+
+${USAGE}
+
+Options:
+  --format human|json              output format (default: human)
+  --browser chrome                 target browser (only chrome in v0.1)
+  --min-severity reject|fix|info   minimum severity to report (default: info)
+  -v, --version                    print version
+  -h, --help                       show this help
+
+Exit codes: 0 pass | 1 needs fixes | 2 high rejection risk | 3 tool error
+Docs: https://github.com/rsub122/tabsmith-lint`;
+}
+export function run(argv) {
+    let dir;
+    let format = "human";
+    let browser = "chrome";
+    let minSeverity = "info";
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--format")
+            format = argv[++i];
+        else if (arg === "--browser")
+            browser = argv[++i];
+        else if (arg === "--min-severity")
+            minSeverity = argv[++i];
+        else if (arg === "-h" || arg === "--help")
+            return { exitCode: 0, stdout: helpText() };
+        else if (arg === "-v" || arg === "--version")
+            return { exitCode: 0, stdout: version() };
+        else if (arg.startsWith("--"))
+            return { exitCode: 3, stderr: `Unknown option: ${arg}\n${USAGE}` };
+        else if (dir === undefined)
+            dir = arg;
+        else
+            return { exitCode: 3, stderr: `Unexpected argument: ${arg}\n${USAGE}` };
+    }
+    if (!dir)
+        return { exitCode: 3, stderr: `No extension directory provided.\n${USAGE}` };
+    if (browser !== "chrome")
+        return { exitCode: 3, stderr: `Only --browser chrome is supported in v0.1 (got "${browser}").` };
+    if (!["human", "json"].includes(format))
+        return { exitCode: 3, stderr: `Invalid --format "${format}" (expected human|json).` };
+    if (!["reject", "fix", "info"].includes(minSeverity))
+        return { exitCode: 3, stderr: `Invalid --min-severity "${minSeverity}" (expected reject|fix|info).` };
+    let report;
+    try {
+        report = analyze(dir, { version: version(), minSeverity });
+    }
+    catch (e) {
+        const msg = e instanceof ManifestError ? e.message : e.message;
+        return { exitCode: 3, stderr: `error: ${msg}` };
+    }
+    const stdout = format === "json" ? renderJson(report) : renderHuman(report, minSeverity);
+    return { exitCode: verdictExitCode(report.browsers.chrome.verdict), stdout };
+}
+// Run as a CLI only when invoked directly (not when imported by tests). npm/npx
+// install the bin as a SYMLINK (node_modules/.bin/tabsmith-lint -> dist/cli.js),
+// so process.argv[1] is the symlink path while import.meta.url is the real file —
+// compare realpaths, or the published binary silently does nothing.
+let invokedDirectly = false;
+try {
+    invokedDirectly = !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    invokedDirectly = false;
+}
+if (invokedDirectly) {
+    const result = run(process.argv.slice(2));
+    if (result.stdout)
+        console.log(result.stdout);
+    if (result.stderr)
+        console.error(result.stderr);
+    process.exit(result.exitCode);
+}

package/dist/data/chrome-permission-map.js

@@ -0,0 +1,54 @@
+// High-frequency Chrome permission → API namespace map (PRD 6.6). Not exhaustive
+// by design; unknown permissions are simply not mapped (no false unused finding).
+// Null-prototype throughout: namespace/permission keys come from parsed code, so
+// a lookup like map["constructor"] must not resolve to an inherited Object member.
+export const chromePermissionMap = Object.assign(Object.create(null), {
+    storage: { namespace: "storage" },
+    scripting: { namespace: "scripting" },
+    cookies: { namespace: "cookies", requiresHostPermission: true },
+    bookmarks: { namespace: "bookmarks" },
+    alarms: { namespace: "alarms" },
+    notifications: { namespace: "notifications" },
+    contextMenus: { namespace: "contextMenus" },
+    webRequest: { namespace: "webRequest", requiresHostPermission: true },
+    declarativeNetRequest: { namespace: "declarativeNetRequest" },
+    downloads: { namespace: "downloads" },
+    history: { namespace: "history" },
+    identity: { namespace: "identity" },
+    management: { namespace: "management" },
+    tabs: { special: "sensitiveTabProperties" },
+    activeTab: { special: "temporaryHostAccess" },
+});
+/** namespace → permission required to use it (PERM002). Only namespaces whose
+ *  use genuinely requires a permission. `tabs` is intentionally excluded: the
+ *  tabs namespace methods don't require the `tabs` permission (PRD §5 PERM002). */
+export const namespaceToPermission = (() => {
+    const out = Object.create(null);
+    for (const [perm, mapping] of Object.entries(chromePermissionMap)) {
+        if (mapping.namespace)
+            out[mapping.namespace] = perm;
+    }
+    return out;
+})();
+/** Some namespaces are granted by more than one permission string. Declaring
+ *  ANY of these satisfies PERM002 for that namespace. (Real extensions commonly
+ *  use declarativeNetRequestWithHostAccess instead of the base permission.) */
+export const namespacePermissionAliases = Object.assign(Object.create(null), {
+    declarativeNetRequest: [
+        "declarativeNetRequest",
+        "declarativeNetRequestWithHostAccess",
+        "declarativeNetRequestFeedback",
+    ],
+});
+/** All permission strings that satisfy a namespace's PERM002 requirement. */
+export function permissionsForNamespace(namespace) {
+    if (namespacePermissionAliases[namespace])
+        return namespacePermissionAliases[namespace];
+    const p = namespaceToPermission[namespace];
+    return p ? [p] : [];
+}
+/** Broad host match patterns that trigger PERM003/004/005. */
+export const BROAD_HOST_PATTERNS = ["<all_urls>", "*://*/*", "http://*/*", "https://*/*"];
+export function isBroadHost(pattern) {
+    return BROAD_HOST_PATTERNS.includes(pattern);
+}

package/dist/engine/analyze.js

@@ -0,0 +1,87 @@
+import { loadManifest } from "./manifest.js";
+import { discoverFiles, isScript, isHtml } from "./file-discovery.js";
+import { collectManifestRefs } from "./manifest-refs.js";
+import { parseScript } from "../parse/parse-script.js";
+import { extractFromScripts } from "../parse/extract-api-calls.js";
+import { runRules } from "../rules/index.js";
+import { computeVerdict, filterByMinSeverity } from "./verdict.js";
+/** Pure-ish engine entry point: directory in → LintReport out. Only manifest
+ *  loading and file discovery touch the filesystem. Throws ManifestError (→ CLI
+ *  exit 3) when the manifest is missing or invalid. */
+export function analyze(rootDir, options) {
+    const { manifest, raw } = loadManifest(rootDir);
+    const manifestRefs = collectManifestRefs(manifest);
+    const files = discoverFiles(rootDir, manifestRefs);
+    const htmlFiles = files.filter((f) => isHtml(f.relPath));
+    const scriptFiles = files.filter((f) => isScript(f.relPath)).map(parseScript);
+    const extraction = extractFromScripts(scriptFiles);
+    const hostAccessSignals = [
+        ...extraction.hostAccessSignals,
+        ...deriveHostSignals(extraction.apiCalls),
+        ...(manifest.content_scripts?.length ? [{ kind: "contentScript", file: "manifest.json" }] : []),
+    ];
+    const model = {
+        rootDir,
+        manifest,
+        manifestRaw: raw,
+        files,
+        scriptFiles,
+        htmlFiles,
+        apiCalls: extraction.apiCalls,
+        sensitiveTabReads: extraction.sensitiveTabReads,
+        dynamicApiAccess: extraction.dynamicApiAccess,
+        hostAccessSignals,
+        manifestRefs: manifestRefs.all,
+    };
+    const ruleFindings = runRules(model);
+    const parseFindings = scriptFiles
+        .filter((s) => s.parseError)
+        .map((s) => ({
+        ruleId: "PARSE",
+        severity: "info",
+        confidence: "low",
+        title: "File could not be parsed",
+        message: `${s.relPath} failed to parse; its API usage was not analyzed. Findings for code in this file may be incomplete.`,
+        file: s.relPath,
+    }));
+    const allFindings = [...ruleFindings, ...parseFindings];
+    // --min-severity is a threshold, not just a display filter: it gates both the
+    // reported findings AND the verdict/exit code. This mirrors eslint --quiet
+    // (suppressing warnings makes a warning-only run exit 0). So `--min-severity
+    // reject` on a fix-only extension yields `pass`/exit 0 by design — the caller
+    // opted out of caring about fix-level findings.
+    const findings = filterByMinSeverity(allFindings, options.minSeverity ?? "info");
+    const verdict = computeVerdict(findings);
+    const scriptsParsed = scriptFiles.filter((s) => !s.parseError).length;
+    return {
+        tool: "tabsmith-lint",
+        version: options.version,
+        inputPath: rootDir,
+        manifestVersion: manifest.manifest_version,
+        browsers: {
+            chrome: {
+                verdict,
+                findings,
+                stats: {
+                    filesScanned: files.length,
+                    scriptsParsed,
+                    parseErrors: scriptFiles.length - scriptsParsed,
+                },
+            },
+        },
+    };
+}
+function deriveHostSignals(apiCalls) {
+    const out = [];
+    for (const c of apiCalls) {
+        if (c.namespace === "cookies")
+            out.push({ kind: "cookies", file: c.file, line: c.line });
+        else if (c.namespace === "webRequest")
+            out.push({ kind: "webRequest", file: c.file, line: c.line });
+        else if (c.namespace === "declarativeNetRequest")
+            out.push({ kind: "declarativeNetRequest", file: c.file, line: c.line });
+        else if (c.namespace === "scripting" && c.path.includes("executeScript"))
+            out.push({ kind: "scripting.executeScript", file: c.file, line: c.line });
+    }
+    return out;
+}

package/dist/engine/file-discovery.js

@@ -0,0 +1,122 @@
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { join, relative, posix, dirname, resolve, sep } from "node:path";
+import { stripBom } from "./source-lines.js";
+const SCRIPT_EXT = [".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"];
+const HTML_EXT = [".html", ".htm"];
+const SCANNABLE = new Set([...SCRIPT_EXT, ...HTML_EXT]);
+const EXCLUDE_DIRS = new Set(["node_modules", ".git", "dist", "build", ".cache", "coverage"]);
+function ext(path) {
+    const i = path.lastIndexOf(".");
+    return i < 0 ? "" : path.slice(i).toLowerCase();
+}
+export function isScript(relPath) {
+    return SCRIPT_EXT.includes(ext(relPath));
+}
+export function isHtml(relPath) {
+    return HTML_EXT.includes(ext(relPath));
+}
+function toRel(rootDir, abs) {
+    return relative(rootDir, abs).split(/[\\/]/).join(posix.sep);
+}
+/** A leading "/" in a manifest reference is root-relative to the EXTENSION, not
+ *  the filesystem (e.g. "/images/icon.png" means <ext-root>/images/icon.png).
+ *  Normalize to a path relative to rootDir before any filesystem use. */
+export function refToRelPath(p) {
+    return p.replace(/^[\\/]+/, "");
+}
+/** True when a manifest reference resolves to a location inside `rootDir`.
+ *  Blocks "../secret.js" from escaping the package; allows root-relative "/x". */
+export function isWithinRoot(rootDir, relPath) {
+    const root = resolve(rootDir);
+    const abs = resolve(rootDir, refToRelPath(relPath));
+    return abs === root || abs.startsWith(root + sep);
+}
+function readVirtual(rootDir, relPath, discoveredBy) {
+    const rel = refToRelPath(relPath);
+    if (!isWithinRoot(rootDir, rel))
+        return null; // never read/parse files outside the package
+    const absPath = join(rootDir, rel);
+    if (!existsSync(absPath) || !statSync(absPath).isFile())
+        return null;
+    return { relPath: rel, absPath, content: stripBom(readFileSync(absPath, "utf8")), discoveredBy };
+}
+const SCRIPT_SRC_RE = /<script[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi;
+function localScriptSrcs(htmlContent, htmlRel) {
+    const out = [];
+    let m;
+    while ((m = SCRIPT_SRC_RE.exec(htmlContent)) !== null) {
+        const src = m[1];
+        if (/^(https?:)?\/\//i.test(src) || src.startsWith("data:"))
+            continue; // remote/inline-data handled by MV3001
+        const resolved = posix.normalize(posix.join(dirname(htmlRel) || ".", src)).replace(/^\.\//, "");
+        out.push(resolved);
+    }
+    return out;
+}
+/**
+ * Two-pass discovery: manifest-directed entry points first (tagged "manifest"),
+ * then a package-wide fallback scan (tagged "fallback"). Manifest tags win on
+ * dedupe. node_modules/.git/build caches and source maps are excluded.
+ *
+ * Takes pre-collected ManifestRefs so the caller can reuse them (e.g. for
+ * model.manifestRefs) without collecting twice.
+ */
+export function discoverFiles(rootDir, refs) {
+    const byRel = new Map();
+    const add = (vf) => {
+        if (!vf)
+            return;
+        const existing = byRel.get(vf.relPath);
+        if (!existing || (existing.discoveredBy === "fallback" && vf.discoveredBy === "manifest")) {
+            byRel.set(vf.relPath, vf);
+        }
+    };
+    // --- Pass 1: manifest-directed ---
+    for (const s of refs.scripts)
+        add(readVirtual(rootDir, s, "manifest"));
+    for (const p of refs.pages) {
+        const page = readVirtual(rootDir, p, "manifest");
+        add(page);
+        if (page && isHtml(p)) {
+            for (const src of localScriptSrcs(page.content, p))
+                add(readVirtual(rootDir, src, "manifest"));
+        }
+    }
+    // --- Pass 2: fallback scan ---
+    walk(rootDir, rootDir, (abs) => {
+        const rel = toRel(rootDir, abs);
+        if (rel === "manifest.json")
+            return;
+        if (rel.endsWith(".map"))
+            return;
+        if (!SCANNABLE.has(ext(rel)))
+            return;
+        add(readVirtual(rootDir, rel, "fallback"));
+        if (isHtml(rel)) {
+            const page = byRel.get(rel);
+            for (const src of localScriptSrcs(page.content, rel))
+                add(readVirtual(rootDir, src, "fallback"));
+        }
+    });
+    return [...byRel.values()];
+}
+function walk(rootDir, dir, onFile) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        const abs = join(dir, e.name);
+        if (e.isDirectory()) {
+            if (EXCLUDE_DIRS.has(e.name))
+                continue;
+            walk(rootDir, abs, onFile);
+        }
+        else if (e.isFile()) {
+            onFile(abs);
+        }
+    }
+}

package/dist/engine/manifest-refs.js

@@ -0,0 +1,95 @@
+function pushStr(out, source, v) {
+    if (typeof v === "string" && v.length > 0)
+        out.push({ ref: v, source });
+}
+function pushList(out, source, v) {
+    if (Array.isArray(v))
+        for (const item of v)
+            pushStr(out, source, item);
+}
+/** Collect file references from the manifest. Glob entries (containing '*') are
+ *  dropped from `all` since they can't be existence-checked. */
+export function collectManifestRefs(manifest) {
+    const all = [];
+    const pages = [];
+    const scripts = [];
+    const m = manifest;
+    // background
+    pushStr(all, "background.service_worker", m.background?.service_worker);
+    if (m.background?.service_worker)
+        scripts.push(m.background.service_worker);
+    pushList(all, "background.scripts", m.background?.scripts);
+    if (Array.isArray(m.background?.scripts))
+        scripts.push(...m.background.scripts);
+    // content scripts
+    if (Array.isArray(m.content_scripts)) {
+        for (const cs of m.content_scripts) {
+            pushList(all, "content_scripts.js", cs?.js);
+            pushList(all, "content_scripts.css", cs?.css);
+            if (Array.isArray(cs?.js))
+                scripts.push(...cs.js);
+        }
+    }
+    // action popup + icons
+    pushStr(all, "action.default_popup", m.action?.default_popup ?? m.browser_action?.default_popup);
+    const popup = m.action?.default_popup ?? m.browser_action?.default_popup;
+    if (typeof popup === "string")
+        pages.push(popup);
+    collectIcons(all, "action.default_icon", m.action?.default_icon);
+    collectIcons(all, "icons", m.icons);
+    // pages
+    for (const [key, val] of [
+        ["options_page", m.options_page],
+        ["options_ui.page", m.options_ui?.page],
+        ["devtools_page", m.devtools_page],
+        ["side_panel.default_path", m.side_panel?.default_path],
+    ]) {
+        if (typeof val === "string") {
+            pushStr(all, key, val);
+            if (val.endsWith(".html"))
+                pages.push(val);
+        }
+    }
+    // chrome_url_overrides
+    if (m.chrome_url_overrides && typeof m.chrome_url_overrides === "object") {
+        for (const [k, v] of Object.entries(m.chrome_url_overrides)) {
+            pushStr(all, `chrome_url_overrides.${k}`, v);
+            if (typeof v === "string" && v.endsWith(".html"))
+                pages.push(v);
+        }
+    }
+    // web accessible resources (skip globs)
+    if (Array.isArray(m.web_accessible_resources)) {
+        for (const war of m.web_accessible_resources) {
+            if (Array.isArray(war?.resources)) {
+                for (const r of war.resources) {
+                    if (typeof r === "string" && !r.includes("*"))
+                        pushStr(all, "web_accessible_resources", r);
+                }
+            }
+            else if (typeof war === "string" && !war.includes("*")) {
+                // MV2-style flat array
+                pushStr(all, "web_accessible_resources", war);
+            }
+        }
+    }
+    // declarative net request rulesets
+    const rulesets = m.declarative_net_request?.rule_resources;
+    if (Array.isArray(rulesets)) {
+        for (const rs of rulesets)
+            pushStr(all, "declarative_net_request.path", rs?.path);
+    }
+    return { all, pages: dedupe(pages), scripts: dedupe(scripts) };
+}
+function collectIcons(out, source, icons) {
+    if (typeof icons === "string") {
+        pushStr(out, source, icons);
+    }
+    else if (icons && typeof icons === "object") {
+        for (const v of Object.values(icons))
+            pushStr(out, source, v);
+    }
+}
+function dedupe(xs) {
+    return [...new Set(xs)];
+}

package/dist/engine/manifest.js

@@ -0,0 +1,41 @@
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { stripBom } from "./source-lines.js";
+export class ManifestError extends Error {
+}
+/**
+ * Load and minimally validate manifest.json from an extension directory.
+ * Throws ManifestError (→ CLI exit 3) on a missing dir, missing/unreadable
+ * manifest, malformed JSON, or absent manifest_version. We deliberately do NOT
+ * deep-validate the schema here — rules handle semantics.
+ */
+export function loadManifest(rootDir) {
+    if (!existsSync(rootDir) || !statSync(rootDir).isDirectory()) {
+        throw new ManifestError(`Not a directory: ${rootDir}`);
+    }
+    const manifestPath = join(rootDir, "manifest.json");
+    if (!existsSync(manifestPath)) {
+        throw new ManifestError(`No manifest.json found in ${rootDir}`);
+    }
+    let raw;
+    try {
+        raw = stripBom(readFileSync(manifestPath, "utf8"));
+    }
+    catch (e) {
+        throw new ManifestError(`Could not read manifest.json: ${e.message}`);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new ManifestError(`manifest.json is not valid JSON: ${e.message}`);
+    }
+    if (typeof manifest !== "object" || manifest === null) {
+        throw new ManifestError("manifest.json must be a JSON object");
+    }
+    if (typeof manifest.manifest_version !== "number") {
+        throw new ManifestError("manifest.json is missing a numeric manifest_version");
+    }
+    return { manifest, raw };
+}

package/dist/engine/model.js

@@ -0,0 +1,2 @@
+// Core types for the tabsmith-lint engine. PRD 6.2 (ExtensionModel/ApiCall) + 4.2 (report schema).
+export {};

package/dist/engine/source-lines.js

@@ -0,0 +1,22 @@
+// ponytail: naive first-match line lookup. Manifest findings get an approximate
+// line by searching the raw JSON text for a needle. Good enough for a hint;
+// upgrade to a real JSON AST (jsonc-parser) only if precise locations are needed.
+export function findLine(source, needle) {
+    if (!needle)
+        return undefined;
+    const lines = source.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes(needle))
+            return i + 1;
+    }
+    return undefined;
+}
+/** 1-based line number for a character offset into `source`. */
+export function findLineByIndex(source, index) {
+    return source.slice(0, index).split("\n").length;
+}
+/** Strip a leading UTF-8 BOM (U+FEFF). Windows/PowerShell-authored files often
+ *  carry one, which would otherwise break JSON.parse and source scanning. */
+export function stripBom(s) {
+    return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
+}

package/dist/engine/verdict.js

@@ -0,0 +1,25 @@
+/** Canonical severity ranking — the single source of truth for ordering and
+ *  filtering. Higher = more severe. */
+export const SEVERITY_RANK = { reject: 2, fix: 1, info: 0 };
+/** Most-severe-first order, for grouped display and stable sorting. */
+export const SEVERITY_ORDER = ["reject", "fix", "info"];
+export function filterByMinSeverity(findings, min) {
+    return findings.filter((f) => SEVERITY_RANK[f.severity] >= SEVERITY_RANK[min]);
+}
+export function computeVerdict(findings) {
+    if (findings.some((f) => f.severity === "reject"))
+        return "high_rejection_risk";
+    if (findings.some((f) => f.severity === "fix"))
+        return "needs_fixes";
+    return "pass";
+}
+export function verdictExitCode(verdict) {
+    switch (verdict) {
+        case "pass":
+            return 0;
+        case "needs_fixes":
+            return 1;
+        case "high_rejection_risk":
+            return 2;
+    }
+}