peer-ai-standards 1.0.0-next.0

package/dist/profile.js

@@ -0,0 +1,269 @@
+import { CHECKS, SEVERITIES, TRAITS } from "peer-ai-workflow";
+import { z } from "zod";
+import { SourceSchema, STAGES, traitsNeeded } from "./rule.js";
+// A stack profile says how to follow core rules in one stack (RFC 0006). Each of its rules names
+// the core rule it carries out, and may apply only to some architectures, hold a number the
+// project can change, and name the tool setting that enforces it. An automatic rule comes with an
+// example that must fail and one that must pass, which the tests run through the real tool.
+const Text = z.string().min(1);
+const Slug = z.string().regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "use lowercase letters, digits and hyphens");
+const CoreRuleId = z.string().regex(/^[A-Z][A-Z0-9]*-\d{2,}$/, "a core rule id, such as CODE-14");
+const ValueSchema = z.union([z.number(), Text]);
+/** The jobs of Peer AI's pipeline workflow that check a rule automatically (RFC 0006, section 4). */
+export const PIPELINE_JOBS = ["secrets", "dependencies", "workflows", "code"];
+/** Where an option holds this, the tool gets the rule's value: its default, or the project's. */
+export const VALUE = "$value";
+export const EnforcerSchema = z.discriminatedUnion("tool", [
+    z.strictObject({
+        tool: z.literal("eslint"),
+        rule: Text.describe("The ESLint rule, with its plugin's prefix, such as @typescript-eslint/no-explicit-any."),
+        options: z.array(z.unknown()).optional().describe(`The rule's options. "${VALUE}" stands for the rule's value.`),
+        typed: z.boolean().optional().describe("The rule needs type information, so it runs on TypeScript files only."),
+        files: z
+            .array(Text)
+            .min(1)
+            .optional()
+            .describe("The files it applies to, as globs within the part, such as **/*.tsx. None: every script."),
+        ignores: z.array(Text).min(1).optional().describe("Files within those it leaves alone, such as **/*.test.*."),
+    }),
+    z.strictObject({
+        tool: z.literal("ruff"),
+        rule: z
+            .string()
+            .regex(/^[A-Z]+[0-9]+$/, "a Ruff rule code, such as S608")
+            .describe("The Ruff rule's code."),
+        settings: z
+            .record(z.string(), z.record(z.string(), z.unknown()))
+            .optional()
+            .describe(`Ruff's lint settings the rule reads, such as { pylint: { "max-statements": "${VALUE}" } }.`),
+    }),
+    z.strictObject({
+        tool: z.literal("github-actions"),
+        job: z.enum(PIPELINE_JOBS).describe("The job of Peer AI's pipeline workflow that runs the check."),
+        finding: Text.optional().describe("What the tool reports for this rule, where one job checks several rules."),
+    }),
+    z.strictObject({
+        tool: z.literal("typescript"),
+        option: Text.describe("The compiler option, such as strict."),
+        value: z.unknown().describe("The value it must have."),
+    }),
+]);
+const ExampleSchema = z.union([
+    Text,
+    z.custom((input) => typeof input === "function", "a string or a function of the value"),
+]);
+export const ExamplesSchema = z.strictObject({
+    file: Text.describe("The example's file name, which sets its language, such as example.ts."),
+    fails: ExampleSchema.describe("Code the enforcer must refuse."),
+    passes: ExampleSchema.describe("Code the enforcer must accept."),
+});
+export const ProfileRuleSchema = z
+    .strictObject({
+    id: z.string().regex(/^[A-Z][A-Z0-9]*-\d{2,}$/, "use the profile's prefix and a number, such as TS-01"),
+    title: Text.max(100),
+    rule: Text,
+    why: Text,
+    ask: Text.regex(/\?$/, "the ask is a question"),
+    stage: z.enum(STAGES),
+    check: z.enum(CHECKS),
+    severity: z.enum(SEVERITIES),
+    when: z.array(z.enum(TRAITS)).min(1).optional(),
+    sources: z.array(SourceSchema).min(1).optional(),
+    carries: CoreRuleId.describe("The core rule this rule carries out in the stack."),
+    architectures: z
+        .array(Slug)
+        .min(1)
+        .optional()
+        .describe("The architecture labels it applies to. A rule with none applies to every architecture."),
+    default: z
+        .strictObject({ value: ValueSchema, unit: Text.optional() })
+        .optional()
+        .describe("A number or a choice the project may change, which {value} in the text stands for."),
+    enforcer: EnforcerSchema.optional(),
+    examples: ExamplesSchema.optional(),
+})
+    .superRefine((rule, ctx) => {
+    const issue = (path, message) => {
+        ctx.addIssue({ code: "custom", path: [path], message });
+    };
+    if (rule.check === "auto" && rule.enforcer === undefined)
+        issue("enforcer", "an automatic rule names its enforcer");
+    if (rule.check !== "auto" && rule.enforcer !== undefined)
+        issue("check", "a rule with an enforcer is automatic");
+    if (rule.enforcer !== undefined && rule.examples === undefined) {
+        issue("examples", "an enforced rule has an example that must fail and one that must pass");
+    }
+    const settings = rule.enforcer?.tool === "eslint"
+        ? rule.enforcer.options
+        : rule.enforcer?.tool === "ruff"
+            ? rule.enforcer.settings
+            : undefined;
+    const usesValue = `${rule.title} ${rule.rule}`.includes("{value}") || JSON.stringify(settings ?? []).includes(VALUE);
+    if (usesValue && rule.default === undefined)
+        issue("default", "a rule that uses {value} has a default");
+});
+export const ProfileSchema = z.strictObject({
+    id: Slug.describe("How a project lists the profile in standards.profiles, such as react-native."),
+    name: Text,
+    prefix: z.string().regex(/^[A-Z][A-Z0-9]*$/, "capital letters and digits, such as REACT"),
+    about: Text.describe("What the profile covers, for its page."),
+    stacks: z
+        .array(Slug)
+        .describe("The stack tags it applies to, as detection writes them. None: every part, when listed."),
+    extends: z.array(Slug).optional().describe("Profiles it builds on, which apply wherever it does."),
+    rules: z.array(ProfileRuleSchema),
+});
+/**
+ * Checks every profile against the schema and against the core: prefixes and ids used once, each
+ * rule's id starting with its profile's prefix, each carried rule a core rule, and every profile
+ * it extends known, without a loop.
+ */
+export function checkProfiles(inputs, core, corePrefixes) {
+    const problems = [];
+    const profiles = [];
+    const coreById = new Map(core.map((rule) => [rule.id, rule]));
+    const ids = new Set();
+    const prefixes = new Set(corePrefixes);
+    const ruleIds = new Set();
+    for (const input of inputs) {
+        const result = ProfileSchema.safeParse(input);
+        if (!result.success) {
+            for (const issue of result.error.issues)
+                problems.push(`${input.id}: ${issue.path.join(".")}: ${issue.message}`);
+            continue;
+        }
+        const profile = result.data;
+        if (ids.has(profile.id))
+            problems.push(`${profile.id}: the profile id is used twice`);
+        if (prefixes.has(profile.prefix))
+            problems.push(`${profile.id}: the prefix ${profile.prefix} is already used`);
+        ids.add(profile.id);
+        prefixes.add(profile.prefix);
+        const rules = [];
+        for (const rule of profile.rules) {
+            if (!rule.id.startsWith(`${profile.prefix}-`)) {
+                problems.push(`${rule.id}: a ${profile.id} rule's id starts with ${profile.prefix}-`);
+            }
+            if (ruleIds.has(rule.id))
+                problems.push(`${rule.id}: the id is used twice`);
+            ruleIds.add(rule.id);
+            const carried = coreById.get(rule.carries);
+            if (carried === undefined) {
+                problems.push(`${rule.id}: it carries ${rule.carries}, which isn't a core rule`);
+                continue;
+            }
+            rules.push({ ...rule, profile: profile.id, domain: carried.domain });
+        }
+        profiles.push({ ...profile, extends: profile.extends ?? [], rules });
+    }
+    const byId = new Map(profiles.map((profile) => [profile.id, profile]));
+    for (const profile of profiles) {
+        for (const base of profile.extends) {
+            if (!byId.has(base))
+                problems.push(`${profile.id}: it extends ${base}, which isn't a profile`);
+        }
+        if (reachable(byId, profile.extends).has(profile.id))
+            problems.push(`${profile.id}: it extends itself`);
+    }
+    return { profiles, problems };
+}
+/** Every profile the given ones extend, directly or through others. */
+function reachable(byId, start) {
+    const seen = new Set();
+    const queue = [...start];
+    for (let id = queue.shift(); id !== undefined; id = queue.shift()) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        queue.push(...(byId.get(id)?.extends ?? []));
+    }
+    return seen;
+}
+/**
+ * The listed profiles that apply to a part, with the profiles they extend, bases first. A listed
+ * profile applies when the part's stack has one of its tags, when it names no stacks, or when the
+ * part names no stack. A profile it extends comes only with it, never on its own tag.
+ */
+export function profilesFor(all, listed, part) {
+    const byId = new Map(all.map((profile) => [profile.id, profile]));
+    const stack = part.stack ?? [];
+    const direct = listed.filter((id) => {
+        const profile = byId.get(id);
+        if (profile === undefined)
+            return false;
+        return stack.length === 0 || profile.stacks.length === 0 || profile.stacks.some((tag) => stack.includes(tag));
+    });
+    const applying = new Set([...direct, ...reachable(byId, direct)]);
+    const ordered = [];
+    const visit = (id) => {
+        const profile = byId.get(id);
+        if (profile === undefined || ordered.includes(profile) || !applying.has(id))
+            return;
+        for (const base of profile.extends)
+            visit(base);
+        ordered.push(profile);
+    };
+    for (const id of all.map((profile) => profile.id))
+        visit(id);
+    return ordered;
+}
+/** Puts the rule's value in its text, and in its enforcer's options. */
+export function withValue(rule, value) {
+    if (value === undefined)
+        return rule;
+    const fillText = (text) => text.replaceAll("{value}", String(value));
+    const enforcer = rule.enforcer?.tool === "eslint" && rule.enforcer.options !== undefined
+        ? { ...rule.enforcer, options: fillOptions(rule.enforcer.options, value) }
+        : rule.enforcer?.tool === "ruff" && rule.enforcer.settings !== undefined
+            ? { ...rule.enforcer, settings: fill(rule.enforcer.settings, value) }
+            : rule.enforcer;
+    return {
+        ...rule,
+        title: fillText(rule.title),
+        rule: fillText(rule.rule),
+        ask: fillText(rule.ask),
+        ...(enforcer === undefined ? {} : { enforcer }),
+        value,
+    };
+}
+/** The options or settings with the rule's value put where they say $value. */
+function fill(option, value) {
+    if (option === VALUE)
+        return value;
+    if (Array.isArray(option))
+        return option.map((inner) => fill(inner, value));
+    if (option !== null && typeof option === "object") {
+        return Object.fromEntries(Object.entries(option).map(([key, inner]) => [key, fill(inner, value)]));
+    }
+    return option;
+}
+const fillOptions = (options, value) => fill(options, value);
+/**
+ * The profile rules that apply to a part at the project's stage, with its traits and its
+ * architecture, and with the project's values in place of the defaults.
+ */
+export function applyProfiles(all, selection) {
+    const reached = STAGES.indexOf(selection.stage);
+    const traits = selection.traits ?? [];
+    return profilesFor(all, selection.listed, selection)
+        .flatMap((profile) => profile.rules)
+        .filter((rule) => STAGES.indexOf(rule.stage) <= reached &&
+        traitsNeeded(rule).every((trait) => traits.includes(trait)) &&
+        (rule.architectures === undefined ||
+            (selection.architecture !== undefined && rule.architectures.includes(selection.architecture))))
+        .map((rule) => {
+        const changed = selection.overrides?.[rule.id]?.value;
+        return withValue(rule, changed !== undefined && overrideFits(rule, changed) ? changed : rule.default?.value);
+    });
+}
+/**
+ * Whether a project's value can stand in for the rule's default: a rule with one, and a value of
+ * its type. A default that's a whole number, such as a count of lines, takes only whole numbers of
+ * 0 or more, since the tools refuse anything else.
+ */
+export function overrideFits(rule, value) {
+    if (rule.default === undefined || typeof value !== typeof rule.default.value)
+        return false;
+    const counts = typeof rule.default.value === "number" && Number.isInteger(rule.default.value);
+    return !counts || (Number.isInteger(value) && Number(value) >= 0);
+}

