Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions WEB_TOPS.md
Original file line number Diff line number Diff line change
Expand Up @@ -295,7 +295,7 @@ A second adopter, an `astro-site` with tests or a `node-service` reopens the que
and `laws`, and build output only where the class maps a build-output layer. It requires the judged
laws it maps (§8.2, the tick column): the laws no class gates, plus its "Extra laws" row, with
W-27 only when the project depends on Astro. `W-06 strict` for `node-service` is a reading of W-06,
which every class maps, as it does W-48 (unused exports, files and dependencies). A law a class maps but that has no reader yet (W-37, W-42 to W-48) is
which every class maps, as it does W-48 (unused exports, files and dependencies). A law a class maps but that has no reader yet (W-42 to W-48) is
required when it is judged. Under `hard`, `check` refuses a coverage floor below, and a CRAP cap or
`unexplained_survivors_max` above, the class's value in this table (§9, §12).

Expand Down Expand Up @@ -788,7 +788,7 @@ These tables are generated from `laws/W-NN.yaml` (§8.3). Edit the file, not the
| W-34 | No focused or skipped tests committed | R | tl: `@vitest/eslint-plugin` (1.6) `no-focused-tests`, `no-disabled-tests` | ✓ |
| W-35 | Every suppression names its rule and says why: `eslint-disable` with a description, `@ts-expect-error` with a description, no `@ts-ignore` or `@ts-nocheck`; unused directives fail | R | tl: `eslint-comments/require-description`, `no-unlimited-disable`; `ban-ts-comment` (`allow-with-description`); `reportUnusedDisableDirectives: "error"`. The suppression census in §6.7 lists every kind that is counted and ratcheted | ✓ |
| W-36 | No `set:html`, `dangerouslySetInnerHTML` or `innerHTML` with unsanitized input | R | an | |
| W-37 | Only public env reaches client code (`PUBLIC_` vars, `astro:env` client fields) | R | an | |
| W-37 | Only public env reaches client code (`PUBLIC_` vars, `astro:env` client fields) | R | an: custom ESLint rule, on `**/*.{jsx,tsx}` and `.astro` client script blocks (frontmatter is server code) | |
| W-38 | No high or critical advisories in production dependencies | R | tl: dependency audit **[verify `bun audit` output]** | ✓ |
| W-39 | No secrets in source or fixtures | R | tl: secrets scanner **[verify]** | |
| W-40 | `bun.lock` is committed and installs with `--frozen-lockfile` | R | tl | ✓ |
Expand Down Expand Up @@ -1131,6 +1131,7 @@ web-tops/
│ ├── report/ # report writing, text and JSON rendering
│ └── survivors/ # the survivor key (section 6.4), and the ledger when it lands
├── profiles/ # one profile per launch class: the data init renders from
├── packages/ # eslint-plugin-webtops: the custom ESLint rules behind W-23, W-36 and W-37, built into the web-tops package
├── laws/ # one W-NN.yaml per law (§8.3): the source of the §8.2 tables
├── schema/ # web-tops, gate-report, baseline, core (verdicts, modes) and law schemas
├── config/ # drop-in templates, AGENTS.md.tmpl
Expand All @@ -1146,7 +1147,7 @@ web-tops/

The law twins are in `fixtures/laws/W-NN/{bad,clean}/`: a bad and a clean twin per law, which the law probe (`src/laws/probe/`) proves.

Not yet in the tree: `src/budgets/` (the `dist/` byte reader, M4) and the M3 paths: `packages/eslint-plugin-webtops/`, `examples/node-service/`, `src/layers/laws/`, `src/acks/` and `src/lawdiff/`. The kit's tools already cover them: the M3 source paths and the plugin are linted, type-checked, formatted, cruised and tested like the rest of the source; the law fixtures are data, skipped like the probe fixtures; `examples/node-service` gates itself.
Not yet in the tree: `src/budgets/` (the `dist/` byte reader, M4) and the M3 paths: `examples/node-service/`, `src/layers/laws/`, `src/acks/` and `src/lawdiff/`. The kit's tools already cover them: the M3 source paths and the plugin are linted, type-checked, formatted, cruised and tested like the rest of the source; the law fixtures are data, skipped like the probe fixtures; `examples/node-service` gates itself.

