peer-ai-standards 1.0.0-next.0

package/dist/core/code-quality.js

@@ -0,0 +1,179 @@
+// What makes code good in any language: naming, size, duplication, errors and types.
+export const codeQuality = [
+    {
+        id: "CODE-01",
+        domain: "code-quality",
+        title: "Names say what things are",
+        rule: "A name says what the thing is, in the language's own style: `amountMinor` or `amount_minor`, not `amt`; `profileId` or `profile_id`, not `pid`.",
+        why: "Code is read far more often than it's written. An abbreviation saves the writer a second and costs every reader a guess.",
+        ask: "Could someone new to the code understand every name in this change without asking?",
+        stage: "prototype",
+        check: "ai-review",
+        severity: "low",
+    },
+    {
+        id: "CODE-02",
+        domain: "code-quality",
+        title: "True-or-false values read as statements",
+        rule: "A true-or-false value is named as a statement, such as `isPublished`, `hasError` or `canBook` (or `is_published` where the language uses snake_case).",
+        why: "`published` could mean a date, a flag or a count; `isPublished` can only mean one thing.",
+        ask: "Does every true-or-false value in this change read as a statement?",
+        stage: "prototype",
+        check: "ai-review",
+        severity: "low",
+    },
+    {
+        id: "CODE-03",
+        domain: "code-quality",
+        title: "Things are named the way the people using the product name them",
+        rule: "Code, screens and design tokens use the words the people using the product use: a person manages notifications, not webhook config.",
+        why: "When the code and the product use different words, every conversation needs a translator, and mistakes hide in the translation.",
+        ask: "Do the names in this change match the words on the screen and in the requirements?",
+        stage: "prototype",
+        check: "ai-review",
+        severity: "low",
+    },
+    {
+        id: "CODE-04",
+        domain: "code-quality",
+        title: "Rule of three",
+        rule: "Copy code freely once, note it the second time, and move it into one shared place the third time.",
+        why: "A shared piece built too early is harder to remove than three similar ones, because everything comes to depend on it.",
+        ask: "Is anything in this change repeated for the third time, or shared before it was needed?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "low",
+    },
+    {
+        id: "CODE-05",
+        domain: "code-quality",
+        title: "Rules that must never disagree are shared on the first repeat",
+        rule: "Money maths, validation, permission checks and safety-critical logic are moved into one shared place the first time they're repeated, not the third.",
+        why: "Two copies of a rule eventually disagree. When the rule is money, safety or who may see what, the disagreement is a wrong charge, a harmed person or a data leak.",
+        ask: "Is any money, validation, permission or safety logic written more than once?",
+        stage: "prototype",
+        check: "ai-review",
+        severity: "high",
+    },
+    {
+        id: "CODE-06",
+        domain: "code-quality",
+        title: "A deliberate copy names its twin",
+        rule: "If a rule truly has to live in two places, each copy says where the other one is.",
+        why: "Copies drift apart silently when nobody knows the other exists.",
+        ask: "Does every deliberate copy of logic point to its twin?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+    },
+    {
+        id: "CODE-07",
+        domain: "code-quality",
+        title: "A function does one thing",
+        rule: "A function has one reason to change.",
+        why: "A function that does two things can't change one of them without risking the other, and its tests have to cover both.",
+        ask: "Does each function this change touches do one thing?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+    },
+    {
+        id: "CODE-08",
+        domain: "code-quality",
+        title: "Comments explain why; the code explains what",
+        rule: "If code needs a comment to explain what it does, it's too long or badly named. Comments that explain why are welcome.",
+        why: "Comments about what code does go out of date when the code changes. The reasons behind it last.",
+        ask: "Does any comment in this change explain what the code does, rather than why?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "low",
+    },
+    {
+        id: "CODE-09",
+        domain: "code-quality",
+        title: "Deep nesting becomes early returns",
+        rule: "When conditions nest deeply, handle the simple cases first and return, so the main path reads straight down. Each profile sets how deep is too deep.",
+        why: "Every level of nesting is one more thing a reader has to hold in mind.",
+        ask: "Is any code nested more deeply than its profile allows?",
+        stage: "mvp",
+        check: "auto",
+        severity: "low",
+    },
+    {
+        id: "CODE-10",
+        domain: "code-quality",
+        title: "Size prompts a question",
+        rule: "A function, component or module that grows past its profile's size limit prompts a question: is it doing two things, and what could move out? Size alone isn't a defect.",
+        why: "Large units usually hide a second job, and the limit is the reminder to look for it.",
+        ask: "Has anything grown past its size limit, and has someone asked whether it's doing two things?",
+        stage: "mvp",
+        check: "auto",
+        severity: "low",
+    },
+    {
+        id: "CODE-11",
+        domain: "code-quality",
+        title: "No swallowed errors",
+        rule: "An error is never caught and ignored. Where ignoring one is genuinely right, such as cleanup that mustn't fail the work it cleans up after, it's logged, and the reason is written beside it.",
+        why: "A swallowed error turns a loud, fixable failure into silent wrong behaviour that surfaces weeks later.",
+        ask: "Is any error caught and dropped without being logged and explained?",
+        stage: "prototype",
+        check: "auto",
+        severity: "high",
+    },
+    {
+        id: "CODE-12",
+        domain: "code-quality",
+        title: "Catching every kind of error needs a reason",
+        rule: "Catching every kind of error at once needs a comment saying what's expected and why it's safe to handle them all the same way.",
+        why: "A catch-all also catches the bugs nobody expected, and hides them.",
+        ask: "Does every catch-all in this change say what it expects and why?",
+        stage: "mvp",
+        check: "auto",
+        severity: "medium",
+    },
+    {
+        id: "CODE-13",
+        domain: "code-quality",
+        title: "Impossible states can't be written down",
+        rule: "When something has distinct states, such as loading, failed and ready, it's one status value, not several true-or-false flags that can contradict each other.",
+        why: "Three flags allow eight combinations, and most of them make no sense. One status allows only the real ones.",
+        ask: "Could any combination of flags in this change describe a state that can't really happen?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+    },
+    {
+        id: "CODE-14",
+        domain: "code-quality",
+        title: "Types are strict",
+        rule: "Where the language has types, they're strict. No escape-hatch type, such as TypeScript's `any` or Python's `Any`, where a real type exists: data of unknown shape is checked and narrowed.",
+        why: "An escape-hatch type switches the checks off exactly where the data is least trusted.",
+        ask: "Does this change use an escape-hatch type where a real type exists?",
+        stage: "prototype",
+        check: "auto",
+        severity: "medium",
+    },
+    {
+        id: "CODE-15",
+        domain: "code-quality",
+        title: "Edge cases are handled",
+        rule: "Code gives the right answer at the edges of what it can receive: time zones and daylight saving, empty and very long input, ties and equal values, the first and last item, and zero.",
+        why: "Most bugs live at the edges. The ordinary path is the one everyone tries, so it's rarely where things break.",
+        ask: "Does this change give the right answer at its edges: time zones, empty or huge input, ties, first and last, and zero?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+    },
+    {
+        id: "CODE-16",
+        domain: "code-quality",
+        title: "The framework's own rules are kept",
+        rule: "Where a framework needs code written a certain way to work, such as React's rules for hooks, that way is followed, and checked by a tool where one exists.",
+        why: "A framework's rules protect assumptions the types can't see. Breaking one gives bugs that appear far from their cause, often only sometimes.",
+        ask: "Does this change break a rule its framework depends on?",
+        stage: "prototype",
+        check: "ai-review",
+        severity: "medium",
+    },
+];

package/dist/core/data.d.ts

@@ -0,0 +1,45 @@
+export declare const data: ({
+    id: string;
+    domain: "data";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "auto";
+    severity: "high";
+    when?: never;
+} | {
+    id: string;
+    domain: "data";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "prototype";
+    check: "ai-review";
+    severity: "critical";
+    when?: never;
+} | {
+    id: string;
+    domain: "data";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "medium";
+    when: "uploads"[];
+} | {
+    id: string;
+    domain: "data";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "auto";
+    severity: "medium";
+    when?: never;
+})[];

package/dist/core/data.js

@@ -0,0 +1,59 @@
+// Databases, migrations, stored files, and data kept on a person's device.
+export const data = [
+    {
+        id: "DATA-01",
+        domain: "data",
+        title: "Migrations are the only source of truth for the database's structure",
+        rule: "The database's structure comes only from migrations. Tools that shape a database straight from the code are for experiments, never for a database that matters.",
+        why: "Those tools can't produce everything a migration can, such as triggers or partial indexes, and they can drop data without asking.",
+        ask: "Does this change shape a real database any way other than a migration?",
+        stage: "mvp",
+        check: "auto",
+        severity: "high",
+    },
+    {
+        id: "DATA-02",
+        domain: "data",
+        title: "A model change ships with its migration",
+        rule: "A change to how data is modelled ships with its migration, in the same pull request, and CI checks that they match.",
+        why: "A model without its migration works on the developer's machine and fails everywhere else.",
+        ask: "Does every model change in this change come with its migration?",
+        stage: "mvp",
+        check: "auto",
+        severity: "high",
+    },
+    {
+        id: "DATA-03",
+        domain: "data",
+        title: "A change to stored data never loses it",
+        rule: "A migration or app update keeps existing data. Renaming or reshaping moves the data across. A table, column or storage key is removed only after its data has moved and nothing reads it: add, migrate, then remove. This includes data stored on a person's device.",
+        why: "Lost data can't be fixed by the next release. It's gone, along with the trust of everyone who lost it.",
+        ask: "Does this change remove, rename or reshape stored data without moving what's already there?",
+        stage: "prototype",
+        check: "ai-review",
+        severity: "critical",
+    },
+    {
+        id: "DATA-04",
+        domain: "data",
+        title: "Deleting a record deletes its files",
+        rule: "When a record is deleted, the files that belong to it are deleted too.",
+        why: "Orphaned files keep personal data long after the person asked for it to go, and cost money to store.",
+        ask: "Does deleting a record in this change also delete its files?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+        when: ["uploads"],
+    },
+    {
+        id: "DATA-05",
+        domain: "data",
+        title: "Export and import round-trip exactly",
+        rule: "Where the product offers export and import, importing an export gives back exactly what was exported, and a test proves it.",
+        why: "An export people can't restore from exactly is a backup that fails on the day it's needed.",
+        ask: "If this change affects export or import, does a test prove they still round-trip exactly?",
+        stage: "mvp",
+        check: "auto",
+        severity: "medium",
+    },
+];

package/dist/core/delivery.d.ts

@@ -0,0 +1,153 @@
+export declare const delivery: ({
+    id: string;
+    domain: "delivery";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "prototype";
+    check: "auto";
+    severity: "medium";
+    sources?: never;
+} | {
+    id: string;
+    domain: "delivery";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "low";
+    sources?: never;
+} | {
+    id: string;
+    domain: "delivery";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "auto";
+    severity: "high";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+} | {
+    id: string;
+    domain: "delivery";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "auto";
+    severity: "high";
+    sources?: never;
+} | {
+    id: string;
+    domain: "delivery";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "auto";
+    severity: "medium";
+    sources?: never;
+} | {
+    id: string;
+    domain: "delivery";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "high";
+    sources?: never;
+} | {
+    id: string;
+    domain: "delivery";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "production";
+    check: "ai-review";
+    severity: "medium";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+} | {
+    id: string;
+    domain: "delivery";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "production";
+    check: "auto";
+    severity: "medium";
+    sources?: never;
+} | {
+    id: string;
+    domain: "delivery";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "high";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+} | {
+    id: string;
+    domain: "delivery";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "production";
+    check: "auto";
+    severity: "medium";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+} | {
+    id: string;
+    domain: "delivery";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "mvp";
+    check: "ai-review";
+    severity: "medium";
+    sources?: never;
+} | {
+    id: string;
+    domain: "delivery";
+    title: string;
+    rule: string;
+    why: string;
+    ask: string;
+    stage: "production";
+    check: "ai-review";
+    severity: "high";
+    sources: {
+        name: string;
+        ref: string;
+        url: string;
+    }[];
+})[];

package/dist/core/delivery.js

@@ -0,0 +1,149 @@
+// Dependencies, the pipeline every change goes through, and how changes reach people.
+const ASVS = "OWASP ASVS 5.0";
+const V15 = "https://github.com/OWASP/ASVS/blob/master/5.0/en/0x24-V15-Secure-Coding-and-Architecture.md";
+const MASVS = "OWASP MASVS 2.1.0";
+export const delivery = [
+    {
+        id: "DEL-01",
+        domain: "delivery",
+        title: "Versions are pinned and the lockfile is committed",
+        rule: 'Every dependency names the exact version that was tested, never "latest", and the lockfile is committed.',
+        why: '"Whatever is newest today" isn\'t a version. A build that pulls in different code tomorrow can break, or be compromised, without anyone changing a line.',
+        ask: "Does this change add a dependency without an exact version, or leave the lockfile out?",
+        stage: "prototype",
+        check: "auto",
+        severity: "medium",
+    },
+    {
+        id: "DEL-02",
+        domain: "delivery",
+        title: "A new dependency is justified",
+        rule: "A new dependency comes with a reason in the pull request: what it does, why nothing already there does it, and what it brings with it.",
+        why: "Every dependency is code you didn't write and have to trust, update and secure for as long as you use it.",
+        ask: "Does every new dependency in this change say why it's needed?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "low",
+    },
+    {
+        id: "DEL-03",
+        domain: "delivery",
+        title: "Dependencies are watched for vulnerabilities, and each is fixed in a set time",
+        rule: "Dependencies are checked for known vulnerabilities on every change and at least daily, and each vulnerability is fixed within a set time for its severity.",
+        why: "Most attacks on software use vulnerabilities that were already public, in components nobody updated. New ones are published every day about code that's already running, so checking only when something changes misses them.",
+        ask: "Does this change leave a dependency with a known vulnerability past its time to fix?",
+        stage: "mvp",
+        check: "auto",
+        severity: "high",
+        sources: [
+            { name: ASVS, ref: "15.2.1, level 1", url: V15 },
+            { name: MASVS, ref: "MASVS-CODE-3", url: "https://github.com/OWASP/masvs/blob/master/controls/MASVS-CODE-3.md" },
+        ],
+    },
+    {
+        id: "DEL-04",
+        domain: "delivery",
+        title: "Every change passes the same required checks before it merges",
+        rule: "Every change passes the same automated checks before it merges: formatting, linting, types, tests, secret scanning, dependency checks and code scanning. The checks are required, not advisory.",
+        why: "A check that can be skipped will be skipped, on the day it would have caught something.",
+        ask: "Does this change merge only after passing every required check?",
+        stage: "mvp",
+        check: "auto",
+        severity: "high",
+    },
+    {
+        id: "DEL-05",
+        domain: "delivery",
+        title: "No check only reports",
+        rule: "Every check in the pipeline fails the build when it finds a problem. None is set to report and carry on.",
+        why: "A check that reports without failing gives the same green as a clean pass, so nobody reads it.",
+        ask: "Is any check in this change set to report without failing the build?",
+        stage: "mvp",
+        check: "auto",
+        severity: "medium",
+    },
+    {
+        id: "DEL-06",
+        domain: "delivery",
+        title: "Changes reach production only through the pipeline",
+        rule: "Changes reach production only through the pipeline, never by hand from someone's computer.",
+        why: "A change made by hand skips every check, and nobody can say afterwards exactly what's running.",
+        ask: "Could any change in this project reach production without going through the pipeline?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "high",
+    },
+    {
+        id: "DEL-07",
+        domain: "delivery",
+        title: "Only what's needed ships to production",
+        rule: "Production gets only what the product needs to run: no test code, sample code, development tools or debug features.",
+        why: "Every extra piece in production is something an attacker can find and use.",
+        ask: "Does this change ship test, sample or development code to production?",
+        stage: "production",
+        check: "ai-review",
+        severity: "medium",
+        sources: [{ name: ASVS, ref: "15.2.3, level 2", url: V15 }],
+    },
+    {
+        id: "DEL-08",
+        domain: "delivery",
+        title: "The running app is scanned before it's released",
+        rule: "Before a release reaches production, a scanner tests the running app in staging from the outside, the way an attacker would. Every finding is fixed or recorded as an accepted risk. The scan runs only against the project's own staging, never production or anyone else's system.",
+        why: "Code scanning reads the code. It can't see a server that's set up wrongly, a debug page left switched on or a missing security header. Only testing the running app finds those.",
+        ask: "Was the running app scanned in staging before this release, and is every finding fixed or accepted?",
+        stage: "production",
+        check: "auto",
+        severity: "medium",
+    },
+    {
+        id: "DEL-09",
+        domain: "delivery",
+        title: "Packages come only from the registry you expect",
+        rule: "Every dependency, and everything it depends on, is installed from the registry the project expects. A name the project uses for its own private packages can't be served from a public registry instead.",
+        why: "If a private package's name is free on a public registry, anyone can publish a package under it with a higher version, and a build that looks in both places installs theirs. This is called dependency confusion.",
+        ask: "Could any dependency in this change be installed from a registry the project doesn't expect?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "high",
+        sources: [
+            { name: ASVS, ref: "15.2.4, level 3", url: V15 },
+            { name: ASVS, ref: "15.1.2, level 2", url: V15 },
+        ],
+    },
+    {
+        id: "DEL-10",
+        domain: "delivery",
+        title: "There's a current list of every dependency",
+        rule: "The project keeps a list of every dependency it ships, direct and indirect, with its version and where it comes from, such as a software bill of materials, and updates it with every release.",
+        why: "When a vulnerability is announced, the first question is whether you use the affected package. Without a list, answering takes days; with one, it's a search.",
+        ask: "Is the list of dependencies up to date for this release?",
+        stage: "production",
+        check: "auto",
+        severity: "medium",
+        sources: [{ name: ASVS, ref: "15.1.2, level 2", url: V15 }],
+    },
+    {
+        id: "DEL-11",
+        domain: "delivery",
+        title: "Every dependency's licence allows how the product uses it",
+        rule: "Each dependency's licence is known and allows how the product is used and distributed. A licence that would require publishing the product's own code, or that forbids commercial use, needs a person's decision before the dependency is added.",
+        why: "A licence is a legal agreement. One that doesn't fit can force a product to publish its code or stop selling it, and it's cheapest to catch before the code depends on it.",
+        ask: "Does this change add a dependency whose licence doesn't fit how the product is used?",
+        stage: "mvp",
+        check: "ai-review",
+        severity: "medium",
+    },
+    {
+        id: "DEL-12",
+        domain: "delivery",
+        title: "Risky dependencies are chosen on purpose",
+        rule: "A dependency that runs code when it's installed, is no longer maintained, or has a name one slip away from a better-known package is checked before it's added, and kept only with a written reason.",
+        why: "Attackers take over abandoned packages and publish look-alike names, and a package that runs code when it's installed runs it on every developer's machine and every build.",
+        ask: "Does this change add a dependency that runs code when installed, is no longer maintained, or looks like another package's name?",
+        stage: "production",
+        check: "ai-review",
+        severity: "high",
+        sources: [{ name: ASVS, ref: "15.1.4, level 3", url: V15 }],
+    },
+];