package/dist/profiles/express.d.ts

@@ -0,0 +1,2 @@
+import type { ProfileInput } from "../profile.ts";
+export declare const express: ProfileInput;

package/dist/profiles/express.js

@@ -0,0 +1,93 @@
+// Express. It builds on Node. Its layering rules apply only where a part declares that
+// architecture, so a modular monolith and a layered API each get their own. Examples are from a
+// made-up bicycle repair booking service.
+export const express = {
+    id: "express",
+    name: "Express",
+    prefix: "EXPRESS",
+    about: "APIs in Express: bodies with a limit, input checked at the route, one error handler that keeps internals in, security headers, and callers from a fixed list. Its layering rules follow the architecture a part declares. It builds on the Node profile.",
+    stacks: ["express"],
+    extends: ["node"],
+    rules: [
+        {
+            id: "EXPRESS-01",
+            title: "Request bodies stay under {value}",
+            rule: 'Body parsers keep a size limit, such as `express.json({ limit: "{value}" })`, raised only for a route that needs more, such as an upload.',
+            why: "A body with no limit lets one request fill the server's memory.",
+            ask: "Does every body parser in this change keep a size limit?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "BE-02",
+            default: { value: "100kb" },
+        },
+        {
+            id: "EXPRESS-02",
+            title: "Input is checked at the route",
+            rule: "Every route checks its body, parameters and query against a schema before anything else uses them.",
+            why: "Express passes on whatever arrives. Unchecked input is how wrong types, extra fields and injections reach the business rules.",
+            ask: "Does every route in this change check its input against a schema?",
+            stage: "prototype",
+            check: "ai-review",
+            severity: "high",
+            carries: "SEC-05",
+        },
+        {
+            id: "EXPRESS-03",
+            title: "One error handler, and no internals in its answer",
+            rule: "Errors reach one error handler, which answers in the project's error shape, without stack traces, queries or file paths.",
+            why: "Express's default answer to an error shows the stack trace outside production, and a missed setting shows it in production.",
+            ask: "Could an error in this change send internal detail to the client?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "SEC-09",
+        },
+        {
+            id: "EXPRESS-04",
+            title: "Every response sets its security headers",
+            rule: "The security headers are set for every response, such as with `helmet`, before any route.",
+            why: "Express sets none by default, so a browser gives its pages none of the protections the headers switch on.",
+            ask: "Are the security headers set before every route?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "SEC-17",
+        },
+        {
+            id: "EXPRESS-05",
+            title: "Cross-origin callers come from a fixed list",
+            rule: "CORS allows only a fixed list of the project's own origins. It never echoes back whatever origin asked, such as with `origin: true`, least of all with credentials.",
+            why: "Echoing the caller's origin with credentials lets any site call the API as the visitor.",
+            ask: "Does the CORS policy allow only a fixed list of origins?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "high",
+            carries: "SEC-16",
+        },
+        {
+            id: "EXPRESS-06",
+            title: "Routes call services, never the database",
+            rule: "In a layered API, a route reads the request, calls a service and answers. Only the data layer queries the database.",
+            why: "A route that queries the database skips the rules the service enforces, and the next change has to find every copy.",
+            ask: "Does any route in this change reach the database without its service?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "ARC-07",
+            architectures: ["layered"],
+        },
+        {
+            id: "EXPRESS-07",
+            title: "Modules use each other only through what they export",
+            rule: "In a modular monolith, each module's routes, services and data stay inside it. Another module imports only what the module's index exports.",
+            why: "Reaching into another module's files ties the two together, so neither can change alone.",
+            ask: "Does this change import another module's internal files?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "ARC-03",
+            architectures: ["modular-monolith"],
+        },
+    ],
+};

