peer-ai 1.0.0-next.0

package/dist/assess.js

@@ -0,0 +1,545 @@
+// peer-ai assess: reads a repository and records, for each item on the project map, whether
+// it is present, partial, missing or not applicable, with the files that prove it. Items found
+// by reading code rather than a document are marked inferred, for a person to confirm.
+// Gaps are ranked by the project's stage: a prototype needs almost nothing, production a lot.
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { MAP_ITEM_IDS, TRAITS, readConfig, validateMap, } from "peer-ai-workflow";
+import { PROFILES, profilesForPart } from "peer-ai-standards";
+import { CONFIG_FILE, detect, detectDelivery, detectTracks } from "./detect.js";
+import { listRepoFiles } from "./files.js";
+export const MAP_FILE = ".peer-ai/map.json";
+export const MAP_SCHEMA_URL = "https://raw.githubusercontent.com/AbuMahir980/peer-ai/main/packages/workflow/schemas/map.schema.json";
+/** What each stage needs. Items not applicable to a project are never required. */
+export const REQUIRED = {
+    prototype: [],
+    mvp: ["requirements", "api-contract", "ci", "tests", "threat-model", "data-inventory", "docs"],
+    production: [
+        "requirements",
+        "api-contract",
+        "ci",
+        "tests",
+        "threat-model",
+        "data-inventory",
+        "docs",
+        "architecture",
+        "specs",
+        "data-model",
+        "dpia",
+        "design",
+        "standards",
+        "environments",
+        "infrastructure",
+        "observability",
+        "slos",
+        "runbooks",
+        "load-testing",
+    ],
+};
+export const NEXT_STAGE = {
+    prototype: "mvp",
+    mvp: "production",
+    production: undefined,
+};
+export const UI_KINDS = ["web", "mobile", "desktop", "extension"];
+export const MANIFEST = /(^|\/)(package\.json|requirements[^/]*\.txt|pyproject\.toml|pubspec\.yaml|Gemfile|go\.mod|Cargo\.toml|composer\.json|build\.gradle(\.kts)?|pom\.xml|[^/]+\.csproj|Directory\.Packages\.props|Package\.swift|Podfile|mix\.exs)$/;
+// Where a project describes its data: migrations and schema files, and the model or entity
+// classes that ORMs in any language read, such as models/order.py, app/Models/Order.php,
+// Entities/Order.cs or order.entity.ts.
+export const SCHEMA_FILE = /(^|\/)(migrations?|migrate|alembic|prisma|drizzle|supabase|db|database)\/.*\.(sql|prisma|py|ts|js|rb|php|cs|go|java|kt|rs|exs?)$|\.sql$|schema\.prisma$|(^|\/)(models?|entities|entity|schemas?)\/[^/]+\.(py|ts|js|rb|php|cs|go|java|kt|rs|swift|ex)$|(^|\/)models?\.(py|ts|js|go|rs)$|\.(entity|model|schema)\.[cm]?[jt]s$/i;
+// Field names are matched as whole words, where an underscore also separates words, so a prefixed
+// name such as recipient_phone counts but iphone doesn't. camelCase names are split into words
+// first (see snakeCase), so recipientPhone and phoneNumber count too.
+export const PERSONAL_FIELD = /(?<![a-z0-9])(email|phone(?:_number)?|mobile_number|date_of_birth|dob|birth_?date|home_address|address(?:_line_?\d)?|post_?code|zip_?code|bvn|nin|ssn|national_id|passport(?:_number)?|ip_address|latitude|longitude)(?![a-z0-9])/gi;
+const CARD_FIELD = /(?<![a-z0-9])(card_?number|card_no|pan|cvv2?|cvc|card_expiry)(?![a-z0-9])/gi;
+const PAYMENT_PROVIDER = /\b(stripe|paystack|flutterwave|braintree|adyen|razorpay|paypal|squareup|mollie|monnify|interswitch)\b/gi;
+const OBSERVABILITY = /(@sentry\/[\w-]+|\bsentry[\w-]*|@opentelemetry\/[\w-]+|\bopentelemetry[\w-]*|\bdd-trace\b|\bdatadog\b|\bnewrelic\b|\bprom-client\b|\bprometheus[\w-]*|\bpino\b|\bwinston\b|\bstructlog\b|\bloguru\b|\blogfire\b|go\.uber\.org\/zap|\bzerolog\b|\bmicrometer[\w-]*|\bserilog[\w.]*|\bmonolog\b|\blograge\b|\btracing-subscriber\b)/gi;
+const LOCAL_SCHEMA_FILE = /(^|\/)(db|database|schema|storage|store|models?)\.(ts|tsx|js|mjs)$/i;
+const LOCAL_SCHEMA = /\.stores\(\s*\{|indexedDB\.open\(|\bopenDB\(|\bappSchema\(|CREATE TABLE/;
+export const INFRASTRUCTURE_AS_CODE = /\.tf$|\.tf\.json$|\.bicep$|\.cfn\.(ya?ml|json)$|(^|\/)(Pulumi\.ya?ml|cdk\.json|Chart\.yaml|kustomization\.ya?ml|serverless\.ya?ml|samconfig\.toml)$/;
+// Libraries that suggest a trait, found by name in dependency files. A suggestion is only that:
+// the evidence is shown, and a person decides.
+export const TRAIT_LIBRARIES = [
+    [
+        "offline",
+        /(workbox[\w-]*|vite-plugin-pwa|next-pwa|@serwist\/[\w-]+|\bdexie\b|\brxdb\b|\bpouchdb[\w-]*|@nozbe\/watermelondb|\bsqflite\b|\bdrift\b|androidx\.room)/gi,
+    ],
+    [
+        "real-time",
+        /(@nestjs\/websockets|socket\.io[\w-]*|\bwebsockets?\b|gorilla\/websocket|\bpusher[\w-]*|\bably\b|@supabase\/realtime-js|\bsignalr\b|\bactioncable\b|\bcentrifuge[\w-]*)/gi,
+    ],
+    [
+        "uploads",
+        /(\bmulter\b|\bbusboy\b|\bformidable\b|@fastify\/multipart|python-multipart|\buploadthing\b|react-dropzone|@uppy\/[\w-]+|\bfilepond\b|expo-image-picker|expo-document-picker|\bimage_picker\b|\bfile_picker\b|\bcarrierwave\b|\bshrine\b|\bcloudinary\b)/gi,
+    ],
+    [
+        "ai-features",
+        /(@anthropic-ai\/sdk|\banthropic\b|@ai-sdk\/[\w-]+|\bopenai\b|@langchain\/[\w-]+|\blangchain[\w-]*|llama[-_]?index|@google\/(?:generative-ai|genai)|google-(?:generativeai|genai)|@mistralai\/[\w-]+|\bmistralai\b|groq-sdk|\bollama\b|\breplicate\b|\bhuggingface[\w-]*|semantickernel|spring-ai[\w-]*|langchain4j)/gi,
+    ],
+];
+const SERVICE_WORKER = /(^|\/)(service-worker|sw)\.[cm]?[jt]s$/;
+const TENANT_FIELD = /(?<![a-z0-9])(tenant_?id|organi[sz]ation_?id|org_?id|workspace_?id)(?![a-z0-9])/gi;
+const SAFETY_FIELD = /(?<![a-z0-9])(allerg(?:en|ens|y|ies)|medications?|dosage|contraindications?|blood_type|diagnos[ie]s)(?![a-z0-9])/gi;
+// A copy of the v0 playbook, which 1.0 replaces, recognised by its setup files. Its templates
+// would otherwise read as the project's own requirements, specs and standards.
+export const LEGACY_PLAYBOOK = "peer-ai/";
+export const LEGACY_MARKERS = ["peer-ai/shared/00-setup.md", "peer-ai/phase-config.json"];
+export const TEST_FILE = /(^|\/)(tests?|Tests|__tests__|integration_test|spec|e2e)\/|(^|\/)[^/]+\.Tests?\/|[._-](test|spec)\.[cm]?[jt]sx?$|_test\.(go|dart|py|exs)$|(^|\/)test_[^/]+\.py$|_spec\.rb$|(Tests?|Spec)\.(swift|kt|java|cs|php)$/;
+// A written test strategy: a start on the tests item, never a substitute for tests.
+const TEST_STRATEGY = /(^|\/)docs\/[^/]*test[-_]?strategy[^/]*\.md$/i;
+const clip = (text, max = 200) => (text.length <= max ? text : `${text.slice(0, max - 1)}…`);
+const unique = (values) => [...new Set(values)];
+function matching(ctx, pattern) {
+    return ctx.files.filter((file) => pattern.test(file));
+}
+/** Up to five pieces of evidence, preferring the folder when many files share one. */
+function evidence(files, collapseTo) {
+    const shown = collapseTo === undefined ? files : files.map((file) => collapseTo.exec(file)?.[0] ?? file);
+    return unique(shown).sort().slice(0, 5);
+}
+/**
+ * Splits camelCase and PascalCase names into words the way snake_case already is, so phoneNumber
+ * reads as phone_Number and IPAddress as IP_Address. A lone leading "i", as in iPhone, stays part
+ * of its word.
+ */
+export function snakeCase(text) {
+    return text.replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/(?<=[a-z0-9])(?<!(?:^|[^A-Za-z0-9])i)(?=[A-Z])/g, "_");
+}
+function scan(ctx, files, pattern, prepare = (text) => text) {
+    const found = new Map();
+    for (const file of files) {
+        for (const match of prepare(ctx.read(file)).matchAll(pattern)) {
+            const name = match[1]?.toLowerCase() ?? match[0].toLowerCase();
+            if (!found.has(name))
+                found.set(name, file);
+        }
+    }
+    return [...found].map(([name, file]) => ({ name, file }));
+}
+export function collectSignals(ctx) {
+    const schemaFiles = matching(ctx, SCHEMA_FILE);
+    const manifests = matching(ctx, MANIFEST);
+    return {
+        personalData: scan(ctx, schemaFiles, PERSONAL_FIELD, snakeCase),
+        cardData: scan(ctx, schemaFiles, CARD_FIELD, snakeCase),
+        paymentProviders: scan(ctx, manifests, PAYMENT_PROVIDER).map((finding) => finding.name),
+    };
+}
+function trackEvidence(tracks) {
+    return tracks.map((track) => track.path ?? ".");
+}
+/**
+ * Traits the code suggests, with what suggested each. Traits the config already declares are left
+ * out. Several apps on one backend count, even when the backend lives in another repository.
+ */
+function suggestTraits(ctx, signals, tracks) {
+    const found = new Map();
+    const suggest = (trait, evidence) => {
+        if (evidence !== undefined && !found.has(trait))
+            found.set(trait, evidence);
+    };
+    const first = (findings) => findings[0] === undefined ? undefined : `${findings[0].name} in ${findings[0].file}`;
+    const schemaFiles = matching(ctx, SCHEMA_FILE);
+    const manifests = matching(ctx, MANIFEST);
+    if (signals.paymentProviders.length > 0)
+        suggest("money", `payment provider ${signals.paymentProviders.join(", ")}`);
+    suggest("money", first(signals.cardData));
+    suggest("safety-critical", first(scan(ctx, schemaFiles, SAFETY_FIELD, snakeCase)));
+    const apps = tracks.filter((track) => UI_KINDS.includes(track.kind) && track.status !== "dormant");
+    if (apps.length > 1 && tracks.some((track) => track.kind === "backend")) {
+        suggest("several-audiences", `${String(apps.length)} apps (${apps.map((track) => track.id).join(", ")}) share a backend`);
+    }
+    suggest("several-audiences", first(scan(ctx, schemaFiles, TENANT_FIELD, snakeCase)));
+    const worker = matching(ctx, SERVICE_WORKER)[0];
+    suggest("offline", worker === undefined ? undefined : `a service worker, ${worker}`);
+    for (const [trait, pattern] of TRAIT_LIBRARIES)
+        suggest(trait, first(scan(ctx, manifests, pattern)));
+    const declared = ctx.config?.project.traits ?? [];
+    return TRAITS.flatMap((trait) => {
+        const evidence = found.get(trait);
+        return evidence === undefined || declared.includes(trait) ? [] : [{ trait, evidence }];
+    });
+}
+const present = (files) => ({ status: "present", evidence: files });
+const RULES = {
+    requirements: (ctx) => {
+        const docs = matching(ctx, /(^|\/)(PRODUCT|PRD|REQUIREMENTS|BRIEF)([^a-z/][^/]*)?\.md$|(^|\/)docs\/[^/]*(requirement|product-brief|prd|brief)[^/]*\.md$/i);
+        return docs.length > 0 ? present(evidence(docs)) : { status: "missing" };
+    },
+    architecture: (ctx) => {
+        const docs = matching(ctx, /(^|\/)ARCHITECTURE\.md$|(^|\/)docs\/[^/]*architecture[^/]*\.md$|(^|\/)(adr|adrs|decisions)\/[^/]+\.md$/i);
+        if (docs.length > 0)
+            return present(evidence(docs, /^(.*\/)?(adr|adrs|decisions)\//i));
+        if (ctx.tracks.length === 0)
+            return { status: "missing" };
+        const parts = ctx.tracks.map((track) => `${track.id} (${track.kind})`).join(", ");
+        return {
+            status: "partial",
+            evidence: trackEvidence(ctx.tracks),
+            inferred: true,
+            note: clip(`No architecture document. From the code: ${String(ctx.tracks.length)} parts: ${parts}.`),
+        };
+    },
+    "threat-model": (ctx) => {
+        const docs = matching(ctx, /threat[-_ ]?model/i);
+        return docs.length > 0 ? present(evidence(docs)) : { status: "missing" };
+    },
+    specs: (ctx) => {
+        const docs = matching(ctx, /(^|\/)docs\/.*spec[^/]*\.md$|(^|\/)specs?\/[^/]+\.md$|^[^/]*\b(spec|specs|specification)\b[^/]*\.md$/i);
+        return docs.length > 0 ? present(evidence(docs)) : { status: "missing" };
+    },
+    "api-contract": (ctx) => {
+        const configured = (ctx.config?.apis ?? [])
+            .map((api) => api.contract?.location)
+            .filter((location) => location !== undefined && existsSync(join(ctx.root, location)));
+        const files = matching(ctx, /(^|\/)(openapi|swagger|asyncapi)[^/]*\.(json|ya?ml)$|\.proto$|\.graphqls?$|(^|\/)docs\/[^/]*api-contract[^/]*\.md$/i);
+        const found = unique([...configured, ...files]);
+        if (found.length > 0)
+            return present(evidence(found));
+        const own = ctx.tracks.map((track) => track.id);
+        const apis = ctx.config?.apis ?? [];
+        const providesApi = ctx.tracks.some((track) => track.kind === "backend") ||
+            apis.some((api) => api.providedBy !== undefined && own.includes(api.providedBy));
+        if (!providesApi) {
+            const statusOf = new Map((ctx.config?.tracks ?? []).map((track) => [track.id, track.status]));
+            const providedWhile = (status) => apis
+                .filter((api) => api.providedBy !== undefined && statusOf.get(api.providedBy) === status)
+                .map((api) => api.id);
+            const elsewhere = providedWhile("external");
+            const later = providedWhile("dormant");
+            const note = elsewhere.length > 0
+                ? `Provided by another repository, where its contract lives: ${elsewhere.join(", ")}.`
+                : later.length > 0
+                    ? `Provided by a part that hasn't started yet: ${later.join(", ")}.`
+                    : "No API is provided by this repository.";
+            return { status: "not-applicable", note: clip(note), inferred: true };
+        }
+        return {
+            status: "missing",
+            note: "No contract file found. Frameworks such as NestJS, FastAPI and ASP.NET Core can generate one: commit it, or set its location in peer-ai.config.json.",
+        };
+    },
+    "data-model": (ctx) => {
+        const files = matching(ctx, /(^|\/)(migrations?|alembic|drizzle)\/|(^|\/)db\/migrate\/|schema\.prisma$|(^|\/)db\/schema\.(rb|sql)$|(^|\/)supabase\/migrations\//i);
+        // A written data model counts too, such as one designed before any migration exists.
+        const written = matching(ctx, /(^|\/)docs\/[^/]*data[-_]?model[^/]*\.md$/i);
+        if (files.length + written.length > 0) {
+            return present(evidence([...files, ...written], /^(.*\/)?(migrations?|alembic|drizzle|supabase\/migrations|db\/migrate)\/|^.*schema\.(prisma|rb|sql)$/i));
+        }
+        // An offline-first or mobile app keeps its database on the device, defined in code rather than
+        // in migration files: Dexie or idb for IndexedDB, WatermelonDB, or SQLite tables.
+        const onDevice = matching(ctx, LOCAL_SCHEMA_FILE).filter((file) => LOCAL_SCHEMA.test(ctx.read(file)));
+        if (onDevice.length > 0) {
+            return { ...present(evidence(onDevice)), note: "A database on the device, defined in code." };
+        }
+        if (ctx.tracks.some((track) => track.kind === "backend"))
+            return { status: "missing" };
+        return { status: "not-applicable", note: "No database found in this repository.", inferred: true };
+    },
+    "data-inventory": (ctx, signals) => {
+        const configured = ctx.config?.compliance?.dataInventory;
+        const docs = matching(ctx, /data[-_ ]?inventory/i);
+        if (configured !== undefined && existsSync(join(ctx.root, configured)))
+            return present([configured]);
+        if (docs.length > 0)
+            return present(evidence(docs));
+        if (signals.personalData.length === 0) {
+            return {
+                status: "not-applicable",
+                note: "No personal-data fields found in the schema or migrations.",
+                inferred: true,
+            };
+        }
+        const names = signals.personalData.map((finding) => finding.name).join(", ");
+        return {
+            status: "missing",
+            note: clip(`Personal data in ${String(signals.personalData.length)} fields (${names}), and no inventory of it.`),
+        };
+    },
+    dpia: (ctx, signals) => {
+        const docs = matching(ctx, /dpia|data[-_ ]protection[-_ ]impact|impact[-_ ]assessment/i);
+        if (docs.length > 0)
+            return present(evidence(docs));
+        if (signals.personalData.length === 0) {
+            return {
+                status: "not-applicable",
+                note: "No personal-data fields found in the schema or migrations.",
+                inferred: true,
+            };
+        }
+        return { status: "missing" };
+    },
+    design: (ctx) => {
+        const reference = ctx.config?.design?.reference;
+        if (reference !== undefined && (/^https?:\/\//.test(reference) || existsSync(join(ctx.root, reference)))) {
+            return present([reference]);
+        }
+        const files = matching(ctx, /(^|\/)(design|designs|design_handoff[^/]*|mockups?|figma)\/|(^|\/)(design-)?tokens\.(json|ts|js|css)$|(^|\/)docs\/[^/]*design[-_]?system[^/]*\.md$/i);
+        if (files.length > 0)
+            return present(evidence(files, /^(.*\/)?(design|designs|design_handoff[^/]*|mockups?|figma)\//i));
+        if (ctx.tracks.some((track) => UI_KINDS.includes(track.kind)))
+            return { status: "missing" };
+        return { status: "not-applicable", note: "No user interface found.", inferred: true };
+    },
+    standards: (ctx) => {
+        const documents = (ctx.config?.standards?.documents ?? []).map((document) => document.path);
+        const written = matching(ctx, /(^|\/)docs\/.*(standard|coding-rules|conventions|style-guide).*\.md$|(^|\/)(STANDARDS|CONVENTIONS|STYLEGUIDE)[^/]*\.md$/i);
+        if (documents.length + written.length > 0)
+            return present(evidence([...documents, ...written]));
+        const linting = matching(ctx, /(^|\/)(eslint\.config\.[cm]?[jt]s|\.eslintrc[^/]*|biome\.jsonc?|ruff\.toml|\.flake8|\.pylintrc|\.golangci\.ya?ml|analysis_options\.yaml|\.rubocop\.yml|detekt\.yml|checkstyle[^/]*\.xml|\.swiftlint\.ya?ml|phpstan\.neon(\.dist)?|\.php-cs-fixer(\.dist)?\.php|clippy\.toml|\.credo\.exs)$/);
+        if (linting.length > 0) {
+            return {
+                status: "partial",
+                evidence: evidence(linting),
+                note: "Linting is configured, but there is no written standard.",
+            };
+        }
+        return { status: "missing" };
+    },
+    ci: (ctx) => {
+        // A pipeline in the repository counts whatever the config says: the config may predate it.
+        const found = detectDelivery(ctx.root);
+        if (found !== undefined)
+            return present([found.pipeline]);
+        const configured = ctx.config?.delivery;
+        if (configured?.ci === "existing")
+            return present([configured.pipeline ?? CONFIG_FILE]);
+        return { status: "missing" };
+    },
+    environments: (ctx) => {
+        if ((ctx.config?.environments ?? []).length > 0)
+            return present([CONFIG_FILE]);
+        const files = matching(ctx, /(^|\/)\.env\.(staging|production|prod)(\.example)?$|(^|\/)(environments|envs)\/|[._-](staging|production|prod)\.(ya?ml|json|toml|tfvars)$/i);
+        if (files.length > 0)
+            return present(evidence(files));
+        const deployed = ctx.tracks.filter((track) => track.deploy !== undefined);
+        if (deployed.length > 0) {
+            return {
+                status: "partial",
+                evidence: trackEvidence(deployed),
+                note: "Parts deploy, but no environments are defined.",
+            };
+        }
+        return { status: "missing" };
+    },
+    tests: (ctx) => {
+        const testFiles = matching(ctx, TEST_FILE);
+        const strategy = matching(ctx, TEST_STRATEGY);
+        const noTests = strategy.length > 0
+            ? { status: "partial", evidence: evidence(strategy), note: "A test strategy, but no tests yet." }
+            : { status: "missing" };
+        const parts = ctx.tracks.filter((track) => track.kind !== "infrastructure" && ["active", "frozen"].includes(track.status));
+        if (parts.length === 0)
+            return testFiles.length > 0 ? present(evidence(testFiles)) : noTests;
+        const inside = (track) => testFiles.filter((file) => track.path === undefined || file.startsWith(`${track.path}/`));
+        const tested = parts.filter((track) => inside(track).length > 0);
+        if (tested.length === 0)
+            return noTests;
+        if (tested.length === parts.length)
+            return present(trackEvidence(tested));
+        const untested = parts.filter((track) => !tested.includes(track)).map((track) => track.id);
+        return {
+            status: "partial",
+            evidence: trackEvidence(tested),
+            note: clip(`Tests in ${String(tested.length)} of ${String(parts.length)} parts; none in: ${untested.join(", ")}.`),
+        };
+    },
+    "load-testing": (ctx) => {
+        const files = matching(ctx, /(^|\/)(k6|load[-_]?tests?|perf)\/|\.k6\.[jt]s$|(^|\/)locustfile\.py$|artillery[^/]*\.ya?ml$|\.jmx$|k6-summary/i);
+        return files.length > 0 ? present(evidence(files)) : { status: "missing" };
+    },
+    infrastructure: (ctx) => {
+        const infra = ctx.tracks.filter((track) => track.kind === "infrastructure");
+        if (infra.length > 0)
+            return present(trackEvidence(infra));
+        const iac = matching(ctx, INFRASTRUCTURE_AS_CODE);
+        if (iac.length > 0)
+            return present(evidence(iac.map((file) => dirname(file))));
+        const deployed = ctx.tracks.filter((track) => track.deploy !== undefined);
+        if (deployed.length > 0) {
+            const targets = unique(deployed.map((track) => track.deploy)).join(", ");
+            return {
+                status: "partial",
+                evidence: trackEvidence(deployed),
+                note: clip(`Deployed through platform configuration (${targets}), with no infrastructure as code.`),
+            };
+        }
+        return { status: "missing" };
+    },
+    observability: (ctx) => {
+        const manifests = matching(ctx, MANIFEST);
+        const found = scan(ctx, manifests, OBSERVABILITY);
+        if (found.length === 0)
+            return { status: "missing" };
+        return {
+            status: "present",
+            evidence: evidence(found.map((finding) => finding.file)),
+            note: clip(`Found: ${unique(found.map((finding) => finding.name)).join(", ")}.`),
+        };
+    },
+    slos: (ctx) => {
+        const files = matching(ctx, /(^|\/)[^/]*\bslos?\b[^/]*\.(md|ya?ml|json)$|service[-_ ]level/i);
+        return files.length > 0 ? present(evidence(files)) : { status: "missing" };
+    },
+    runbooks: (ctx) => {
+        const files = matching(ctx, /runbook/i);
+        return files.length > 0 ? present(evidence(files, /^(.*\/)?runbooks?\//i)) : { status: "missing" };
+    },
+    docs: (ctx) => {
+        const readme = matching(ctx, /^README(\.md)?$/i);
+        const docs = matching(ctx, /^docs\/.*\.md$/i);
+        if (readme.length > 0 && docs.length > 0)
+            return present([...readme, "docs/"]);
+        if (readme.length > 0)
+            return { status: "partial", evidence: readme, note: "A README, but no docs folder." };
+        return { status: "missing" };
+    },
+};
+function tracksFromConfig(config) {
+    return config.tracks.map((track) => ({
+        id: track.id,
+        kind: track.kind,
+        ...(track.path === undefined ? {} : { path: track.path }),
+        ...(track.deploy === undefined ? {} : { deploy: track.deploy.target }),
+        status: track.status,
+    }));
+}
+export function assess(root, config, stage) {
+    const cache = new Map();
+    const read = (file) => {
+        const cached = cache.get(file);
+        if (cached !== undefined)
+            return cached;
+        const full = join(root, file);
+        const text = existsSync(full) && statSync(full).size <= 1_000_000 ? readFileSync(full, "utf8") : "";
+        cache.set(file, text);
+        return text;
+    };
+    const detected = config === undefined ? detect(root) : undefined;
+    const tracks = config === undefined
+        ? (detected?.tracks ?? []).map((track) => ({
+            id: track.id,
+            kind: track.kind,
+            ...(track.path === undefined ? {} : { path: track.path }),
+            ...(track.deploy === undefined ? {} : { deploy: track.deploy }),
+            status: "active",
+        }))
+        : tracksFromConfig(config);
+    const allFiles = listRepoFiles(root);
+    const legacyPlaybook = allFiles.some((file) => LEGACY_MARKERS.includes(file));
+    const files = legacyPlaybook ? allFiles.filter((file) => !file.startsWith(LEGACY_PLAYBOOK)) : allFiles;
+    // Parts in another repository, and parts not started yet, are listed but create no requirements.
+    const own = tracks.filter((track) => track.status !== "external" && track.status !== "dormant");
+    const ctx = { root, files, tracks: own, config, read };
+    const signals = collectSignals(ctx);
+    const items = Object.fromEntries(MAP_ITEM_IDS.map((id) => [id, RULES[id](ctx, signals)]));
+    return {
+        name: config?.project.name ?? detected?.name ?? "",
+        stage,
+        tracks,
+        items,
+        signals,
+        suggestedTraits: suggestTraits(ctx, signals, tracks),
+        suggestedProfiles: suggestProfiles(root, config, detected),
+        suggestedStacks: suggestStacks(root, config),
+        legacyPlaybook,
+    };
+}
+/**
+ * Profiles that fit each part's stack, from the config or, where it names none, from detection.
+ * Only the most specific fits: a profile another suggested or listed one extends isn't repeated.
+ */
+function suggestProfiles(root, config, detected) {
+    const listed = config?.standards?.profiles ?? [];
+    const found = detected?.tracks ?? detectTracks(root, config?.project.name ?? "");
+    const parts = (config?.tracks ?? found)
+        .filter((track) => !("status" in track) || track.status !== "external")
+        .map((track) => ({
+        id: track.id,
+        stack: track.stack ?? found.find((other) => (other.path ?? ".") === (track.path ?? "."))?.stack ?? [],
+    }));
+    const suggestions = new Map();
+    for (const part of parts) {
+        const covered = new Set(profilesForPart(listed, { stack: part.stack }).map((profile) => profile.id));
+        const fits = PROFILES.filter((profile) => profile.stacks.some((tag) => part.stack.includes(tag)) && !covered.has(profile.id));
+        // The profiles each fit builds on, without itself: a fit another fit builds on isn't repeated.
+        const builtOn = new Set(fits.flatMap((fit) => profilesForPart([fit.id], {})
+            .filter((base) => base.id !== fit.id)
+            .map((base) => base.id)));
+        for (const profile of fits) {
+            if (builtOn.has(profile.id) || suggestions.has(profile.id))
+                continue;
+            const tag = profile.stacks.find((each) => part.stack.includes(each));
+            if (tag !== undefined)
+                suggestions.set(profile.id, `${part.id} is tagged ${tag}`);
+        }
+    }
+    return [...suggestions].map(([profile, evidence]) => ({ profile, evidence }));
+}
+/** The stack detection finds in each part the config lists without one. */
+function suggestStacks(root, config) {
+    if (config === undefined)
+        return [];
+    const found = detectTracks(root, config.project.name);
+    return config.tracks.flatMap((track) => {
+        if (track.stack !== undefined || track.status === "external")
+            return [];
+        const stack = found.find((other) => (other.path ?? ".") === (track.path ?? "."))?.stack ?? [];
+        return stack.length === 0 ? [] : [{ track: track.id, stack }];
+    });
+}
+export function gaps(assessment, stage) {
+    return REQUIRED[stage].filter((id) => ["missing", "partial"].includes(assessment.items[id].status));
+}
+export function toMap(assessment, now) {
+    const at = now.toISOString();
+    const map = {
+        $schema: MAP_SCHEMA_URL,
+        version: 1,
+        assessedAt: at,
+        items: Object.fromEntries(MAP_ITEM_IDS.map((id) => {
+            const item = assessment.items[id];
+            return [
+                id,
+                {
+                    status: item.status,
+                    ...(item.evidence === undefined ? {} : { evidence: item.evidence }),
+                    ...(item.inferred === true ? { inferred: true } : {}),
+                    ...(item.note === undefined ? {} : { note: item.note }),
+                    checkedAt: at,
+                },
+            ];
+        })),
+    };
+    const result = validateMap(map);
+    if (!result.ok)
+        throw new Error(`assess built an invalid project map: ${result.errors.join("; ")}`);
+    return result.value;
+}
+/** Reads peer-ai.config.json, following a relative `extends`. Returns errors instead of throwing. */
+export const loadConfig = readConfig;
+export function runAssess(options, out, report) {
+    const { config, errors } = loadConfig(options.cwd);
+    if (errors !== undefined) {
+        out.error(`${CONFIG_FILE} is not valid:`);
+        for (const error of errors)
+            out.error(`  ${error}`);
+        return 2;
+    }
+    const stage = options.target ?? config?.project.stage ?? "mvp";
+    const assessment = assess(options.cwd, config, stage);
+    const map = toMap(assessment, options.now ?? new Date());
+    if (options.json)
+        out.log(JSON.stringify(map, null, 2));
+    else
+        for (const line of report(assessment, stage))
+            out.log(line);
+    if (!options.dryRun) {
+        const path = join(options.cwd, MAP_FILE);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(map, null, 2)}\n`);
+        if (!options.json)
+            out.log(`Wrote ${MAP_FILE}.`);
+    }
+    return 0;
+}

package/dist/check.d.ts

@@ -0,0 +1,30 @@
+import { type PeerAiConfig, type WorkItem } from "peer-ai-workflow";
+import { type Assessment } from "./assess.ts";
+import { type Check } from "./checks.ts";
+import type { Output, Stage } from "./init.ts";
+export interface Verdict {
+    name: string;
+    stage: Stage;
+    ok: boolean;
+    checks: Check[];
+    /** What doctor would fail on, which fails the build too (RFC 0007), and a count of its warnings. */
+    setup: Check[];
+}
+/**
+ * The setup checks doctor makes: every failure, and one line counting the warnings. The skills
+ * are left out, since CI never has them.
+ */
+export declare function setupChecks(root: string, nodeVersion?: string, today?: Date): Check[];
+/**
+ * Whether a work item may be at ship or done. `items` are the project's other work items, for its
+ * dependencies (RFC 0005): an item can't ship before the items it depends on have.
+ */
+export declare function gateWorkItem(item: WorkItem, config: PeerAiConfig, stage: Stage, assessment: Assessment, items?: WorkItem[]): Check[];
+export declare function evaluate(root: string, config: PeerAiConfig): Verdict;
+export declare function formatVerdict(verdict: Verdict): string[];
+export interface CheckOptions {
+    cwd: string;
+    json: boolean;
+}
+/** Exit code 0 when it passes, even with warnings; 1 when it fails; 2 without a valid config. */
+export declare function runCheck(options: CheckOptions, out: Output): number;