Self-hosting: the kit runs `hard` and passes its own tier-1 gate before any release.

Expand Down
8 changes: 8 additions & 0 deletions fixtures/init/astro-site/eslint.preset.json.golden
Original file line number Diff line number Diff line change
Expand Up @@ -611,6 +611,14 @@
}
}
},
{
"plugins": [
"webtops"
],
"rules": {
"webtops/no-unsanitized-html": "error"
}
},
{
"files": [
"**/*.js",
Expand Down
8 changes: 8 additions & 0 deletions fixtures/init/node-service/eslint.preset.json.golden
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,14 @@
"vitest/no-disabled-tests": "error"
}
},
{
"plugins": [
"webtops"
],
"rules": {
"webtops/no-unsanitized-html": "error"
}
},
{
"files": [
"**/*.js",
Expand Down
8 changes: 8 additions & 0 deletions fixtures/init/ts-library/eslint.preset.json.golden
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,14 @@
"vitest/no-disabled-tests": "error"
}
},
{
"plugins": [
"webtops"
],
"rules": {
"webtops/no-unsanitized-html": "error"
}
},
{
"files": [
"**/*.js",
Expand Down
8 changes: 8 additions & 0 deletions fixtures/init/ui-components/eslint.preset.json.golden
Original file line number Diff line number Diff line change
Expand Up @@ -411,6 +411,14 @@
"react-hooks/exhaustive-deps": "error"
}
},
{
"plugins": [
"webtops"
],
"rules": {
"webtops/no-unsanitized-html": "error"
}
},
{
"files": [
"**/*.js",
Expand Down
8 changes: 8 additions & 0 deletions fixtures/init/web-app/eslint.preset.json.golden
Original file line number Diff line number Diff line change
Expand Up @@ -411,6 +411,14 @@
"react-hooks/exhaustive-deps": "error"
}
},
{
"plugins": [
"webtops"
],
"rules": {
"webtops/no-unsanitized-html": "error"
}
},
{
"files": [
"**/*.js",
Expand Down
2 changes: 1 addition & 1 deletion laws/W-37.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ severity: R
classes: [ui-components, astro-site, web-app]
reader:
kinds: [an]
text: "an"
text: "an: custom ESLint rule, on `**/*.{jsx,tsx}` and `.astro` client script blocks (frontmatter is server code)"
rules:
- { tool: eslint, name: "webtops/public-env-only" }
judged: m3
Expand Down
3 changes: 3 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@
"laws",
"config",
"profiles",
"packages/eslint-plugin-webtops/package.json",
"packages/eslint-plugin-webtops/dist",
"fixtures/laws"
],
"engines": {
Expand All @@ -51,6 +53,7 @@
},
"packageManager": "bun@1.4.4",
"scripts": {
"prepare": "tsc -p packages/eslint-plugin-webtops/tsconfig.build.json",
"typecheck": "tsc -b --noEmit",
"lint": "eslint .",
"test": "vitest run --coverage --sequence.shuffle",
Expand Down
26 changes: 26 additions & 0 deletions packages/eslint-plugin-webtops/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
{
"name": "eslint-plugin-webtops",
"version": "0.3.0",
"private": true,
"description": "ESLint rules behind Web-TOPS laws W-23, W-36 and W-37 (complete Tailwind classes, no unsanitized HTML, public env only in client code)",
"license": "MIT OR Apache-2.0",
"type": "module",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
},
"./package.json": "./package.json"
},
"files": [
"dist"
],
"peerDependencies": {
"eslint": ">=10.15.0"
},
"scripts": {
"build": "tsc -p tsconfig.build.json"
}
}
112 changes: 112 additions & 0 deletions packages/eslint-plugin-webtops/src/ast.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
import { describe, expect, it } from "vitest";
import {
attributeName,
attributeValue,
byKind,
child,
children,
dottedName,
kind,
lookup,
propertyName,
quasisOf,
staticText,
stringList,
} from "./ast.ts";

const id = (name: string) => ({ type: "Identifier", name });
const member = (object: unknown, property: unknown, computed = false) => ({
type: "MemberExpression",
object,
property,
computed,
});
const literal = (value: unknown) => ({ type: "Literal", value });