package/dist/profiles/fastapi.d.ts

@@ -0,0 +1,2 @@
+import type { ProfileInput } from "../profile.ts";
+export declare const fastapi: ProfileInput;

package/dist/profiles/fastapi.js

@@ -0,0 +1,104 @@
+// FastAPI. It builds on Python. Its layering rules apply only where a part declares that
+// architecture, so a modular monolith and a layered API each get their own. Examples are from a
+// made-up bicycle repair booking service.
+export const fastapi = {
+    id: "python-fastapi",
+    name: "FastAPI",
+    prefix: "FASTAPI",
+    about: "APIs in FastAPI: models for what comes in and what goes out, permission checked per record, settings checked at start-up, callers from a fixed list, errors that keep internals in, and a body limit set somewhere. Its layering rules follow the architecture a part declares. It builds on the Python profile.",
+    stacks: ["fastapi"],
+    extends: ["python"],
+    rules: [
+        {
+            id: "FASTAPI-01",
+            title: "Every route has models for what comes in and goes out",
+            rule: "Every route takes its body as a Pydantic model and declares its response model, so FastAPI checks what arrives and sends only the fields the response names.",
+            why: "A route that returns a database object sends every field it has, including ones the client should never see.",
+            ask: "Does every route in this change declare request and response models?",
+            stage: "prototype",
+            check: "ai-review",
+            severity: "high",
+            carries: "SEC-05",
+        },
+        {
+            id: "FASTAPI-02",
+            title: "Permission is checked for the record, not only the person",
+            rule: "A route that takes an id checks the caller may use that record, such as in a dependency that loads it for the caller, not only that they're signed in.",
+            why: "A dependency that only checks sign-in lets anyone signed in change an id in the URL and read someone else's record.",
+            ask: "Does every route in this change that takes an id check the caller may use that record?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "critical",
+            carries: "SEC-01",
+        },
+        {
+            id: "FASTAPI-03",
+            title: "Settings are checked when the app starts",
+            rule: "Settings are a Pydantic settings class, loaded once at start-up, so the app refuses to start with a setting missing or wrong, and an environment name it doesn't know is treated as production.",
+            why: "A setting read with os.environ where it's used fails the first request that needs it, long after the deploy looked fine.",
+            ask: "Does this change read a setting outside the settings class?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "REL-04",
+        },
+        {
+            id: "FASTAPI-04",
+            title: "Cross-origin callers come from a fixed list",
+            rule: "`CORSMiddleware` allows only a fixed list of the project's own origins, never `*` with credentials.",
+            why: "An open CORS policy lets any site call the API with the visitor's credentials.",
+            ask: "Does the CORS middleware allow only a fixed list of origins?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "high",
+            carries: "SEC-16",
+        },
+        {
+            id: "FASTAPI-05",
+            title: "Errors keep internals in",
+            rule: "Exception handlers answer in the project's error shape, without tracebacks, queries or driver errors, and `debug` is off outside development.",
+            why: "With debug on, or a handler that passes on an exception's text, such as `HTTPException(detail=str(error))`, a database error reaches the client with the query and the table names in it.",
+            ask: "Could an error in this change reach the client with internal detail?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "SEC-09",
+        },
+        {
+            id: "FASTAPI-06",
+            title: "Request bodies stay under {value}",
+            rule: "Something limits request bodies to {value}, such as the proxy in front or a middleware like Starlette's `RequestBodyLimitMiddleware`, since FastAPI sets no limit itself.",
+            why: "With no limit, one request can fill the server's memory.",
+            ask: "What limits the size of a request body, and is it {value} or less?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "BE-02",
+            default: { value: "1 MiB" },
+        },
+        {
+            id: "FASTAPI-07",
+            title: "Routes call services, never the session",
+            rule: "In a layered API, a route reads the request, calls a service and answers. Only the data layer uses the database session.",
+            why: "A route that queries the session skips the rules the service enforces, and the next change has to find every copy.",
+            ask: "Does any route in this change use the database session directly?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "ARC-07",
+            architectures: ["layered"],
+        },
+        {
+            id: "FASTAPI-08",
+            title: "Each domain keeps its router, services and models to itself",
+            rule: "In a modular monolith, each domain's package holds its router, services and models. Another domain imports only what the package's public module exports.",
+            why: "Reaching into another domain's models or services ties the two together, so neither can change alone.",
+            ask: "Does this change import another domain's internal modules?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "ARC-03",
+            architectures: ["modular-monolith"],
+        },
+    ],
+};