describe("reading nodes by shape", () => {
it("takes a node's type and fields, and nothing from a value that is not a node", () => {
expect(kind(id("a"))).toBe("Identifier");
expect(kind(null)).toBeUndefined();
expect(kind("Identifier")).toBeUndefined();
expect(kind({ type: 5 })).toBeUndefined();
expect(child(null, "x")).toBeUndefined();
expect(child({ x: 1 }, "x")).toBe(1);
});

it("reads a list field, and an empty list when it is absent or not a list", () => {
expect(children({ list: [1, 2] }, "list")).toEqual([1, 2]);
expect(children({}, "list")).toEqual([]);
expect(children({ list: "no" }, "list")).toEqual([]);
});

it("looks a node type or a name up in a table", () => {
const table = new Map([["Identifier", 1]]);
expect(byKind(table, id("a"))).toBe(1);
expect(byKind(table, literal("a"))).toBeUndefined();
expect(byKind(table, null)).toBeUndefined();
expect(lookup(table, "Identifier")).toBe(1);
expect(lookup(table, undefined)).toBeUndefined();
});

it("gives the cooked text of each template part, and nothing for a part that cannot be cooked", () => {
const template = {
type: "TemplateLiteral",
quasis: [{ value: { cooked: "a" } }, { value: { cooked: null } }, { value: {} }],
expressions: [],
};
expect(quasisOf(template)).toEqual(["a", "", ""]);
});

it("gives static text for a string literal and a template with no interpolation only", () => {
const plain = {
type: "TemplateLiteral",
quasis: [{ value: { cooked: "t" } }],
expressions: [],
};
expect(staticText(literal("s"))).toBe("s");
expect(staticText(literal(5))).toBeUndefined();
expect(staticText(plain)).toBe("t");
expect(staticText({ ...plain, expressions: [id("x")] })).toBeUndefined();
expect(staticText(id("x"))).toBeUndefined();
});

it("names an identifier, and a chain of plain member accesses", () => {
expect(dottedName(id("a"))).toBe("a");
expect(dottedName(member(member(id("a"), id("b")), id("c")))).toBe("a.b.c");
expect(dottedName(member(id("a"), literal("b"), true))).toBeUndefined();
expect(dottedName(member(id("a"), id("b"), true))).toBeUndefined();
expect(dottedName(member({ type: "ThisExpression" }, id("x")))).toBeUndefined();
expect(dottedName(member(id("a"), { type: "PrivateIdentifier" }))).toBeUndefined();
expect(dottedName(literal("a"))).toBeUndefined();
});

it("names a property by identifier or by string key, and not by another computed key", () => {
expect(propertyName(member(id("a"), id("b")))).toBe("b");
expect(propertyName(member(id("a"), literal("b"), true))).toBe("b");
expect(propertyName(member(id("a"), id("b"), true))).toBeUndefined();
});

it("names a JSX attribute, plain or namespaced, and reads its value", () => {
const plain = { type: "JSXAttribute", name: { type: "JSXIdentifier", name: "className" } };
const spaced = {
type: "JSXAttribute",
name: {
type: "JSXNamespacedName",
namespace: { name: "set" },
name: { name: "html" },
},
value: { type: "JSXExpressionContainer", expression: id("x") },
};
expect(attributeName(plain)).toBe("className");
expect(attributeName(spaced)).toBe("set:html");
expect(attributeName({ name: { type: "JSXNamespacedName" } })).toBe(":");
expect(attributeValue(spaced)).toEqual(id("x"));
expect(attributeValue({ value: literal("a b") })).toEqual(literal("a b"));
});

it("takes only the strings of a list option, and the fallback when there is no list", () => {
expect(stringList({ names: ["a", 1, "b"] }, "names", ["z"])).toEqual(["a", "b"]);
expect(stringList({}, "names", ["z"])).toEqual(["z"]);
expect(stringList(undefined, "names", ["z"])).toEqual(["z"]);
});
});
111 changes: 111 additions & 0 deletions packages/eslint-plugin-webtops/src/ast.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
/**
* A syntax node as the parser hands it over. ESLint's typings leave out JSX and Astro nodes, so the
* rules read every node by its shape: `type`, then the fields they care about.
*/
export type Loose = Readonly<Record<string, unknown>>;

const isLoose = (value: unknown): value is Loose => typeof value === "object" && value !== null;

/** The node's `type`, or undefined for anything that is not a node. */
export function kind(node: unknown): string | undefined {
const type = isLoose(node) ? node["type"] : undefined;
return typeof type === "string" ? type : undefined;
}

/** One field of a node, or undefined. */
export const child = (node: unknown, key: string): unknown =>
isLoose(node) ? node[key] : undefined;

/** A list field of a node: empty when the field is absent or not a list. */
export function children(node: unknown, key: string): readonly unknown[] {
const value = child(node, key);
return Array.isArray(value) ? value : [];
}

/** The cooked text of a template element. */
const cooked = (quasi: unknown): string | undefined => {
const text = child(child(quasi, "value"), "cooked");
return typeof text === "string" ? text : undefined;
};

/** The static text of a template literal's parts: one string per quasi, `""` for a part the parser could not cook. */
export const quasisOf = (template: unknown): readonly string[] =>
children(template, "quasis").map((quasi) => cooked(quasi) ?? "");

const literalText = (node: unknown): string | undefined => {
const value = child(node, "value");
return typeof value === "string" ? value : undefined;
};

const plainTemplateText = (node: unknown): string | undefined =>
children(node, "expressions").length === 0 ? quasisOf(node)[0] : undefined;

// Tables are built where they are used, not at module level: a mutant in module-level data runs
// the whole suite again (a static mutant), one in a function runs only the tests that reach it.
const textReaders = (): ReadonlyMap<string, (node: unknown) => string | undefined> =>
new Map([
["Literal", literalText],
["TemplateLiteral", plainTemplateText],
]);

/** The entry of a table keyed by node type, for the node's own type. */
export function byKind<T>(table: ReadonlyMap<string, T>, node: unknown): T | undefined {
const type = kind(node);
return type === undefined ? undefined : table.get(type);
}

/** The entry of a table for a name that may be missing. */
export const lookup = <T>(
table: ReadonlyMap<string, T>,
name: string | undefined,
): T | undefined => (name === undefined ? undefined : table.get(name));

/** The text of a string literal or of a template literal with no interpolation; undefined for anything else. */
export const staticText = (node: unknown): string | undefined =>
byKind(textReaders(), node)?.(node);

const joined = (object: string | undefined, property: string | undefined): string | undefined =>
object !== undefined && property !== undefined ? `${object}.${property}` : undefined;

const memberName = (node: unknown): string | undefined =>
kind(node) === "MemberExpression" && child(node, "computed") !== true
? joined(dottedName(child(node, "object")), nameOf(child(node, "property")))
: undefined;

/** `name` for an identifier, `a.b.c` for a chain of member accesses, else undefined. */
export const dottedName = (node: unknown): string | undefined =>
kind(node) === "Identifier" ? nameOf(node) : memberName(node);

/** The `name` field of an identifier-like node. */
export function nameOf(node: unknown): string | undefined {
const name = child(node, "name");
return typeof name === "string" ? name : undefined;
}

/** The name a property is read by: `a.b` and `a["b"]`; undefined for a computed key that is not a string literal. */
export const propertyName = (member: unknown): string | undefined =>
child(member, "computed") === true
? staticText(child(member, "property"))
: nameOf(child(member, "property"));

const namespaced = (name: unknown): string =>
`${nameOf(child(name, "namespace")) ?? ""}:${nameOf(child(name, "name")) ?? ""}`;

/** The attribute's name: `className`, or `set:html` for a namespaced one. */
export function attributeName(attribute: unknown): string | undefined {
const name = child(attribute, "name");
return kind(name) === "JSXNamespacedName" ? namespaced(name) : nameOf(name);
}

/** The expression inside `attr={...}`, or the literal of `attr="..."`. */
export function attributeValue(attribute: unknown): unknown {
const value = child(attribute, "value");
return kind(value) === "JSXExpressionContainer" ? child(value, "expression") : value;
}

/** Strings from a rule option that should be a list of them: anything else is dropped. */
export function stringList(option: unknown, key: string, fallback: readonly string[]): string[] {
const value = child(option, key);
if (!Array.isArray(value)) return [...fallback];
return value.filter((entry): entry is string => typeof entry === "string");
}
Loading
Loading