package/dist/profiles/fastify.d.ts

@@ -0,0 +1,2 @@
+import type { ProfileInput } from "../profile.ts";
+export declare const fastify: ProfileInput;

package/dist/profiles/fastify.js

@@ -0,0 +1,56 @@
+// Fastify. It builds on Node. Examples are from a made-up bicycle repair booking service.
+export const fastify = {
+    id: "fastify",
+    name: "Fastify",
+    prefix: "FASTIFY",
+    about: "APIs in Fastify: a schema on every route, for what comes in and what goes out, a body limit chosen on purpose, one error handler, and plugins that keep to themselves. It builds on the Node profile.",
+    stacks: ["fastify"],
+    extends: ["node"],
+    rules: [
+        {
+            id: "FASTIFY-01",
+            title: "Every route has a schema, in and out",
+            rule: "Every route declares schemas for its body, parameters, query and responses, so Fastify checks what comes in and sends only the fields the response schema names.",
+            why: "Without a response schema, Fastify sends whatever the handler returns, including fields the client should never see.",
+            ask: "Does every route in this change declare its request and response schemas?",
+            stage: "prototype",
+            check: "ai-review",
+            severity: "high",
+            carries: "SEC-05",
+        },
+        {
+            id: "FASTIFY-02",
+            title: "Request bodies stay under {value}",
+            rule: "`bodyLimit` stays at {value} or below, raised only for a route that needs more, such as an upload.",
+            why: "Raising the limit for everything lets one request fill the server's memory.",
+            ask: "Does this change raise the body limit beyond {value}, or for more than the routes that need it?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "BE-02",
+            default: { value: "1 MiB" },
+        },
+        {
+            id: "FASTIFY-03",
+            title: "One error handler keeps internals in",
+            rule: "`setErrorHandler` answers every error in the project's error shape, with a generic message for anything unexpected, and the detail kept for the log.",
+            why: "Fastify's default handler sends the error's own message, even on a 500, which can carry query text or table names.",
+            ask: "Could an error in this change reach the client with its own message?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "SEC-09",
+        },
+        {
+            id: "FASTIFY-04",
+            title: "Plugins keep what they add to themselves",
+            rule: "A plugin's decorators and hooks stay inside it. One is shared with `fastify-plugin` only when the whole app needs it, and says so.",
+            why: "Sharing everything by default makes each plugin depend on the others' insides, so none can change alone.",
+            ask: "Does this change share a plugin's decorators or hooks beyond the code that needs them?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "low",
+            carries: "ARC-03",
+        },
+    ],
+};

package/dist/profiles/github-actions.d.ts

@@ -0,0 +1,2 @@
+import type { ProfileInput } from "../profile.ts";
+export declare const githubActions: ProfileInput;